holoscript-holorepo

Python companion for HoloRepo: a plug-and-play sovereign GitHub + database + HoloScript knowledge store for high-volume agent frameworks.

The Python client covers the DB/KS guest surface. It reads any Postgres reachable by psql, or an explicitly configured owned node over SSH + Docker. No host, IP, or container is assumed by default.

Install

pip install holoscript-holorepo

Config

Use holorepo.config.json or env:

export HOLOREPO_DATABASE_URL="postgres://user@host:5432/app"
export PGPASSWORD="..."

For an owned node over SSH, use the jetsonExample profile as an example and set HOLOREPO_SSH, HOLOREPO_SSH_KEY, and HOLOREPO_POSTGRES_CONTAINER.

Use

holorepo-py db read knowledge "select count(*) from memory_entries"
holorepo-py ks query "storage lanes" 8

from holoscript_holorepo import query_ks, read_db

hits = query_ks("sovereign backbone", limit=5)["rows"]

Reads refuse mutations. Writes are staged by the npm client as holorepo.storage-proof.v1 and admitted by the configured operator route.

Native delivery planning, manifest generation, installer templates, and admission proofs live in the npm CLI:

holorepo delivery plan --class native-service --rail oci --rail compose
holorepo delivery manifest --class native-app --rail web-bundle --rail holoqr
holorepo delivery readback --rail pypi --name holoscript-holorepo --version 0.7.0
holorepo delivery admit --manifest delivery.manifest.json --receipt pypi-readback.json
holorepo delivery promote --admission delivery.admission.json --custody-receipt holokey:lease
holorepo delivery import --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --write
holorepo delivery import --storage-adapter owned-metal --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=ssh://node/path/to/app.tgz --destination-digest offline-tarball=sha256:...
holorepo delivery import --storage-adapter owned-metal --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=scp://node/path/to/app.tgz --copy-profile scp-owned-metal --write

Python frameworks can consume the emitted manifest JSON while the package keeps DB/KS reads dependency-free.

Artifact Lifecycle

Version 0.7 adds the dependency-free artifact intake and canon-graduation lifecycle shared with the public HoloRepo contract. It supports exact artifacts from npm, pypi, github, oci, service, and filesystem rails.

holorepo-py lifecycle sample > lifecycle-input.json
holorepo-py lifecycle evaluate lifecycle-input.json

from holoscript_holorepo import (
    build_artifact_lifecycle,
    build_sample_artifact_lifecycle_input,
)

result = build_artifact_lifecycle(build_sample_artifact_lifecycle_input())
assert result["ledger"]["records"][0]["state"] == "source-proven"
assert result["graduationPlan"]["mode"] == "propose-only"

The Python API and CLI use the same batch JSON shape as the npm package: artifacts, consumptionReceipts, lineageMappings, graduationReceipts, and coordinationReceipts. Each artifact kind is one of npm, pypi, github, oci, service, or filesystem; there is no separate rail field.

Lifecycle inputs require an exact version, sha256/sha512 hex or SRI artifact integrity, an exact receipt digest, and a full 40- or 64-character source commit. Consumption evidence must use holorepo.consumption-receipt.v1, include all 12 public gates, and exact-bind subject kind, name, version, artifact digest, artifact ID, rollback, founder escalation, commands, and receipt evidence. Lineage mappings exact-bind artifact ID/version/digest, source repository, version, commit, directory, and evidence receipt digest. Invalid identity, integrity, or supplied admission evidence is quarantined.

HoloMesh coordination receipt references are optional context only. They cannot grant authority, change state, or alter candidateAdmissionHash. The package never installs artifacts or executes graduation. A caller-observed holorepo.canon-graduation-receipt.v1 can record canon-graduated only when it is exact-bound and includes executedByCaller=true, authorityRef, decisionRef, and receiptDigest.

Public lifecycle receipts refuse local absolute paths, URL credentials, URL queries/fragments, placeholders, and secret-looking key material.

Repository Soul Participation

The companion also builds dependency-free participation envelopes. HoloMesh is modeled as an optional sister product: routine plans target an injected holomesh_suggest adapter, while founder, spend, custody, public commitment, governance, and compliance boundaries require a separate protected-review adapter. Neither route grants authority or mutates source.

from holoscript_holorepo import (
    build_holomesh_participation_plan,
    build_repository_soul_suggestion,
    normalize_participation_result,
)

suggestion = build_repository_soul_suggestion(
    repository_soul,
    {
        "source": {"path": "docs/guide.md", "doorId": "contributing"},
        "submitter": {"kind": "agent", "id": "agent-example"},
        "intent": {
            "kind": "documentation",
            "title": "Clarify setup",
            "description": "Add a tested example.",
        },
    },
)
plan = build_holomesh_participation_plan(suggestion, team_id="team-example")
# The caller may pass plan["operation"]["payload"] to its own adapter.
receipt = normalize_participation_result(
    suggestion,
    plan,
    {"ok": True, "result": {"success": True, "suggestion": {"id": "suggestion-1"}}},
)

The emitted schemas are holorepo.repository-soul-suggestion.v1, holorepo.holomesh-participation-plan.v1, and holorepo.repository-soul-participation-receipt.v1.

Release Boundary

holoscript-holorepo is distributed under the MIT license. The compatibility label is still v0-preview: the Python companion supports deterministic artifact lifecycle evaluation plus config/env-driven DB/KS reads for agent frameworks, while artifact consumption, write admission, and canon graduation remain caller or HoloGate/HoloKey operator responsibilities. The npm client also writes delivery promotion import receipts, filesystem storage-import byte receipts, object/owned-metal destination digest proof receipts, and opt-in provider-copy profile receipts (aws-s3, rclone-copyto, mc-cp, or scp-owned-metal) that bind admitted mirrors back to HoloRepo custody.