activity-core/docs/custodian-runtime-binding-proposal.md

# Custodian runtime binding proposal

Review artifact, 2026-10-19. Not a deployment or activation approval. Both native
ActivityDefinitions remain `enabled: false`. No manifests, images or schedules
were changed for this proposal. Read with `custodian-bounded-operations.md`.

## Verified source boundary

The worker in `k8s/railiance/20-runtime.yaml` runs as UID/GID 1000 and already
uses `actcore-ops-artefacts` for freshness and owner-return subdirectories. Its
image does not contain the Custodian commands; its current mounts contain
neither the accepted fleet workplans/decisions nor the new private state.
`CUSTODIAN_REPO_ROOT=/var/custodian` only binds existing prompts/working memory;
it does not satisfy any `ACTIVITY_CORE_CUSTODIAN_*` binding.

The existing immutable ConfigMap plus read-only mount pattern documented in
`k8s/backup-release/README.md` is sufficient for the small command bundle. No
new packaging service is needed. Proposed source pin:
`the-custodian@60d893af1bf77f457504b64ff1c9ffb5c6ae6579`.
These four files total 30,169 bytes and use Python standard-library modules;
the daily command imports/calls the two sibling helper scripts.

| Path under owner root | SHA-256 |
| --- | --- |
| scripts/security_flow_daily.py | 4a4e84702b3fb38d086695bb6d601430d8914bd79286b4f683794206f110c353 |
| scripts/security_flow_report.py | eac9fdcc56d7f3ff613e6848c7523fb9a421d82a3b564a51c36f8c2b842eef02 |
| scripts/sync_resolved_decisions.py | 182433ca7cd31e2b2773246ec1be02569ba6f089ac009add6543e5e48777b5ec |
| scripts/weekly_allocation_report.py | 93f546243331308d7e60f8db36e988d9847537a2fe46cce49ee2fffba1f7f247 |

A reviewed immutable ConfigMap can map these four keys to `scripts/<name>`
below `/opt/custodian-commands`. Kubernetes ConfigMap volume projections use
symlinks, which the executor deliberately rejects. Therefore copy the mounted
immutable bundle into a dedicated emptyDir in an init container, verify all four
hashes there, then mount that copy read-only in the worker. Do not bind the
projected ConfigMap directly or weaken executor symlink checks. Alternatively,
copy the same pinned files into the existing worker image during its reviewed
build. The latter avoids the init-container copy and is the narrower runtime
mount boundary, but requires an accepted source-delivery/build input. Neither
alternative has been chosen or implemented here.

## Exact proposed bindings and outstanding choices

| Binding | Proposed value / owner decision |
| --- | --- |
| ACTIVITY_CORE_CUSTODIAN_ROOT | `/opt/custodian-commands`, regular files, read-only, hashes above |
| ACTIVITY_CORE_CUSTODIAN_FLEET_ROOT | `/var/lib/custodian-inputs/fleet`, read-only accepted snapshots |
| ACTIVITY_CORE_CUSTODIAN_STATE_ROOT | `/var/lib/activity-core/custodian`, persistent, UID 1000, mode 0700 |
| ACTIVITY_CORE_CUSTODIAN_REPOS | Explicit operator-approved subset of the daily report estate; each must have `workplans/` |
| ACTIVITY_CORE_CUSTODIAN_HUB | `http://state-hub.state-hub.svc.cluster.local:8000`, subject to admitted network verification |
| ACTIVITY_CORE_CUSTODIAN_ALLOCATION_REQUEST | `/var/lib/activity-core/custodian/requests/current.json`, regular file protected against concurrent writers |

For daily input, preserve `<repo>/workplans/**/*.md` including dependency records
and `<repo>/decisions/*.md` only for approved decision-sync scope. The decision
helper scans every repo under the fleet root independently of the report list.
Do not mount a whole workstation home, `.git`, credential directories or arbitrary
mutable repositories. Fleet snapshots need per-repo revision, capture time,
refresh owner and an explicit staleness policy. No existing publication contract
for this combined input was found in the worker manifests. Choosing its publisher
is a real prerequisite; a pinned old snapshot alone cannot support daily freshness.

Weekly input remains the existing retained collector outputs plus request JSON,
not a new collector. Its owner must bind actual input/report paths and evaluation
time, freeze the request across retries, and publish a new request for the next
week. The executor does not advance a static `current.json` automatically.
Snapshot publication must be atomic relative to execution and preserve retained
inputs needed to reproduce reports. Never substitute synthetic readings.

Storage choice: reuse a new `custodian` subdirectory of existing
`actcore-ops-artefacts` only after its owner accepts capacity, retention and backup
coverage, or provision a dedicated claim with those properties. The existing
rollout document describes a 1Gi local-path claim, and October 4 evidence reports
it Bound; neither proves present capacity or backup coverage. Precreate state,
`security-flow`, `requests` and output/input retention directories with correct
ownership. Do not chown/chmod the whole shared claim. A PVC subPath is acceptable
if actual mounted paths are regular directories and pass executor validation.

The proposed direct Hub service matches the worker's existing
`STATE_HUB_API_BASE`; the shared config also contains an edge-relay URL. Daily
message delivery requires a central message ID. A relay queued receipt is pending
evidence and is not interchangeable with that ID; do not select relay delivery
without an explicit adapter/replay contract. Needed operations are GET open
decisions, POST decision resolution, POST messages, and the existing progress
sink. Runtime network authorization remains unverified. The shared worker already
has secret env and kube mounts: this proposal does not establish credential isolation.

Placement choices for owner review:

1. Existing production worker: choose image-baked scripts or verified copied
   immutable bundle, choose fleet publisher and state claim above, then review
   normal owner GitOps changes. This reuses the present Temporal task queue.
2. Workstation execution: requires an explicitly routed worker/task queue and
   a durable always-on ownership/connectivity contract. Merely starting another
   worker on `orchestrator-tq` is unsafe because either worker may receive these
   activities. No workstation routing or second scheduler is proposed.

## Verification and rollback before activation

Prepare the accepted source bundle and manifest diff outside active kustomization
until the choices above are recorded. Preserve both disabled definitions; native
schedule synchronization creates disabled definitions paused. Verify their DB
versions and Temporal paused state after any later deployment, without firing.
Mount/env changes exceed image-only promotion authority; follow owner-reviewed
GitOps promotion, not a widened image-only helper.

Local source tests already cover parsing both disabled definitions, missing-binding
refusal before subprocess, fixed commands, symlink rejection, bounded timeouts
and sanitized receipts. At delivery review, independently verify pinned hashes,
worker Python imports, UID/modes, mount read-only flags, free retained capacity,
scoped fleet revision/age and actual request/output confinement. Use fixture inputs
for initial process verification; daily dry-run still reads Hub and therefore is
not an offline test. Obtain separate authorization for real Hub operations.

After operator-approved runtime placement, retain exact worker image/bundle and
input revisions, operation context, owner report hash, progress sink result and
owner acknowledgment. Scheduled activation and first unattended run remain
ACTIVITY-WP-0047-T02/T03 and CUST-WP-0071-T04/T05 gates. An exit-zero fixture
or a paused schedule does not satisfy them.

Rollback: keep both schedules paused, restore the previous reviewed worker
image/config/bundle references through GitOps, and keep old bundle objects until
no rollback ReplicaSet references them. Preserve private reports, checkpoints
and requests; do not delete the state claim. Inspect partially delivered daily
checkpoints before retrying, because rollback cannot undo Hub writes. Do not
reuse or overwrite an immutable weekly output for revised inputs.