repo-manager/docs/custodian-fleet-input-contract.md

Custodian fleet input publication contract

Owner recommendation, 2026-10-19; source preparation only. Repo Manager owns commit selection and work-record publication. Activity Core owns scheduling, private consumer storage, admission and run evidence. Custodian owns daily report semantics. These are proposed defaults, not runtime acceptance or an activation.

Reuse and exact missing boundary

rmgr freshness run --limit N --max-seconds S already observes Forge default HEAD, verifies the primary Hub projection and writes durable repo-manager.freshness-receipt.v1 receipts. It explicitly makes no checkout. The classification publisher's snapshots contain metadata, not work-record files. Neither command currently supplies a filesystem tree to Custodian commands. Do not reinterpret Hub rows or a classification snapshot as those input files.

The new offline prerequisite is:

python -m repo_manager.fleet_snapshot --request selected-commits.json --output snapshots/<unique-run-id>

It reads existing local Git objects, never fetches, checks out, changes a repo, contacts Hub/Forge, or reads a credential. This is a module CLI rather than a new daemon or scheduler. The publication owner supplies object stores using its existing approved Git delivery path. Choosing that runtime source/access path is still required; the exporter itself needs no network or authentication.

Request contract:

{
  "observed_at": "2026-10-19T07:00:00+02:00",
  "repositories": [
    {"slug": "the-custodian", "path": "/accepted/local/object-store/the-custodian", "commit": "<full-40-character-commit>"}
  ]
}

The example commit is a placeholder, deliberately not runnable. The publisher must retain each matching Forge observation/receipt ID separately; observed_at is supplied evidence, not a freshness assertion made by the offline exporter. Only workplans/**/*.md (including archived dependencies) and decisions/*.md are copied. Git symlinks, submodules at selected record paths, invalid slugs, non-full commit IDs, absent workplans and oversize records are refused. Dirty working files, .git, credentials and unrelated files are not copied. Limits are 2MiB per record and 64MiB total per export; exceeding either is an explicit publication failure, never partial accepted coverage.

Each new unique output contains <slug>/workplans, optional <slug>/decisions, manifest.json and finally COMPLETE. Manifest schema repo-manager.fleet-input.v1 records the requested observation time, all commits, file byte lengths and SHA-256 values. freshness_verified: false is intentional. COMPLETE contains the manifest SHA-256. Consumers must validate this marker, manifest and every file before accepting a publication. Failed promotion leaves no COMPLETE and must never be consumed. Names are never overwritten, even empty existing directories. The owner protects the output parent against concurrent untrusted writers. This is completion-marked publication, not a crash-durable transaction or automatically enforced read-only store. Do not change published files; mount the selected immutable directory read-only for the consumer.

Recommended default daily policy

Initial scope is the existing report estate: the-custodian, net-kingdom, railiance-platform, activity-core, access-engine, secrets-engine, ops-mason, ops-warden, key-cape, user-engine, tenant-engine, gate-house, kings-guard, policy-nexus and rapp-policy-nexus. This is a proposed explicit allowlist, not permission to publish every registered repo. The same selected set bounds both workplan reporting and decision synchronization. Review additions for cross-repo dependency completeness; missing dependencies remain unknown.

Recommend one pre-run publication step in the existing native daily workflow, not a separate timer. Reuse Repo Manager's Forge HEAD/primary receipt verification for the selected set, then export those exact commits from accepted object stores. Existing freshness run rotates the stalest fleet members and has no explicit repo-set option: its successful invocation alone does not establish this set's coverage. The publisher must join per-repo receipts and require every selected repo; no fabricated receipt or broad forced reconciliation is acceptable.

Recommended admission: observations at most 2 hours old at daily start, no future observation beyond 5 minutes of clock tolerance, all required repos present, full commits matching the verified observations, exact file hashes, and COMPLETE valid. Old commit age is not failure when its HEAD was recently re-observed. Never rewrite an old snapshot's timestamp to make it fresh. On missing/stale inputs, fail before security_flow_daily.py --apply, retain a sanitized missing repo/reason receipt and notify through the existing Activity Core failure path. Do not silently reuse yesterday's tree. These consumer freshness checks and the publication step are not yet integrated into the bounded executor; its current path existence checks are insufficient for activating this contract.

Hold a specific snapshot path throughout a run and its retries. Avoid current symlinks (executor rejects them) and in-place directory replacement. Placement must supply an immutable per-run path or a serialized binding update while consumers are quiescent. A static worker env mount cannot advance per-run inputs by itself; runtime owner must implement this handoff before activation.

Retention and weekly boundary

Recommend retaining 35 days of daily publications plus every snapshot referenced by an unresolved failure, checkpoint, audit or accepted recommendation. Capacity planning must use measured export sizes, not assume the shared 1Gi claim suffices. Pruning is owner-reviewed initially; this exporter performs no deletion. Keep manifest/receipt hashes with run evidence and back up private state separately. Restore testing and capacity alarms are delivery gates, not established here.

Weekly sizing uses the existing cluster, resource-control, telemetry, inventory, provenance and optional previous-report/review inputs. Repo Manager must not manufacture telemetry or impersonate those collectors. Recommend retaining at least 13 weekly bundles plus all referenced/open recommendation evidence, with evaluation windows preserved. Custodian owns the weekly request and collector coverage validation; Activity Core owns immutable request handoff and retained report storage. Daily Git snapshots do not satisfy weekly measurement coverage.

Owner handoff and validation

Repo Manager recommendation: use this bounded offline export after the existing Forge receipt checks, with the explicit 15-repo set and 2-hour admission default. Activity Core should add the manifest/freshness gate and per-run immutable binding when implementing the chosen worker placement; never loosen symlink validation. No public API, broad clone service, extra schedule or new credential path is needed. Production receipt verification, object-store provisioning, consumer gate, retention/storage acceptance and first scheduled evidence remain unfinished.

Local tests use temporary Git repositories and prove committed-byte export despite dirty files, strict path selection, hashes/completion marker, immutable names, invalid-request refusal, selected symlink refusal and size bounds. They perform no network, production reads, schedule changes or Hub writes.