Metadata-Version: 2.4
Name: holoscript-holorepo
Version: 1.0.0
Summary: Stable HoloRepo contracts, identity, lifecycle, and bounded-autonomy companion for agent frameworks.
Author: HoloScript ecosystem
License-Expression: MIT
Project-URL: Homepage, https://github.com/brianonbased-dev/ai-ecosystem/tree/main/packages/holorepo-py
Project-URL: Source, https://github.com/brianonbased-dev/ai-ecosystem
Project-URL: Doctrine, https://github.com/brianonbased-dev/ai-ecosystem/blob/main/docs/handbooks/holorepo-operating-model.md
Keywords: holoscript,holorepo,bounded-autonomy,task-farm,artifact-lifecycle,repository-identity,authority-envelope,holokey,holomesh,supply-chain,sovereign,postgres,knowledge-store,agent-framework
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Database
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
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`:

```bash
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
```

```python
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:

```bash
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

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

```python
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:

```bash
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.

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

```python
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.

```bash
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:

```python
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.

```bash
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
```

```python
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.

```python
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.
