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.8.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.

Portable Repository Identity

Version 0.8 mirrors the npm repository identity and authority state machine. Repository Soul is descriptive only. Promotion, rotation, revocation, migration, and recovery bind the exact identity state, Soul snapshot, sequence, nonce, expiry, previous receipt, target, and signer policy.

holorepo-py identity sample > repository-identity.json
holorepo-py identity evaluate repository-identity.json

The sample is intentionally unsigned, and CLI evaluation fails closed because a static JSON command cannot inject a trusted signature verifier. Agent runtimes use the SDK with their caller-owned HoloKey-compatible adapter:

from holoscript_holorepo import build_repository_identity_ledger

ledger = build_repository_identity_ledger(
    identity_input,
    verify_signature=caller_owned_holokey.verify_detached,
    consume_nonce=caller_owned_replay_store.consume_atomic,
)

The verifier returns exact ok, keyRef, payloadHash, signerAddress, and receiptDigest bindings for eip191_secp256k1 over stable canonical { body, nonce, timestamp } JSON. A second injected adapter atomically consumes the 32-lowercase-hex nonce and binds it to the payload in durable caller-owned storage. HoloMesh participant and session identities remain optional receipt references and never satisfy an authority threshold.

Wire timestamps use canonical UTC milliseconds (...00.000Z), and threshold policies count unique verified signer addresses rather than key-reference aliases. Persist ledger["currentIdentity"] and its transition receipts; later operations pass that identity as currentIdentity with only the next signed envelope plus a caller-owned verify_identity_checkpoint adapter that proves the exact state exists in trusted durable custody. Exact durable readback is labeled replayed-same-payload and counted separately from newly applied work.

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, portable repository identity transitions, and config/env-driven DB/KS reads for agent frameworks, while artifact consumption, write admission, canon graduation, and key custody 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.