Metadata-Version: 2.4
Name: holoscript-holorepo
Version: 0.8.0
Summary: Dependency-free HoloRepo lifecycle, sovereign DB, and HoloScript KS 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,artifact-lifecycle,repository-identity,authority-envelope,holokey,supply-chain,sovereign,postgres,knowledge-store,agent-framework
Classifier: Development Status :: 3 - Alpha
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
```

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

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

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