the-custodian/docs/changes/2026-11-01-scanner-json-digest/native-r2/PLAN.md

Exact JSON filename/digest correction, revision 2

Proposal: SYNC-SCANNER-JSON-DIGEST-20261101, revision 2. Revision 1 remains preserved in the parent directory. This revision adds executable native preparation to the already-tested paired profile correction. No native mutation or source-policy activation has occurred.

The founder's read-only preflight verified deployment forgejo/forge UID 1faefb26-cccd-4d0e-b509-70a7eb0b4f4d, pod UID 2c9f911a-403e-4183-a027-2b8d48742348, node UID 0659e49e-6539-480a-8b0f-2969dd88cb05, and the exact previous adapter, Gitleaks and hook hashes. CPU requests were 68% and memory requests 76%. Strategy is Recreate; main container requests remain 200m/1104Mi and memory limit 1536Mi.

Action and scope

The existing YAML filename/exact lowercase 64-hex exception gains its quoted JSON equivalent in both local and receiver adapters. It still applies only to generic-api-key matches whose filename has one of the existing extensions. It does not adjudicate UUID resource identities, public fingerprints, natural-language findings, other digest formats, or every held Custodian artifact.

1. Recheck six owner-source preimages, deployment/node/pod identities, existing guard and selected ConfigMap, and every current repository's hook inventory. Refuse unknown hook bytes, symlinks, missing scanner fragments or more than 500 repositories. Snapshot protected hook hashes and permissions. The initial pod identity must still match; drift requires new preparation/review.
2. Server dry-run the new immutable ConfigMap and conditional deployment patch, and capture client ConfigMap diff without printing raw objects or errors. The receipt lists the exact two deployment fields being changed. These server checks are prepared; they have not been run against the live cluster yet.
3. Stage binary d7dbd0ef57312ab9507874bb5fd67c49bef637b6d7dee121e526227307af4bf0 in /data/security/receive-secret-scan/20261102-d7dbd0ef5731; copy the unchanged pinned Gitleaks from the verified old directory. Check owner, hash, non-symlink and executable modes. Retain every previous directory.
4. Before activation, run a disposable tmpfs receive-pack probe with the staged binary, pinned real Gitleaks and a copy of an actual current dispatcher: accept the JSON digest; reject an intermediate synthetic private key even after removal from the tip; discard quarantine; reject unavailable scanner; accept clean recovery. No hosted repository is used for probe writes.
5. Create immutable forgejo-secret-template-619d94208139. Atomically replace only each repository's scanner fragment, keeping permissions/group and protected dispatcher/authorization hooks. Append the new artifact guard to all existing guards and select the new hook ConfigMap with UID/resourceVersion/before-value JSON-patch tests. No image, resource, strategy, credential or Git object changes.
6. Wait up to 180 seconds for the current deployment's Ready pod; reconcile known old hooks on any repositories created during the transition. Verify protected hooks, mounted template hash and full artifact guard. Repeat the isolated receive probe after activation. Retain a sanitized local receipt at /tmp/forge-scanner-rollout-receipt.json.
7. After native verification, source_followthrough.py applies the six exact reviewed source changes: two repo-manager files, two railiance-forge files, and Apps Helm values/immutable ConfigMap. It checks all preimages before writing and requires this packet's successful native receipt. The local pre-commit hook directly imports the repo-manager source, so this paired source update activates its identical local profile. Commit and publish these sources through normal hooks, then retry eligible held publication and audit remaining failures separately.

packet.json seals executable scripts, selected inputs, source diffs/candidates, tests and this plan. Its SHA256 is the approval digest; the runner rechecks every sealed file. --approved-digest is an acknowledgement for founder execution, not a credential boundary or agent-issued approval. The agent must not use the founder kubeconfig. Native execution is attended by the founder or an independently authorized exact privileged execution path. No owner-agent approval has been invented; the founder reviews the paired owner source in this packet.

Verification and recovery

The original paired candidate passed 12 local real-Gitleaks tests and the full receiver suite. This native preparation passed 13 isolated filesystem/real receive cases and 5 controller tests. Tests cover staging/hash failure, symlinks, unchanged protected hooks, complete-scope refusal before writing, partial hook failure restoration, unknown-drift preservation, conditional patch roundtrip and recovery after a lost patch response. The offline dispatcher is an explicit scanner-only fixture; native execution separately copies and tests a real current dispatcher, excluding the authorization engine's native invocation as documented by the probe.

Any exception after staging starts is recorded as failure and attempts guarded rollback, including an uncertain patch response. Rollback accepts only the exact known old or proposed guard/template pair. It restores the old deployment reference/guard, waits up to 180 seconds, restores only known old/new scanner fragments, verifies all preserved hooks, rechecks the mounted old template and runs the old clean/private-key/quarantine/recovery probe. Unknown concurrent changes are retained and reported as unverified rather than overwritten. Old artifacts are never deleted. New immutable artifacts/ConfigMap are retained for evidence; a retry requires preserving/reviewing the prior receipt. Separate rollback mode is prepared in the same runner. A failed rollback requires founder recovery; automatic recovery is not guaranteed.

The controller does not coordinate unrelated native administrators or freeze repository creation. It catches known old hooks again after rollout and verifies template inheritance for future repositories. Concurrent destructive repository or protected-hook changes fail verification. All scans retain complete introduced-object/history scope and existing limits; no suppression switch or raw finding values are introduced.

Cost, interruption and residual risk

No new service, image pull, infrastructure commitment or increased resource request is proposed. Estimated attended execution is 15–30 minutes; local probes use existing compute. Monetary infrastructure increment is EUR 0; founder time is unpriced. Recreate causes an expected 1–3 minute Git-hosting interruption, with up to another 3 minutes for readiness rollback, plus bounded probe/command time. This is an estimate, not an availability guarantee.

Modelled recovery effort is up to one hour (illustratively EUR 100 at EUR 100/hour); there is no defensible complete EUR loss bound for a scanner exception or failed native recovery. The security consequence remains subject to explicit supervisor judgement. A real credential deliberately shaped as an approved filename/digest is indistinguishable by this exception alone; this limitation already exists for the YAML form and extends to its JSON representation. Other rules and provider/private-key negative tests remain active. No autopilot budget, risk grant, promotion or scored approval follows from this preparation.

Founder execution after exact approval

The convenience launcher /tmp/forge-scanner-rollout.sh pins this packet's SHA256, explicitly selects the attended admin context, and runs apply. Review the plan, six source diffs and runner before execution. Return the sanitized receipt/output. Source followthrough and publication then continue under the same exact approved scope. Do not rerun an uncertain apply; preserve its receipt and inspect or use the reviewed rollback.