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

Stable 1.x Contract

The Python package shares the exact contract hash, schema ids, platform fixtures, migration behavior, authority semantics, and recovery reports with @holoscript/holorepo:

holorepo-py contract show
holorepo-py contract fixture offline > conformance.json
holorepo-py contract check conformance.json
holorepo-py contract recovery-sample --scenario offline-startup

from holoscript_holorepo import (
    build_holorepo_public_contract,
    build_holorepo_conformance_fixture,
    evaluate_holorepo_conformance,
)

contract = build_holorepo_public_contract()
report = evaluate_holorepo_conformance(
    build_holorepo_conformance_fixture("offline")
)
assert contract["releaseLane"] == "v1-public"
assert report["ok"]

These operations are dependency-free and pure. Callers retain storage, process, adapter, receipt-verification, secret, write, and spend authority. HoloMesh is an optional sister product with separate ownership and no repository authority.

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

Bounded Autonomy

Version 0.9 adds the dependency-free bounded-autonomy planner shared with the npm contract. It validates receipt-backed repository state, detects drift, selects a deterministic bounded task set, emits non-authorizing lease requests, and projects the same state as JSON, SSE, or HoloScript.

holorepo-py autonomy sample > bounded-autonomy.json
holorepo-py autonomy plan bounded-autonomy.json
holorepo-py autonomy project bounded-autonomy.json --format holoscript
holorepo-py autonomy project bounded-autonomy.json --bundle --out-dir .holorepo/projections/autonomy

from holoscript_holorepo import (
    AUTONOMY_TRANSCRIPT_EVENT_SCHEMA,
    build_bounded_autonomy_projection_bundle,
    build_bounded_autonomy_state,
    build_sample_bounded_autonomy_input,
    create_holomesh_autonomy_adapter,
    run_bounded_task_farm,
)

input_value = build_sample_bounded_autonomy_input()
state = build_bounded_autonomy_state(
    input_value,
    generated_at="2026-01-01T12:00:00.000Z",
)

holomesh = create_holomesh_autonomy_adapter(channel="team:public")
transcript = isolated_executor.run(state, coordination=holomesh)
receipt = run_bounded_task_farm(input_value, transcript=transcript)
bundle = build_bounded_autonomy_projection_bundle(receipt["finalState"])

assert all(
    event["schema"] == AUTONOMY_TRANSCRIPT_EVENT_SCHEMA
    for event in transcript
)
assert bundle["custody"]["writesFiles"] is False

Tasks describe only an adapter name and exact inputHash; exact schemas and a recursive forbidden-key scan reject nested command, payload, environment, secret, credential, key, password, and token material. Receipts must be current or revoked, use canonical timestamps, and cannot be future issued or expire at/before issue time. Protected tasks remain blocked because the package cannot accept self-asserted authority.

The package does not invoke task callbacks. A caller-owned isolated executor obtains state-checkpoint, task-authorization, lease, heartbeat, attempt, rollback, recovery, and release receipts, then supplies the strict ordered transcript. Runtime timestamps use the wall clock; generated_at remains a planning-only input and cannot backdate evaluation. Short leases require a bound heartbeat and are rechecked around attempts, rollback, and recovery. policy.minimumLeaseWindowSeconds is bounded to 1-300 seconds and must be shorter than the lease TTL.

receipt["ok"] means the transcript is complete, ordered, request-bound, and policy-consistent. It is not signature verification or admission authority; external receipt authenticity remains caller-owned. Duplicate receipt references, missing kind-specific fields, misordered operator stops, secret- bearing URL/error material, and unconsumed tail events fail closed. Public APIs reject callback, executor, signal, HoloMesh client, force, and cwd options instead of silently ignoring them.

Projection building is pure. The bundle contains relative output hints and the JSON, SSE, and HoloScript strings, but creates or overwrites no file. HoloMesh is optional transcript-transport metadata: it is never a hard dependency and never grants repository authority. Laptop, Jetson, and cloud replicas are optional unless the caller marks one required. The package owns no commands, private keys, secrets, process termination, or persistence.

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 v1-public: documented SDK/CLI contracts, listed schema ids, platform conformance, explicit migration, receipt-only recovery, artifact lifecycle, portable repository identity transitions, bounded-autonomy planning, and config/env-driven DB/KS reads are stable within 1.x. Artifact consumption, write admission, receipt verification, 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.