@holoscript/holorepo

HoloRepo is a plug-and-play sovereign GitHub + database + HoloScript knowledge store for high-volume agent frameworks, with a proof-backed visual participation layer for humans.

Point it at storage you control: an NVMe, external drive, mounted network share, synced cloud folder, object-backed filesystem, self-hosted Postgres, or managed Postgres. Then point it at the repos and agents in that ecosystem. HoloRepo gives them a canon git lane, DB read/stage receipts, KS queries, custody metadata, and promotion boundaries without assuming Joseph's hardware. Completion management turns explicit task residue into deduplicated successor tasks or protected-review packets before the source task closes. Each repo also gets a front-door graph SSOT: the operator laptop can build graph snapshots, but the graph becomes canon only after HoloRepo loads it into the configured durable repoGraph backend. A package-native Repo Soul compiler turns that same repository evidence into language DNA, human and agent participation doors, SOUL.md, agent JSON, and a self-contained visual portrait. A typed participation contract can turn a selected door into a non-authoritative suggestion envelope and an adapter plan without making any live coordination product a package dependency.

For the HoloScript ecosystem, HoloRepo is the canonical build surface for the HoloGate umbrella and the SSOT agents consult before creating lane-specific glue. Hardware, fleet, graph, embedding, and model-serving lanes publish receipts and state into HoloRepo; they do not become independent canon without HoloRepo custody evidence.

Jetson is only an example profile.

Install

npm i -g @holoscript/holorepo

Stable 1.x Contract

Version 1.0 freezes the documented SDK exports, CLI exit meanings, schema ids, migration rules, support boundary, and authority semantics for the 1.x line. Inspect the machine-readable contract and run a platform fixture without any network, file write, private repository, founder path, Jetson, or Railway dependency:

holorepo contract show --json
holorepo contract fixture --profile offline --json > conformance.json
holorepo contract check --fixture conformance.json --json
holorepo contract recovery-sample --scenario interrupted-write --json

The same surface is exported from @holoscript/holorepo/contract. Migration is explicit and returns a new document plus a receipt; it never overwrites caller state. Recovery evaluates an ordered caller-supplied receipt transcript; the package does not inject failures, restore state, verify receipt authenticity, execute commands, grant repository authority, or promote canon.

HoloMesh is an optional sister product with separate ownership. HoloRepo can validate its portable lease-event metadata, but HoloMesh is not a dependency and neither product grants source or repository authority to the other.

First Run

holorepo init --storage-root /mnt/my-nvme/holorepo
holorepo doctor
holorepo graph plan
holorepo graph build --max-files all --write
holorepo soul build --write
holorepo git plan

This writes holorepo.config.json. Agents read that file first.

Living Repository Portrait

One evidence model serves both audiences:

# Read the agent model without writing files.
holorepo soul build --json

# Write SOUL.md, stable agent JSON, offline HTML, and a correlation receipt.
holorepo soul build --write

# Fail when a projection or its immutable correlation receipt has drifted or is missing.
holorepo soul check --json

The stable projections are derived from the committed Git tree, not the index, working tree, or a README alone. Language statistics use committed source-blob bytes and recognize .holo, .hs, and .hsplus as HoloScript. The write receipt correlates the stable Soul hash to the current graph, plan, and repository head. Receipts are append-only; soul check verifies their hashes and output bindings. A partial or unborn repository is visible in read mode but refuses normal writes unless the operator explicitly passes --allow-partial.

SOUL.md is deliberately personable, but it is not authority or an identity principal. It cannot override source, AGENTS.md, policy, licenses, security rules, or receipts. Existing unmanaged SOUL.md files are protected unless the operator explicitly passes --force. The first HTML tracer is offline and read-only: it detects participation entry points but does not submit suggestions. Custom projection paths must remain self-excluded as SOUL.* files or under .holorepo/portraits/; receipts remain under .holorepo/receipts/soul/.

Typed Participation

HoloRepo and HoloMesh are optional sister products. Neither is subordinate to the other, and neither supplies source authority to the other.

| Product | Owns | |---|---| | HoloRepo | Durable repository evidence, admitted repo graph, Repo Soul, admission, and repository receipts | | HoloMesh | Live identity and presence, suggestions, tasks, protected reviews, leases, messages, and completion routing |

The package works without HoloMesh. participation plan validates a compiled Soul, binds a repository-relative source, submitter identity, and intent into a holorepo.repository-soul-suggestion.v1 envelope, then emits a holorepo.holomesh-participation-plan.v1. Planning does not call HoloMesh, mutate source, create a task, or grant authority:

holorepo participation plan \
  --soul .holorepo/portraits/repository-soul.json \
  --source CONTRIBUTING.md \
  --submitter-kind human \
  --submitter-id contributor-42 \
  --intent documentation \
  --title "Clarify the local setup" \
  --description "Add the missing database bootstrap step." \
  --team-id team_public \
  --json

An operator may inject a HoloMesh sister adapter to execute that plan. Routine suggestions use HoloMesh's native title, description, category, and evidence fields; protected classifications require a separate submitProtectedReview adapter. Execution returns a holorepo.repository-soul-participation-receipt.v1 bound to the envelope and Soul hashes. An adapter is not live merely because it is configured or named: the claim requires a successful or replay-deduplicated typed receipt. The offline Soul HTML remains read-only and never invokes an adapter. The current signed canary proves routine HoloMesh suggestion submission and replay deduplication only. Protected-review execution is an injectable contract, not a live capability proven by that canary.

Seed Bootstrap

Public consumers should start from a canon prompt seed, then grow their own custody surface. The seed can come from @holoscript/agent-runtime:

import { buildSovereignSeedPrompt } from '@holoscript/agent-runtime';

const seed = buildSovereignSeedPrompt({
  productName: 'my agent framework',
  masterCanonLabel: 'operator canon capsule',
});

The seed is not founder memory. It asks whether the work serves humans and agents, whether it is sovereign and novel, and whether it can be consumed from public rails. The expected result is operator-owned state:

| Output | HoloRepo proof path | |---|---| | HoloRepo config | holorepo init, holorepo doctor --json | | DB | holorepo db read --receipt or holorepo proof sample --lane database-template | | KS | holorepo ks query, holorepo ks stats, or holorepo proof sample --lane knowledge-store-template | | GOLD-compatible authority | caller-owned bundle or adapter boundary until the public GOLD package exists | | Package/cloud readback | holorepo delivery readback plus public-consumer lane receipts |

@holoscript/gold is unreleased. Do not require it for cold consumers yet; name the migration boundary and let operators bring a local GOLD-compatible authority bundle.

Consumer Core

The public package exposes the same setup and decision surfaces to humans, founders, operators, and agents. Inputs belong to the caller; no command reads the HoloScript founder repo, private telemetry, Jetson state, or HoloMesh state.

holorepo onboard --config holorepo.config.json --json
holorepo verify --proof db-proof.json --json
holorepo capabilities --index my-capabilities.json --query storage --json
holorepo strategy --manifest my-strategy.json --focus agents --json
holorepo interface --manifest my-interface.json --intent "publish this package" --json
holorepo consume check --gate-config my-gates.json --receipt my-release.json --json
holorepo lifecycle evaluate --input my-artifact-lifecycle.json --json
holorepo identity sample --json

The matching SDK is exported from @holoscript/holorepo/consumer and the root module. Bundled manifests provide a cold-start default, while --index, --manifest, and --gate-config replace those defaults with caller policy. onboard reports only environment-key presence and redacted config. verify performs secret-safe structural proof validation; live HoloKey custody checks remain an explicit adapter boundary and never reveal a secret.

Artifact Lifecycle

holorepo lifecycle evaluate replaces workspace-specific package candidate logic with one public contract for npm, PyPI, GitHub, OCI, service, and portable filesystem artifacts. It binds each candidate to an exact version and integrity receipt, then evaluates these states:

discovered -> consumption-admitted -> source-proven -> canon-graduated
       \-> quarantined (invalid or mismatched supplied evidence)

Source proof requires the artifact version and digest, a credential-free source repository, the same exact source version, a full 40- or 64-character commit, and a lineage receipt digest. Graduation output is always propose-only. HoloRepo may record a caller-executed graduation receipt, but it never executes the transition or grants itself authority. In 0.7 that receipt is explicitly caller-attested, not cryptographically verified; portable signature envelopes belong to the separate authority layer shipped in 0.8. Optional HoloMesh receipts are coordination references only and cannot change admission or authority.

The SDK is available from the root module and @holoscript/holorepo/lifecycle:

import { randomBytes } from 'node:crypto';
import {
  buildArtifactLifecycle,
  buildSampleArtifactLifecycleInput,
} from '@holoscript/holorepo/lifecycle';

const input = buildSampleArtifactLifecycleInput();
const lifecycle = buildArtifactLifecycle(input);

Portable Repository Identity

Repository Soul remains a descriptive portrait, never an authority token. Version 0.8 derives a provisional repository identity from the repository, caller-owned custody references, and an exact Soul snapshot. The stable identityId derives from the repository binding; the signable identityHash also binds the Soul snapshot so an approval cannot replay after the portrait or source proof changes.

The authority state machine supports promote, rotate, revoke, migrate, and recover. Every transition binds the current identity hash, sequence, one-time nonce, previous transition receipt, expiry, target, authority and decision references, and required signer roles. Promotion, rotation, migration, and recovery require successor-key acceptance. Recovery additionally enforces the caller's configured recovery threshold.

import {
  buildProvisionalRepositoryIdentity,
  buildRepositoryAuthorityEnvelope,
  buildRepositoryIdentityLedger,
} from '@holoscript/holorepo/identity';

const provisionalIdentity = buildProvisionalRepositoryIdentity(identityInput);
const unsigned = buildRepositoryAuthorityEnvelope({
  identity: provisionalIdentity,
  action: 'promote',
  sequence: 1,
  nonce: randomBytes(16).toString('hex'),
  issuedAt: new Date().toISOString(),
  expiresAt,
  authorityRef: 'holokey:founder-authority',
  decisionRef: 'decision:promote-repository',
  target: { controllerKeyRef: 'holokey:repository-controller' },
});

const signed = await callerOwnedHoloKey.signRequiredApprovals(unsigned);
const ledger = buildRepositoryIdentityLedger(
  { provisionalIdentity, authorityEnvelopes: [signed] },
  {
    verifySignature: callerOwnedHoloKey.verifyDetached,
    consumeNonce: callerOwnedReplayStore.consumeAtomic,
  },
);

The injected verifier must synchronously return { ok, keyRef, payloadHash, signerAddress, receiptDigest } with exact bindings. The signature scheme is eip191_secp256k1; the signed message is stable canonical JSON shaped as { body, nonce, timestamp }, matching the HoloKey/HoloMesh EIP-191 contract. Wire timestamps are canonical UTC strings with milliseconds, such as 2026-07-13T00:00:00.000Z. Recovery thresholds count unique verified signer addresses, not key-reference aliases. Nonces are 128 random bits encoded as 32 lowercase hex characters.

The injected nonce consumer must atomically persist repository scope, nonce hash, payload hash, expiry, and a receipt digest. It may return replayed-same-payload for deterministic readback, but must deny the same nonce with a different payload. Readback is labeled in the transition receipt and is counted under summary.replayed, never summary.applied. Missing, asynchronous, expired, conflicting-replay, revoked, stale-controller, or threshold-incomplete evidence fails closed. The package never holds private keys or claims a signature scheme verified itself. HoloMesh participant and session identities may appear in transition receipts; they are excluded from the signed authority payload and grant no repository authority.

Persist ledger.currentIdentity and the transition receipts after each accepted operation. Later operations start from { currentIdentity, authorityEnvelopes: [nextSignedEnvelope] }; they do not replay expired historical envelopes from the original provisional identity. Continuation additionally requires verifyIdentityCheckpoint, a synchronous caller-owned adapter that proves the exact identity ID, identity hash, state, generation, and transition receipt hash exist in trusted durable custody. Self-recomputed hashes never authenticate a continuation.

holorepo identity sample --json emits a portable unsigned fixture. CLI identity evaluate intentionally blocks because a static JSON invocation cannot inject a trusted verifier; production transition evaluation uses the SDK with the caller-owned HoloKey or equivalent adapter.

Bounded Autonomy

Version 0.9 adds a portable task-farm contract without turning HoloRepo into a command runner or an authority source. The planner compares the expected repository identity, Soul, committed-source digest, graph digest, required receipts, and required replicas with current observations. Drift, expired or revoked receipts, retry exhaustion, protected work, and unavailable required replicas fail closed.

Task actions contain only an adapter kind, action name, and input hash. The manifest uses strict task and action schemas; nested commands, payloads, environment maps, credentials, tokens, private keys, and secrets are rejected. The SDK runner does not invoke task callbacks. A caller-owned isolated executor performs any work and supplies a strict ordered receipt transcript. Independent state-checkpoint and task-authorization receipts must precede lease and task evidence. Every lease, attempt, heartbeat, rollback, recovery, and release is bound to the exact request fields before it counts.

import {
  AUTONOMY_TRANSCRIPT_EVENT_SCHEMA,
  buildBoundedAutonomyProjectionBundle,
  buildBoundedAutonomyState,
  createHoloMeshAutonomyAdapter,
  runBoundedTaskFarm,
} from '@holoscript/holorepo/autonomy';

const state = buildBoundedAutonomyState(input, {
  generatedAt: new Date().toISOString(),
});

const holoMesh = createHoloMeshAutonomyAdapter({ channel: 'team:public' });
const transcript = await isolatedExecutor.run(state, { coordination: holoMesh });
const run = await runBoundedTaskFarm(input, { transcript });
const bundle = buildBoundedAutonomyProjectionBundle(run.finalState);

console.assert(transcript.every(
  (event) => event.schema === AUTONOMY_TRANSCRIPT_EVENT_SCHEMA,
));
console.assert(bundle.custody.writesFiles === false);

Planning accepts an explicit generatedAt for reproducible evaluation. Transcript evaluation deliberately does not: it evaluates lease evidence and expiry against its wall clock, requires heartbeat evidence when the next bounded stage lacks a safe lease window, and rechecks expiry after attempts. The public API rejects injected adapters, HoloMesh clients, stop callbacks, and abort signals. Consumers own process or worker isolation, hard termination, live coordination, secret custody, and durable writes.

run.ok means the supplied transcript is complete, ordered, request-bound, and consistent with the package policy. It is not signature verification or admission authority. Receipt authenticity remains caller-owned and the run receipt states that boundary explicitly. Duplicate receipt references, misordered operator stops, missing kind-specific fields, and unconsumed tail events fail closed.

Projection building is pure. buildBoundedAutonomyProjectionBundle returns relative output hints plus JSON, SSE, and HoloScript strings; it never creates, overwrites, or resolves a file. A caller-owned writer decides where and how to persist the bundle.

Projection writes are immutable and descriptor-based. Existing identical files are an idempotent no-op; changed files, force, symlinked paths, and descriptors whose real path escapes the consumer cwd are rejected.

JSON, SSE, and HoloScript are projections of the same hashed state. The founder composition exposes repository graph state, agents, decisions, the admission funnel, tasks, blockers, receipt freshness, replicas, and next actions. It is a HoloScript-native operational view, not a separate dashboard state store.

HoloMesh remains an optional sister product for live presence, leases, tasks, messages, and collaboration. Its adapter returns receipt references only and grants no repository authority. HoloRepo retains durable graph, Soul, admission, run, and receipt custody. Laptop, Jetson, and cloud replicas are optional unless the caller explicitly marks one required.

Consumption Gate

holorepo consume check requires operator outcome, package entrypoint, sovereign storage, concrete HoloGate admission, HoloKey or equivalent secret-safe custody, DB/KS proof or N/A, agent-operable JSON/CLI, validation evidence, release state, rollback, risk, and founder-escalation classification. The public receipt schema is holorepo.consumption-receipt.v1. Existing holorepo.founder-consumption-receipt.v1 receipts remain accepted with a migration warning.

Routine process decisions stay agent-owned. Protected spend, custody, physical-world, public-founder, or governance mutations require explicit founder escalation.

Config Shape

{
  "schema": "holorepo.config.v1",
  "storage": { "kind": "filesystem", "root": "/mnt/my-nvme/holorepo" },
  "git": { "backend": "local-bare", "root": "/mnt/my-nvme/holorepo/git" },
  "database": { "transport": "pg", "connectionEnv": "HOLOREPO_DATABASE_URL" },
  "knowledgeStore": { "database": "knowledge", "table": "memory_entries" },
  "repoGraph": {
    "primaryBackend": "database-template",
    "database": "knowledge",
    "tablePrefix": "holorepo_repo_graph",
    "buildRoot": ".holorepo/build/repo-graphs",
    "root": "/mnt/my-nvme/holorepo/repo-graphs",
    "maxFiles": "all"
  },
  "agents": { "maxConcurrentWriters": 100 },
  "agentDependencies": {
    "absorbService": {
      "mode": "optional-adapter",
      "role": "graphrag-enrichment",
      "package": "@holoscript/absorb-service",
      "localMcpUrl": "http://127.0.0.1:7411/mcp",
      "remoteUrlEnv": "ABSORB_SERVICE_URL",
      "apiKeyEnv": "ABSORB_API_KEY"
    }
  }
}

Supported DB transports in this preview:

| Transport | Use | |---|---| | pg | Default package-native Postgres driver for local, self-hosted, Supabase, Neon, RDS, and other Postgres URLs | | direct-psql | Optional external psql client transport when an operator wants shell parity | | docker-psql | Postgres container on the same machine | | ssh-docker-psql | Owned node over SSH, with Postgres inside Docker |

Credentials stay in environment variables or the caller's secret provider. Receipts carry digests and redacted summaries only.

Existing knowledge stores do not need to be reshaped before adoption. Map the columns HoloRepo should read, and set optional columns to null when the operator's table does not have them:

{
  "knowledgeStore": {
    "database": "railway",
    "table": "knowledge_entries",
    "domainColumn": "workspace_id",
    "confidenceColumn": "validation_agreements",
    "staleColumn": "is_stale",
    "embeddingColumn": "embedding",
    "reuseColumn": null
  }
}

Commands

holorepo doctor --json
holorepo git plan --json
holorepo git init-canon --apply
holorepo git admit --remote origin --ref main --capsule .scratch/holorepo/change-capsule-latest.json --custody-receipt holokey:lease --write

holorepo graph plan --json
holorepo graph build --max-files all --write --json
holorepo graph build --max-files 1000 --write --json
holorepo graph load --snapshot .holorepo/build/repo-graphs/<snapshot>.json --write --json

holorepo ci plan --repo owner/name --sha 1111111111111111111111111111111111111111 --gate holo-ci/check="pnpm test" --json
holorepo ci receipt --repo owner/name --sha 1111111111111111111111111111111111111111 --status holo-ci/check=success --write
holorepo ci receipt --from-holo-ci runtime/shared/receipts/holo-ci.ndjson --workload ci-11111111 --write
holorepo ci admit --receipt cicd-receipt.json --capsule change-capsule.json --git-admission git-admission.json --custody-receipt holokey:lease --write

holorepo db list
holorepo db read --db knowledge --query "select count(*) from memory_entries" --receipt
holorepo db stage-write --db knowledge --migration ./migration.sql

holorepo ks query "storage lanes" --limit 8
holorepo ks stats

holorepo absorb plan --json
holorepo absorb sync --adapter-result absorb-result.json --write --json
holorepo absorb sync --invoke --operation status --endpoint local --write --json

holorepo agents plan --agent-count 100 --changed --json
holorepo agents plan --agent-count 100 --path package.json --path docs/guide.md --json

holorepo completion plan --manifest residue.json --task-id task_123 --commit abc1234 --json
holorepo completion plan --manifest residue.json --task-id task_123 --commit abc1234 --write --json
holorepo completion no-residue --task-id task_123 --commit abc1234 --reason "The acceptance boundary is exhausted." --write --json

holorepo lifecycle sample --json
holorepo lifecycle evaluate --input artifact-lifecycle.json --json

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

holorepo soul build --json
holorepo soul build --write
holorepo soul check --json

holorepo participation plan --soul .holorepo/portraits/repository-soul.json --source CONTRIBUTING.md --submitter-kind human --submitter-id contributor-42 --intent documentation --title "Clarify the local setup" --description "Add the missing database bootstrap step." --team-id team_public --json

holorepo proof sample --lane database-template --write --out db-proof.json
holorepo proof sample --lane knowledge-store-template --write --out ks-proof.json
holorepo proof source-sample --write --out storage-proof-source.json

holorepo delivery plan --class native-service --rail oci --rail compose --json
holorepo delivery manifest --class native-service --name api --version 0.1.0 --write
holorepo delivery installer --rail compose --name api --image registry/api:0.1.0 --write
holorepo delivery readback --rail npm --name @holoscript/holorepo --version 0.5.1 --write
holorepo delivery admit --manifest delivery.manifest.json --receipt npm-readback.json --write
holorepo delivery promote --admission delivery.admission.json --custody-receipt holokey:lease --write
holorepo delivery import --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --write
holorepo delivery import --storage-adapter object-storage --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=s3://bucket/app.tgz --destination-digest offline-tarball=sha256:...
holorepo delivery import --storage-adapter object-storage --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=s3://bucket/app.tgz --copy-profile aws-s3 --json
holorepo delivery import --storage-adapter object-storage --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=s3://bucket/app.tgz --copy-profile aws-s3 --write
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

db read refuses mutations. Writes are staged as holorepo.storage-proof.v1 and require an authorized HoloGate/HoloKey admission route before they are applied to the configured database.

git admit is the local verifier for GitHub, Gitea, GitLab, Forgejo, or any Git-compatible federation rail. It observes the remote ref with git ls-remote, binds it to the expected local commit, requires a promotion-eligible HoloRepo change capsule, and writes holorepo.git-federation-admission.v1. A remote URL alone is still not custody proof.

ci plan, ci receipt, and ci admit fold HoloCI/CD into HoloRepo without turning HoloRepo into a runner. Existing HoloCI dispatch/reconcile/report surfaces execute gates and seal cael-ci-v1 ledger entries. holorepo ci receipt --from-holo-ci <ledger-or-json> imports that live receipt into holorepo.cicd-receipt.v1; --status context=state remains the manual/readback path. Admission happens only when the receipt matches the change capsule, optional Git federation admission, and HoloKey/operator custody receipt. GitHub commit statuses remain readback signals until captured in this receipt.

The live HoloCI reporter keeps receipt-only behavior by default. To let it write the admission receipt immediately after the HoloRepo CI receipt, set HOLOREPO_CICD_ADMIT=1, HOLOREPO_CICD_CAPSULE=<change-capsule.json>, and HOLOREPO_CICD_CUSTODY_RECEIPT=<holokey-or-operator-receipt>. Optional knobs: HOLOREPO_CICD_GIT_ADMISSION=<git-admission.json>, HOLOREPO_CICD_REQUIRE_GIT_ADMISSION=1, HOLOREPO_CICD_OPERATOR=<operator-id>, and HOLOREPO_CICD_ADMISSION_OUT=<admission.json>. These values are receipt references and paths only; do not put raw tokens, private keys, wallet material, or database credentials in them.

proof sample and proof source-sample emit redacted DB/KS proof shapes for external agent frameworks. Replace the placeholders with live holo_secrets_grant lease coordinates and redacted DB/knowledge receipts before using them in a storage verification closeout.

graph plan, graph build, and graph load make the repo graph the first object agents consume. Build runs on the laptop or operator machine and produces a holorepo.repo-graph-snapshot.v1. Builds scan all tracked files by default (repoGraph.maxFiles: "all"); bounded diagnostic runs must pass --max-files <N> and remain visibly capped in the snapshot receipt. Load writes holorepo.repo-graph-load-receipt.v1 and admits that snapshot into the configured HoloRepo repoGraph backend. With the default database-template backend, load creates/upserts holorepo_repo_graph_snapshots, holorepo_repo_graph_nodes, and holorepo_repo_graph_edges in the configured repoGraph database, records row counts plus schema/mutation digests, and never prints raw DB credentials. A laptop build/cache file is not canon by itself.

Absorb-Service is the optional ADEP for graph intelligence. HoloRepo owns source custody, DB/KS boundaries, repoGraph rows, and admission receipts; Absorb-Service adds chunks, embeddings, GraphRAG answers, provenance, diffs, and HoloScript transform suggestions. Local repos should route to the sovereign local MCP first (localMcpUrl); remote Absorb is an opt-in service lane through env-provided URL/key values.

absorb plan reports the configured ADEP route. absorb sync writes holorepo.absorb-adep-sync-receipt.v1, either by importing an existing --adapter-result JSON or by opt-in invocation with --invoke. Receipts record summary counts and digests while redacting service URLs and never treating Absorb output as the custody source.

Agent Coordination

agents plan is the package-native 100-agent coordination surface. It does not spawn agents or replace a board. It maps changed or explicit paths to conflict domains, exclusive or partitioned leases, heartbeat/TTL expectations, promotion lanes, and validation commands so HoloMesh, another framework, or an operator can keep concurrent writers out of shared authority files.

Completion Management

completion plan consumes holomesh.task-completion-residue.v1 and emits holomesh.completion-management-plan.v1. Routine residue becomes a source-linked board-task payload with a stable completion:<task>:<item> deduplication key. Custody, cap changes, physical actions, public commitments, governance, and compliance boundaries become protected review packets instead. Caller route hints cannot downgrade a protected classification.

The package plans and receipts the effects; it does not assume a particular board or message service. HoloMesh applies them through Bullhorn in the HoloScript ecosystem. Other frameworks can map followUpTasks and escalations to their own adapters, or inject a stricter classifyItem policy through the SDK. --write stores the plan under .holorepo/receipts/completion/ unless --out is supplied. An explicit no-residue receipt is required when the stated acceptance boundary is genuinely exhausted.

API

import {
  defaultHoloRepoConfig,
  buildDoctorReport,
  buildCiCdReceipt,
  buildCiCdReceiptFromHoloCi,
  buildCiCdAdmission,
  buildGitCanonPlan,
  buildGitFederationAdmission,
  buildRepoGraphDatabaseSql,
  buildRepoGraphPlan,
  buildRepoGraphSnapshot,
  buildRepositorySoul,
  renderRepositorySoulMarkdown,
  renderRepositorySoulHtml,
  buildRepositorySoulSuggestion,
  buildHoloMeshParticipationPlan,
  createHoloMeshSisterAdapter,
  submitRepositorySoulParticipation,
  loadRepoGraphSnapshotToDatabase,
  buildAbsorbAdepPlan,
  buildAbsorbAdepSyncReceipt,
  buildHoloRepoAgentCoordinationPlan,
  buildCompletionManagementPlan,
  openDb,
  queryKs,
  buildStorageProofTemplate,
  buildDeliveryStorageImport,
  buildArtifactLifecycle,
  buildCanonGraduationPlan,
  buildBoundedAutonomyProjectionBundle,
  buildBoundedAutonomyState,
  renderBoundedAutonomySse,
  renderFounderAutonomyHoloScript,
  runBoundedTaskFarm
} from '@holoscript/holorepo';

const config = defaultHoloRepoConfig({ storageRoot: '/mnt/my-nvme/holorepo' });
const doctor = buildDoctorReport({ config });
const graph = buildRepoGraphPlan(config);
const snapshot = buildRepoGraphSnapshot(config);
const soul = buildRepositorySoul(snapshot);
const suggestion = buildRepositorySoulSuggestion(soul, {
  source: 'CONTRIBUTING.md',
  submitter: { kind: 'human', id: 'contributor-42' },
  intent: {
    kind: 'documentation',
    title: 'Clarify the local setup',
    description: 'Add the missing database bootstrap step.',
  },
});
const participation = buildHoloMeshParticipationPlan(suggestion, {
  teamId: 'team_public',
});
const absorb = buildAbsorbAdepPlan(config);
const agents = buildHoloRepoAgentCoordinationPlan({ config, paths: ['package.json'], agentCount: 100 });
const completion = buildCompletionManagementPlan(completionManifest, { taskId: 'task_123', commit: 'abc1234' });
const plan = buildGitCanonPlan(config);
const lifecycle = buildArtifactLifecycle(artifactLifecycleInput);
const identityLedger = buildRepositoryIdentityLedger(identityInput, { verifySignature });
const autonomy = buildBoundedAutonomyState(boundedAutonomyInput);
const autonomyBundle = buildBoundedAutonomyProjectionBundle(autonomy);

Product Boundary

HoloRepo is not only a GitHub skin. It is the agent-operable backing substrate and the evidence source for a human living-ecosystem view:

• sovereign git canon on storage the operator controls
• repo graph SSOT loaded into durable HoloRepo storage after laptop-side build
• DB receipts and staged migrations against the operator's Postgres
• HoloScript KS queries over the operator's knowledge store
• optional Absorb-Service/HoloGraph enrichment as an ADEP, without making it a hard custody dependency
• Git federation admission receipts that keep GitHub useful without treating it as custody
• HoloCI/CD plan, receipt, and admission proofs for sovereign gate evidence
• redacted DB/KS proof templates with explicit HoloKey lease placeholders
• native delivery planning for packages, apps, services, schemas, models, and corpora
• HoloGate delivery manifests plus OCI/Compose/systemd/Helm installer templates
• mirror readback receipts for npm, PyPI, OCI, web/object rails, and offline bundles
• readback-aware admission proofs for npm, PyPI, OCI, web, object storage, offline bundle, and HoloQR mirrors
• exact-integrity lifecycle ledgers for npm, PyPI, GitHub, OCI, service, and portable filesystem artifacts, with source lineage and propose-only graduation
• Soul-bound provisional repository identity with approval-bound promotion, rotation, revocation, migration, recovery, and caller-owned signature verification
• bounded task farming with drift and stale-receipt detection, receipt-backed external state/task authorization, leases/heartbeats/retries/rollback/recovery, wall-clock deadlines, and JSON/SSE/HoloScript projections
• operator promotion import receipts that bind admitted mirrors to HoloRepo custody
• filesystem storage imports that copy admitted artifact bytes into operator-controlled storage
• object-storage and owned-metal storage imports that accept destination digest proofs or opt-in provider-copy profiles
• package-native high-volume agent coordination planner (holorepo agents plan)
• package-native completion planner for deduplicated successor tasks and protected-review packets
• package-native Repo Soul compiler with language DNA, participation doors, non-authoritative SOUL.md, stable agent JSON, offline HTML, and write receipts
• package-native typed participation envelopes and adapter plans that grant no source authority and keep HoloMesh an optional sister product
• an optional HoloMesh sister-adapter boundary for live identity, suggestions, tasks, protected reviews, leases, messages, and completion routing; the current canary proves routine suggestion submission/dedup only, and no other live adapter capability is implied without its typed receipt
• federation to GitHub/Gitea/GitLab as export or review, not custody proof

Release lane: v1-public.

Release Boundary

This package is distributed under the MIT license so agent frameworks can adopt, fork, and embed the client surface. The compatibility label is v1-public: documented exports and commands, listed schema ids, pure contract/conformance/ migration/recovery evaluation, config, read-only DB/KS operations, stage-write proofs, local git planning, lifecycle, identity, bounded autonomy, and receipt generation are stable within 1.x. Typed Repo Soul participation envelopes/plans/receipts are also supported: planning remains local and dependency-free, while live HoloMesh execution requires an injected sister adapter and a returned typed receipt. Admission proofs can consume one or more readback receipts as rail-specific evidence, reject mismatched rails, versions, and digests, and prepare a promotion route. Promotion imports require an operator custody receipt and write HoloRepo custody proof; delivery import copies digest-checked artifact bytes into filesystem roots controlled by the operator. For object-storage and owned-metal roots, it stays credential-safe in two modes: proof-only mode accepts a destination URI plus matching digest after an operator-managed transfer; provider-copy mode uses operator-approved profiles (aws-s3, rclone-copyto, mc-cp, or scp-owned-metal) from the operator environment, emits a dry-run preview receipt with redacted argv metadata and per-rail timeout policy, downloads a readback copy after --write, verifies the digest, and records the custody receipt without embedding cloud or SSH secrets. Legacy --copy-executor aws|rclone|mc|scp aliases resolve to those profiles.