docs: a file deploy owns has two shapes, and a checker sees the other one #687

Merged

coilyco-ops merged 1 commit from docs/a-deploy-owned-file-has-two-shapes-claude into main

2026-08-13 18:52:59 +00:00

coilyco-ops commented

2026-08-13 18:51:28 +00:00

Member

closes #682

Both of Echo's deploy-owned config files are ConfigMaps, and both loaders got that wrong in opposite directions:

LoadAccessPolicy(ConfigMap)  -> error          KnownFields(true)
LoadMCPRoster(ConfigMap)     -> 0 servers, nil  no strictness

The gate built on the first rejected every policy deploy has while passing every fixture. The second returned an empty roster, which is a legitimate state, so a wrong path and a deliberate no-tool deployment looked identical.

Why the contrast is the document

A reader who saw only the loud failure would conclude the strictness was the problem — and would then write the quiet one. That is precisely what happened here, in one package, and neither loader is wrong for the pod.

The cheaper half

A fixture written from a format's documentation describes the mounted shape, which is the one input a checker never receives. Mine did, and passed. Reading one real file from deploy before writing the first fixture is one command.

Placement

Its own file rather than a section: sirens-echo-access-check.md was at 78 lines and lands exactly on the 80-line cap with the single link added. That is #527's problem arriving in practice, and splitting was the answer there too.

ward exec gate green.

closes #682 Both of Echo's deploy-owned config files are ConfigMaps, and **both loaders got that wrong in opposite directions**: ``` LoadAccessPolicy(ConfigMap) -> error KnownFields(true) LoadMCPRoster(ConfigMap) -> 0 servers, nil no strictness ``` The gate built on the first rejected every policy deploy has while passing every fixture. The second returned an empty roster, which is a **legitimate state**, so a wrong path and a deliberate no-tool deployment looked identical. ## Why the contrast is the document A reader who saw only the loud failure would conclude the strictness was the problem — and would then write the quiet one. That is precisely what happened here, in one package, and neither loader is wrong for the pod. ## The cheaper half **A fixture written from a format's documentation describes the mounted shape**, which is the one input a checker never receives. Mine did, and passed. Reading one real file from deploy before writing the first fixture is one command. ## Placement Its own file rather than a section: `sirens-echo-access-check.md` was at 78 lines and lands exactly on the 80-line cap with the single link added. That is #527's problem arriving in practice, and splitting was the answer there too. `ward exec gate` green.

coilyco-ops added 1 commit

2026-08-13 18:51:28 +00:00

docs: a file deploy owns has two shapes, and a checker sees the other one

ci / image-build (pull_request) Successful in 22s

Details

ci / test (pull_request) Successful in 37s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

878084d204

Two of Echo's configuration files are ConfigMaps in the deploy repository.
Kubernetes mounts the value under data as a file, so the runtime loader
receives a bare document and is right to expect one. An offline checker reads
the repository file, which is the wrapper.

Both loaders got this wrong and in opposite directions. LoadAccessPolicy has
KnownFields and errored, so the gate built on it rejected every real policy
while passing every fixture. LoadMCPRoster had no strictness, so the wrapper
parsed to zero servers with no error, and an empty roster is a legitimate state.

The contrast is why this is a document rather than a comment. A reader who saw
only the loud failure would conclude the strictness was the problem, and would
then write the quiet one.

The second half is the cheaper lesson: a fixture written from a format's
documentation describes the mounted shape, which is the one input a checker
never receives. Reading one real file first costs one command.

sirens-echo-access-check.md gains one line and lands exactly on the 80 line cap,
which is why the rule is its own file rather than a section.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 18:51:28 +00:00

coilyco-ops merged commit 71c1602919 into main

2026-08-13 18:52:59 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 18:53:01 +00:00

Merge pull request 'docs: a file deploy owns has two shapes, and a checker sees the other one' (#687) from docs/a-deploy-owned-file-has-two-shapes-claude into main