ops-mason/docs/forgejo-structural-materialization-source-v1.md

# Forgejo structural materialization preparation v1 — 2026-10-11

Materialization is the policies, roles, fixed custody layout and catalog identity
under accepted SecurityCaseTypes §2/§7. It precedes follow-through. Minting a
secret, delivering it, registering a client and verifying the native consumer
are follow-through success, not structural prerequisites. The accepted execution
architecture (memo infd-20261010-security-case-execution version1, confirmed
approval e46b149b-ec3c-4b3b-98a7-dcb4934448ca) preserves this split and requires
independent structural evidence. It approves no new native session or type.

## Concrete source drift and the hash boundary

The committed Forgejo case and bundle are both @1.1; all bundle file hashes still
match. Both Mason plan and manifest pin full render af1f4f81ef313f5e086e6e3de17197d9112dd40f00b4c20b52b5ca73c7a6d18a.
Re-rendering type e2174ce with today's exact validator/provider declarations
reproduces that digest. Current type patch 35880bb adds --check-config and
startup-check wording to register-client; it renders full digest
e64b56e4590b57b858303fcda1a474693e3dd821bc83df26646fe78fc345498a.
Only follow_through changes. Materialization, composition, verification and
rollback compare equal. This is a real stricter execution guard, not volatile
Git/time data. The complete run digest must remain different.

`src/ops_mason/case_structure.py` prepares a separate structural projection
fingerprint and exact current case/type/plan/bundle pins. Before producing a
request it verifies every hashed bundle file, the complete current generated
policy (including self lifecycle), exact CCR reader/role/target bindings, custody
layout inventory and catalog source. A freshly rehashed wider ACL, namespace or
sibling-path change still fails against current templates. Non-semantic HCL
header comments may differ; policy statements must match. Unknown bundle files,
path traversal and symlinks are refused. The stale full run digest is retained as
reviewed_render_digest with run_source_changed=true, never promoted into current
execution acceptance. Source structural equality is distinct from native presence
or creation ownership.

Read-only command, using NetKingdom's validator/render and no live survey:

```
ops-mason structure-request --case ../net-kingdom/security-cases/forgejo-netkingdom-oidc.yaml --plan plans/case-forgejo-netkingdom-oidc.md --bundle builds/case-forgejo-netkingdom-oidc --allow-unimplemented
```

The real source yields five object requests: fixed KV layout, ESO policy,
consumer policy, ESO role and draft catalog pointer. Native policy/role evidence
belongs to RailiancePlatform; the pointer source belongs to OpsWarden. KV layout
proof is metadata/layout only and never requires or claims a value. Neither mint
nor secret-delivered is in this structural inventory. Each source input is bounded
at 256 KiB; maximum inventory is 32 objects/64 files.

## Typed receipt seam, not a bare status label

Request protocol ops-mason.case-structure-request.v1 and typed Observation are a
local source seam; owner acknowledgment is still required before wiring them into
native dispatch. Each observation binds the full request, object ID, owner,
exact target and expected structural fingerprint, disposition and evidence ref.
The injected verifier must authenticate native owner provenance or explicitly
attended manual evidence. It sees the complete observation/change receipt, never
only a trusted JSON ref. No native verifier is installed here. Fake unit verifiers
prove refusal/projection behavior only.

Native structure is classified created or preexisting-matched. Created requires
an independently verified change receipt. Layout-only and pointer-source neither
claim stored values nor creation undo. VerifiedStructure projects only proven
created typed StructuralObject identities into reverse-order rollback, retaining
object ID, kind, target, owner and source digest. Policy/role name collisions remain
distinct; shared objects and source layout
never acquire delete authority. Provider diagnostics, OS/Python output and raw
exceptions are withheld during receipt verification. This produces candidate
structural evidence, not a case status mutation or global native-complete result.

`bind_status_transition` previews the raw-hash seam without writing a case: it
re-authenticates all structural observations, requires exact accepted source
bytes, permits only semantic status accepted→materialized with every other field
unchanged, and retains original/request/materialized digests. An admitted owner
must authenticate that binding for Warden; the function supplies no signature,
case update or authority. Parameter, owner or acceptance changes require new
review. This avoids binding an accepted-status receipt to the wrong raw digest
when Warden and the broker later read the materialized case.

The legacy committed rollback.yaml lists planned identities in removes_exactly;
that list is not creation evidence. Existing case_plan uses it as an own-build
collision hint. The new structural receipt path deliberately does not inherit
that hint as ownership or rollback permission. Replacing the legacy planning hint
with authenticated receipt ingestion is a distinct integration step requiring an
actual owner evidence adapter; source JSON alone cannot discharge it.

## Exact owner contracts still needed

| Owner | Existing source capability | Missing machine/native contract |
| --- | --- | --- |
| ops-mason + RailiancePlatform | Source bundle, CCR41 ESO structure applied; typed metadata inventory prepared | Fresh independently authenticated policy/role/layout observations; created vs preexisting provenance; exact receipt signing/attended manual custody and binding consumed by Warden |
| railiance-apps + RailiancePlatform | CCR42 consumer policy draft | Consumer reader openbao.auth, actual namespace/SA or admitted identity, review and application; CCR42 is still in_flight with historical @1.0 provenance and must be reconciled explicitly to current @1.1 before using its receipt |
| RailiancePlatform | Exact generated-in-custody broker, CAS0, materialized-case/client checks, grant_token_revoked receipt | Closed adapter interface/source acceptance; immutable case source resolution, per-attempt owner receipt plus broker-grant and parent-session revocation fingerprints; owner-native CAS already-present reconciliation (never rerun generation) |
| NetKingdom + KeyCape | Contained registration helper with --check-config, expected UID/RV, byte-preserving merge/readback | Typed adapter parameters and receipt/undo contract for groups/env/client registration, source-resolved current case, native UID/RV refusal and attribution; no user-engine runtime-token substitution |
| RailiancePlatform | Delivery source for ESO | Fixed metadata-only delivery/status/undo adapter and independently verified created target refs; readiness separate from materialization |
| railiance-apps | Forgejo OIDC/group-enforcement consumer ownership | Fixed owner adapter or authenticated receipt-only step, exact CCR42 binding, actual consumer group refusal and rollback evidence |
| NetKingdom + OpsWarden | Acknowledged descriptive type1.1; durable local execution kernel | Accepted exact machine descriptors and owner adapter/source refs pinned in the type, all ordered verification steps, native evidence/caller provenance, contained session integration and dispatch CLI |

The first broker descriptor must require both broker-grant and parent-session
revocation scopes, exact case/type/source/catalog/actor/lane pins and per-attempt
identity. Existing broker exit3 already-present is owner reconciliation work,
not verified failed-before-change/retry-safe. Current descriptive type remains
plan-only. No prose entry_point/check/action is interpreted as shell or argv.

## Validation and remaining state

Thirty-three relevant tests pass: fifteen structural/CLI tests plus existing case
plan/build suites. Structural negatives alter and rehash source ACLs, auth
namespace, catalog and KV inventory; receipt negatives omit owners, forge exact
pins or use secret-minted as structural status. Created/preexisting projection
excludes shared objects from undo; source CLI performs no live survey or bundle
write. Existing stale @1.0 test assertions now validate the accepted input type
instead of falsely failing the @1.1 reference case. Ruff checks pass.

MASON-WP-0010-T03 remains progress for actual structural evidence and CCR42
binding/application; mint is removed from its structural readiness blocker.
WARDEN-WP-0044-T03 and NK-WP-0048-T06 retain native follow-through, full current
run digest/machine source binding, verification and first live-case acceptance.
No case/type status, credential, policy, catalog activation or workload was changed.

## Explicit source-root selection — 2026-10-16

`plan`, `build` and `structure-request` accept `--types-root` and pass it to
NetKingdom's existing exact-version loader. The default remains
`<netkingdom-root>/security-case-types`; a requested version never falls forward
or backward. Provider declarations still resolve from the NetKingdom repository's
siblings, independently of the selected type root.

Prepare the acknowledged 1.2 source projection without a live survey:

```bash
ops-mason plan --case ../net-kingdom/security-case-type-revisions/1.2/oidc-browser-relying-party/examples/forgejo.yaml --types-root ../net-kingdom/security-case-type-revisions/1.2 --no-live --allow-unimplemented
```

This actual case is proposed and has no acceptance. Its six-object draft includes
the dedicated consumer ESO role bound to namespace `forgejo` and service account
`forgejo-keycape-forgejo-eso`. Source-root selection grants no acceptance: normal
admission still refuses the acknowledged type; `build` refuses the proposed case,
and `structure-request` refuses the historical 1.1 plan/bundle for it. A current
accepted case and reviewed plan are needed before regenerating a build/request.
Do not repin historical acceptance or relabel an offline plan as reviewed.

Six integration checks exercise these paths against the actual owner validator
and source package, including malformed namespace refusal. This CLI compatibility
change does not supply the owner-native contracts listed above. Machine descriptors,
source receipt authentication, current CCR42 binding and native six-object proof
remain with MASON-WP-0010-T03 / NK-WP-0048-T06 and their existing owners.