coulomb/policy-nexus
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Preserve complete served policy history in clean release builds

Browse source 
Assistant: codex
Assistant-Model: gpt-6.1-sol
Assistant-Session: 01a126e1-76f8-7643-8cf3-e93336539ade
This commit is contained in:
tegwick 2026-10-11 02:25:29 +02:00
parent bb76867678
commit 7c51a7b185
162 changed files with 37466 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/evidence/2026-10-11-hosting-preparation/complete-history-validation.json Normal file
View file

@ -0,0 +1,30 @@
{
"schema_version": 1,
"policy_tests_passed": 45,
"new_history_regressions": 7,
"new_transition_regressions": 5,
"original_owner_sources_git_show_verified": 72,
"previous_current_immutable_urls_captured_http200": 72,
"previous_current_immutable_urls_byte_exact_preserved": 72,
"clean_candidate_documents": 73,
"reviewed_semantic_changed_ids": [
"CUST-ADR-002",
"CUST-ADR-004",
"RISK-F-0008",
"RMASTER-ADR-0006",
"canon-work-record-types",
"canon-workplan-terminology-fleet",
"net-kingdom-architecture",
"netkingdom-security-layer-model-v0.7",
"netkingdom-security-layer-model-v0.8",
"netkingdom-tenancy-posture",
"ops-warden-adr-0004"
],
"three_minimal_owner_publication_revision_bumps": {
"netkingdom-tenancy-posture": "draft-14 -> draft-15",
"net-kingdom-architecture": "draft-3 -> draft-4",
"RISK-F-0008": "published-1 -> published-2"
},
"new_revision_public_urls_prior_status": 404,
"limits": "Staged-source behavior verification against exact current HEAD exports plus three explicit revision-only overlays, not final committed CI source lock, OCI image, inventory provenance, security scan or native deployment approval. All original failed transition evidence is retained."
}

147
docs/evidence/2026-10-11-hosting-preparation/content-delta.json Normal file
View file

@ -0,0 +1,147 @@
{
"added": [
{
"canonical_path": "standards/security-layer-model/v0.8/index.html",
"currency": "current",
"id": "netkingdom-security-layer-model-v0.8",
"last_reviewed": "2026-10-10",
"lifecycle": "active",
"owner": "gate-house",
"review_due": "2027-01-10",
"revision": "accepted-1",
"revision_path": "standards/security-layer-model/v0.8/revisions/accepted-1/index.html",
"source_digest": "3d8298560069ef471fba28d2b1245fb2309328f231dad1a667cdf0ce5a5a7c8b",
"source_path": "canon/standards/security-layer-model_v0.8.md",
"source_repo": "net-kingdom",
"source_revision": "0e17d956ab45f8c4a0163b70749490c414e54e67",
"status": "accepted",
"title": "NetKingdom Security Layer Model v0.8"
}
],
"existing_changes": [
{
"id": "netkingdom-tenancy-posture",
"delta": {
"source_digest": {
"served": "27d6878c68310619877de516000d9af78d5456a92572a709884ed052d765b876",
"candidate": "795944f3f7735f58c5447b57bd3f65766a6e8d7d54f75586f9f269d4f6de5c56"
}
},
"removed": false
},
{
"id": "canon-work-record-types",
"delta": {
"source_digest": {
"served": "1a40de294be332ee713cdaab532a32a83718f3952c339fbff835ecee899a8dbc",
"candidate": "ab5d9de07fd899fc5334c9912571ed3d6748f2ee4bd0c9f81c5606c4727024d1"
},
"revision": {
"served": "accepted-1",
"candidate": "accepted-2"
}
},
"removed": false
},
{
"id": "canon-workplan-terminology-fleet",
"delta": {
"source_digest": {
"served": "199812632ac342ca3231498e545e3701e10c191ca144035b36a23c1a0b717712",
"candidate": "431d36f40d90bcd40a640c16b583095ad35757675f78ddcea382e6f1b2e23710"
},
"revision": {
"served": "accepted-1",
"candidate": "accepted-2"
}
},
"removed": false
},
{
"id": "net-kingdom-architecture",
"delta": {
"source_digest": {
"served": "b9f89f706a801d54961fc67d725ca433b7c3b6a083c54793de6e8b60d1dd42a8",
"candidate": "d57021a85db6b69b58d21f6be258a57ec86deecdfff30395412657cf273dd9e7"
}
},
"removed": false
},
{
"id": "RMASTER-ADR-0006",
"delta": {
"source_digest": {
"served": "9839d8a4a4617b745cfacab6a0fb72157e88cddf53f40226d8246a64864de533",
"candidate": "5d0454384e1a3f31939aaa4e3d4225ede73c3669a2d86b15efb4b56803e01690"
},
"revision": {
"served": "accepted-2",
"candidate": "accepted-3"
}
},
"removed": false
},
{
"id": "ops-warden-adr-0004",
"delta": {
"source_digest": {
"served": "5db38dcb754af1ba639f4ceca056df842bc7b91fa48dd8bad21611aee29f682d",
"candidate": "e379f47fb56214ff0cc6abcddaaad33c6969cf386e11abeed105b4fef953c5a0"
},
"revision": {
"served": "1",
"candidate": "2"
}
},
"removed": false
},
{
"id": "CUST-ADR-002",
"delta": {
"source_digest": {
"served": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec",
"candidate": "b860b02b1e8f47b914d41c6ecf67f451e86326ed51c7c53dcc6b7870fc889e42"
},
"revision": {
"served": "accepted-1",
"candidate": "accepted-2"
}
},
"removed": false
},
{
"id": "CUST-ADR-004",
"delta": {
"source_digest": {
"served": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557",
"candidate": "4f9978b40c104600c0ccb981a8ee52376a5d3003da4786752029af524b7dede7"
},
"revision": {
"served": "accepted-1",
"candidate": "accepted-2"
}
},
"removed": false
},
{
"id": "netkingdom-security-layer-model-v0.7",
"delta": {
"lifecycle": {
"served": "active",
"candidate": "superseded"
}
},
"removed": false
},
{
"id": "RISK-F-0008",
"delta": {
"source_digest": {
"served": "8bf47414a9f958afb57649f087a2617f91a8f2aeaa4f34d04d8fb3a0f453e840",
"candidate": "1762d479f1ea572bacdb8ea7612b36b342fb6f87c21e5a4a92732c74215865b1"
}
},
"removed": false
}
]
}

101
docs/evidence/2026-10-11-hosting-preparation/content-review.json Normal file
View file

File diff suppressed because one or more lines are too long

798
docs/evidence/2026-10-11-hosting-preparation/immutable-audit.json Normal file
View file

@ -0,0 +1,798 @@
{
"baseline_documents": 72,
"candidate_documents": 73,
"immutable_results": [
{
"id": "netkingdom-tenancy-posture",
"revision_path": "standards/tenancy-posture/v0.1/revisions/draft-14/index.html",
"old_source_digest": "27d6878c68310619877de516000d9af78d5456a92572a709884ed052d765b876",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "404f0bc2699040d0a065d557dc02232c025b1e340a77c64d645464bca2745b01",
"candidate_exists": true,
"candidate_html_sha256": "66525eb12b28a488ecca9c42e9788f3c19133848e990c8c1ec19765cf7c251d1",
"retained_byte_exact": false
},
{
"id": "canon-autonomy-lanes",
"revision_path": "standards/autonomy-lanes/v0.1/revisions/accepted-1/index.html",
"old_source_digest": "106cb0c99f73983199c9f1d8491143aa2a2eb41ee450a02ec7968d3763f30399",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "aec0623d3e2a81d6141120906e97efbae941f7b2b5704ad42634484702932b13",
"candidate_exists": true,
"candidate_html_sha256": "5a9ccc831d60225e76a8ff3053034360d6672f6891cd5f6aaaa5bb0e66e160af",
"retained_byte_exact": false
},
{
"id": "canon-contrib-convention",
"revision_path": "standards/contribution-convention/v0.1/revisions/accepted-1/index.html",
"old_source_digest": "6dfc1d7b2b82ab18228a84660c1c7dff607aad1d9da37ac12084cdd2ab8ae112",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "0b8aa643a908ba780ce231cd5628d10035697004d2ac512b9d60c32077cd936e",
"candidate_exists": true,
"candidate_html_sha256": "aeb3e5fd208fb245d29c116a5d194bdb71eeb69a335829c292e9be85951ee1ee",
"retained_byte_exact": false
},
{
"id": "canon-project-repository-flavor",
"revision_path": "standards/project-repository-flavor/v0.1/revisions/accepted-1/index.html",
"old_source_digest": "61889b2f18a82a08b66ef90d758efe5c028a4f52aced1721a23e69c6f24a8224",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "cc5cdbaa875338b08a7ffed743121df16f002ada0b5a70268d32448ead57b2eb",
"candidate_exists": true,
"candidate_html_sha256": "dffddd9b2bdb30756593c493b31b5a888adedf3c3758e7edd8f62d9a33b46e5c",
"retained_byte_exact": false
},
{
"id": "canon-work-record-types",
"revision_path": "standards/work-record-types/v0.1/revisions/accepted-1/index.html",
"old_source_digest": "1a40de294be332ee713cdaab532a32a83718f3952c339fbff835ecee899a8dbc",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "43cf02d4b768194c482fc09a0eda11c62bfd3d4250da0175a9f0012f68b1fec4",
"candidate_exists": false,
"candidate_html_sha256": null,
"retained_byte_exact": false
},
{
"id": "canon-workplan-terminology-fleet",
"revision_path": "standards/workplan-terminology/v0.1/revisions/accepted-1/index.html",
"old_source_digest": "199812632ac342ca3231498e545e3701e10c191ca144035b36a23c1a0b717712",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "3fffb8c59107797e97db55bf8ee23280ddc2ca0ef1ea1edc1547c3b2c3bef3c0",
"candidate_exists": false,
"candidate_html_sha256": null,
"retained_byte_exact": false
},
{
"id": "coulomb-estate-architecture",
"revision_path": "architecture/coulomb-estate/v0.1/revisions/draft-3/index.html",
"old_source_digest": "3b4f93acdedc6f6d1a1c737c3327d9d55061506c5a879be09e6b0a2ea7f5f9bc",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "bac4d0ac08eaf5a64d8e0b3363e091e2426de99a2e5054b6812c650084dd3dd8",
"candidate_exists": true,
"candidate_html_sha256": "97ddf92ff7a0815f3ed27287f094eaf49013247e1d62cdcd01c1856a761ec7c0",
"retained_byte_exact": false
},
{
"id": "railiance-architecture",
"revision_path": "architecture/railiance/v0.1/revisions/draft-3/index.html",
"old_source_digest": "77de319978dfad02f40658bbeb96db46b246a46f1abd6a45f5b1269563de5568",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "4bfde5ce9935572f1b0c38368877605d35a30b8d822ad7735697462aa4e5318e",
"candidate_exists": true,
"candidate_html_sha256": "4a05fb79c324aeee1e7056f9da5ad78e18c4bfdaabd777d311e767d9f8b64b7e",
"retained_byte_exact": false
},
{
"id": "net-kingdom-architecture",
"revision_path": "architecture/net-kingdom/v0.1/revisions/draft-3/index.html",
"old_source_digest": "b9f89f706a801d54961fc67d725ca433b7c3b6a083c54793de6e8b60d1dd42a8",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "827f197303b1074e022dd60af8e9e0245d01b6785bc039e21cb7c527805f7010",
"candidate_exists": true,
"candidate_html_sha256": "1d0fd228cfb3cd7c3e04dbf5071cbdce4d64939c30a586311128746da771d0f3",
"retained_byte_exact": false
},
{
"id": "state-hub-architecture",
"revision_path": "architecture/state-hub/v0.1/revisions/draft-3/index.html",
"old_source_digest": "e7104b2182612efe90c9a12168757506402490229814d454e94917ae62d2bfac",
"old_source_revision": "803bb95e1d071f188f4202d53a235f8721a8ecdc",
"http_status": 200,
"served_html_sha256": "0430e83028f33b966e72f637f7b12acbcfa58a60810c0f6aaa2cfe3afc253c41",
"candidate_exists": true,
"candidate_html_sha256": "1281c6c65e37a6fd62051f9c36ccc528119bf4eb2c32b69bdd3e3d3c4b6904a6",
"retained_byte_exact": false
},
{
"id": "policy-nexus-architecture",
"revision_path": "architecture/policy-nexus/v0.1/revisions/draft-1/index.html",
"old_source_digest": "179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480",
"old_source_revision": "c1b60f322e3bcddff3cece618ece2bd3686169e1",
"http_status": 200,
"served_html_sha256": "1fe8e9ddfee222c1d3604f5a37a3b34b1274344dfb5233b1d9f52c98aaa944e6",
"candidate_exists": true,
"candidate_html_sha256": "ab06698c1ccddd1d465a23a98418cde1fd1ee82afc45085400dfa59bbd70595a",
"retained_byte_exact": false
},
{
"id": "policy-nexus-adr-0001",
"revision_path": "adr/addressing-and-permanence/v1/revisions/accepted-1/index.html",
"old_source_digest": "a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be",
"old_source_revision": "c1b60f322e3bcddff3cece618ece2bd3686169e1",
"http_status": 200,
"served_html_sha256": "883a91470d4dcf5d1eb0f02e769081c97c2be060379235757e27a7f59c9eb824",
"candidate_exists": true,
"candidate_html_sha256": "b097d2a93b1b68e5e0a084e245d17ba549c6d7745892816525dfbf469a8fb730",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0001",
"revision_path": "adr/railiance-repository-prefix/v1/revisions/accepted-1/index.html",
"old_source_digest": "b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "f005c4645fd09709ea4fb6ed24e080e6dc8dd6975e3a87ccc495b6516195ac18",
"candidate_exists": true,
"candidate_html_sha256": "4e21ca2c5969caa7b5d6a3884ef08fa7ef095d8a135e54196ba4bacc21582c2d",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0002",
"revision_path": "adr/railiance-rail-kubernetes-wave-1-boundary/v1/revisions/accepted-1/index.html",
"old_source_digest": "7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "bf60c98f5cb2e2e01e4c03bc8adb0059f041cfc894f2d1e5e086f2b7e1912c64",
"candidate_exists": true,
"candidate_html_sha256": "8f606d840935de029139c75de4e504cd006cb5e06074abfd45a0e2992dca69b7",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0003",
"revision_path": "adr/railiance-rapp-first-wave-selection/v1/revisions/accepted-1/index.html",
"old_source_digest": "28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "baab701edeb557dd1c971a802952b9f038ddeb8b88c92324b338988e6261ec7a",
"candidate_exists": true,
"candidate_html_sha256": "56c97200598f98f1d8813ff1eb633586839a2c5a79d023a98b7899cd3d04caef",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0004",
"revision_path": "adr/railiance-first-wave-reef-rollout/v1/revisions/accepted-1/index.html",
"old_source_digest": "36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "39274457b44e6ce0f4f5493272ad0022821ce86c190d42a0ed02d6d0131e637e",
"candidate_exists": true,
"candidate_html_sha256": "5e4f6f82d2bbc18c1a6347d371649026f4d199745c685695b752a3a869b8e8a1",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0005",
"revision_path": "adr/railiance-derived-rail-composition/v1/revisions/accepted-1/index.html",
"old_source_digest": "e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "9bc8dea9ae3fdc3a97ca78f388ef992d9966040e253fb7cc983b5efca78c4728",
"candidate_exists": true,
"candidate_html_sha256": "67f14e707247d126d22f906b8d3342549b9fe69ad15aa8d02f3bf6d42f7f412b",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0006",
"revision_path": "adr/railiance-reef-production-admission/v1/revisions/accepted-2/index.html",
"old_source_digest": "9839d8a4a4617b745cfacab6a0fb72157e88cddf53f40226d8246a64864de533",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "051b11d1f82a21775aa4328b39385d43649ddf7a267cb12d691c17feff07161b",
"candidate_exists": false,
"candidate_html_sha256": null,
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0007",
"revision_path": "adr/railiance-rapp-declaration-contract/v1/revisions/accepted-2/index.html",
"old_source_digest": "b1185388ded53188dc624fbda9bee517dd3ac80b35e881cd4a7962531bec52ff",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "fdb4bedcc9120932e8c2792956c603f9fa45a6b06ebe30c92b7661c62cd0a0e6",
"candidate_exists": true,
"candidate_html_sha256": "a5bb562cf37626deae56120acdde9d5c0c33fe76e8357746353cdf738c674f16",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0008",
"revision_path": "adr/railiance-private-by-default-exposure/v1/revisions/accepted-2/index.html",
"old_source_digest": "bd97ec8ee663bb416fae53c8cfe29c7066e4fd3a51a5bc364895297e6eb994b7",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "5c913da6b1e0c223bbe197d50f0f71dbf2e9c283ab7193758cf4567e059047ba",
"candidate_exists": true,
"candidate_html_sha256": "0a62d8368b0e4216985987b689faa5651ae14332664ecfbf54425845f07adf6d",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-001",
"revision_path": "adr/activity-core-event-bridge/v1/revisions/accepted-2/index.html",
"old_source_digest": "57ecf490465e71cc4970133301cc315748b1d6ee65caac3690472ff88f3aab06",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "ebbe7111cc8fe75943cac3b8df625eed6675c268fb2d78de90de7766427ba032",
"candidate_exists": true,
"candidate_html_sha256": "351f848c282870a3dd750ba2021ca593d13999880518b4347de11481a6ea833f",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-002",
"revision_path": "adr/activity-core-definition-format/v1/revisions/accepted-2/index.html",
"old_source_digest": "1670e1616094bc6f2c0c7d47b2e019c02d5870b22b564ef83afa24caff197bab",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "4f77070a5ceacc7463d6e570d650649149d934b865b069cf303a829e8823fb2c",
"candidate_exists": true,
"candidate_html_sha256": "4724343520b13411034fdcb440c433ad916685488fc9d2595935fdd2bc26371f",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-003",
"revision_path": "adr/activity-core-rule-instruction-model/v1/revisions/accepted-2/index.html",
"old_source_digest": "f1017730074727bcb0c68309c445ffb219ef647c8c5604adbfff76c4aa3f9d66",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "99ff7ee81f42d460105a4dadc69ddd369094bde64617cb07bf850458ff0f2400",
"candidate_exists": true,
"candidate_html_sha256": "d71ec09ce482561ae38e1a01ba910340e4abf687fe1850ccf2a8f2262ab66fe8",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-004",
"revision_path": "adr/activity-core-producer-trust-boundary/v1/revisions/accepted-2/index.html",
"old_source_digest": "92da58f58ee3dbb62233161a0fc0b7780920f81ec37fdd40d476be354f24e0eb",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "da014cb4991ecb8f03458016b69595a7ef82cece8a2a1f301b9a65140c6db5fe",
"candidate_exists": true,
"candidate_html_sha256": "eb29d356b52eefc6117d43aa3d23c85ca23947a84890f5f2d37c100e91f8eb93",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-005",
"revision_path": "adr/activity-core-ops-runs-vs-work-records/v1/revisions/accepted-2/index.html",
"old_source_digest": "984208262a0f6b67a6dc94cb078ebd0bcddc95d0b21a694d7e207677c10b471f",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "fb1afdaa34eed2c923d451a0ab119079abfaf3924c452bcd8bb9ab84b0b047bf",
"candidate_exists": true,
"candidate_html_sha256": "2ee5c97ecd32e5c2a34521610fac51b871796a8380f648f9e06efc3caea37519",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0001",
"revision_path": "adr/ops-warden-catalog-pointer-layer/v1/revisions/1/index.html",
"old_source_digest": "7df0bb364276e382cbee9383e7e67d399b0ac1b0353246e0ab323e629e732a6d",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "1c0fb4914894de9aae6fa9549d5b6e0ae2dcb401cb50e70febb481a93cf5acdf",
"candidate_exists": true,
"candidate_html_sha256": "70e4b7518b82a732339440890ae76bba813f0ad69b4d045ab98e352447469665",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0002",
"revision_path": "adr/ops-warden-conduit-not-broker/v1/revisions/1/index.html",
"old_source_digest": "7dcc31732d774ddf2c98636b69ee12e2d74034836ed0def81b7e06461309b53a",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "3484b554239c617d438325ab8e87a744ac24797f6e665cb2da9562060841b352",
"candidate_exists": true,
"candidate_html_sha256": "11fd3dc0cf8b6e79b815770577d55b1e63f329c1a3e23f219456d466adeb9edd",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0003",
"revision_path": "adr/ops-warden-cover-gaps/v1/revisions/1/index.html",
"old_source_digest": "45b47c02afa575fbfe5be980e426c331a1d99bb9cd9c7a8de80bf8e319469f81",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "6deb88e23100298841f7022f1ab81376862073293ab1edefe9e4b6ad32e45163",
"candidate_exists": true,
"candidate_html_sha256": "1dc4689947f8944bb6efe876172f7c8135f1cfab97a1ef3fd9c56ea4433bd735",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0004",
"revision_path": "adr/ops-warden-high-risk-read-boundary/v1/revisions/1/index.html",
"old_source_digest": "5db38dcb754af1ba639f4ceca056df842bc7b91fa48dd8bad21611aee29f682d",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "830b886a57017d5e5feb1e39289bc13eec389dacc2f0072812ff45e76f735590",
"candidate_exists": false,
"candidate_html_sha256": null,
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0005",
"revision_path": "adr/ops-warden-implement-narrowly/v1/revisions/1/index.html",
"old_source_digest": "31eafe4d8d9362a3446739d63c3af83fd9138cfdc6ad120086312a67dc0d27d0",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "4ea223b2f0105372a3d6868486480ce549926808658aaa1606dbde510f7ddb78",
"candidate_exists": true,
"candidate_html_sha256": "79ad8e9c2182eff9b20359d5701b7884d34fe346353ef2fad349cee5fda58045",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-001",
"revision_path": "adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-2/index.html",
"old_source_digest": "183023ee57bae9c29e726fec5ee0361633fe3a2b182436a57869ae4b2a27af24",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "c8f76626fcdaf5d777b966082620071c7b005ebe85c8dcef2f9c899521edf28e",
"candidate_exists": true,
"candidate_html_sha256": "c1d30034131f2fa0ed9c7335530ee442fdd7fc7a4e4c5bcdae31aae11f4fdc4f",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-002",
"revision_path": "adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html",
"old_source_digest": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "ea4eae05b62d50cd8204a47c1a4f3e3e0beda571880ed1de93ccbb17987d84aa",
"candidate_exists": true,
"candidate_html_sha256": "ea4eae05b62d50cd8204a47c1a4f3e3e0beda571880ed1de93ccbb17987d84aa",
"retained_byte_exact": true
},
{
"id": "CUST-ADR-003",
"revision_path": "adr/custodian-materialized-derived-state/v1/revisions/accepted-2/index.html",
"old_source_digest": "fcb49719e2b85b9120c0bd5bebd5e82748ca713f16b44951c028b60205514e2b",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "bca06c973dcf18494b7b57071b00af5f37b2eac231f30cfac771ad49698d09d0",
"candidate_exists": true,
"candidate_html_sha256": "4ce241adbfdcff1e15ea51746a4cc6660287b4a9429b805da96bfa0aecb8001f",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-004",
"revision_path": "adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html",
"old_source_digest": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "3db1b0f5c50543ff0fb022ea67f1d85b30f8ff691eaa1a2443220b7474b54de7",
"candidate_exists": true,
"candidate_html_sha256": "3db1b0f5c50543ff0fb022ea67f1d85b30f8ff691eaa1a2443220b7474b54de7",
"retained_byte_exact": true
},
{
"id": "CUST-ADR-005",
"revision_path": "adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html",
"old_source_digest": "13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "61804eedae4fbc82ddf86bd17a994f1e2291290d39af3d8a212b503eab0f359d",
"candidate_exists": true,
"candidate_html_sha256": "3b648cc46f33ec1078e42011bb4530833a5e4cbed7010fc2f4e5d34efb292958",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-006",
"revision_path": "adr/custodian-canon-federation/v1/revisions/accepted-1/index.html",
"old_source_digest": "a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "e10fdd888936a997cb91d6e5df8b801f2e7be1bbd170e82087faf1d37bf6d15b",
"candidate_exists": true,
"candidate_html_sha256": "992cebe70a9bfdc7e6c7e55c5d5c68d9a7ddef85784b9c0e70cbe66abf084b99",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-007",
"revision_path": "adr/custodian-workplan-identity/v1/revisions/accepted-2/index.html",
"old_source_digest": "1169f0c1f485a2bb7241a8f64f3167c060c04f83341b12586fd9be5c2b3693f8",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "bdf9f9522a48278f36cb86cd1f79765c97ab23b7abef94b5de2dada77dfc9e84",
"candidate_exists": true,
"candidate_html_sha256": "89de424e7e1f5e845e0d403a2fbdcde8857785168403e3ac1e2e91d612b24f6f",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-010",
"revision_path": "adr/custodian-hub-authority/v1/revisions/draft-2/index.html",
"old_source_digest": "5979da20799118259fc19246f51e8cc8f2c0c1be3d414318bd51d5a27d9ad565",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "83eeac4536266033882082332ffa150a8df69ad7b5f6bd8bd02d1ce587844ddd",
"candidate_exists": true,
"candidate_html_sha256": "412a30d486f3941df2a67367ee5facbfa4bef1884a932ab0565b566800e9154b",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-011",
"revision_path": "adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html",
"old_source_digest": "f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "b4b023c51266d152adc41d126566c55fdb6bf303047ca93d0585a4f60f8194c8",
"candidate_exists": true,
"candidate_html_sha256": "45b931e7ff0611c34dc011383446450e76108fee8a69818262e4f2f98d3972ed",
"retained_byte_exact": false
},
{
"id": "RPLAT-ADR-0001",
"revision_path": "adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html",
"old_source_digest": "63697581401b53a8437835c2bb8b40f8054cc40d0bc7a2972f83a4a10377f6ba",
"old_source_revision": "62423fd0925d75f5a2b27034044dc1080823d341",
"http_status": 200,
"served_html_sha256": "1fd07544a0a0f59087c5cbae908a2b883455e40b81bdb062305c33c646812708",
"candidate_exists": true,
"candidate_html_sha256": "8d9b19fb364f46edb78024170d5fa7334c1f8874e40badcf0ecf514ab560ee9f",
"retained_byte_exact": false
},
{
"id": "RPLAT-ADR-0002",
"revision_path": "adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html",
"old_source_digest": "cfc0ad202c2eeeefd963127ff1defa127c715c001ecc684ab8759733bd8fb9f8",
"old_source_revision": "62423fd0925d75f5a2b27034044dc1080823d341",
"http_status": 200,
"served_html_sha256": "6abef6687e89a35352aa283d930c2dfdfd566cd4881a1859fdc7597214431be8",
"candidate_exists": true,
"candidate_html_sha256": "a236962f1493b7bbd0679b0897c80e4a3db0e1ae85958c074065e2771985a820",
"retained_byte_exact": false
},
{
"id": "RPLAT-ADR-0003",
"revision_path": "adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html",
"old_source_digest": "9b12ab6aa0e6f9eba03465782c35d6ff4683b682191599e38f4f9614cde9fa1b",
"old_source_revision": "62423fd0925d75f5a2b27034044dc1080823d341",
"http_status": 200,
"served_html_sha256": "ac49cddc344d6937dfdb0ba89f15bcad96bca1c6c360b0cc1c1e5632c69560e5",
"candidate_exists": true,
"candidate_html_sha256": "41a11ad7c4450ced6831e7565daf6879263bed7b588cd1ef4fec75a2ef15e68c",
"retained_byte_exact": false
},
{
"id": "netkingdom-iam-profile-v0.3",
"revision_path": "standards/iam-profile/v0.3/revisions/accepted-1/index.html",
"old_source_digest": "6c47b596ea145fa197c9665081c84902482d90f5bb94d185c1223af65279be1d",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "b020f882093fbb0fa8290d4c09be665c3ed3b157522ec2f7231652e525019875",
"candidate_exists": true,
"candidate_html_sha256": "4413eb2f14bd8452019b600962fbc90838c1bd7aed6ef882800306a1e00394ec",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0006",
"revision_path": "adr/netkingdom-recursive-multi-tenant-identity-authorization/v1/revisions/1/index.html",
"old_source_digest": "e92a43649bb6e14e53ec62ecc819405bf3a44bda9557487f7177402f107bbd13",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "97070487ddd5d14bd85e68ae2e02f2512a3ad997352b384c0df344be48b3394c",
"candidate_exists": true,
"candidate_html_sha256": "bff0fd703bda76b2179e6a19d6bea0d345a90f5515f015db64f4b5aebf2a4b71",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0007",
"revision_path": "adr/netkingdom-security-orchestration-boundary/v1/revisions/1/index.html",
"old_source_digest": "b4fcff8448f07aca1fcb6908618bdb19f6c0e7dce25d4c5c8b85eec2f175233b",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "15056fedbd58e65e7c2b16cb5ea6d1c5f23cd23b1162c59e3e29500f8075ff3c",
"candidate_exists": true,
"candidate_html_sha256": "22555214d2bad8a972c6e1448de5621b4a639702f14ac234c33c1406b48dfdc9",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0008",
"revision_path": "adr/netkingdom-object-storage-sts-credential-vending/v1/revisions/1/index.html",
"old_source_digest": "f47276f4953f62b783397ee7fb1d3693da060103247e425a9a5b40d019fb4272",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "6a9a2b2249de33ff1342e027829f6cf2ce55dd067758c1cb63c8d2cd8e528f9b",
"candidate_exists": true,
"candidate_html_sha256": "2f23c90506a33941e510d9c1808c43d5e9ff989cfcec1b2c328a9f0aa9c8441b",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0010",
"revision_path": "adr/netkingdom-orchestration-dependency-intent/v1/revisions/1/index.html",
"old_source_digest": "b7c4f6a13f2f5add08bd03cb39c4f18ca25b202747dde883a309d1b3eaa1f571",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "be883fd0ad350fd0bb7991304fa29056485e1a9f95a61f8472e6b335261c4922",
"candidate_exists": true,
"candidate_html_sha256": "830595ef5922e2206cd654dd1c11d0889680a124132cf5264233bff59f1a8e07",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0011",
"revision_path": "adr/netkingdom-iam-profile-governance/v1/revisions/1/index.html",
"old_source_digest": "b5c7fd1e78026063b4a2ca4017202512d4f94ab5e12dc8498a34d04d3a48c7a9",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "3d75a914645d4c7bd2aaea7c9ebb3d1d22d491e1ebdd3cc84a8a3c7ad44ede1b",
"candidate_exists": true,
"candidate_html_sha256": "a9a3794ab00acaafdccf691623b23f8833eb4434922cdf16145876ea14cb41fa",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0012",
"revision_path": "adr/netkingdom-playbook-capability-ownership/v1/revisions/1/index.html",
"old_source_digest": "e269fabfc376f97f2a03ea66e34059d54016a445a7f30b351a6774b65c96c2ee",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "f64f93bcc0d527e5a782a599bf4e61374fcac9ded2c1a1e9003176de374a03fa",
"candidate_exists": true,
"candidate_html_sha256": "43e9f9dbd66f174bf8c3f27ef7257a825f3022aef12f6931be18deace5639645",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0013",
"revision_path": "adr/netkingdom-tenant-onboarding-taxonomy/v1/revisions/2/index.html",
"old_source_digest": "3a6030a8958176a902942ffd29154104ba3441a09d06edf3deaeadc7291ee0d4",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "c0b6997e551dba96b07eea3e78fca10f1760104494143606847fa74ccfdde53a",
"candidate_exists": true,
"candidate_html_sha256": "fb203f3ff1a51c0e798b0cdc1a85000ab575d677264a855f4fb5acacc6ba6cbe",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0014",
"revision_path": "adr/netkingdom-tenant-capability-ownership/v1/revisions/1/index.html",
"old_source_digest": "843f7a65f0fc145d08a73e364bc9a1dee0f7b8af934abf1584ee39dffa903ee0",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "6d2c05eb1fd48b27d2236ca7006e593bf8747df47e72952c947cbcda9ea0456f",
"candidate_exists": true,
"candidate_html_sha256": "7d8e851bd80e0b887d0d6e84b0ea2c82a78cb1f7a738e36f6a21b4f4557896f3",
"retained_byte_exact": false
},
{
"id": "NK-ADR-0015",
"revision_path": "adr/netkingdom-railiance-workload-packaging/v1/revisions/1/index.html",
"old_source_digest": "2000985ef211aeedd3656e15cedb289e655526c2dcc4a161a64ffc27f0289db1",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "826db77b95bccd3bbb169808aebab17f6a511405b03d4d05c04c79be2e49f3aa",
"candidate_exists": true,
"candidate_html_sha256": "602d683697bd6d29eef48b447e5d07f11432b90c03e33c6cdc1572b3bfff0eff",
"retained_byte_exact": false
},
{
"id": "RINFRA-ADR-0005",
"revision_path": "adr/railiance-k3s-api-tunnel-only/v1/revisions/accepted-1/index.html",
"old_source_digest": "4d93643d00d19b9d7c46843cd9be674c24e4cd613dc8e780c1684d97a6a9030a",
"old_source_revision": "f3e8bf3ab4b1dafa4d0b251b88ab2ef23a30c37b",
"http_status": 200,
"served_html_sha256": "ce55375217dd70e253f422ad6ed29006d99a64fec64ea16b2d6544ddd812654e",
"candidate_exists": true,
"candidate_html_sha256": "c9c7bd1061a2c2a8f37bcb126f19fcbc4bd8892bb64acef638b96efec0dc2a75",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-006",
"revision_path": "adr/activity-core-glas-profile-execution/v1/revisions/accepted-1/index.html",
"old_source_digest": "88041e9eb3a0f91fdd9da46f9813d7304b5ba58e62f9d28ea8f63c0a7b055b63",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "fd7e88b98f1da488e38e52cdbf6fc08cd3e2e5862c9ad7a00f56fcee1da77daf",
"candidate_exists": true,
"candidate_html_sha256": "d4fda9ccae399c8c9fe5c263aa0266ea13e3da6d43e59c00c6dbf84853168942",
"retained_byte_exact": false
},
{
"id": "ACT-ADR-007",
"revision_path": "adr/activity-core-bounded-operations/v1/revisions/accepted-1/index.html",
"old_source_digest": "75f42047b51293f7240f8a8c3ec02bf025a47fe6627f106fc4ef22fb1be7459d",
"old_source_revision": "b72fdb5452bff51a867a0316edb994723b35f268",
"http_status": 200,
"served_html_sha256": "2c41e74508a38ba0ab9e711c7fd4052d3cbb837a15b10f1e43ca11329d10058a",
"candidate_exists": true,
"candidate_html_sha256": "ab43dc9fc3e57da6f21ebb271ba1f5190fecb396724f51c55b492502dd2f4ec2",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0007",
"revision_path": "adr/ops-warden-build-stage-credential-disclosure/v1/revisions/1/index.html",
"old_source_digest": "868f953688988b11ce48f4141833bbca51abdb4e86d5b495a8a905002830d7b0",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "a6ad7d6fb4fadc21e6e6755225745733780b13755b28d4d706c614b9269003aa",
"candidate_exists": true,
"candidate_html_sha256": "22213fb8cb2bfe3ed79bf3b47733bd005338b17c88fca4c0bf08391d30ad6415",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0008",
"revision_path": "adr/ops-warden-grade-disclosure-path/v1/revisions/1/index.html",
"old_source_digest": "2e22863ba592802cceb40b32d395168b42ace747741f5188307505eaa89ff764",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "b0129596a06884b2d34a74adfac4b08e3bd2e1af6ab8856d5bd4d50b4496a66c",
"candidate_exists": true,
"candidate_html_sha256": "1c462afdcdd736006fb7f484b381ce24c898282cf70353e0269a29d1713bbad9",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0009",
"revision_path": "adr/ops-warden-security-zones-consumer/v1/revisions/1/index.html",
"old_source_digest": "73fff22177b4bec2c56ff737e06e4225eb02d39669be3ea1b723906245f878b8",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "533a14b26081a1d88fa9c2fb0c7ea9bfde542e452cc989a68b5da33b0e024510",
"candidate_exists": true,
"candidate_html_sha256": "4ce260d625d1a0e867b740da6b859743e7ae5863522a95c1be823699ea851a43",
"retained_byte_exact": false
},
{
"id": "ops-warden-adr-0010",
"revision_path": "adr/ops-warden-staff-layer/v1/revisions/1/index.html",
"old_source_digest": "064455bcb2870abf8e243f5a8c154e50bfc1c537cfba7996a792f9e314dd78ae",
"old_source_revision": "8afcc9c32170d76f6d5d02ea153967ed5c6fc4d5",
"http_status": 200,
"served_html_sha256": "91727be45934f64eb5f98cb995fcea9f76bb219e1c6bec197e8937f8ea82f6b1",
"candidate_exists": true,
"candidate_html_sha256": "e94876e29a3c787949ba17f2c1717ce6cc3ec78b52a560174bfda39692f6176d",
"retained_byte_exact": false
},
{
"id": "RMASTER-ADR-0009",
"revision_path": "adr/railiance-netkingdom-security-layer-interaction/v1/revisions/accepted-1/index.html",
"old_source_digest": "c2f81c9718715fc08ea7a2e3021d0d3159958ace23b60a16430020637b9f57f2",
"old_source_revision": "5ffd7d1b40d56249f490a318e728047fd3517c4c",
"http_status": 200,
"served_html_sha256": "0a91e1d4fac1ebda5dc383c9f750d307dc29ef81789ac26d3c2659d58666b897",
"candidate_exists": true,
"candidate_html_sha256": "243ce8e88610ef88056d47c2bd5ee92b535b743a30ec1590a9aead13895ff11b",
"retained_byte_exact": false
},
{
"id": "CUST-ADR-012",
"revision_path": "adr/custodian-projection-source-overlay/v1/revisions/1.0/index.html",
"old_source_digest": "b5e8582459f546ae789ad5fd62f458454aa19997b520e32b6b9f792d6af55987",
"old_source_revision": "f9435cd605cc5b3cb0f2e957ce6287d9f3129aac",
"http_status": 200,
"served_html_sha256": "63488f677010582fcbdd157fd6c10b2fa6e765db3c605605d1177e57e231f4ff",
"candidate_exists": true,
"candidate_html_sha256": "00bd1b554e41605c361759e3bea8c74ddd336c54a3ecadbc127dac86620d88ef",
"retained_byte_exact": false
},
{
"id": "netkingdom-posture-feedback-v0.1",
"revision_path": "standards/posture-feedback/v0.1/revisions/0.1/index.html",
"old_source_digest": "dd2628b9f0c2a662ac44af22657d91918da228f307ebc7ceb09fc856162985db",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "54c14e25e018593d83df5f4b69a8316c0f1082460f94e5a0fbc80ecf61089d3b",
"candidate_exists": true,
"candidate_html_sha256": "7ad388d0f4b320db48366f1ff77a476fb5276e44911b3d1b10747e955eae79c0",
"retained_byte_exact": false
},
{
"id": "netkingdom-security-layer-model-v0.7",
"revision_path": "standards/security-layer-model/v0.7/revisions/0.7/index.html",
"old_source_digest": "8155e7b123be1e84377d8278525b1bad8961007b6bb8ff012dd01ba24ff8065b",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "7d7a38a8c3b9fff65b46280fcd5723eff77dc9d0784f871bb35f718bc4e8c0e7",
"candidate_exists": true,
"candidate_html_sha256": "7d7a38a8c3b9fff65b46280fcd5723eff77dc9d0784f871bb35f718bc4e8c0e7",
"retained_byte_exact": true
},
{
"id": "netkingdom-security-scenario-composition-v0.1",
"revision_path": "standards/security-scenario-composition/v0.1/revisions/0.1/index.html",
"old_source_digest": "17b715d78e04470a0f83b8bc8c7313ab16e13e9e741d5ec445172d9008fce937",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "2e401b2c8948ca983e7cd364faeea28b1d0bb6963a156e9b8e0e0a04961bf1c9",
"candidate_exists": true,
"candidate_html_sha256": "04d30ddc03b140d9972be5428533c66df9a197cfee0b2e0d286957c76c5a39fd",
"retained_byte_exact": false
},
{
"id": "netkingdom-security-zones-v0.1",
"revision_path": "standards/security-zones/v0.1/revisions/0.1/index.html",
"old_source_digest": "32e71e9c0d6946bb14099eb66193822da26f199de0e11d8488464207f3bd9906",
"old_source_revision": "9781102e2971d762ae42fdd5085a6647afd1cd66",
"http_status": 200,
"served_html_sha256": "b8c7ce8198edbb637657ed4194356453aa3c3794c5592ebcee4c157a68a9a2b1",
"candidate_exists": true,
"candidate_html_sha256": "d6d4880830a57c138ef76cd0eb7e19b12bf65ba44ff069c30afc4914d71a8c9e",
"retained_byte_exact": false
},
{
"id": "RISK-F-0001",
"revision_path": "findings/flex-auth-unauthenticated-check/v1/revisions/published-1/index.html",
"old_source_digest": "b2d1d0c526d5c9b5729b8353877bb9f29096667145f1498cfde73c9711206fda",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "adfc18f51f4defb529c5529669eb33bf283a4d9c6da78f26bc8cd73cddad85b7",
"candidate_exists": true,
"candidate_html_sha256": "87d59a33ce04acafd52b90e58adeaf067996b18e13405aa6e3f3f329c4425c0d",
"retained_byte_exact": false
},
{
"id": "RISK-F-0008",
"revision_path": "findings/audit-retention-legal-basis/v1/revisions/published-1/index.html",
"old_source_digest": "8bf47414a9f958afb57649f087a2617f91a8f2aeaa4f34d04d8fb3a0f453e840",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "c6aee9543f8ef21964b8fe0cd966dfc4ac49b17958d258bef6b580210be08656",
"candidate_exists": true,
"candidate_html_sha256": "d15c81268f430a502be843e6a24ab69a9ddd5ace4280c49b499efaa5f0f84217",
"retained_byte_exact": false
},
{
"id": "RISK-METHOD-SEVERITY",
"revision_path": "methods/risk-severity/v1/revisions/adopted-1/index.html",
"old_source_digest": "f064c591aeef9425bbfbd5fa2aae659abb0ef83b8586848300077f41dd4ffaab",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "8073cd40f67197fe093ce1173bcc0a9ce1e7170c157dd88726997fff1cb791e6",
"candidate_exists": true,
"candidate_html_sha256": "5adcb8d703a836011dbd9db475318fcbb9c2dc4d4a2d8b88be885fdd1f300958",
"retained_byte_exact": false
},
{
"id": "RISK-METHOD-DISCLOSURE",
"revision_path": "methods/risk-disclosure/v1/revisions/adopted-1/index.html",
"old_source_digest": "bd825a87736c8fb019d4224c3ef4fe3882b8f3028035225b4b8ff8cad62fdb81",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "f0e2eaabe65543725f54b4701ea3a1efdbc936006ee9d309650feb21cbc593ca",
"candidate_exists": true,
"candidate_html_sha256": "444b7dfe892602458ffeedaaf90df4d41b11bdd936ee77f0db487d38d858f414",
"retained_byte_exact": false
},
{
"id": "RISK-METHOD-REVIEW",
"revision_path": "methods/risk-review/v1/revisions/adopted-1/index.html",
"old_source_digest": "8f873d105bf6bd711a1a15ebd739b2abe97365b4e854be9d1c82e3ff3b162cfd",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "64e707283c19bc46bf41b03c266ee6b625824696dcfc35dc83333b43e1662f8e",
"candidate_exists": true,
"candidate_html_sha256": "9625ea73467252e6f947eaf26e4c72c5ebd60e1a152614b049a54f96b49c1af1",
"retained_byte_exact": false
},
{
"id": "RISK-METHOD-VERIFICATION",
"revision_path": "methods/risk-verification/v1/revisions/adopted-1/index.html",
"old_source_digest": "562b6eb3031ffe35e712c5e11e35aae23ce84a90e0090438dc89513f9685052b",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "e6219a88daef48fd715d7c8092d2db6e5eda8f4d44dcbf9a0b7d975227237b92",
"candidate_exists": true,
"candidate_html_sha256": "88cc89b0cdcfd3b06b9ce18255046e68eee26a7c4ee148cd613ccf7707ef2b71",
"retained_byte_exact": false
},
{
"id": "RISK-METHOD-DEPENDENCIES",
"revision_path": "methods/risk-dependencies/v1/revisions/adopted-1/index.html",
"old_source_digest": "a5e7b42043b0bb366add9bbc5f606e134ef5b0454532480203d5d87099296240",
"old_source_revision": "d65aaf7484cf8d01510fa6ae0ee267f434549ff6",
"http_status": 200,
"served_html_sha256": "24f29c04622f13156a1c6d69c0f98843e00d2d12cdbf506bf6a260d67b00d4e4",
"candidate_exists": true,
"candidate_html_sha256": "e249ffb8ccdeeef49ebf1b0e2d48b1c4a9a169574be37d6344aae2b770066f83",
"retained_byte_exact": false
}
]
}

119
docs/evidence/2026-10-11-hosting-preparation/live-baseline.json Normal file
View file

@ -0,0 +1,119 @@
{
"captured_at": "2026-10-11T00:16:33.889261+00:00",
"record_type": "read-only-pre-adoption",
"cluster_mutated": false,
"secret_values_observed": false,
"nodes": [
{
"name": "239.62.205.92.host.secureserver.net",
"addresses": [
{
"address": "92.205.62.239",
"type": "InternalIP"
},
{
"address": "2a00:1169:111:6d70::",
"type": "InternalIP"
},
{
"address": "239.62.205.92.host.secureserver.net",
"type": "Hostname"
}
],
"cpu_allocatable": "4"
}
],
"applications": [
{
"name": "railiance-apps-root",
"target_revision": "main",
"namespace": "argocd",
"health": "Healthy",
"sync": "OutOfSync"
}
],
"deployment": {
"image": "forgejo.coulomb.social/coulomb/policy-nexus@sha256:23df0ab3dc80d2a92b8058eeb572c222ceb05d17434f173a24142b2450ab3cea",
"generation": 8,
"ready": 1,
"observed_generation": 8,
"replicas": 1,
"strategy": {
"rollingUpdate": {
"maxSurge": 1,
"maxUnavailable": 0
},
"type": "RollingUpdate"
},
"resources": {
"limits": {
"cpu": "100m",
"memory": "64Mi"
},
"requests": {
"cpu": "10m",
"memory": "32Mi"
}
},
"release_metadata": {
"meta.helm.sh/release-name": "policy-nexus",
"meta.helm.sh/release-namespace": "policy-nexus",
"policy.coulomb.social/publication-manifest-digest": "09f9f7edcc46e31d4b3f73b62d16fdf17808ae1f893f312242b7b9e2037319e0",
"policy.coulomb.social/source-inventory-digest": "9658803bc79d19cef1a9c842d1a8c161f1998d59ce6e4bc4df3c88aba2f4c9c4",
"policy.coulomb.social/source-set-digest": "03f04902a3559099433795453829d75470aa1490dd243b42e7703b6eab87772f",
"argocd.argoproj.io/tracking-id": null
},
"managed_by": "Helm"
},
"helm_history": [
{
"revision": 1,
"status": "superseded",
"chart": "policy-nexus-0.1.0"
},
{
"revision": 2,
"status": "superseded",
"chart": "policy-nexus-0.2.0"
},
{
"revision": 3,
"status": "superseded",
"chart": "policy-nexus-0.1.0"
},
{
"revision": 4,
"status": "superseded",
"chart": "policy-nexus-0.2.0"
},
{
"revision": 5,
"status": "superseded",
"chart": "policy-nexus-0.2.0"
},
{
"revision": 6,
"status": "superseded",
"chart": "policy-nexus-0.2.0"
},
{
"revision": 7,
"status": "superseded",
"chart": "policy-nexus-0.2.0"
},
{
"revision": 8,
"status": "deployed",
"chart": "policy-nexus-0.2.0"
}
],
"helm_release_inputs": {
"image": {
"digest": "sha256:23df0ab3dc80d2a92b8058eeb572c222ceb05d17434f173a24142b2450ab3cea",
"repository": "forgejo.coulomb.social/coulomb/policy-nexus"
},
"publicationManifestDigest": "09f9f7edcc46e31d4b3f73b62d16fdf17808ae1f893f312242b7b9e2037319e0",
"sourceInventoryDigest": "9658803bc79d19cef1a9c842d1a8c161f1998d59ce6e4bc4df3c88aba2f4c9c4",
"sourceSetDigest": "03f04902a3559099433795453829d75470aa1490dd243b42e7703b6eab87772f"
}
}

1230
docs/evidence/2026-10-11-hosting-preparation/public-baseline-manifest.json Normal file
View file

File diff suppressed because it is too large Load diff

555
docs/evidence/2026-10-11-hosting-preparation/source-exports.json Normal file
View file

@ -0,0 +1,555 @@
[
{
"repo": "net-kingdom",
"path": "canon/standards/iam-profile_v0.3.md",
"sha256": "6c47b596ea145fa197c9665081c84902482d90f5bb94d185c1223af65279be1d",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/posture-feedback_v0.1.md",
"sha256": "dd2628b9f0c2a662ac44af22657d91918da228f307ebc7ceb09fc856162985db",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/security-layer-model_v0.7.md",
"sha256": "8155e7b123be1e84377d8278525b1bad8961007b6bb8ff012dd01ba24ff8065b",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/security-layer-model_v0.8.md",
"sha256": "3d8298560069ef471fba28d2b1245fb2309328f231dad1a667cdf0ce5a5a7c8b",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/security-scenario-composition_v0.1.md",
"sha256": "17b715d78e04470a0f83b8bc8c7313ab16e13e9e741d5ec445172d9008fce937",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/security-zones_v0.1.md",
"sha256": "32e71e9c0d6946bb14099eb66193822da26f199de0e11d8488464207f3bd9906",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "canon/standards/tenancy-posture_v0.1.md",
"sha256": "38e7500a487cf65a5c7cf479852e4fa2cbcf0915e6d7218bcbaa96dae1f2e6ce",
"kind": "reviewed-stage",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md",
"sha256": "e92a43649bb6e14e53ec62ecc819405bf3a44bda9557487f7177402f107bbd13",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0007-security-orchestration-boundary.md",
"sha256": "b4fcff8448f07aca1fcb6908618bdb19f6c0e7dce25d4c5c8b85eec2f175233b",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0008-object-storage-sts-credential-vending.md",
"sha256": "f47276f4953f62b783397ee7fb1d3693da060103247e425a9a5b40d019fb4272",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md",
"sha256": "b7c4f6a13f2f5add08bd03cb39c4f18ca25b202747dde883a309d1b3eaa1f571",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md",
"sha256": "b5c7fd1e78026063b4a2ca4017202512d4f94ab5e12dc8498a34d04d3a48c7a9",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0012-playbook-capability-contract-ownership.md",
"sha256": "e269fabfc376f97f2a03ea66e34059d54016a445a7f30b351a6774b65c96c2ee",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md",
"sha256": "3a6030a8958176a902942ffd29154104ba3441a09d06edf3deaeadc7291ee0d4",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md",
"sha256": "843f7a65f0fc145d08a73e364bc9a1dee0f7b8af934abf1584ee39dffa903ee0",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md",
"sha256": "2000985ef211aeedd3656e15cedb289e655526c2dcc4a161a64ffc27f0289db1",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/architecture/net-kingdom_v0.1.md",
"sha256": "db86e509552e92e3e235799dabe08a0c93506e7ef8402cbfbae01b7a1f526d81",
"kind": "reviewed-stage",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/evidence/2026-10-11-layer-v07-immutable-publication/security-layer-model-v0.7.html",
"sha256": "7d7a38a8c3b9fff65b46280fcd5723eff77dc9d0784f871bb35f718bc4e8c0e7",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "net-kingdom",
"path": "docs/evidence/2026-10-11-layer-v07-immutable-publication/security-layer-model-v0.7.md",
"sha256": "8155e7b123be1e84377d8278525b1bad8961007b6bb8ff012dd01ba24ff8065b",
"kind": "clean-head",
"source_head": "f4436dadd5adbedb8b74114a76e8c8ab8ae91b1d"
},
{
"repo": "policy-nexus",
"path": "docs/adr/ADR-0001-addressing-and-permanence.md",
"sha256": "a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be",
"kind": "clean-head",
"source_head": "6d2c7eef779c823731e6f793b3adcf44afddd183"
},
{
"repo": "policy-nexus",
"path": "docs/architecture/policy-nexus_v0.1.md",
"sha256": "179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480",
"kind": "clean-head",
"source_head": "6d2c7eef779c823731e6f793b3adcf44afddd183"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0001-repository-prefix-architecture.md",
"sha256": "b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md",
"sha256": "7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0003-rapp-first-wave-selection.md",
"sha256": "28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0004-first-wave-reef-rollout.md",
"sha256": "36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0005-derived-rail-composition.md",
"sha256": "e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0006-reef-production-admission.md",
"sha256": "5d0454384e1a3f31939aaa4e3d4225ede73c3669a2d86b15efb4b56803e01690",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0007-rapp-declaration-contract.md",
"sha256": "b1185388ded53188dc624fbda9bee517dd3ac80b35e881cd4a7962531bec52ff",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0008-private-by-default-exposure.md",
"sha256": "bd97ec8ee663bb416fae53c8cfe29c7066e4fd3a51a5bc364895297e6eb994b7",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/adr/ADR-0009-netkingdom-security-layer-interaction.md",
"sha256": "c2f81c9718715fc08ea7a2e3021d0d3159958ace23b60a16430020637b9f57f2",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "railiance-master",
"path": "docs/architecture/railiance_v0.1.md",
"sha256": "77de319978dfad02f40658bbeb96db46b246a46f1abd6a45f5b1269563de5568",
"kind": "clean-head",
"source_head": "078515b5adc7ac742ffad1b20577fcf88400acbb"
},
{
"repo": "state-hub",
"path": "docs/architecture/state-hub_v0.1.md",
"sha256": "e7104b2182612efe90c9a12168757506402490229814d454e94917ae62d2bfac",
"kind": "clean-head",
"source_head": "cccc27ce44928e579627aa86ccee38ae4fb1ca10"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md",
"sha256": "183023ee57bae9c29e726fec5ee0361633fe3a2b182436a57869ae4b2a27af24",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-002-custodian-agent-runtime-design.md",
"sha256": "b860b02b1e8f47b914d41c6ecf67f451e86326ed51c7c53dcc6b7870fc889e42",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-003-materialized-derived-state.md",
"sha256": "fcb49719e2b85b9120c0bd5bebd5e82748ca713f16b44951c028b60205514e2b",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-004-connectivity-first-network-posture.md",
"sha256": "4f9978b40c104600c0ccb981a8ee52376a5d3003da4786752029af524b7dede7",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md",
"sha256": "13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-006-canon-federation-concept-ownership.md",
"sha256": "a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md",
"sha256": "1169f0c1f485a2bb7241a8f64f3167c060c04f83341b12586fd9be5c2b3693f8",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md",
"sha256": "5979da20799118259fc19246f51e8cc8f2c0c1be3d414318bd51d5a27d9ad565",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md",
"sha256": "f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/adr-012-projection-source-and-preliminary-overlay.md",
"sha256": "b5e8582459f546ae789ad5fd62f458454aa19997b520e32b6b9f792d6af55987",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/architecture/coulomb-estate_v0.1.md",
"sha256": "3b4f93acdedc6f6d1a1c737c3327d9d55061506c5a879be09e6b0a2ea7f5f9bc",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/standards/autonomy-lanes_v0.1.md",
"sha256": "106cb0c99f73983199c9f1d8491143aa2a2eb41ee450a02ec7968d3763f30399",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/standards/contribution-convention_v0.1.md",
"sha256": "6dfc1d7b2b82ab18228a84660c1c7dff607aad1d9da37ac12084cdd2ab8ae112",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/standards/project-repository-flavor_v0.1.md",
"sha256": "61889b2f18a82a08b66ef90d758efe5c028a4f52aced1721a23e69c6f24a8224",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/standards/work-record-types_v0.1.md",
"sha256": "ab5d9de07fd899fc5334c9912571ed3d6748f2ee4bd0c9f81c5606c4727024d1",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "canon/standards/workplan-terminology-fleet_v0.1.md",
"sha256": "431d36f40d90bcd40a640c16b583095ad35757675f78ddcea382e6f1b2e23710",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "docs/evidence/2026-10-11-adr-currency-review/adr-002-accepted-1.html",
"sha256": "ea4eae05b62d50cd8204a47c1a4f3e3e0beda571880ed1de93ccbb17987d84aa",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "docs/evidence/2026-10-11-adr-currency-review/adr-002-accepted-1.md",
"sha256": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "docs/evidence/2026-10-11-adr-currency-review/adr-004-accepted-1.html",
"sha256": "3db1b0f5c50543ff0fb022ea67f1d85b30f8ff691eaa1a2443220b7474b54de7",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "the-custodian",
"path": "docs/evidence/2026-10-11-adr-currency-review/adr-004-accepted-1.md",
"sha256": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557",
"kind": "clean-head",
"source_head": "dcdec162d61398f0def4990957455d45a74a1b01"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-001-event-bridge-architecture.md",
"sha256": "57ecf490465e71cc4970133301cc315748b1d6ee65caac3690472ff88f3aab06",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-002-definition-format.md",
"sha256": "1670e1616094bc6f2c0c7d47b2e019c02d5870b22b564ef83afa24caff197bab",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-003-rule-instruction-model.md",
"sha256": "f1017730074727bcb0c68309c445ffb219ef647c8c5604adbfff76c4aa3f9d66",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-004-producer-trust-boundary.md",
"sha256": "92da58f58ee3dbb62233161a0fc0b7780920f81ec37fdd40d476be354f24e0eb",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-005-ops-runs-vs-dev-work-records.md",
"sha256": "984208262a0f6b67a6dc94cb078ebd0bcddc95d0b21a694d7e207677c10b471f",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-006-glas-profile-execution.md",
"sha256": "88041e9eb3a0f91fdd9da46f9813d7304b5ba58e62f9d28ea8f63c0a7b055b63",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "activity-core",
"path": "docs/adr/adr-007-bounded-operations.md",
"sha256": "75f42047b51293f7240f8a8c3ec02bf025a47fe6627f106fc4ef22fb1be7459d",
"kind": "clean-head",
"source_head": "fd84f2b6518ff17509930499099ec2a6692d088c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0001-catalog-is-a-pointer-layer.md",
"sha256": "7df0bb364276e382cbee9383e7e67d399b0ac1b0353246e0ab323e629e732a6d",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0002-conduit-not-broker.md",
"sha256": "7dcc31732d774ddf2c98636b69ee12e2d74034836ed0def81b7e06461309b53a",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0003-cover-gaps-never-silently-own-them.md",
"sha256": "45b47c02afa575fbfe5be980e426c331a1d99bb9cd9c7a8de80bf8e319469f81",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0004-agent-read-boundary-on-high-risk-lanes.md",
"sha256": "e379f47fb56214ff0cc6abcddaaad33c6969cf386e11abeed105b4fef953c5a0",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0005-implement-narrowly-route-broadly.md",
"sha256": "31eafe4d8d9362a3446739d63c3af83fd9138cfdc6ad120086312a67dc0d27d0",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0007-build-stage-stops-at-credential-disclosure.md",
"sha256": "868f953688988b11ce48f4141833bbca51abdb4e86d5b495a8a905002830d7b0",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0008-grade-the-path-not-the-field.md",
"sha256": "2e22863ba592802cceb40b32d395168b42ace747741f5188307505eaa89ff764",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0009-adopt-security-zones-as-a-consumer.md",
"sha256": "73fff22177b4bec2c56ff737e06e4225eb02d39669be3ea1b723906245f878b8",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "ops-warden",
"path": "docs/adr/ADR-0010-ops-warden-is-staff.md",
"sha256": "064455bcb2870abf8e243f5a8c154e50bfc1c537cfba7996a792f9e314dd78ae",
"kind": "clean-head",
"source_head": "eaabb4216186f4fee2d830376a381740b140087c"
},
{
"repo": "railiance-platform",
"path": "docs/adr/ADR-0001-s3-platform-service-boundary.md",
"sha256": "63697581401b53a8437835c2bb8b40f8054cc40d0bc7a2972f83a4a10377f6ba",
"kind": "clean-head",
"source_head": "8c152d012a44664f51969f2cb3456e28a3a0e5ff"
},
{
"repo": "railiance-platform",
"path": "docs/adr/ADR-0002-placement-policy-ownership.md",
"sha256": "cfc0ad202c2eeeefd963127ff1defa127c715c001ecc684ab8759733bd8fb9f8",
"kind": "clean-head",
"source_head": "8c152d012a44664f51969f2cb3456e28a3a0e5ff"
},
{
"repo": "railiance-platform",
"path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md",
"sha256": "9b12ab6aa0e6f9eba03465782c35d6ff4683b682191599e38f4f9614cde9fa1b",
"kind": "clean-head",
"source_head": "8c152d012a44664f51969f2cb3456e28a3a0e5ff"
},
{
"repo": "railiance-infra",
"path": "docs/adr/ADR-005-k3s-api-tunnel-only.md",
"sha256": "4d93643d00d19b9d7c46843cd9be674c24e4cd613dc8e780c1684d97a6a9030a",
"kind": "clean-head",
"source_head": "ef64e324b61e9aa9b9ed03aad7dd2101915057ca"
},
{
"repo": "risk-nexus",
"path": "docs/method/dependencies.md",
"sha256": "a5e7b42043b0bb366add9bbc5f606e134ef5b0454532480203d5d87099296240",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "docs/method/disclosure.md",
"sha256": "bd825a87736c8fb019d4224c3ef4fe3882b8f3028035225b4b8ff8cad62fdb81",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "docs/method/review.md",
"sha256": "8f873d105bf6bd711a1a15ebd739b2abe97365b4e854be9d1c82e3ff3b162cfd",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "docs/method/severity.md",
"sha256": "f064c591aeef9425bbfbd5fa2aae659abb0ef83b8586848300077f41dd4ffaab",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "docs/method/verification.md",
"sha256": "562b6eb3031ffe35e712c5e11e35aae23ce84a90e0090438dc89513f9685052b",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "findings/RISK-F-0001-flex-auth-unauthenticated-check.md",
"sha256": "b2d1d0c526d5c9b5729b8353877bb9f29096667145f1498cfde73c9711206fda",
"kind": "clean-head",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
},
{
"repo": "risk-nexus",
"path": "findings/RISK-F-0008-audit-retention-legal-basis-assumed.md",
"sha256": "b1b6ea241f82be48df427af915227dad2fe9a90b970b8a03fb4b39a0ab3a821c",
"kind": "reviewed-stage",
"source_head": "7095f328e6639fd0033c90296ebc73e8acb76c9c"
}
]

76
docs/evidence/2026-10-11-hosting-preparation/transition-failure.txt Normal file
View file

@ -0,0 +1,76 @@
RISK-F-0008: unreviewed semantic change
RMASTER-ADR-0006: unreviewed semantic change
canon-work-record-types: unreviewed semantic change
canon-workplan-terminology-fleet: unreviewed semantic change
net-kingdom-architecture: unreviewed semantic change
netkingdom-tenancy-posture: unreviewed semantic change
ops-warden-adr-0004: unreviewed semantic change
netkingdom-tenancy-posture: old immutable bytes changed
canon-autonomy-lanes: old immutable bytes changed
canon-contrib-convention: old immutable bytes changed
canon-project-repository-flavor: old immutable bytes changed
canon-work-record-types: old immutable revision absent or unsafe
canon-workplan-terminology-fleet: old immutable revision absent or unsafe
coulomb-estate-architecture: old immutable bytes changed
railiance-architecture: old immutable bytes changed
net-kingdom-architecture: old immutable bytes changed
state-hub-architecture: old immutable bytes changed
policy-nexus-architecture: old immutable bytes changed
policy-nexus-adr-0001: old immutable bytes changed
RMASTER-ADR-0001: old immutable bytes changed
RMASTER-ADR-0002: old immutable bytes changed
RMASTER-ADR-0003: old immutable bytes changed
RMASTER-ADR-0004: old immutable bytes changed
RMASTER-ADR-0005: old immutable bytes changed
RMASTER-ADR-0006: old immutable revision absent or unsafe
RMASTER-ADR-0007: old immutable bytes changed
RMASTER-ADR-0008: old immutable bytes changed
ACT-ADR-001: old immutable bytes changed
ACT-ADR-002: old immutable bytes changed
ACT-ADR-003: old immutable bytes changed
ACT-ADR-004: old immutable bytes changed
ACT-ADR-005: old immutable bytes changed
ops-warden-adr-0001: old immutable bytes changed
ops-warden-adr-0002: old immutable bytes changed
ops-warden-adr-0003: old immutable bytes changed
ops-warden-adr-0004: old immutable revision absent or unsafe
ops-warden-adr-0005: old immutable bytes changed
CUST-ADR-001: old immutable bytes changed
CUST-ADR-003: old immutable bytes changed
CUST-ADR-005: old immutable bytes changed
CUST-ADR-006: old immutable bytes changed
CUST-ADR-007: old immutable bytes changed
CUST-ADR-010: old immutable bytes changed
CUST-ADR-011: old immutable bytes changed
RPLAT-ADR-0001: old immutable bytes changed
RPLAT-ADR-0002: old immutable bytes changed
RPLAT-ADR-0003: old immutable bytes changed
netkingdom-iam-profile-v0.3: old immutable bytes changed
NK-ADR-0006: old immutable bytes changed
NK-ADR-0007: old immutable bytes changed
NK-ADR-0008: old immutable bytes changed
NK-ADR-0010: old immutable bytes changed
NK-ADR-0011: old immutable bytes changed
NK-ADR-0012: old immutable bytes changed
NK-ADR-0013: old immutable bytes changed
NK-ADR-0014: old immutable bytes changed
NK-ADR-0015: old immutable bytes changed
RINFRA-ADR-0005: old immutable bytes changed
ACT-ADR-006: old immutable bytes changed
ACT-ADR-007: old immutable bytes changed
ops-warden-adr-0007: old immutable bytes changed
ops-warden-adr-0008: old immutable bytes changed
ops-warden-adr-0009: old immutable bytes changed
ops-warden-adr-0010: old immutable bytes changed
RMASTER-ADR-0009: old immutable bytes changed
CUST-ADR-012: old immutable bytes changed
netkingdom-posture-feedback-v0.1: old immutable bytes changed
netkingdom-security-scenario-composition-v0.1: old immutable bytes changed
netkingdom-security-zones-v0.1: old immutable bytes changed
RISK-F-0001: old immutable bytes changed
RISK-F-0008: old immutable bytes changed
RISK-METHOD-SEVERITY: old immutable bytes changed
RISK-METHOD-DISCLOSURE: old immutable bytes changed
RISK-METHOD-REVIEW: old immutable bytes changed
RISK-METHOD-VERIFICATION: old immutable bytes changed
RISK-METHOD-DEPENDENCIES: old immutable bytes changed

9
docs/evidence/2026-10-11-served-publication-history/README.md Normal file
View file

@ -0,0 +1,9 @@
# Observed publisher history, 2026-10-11
This is a publisher receipt of bytes actually delivered by policy.coulomb.social, not a replacement for owner canon or a new acceptance decision. All 72 current immutable revision URLs from the delivered publication manifest returned HTTP200. Their HTML is preserved under `pages/`; original owner Markdown is separately retained under `sources/`. The receipt binds both byte hashes, original owner repository/path, the exact source commit embedded in the served HTML, and delivered immutable URL/revision. Original Markdown was obtained using `git show <exact HTML provenance commit>:<owner source path>` for each record; every one of 72 source hashes matched both the served HTML and delivered manifest.
The delivered manifest's current source revision may differ from immutable HTML's original source revision when a later owner HEAD renders the canonical URL. The receipt records both; it does not rewrite historical provenance to a current HEAD. The archived Markdown is historical evidence, not the current owner source selected for canonical publication. New builds verify receipt/manifest/source/HTML hashes, identity/revision and provenance, then restore exact old pages before rendering current canonical content. A changed owner source under the same revision refuses; a new current revision retains the old path.
Existing NetKingdom v0.7 and Custodian ADR002/004 owner archival snapshots remain authoritative owner evidence and are retained. Their rendered bytes agree with the publisher receipt. No owner source decision, status, authorship, original acceptance date, enforcement grant or live hosting state is changed by importing this archive.
Limit: this capture covers every current immutable URL in the delivered 72-document manifest. It does not assert that no earlier URL absent from that manifest has ever existed. Additional already served historical paths must be imported as additional reviewed receipts when identified; existing explicit owner historical revisions are preserved independently. This archive is publicly served policy content and exact original public source, not credentials or customer data.

247
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-001.html Normal file
View file

@ -0,0 +1,247 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="b72fdb5452bff51a867a0316edb994723b35f268">
<meta name="policy-source-digest" content="57ecf490465e71cc4970133301cc315748b1d6ee65caac3690472ff88f3aab06">
<title>Activity-Core as Coulomb Org Event Bridge</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-001</span> <span class="stat">accepted · accepted-2</span> <span>activity-core</span> <span>reviewed 2026-05-14</span><span>generated from canonical source — do not edit</span></div><h1>Activity-Core as Coulomb Org Event Bridge</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-001-event-bridge-architecture.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><p class="sub">Review due: 2026-11-14</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#trigger-types"><span class="n">·</span>Trigger types</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The Coulomb organization's set of repositories, services, and deployments is growing beyond what a single person can coordinate manually. The state hub tracks cross-domain state but has no mechanism to automatically respond to it. Recurring maintenance (dependency scans, SBOM staleness checks, consistency audits) is implemented as bespoke cron jobs baked into individual services — scattered, hard to audit, and impossible to govern from a single vantage point.</p>
<p>Three forces drive the need for a dedicated orchestration layer:</p>
<ol><li><strong>Scale</strong>: as the repo count grows, manual coordination becomes the bottleneck.</li><li><strong>Reactivity</strong>: org-level events (new repo registered, CVE published, deployment completed) should trigger coordinated responses without human intervention.</li><li><strong>Separation of concerns</strong>: the state hub is a read model and should remain one. It must not accumulate automation logic to avoid becoming a God object.</li></ol>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>activity-core is the org-wide Event Bridge for the Coulomb organization.</strong></p>
<p>Its responsibility is exactly three things:</p>
<ol><li><strong>Receive events</strong> — time-based (cron, one-off scheduled) and domain events (NATS, Gitea webhooks, state hub lifecycle signals).</li><li><strong>Evaluate rules and instructions</strong> — given event payload and resolved context, determine what work must be created.</li><li><strong>Emit task sets</strong> — publish structured task creation requests to issue-core.</li></ol>
<p>It does not execute work. It does not track task lifecycle. It does not manage projects.</p>
<h3>Boundary rules</h3>
<div class="scroll"><table><thead><tr><th>Concern</th><th>Owner</th></tr></thead><tbody><tr><td>Cross-org task scheduling and reactive automation</td><td><strong>activity-core</strong></td></tr><tr><td>Task lifecycle (create, assign, track, close)</td><td><strong>issue-core</strong></td></tr><tr><td>Project and initiative management (phased, completion-gated)</td><td><strong>project-core</strong> (future)</td></tr><tr><td>Repository capability profiling</td><td><strong>repo-scoping</strong></td></tr><tr><td>Cross-domain coordination state</td><td><strong>state hub</strong></td></tr><tr><td>Execution of automatable tasks</td><td>Temporal workers (per-repo)</td></tr></tbody></table></div>
<h3>Event type registry</h3>
<p>Event types are declared by publishers as markdown definition files (see ACT-ADR-002). Governance is <strong>publisher-declared by default</strong>: a publisher registers its event types by committing definition files to the event-types registry. In production environments, a curator gate can be enabled — registry entries must be reviewed before the runtime accepts events of that type. This is a configuration flag per runtime scope (dev, staging, prod), not a hard-coded rule.</p>
<h3>State hub relationship</h3>
<p>The state hub <strong>delegates automation to activity-core</strong> rather than implementing it internally. Concretely:</p>
<ul><li>Maintenance jobs currently baked into the state hub (consistency sync, SBOM staleness checks) are migrated to ActivityDefinitions in activity-core.</li><li>The state hub becomes a <strong>publisher</strong> of lifecycle events on NATS (<code>org.workstream.created</code>, <code>org.decision.resolved</code>, <code>org.repo.registered</code>, etc.).</li><li>The state hub does not subscribe to activity-core's output directly; it reads task state from issue-core when needed.</li></ul>
<p>This preserves the state hub as a read model and makes activity-core the single home for automation policy.</p>
<h3>rules-core: module-first</h3>
<p>The rule and instruction evaluation engine starts as <code>src/activity_core/rules/</code> — a module with a clean internal boundary (no imports from Temporal, Postgres, or FastAPI within the module). Extraction to a standalone <code>rules-core</code> repository happens when a <strong>second consumer</strong> (e.g. state hub governance, project-core) needs the engine. This follows the same discipline as the task-flow-engine extraction plan (CUST-TFE-SCOPE).</p>
<h3>NATS as org infrastructure</h3>
<p>NATS JetStream is promoted from an activity-core internal component to <strong>org-wide event bus infrastructure</strong>. It runs as a standalone service (not bundled in activity-core's docker-compose) with its own lifecycle. All services that publish or subscribe to org events do so via NATS streams.</p>
<h3>issue-core integration</h3>
<p>activity-core communicates with issue-core via a <strong>task emission adapter</strong> — an abstraction layer that, in the initial implementation, calls issue-core's REST API. The adapter interface is defined now; the transport can migrate to NATS subscription (issue-core subscribes to <code>task.spawned</code> events) once issue-core adds that capability. This avoids hardcoding REST coupling throughout the codebase.</p>
<h3>Webhook receiver</h3>
<p>A new HTTP endpoint within activity-core accepts inbound webhooks from Gitea (and later GitHub, other services). It normalises payloads to the canonical EventEnvelope format, validates against the event type registry, and publishes to NATS. This runs alongside the existing FastAPI <code>api.py</code>.</p>
<h3>Domain assignment</h3>
<p>activity-core and issue-core are assigned to the <strong><code>capabilities</code></strong> domain — the same domain as repo-scoping. These are org-wide infrastructure tools that serve all domains equally, not artefacts of any single project or custodian's personal workflow. issue-core is explicitly disassociated from the markitect domain.</p>
</section>
<section id="trigger-types"><h2>Trigger types</h2>
<p>Three trigger types are supported:</p>
<div class="scroll"><table><thead><tr><th>Type</th><th>Description</th><th>Temporal mechanism</th></tr></thead><tbody><tr><td><code>cron</code></td><td>Recurring schedule (5-field cron + timezone + misfire policy)</td><td>Temporal Schedule (implemented WP-0002)</td></tr><tr><td><code>event</code></td><td>React to a named event type on NATS</td><td>Temporal workflow started by Event Router</td></tr><tr><td><code>scheduled</code></td><td>One-off at a future datetime</td><td>Temporal Schedule with <code>remaining_actions: 1</code></td></tr></tbody></table></div>
<p><code>scheduled</code> is a new trigger type added in WP-0003.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Immediate</h3>
<ul><li>activity-core's <code>INTENT.md</code> and <code>SCOPE.md</code> are rewritten to reflect this architecture.</li><li><code>task_spawn_log</code> is the local <strong>spawn audit trail</strong>; authoritative work-item lifecycle state lives downstream.</li><li>A task emission adapter (<code>src/activity_core/issue_sink.py</code>) owns downstream creation. The unused <code>TaskExecutorWorkflow</code> and <code>task_instances</code> compatibility surface was retired by ACTIVITY-WP-0035.</li></ul>
<h3>Medium term</h3>
<ul><li>State hub adds NATS publishing to its lifecycle operations.</li><li>Gitea webhook receiver added to activity-core as a new HTTP router.</li><li>Existing state hub maintenance crons are migrated to ActivityDefinitions.</li><li>issue-facade is renamed issue-core and re-registered under the <code>capabilities</code> domain.</li></ul>
<h3>Long term</h3>
<ul><li>rules-core extracted as a standalone package when a second consumer appears.</li><li>project-core created (depends on task-flow-engine extraction) for multi-phase initiative management — explicitly out of scope for activity-core.</li><li>NATS gets its own operational runbook and monitoring as org infrastructure.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<p><strong>State hub absorbs activity-core functionality</strong>: rejected — turns the state hub into a God object, violates the read-model boundary, and makes automation logic impossible to test independently.</p>
<p><strong>Per-repo automation (GitHub Actions style)</strong>: rejected — cross-repo coordination requires a single vantage point that can see all repos; per-repo actions can't express org-level triggers or context.</p>
<p><strong>Activity-core as a thin Temporal wrapper only</strong>: rejected — without the event type registry and rule model, it's just a scheduler. The governance and introspection properties are the point.</p>
<p><strong>Separate rules-core from day one</strong>: rejected — premature extraction adds dependency management overhead before a second consumer exists. Module-first with a clean boundary costs nothing and preserves the extraction option.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ACT-ADR-002 — Event type and ActivityDefinition definition format</li><li>ACT-ADR-003 — Rule vs. Instruction model and DSL</li><li>CUST-ADR-001 — Workplans as repository artefacts (canon/architecture/)</li><li>CUST-TFE-SCOPE-2026-000001 — task-flow-engine extraction plan (canon/projects/)</li><li>activity-core INTENT.md (to be written)</li><li>activity-core WP-0003 (to be written)</li></ul>
</section><footer><span>ACT-ADR-001 · accepted-2 · accepted</span><span>activity-core · docs/adr/adr-001-event-bridge-architecture.md · b72fdb5452bff51a867a0316edb994723b35f268</span></footer></main></div></div></html>

437
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-002.html Normal file
View file

@ -0,0 +1,437 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="b72fdb5452bff51a867a0316edb994723b35f268">
<meta name="policy-source-digest" content="1670e1616094bc6f2c0c7d47b2e019c02d5870b22b564ef83afa24caff197bab">
<title>Markdown-as-Definition Format for Event Types and ActivityDefinitions</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-002</span> <span class="stat">accepted · accepted-2</span> <span>activity-core</span> <span>reviewed 2026-05-14</span><span>generated from canonical source — do not edit</span></div><h1>Markdown-as-Definition Format for Event Types and ActivityDefinitions</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-002-definition-format.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><p class="sub">Review due: 2026-11-14</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>Event type schemas and ActivityDefinition rules need to be understood and authored by three distinct audiences simultaneously: humans reviewing and debugging automation, agents creating and modifying definitions at runtime, and machines parsing and evaluating them. Traditional approaches split these concerns — schemas go in JSON Schema or YAML, documentation goes in a wiki, logic goes in code — and they drift apart. A bug in a rule requires cross-referencing three places to understand intent, check the schema, and read the condition.</p>
<p>The Custodian ecosystem already uses markdown files with YAML frontmatter as the authoritative format for workplans, ADRs, SCOPE.md, and INTENT.md — all understood by humans and agents without additional tooling. The same pattern should apply here.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Event type definitions and ActivityDefinitions are markdown files</strong> where machine- parseable structure (frontmatter YAML and fenced definition blocks) is embedded within human-readable narrative. Intent, schema, logic, and debugging notes live in one file.</p>
<h3>Event Type Definition Files</h3>
<p><strong>Location</strong>: <code>event-types/{namespace}.{event-name}.md</code> within the activity-core repo (or a registered event-types registry repo if volumes justify separation).</p>
<p><strong>Naming convention</strong>: <code>{publisher-domain}.{noun}.{verb}.md</code>, e.g.:</p>
<ul><li><code>org.repo.registered.md</code></li><li><code>org.security.cve.published.md</code></li><li><code>org.workstream.completed.md</code></li></ul>
<p><strong>Structure</strong>:</p>
<pre>---
id: org.repo.registered
type: event-type
version: &quot;1.0&quot;
publisher: the-custodian/state-hub
governance: publisher-declared # publisher-declared | curated
status: active # active | deprecated | draft
introduced: &quot;2026-05-14&quot;
---
# Event: org.repo.registered
## Intent
One-paragraph statement of why this event exists and what it signals.
Written for an agent or human who has never seen it before.
## When Published
Bulleted list of the exact conditions under which the publisher fires this event.
Be precise — ambiguity here causes missed or duplicate activations.
## Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
| `repo_slug` | string | yes | URL-safe repository identifier |
| `domain` | string | yes | Domain slug the repo is assigned to |
| `tags` | string[] | no | Capability tags set at registration time |
| `registered_at` | datetime | yes | ISO 8601 UTC timestamp |
## Example Payload
​```json
{
&quot;id&quot;: &quot;evt-7f3a1b2c&quot;,
&quot;type&quot;: &quot;org.repo.registered&quot;,
&quot;version&quot;: &quot;1.0&quot;,
&quot;timestamp&quot;: &quot;2026-05-14T10:00:00Z&quot;,
&quot;publisher&quot;: &quot;the-custodian/state-hub&quot;,
&quot;attributes&quot;: {
&quot;repo_slug&quot;: &quot;new-python-service&quot;,
&quot;domain&quot;: &quot;railiance&quot;,
&quot;tags&quot;: [&quot;python-service&quot;, &quot;fastapi&quot;],
&quot;registered_at&quot;: &quot;2026-05-14T10:00:00Z&quot;
}
}
​```
## Consumer Notes
Guidance for agents and humans writing rules against this event type:
- Which attributes are safe for instruction prompts (trusted fields)
- Common misuses or gotchas
- Related events that are often used together
## Debugging
What to check when an activity that subscribes to this event does not fire:
- How to verify the event was published (NATS subject, log entry)
- How to inspect the event payload in the registry
- Common schema validation failures</pre>
<h3>Attribute Types</h3>
<p>The type system for event attributes is intentionally small:</p>
<div class="scroll"><table><thead><tr><th>Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>string</code></td><td>UTF-8 string</td></tr><tr><td><code>integer</code></td><td>64-bit signed integer</td></tr><tr><td><code>float</code></td><td>64-bit float</td></tr><tr><td><code>boolean</code></td><td>true / false</td></tr><tr><td><code>datetime</code></td><td>ISO 8601 UTC string in payload, parsed to datetime in evaluator</td></tr><tr><td><code>uuid</code></td><td>String in payload, validated as UUID v4</td></tr><tr><td><code>string[]</code></td><td>JSON array of strings</td></tr><tr><td><code>integer[]</code></td><td>JSON array of integers</td></tr><tr><td><code>object</code></td><td>Freeform JSON object — cannot be used in rule conditions; instruction-only</td></tr></tbody></table></div>
<p><code>object</code> type attributes are available to instructions but excluded from rule conditions deliberately — rules must be deterministic and schema-validatable.</p>
<h3>ActivityDefinition Files</h3>
<p><strong>Location</strong>: <code>activity-definitions/{slug}.md</code> within the repo that owns the automation. For org-wide automations: <code>activity-core/activity-definitions/</code>. For domain-specific automations: <code>{domain-repo}/activity-definitions/</code>.</p>
<p><strong>Structure</strong>:</p>
<pre>---
id: ACT-DEF-onboard-python-repo
type: activity-definition
version: &quot;1.0&quot;
status: active
trigger:
type: event # event | cron | scheduled
event_type: org.repo.registered # for type: event
# cron: &quot;0 9 * * 1&quot; # for type: cron (5-field, UTC)
# timezone: &quot;Europe/Berlin&quot; # optional, cron only
# misfire_policy: skip # skip | catchup | compress (cron only)
# at: &quot;2026-06-01T09:00:00Z&quot; # for type: scheduled (one-off)
context_sources:
- type: repo-scoping
query: repo_profile
bind_to: context.repo_profile
- type: state-hub
query: domain_summary
bind_to: context.domain_summary
governance: publisher-declared
owner: custodian-agent
created: &quot;2026-05-14&quot;
---
# ActivityDefinition: Onboard New Python Service
## Purpose
One paragraph. What does this automation do and why does it exist? What problem
would accumulate if this automation were turned off?
## Trigger
Which event type fires this activity, and under what conditions does it apply?
Cross-reference the event type definition file.
## Context Sources
What context is resolved before rules are evaluated? Explain what each source
provides and why it is needed.
## Rules
Each rule is a fenced block tagged `rule`. Rules are evaluated in order; all
matching rules fire (not first-match-only). See ACT-ADR-003 for the expression
language specification.
​```rule
id: create-sbom-scan
condition: &#x27;&quot;python-service&quot; in event.attributes.tags&#x27;
action:
task_template: tasks/sbom-initial-scan.md
target_repo: event.attributes.repo_slug
priority: high
labels: [&quot;onboarding&quot;, &quot;security&quot;]
​```
​```rule
id: create-scope-generation
condition: &#x27;&quot;python-service&quot; in event.attributes.tags and context.repo_profile.scope_md_exists == false&#x27;
action:
task_template: tasks/generate-scope-md.md
target_repo: event.attributes.repo_slug
priority: medium
labels: [&quot;onboarding&quot;, &quot;documentation&quot;]
​```
## Instructions
Instructions are evaluated after all rules. An instruction asks an LLM to decide
what additional tasks (if any) to create. See ACT-ADR-003 for safety requirements.
​```instruction
id: domain-specific-onboarding
condition: &#x27;event.attributes.domain != &quot;test_domain_v2&quot;&#x27;
trusted_fields:
- event.attributes.repo_slug
- event.attributes.domain
- event.attributes.tags
model: claude-sonnet-4-6
review_advisory: false
prompt: |
A new repository has been registered in the Coulomb organization.
Repository: {event.attributes.repo_slug}
Domain: {event.attributes.domain}
Tags: {event.attributes.tags}
Based on the domain&#x27;s current standards and the repository profile above,
determine what additional domain-specific onboarding tasks should be created
beyond the standard SBOM scan and SCOPE.md generation. Return an empty list
if no additional tasks are warranted.
output_schema: tasks/task-template-list-schema.json
​```
## Task Templates
References to task template files used in rule actions. Each template is a
separate markdown file under `tasks/` that defines the task title, description
template, default labels, and default assignee logic.
- `tasks/sbom-initial-scan.md`
- `tasks/generate-scope-md.md`
## Notes
Operational notes, edge cases, and context that does not fit elsewhere.
## Debugging
Checklist for when this ActivityDefinition fires but produces unexpected output:
1. Was the triggering event published with the correct type and attributes?
2. Do the rule conditions evaluate as expected? (Use `make eval-rule` with a fixture)
3. Is issue-core reachable and configured for the target domain?
4. For instructions: check the audit log for the model response and output validation result.
## Change History
- v1.0 (2026-05-14): Initial definition</pre>
<h3>Governance model</h3>
<p>The <code>governance</code> field on an event type definition determines how the registry runtime handles it:</p>
<div class="scroll"><table><thead><tr><th>Value</th><th>Behaviour</th></tr></thead><tbody><tr><td><code>publisher-declared</code></td><td>Accepted immediately on publish; no review required</td></tr><tr><td><code>curated</code></td><td>Held in <code>pending</code> state until a curator approves via registry API</td></tr></tbody></table></div>
<p>The runtime checks the <strong>environment's curator gate configuration</strong> — not just the file's governance field. An environment configured with <code>curator_gate: disabled</code> treats all event types as <code>publisher-declared</code> regardless of the field value. An environment with <code>curator_gate: required</code> treats all event types as <code>curated</code> regardless of the field value. The field is the publisher's declared preference; the environment config is the enforcement point.</p>
<p>This means:</p>
<ul><li><strong>Dev / integration</strong>: <code>curator_gate: disabled</code> — developers and agents iterate freely; new event types take effect immediately.</li><li><strong>Staging / production</strong>: <code>curator_gate: required</code> — all new event types queue for curator review before the runtime accepts events of that type.</li></ul>
<h3>File as source of truth</h3>
<p>Following CUST-ADR-001 (Workplans as Repository Artefacts), definition files are the canonical source of truth. The activity-core runtime indexes them into its database on startup and via a sync command. The database is a queryable cache, not the origin. A definition deleted from the filesystem is disabled at next sync.</p>
<h3>Task Templates</h3>
<p>Task templates are separate markdown files (<code>tasks/{slug}.md</code>) referenced from ActivityDefinition action blocks. They define:</p>
<pre>---
id: tasks/sbom-initial-scan
type: task-template
---
# Task: Run Initial SBOM Scan
## Title template
`Run SBOM scan — {target_repo}`
## Description template
Initial SBOM scan required for newly registered repository `{target_repo}`.
Run: `make ingest-sbom REPO={target_repo} SCAN=1`
## Default labels
[&quot;sbom&quot;, &quot;security&quot;, &quot;automated&quot;]
## Default assignee
None (unassigned)</pre>
<p>This keeps task content editable separately from the routing logic in ActivityDefinitions.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>A new <code>event-types/</code> directory in activity-core (and eventually a shared registry) holds all org event type definitions.</li><li>A new <code>activity-definitions/</code> directory in activity-core holds org-wide automations.</li><li>Domain repos may hold their own <code>activity-definitions/</code> for domain-specific automations, scanned by activity-core at sync time.</li><li>The runtime requires a parser for the <code>rule</code> and <code>instruction</code> fenced blocks.</li><li>SCOPE.md for activity-core must be updated to list these directories.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<p><strong>Pure JSON Schema for event types, separate wiki for docs</strong>: rejected — documentation and schema diverge immediately; agents must cross-reference two systems to author a rule correctly.</p>
<p><strong>OpenAPI / AsyncAPI specification</strong>: rejected — those formats are excellent for API and broker documentation but not designed for co-locating operational intent and debugging guidance. They are also less readable for non-specialists.</p>
<p><strong>Code-only (Python dataclasses for event schemas, Python functions for rules)</strong>: rejected — requires code deployment for any definition change; agents cannot modify definitions without write access to the codebase; non-technical stakeholders cannot review or understand automation policies.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ACT-ADR-001 — Event Bridge Architecture</li><li>ACT-ADR-003 — Rule vs. Instruction model and DSL</li><li>CUST-ADR-001 — Workplans as repository artefacts</li></ul>
</section><footer><span>ACT-ADR-002 · accepted-2 · accepted</span><span>activity-core · docs/adr/adr-002-definition-format.md · b72fdb5452bff51a867a0316edb994723b35f268</span></footer></main></div></div></html>

294
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-003.html Normal file
View file

@ -0,0 +1,294 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="b72fdb5452bff51a867a0316edb994723b35f268">
<meta name="policy-source-digest" content="f1017730074727bcb0c68309c445ffb219ef647c8c5604adbfff76c4aa3f9d66">
<title>Rule vs. Instruction Model and Expression DSL</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-003</span> <span class="stat">accepted · accepted-2</span> <span>activity-core</span> <span>reviewed 2026-05-14</span><span>generated from canonical source — do not edit</span></div><h1>Rule vs. Instruction Model and Expression DSL</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-003-rule-instruction-model.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><p class="sub">Review due: 2026-11-14</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>ActivityDefinitions need two distinct evaluation modes to cover the full range of automation scenarios in the Coulomb org:</p>
<p><strong>Deterministic cases</strong>: "if this repo has tag <code>python-service</code> AND has no SBOM in the last 30 days, create a scan task." The condition is fully expressible as a boolean predicate over known attributes. The output is fixed by the template. No ambiguity, no LLM required, fully testable.</p>
<p><strong>Judgement cases</strong>: "a new repository has been registered — based on its domain and profile, determine what domain-specific onboarding tasks are appropriate." The right answer depends on context that is expensive to encode as explicit rules. An LLM is a better evaluator than a rule tree, but introduces non-determinism, cost, and a new attack surface (prompt injection via event payload).</p>
<p>Conflating these two modes into one mechanism produces a system that is either too rigid (rules only) or too unpredictable (LLM everywhere). The two modes need different evaluation pipelines, testing strategies, and audit trails.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Two named, distinct evaluation modes: Rule and Instruction.</strong></p>
<p>Terminology is deliberate. A <strong>Rule</strong> is deterministic and mechanical — it applies or it does not. An <strong>Instruction</strong> is contextual and interpretive — it guides an LLM agent to make a judgement call. Both are expressed as fenced blocks in ActivityDefinition markdown files (see ACT-ADR-002).</p>
<h3>Rules</h3>
<p>A Rule has two parts: a <strong>condition</strong> (boolean predicate) and one or more <strong>actions</strong> (task template references).</p>
<h3>Condition expression language</h3>
<p>The condition is a single-line string expression evaluated by a sandboxed AST walker — never <code>exec()</code> or <code>eval()</code>. The evaluator walks the parsed AST and whitelist-checks every node type before executing. Unknown node types raise an <code>UnsafeExpression</code> error at parse time, not at evaluation time.</p>
<p><strong>Available operations</strong>:</p>
<div class="scroll"><table><thead><tr><th>Category</th><th>Syntax</th><th>Example</th></tr></thead><tbody><tr><td>Equality</td><td><code>==</code>, <code>!=</code></td><td><code>event.type == &quot;org.repo.registered&quot;</code></td></tr><tr><td>Comparison</td><td><code>&gt;</code>, <code>&lt;</code>, <code>&gt;=</code>, <code>&lt;=</code></td><td><code>event.attributes.sbom_age_days &gt; 30</code></td></tr><tr><td>Membership</td><td><code>in</code>, <code>not in</code></td><td><code>&quot;python-service&quot; in event.attributes.tags</code></td></tr><tr><td>Boolean</td><td><code>and</code>, <code>or</code>, <code>not</code></td><td><code>a and (b or not c)</code></td></tr><tr><td>Grouping</td><td><code>( )</code></td><td><code>(a or b) and c</code></td></tr><tr><td>Length</td><td><code>len(x)</code></td><td><code>len(event.attributes.affected_repos) &gt; 0</code></td></tr><tr><td>Existence</td><td><code>x is None</code>, <code>x is not None</code></td><td><code>event.attributes.domain is not None</code></td></tr></tbody></table></div>
<p><strong>Attribute access</strong> follows dot notation on the <code>event</code> object and the <code>context</code> object (populated by context sources declared in the ActivityDefinition):</p>
<ul><li><code>event.id</code> — UUID string</li><li><code>event.type</code> — event type identifier</li><li><code>event.version</code> — event type version</li><li><code>event.timestamp</code> — ISO 8601 datetime string</li><li><code>event.publisher</code> — publisher identifier</li><li><code>event.attributes.{name}</code> — typed attribute per event type schema</li><li><code>context.{source}.{field}</code> — resolved context data</li></ul>
<p><strong>Explicitly forbidden</strong> (evaluator rejects at parse time):</p>
<ul><li>Function calls other than <code>len()</code> and <code>None</code> tests</li><li>Attribute access on arbitrary Python objects</li><li>String interpolation or formatting</li><li>Any control flow (<code>if</code>, <code>for</code>, <code>while</code>, <code>lambda</code>)</li><li>Import statements</li><li>Assignments</li></ul>
<p><strong>Design rationale</strong>: the expression language is intentionally small. Anything complex enough to need more than this belongs in an Instruction, not a Rule. When a rule condition becomes difficult to express, that is a signal that the case requires LLM judgement, not a signal that the DSL needs more features.</p>
<h3>Actions</h3>
<p>A Rule's action block specifies:</p>
<pre>action:
task_template: &quot;Run SBOM rescan for {context.repo.repo_slug}&quot;
target_repo: context.repo.repo_slug
priority: medium
labels: [&quot;sbom&quot;, &quot;security&quot;, &quot;{context.repo.repo_slug}&quot;]
due_in_days: 7</pre>
<p><code>action.task_template</code> is the emitted task title template. It is not a path to a repo-local file. Older design notes and the legacy <code>tasks/*.md</code> directory use "task template" for materialized task-body templates; that is a separate legacy surface. To avoid surprise, new rule actions should treat <code>task_template</code> as <code>title_template</code> semantics until the field can be renamed in a schema-breaking revision.</p>
<p>Action fields accept two deterministic rendering forms:</p>
<ul><li>Whole-field paths: if the whole string is a path like <code>context.repo.repo_slug</code> or <code>event.attributes.repo_slug</code>, the rendered value keeps the original scalar/list/object shape from that path. This is the correct form for <code>target_repo</code> and other fields that should not become prose.</li><li>Scalar placeholders: strings may include <code>{context.foo}</code> or <code>{event.foo}</code> placeholders. Each placeholder must resolve to a scalar. Lists and objects are rejected rather than stringified, which prevents accidental JSON blobs or untrusted text from being embedded into task titles.</li></ul>
<p>Unsafe action cases are rejected:</p>
<ul><li>Any action path outside <code>context.*</code> or <code>event.*</code>.</li><li>Any path containing calls, indexing, arithmetic, filters, or boolean logic.</li><li>Placeholder values that resolve to lists or objects.</li><li><code>for_each</code> values that are not a whole-field <code>context.*</code> or <code>event.*</code> path to a list.</li><li><code>bind_as</code> names that are not simple identifiers.</li></ul>
<p>Per-item rule expansion is explicit:</p>
<pre>for_each: context.repos.repos
bind_as: repo
condition: &#x27;context.repo.sbom_age_days &gt; 30&#x27;
action:
task_template: Run SBOM rescan for {context.repo.repo_slug}
target_repo: context.repo.repo_slug
priority: medium
labels: [&quot;sbom&quot;, &quot;security&quot;, &quot;automated&quot;]</pre>
<p>The weekly SBOM staleness definition is the canonical pattern. The State Hub bulk resolver exposes all repository entries at <code>context.repos.repos</code>, the rule binds each item as <code>context.repo</code>, and the strict staleness definition is <code>context.repo.sbom_age_days &gt; 30</code>. Thirty days exactly is not stale; thirty-one days is stale.</p>
<h3>Evaluation semantics</h3>
<ul><li>All rules in an ActivityDefinition are evaluated; <strong>all matching rules fire</strong> (not first-match-only). There is no implicit ordering beyond the file order, which is documented in the ActivityDefinition for human clarity.</li><li>A rule whose condition raises an error during evaluation is skipped and logged as <code>rule_error</code>; other rules still fire. This prevents a single malformed rule from silencing an entire ActivityDefinition.</li><li>An empty condition (omitted <code>condition</code> field) evaluates to <code>true</code> — the rule always fires when the trigger fires.</li></ul>
<h3>Instructions</h3>
<p>An Instruction defers the task-creation decision to an LLM. It specifies what context to provide, how to frame the prompt, and what output schema to enforce.</p>
<h3>Structure</h3>
<pre># in an instruction fenced block:
id: {slug}
condition: &#x27;{expression}&#x27; # optional pre-filter (Rule DSL); runs before LLM
trusted_fields: # REQUIRED — explicit allowlist of payload fields
- event.attributes.repo_slug # safe to interpolate into prompt
- event.attributes.domain
- event.attributes.tags
model: claude-sonnet-4-6
review_advisory: false # true | false — advisory evidence, not a gate
prompt: |
{prompt template — only trusted_fields may be interpolated}
output_schema: {path to JSON schema file}</pre>
<h3>Trusted fields and prompt injection protection</h3>
<p>The <code>trusted_fields</code> list is <strong>required</strong> and enforced at parse time. Any field not listed is unavailable to the prompt template. The template engine raises <code>UntrustedFieldError</code> if the prompt references a field not in <code>trusted_fields</code>.</p>
<p>The rationale: event payloads may contain free-text from untrusted sources — commit messages, issue titles, CVE descriptions, repo descriptions. Interpolating these directly into a prompt creates a prompt injection surface. Trusted fields are those whose values are validated by the event type schema (typed attributes like slugs, domain names, tag lists) and cannot carry arbitrary instruction text by construction.</p>
<p>Fields of type <code>object</code> (freeform JSON) are <strong>never eligible</strong> for <code>trusted_fields</code> even if listed — the evaluator rejects this at parse time.</p>
<h3>Output schema enforcement</h3>
<p>The LLM response is validated against <code>output_schema</code> using JSON Schema validation. If validation fails, the instruction retries once with the schema error appended to the prompt. If the second attempt also fails, the instruction records an <code>instruction_output_error</code> audit event and emits no tasks. Tasks are <strong>never created from unvalidated output</strong>.</p>
<p>Structured output mode (tool_use / JSON mode) is used where the model supports it. The output schema must define <code>List[TaskSpec]</code> or a compatible envelope.</p>
<h3><code>review_advisory: true</code></h3>
<p>ACTIVITY-WP-0035 selected advisory-only semantics because no downstream owner currently exposes an acknowledged proposal/decision/release contract. The instruction's task/report evidence is marked <code>review_advisory=true</code> and <code>review_gate_applied=false</code> so an operator can distinguish review-worthy output without interpreting it as held for approval.</p>
<p>The legacy input name <code>review_required</code> is accepted during migration and normalized to <code>review_advisory</code>; new definitions must not use it. activity-core does <strong>not</strong> route proposals to a pending-review queue and does not own review lifecycle state. A future hold/release design requires a named downstream owner, an idempotent release reference, an ADR update, and fail-closed emission tests.</p>
<h3>Evaluation semantics</h3>
<ul><li>Instructions are evaluated <strong>after</strong> all rules in the ActivityDefinition.</li><li>The optional <code>condition</code> field on an instruction uses the same Rule DSL as a first-pass filter — if the condition is false, the LLM is not called. This avoids LLM cost for events that clearly do not need instruction judgement.</li><li>Instructions are <strong>not</strong> first-match-only; all instructions whose conditions pass fire. An ActivityDefinition may have zero instructions.</li></ul>
<h3>Audit trail</h3>
<p>Every task emission records:</p>
<div class="scroll"><table><thead><tr><th>Field</th><th>Rule</th><th>Instruction</th></tr></thead><tbody><tr><td><code>source_type</code></td><td><code>&quot;rule&quot;</code></td><td><code>&quot;instruction&quot;</code></td></tr><tr><td><code>source_id</code></td><td>rule <code>id</code> from definition</td><td>instruction <code>id</code> from definition</td></tr><tr><td><code>source_version</code></td><td>ActivityDefinition version</td><td>ActivityDefinition version</td></tr><tr><td><code>triggering_event_id</code></td><td>event UUID</td><td>event UUID</td></tr><tr><td><code>condition_matched</code></td><td>expression string</td><td>expression string (pre-filter)</td></tr><tr><td><code>prompt_hash</code></td><td>—</td><td>SHA-256 of rendered prompt</td></tr><tr><td><code>model</code></td><td>—</td><td>model ID used</td></tr><tr><td><code>output_validated</code></td><td>—</td><td><code>true</code> / <code>false</code></td></tr><tr><td><code>review_advisory</code></td><td>—</td><td><code>true</code> / <code>false</code>; no gate applied</td></tr></tbody></table></div>
<p>The audit trail is written to the <code>task_spawn_log</code> table in activity-core's database and referenced from the task record in issue-core.</p>
<p>The rendered prompt and provider response are deliberately not persisted. The prompt hash proves equality when an authorized operator can reconstruct the same input, but the audit contract does not promise reconstruction after source definitions or upstream event retention have changed. <code>activity_runs</code> retains the definition version and bounded context snapshot; reports may retain allowlisted route/usage metadata. Prompts, messages, tool output, credential fields, and provider blobs are excluded from run, progress, and public API evidence.</p>
<h3>Testing strategy</h3>
<p><strong>Rules</strong>: every rule can and should be unit-tested with fixture event payloads. A test helper <code>evaluate_rule(condition_str, event_fixture)</code> returns <code>bool</code> and raises on syntax errors. Tests live alongside ActivityDefinition files: <code>activity-definitions/{slug}.test.json</code> — a list of <code>{event, expected_rules_fired}</code> fixtures.</p>
<p><strong>Instructions</strong>: instructions cannot be deterministically unit-tested. Instead:</p>
<ul><li>Sample evaluations are collected: given a fixture event, record the LLM response.</li><li>Samples are committed to <code>activity-definitions/{slug}.samples/</code> for human review.</li><li>Output schema validation is unit-tested independently of the LLM call.</li><li>Prompt injection resistance is tested by including injection strings in fixture event payloads and asserting they do not appear in the rendered prompt.</li></ul>
<h3>rules-core module boundary</h3>
<p>The rule evaluator and instruction executor live in <code>src/activity_core/rules/</code>. Within this module:</p>
<ul><li><strong>No imports from</strong> <code>temporalio</code>, <code>sqlalchemy</code>, <code>fastapi</code>, or any activity-core application code.</li><li>Public surface: <code>evaluate_condition(expr: str, event: EventEnvelope, context: dict) -&gt; bool</code> and <code>execute_instruction(instr: InstructionDef, event: EventEnvelope, context: dict) -&gt; List[TaskSpec]</code>.</li><li>The module is independently importable and testable without starting the Temporal worker or Postgres.</li></ul>
<p>This boundary makes future extraction to <code>rules-core</code> a packaging exercise, not a refactor.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>The <code>ActivityDefinition</code> Pydantic model gains <code>rules: List[RuleDef]</code> and <code>instructions: List[InstructionDef]</code> fields. The current implicit "always create tasks" behaviour is replaced by explicit rule blocks.</li><li>A new <code>RuleEvaluator</code> class (AST walker) is added to <code>src/activity_core/rules/</code>.</li><li>A new <code>InstructionExecutor</code> class handles prompt rendering, LLM call, output validation, and review-required audit metadata. Pending review queue routing remains a future issue-core integration.</li><li>Integration tests for rule evaluation use fixture JSON; no running Temporal required.</li><li>The <code>task_spawn_log</code> table is added to the Postgres schema (new Alembic migration).</li><li>ActivityDefinition files that omit both <code>rules</code> and <code>instructions</code> are valid (they fire with no output) — this supports future placeholder definitions.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<p><strong>OPA / Rego for rule conditions</strong>: powerful, well-established policy language, supports complex logic. Rejected — Rego's learning curve is high for non-specialists; agents rarely produce correct Rego without fine-tuning; it adds a runtime dependency. The simple AST-walker DSL covers the realistic condition complexity for this org.</p>
<p><strong>Rules as Python lambdas</strong>: maximum expressiveness. Rejected — arbitrary code execution in a rule condition is a serious security surface, especially in an org-wide event loop. Code deployment required for any rule change; agents cannot write rules without code write access.</p>
<p><strong>LLM for all conditions (no Rule/Instruction split)</strong>: simpler model, more flexible. Rejected — non-deterministic for cases that are deterministic; expensive for high-frequency events like cron ticks; impossible to unit-test; audit trail for deterministic rules becomes murky.</p>
<p><strong>Instructions only, no Rules</strong>: allows arbitrary LLM judgement for everything. Rejected — LLM cost for every event, latency, and non-determinism are unacceptable for high-frequency maintenance automations. Many cases (SBOM staleness check, tag-based routing) are fully deterministic and should stay that way.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ACT-ADR-001 — Event Bridge Architecture</li><li>ACT-ADR-002 — Definition format (where rule/instruction blocks live)</li><li>CUST-TFE-SCOPE-2026-000001 — task-flow-engine extraction (analogue pattern)</li><li><code>src/activity_core/rules/</code> — implementation home</li></ul>
</section><footer><span>ACT-ADR-003 · accepted-2 · accepted</span><span>activity-core · docs/adr/adr-003-rule-instruction-model.md · b72fdb5452bff51a867a0316edb994723b35f268</span></footer></main></div></div></html>

224
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-004.html Normal file
View file

@ -0,0 +1,224 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="b72fdb5452bff51a867a0316edb994723b35f268">
<meta name="policy-source-digest" content="92da58f58ee3dbb62233161a0fc0b7780920f81ec37fdd40d476be354f24e0eb">
<title>The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Output</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-004</span> <span class="stat">accepted · accepted-2</span> <span>activity-core</span> <span>reviewed 2026-06-26</span><span>generated from canonical source — do not edit</span></div><h1>The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Output</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-004-producer-trust-boundary.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><p class="sub">Review due: 2026-12-26</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>On 2026-06-26 the scheduled daily WSJF triage instruction fired on time, called llm-connect successfully, and produced a long ranked recommendation list — but the JSON broke at char 5268 (~rank 8–9 of ~16), failing schema validation. Because the report was validated and consumed as a single monolithic JSON document, one malformed delimiter discarded the <strong>entire</strong> run, including the 7 perfectly good recommendations the model had already emitted. The scheduling and runtime layers were healthy; the failure was entirely at the seam where free-form model output meets a strict consumer.</p>
<p>This is not a one-off bug, it is a recurring class. activity-core has a <strong>trust boundary</strong> wherever generative or human-authored output meets strict deterministic consumers: the JSON Schema validator, the task emitter, and any classic compute pipeline downstream. The producers on the other side of that boundary — <strong>LLMs, agents, and humans</strong> — are all <em>untrusted producers</em>. Their output may be:</p>
<ul><li><strong>erroneous</strong> — hallucination, truncation at a token limit, drift, type slips, typos, a missing delimiter; or</li><li><strong>malicious</strong> — prompt injection, crafted payloads, or oversized / deeply-nested structures intended to exhaust or confuse the consumer.</li></ul>
<p>The pre-existing design treated producer output optimistically: parse the whole document, validate the whole document, and on any failure discard the whole document (preserving only a bounded diagnostic preview). That gives <strong>zero error locality</strong> — the blast radius of any single defect is the entire activation.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Treat the producer→consumer seam as an explicit, adversarial <strong>trust boundary</strong>, and place guardrails plus error-correction tooling <em>at that boundary</em> rather than letting raw producer output flow into deterministic consumers.</p>
<h3>Two non-fail-fast postures</h3>
<p>When hard-failing on a problem is undesirable, there are two sound strategies, and they <strong>compose</strong>:</p>
<ul><li><strong>A) Trust but handle exceptions</strong> (optimistic / reactive). Consume the output as-is; on exception, catch → repair → retry → or quarantine. Cheap on the happy path; blast radius depends entirely on how granular the catch is. Best when failures are rare and locally recoverable. Risk: failures surface late, possibly after partial side effects.</li><li><strong>B) Verify and mitigate</strong> (defensive / proactive). Validate, sanitize, clamp, and normalize the output to a known-good shape <em>before</em> it enters the pipeline — drop bad items, coerce types, bound sizes/depth, allow-list references — so the consumer only ever sees clean input. Higher upfront cost, smaller blast radius, no partial side effects. Best when failures are common or consequences are high.</li></ul>
<h3>Governing principles</h3>
<ol><li><strong>Push verification to the boundary; keep the interior strict.</strong> Apply posture <strong>B</strong> at the producer→consumer boundary; keep posture <strong>A</strong> for residual exceptions inside the verified core. Never relax the interior schema to absorb producer sloppiness.</li><li><strong>Make error locality match the unit of work.</strong> One bad recommendation must cost one recommendation, not the whole report. Structuring the payload so each item is independently parseable and validatable is the highest-leverage change.</li><li><strong>Quarantine, never silently drop.</strong> Invalid units are preserved as bounded, provenance-tagged artifacts (<code>index</code>, <code>error</code>, <code>raw</code> snippet, <code>reason</code>) so they can be debugged or replayed. Degraded-but-usable is reported distinctly from total loss.</li><li><strong>Both human and agent input get the same rigor.</strong> Guardrails are producer-agnostic: the same count / length / depth caps and reference allow-lists apply whether the producer is an LLM, an agent, or a human.</li></ol>
<h3>What this means concretely in activity-core</h3>
<p>Implemented in <code>src/activity_core/rules/executor.py</code>:</p>
<ul><li><strong>Strict-structure-only schema.</strong> The daily-triage output schema is strict on per-item <em>structure</em> (<code>required [rank, candidate, action, why]</code>, typed <code>wsjf</code>) and carries <code>maxItems</code> as a producer <em>hint</em> — never as a hard whole-document reject, which would reproduce the very blast-radius failure (ACT-ADR-002 governs the schema format; <code>schemas/daily-triage-report.json</code>).</li><li><strong>Item-granular recovery (posture B).</strong> When whole-document parse + one retry fail, <code>_resilient_report</code> recovers individually-parseable recommendation objects via a brace/quote-aware scanner (<code>_extract_object_spans</code>) that works for both pretty-printed and NDJSON output, attempts a best-effort <code>_try_repair</code> on a truncated tail, validates each recovered object against the item schema, and keeps the valid ones. Survivors are emitted with <code>output_validated=true</code>, <code>partial=true</code>, and <code>review_advisory=true</code> (<code>review_gate_applied=false</code>).</li><li><strong>Producer guardrails (<code>_partition_items</code>, applied on both the recovery and the happy path).</strong> Per recommendation: structural type → schema → structural caps (<code>_MAX_DEPTH</code>, <code>_MAX_STRING_LEN</code>) → reference allow-list → count cap (top-N by <code>maxItems</code>). The first failing check quarantines the item with provenance and a <code>reason</code> (<code>malformed</code> / <code>schema</code> / <code>guardrail</code> / <code>allow_list</code> / <code>over_limit</code>).</li><li><strong>Reference allow-list.</strong> A recommendation whose <code>candidate</code> is not in the set of known ids is quarantined. The set is sourced from resolved context (<code>context[&quot;known_candidates&quot;]</code>, via <code>_allow_list_from_context</code>); the check is inert until a context resolver populates it, so the capability ships now and activates with a one-line resolver change.</li></ul>
<h3>Where each posture sits</h3>
<div class="scroll"><table><thead><tr><th>Layer</th><th>Posture</th><th>Mechanism</th></tr></thead><tbody><tr><td>Schema / contract</td><td>B</td><td>strict per-item structure; <code>maxItems</code> as hint</td></tr><tr><td>Whole-document parse</td><td>A</td><td>tolerant parse + single retry</td></tr><tr><td>Failed parse</td><td>B</td><td>item-granular recovery + repair + quarantine</td></tr><tr><td>Per-item screening</td><td>B</td><td>schema + depth/length caps + allow-list + count cap</td></tr><tr><td>Emitted report</td><td>—</td><td><code>partial</code> / <code>quarantined_*</code> provenance; never silent</td></tr></tbody></table></div>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>A single malformed or oversized item no longer discards an entire activation; the daily-triage run that failed on 2026-06-26 would now deliver its 7 valid recommendations and quarantine the broken tail.</li><li>Reports gain a <code>partial</code> / <code>quarantined_*</code> vocabulary; downstream report sinks and reviewers can distinguish degraded-but-usable from total loss.</li><li>Guardrail thresholds (<code>_MAX_DEPTH</code>, <code>_MAX_STRING_LEN</code>, <code>maxItems</code>, the allow-list) are policy knobs that will need tuning; they are intentionally conservative defaults, not a finished calibration.</li><li><strong>Known retention gap (follow-on):</strong> <code>LLMConnectClient.complete()</code> still returns only <code>content</code>, discarding <code>finish_reason</code>/<code>usage</code>, and the total-loss artifact caps raw output below realistic break points. Capturing those signals so failures stay debuggable is tracked as a retention fix, not closed by this ADR.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives considered</h2>
<ul><li><strong>Hard-enforce <code>maxItems</code> in the validator.</strong> Rejected: a hard reject of an over-count document reproduces the whole-document blast radius. Mitigation (keep top-N, quarantine the rest) is preferred.</li><li><strong>Relax the schema to accept anything.</strong> Rejected: violates principle 1; pushes malformed data into downstream consumers.</li><li><strong>Retry-until-valid only (pure posture A).</strong> Rejected as the sole strategy: the 2026-06-26 failure recurred across both the initial attempt and the retry, so retry alone does not bound the blast radius.</li></ul>
</section>
<section id="references"><h2>References</h2>
<ul><li>ACT-ADR-002 — markdown-as-definition format and output schema governance.</li><li>ACT-ADR-003 — Rule vs. Instruction model; the Instruction prompt-injection surface this boundary complements on the output side.</li><li><code>workplans/ACTIVITY-WP-0016-llm-output-robustness-trust-boundary.md</code> — the implementing workplan.</li></ul>
</section><footer><span>ACT-ADR-004 · accepted-2 · accepted</span><span>activity-core · docs/adr/adr-004-producer-trust-boundary.md · b72fdb5452bff51a867a0316edb994723b35f268</span></footer></main></div></div></html>

249
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-005.html Normal file
View file

@ -0,0 +1,249 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="b72fdb5452bff51a867a0316edb994723b35f268">
<meta name="policy-source-digest" content="984208262a0f6b67a6dc94cb078ebd0bcddc95d0b21a694d7e207677c10b471f">
<title>Ops runs vs development work records — claim queue and plane split</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-005</span> <span class="stat">accepted · accepted-2</span> <span>activity-core</span> <span>reviewed 2026-08-03</span><span>generated from canonical source — do not edit</span></div><h1>Ops runs vs development work records — claim queue and plane split</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-005-ops-runs-vs-dev-work-records.md · b72fdb5452bff51a867a0316edb994723b35f268</code></p><p class="sub">Review due: 2027-02-03</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#topology"><span class="n">·</span>Topology</a></li><li><a href="#implementation-stack"><span class="n">·</span>Implementation stack</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p><strong>Accepted</strong> (2026-08-03).</p>
</section>
<section id="context"><h2>Context</h2>
<p>The fleet has two healthy patterns that were forced into one vague “task” idea:</p>
<ol><li><strong>Development / coordination work</strong> — structured workplans and tasks as <strong>repo files</strong>, indexed by <strong>State Hub</strong> on <strong>coulombcore</strong> (<code>fix-consistency</code>, UUIDv7 write-back). This matches ADR-001 and <code>work-record-types_v0.1.md</code> and is how humans and coding agents ship product.</li></ol>
<ol><li><strong>Operations / scheduled automation</strong> — activity-core Temporal schedules (when / what / where), rein-aharness execution (how), completion events (idempotence). Instances of “today’s FI brief” or “this prune fire” are <strong>ephemeral runs</strong>, not multi-day workplan bodies.</li></ol>
<p>Practice collapsed (2) into broken paths:</p>
<div class="scroll"><table><thead><tr><th>Path</th><th>Failure</th></tr></thead><tbody><tr><td>Emit <code>activity_task_spawn</code> progress only</td><td>Append-only; <strong>not claimable</strong>; schedule can “succeed” while nothing runs</td></tr><tr><td><code>ISSUE_SINK_TYPE=rest</code> → issue-core → Forgejo</td><td>Spam + 503s; issue-core INTENT forbids origin of fleet work</td></tr><tr><td>Host systemd timers dual-clocked with Temporal</td><td>Shadow scheduler; weak self-healing</td></tr></tbody></table></div>
<p>issue-core’s <strong>correct</strong> role is a <strong>connector facade</strong> over external trackers (Forgejo, GitHub, Jira, …) so agents need not know each backend. It is <strong>not</strong> the origin of work records and <strong>not</strong> the default internal ops queue. <strong>Gitea is out of scope</strong> for this fleet; the self-hosted forge is <strong>Forgejo</strong>.</p>
<p>Canon already allows a DB-only exception for “runtime operations data (logs, metrics, run histories, token events)” (<code>work-record-types_v0.1.md</code>). This ADR names that exception for <strong>ops runs</strong>.</p>
<p>This is also the precise meaning of INTENT's no-task-lifecycle boundary: <code>ops_run</code> claim/lease/outcome is durable runtime delivery state, not work-item state. It may not grow assignment, commitments, dependencies, project phases, or manually managed task status.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. Two planes for “work,” one vocabulary for people</h3>
<div class="scroll"><table><thead><tr><th>Plane</th><th>Artefact</th><th>Home</th><th>Lifecycle</th></tr></thead><tbody><tr><td><strong>A — Development / coordination</strong></td><td>Work records (<code>workplan</code>, <code>task</code>, <code>intake</code>, …)</td><td>Repo files + State Hub (coulombcore)</td><td>File-backed, reviewable, multi-day</td></tr><tr><td><strong>B — Recurrence control</strong></td><td>Activity definitions + Temporal schedules</td><td>activity-core (railiance)</td><td>Git definitions; DB schedule state</td></tr><tr><td><strong>C — Ops execution</strong></td><td><strong><code>ops_run</code></strong> (runtime claim object)</td><td><strong>activity-core DB + claim API</strong></td><td>open → claimed → succeeded \</td><td>failed \</td><td>expired</td></tr><tr><td><strong>D — External collab</strong></td><td>Tracker issues</td><td><strong>issue-core</strong> optional projection to <strong>Forgejo</strong> (and others)</td><td>Never default for internal automation</td></tr></tbody></table></div>
<p>Coding agents orient on <strong>Plane A</strong> via State Hub. Automation orients on <strong>Planes B+C</strong>. Humans outside the fleet may see <strong>Plane D</strong> only when deliberately projected.</p>
<h3>2. activity-core owns the ops_run claim queue</h3>
<p>When a definition emits a TaskSpec for internal fleet work:</p>
<ol><li>Write <strong><code>ops_run</code></strong> row (durable, claimable) with idempotency key (e.g. <code>fi-daily:2026-08-04</code> for once-per-day briefs).</li><li>Optionally dual-write <code>activity_task_spawn</code> progress for existing observers.</li><li>Do <strong>not</strong> open a Forgejo issue.</li><li>Do <strong>not</strong> create a workplan task file for that day’s fire.</li></ol>
<p>Claim API (implemented in ACTIVITY-WP-0026 and hardened in ACTIVITY-WP-0036):</p>
<ul><li><code>POST /ops-runs/claim</code> — lease next open run matching labels / worker id</li><li><code>POST /ops-runs/{id}/complete</code> — succeeded + completion metadata</li><li><code>POST /ops-runs/{id}/fail</code> — failed + retry policy</li><li><code>GET /ops-runs?state=open</code> — operator visibility</li></ul>
<p>Worker mutation credentials are bound to one configured queue <code>worker_id</code>; the request body cannot assert a different claim owner. Heartbeat, completion, and failure lock the row and require its lease deadline to remain strictly in the future. Operator/SSO credentials provide visibility and explicit administration, but do not act as a normal worker identity.</p>
<p>activity-core remains <strong>when / what / where</strong> only: it does <strong>not</strong> run domain LLM sessions or hold tenant git credentials.</p>
<h3>3. rein-aharness owns how (approach selection + execute)</h3>
<ul><li>Continuous <strong>claim loop</strong> (service / Deployment), not dual wall-clock timers as source of truth.</li><li>Host systemd timers become <strong>break-glass</strong> after cutover.</li><li><strong>Approach selection</strong> at claim time (minimal table v1):</li></ul>
<div class="scroll"><table><thead><tr><th>Labels / definition family</th><th>Approach</th></tr></thead><tbody><tr><td>mail / mail-intake</td><td>deterministic adapter (+ optional triage)</td></tr><tr><td>research-brief / fi-daily</td><td>structured llm-connect (<code>fi-research-brief</code>)</td></tr><tr><td>binky rhythm</td><td>structured llm-connect (<code>brief-daily</code>)</td></tr><tr><td>agent-session</td><td>persona + tool profile session</td></tr><tr><td>unknown</td><td>refuse; do not invent</td></tr></tbody></table></div>
<ul><li>Success posts <strong>domain completion event</strong> (e.g. <code>fi_daily_brief</code>) so resolvers set <code>due=false</code>, and closes the <code>ops_run</code>.</li></ul>
<h3>4. State Hub remains the work-record read model</h3>
<ul><li>Stays on <strong>coulombcore</strong>; railiance peers via edge relay / ops-bridge.</li><li>May <strong>project</strong> open/failed ops runs for fleet ops UI (read-only), but is <strong>not</strong> the claim authority.</li><li>Development workplans/tasks continue file + <code>fix-consistency</code> only.</li></ul>
<h3>5. issue-core is Forgejo (and multi-tracker) facade only</h3>
<ul><li><strong>Forgejo</strong> is the self-hosted forge; do not plan for <strong>Gitea</strong> as a product.</li><li>Optional <strong>project / link</strong> of an existing work-record UUID to an external issue when collaboration needs it.</li><li>Authenticated <code>POST /issues/</code> means “create/link <strong>external</strong> tracker work,” never “spawn fleet automation.”</li><li>Internal automation <strong>must not</strong> use issue-core as the ops claim queue unless a future design adds an <strong>internal-only</strong> backend with projection <strong>hard-off</strong> for automation labels — out of scope unless a later ADR says otherwise.</li></ul>
<h3>6. Promotion path ops → dev</h3>
<p>When an ops run discovers multi-day product work (e.g. “collect Kimi K3 under new quota”), the executor or human <strong>promotes</strong> an <code>intake</code> / workplan in the domain repo (Plane A). Ops runs never become permanent fake workplans.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>Self-healing recurrence: schedule → claimable row → claim → complete/fail.</li><li>Aligns issue-core INTENT with practice; stops Forgejo spam path.</li><li>Keeps activity-core thin; keeps rein-aharness as sole session/credential shell.</li><li>Preserves the good dev loop (files + State Hub).</li></ul>
<h3>Negative / cost</h3>
<ul><li>New schema + API + migrator in activity-core.</li><li>rein-aharness must leave issue-core-only poll as primary for ops.</li><li>Temporary dual-write and dual timers until cutover proven.</li></ul>
<h3>Non-goals</h3>
<ul><li>Replacing workplans for development.</li><li>Running domain briefs inside activity-core workers.</li><li>Global <code>ISSUE_SINK_TYPE=rest</code> to Forgejo.</li><li>Gitea support or migration paths.</li></ul>
</section>
<section id="topology"><h2>Topology</h2>
<pre>coulombcore: State Hub + work-record registry
railiance: activity-core (Temporal + ops_run queue)
rein-aharness (claim loop + approach + llm-connect)
domain checkouts
forgejo: optional external collab via issue-core projection only</pre>
</section>
<section id="implementation-stack"><h2>Implementation stack</h2>
<div class="scroll"><table><thead><tr><th>Workplan</th><th>Owner</th><th>Role</th></tr></thead><tbody><tr><td>ACTIVITY-WP-0026</td><td>activity-core</td><td>ops_run schema, claim API, emit path, dual-write</td></tr><tr><td>REIN-A-0002</td><td>rein-aharness</td><td>claim loop, approach table, FI/Binky cutover</td></tr><tr><td>ISSUE-WP-0006</td><td>issue-core</td><td>Forgejo-only language; projection boundary; no ops queue</td></tr><tr><td>STATE-WP-0078</td><td>state-hub</td><td>Read projection of ops_run for ops UI (optional consume)</td></tr></tbody></table></div>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>docs/recurring-automations-playbook.md</code></li><li><code>docs/task-emission-consumer-contract.md</code></li><li><code>docs/issue-core-emission-boundary.md</code></li><li>ACTIVITY-WP-0022, ACTIVITY-WP-0023 (G2)</li><li><code>the-custodian/canon/standards/work-record-types_v0.1.md</code></li><li><code>issue-core/INTENT.md</code> (work-record boundary)</li><li><code>state-hub/docs/cluster-operating-model.md</code> (coulombcore primary)</li></ul>
</section><footer><span>ACT-ADR-005 · accepted-2 · accepted</span><span>activity-core · docs/adr/adr-005-ops-runs-vs-dev-work-records.md · b72fdb5452bff51a867a0316edb994723b35f268</span></footer></main></div></div></html>

228
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-006.html Normal file
View file

@ -0,0 +1,228 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ea6fb0e92a25825b42e00b2f85aa23cf50605294">
<meta name="policy-source-digest" content="88041e9eb3a0f91fdd9da46f9813d7304b5ba58e62f9d28ea8f63c0a7b055b63">
<title>Profile-driven execution selection over the ops_run pull queue</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-006</span> <span class="stat">accepted · accepted-1</span> <span>activity-core</span> <span>reviewed 2026-08-21</span><span>generated from canonical source — do not edit</span></div><h1>Profile-driven execution selection over the ops_run pull queue</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-006-glas-profile-execution.md · ea6fb0e92a25825b42e00b2f85aa23cf50605294</code></p><p class="sub">Review due: 2027-02-21</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p><strong>Accepted</strong> (2026-08-21). Hub decision <code>147beec6-7fe7-4837-8e3a-4264a240379d</code> ("Glas contract 1.0 makes execution constellation selection explicit").</p>
</section>
<section id="context"><h2>Context</h2>
<p>ACT-ADR-005 gave internal scheduled automation a claimable <code>ops_run</code> plane. What an ops_run said about <em>how</em> to execute was <code>approach_hint</code> — free text, interpreted by the claiming executor at claim time.</p>
<p>That binding is too late. Live failure, railiance01 2026-08-17:</p>
<pre>state=failed attempt=1 claim_owner=rein-aharness@railiance01
title=Run SBOM rescan for binect-js
failure=no approach matched labels/definition;
labels=[&#x27;sbom&#x27;,&#x27;security&#x27;,&#x27;automated&#x27;]</pre>
<p>The run was claimed and leased, <em>then</em> died because nothing could execute it. A claim was consumed to discover the request was unroutable.</p>
<p><code>glas-harness</code> GLAS-WP-0004 closed contract 1.0 and proved it by running one bounded task through two different reins (<code>rein-aharness</code>, <code>rein-openweights</code>) via an explicit <code>harness_profile_ref</code>, with real commits and verified sandbox destruction. Meanwhile every activity-core claim in the week to 2026-08-21 was <code>rein-aharness@railiance01</code> — a coupling that is now avoidable rather than inherent.</p>
<p>Two shapes were considered: keep the pull queue and carry the profile as payload, or have activity-core call the Glas gateway directly. glas-harness, which owns the contract, advised the first for the initial migration.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. The queue stays; the payload changes</h3>
<p>activity-core continues to insert <code>ops_run(open)</code> and executors continue to claim under lease. Scheduling topology does not change. What changes is that a queued run carries an exact <strong>versioned <code>harness_profile_ref</code></strong> plus the correlation / assignment / role / duty / goal / resource-envelope references. The claiming executor passes that request into Glas, which resolves or refuses it <strong>before sandbox creation</strong>.</p>
<p>This changes the execution contract without simultaneously changing the scheduling topology — one variable at a time. A direct activity-core → Glas call may be evaluated later, independently, if pull delivery stops meeting operational needs.</p>
<h3>2. <code>harness_profile_ref</code> is authoritative; <code>approach_hint</code> is legacy</h3>
<p>The two coexist with <strong>distinct semantics</strong>, not as fallbacks for one another:</p>
<ul><li><code>harness_profile_ref</code> is the authoritative execution-constellation selector.</li><li><code>approach_hint</code> remains only a legacy activity/definition-matching hint while producers and consumers migrate.</li></ul>
<p><code>approach_hint</code> must <strong>not</strong> override, synthesize, or fall back from an absent or invalid <code>harness_profile_ref</code> on governed execution. A missing profile is an error, never an invitation to guess from a hint. Once inventory shows no caller depends on <code>approach_hint</code> for runtime selection, that use is deprecated.</p>
<h3>3. activity-core does not mirror the profile catalog</h3>
<p>The catalog in glas-harness is authoritative. activity-core must not maintain an independent list, which would drift and produce a second, disagreeing opinion about what is executable.</p>
<p>Consequence, accepted knowingly: Glas exposes deterministic validation through its package and CLI but <strong>no network validation service</strong> today, so activity-core cannot remotely validate a profile ref at emission time. We therefore validate only what is local and structural — that a ref is present and well-formed for governed execution — and rely on the <strong>execution-side Glas resolver as the mandatory fail-closed check</strong>.</p>
<p>This is weaker than refusing at emission, and deliberately so: an unreachable or absent validation service must never downgrade into "emit anything". If emit-time remote validation is later required, it needs a separately scoped Glas API and its own decision — not a mirrored catalogue here.</p>
<p>Even unvalidated at emit, this is strictly better than the 2026-08-17 failure: refusal happens deterministically before sandbox creation rather than after a claim and lease were consumed.</p>
<h3>4. activity-core does not become an executor</h3>
<p>We emit an authorized, profile-named request and record normalized evidence. We do not select reins, provision sandboxes, acquire credentials, or run any inner agentic loop. Glas owns profile resolution and the outer loop; the rein owns its inner loop; <code>sand-boxer</code> owns isolation. This is SCOPE drift risk #1 ("convenience execution") and this ADR does not relax it.</p>
<p>The attribution references we carry (<code>assignment_ref</code>, <code>role_ref</code>, <code>duty_ref</code>, <code>goal_refs</code>, <code>resource_envelope_refs</code>) are <strong>passed through</strong>, not authored here. Their vocabulary belongs to <code>info-tech-canon</code>; activity-core must not invent org roles (ACTIVITY-WP-0029 responsibility map).</p>
<p>ACT-ADR-007's bounded-operation exception does not alter this decision. A code-registered fixed maintenance operation is not a Glas/rein execution constellation, and the exception cannot be used to run an agent loop or execute an <code>ops_run</code> inside activity-core.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>ops_runs</code> grows <code>harness_profile_ref</code> and the attribution refs; the emission path, queue projection, and run artefacts carry them.</li><li>Definitions declare a profile; rules pass it through.</li><li>Unroutable requests fail before sandbox creation instead of at claim time.</li><li>activity-core is no longer coupled to one rein in practice.</li><li>Emit-time validation remains a known gap, owned by a future Glas API.</li><li>Implementation: <strong>ACTIVITY-WP-0032</strong>.</li></ul>
</section><footer><span>ACT-ADR-006 · accepted-1 · accepted</span><span>activity-core · docs/adr/adr-006-glas-profile-execution.md · ea6fb0e92a25825b42e00b2f85aa23cf50605294</span></footer></main></div></div></html>

226
docs/evidence/2026-10-11-served-publication-history/pages/ACT-ADR-007.html Normal file
View file

@ -0,0 +1,226 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ea6fb0e92a25825b42e00b2f85aa23cf50605294">
<meta name="policy-source-digest" content="75f42047b51293f7240f8a8c3ec02bf025a47fe6627f106fc4ef22fb1be7459d">
<title>Code-registered bounded operations are the only local mutation exception</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ACT-ADR-007</span> <span class="stat">accepted · accepted-1</span> <span>activity-core</span> <span>reviewed 2026-08-23</span><span>generated from canonical source — do not edit</span></div><h1>Code-registered bounded operations are the only local mutation exception</h1><p class="sub">Source: <code>activity-core · docs/adr/adr-007-bounded-operations.md · ea6fb0e92a25825b42e00b2f85aa23cf50605294</code></p><p class="sub">Review due: 2027-02-23</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#rejected-alternatives"><span class="n">·</span>Rejected alternatives</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p><strong>Accepted</strong> (2026-08-23) for ACTIVITY-WP-0035.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The Event Bridge principle says activity-core answers when, what, and where and does not execute domain work. Production nevertheless contains three useful operations whose complete outcome is a small scheduled maintenance action:</p>
<ul><li>ingest at most three Repo Manager-selected immutable sources into SBOM Nexus;</li><li>prune Forgejo package versions under live-image protection; and</li><li>invoke the fixed CNPG Option A backup tool for an explicit target list.</li></ul>
<p>Historically the latter two ran through a generic <code>shell</code> context resolver. That made a mutating subprocess look like a read and left extension policy to convention. Removing the operations would recreate bespoke cron; accepting arbitrary shell would make activity-core a general executor.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. Bounded operations are a narrow implementation exception</h3>
<p>The governing when/what/where responsibility does not gain a general “how.” A bounded operation is allowed only when the operation itself is the declared automation outcome and all admission requirements below are code-reviewable.</p>
<p>The initial allowlist is exactly:</p>
<ol><li><code>sbom_nexus_ingest</code></li><li><code>forgejo_package_prune</code></li><li><code>cnpg_option_a_backup</code></li></ol>
<p>Adding an operation requires updating the code-owned registry, this ADR (or a successor), tests, credential route, and evidence contract. A string in a definition cannot register an operation.</p>
<h3>2. Admission is fail closed during file sync</h3>
<p>Each registry entry declares:</p>
<ul><li>source type and query;</li><li>whether mutation intent is <code>apply</code> or <code>dry_run</code> and that it is explicit;</li><li>fixed or maximum target bounds;</li><li>canonical implementation and allowed configuration;</li><li>idempotency and Temporal retry semantics;</li><li>maximum execution timeout;</li><li>credential owner/route; and</li><li>mandatory non-secret evidence mode.</li></ul>
<p>Unknown <code>shell</code> queries are refused unless separately registered as read-only. Known operation queries with missing, malformed, or over-limit safety fields are refused before database projection or Temporal schedule reconciliation.</p>
<h3>3. Context resolution is read-only</h3>
<p>The workflow first resolves and freezes context. Mutations then run in an explicit bounded-operation stage and merge only normalized outcomes into the snapshot before evidence and rule/instruction evaluation.</p>
<p>SBOM selection remains a read in the context phase; its fixed selection is the input to the operation stage. Package prune and backup have no discovery read inside activity-core and bind a pending marker until their operation completes.</p>
<h3>4. Retry behavior is operation-specific</h3>
<ul><li>SBOM ingest uses stable per-run/per-repository idempotency keys and heartbeat checkpoints, so Activity retries resume the frozen batch.</li><li>Forgejo prune and CNPG backup have no activity-core-verifiable remote idempotency receipt. Their operation activity therefore has one Temporal attempt; a failure remains visible for operator reconciliation rather than risking an automatic second mutation.</li></ul>
<p>This does not preclude future safe retries after the platform tools expose a durable operation receipt.</p>
<h3>5. Evidence is mandatory and bounded</h3>
<p>Every operation must produce an allowlisted summary through a configured report/evidence sink. Raw subprocess output, tokens, provider payloads, archive URLs, kubeconfigs, and credential material are not evidence.</p>
</section>
<section id="rejected-alternatives"><h2>Rejected alternatives</h2>
<ul><li><strong>Keep mutating shell resolvers.</strong> Rejected because resolution should be a replayable read and the generic dispatcher hides mutation admission.</li><li><strong>Generic command activity.</strong> Rejected because command text/path from a definition is remote code execution by configuration.</li><li><strong>Move every operation to a rein.</strong> Rejected for these fixed platform operations; it adds an agent execution constellation without judgement or repository work. Operations that exceed this ADR's bounds do belong there.</li><li><strong>Remove all local operations.</strong> Rejected because it recreates scattered cron and loses Temporal/evidence guarantees for established maintenance.</li></ul>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Definition parsing gains a central operation-policy validator.</li><li>The workflow gains an explicit operation stage.</li><li>The generic <code>shell</code> resolver becomes read-only.</li><li>Existing definitions migrate without widening targets or permissions.</li><li>The registry is intentionally small and architectural review is required to expand it.</li></ul>
</section><footer><span>ACT-ADR-007 · accepted-1 · accepted</span><span>activity-core · docs/adr/adr-007-bounded-operations.md · ea6fb0e92a25825b42e00b2f85aa23cf50605294</span></footer></main></div></div></html>

257
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-001.html Normal file
View file

@ -0,0 +1,257 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d3c6f13d7aed9784b6f31c23d2b2777668493ba5">
<meta name="policy-source-digest" content="183023ee57bae9c29e726fec5ee0361633fe3a2b182436a57869ae4b2a27af24">
<title>Workplans and Work Items Are Repository Artefacts</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-001</span> <span class="stat">accepted · accepted-2</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Workplans and Work Items Are Repository Artefacts</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#workplan-closure"><span class="n">·</span>Workplan closure</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#migration"><span class="n">·</span>Migration</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-02-28.</p>
<p>Amended 2026-08-31 to distinguish file-backed work records from hub-native records, identify the Forge default branch as the central projection baseline, and align identity, lifecycle, reconciliation, and closure with ADR-007, ADR-010, ADR-011, ADR-012, and the work-record standards. The central decision is unchanged.</p>
</section>
<section id="context"><h2>Context</h2>
<p>During early State Hub development, workstreams and tasks were created directly in PostgreSQL through bootstrap APIs. This made a database the origin of durable work rather than a projection of repository-owned artefacts. The pattern was convenient, but it made work difficult to audit, review, recover, and carry between generations of tooling.</p>
<p>The original decision correctly moved durable workplans and their work items into repositories. It overstated the consequence, however, by saying that the entire Hub database and every item that matters for coordination must be reconstructible from repository files. Later decisions established two different persistence classes:</p>
<ul><li><strong>file-backed records</strong>, whose durable meaning originates in a repository;</li><li><strong>hub-native records</strong>, such as append-only progress and runtime facts, whose durable meaning originates in the Hub.</li></ul>
<p>Later decisions also established that a central projection reads the pushed default branch in Forgejo. An arbitrary workstation checkout is a workspace, not the shared baseline. Unpushed local work may be represented only as an explicit preliminary overlay.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. File-backed work originates in the owning repository</h3>
<p>Workplans and their file-backed work items <strong>MUST originate as repository artefacts in the repository that owns the work</strong>. The Hub indexes and projects those artefacts but is not their origin.</p>
<p>This includes the workplan, embedded tasks, declared dependencies, residual handoffs, and durable governed decision artefacts when those are represented as files. No authoritative field of a file-backed record may exist solely in a Hub database.</p>
<p>The owning repository is identified by repository identity, not merely by a domain or topic. Domains and topics classify work; they do not own its source.</p>
<h3>2. Authority is explicit per persistence class</h3>
<p>Every record contract must declare whether the record is file-backed or hub-native. The same record must not be writable as authoritative in both places.</p>
<ul><li>For a <strong>file-backed record</strong>, the repository artefact is authoritative and the Hub row is derived state.</li><li>For a <strong>hub-native record</strong>, the Hub is authoritative. Progress events, messages, token events, run history, and similar runtime facts are not made fictional repository records merely to satisfy a rebuild slogan.</li></ul>
<p>The word <code>decision</code> is used by more than one subsystem. Architecture decisions and other governed decision artefacts remain files. A runtime decision event may be hub-native only where its schema says so explicitly; it does not replace the governed artefact.</p>
<p>This replaces the original blanket rejection of a hybrid architecture. The architecture is hybrid <strong>by declared record class</strong>, never ambiguous within one record.</p>
<h3>3. Forge is the central projection baseline</h3>
<p>For the shared central view, the source is the pushed default-branch state held by Forgejo, as decided by ADR-012. Every projected record must be attributable to its source repository, path, and commit.</p>
<p>A working copy remains the authoring workspace. Unpushed work may appear in the Hub only as an attributed preliminary overlay. It must not silently replace or be presented as the Forge-derived baseline. When its commit reaches Forge, the baseline absorbs it and the overlay retires.</p>
<h3>4. Mutations of file-backed state are file-first</h3>
<p>Creating or changing a file-backed work record means changing its repository artefact first. A convenience tool or API is conformant only when it performs a governed repository mutation and leaves a reviewable file and commit. Writing only the projected database row is not a durable update.</p>
<p>Direct Hub APIs remain valid for hub-native records. They may also provide diagnostics or propose repository patches, but a successful database PATCH is not evidence that a file-backed status changed.</p>
<h3>5. The rebuild guarantee applies to the projection, not the whole database</h3>
<p>Given a repository and a specific Forge commit, the system must be able to reconcile that repository's file-derived projection so that it is equivalent to the records derived from that commit. Reconciliation must be idempotent, verifiable, and scoped per repository; a fleet operation is iteration over the same per-repository operation.</p>
<p>Reconciliation retires file-derived records that no longer derive. It does not delete hub-native history attached to them. It must refuse and report a repository whose records exist only in the projection until those records have an explicit disposition. A Forge rebuild does not reconstruct preliminary overlays and must disclose their retirement before proceeding.</p>
<p>Therefore the <strong>file-derived projection is disposable</strong>. The database as a whole is not disposable when it also contains hub-native facts.</p>
<h3>6. Identity and lifecycle are delegated contracts</h3>
<p>This ADR does not define a second identity or lifecycle schema.</p>
<ul><li>Workplan and task identity follow ADR-007 as amended by ADR-011: global identity is namespace-aware, and derivable Hub identifiers are governed by that contract. Existing historical identifiers are grandfathered according to its migration rules.</li><li>Work-record kinds, locations, lifecycle values, and residual handling follow <code>canon/standards/work-record-types_v0.1.md</code> and <code>canon/standards/workplan-terminology-fleet_v0.1.md</code>.</li></ul>
<p>New normative text uses <code>workplan</code> and <code>work record</code>. <code>workstream</code> remains only as a metered compatibility term for legacy database and API surfaces.</p>
<h3>7. Reconciliation belongs at the repository boundary</h3>
<p>Repo Manager owns discovery, parsing, identity checks, and reconciliation for file-backed records. State Hub owns the projection and hub-native records. The implementation may distribute fetch and parse work, but it must preserve that authority boundary.</p>
<p>Legacy <code>create_workstream</code>, <code>create_task</code>, workstation-driven <code>sync-workplans</code>, and similarly named commands are not normative interfaces. They are conformant only if their current implementation satisfies decisions 3 and 4; otherwise they are transitional or retired.</p>
</section>
<section id="workplan-closure"><h2>Workplan closure</h2>
<p>A workplan cannot be marked <code>finished</code> merely by changing its Hub row. Before closure, the responsible worker must:</p>
<ol><li>review the source file and the projected view for unfinished tasks;</li><li>record completed and cancelled outcomes in the source task blocks using the canonical task lifecycle;</li><li>turn every actionable carry-forward item into a live work record with <code>origin: residual</code> and an <code>origin_ref</code>, or into another explicitly linked workplan;</li><li>set the source workplan to <code>finished</code>, update it, and commit the result;</li><li>publish the commit to Forge for the shared baseline and verify that the projection reconciles to that commit.</li></ol>
<p>A local reconciliation before push may expose preliminary state, but it does not complete step 5.</p>
<p>Automated stale-task cleanup must report file/projection drift. It may not silently cancel a file-backed task only in the database. An automated repair may change such a task only through the same governed repository mutation and commit path as any other file-backed change. Cleanup of hub-native records is governed by their own retention contract.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>Durable work remains inspectable, reviewable, and recoverable through Git.</li><li>The central view has an exact repository and commit provenance instead of reflecting whichever workstation synced most recently.</li><li>Reconciliation can be exercised per repository without destroying progress history or other hub-native evidence.</li><li>Multiple contributors share a published baseline while retaining an honest representation of preliminary work.</li><li>Service ownership is clearer: repositories own file-backed truth; the Hub owns runtime facts and projection services.</li></ul>
<h3>Negative</h3>
<ul><li>File-backed changes require a repository mutation and normally a push before they become shared baseline state.</li><li>Forge availability affects projection freshness, although it does not prevent local authoring.</li><li>Preliminary, stale, and retired projection states must be visible in APIs and user interfaces.</li><li>Git merge conflicts become the explicit conflict mechanism for simultaneous edits to the same authoritative artefact.</li><li>Tools that previously corrected only database state must be changed to emit a diagnostic or perform a governed repository update.</li></ul>
</section>
<section id="migration"><h2>Migration</h2>
<p>No bulk rename, UUID rewrite, or historical file rewrite is required by this amendment. Existing identifiers and legacy terminology retain the grandfathering rules of ADR-007, ADR-011, and the terminology standard.</p>
<p>Implementations must audit and retire DB-first creation, closure, and stale-task cleanup paths. Existing file-backed projection rows without a Forge source commit are migration state: they must be matched to a repository artefact or explicitly dispositioned before reset. Forge-derived reconciliation and preliminary overlays are implemented under ADR-012 rather than duplicated here.</p>
<p>The <code>accepted-1</code> publication remains the immutable historical revision. This document is <code>accepted-2</code>.</p>
</section>
<section id="alternatives-considered"><h2>Alternatives considered</h2>
<p><strong>Database-first with export.</strong> Rejected. Export can be skipped, making the reviewable artefact secondary and stale.</p>
<p><strong>Files only, with no projection database.</strong> Rejected. Cross-repository queries, runtime views, and append-only operational facts need indexed services.</p>
<p><strong>Treat every Hub record as reconstructible from Git.</strong> Rejected. This either loses runtime truth during rebuild or creates artificial files whose only purpose is mirroring a database.</p>
<p><strong>Let working copies push authoritative projection rows.</strong> Rejected by ADR-012. It makes the baseline depend on the last workstation to reconcile and cannot be audited against a shared commit.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ADR-003 — materialized and derived state</li><li>ADR-005 — cross-repository work ownership</li><li>ADR-007 — workplan identity and repository worker topology</li><li>ADR-010 — Hub authority and local cache model</li><li>ADR-011 — namespace-aware federation and reconciliation limits</li><li>ADR-012 — Forge projection source and preliminary overlay</li><li><code>canon/standards/work-record-types_v0.1.md</code> — work-record kinds, lifecycle, residuals, and reconciliation</li><li><code>canon/standards/workplan-terminology-fleet_v0.1.md</code> — canonical terminology</li><li><code>canon/values/foundational_values_v0.1.md</code> — local-first operation, auditability, and reversibility</li></ul>
</section><footer><span>CUST-ADR-001 · accepted-2 · accepted</span><span>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</span></footer></main></div></div></html>

242
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-002.html Normal file
View file

@ -0,0 +1,242 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
<meta name="policy-source-digest" content="6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec">
<title>Custodian Agent Runtime — v0.1 Bootstrap Design</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-002</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-03-12</span><span>generated from canonical source — do not edit</span></div><h1>Custodian Agent Runtime — v0.1 Bootstrap Design</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-09-12</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decisions"><span class="n">·</span>Decisions</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#deferred"><span class="n">·</span>Deferred</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>CUST-WP-0001 requires a first working skeleton of the Custodian as an acting agent: a loop that observes project state, reasons about it, and executes bounded write operations — without human interaction for each step.</p>
<p>The dependencies (llm-connect, operational Railiance infra) are now resolved. This ADR captures the five key architectural decisions for the v0.1 bootstrap.</p>
</section>
<section id="decisions"><h2>Decisions</h2>
<h3>D1 — Location: <code>runtime/</code> inside the-custodian (not a new repo)</h3>
<p><strong>Decision:</strong> The runtime lives under <code>the-custodian/runtime/</code> as a standalone Python package (<code>pyproject.toml</code>, own venv) rather than a new repository.</p>
<p><strong>Rationale:</strong> The runtime is tightly coupled to canon (reads constitution, memory) and the state-hub (its primary coordination layer). A separate repo adds friction with no v0.1 benefit. The existing <code>runtime/</code> scaffold confirms the original intent. Extraction to its own repo is deferred to when the runtime has stable boundaries and multiple consumers.</p>
<h3>D2 — OODA loop: single-pass synchronous CLI</h3>
<p><strong>Decision:</strong> One <code>run()</code> call = one complete Observe → Orient → Decide → Act cycle. Entry point is a CLI (<code>agent.py</code>) invoked manually or by a cron job.</p>
<pre>Observe — HTTP GET to state-hub: state summary or domain summary
Orient — Load constitution + build structured LLM context prompt
Decide — Single LLM call (via llm-connect) returns a JSON action plan
Act — Execute only sanctioned write operations from the plan</pre>
<p><strong>Rationale:</strong> Async event loops and daemons add operational complexity that v0.1 doesn't need. A single-pass CLI is testable, debuggable, and can be scheduled externally. The transition to an event-driven loop is Phase 2.</p>
<h3>D3 — LLM backend: ClaudeCodeAdapter by default</h3>
<p><strong>Decision:</strong> The runtime uses <code>llm_connect.ClaudeCodeAdapter</code> as its default LLM backend (shells out to <code>claude --print</code>). Provider is configurable via <code>--llm</code> flag to support <code>gemini</code>, <code>openrouter</code>, or <code>openai</code>.</p>
<p><strong>Rationale:</strong> <code>ClaudeCodeAdapter</code> requires no API key and honours the Local-First value (V2). All current deployments have Claude Code available. The llm-connect abstraction means switching providers is a one-line change.</p>
<h3>D4 — Action constraint: three sanctioned write operations only</h3>
<p><strong>Decision:</strong> The agent may execute exactly three state-hub write operations without human approval:</p>
<ol><li><code>add_progress_event</code> — append an observation to the event log</li><li><code>update_task_status</code> — mark a task done/in_progress (reversible)</li><li><code>flag_for_human</code> — raise an intervention flag (escalation, not action)</li></ol>
<p>All other operations (create workstream, record decision, resolve decision, write to canon) require human approval before execution.</p>
<p><strong>Rationale:</strong> Constitution §3/§4 require bounded agency. The three operations are either append-only (progress events), reversible (task status), or explicitly escalating (flag). They cannot produce irreversible harm.</p>
<h3>D5 — LLM response format: JSON block in markdown</h3>
<p><strong>Decision:</strong> The LLM is prompted to return a Markdown response with a fenced ```json block containing the structured action plan:</p>
<pre>{
&quot;observations&quot;: [&quot;...&quot;],
&quot;progress_events&quot;: [
{&quot;summary&quot;: &quot;...&quot;, &quot;workstream_id&quot;: &quot;...&quot;, &quot;event_type&quot;: &quot;note&quot;}
],
&quot;tasks_to_update&quot;: [
{&quot;task_id&quot;: &quot;...&quot;, &quot;status&quot;: &quot;done&quot;}
],
&quot;tasks_to_flag&quot;: [
{&quot;task_id&quot;: &quot;...&quot;, &quot;note&quot;: &quot;...&quot;}
]
}</pre>
<p>The surrounding Markdown is preserved as a human-readable reasoning trace and written to <code>memory/working/</code> as a session note.</p>
<p><strong>Rationale:</strong> JSON blocks are robust to extraction (delimited), LLMs produce them reliably with clear instructions, and the surrounding prose gives Bernd an auditable reasoning trace without requiring a separate reasoning step.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>runtime/</code> becomes a standalone Python package; <code>make agent-run DOMAIN=x</code> invokes it.</li><li>The runtime has no DB schema changes and no new API endpoints — it is a pure client of the existing state-hub HTTP API.</li><li>Autonomous actions are limited to append-only writes and escalations. Any expansion of the action surface requires a new ADR and human approval.</li><li>The v0.1 loop is single-user (Bernd). Multi-agent expansion is Phase 2+.</li></ul>
</section>
<section id="deferred"><h2>Deferred</h2>
<ul><li>Async event loop / daemon mode (Phase 2)</li><li>RAG over canon (Phase 1 roadmap item)</li><li>Tool adapters beyond state-hub HTTP (planned in <code>runtime/tool_adapters/</code>)</li><li>Deployment on Railiance k3s as a scheduled CronJob</li></ul>
</section><footer><span>CUST-ADR-002 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-002-custodian-agent-runtime-design.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>

248
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-003.html Normal file
View file

@ -0,0 +1,248 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d3c6f13d7aed9784b6f31c23d2b2777668493ba5">
<meta name="policy-source-digest" content="fcb49719e2b85b9120c0bd5bebd5e82748ca713f16b44951c028b60205514e2b">
<title>Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-003</span> <span class="stat">accepted · accepted-2</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-003-materialized-derived-state.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#pattern-name"><span class="n">·</span>Pattern Name</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#implementation-checklist"><span class="n">·</span>Implementation Checklist</a></li><li><a href="#current-implementations"><span class="n">·</span>Current Implementations</a></li><li><a href="#planned-applications"><span class="n">·</span>Planned Applications</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted, and <strong>partially superseded by <code>ADR-012</code></strong> (accepted 2026-08-25). Decision 2's fingerprint composition is invalidated in part; decision 5's rebuild principle is given a concrete source and a required operation. See the notes on each.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The Custodian State Hub is a <strong>read model</strong> (CQRS terminology) — its data is fully derivable from canonical sources that live in repositories and the filesystem. No state-hub data is authoritative; it is always a derived view of what the repos contain.</p>
<p>Several categories of data fit this description:</p>
<div class="scroll"><table><thead><tr><th>Data</th><th>Canonical source</th><th>State-hub table</th></tr></thead><tbody><tr><td>SBOM dependencies</td><td><code>uv.lock</code>, <code>package-lock.json</code>, etc.</td><td><code>sbom_entries</code></td></tr><tr><td>Third-party service declarations</td><td><code>tpsc.yaml</code></td><td><code>tpsc_entries</code></td></tr><tr><td>Provided capabilities</td><td><code>SCOPE.md</code> <code>capability</code> blocks</td><td><code>capability_catalog</code></td></tr><tr><td>DoI compliance tier</td><td>14 criteria across repo files + DB</td><td><code>doi_cache</code></td></tr><tr><td>Workplan task status</td><td><code>workplans/*.md</code></td><td><code>tasks</code></td></tr></tbody></table></div>
<p>Early implementations either recomputed this data on every request (too slow) or ingested it once without invalidation (stale data goes undetected). Neither is acceptable for a system designed to give accurate, fast orientation.</p>
<p>The <code>doi_cache</code> table, introduced in CUST-WP-0024, demonstrated a pattern that solves both problems. This ADR formalises that pattern and mandates its use for all repo-sourced derived data.</p>
</section>
<section id="pattern-name"><h2>Pattern Name</h2>
<p><strong>Materialized Derived State with Fingerprint Invalidation.</strong></p>
<p>This pattern is known under several names in the literature:</p>
<ul><li><strong>Materialized View</strong> (SQL standard, PostgreSQL) — the stored result of a query or computation, refreshed on demand when source data changes.</li><li><strong>Derived Data Store</strong> (Kleppmann, <em>Designing Data-Intensive Applications</em>, Ch. 3 &amp; 11) — a system whose entire dataset can be rebuilt from upstream sources; it is never the source of truth.</li><li><strong>Read Model / Projection</strong> (CQRS / Event Sourcing) — a pre-computed view maintained alongside a write model, rebuilt when relevant events occur.</li><li><strong>Fingerprint-based / Content-addressed invalidation</strong> — analogous to HTTP ETags: a cache entry is valid as long as a composite hash/timestamp of its inputs matches the stored value.</li></ul>
<p>The State Hub already documents itself as a read model. This ADR extends that principle to specify <em>how</em> the read model stays fresh.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. All repo-sourced derived data MUST be materialised in the DB</h3>
<p>Data computed from repository files or repo records must be stored in a dedicated table rather than recomputed per request. Direct computation on every API call is only permissible for development tooling or when explicitly forced by the caller.</p>
<h3>2. Each materialised table MUST carry a <code>fingerprint</code> column</h3>
<p>The fingerprint is a deterministic string encoding all inputs that affect the computed result. It is compared on each read; if unchanged, the stored result is returned without recomputation. If changed, the result is recomputed and the stored value is updated.</p>
<p><strong>Fingerprint composition rules:</strong></p>
<ul><li>Include the <code>updated_at</code> timestamp of every DB record that feeds the computation (repo record, related domain, goals, snapshots).</li><li>Include the <code>mtime</code> (filesystem modification time) of every file that feeds the computation (<code>SCOPE.md</code>, <code>CLAUDE.md</code>, lockfiles, <code>tpsc.yaml</code>, etc.).</li></ul>
<div class="rule-quote"><p><strong>Invalidated in part 2026-08-25 by <code>ADR-012</code> decisions 1 and 2.</strong> Filesystem <code>mtime</code> is not a property of the source. It differs between machines, changes on a fresh clone, and says nothing about content — so a fingerprint built from it describes one workstation's filesystem rather than the repository. Under <code>ADR-012</code> the projection derives from the forge, and the commit that produced a record is both the correct input and the auditable one. This was not merely theoretical drift. <code>git_fingerprint</code> for <code>the-custodian</code> held the repository's <em>initial</em> commit while <code>last_state_synced_at</code> was minutes old: the field meant to identify what a projection reflects was wrong by the entire history of the repository, and nothing noticed. Replace <code>mtime</code> inputs with the source commit.</p></div>
<ul><li>Join all components with <code>|</code> as a pipe-separated string — no hashing needed since the string is compared by equality, not transmitted to clients.</li><li>If a file is absent, encode <code>filename:absent</code> rather than omitting it, so file creation also triggers invalidation.</li></ul>
<p><strong>Reference implementation:</strong> <code>state-hub/api/doi_engine.py::compute_fingerprint()</code></p>
<h3>3. Every materialised endpoint MUST support <code>?force_refresh=true</code></h3>
<p>Callers must always be able to bypass the cache and trigger a fresh computation. This is the escape hatch for debugging, post-ingest verification, and scheduled background refresh jobs.</p>
<h3>4. Writes to source data SHOULD update the repo record's <code>updated_at</code></h3>
<p>Operations that change source data (SBOM ingest, TPSC ingest, capability ingest) must ensure <code>managed_repos.updated_at</code> is refreshed so the fingerprint detects the change on the next read. Where data lives in a related table (e.g. <code>tpsc_snapshots</code>), the fingerprint must include that table's <code>max(snapshot_at)</code> directly rather than relying on the repo record.</p>
<h3>5. The DB is never the source of truth — the rebuild principle holds</h3>
<p>Per ADR-001, the state-hub must be rebuildable from scratch by re-ingesting all canonical sources. Materialised tables are <strong>caches</strong>, not records of authority. They may be wiped and repopulated at any time without data loss.</p>
<div class="rule-quote"><p><strong>Given concrete form 2026-08-25 by <code>ADR-012</code> decision 7.</strong> This principle was correct and, until now, never exercised — an untested rebuild path is an assumption rather than a capability, and this one was believed for long enough that a divergence survived seven weeks behind it. <code>ADR-012</code> requires the reconstruction to exist as a routine operation, scoped per repository, sourced from the forge, and verifiable against it. The claim "without data loss" also needs its precondition stated: it holds only while the rule immediately below does. On 2026-08-25, 111 work records existed only in the hub, so a rebuild at that moment would have destroyed them. <code>ADR-012</code> therefore requires reset to refuse, per repository, when records have no counterpart in the forge.</p></div>
<p>This means:</p>
<ul><li>No materialised table may be the only copy of any information.</li><li>Schema migrations that wipe a materialised table are safe and expected.</li><li>Background jobs that periodically re-ingest all repos are valid and encouraged.</li></ul>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li><strong>Fast reads in steady state</strong> — after the first computation, subsequent reads hit the DB with no filesystem or subprocess overhead.</li><li><strong>Accurate on change</strong> — fingerprint invalidation ensures stale data is never silently served; the cache refreshes exactly when needed.</li><li><strong>Debuggable</strong> — <code>force_refresh=true</code> and <code>checked_at</code> timestamps make it easy to see when a value was last computed and to trigger a recheck.</li><li><strong>Consistent with the read model principle</strong> — the pattern makes explicit what was always implied: state-hub data is derived, not authoritative.</li></ul>
<h3>Negative / Trade-offs</h3>
<ul><li><strong>First-call latency</strong> — cache misses are expensive (filesystem reads, subprocess calls, HTTP self-calls). Mitigated by pre-warming caches at startup or after ingest.</li><li><strong>Fingerprint completeness</strong> — if a new input is added to a computation and not added to the fingerprint, stale results will be silently returned. The fingerprint must be kept in sync with the computation.</li><li><strong>Filesystem dependency</strong> — file mtimes are volatile (e.g. <code>git checkout</code> rewrites mtimes). In practice this means a cache miss after every checkout, not a correctness problem.</li></ul>
</section>
<section id="implementation-checklist"><h2>Implementation Checklist</h2>
<p>When adding a new category of repo-sourced derived data:</p>
<ul><li>[ ] Create a <code>_cache</code> or <code>_snapshots</code> table with <code>fingerprint</code> and <code>checked_at</code> columns.</li><li>[ ] Implement <code>compute_fingerprint(repo, ...)</code> in the relevant module.</li><li>[ ] Add <code>?force_refresh=true</code> query parameter to the read endpoint.</li><li>[ ] Ensure the ingest script (or write path) touches <code>managed_repos.updated_at</code> or includes a related table's <code>max(timestamp)</code> in the fingerprint.</li><li>[ ] Verify the cache can be wiped and repopulated without data loss.</li><li>[ ] Document which inputs are included in the fingerprint in a comment alongside <code>compute_fingerprint</code>.</li></ul>
</section>
<section id="current-implementations"><h2>Current Implementations</h2>
<div class="scroll"><table><thead><tr><th>Derived data</th><th>Table</th><th>Fingerprint inputs</th><th>Force-refresh</th></tr></thead><tbody><tr><td>DoI compliance tier</td><td><code>doi_cache</code></td><td><code>repo.updated_at</code>, <code>max(tpsc_snapshots.snapshot_at)</code>, <code>max(repo_goals.updated_at)</code>, <code>mtime(SCOPE.md)</code>, <code>mtime(CLAUDE.md)</code>, <code>mtime(tpsc.yaml)</code></td><td><code>?force_refresh=true</code></td></tr></tbody></table></div>
</section>
<section id="planned-applications"><h2>Planned Applications</h2>
<div class="scroll"><table><thead><tr><th>Derived data</th><th>Table (proposed)</th><th>Notes</th></tr></thead><tbody><tr><td>SBOM summary stats</td><td><code>sbom_cache</code></td><td>Fingerprint: <code>max(sbom_snapshots.snapshot_at)</code></td></tr><tr><td>Capability declarations</td><td><code>capability_cache</code></td><td>Fingerprint: <code>mtime(SCOPE.md)</code>, <code>repo.updated_at</code></td></tr><tr><td>Workplan status summary</td><td>Already handled by consistency checker</td><td>Fingerprint: workplan file mtimes</td></tr></tbody></table></div>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ADR-001: Workplans and Work Items Are Repository Artefacts</li><li>ADR-002: Custodian Agent Runtime Design</li><li><code>state-hub/api/doi_engine.py</code> — reference implementation</li><li><code>state-hub/api/models/doi_cache.py</code> — reference schema</li><li><code>state-hub/migrations/versions/k8f9a0b1c2d3_doi_cache.py</code> — reference migration</li></ul>
</section><footer><span>CUST-ADR-003 · accepted-2 · accepted</span><span>the-custodian · canon/architecture/adr-003-materialized-derived-state.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</span></footer></main></div></div></html>

236
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-004.html Normal file
View file

@ -0,0 +1,236 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
<meta name="policy-source-digest" content="3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557">
<title>Connectivity-First Network Posture for Custodian Infrastructure</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-004</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-03-26</span><span>generated from canonical source — do not edit</span></div><h1>Connectivity-First Network Posture for Custodian Infrastructure</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-09-26</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#rationale"><span class="n">·</span>Rationale</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-rejected"><span class="n">·</span>Alternatives Rejected</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The Custodian infrastructure spans multiple machines: a primary workstation, a shared compute node (COULOMBCORE), and Railiance cluster nodes. Agents running on remote machines need to reach the state-hub API and MCP server, which live on the workstation. Human operators and agents also need to reach remote services (k3s API, Gitea, Temporal) from the workstation.</p>
<p>Two network postures were considered for how these components communicate:</p>
<p><strong>Option A — Connectivity-first:</strong> Components are connected by default via controlled, observable access paths (reverse SSH tunnels managed by ops-bridge). Isolation is added selectively where there is a specific threat model or compliance reason to do so.</p>
<p><strong>Option B — Isolation-first (zero-trust):</strong> No component trusts any other by default. Every connection requires mutual authentication, short-lived credentials, and explicit authorisation at the point of use. Connectivity is earned, not assumed.</p>
<p>This decision is architectural policy — it governs how ops-bridge tunnels are designed, how agent-to-hub communication works, and how new infrastructure components are onboarded.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Connectivity-first, with isolation as a deliberate option.</strong></p>
<p>The default posture for Custodian infrastructure is: components that need to work together are connected. Access paths are explicit, observable, and managed (via ops-bridge), but they are persistent by default rather than ephemeral. Isolation is introduced where there is a specific, articulated reason — not as a blanket policy applied uniformly.</p>
</section>
<section id="rationale"><h2>Rationale</h2>
<h3>1. Scale and team size</h3>
<p>The infrastructure is operated by a single human and a bounded set of automation agents. The overhead of zero-trust (credential rotation, SPIFFE/SPIRE identity, mTLS everywhere, short-lived tokens per request) is disproportionate for this scale. It would consume significant operational complexity without a commensurate security return.</p>
<h3>2. Observability over perimeter hardening</h3>
<p>The primary security control at this scale is <strong>observability</strong>: knowing what connected, when, from where, and what it did. ops-bridge provides this — every tunnel is named, actor-attributed, health-checked, and audited. A perimeter of invisible short-lived connections would actually reduce observability.</p>
<h3>3. The threat model does not require zero-trust today</h3>
<p>The main threats are:</p>
<ul><li>A runaway agent consuming resources (mitigated by nproc/memory cgroups)</li><li>A compromised workload reaching state-hub and corrupting state (mitigated by the read-model design of state-hub — write surface is narrow and sanctioned)</li><li>An external attacker reaching internal services (mitigated by the tunnels being reverse SSH — no inbound ports exposed)</li></ul>
<p>Zero-trust would address a different threat model: lateral movement between hostile tenants, or untrusted code running in the same environment as sensitive data. That is not the current situation.</p>
<h3>4. Degrade-gracefully requires persistent connectivity</h3>
<p>The Custodian's foundational value of <strong>local-first, degrade-gracefully</strong> requires that agents can orient themselves even when some connections are slow or partially degraded. Ephemeral connectivity (zero-trust tokens, service mesh sidecars) introduces additional failure modes that conflict with graceful degradation. Persistent SSH tunnels with auto-reconnect are more resilient to intermittent conditions.</p>
<h3>5. Isolation remains the right choice in specific cases</h3>
<p>Connectivity-first does not mean no isolation. The following cases call for explicit isolation and are handled separately:</p>
<ul><li><strong>Tenant separation</strong> (when/if multi-user or multi-org) — each tenant gets its own network segment</li><li><strong>Privileged execution</strong> — CI runners and agent actions with write access to production systems run in ephemeral, isolated environments (per the Privileged Execution Control standard)</li><li><strong>Secrets</strong> — credentials are never transmitted over tunnels in plaintext; age-encrypted at rest, SOPS for config</li></ul>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Immediate</h3>
<ul><li>ops-bridge tunnels are <strong>persistent</strong> (max_attempts: 0, auto-reconnect) and are treated as infrastructure, not one-off connections</li><li>Agents on remote machines check tunnel health at session start and restore dropped tunnels before accessing state-hub (documented in global CLAUDE.md)</li><li>New infrastructure components are onboarded with a named tunnel entry in <code>~/.config/bridge/tunnels.yaml</code> — not ad-hoc SSH commands</li></ul>
<h3>Deferred</h3>
<ul><li>If the infrastructure grows to multi-tenant or multi-operator, this decision should be revisited. At that point, isolation-first becomes proportionate.</li><li>If a security audit identifies a specific lateral movement risk, targeted isolation (network policy, mTLS for that service) is the response — not a wholesale posture change.</li></ul>
</section>
<section id="alternatives-rejected"><h2>Alternatives Rejected</h2>
<h3>Zero-trust / isolation-first</h3>
<p>Rejected for current scale. The operational overhead (credential lifecycle, service mesh, mutual TLS) is disproportionate, observability would decrease, and the threat model does not require it. Noted for re-evaluation at multi- tenant scale.</p>
<h3>VPN (WireGuard / Tailscale)</h3>
<p>Considered briefly. VPN would solve the connectivity problem but introduces a persistent network layer that all traffic traverses, reducing the explicitness of individual access paths. ops-bridge tunnels are per-service and per-actor, which gives better observability and blast-radius control. VPN is not ruled out as a future complement but is not the primary approach.</p>
<h3>Ad-hoc SSH (no ops-bridge)</h3>
<p>The pre-ops-bridge approach. Rejected because it has no health checks, no actor attribution, no audit log, and requires manual intervention to restore. ops-bridge formalises the same SSH tunnel pattern with operational discipline.</p>
</section><footer><span>CUST-ADR-004 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-004-connectivity-first-network-posture.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>

225
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-005.html Normal file
View file

@ -0,0 +1,225 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
<meta name="policy-source-digest" content="13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f">
<title>Cross-Repo Workplans Live in Dedicated Project Repos</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-005</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-06-22</span><span>generated from canonical source — do not edit</span></div><h1>Cross-Repo Workplans Live in Dedicated Project Repos</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-12-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#lifecycle"><span class="n">·</span>Lifecycle</a></li><li><a href="#naming"><span class="n">·</span>Naming</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted.</p>
</section>
<section id="context"><h2>Context</h2>
<p>ADR-001 established that workplans and work items originate as files in the repository that owns them, so the State Hub can rebuild its coordination state from repo-owned files alone. The repo-classification redesign (<code>CUST-WP-0050</code>) takes the next step: it makes the <strong>repo the primary anchor</strong> for a workplan (<code>workstreams.repo_id</code> becomes required) and <strong>derives</strong> the market-domain from the repo's <code>.repo-classification.yaml</code> rather than maintaining a separate <code>topic</code>/<code>domain</code> spine. Repos are the most stable, git-managed entities in the ecosystem; binding to them is the most durable anchor available.</p>
<p>This raises an unavoidable question: <strong>what anchors a genuinely cross-repo workplan?</strong> Some efforts coordinate change across many repositories — ecosystem migrations, the FOS hub bootstrap (<code>CUST-WP-0025</code>), or <code>CUST-WP-0050</code> itself, which touches ~70 repos. If every workplan must bind to exactly one repo:</p>
<ul><li>binding it to one arbitrary product repo misrepresents the work and pollutes that repo's history with coordination it does not own;</li><li>leaving it unbound reintroduces the hub-only orphan that ADR-001 forbids;</li><li>modelling it as an array of <code>repo_id</code>s breaks the "one stable anchor, clear ownership, clean lifecycle" property and complicates the rebuild principle.</li></ul>
</section>
<section id="decision"><h2>Decision</h2>
<p>**A complex cross-repo workplan gets its own dedicated <em>project repo</em>.**</p>
<ul><li>The project repo is a real, git-managed repository. It owns the coordination workplan, its tasks, its decisions, and any cross-cutting artefacts. It is the required <code>repo</code> anchor for that workplan, satisfying the repo-primary-anchor rule without distorting any single product repo.</li><li>The project repo is classified under the Repo Classification Standard, normally <code>category: project</code>. Its <code>domain</code>/tags describe the effort, not any one product.</li><li><strong>Implementation still happens in the product repos.</strong> Changes land via per-repo workplans and PRs in the repos being modified. The project repo <em>coordinates and references</em> that work (via dependency edges / links); it does not own product code.</li><li><strong>On completion, the project repo is retired to archive — not deleted.</strong> Its durable results live on in the product repos it modified (the merged changes are the outcome). The archived project repo remains as an immutable provenance record of the coordination, consistent with the append-only-memory value.</li></ul>
<p>The project repo's completion record MUST list the product repos it modified and link to the merged PRs/commits, so the trail survives archival.</p>
</section>
<section id="lifecycle"><h2>Lifecycle</h2>
<pre>draft → active → completed → archived</pre>
<ul><li><strong>active</strong> — work in progress; workplan <code>status: active</code>; repo live in Gitea and registered in the Hub.</li><li><strong>completed</strong> — all tasks done; completion record written (modified repos + links).</li><li><strong>archived</strong> — repo archived in Gitea and <code>status: archived</code> in the Hub. The workplan moves to <code>workplans/archived/</code> per the workplan convention. Results persist in the product repos; the project repo is read-only history.</li></ul>
</section>
<section id="naming"><h2>Naming</h2>
<p>Project repos MUST use the <code>prj-&lt;kebab-slug&gt;</code> prefix.</p>
<p>Exact naming, required files (<code>GOAL.md</code> instead of durable-product <code>INTENT.md</code>), authority boundary, residual handoff, and archive procedure are defined in:</p>
<p><code>canon/standards/project-repository-flavor_v0.1.md</code></p>
<p>That standard closes the naming open question previously deferred to <code>CUST-WP-0050</code> (D1a). The illustrative <code>proj-</code> form mentioned in earlier drafts is not used for new repositories.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><strong>Pro:</strong> every workplan — including cross-repo ones — has a stable, git-managed anchor; no hub-only orphans; the rebuild principle (ADR-001) holds.</li><li><strong>Pro:</strong> the classification standard applies uniformly; project repos are just repos with <code>category: project</code>.</li><li><strong>Pro:</strong> clean, explicit lifecycle; results are never lost on retirement because they live in the modified product repos.</li><li><strong>Con:</strong> proliferation of short-lived repos; requires discipline around the naming and archival convention.</li><li><strong>Con:</strong> cross-references between the project repo and the product repos it modified must be recorded deliberately, or the provenance trail degrades after archival.</li><li><strong>Con:</strong> judgement is required on <em>when</em> an effort is "complex enough" to merit a project repo versus a single-repo workplan; small cross-cutting changes should not spawn a repo.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<ul><li><strong>Bind to a "lead" product repo.</strong> Rejected: distorts that repo's history and creates ambiguous ownership.</li><li><strong>Keep an optional hub-only topic for cross-repo coordination.</strong> Rejected: reintroduces the soft, non-git-managed spine that <code>CUST-WP-0050</code> removes and ADR-001 discourages.</li><li><strong>Multi-anchor workplan (array of repo_ids, no primary).</strong> Rejected: breaks single-anchor simplicity, ownership clarity, and lifecycle modelling.</li></ul>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ADR-001 — Workplans and Work Items Are Repository Artefacts</li><li><code>CUST-WP-0050</code> — Repo Classification &amp; State Hub Registration Redesign (D1)</li><li><code>canon/standards/repo-classification-standard_v1.0.md</code></li></ul>
</section><footer><span>CUST-ADR-005 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-005-cross-repo-workplans-project-repos.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>

253
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-006.html Normal file
View file

@ -0,0 +1,253 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
<meta name="policy-source-digest" content="a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823">
<title>Canon Federation and Concept Ownership Across InfoTech and Commerce</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-006</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-17</span><span>generated from canonical source — do not edit</span></div><h1>Canon Federation and Concept Ownership Across InfoTech and Commerce</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2027-02-17</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#resolutions"><span class="n">·</span>Resolutions</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-17. All seven ownership questions are resolved (see Resolutions); content may now move under <code>CFED-WP-0001</code>.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The ecosystem currently runs two independent canons in the same market domain (<code>infotech</code>), with <strong>no cross-reference in either direction</strong>:</p>
<ul><li><code>info-tech-canon</code> — InfoTechCanon, v0.6.0, status <code>service-baseline</code>. Kernel + 12 models + 3 standards, with declared concept ownership per model, an orthogonality rule ("standards can import but not redefine each other"), and a live CLI/JSON/API surface built on <code>infospace-bench</code>.</li><li><code>identity-canon</code> — documentation-only research repo, category <code>research</code>. Three <code>IDENTITY-WP-*</code> workplans, all <code>finished</code>; no active work since the commercial-identity research pass. ~60 concepts in <code>canon/CanonicalGlossary.md</code>.</li></ul>
<p>Two problems follow.</p>
<p><strong>Concept-ownership collision.</strong> <code>InfoTechCanonOrganizationModel</code> (<code>:55</code>) declares ownership of <code>Actor, Person, Organization, OrganizationalUnit, Team, Group, Role, Position, Membership, Assignment, Responsibility, Authority, Accountability</code>. <code>InfoTechCanonAccessControlModel</code> (<code>:106</code>) declares <code>Subject, Principal, AccessRole, Permission, ...</code>. identity-canon independently defines <code>Actor, Natural Person, Collective Actor, Organization, Group, Role, Membership Relationship, Authenticated Subject, Authorization Principal</code>. Two canons claim the same concepts — exactly what InfoTechCanon's orthogonality rule exists to prevent.</p>
<p><strong>An unowned gap.</strong> <code>InfoTechCanonAccessControlModel</code> (<code>:214</code>, "Boundary with Identity and Authentication") explicitly pushes identity provisioning, authentication factors, identity proofing, and account lifecycle out of scope, and <code>:41</code> does the same for generic organization modelling. So <code>Account, Identity Record, Identifier, Credential, Claim, Persona, Tenant, Realm, Synonymity Assertion, Assurance Level</code> belong to no model at all.</p>
<p><strong>Business semantics are accumulating in the wrong places.</strong> Roughly a third of identity-canon's glossary is not identity but counterparty/commercial modelling (<code>Legal Entity, Beneficial Owner, Customer, Vendor, Commercial Commitment, Payment Mandate, Pipeline Pursuit, Counterparty Assurance Gradient, ...</code>) — hence the repo's <code>government</code> secondary domain. Independently, <code>info-tech-canon/demand/CapabilityProvisionEconomics.md</code> (status <code>accepted</code>, 2026-08-15) records procurement and economics demand arriving in <code>ITC-CAP</code> from consumer <code>resource-control</code>, domain <code>financials</code>. Two unrelated donors pushing commercial semantics into technical canon is a domain boundary, not a coincidence. InfoTechCanon's own Purpose/Demand extension names this <code>ScopePressure</code>.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. Three canons, federated by declared ownership.</strong></p>
<div class="scroll"><table><thead><tr><th>Canon</th><th>Owns</th><th>Repo</th></tr></thead><tbody><tr><td>Custodian canon</td><td>ecosystem-normative governance: constitution, values, standards, ADRs, charters</td><td><code>the-custodian/canon/</code></td></tr><tr><td>InfoTechCanon</td><td>semantics of information-processing systems</td><td><code>info-tech-canon</code></td></tr><tr><td>CommerceCanon</td><td>counterparty and commercial-relationship semantics</td><td><code>commerce-canon</code></td></tr></tbody></table></div>
<p>Canons import but do not redefine each other's concepts, applying InfoTechCanon's existing orthogonality rule one level up.</p>
<p><strong>2. <code>identity-canon</code> is renamed to <code>commerce-canon</code>, in place.</strong> Git history, State Hub registration, <code>.repo-classification.yaml</code>, and the finished <code>IDENTITY-WP-*</code> workplans are retained as provenance for the commercial content that stays. Identity content emigrates; nothing is archived. Structure follows <code>info-tech-canon</code> (<code>canon.yaml</code>, <code>infospace/</code> with kernel/models/standards, <code>assimilation/</code>, <code>mappings/</code>, <code>profiles/</code>) per <code>InfoTechCanonRepositoryLayoutStandard</code>.</p>
<p><strong>3. Identity becomes an InfoTechCanon model</strong>, at <code>infospace/models/identity/InfoTechCanonIdentityModel.md</code> (<code>itc-ident</code>), importing rather than redefining upstream concepts. This fills the gap <code>InfoTechCanonAccessControlModel:214</code> leaves open.</p>
<p><strong>4. Concept ownership is assigned as follows.</strong></p>
<p><em>Imported by <code>itc-ident</code>, owned by <code>itc-org</code>:</em> <code>Actor</code> · <code>Natural Person</code> → <code>Person</code> · <code>Artificial Agent</code> → <code>Agent</code> · <code>Organization</code> · <code>Group</code> · <code>Role</code> · <code>Membership Relationship</code> → <code>Membership</code></p>
<p><em>Imported by <code>itc-ident</code>, owned by <code>itc-access</code>:</em> <code>Authenticated Subject</code> → <code>Subject</code> · <code>Authorization Principal</code> → <code>Principal</code></p>
<p>This follows identity-canon's own design principles: P1 makes <code>Actor</code> the participation root (owned upstream by <code>itc-org</code>), and P6 "Keep Authorization Projections Separate" already treats subject/principal as projections rather than identity-owned definitions.</p>
<p><em>Owned by <code>itc-ident</code> (new):</em> <code>Account</code> · <code>Service Account</code> · <code>Identity Record</code> · <code>Identifier</code> · <code>Scoped Identifier</code> · <code>Pseudonymous Identifier</code> · <code>Credential</code> · <code>Claim</code> · <code>Profile</code> · <code>Persona</code> · <code>Tenant</code> · <code>Realm</code> · <code>Synonymity Assertion</code> · <code>Lifecycle State</code> · the actor-linking relationship taxonomy (<code>Relationship</code>, <code>Affiliation</code>, <code>Following</code>, <code>Representation</code>, <code>Delegation</code>, <code>Administration</code>, <code>Trust</code>) · convenience terms <code>User</code>, <code>Subscriber</code></p>
<p><em>Owned by <code>commerce-canon</code>:</em> <code>Legal Entity</code> · <code>Legal Person</code> · <code>Beneficial Owner</code> · <code>Beneficial Ownership Relationship</code> · <code>Beneficial Ownership Exemption</code> · <code>Customer</code> · <code>Vendor</code> · <code>Commercial Relationship</code> · <code>Commercial Commitment</code> · <code>Payment Instrument Reference</code> · <code>Payment Mandate</code> · <code>Pipeline Pursuit</code> · <code>Commercial Record</code> · <code>Counterparty Assurance Gradient</code> · <code>Reputation Signal</code> · <code>Performance Evidence</code> · <code>Registry Identifier</code> · <code>Proxy Commercial Identifier</code> · convenience terms <code>Reputation</code>, <code>Customer Account</code></p>
<p><em>Owned by <code>itc-evid</code>, the evidence model (see R3, R5, R7):</em> <code>Evidence</code> · <code>Evidence Source</code> · <code>Adjudication Outcome</code></p>
<p>Identifier subtypes demonstrate the intended pattern: <code>itc-ident</code> owns <code>Identifier</code>; <code>commerce-canon</code> owns <code>Registry Identifier</code> and <code>Proxy Commercial Identifier</code> as specializations of it.</p>
<p><strong>5. CommerceCanon grows by demand signal, not speculative authoring.</strong> New content enters through the mechanism InfoTechCanon already runs — a demand signal with named consumer evidence (see <code>demand/</code>). Plausible future consumers (<code>fin-hub</code>, <code>target-revenue</code>, <code>adaptive-pricing</code>, <code>qonto-assistant</code>) must pull; the canon does not push.</p>
<p><strong>6. The Federated Organization Standard stays in Custodian canon.</strong> <code>canon/standards/federated-organization-standard_v1.0.md</code> is ecosystem-normative organizational architecture, human-gated — not commercial vocabulary. If it ever moves, it becomes an InfoTechCanon organization standard, not a CommerceCanon one.</p>
</section>
<section id="resolutions"><h2>Resolutions</h2>
<p>The six collisions listed at draft time, resolved 2026-08-17. Two were settled by evidence already present in the models rather than by argument.</p>
<p><strong>R1 — <code>Scope</code>: owned by <code>itc-ident</code>.</strong> There is no head-on collision: <code>itc-access</code> owns <code>ResourceScope</code> (<code>:717</code>, "the boundary within which access applies"), a narrower concept, not a general <code>Scope</code>. <code>itc-ident</code> owns the general concept, keeping it with <code>Tenant</code> and <code>Realm</code> — <code>Tenant</code> is defined as "an administrative or isolation scope", so separating it from its genus would split a definition from the concept it depends on. <code>itc-access</code> keeps <code>ResourceScope</code> as a refinement.</p>
<p>If <code>landscape</code> or <code>information-space</code> later need general scoping, promote <code>Scope</code> to the kernel <strong>on that demand signal</strong>, not pre-emptively.</p>
<p><strong>R2 — <code>Assurance Level</code>: owned by <code>itc-ident</code>, distinct from governance assurance.</strong> A false collision. <code>itc-gov</code> owns <code>AssuranceCase</code> (<code>:1178</code>, a structured argument that a claim is justified) and <code>AssuranceConclusion</code> (<code>:1184</code>). identity's <code>Assurance Level</code> is NIST SP 800-63-4 IAL/AAL/FAL — graded confidence metadata on credentials, bindings, and federation assertions. They share an English word and nothing else. Both models carry a disambiguation note, because the word will keep causing this.</p>
<p>Design principle P12 ("Distinguish Assurance Dimensions") carries over: IAL, AAL, and FAL must not be collapsed into a single "trust level" on an account.</p>
<p><strong>R3 — <code>Evidence</code> and <code>Evidence Source</code> are a general pair, owned together, and not by commerce.</strong> They are not competing definitions of one concept:</p>
<ul><li><strong>Evidence Source</strong> — an addressable information container: a document, file, or other artifact identifiable by URI.</li><li><strong>Evidence</strong> — a distinct information item, textual or descriptive, drawn from a source: a quotation, an extracted value, a specific assertion.</li></ul>
<p>Both may carry commentary. Which evidence is captured from a source depends on the interest being served.</p>
<p>Worked example: an invoice PDF is an Evidence Source; the amount, the issuer, and the due date are separate Evidence items within it. The common electronic- invoicing pattern of an XML embedding inside a signed PDF is exactly this structure — evidence pre-extracted and bound to its source so the extraction is itself tamper-evident.</p>
<p>The pair is domain-neutral (it extends to criminal, regulatory, and scientific evidence). Commerce, identity, and governance all <strong>use</strong> it; none owns it. Consequently <code>itc-gov</code> no longer owns <code>Evidence</code>; it imports it.</p>
<p><strong>R4 — <code>Relationship Tuple</code>: owned by <code>itc-access</code>.</strong> Already modelled there (<code>:549</code>, under <code>PolicyEvaluationEntity</code> beside <code>AuthorizationRequest</code>, <code>AuthorizationDecision</code>, <code>DecisionReason</code>, <code>EvaluationContext</code>). identity-canon's own entry agrees: "Relationship tuples are not canonical identity roots. They project from actors, accounts, memberships, and delegations into authorization domains." <code>itc-ident</code> must not define it.</p>
<p><strong>R5 — <code>Adjudication Outcome</code>: follows R3, owned with the evidence pair.</strong> Not <code>itc-access</code> <code>AuthorizationDecision</code> (a PDP allow/deny, <code>:907</code>) and not <code>itc-gov</code> <code>Decision</code> (a governance choice point). The concept is general rather than commercial: an arbitration award, court judgment, or regulatory consent order is evidence in employment, licensing, or compliance disputes as much as in commercial ones. Commerce is a consumer, not the owner.</p>
<p>Structurally it is <strong>Evidence</strong> — the outcome asserted — sourced from an Evidence Source such as the judgment document.</p>
<p>The <code>assurance_tier</code> dimension splits accordingly: the evidence model owns a general evidence-strength dimension; <code>commerce-canon</code> owns the <code>Counterparty Assurance Gradient</code> as its named four-tier application of it.</p>
<p><strong>R6 — <code>Community</code> and <code>Household</code> extend <code>itc-org</code>; <code>Family</code> is a separate concept area.</strong> identity-canon defines "Family Or Household" as one entry. That conflation is rejected.</p>
<p><code>Community</code> and <code>Household</code> are collective actors and slot under <code>itc-org</code>'s existing <code>CollectiveActor</code> (<code>:363</code>, beside <code>Person</code>, <code>HumanActor</code>, <code>NonHumanActor</code>), honouring P4 ("Model Collective Actors Without Collapsing Them").</p>
<p><code>Family</code> does not. Family carries substantial structure — kinship, guardianship, dependency, care, and legal, biological, and social parenthood — which changes over time and is subject to interpretation. Modelling it as one more collective actor is the specific mistake most family-oriented software makes, and it is why such software generally models families badly. It gets its own concept area.</p>
<p>Scope discipline applies: the family area is <strong>seeded, not authored</strong>. Record the concept, the privacy sensitivity already flagged in identity-canon ("may have legal implications outside the canon's scope"), and the open modelling questions. Do not build it out inside <code>CFED-WP-0001</code>; it grows on demand signal like any other canon content.</p>
<p><strong>R7 — the evidence pair lives in a dedicated model, <code>itc-evid</code>.</strong> A new InfoTechCanon model at <code>infospace/models/evidence/</code> owns <code>Evidence</code>, <code>Evidence Source</code>, <code>Adjudication Outcome</code>, and the general evidence-strength dimension.</p>
<p><code>itc-gov</code>, <code>itc-ident</code>, and <code>commerce-canon</code> import it. Three named consumers existed before the model did, which is the demand signal the canon requires.</p>
<p>Rejected alternative: leaving both with <code>itc-gov</code> as incumbent owner of <code>Evidence</code>. That is cheaper and preserves the locality of the Policy-Control-Evidence chain pattern (<code>:1391</code>), but it would force identity and commerce to import "governance" in order to describe an invoice line item — mis-signalling evidence as a governance sub-topic when it is domain-neutral.</p>
<p><code>itc-gov</code> retains <code>AssuranceCase</code>, <code>AssuranceConclusion</code>, <code>Audit</code>, and the Policy-Control-Evidence pattern, now expressed over imported evidence concepts.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Positive.</strong> Every concept gains exactly one owner. The identity gap that <code>itc-access</code> explicitly declines is filled. Commercial semantics get a home before they accrete further into technical canon. A dormant research repo with no inbound references becomes a canon with declared consumers. A second canon tests whether <code>InfoTechCanonRepositoryLayoutStandard</code> is a real standard or merely InfoTechCanon's own shape described back to itself.</p>
<p><strong>Negative.</strong> This is a concept-ownership reconciliation, not a file move: the first ~15 glossary entries must be rewritten as imports. Three canons cost more coordination than one. The <code>identity-canon</code> name disappears from tooling, bookmarks, and any external reference.</p>
<p><strong>Risks.</strong> CommerceCanon could repeat identity-canon's failure mode — dormant, zero consumers, drifting — if it launches as a scaffold. Mitigated by decision 2 (it opens holding real, research-backed content) and decision 5 (growth requires consumer evidence).</p>
</section>
<section id="references"><h2>References</h2>
<ul><li>ADR-001 — workplans originate as repo files; hub is a read model</li><li>ADR-005 — cross-repo workplans live in dedicated project repos</li><li><code>info-tech-canon/infospace/models/organization/InfoTechCanonOrganizationModel.md:55</code></li><li><code>info-tech-canon/infospace/models/access-control/InfoTechCanonAccessControlModel.md:106</code>, <code>:214</code></li><li><code>info-tech-canon/infospace/models/governance/InfoTechCanonGovernanceModel.md:107</code></li><li><code>info-tech-canon/demand/CapabilityProvisionEconomics.md</code></li><li><code>identity-canon/canon/CanonicalGlossary.md</code>, <code>canon/DesignPrinciples.md</code></li></ul>
</section><footer><span>CUST-ADR-006 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-006-canon-federation-concept-ownership.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>

279
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-007.html Normal file
View file

@ -0,0 +1,279 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d3c6f13d7aed9784b6f31c23d2b2777668493ba5">
<meta name="policy-source-digest" content="1169f0c1f485a2bb7241a8f64f3167c060c04f83341b12586fd9be5c2b3693f8">
<title>Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-007</span> <span class="stat">accepted · accepted-2</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#migration-needs-a-separate-ruling"><span class="n">·</span>Migration — needs a separate ruling</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle protection, and worker topology are settled.</p>
<p><strong>Remediation of existing collisions (§ Migration) remains an open ruling.</strong> It is disruptive, touches six repositories, and no active work depends on it — all five duplicated identifiers are <code>finished</code>.</p>
</section>
<section id="context"><h2>Context</h2>
<p>On 2026-08-16, <code>STATE-WP-0080</code> was found registered <strong>twice, in two different databases</strong>, with two different workplan UUIDs and two disjoint sets of task UUIDs:</p>
<div class="scroll"><table><thead><tr><th>Registrar</th><th>Workplan UUID</th><th>Reachable at <code>127.0.0.1:8000</code></th></tr></thead><tbody><tr><td>Workstation hub (<code>make api</code>, local postgres)</td><td><code>03f38314</code></td><td>yes</td></tr><tr><td>A second instance, over a second database</td><td><code>bbfce36a</code></td><td><strong>404</strong></td></tr></tbody></table></div>
<p>The second instance is <em>not</em> identifiable from the commit author. <code>custodian-sync@railiance.local</code> is a hardcoded default git identity in <code>scripts/consistency_check.py:1899</code> (<code>GIT_SYNC_USER_NAME</code> / <code>GIT_SYNC_USER_EMAIL</code>), so every machine running <code>fix-consistency</code> commits under that name. The discriminator is the timezone: sync commits appear under both <code>+0000</code> and <code>+0200</code> (the workstation's offset), which is independent evidence of two machines writing to one repository.</p>
<p>Both write their IDs into the same git-tracked workplan file, so each sync overwrites the other's IDs and the file flip-flops on every round trip. The same commit (<code>ff909e1</code>, "renormalize lifecycle state [auto]") also promoted the workplan <code>proposed</code> → <code>active</code> without human review.</p>
<p>A fleet scan of 955 hub workplans (525 with parseable <code>PREFIX-WP-NNNN</code> identifiers) found this is not an isolated incident. Two distinct identity defects are live:</p>
<p><strong>Prefix reuse across repositories:</strong></p>
<pre>CUST-WP- → state-hub, the-custodian
RAIL-BS-WP- → railiance-bootstrap, railiance-cluster
RAILIANCE-WP- → railiance-apps, railiance-forge, railiance-platform, railiance-telemetry</pre>
<p><code>PRJ-WP-</code> is a latent fourth: <code>statehub register</code> derives it from the <code>prj-</code> flavor marker, so every project repository would collide (see <code>RMGR-WP-0004</code>).</p>
<p><strong>Running-number reuse:</strong></p>
<pre>CUST-WP-0000 the-custodian ×2
CUST-WP-0010 the-custodian ×2
CUST-WP-0045 the-custodian ×2
RAILIANCE-WP-0015 railiance-platform, railiance-apps
RAILIANCE-WP-0016 railiance-platform ×2, railiance-apps</pre>
<p><code>RAILIANCE-WP-0015</code> is actively cited in operational memory as the cnpg-backup gate in <code>railiance-apps</code>; a second record of the same name in <code>railiance-platform</code> makes that citation ambiguous.</p>
<p>The <code>C-26</code> consistency check already flags prefix nonconformance <em>within</em> a repo against a canonical prefix, but nothing enforces uniqueness <em>across</em> repos, and nothing prevents number reuse.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. A workplan identifier is globally unique.</strong> <code>PREFIX-WP-NNNN</code> names exactly one workplan across the entire fleet, for all time.</p>
<div class="rule-quote"><p><strong>Amended 2026-08-17 by <code>ADR-011</code> decision 2.</strong> Uniqueness and forward-only allocation are <strong>namespace-scoped</strong>, not global; global identity is the pair <code>(namespace, identifier)</code>, written <code>PREFIX-WP-NNNN@namespace</code> when foreign. Global sequential allocation would require a central coordinator — the exact dependency federation must survive. Everything below holds unchanged <strong>within</strong> a namespace, which is where all current work sits.</p></div>
<ul><li>A workplan prefix is owned by exactly one repository. No two repositories may use the same prefix.</li><li>A running number is never reused within a prefix, including after a workplan is cancelled, archived, or deleted. Numbers are allocated forward only.</li><li>Prefixes are derived from the <em>project or repository identity</em>, never from a flavor marker or category (<code>PRJ-WP-</code> is invalid by construction).</li></ul>
<p><strong>2. Hub identifiers stored in repository files must be derivable, not database-local.</strong> The defect is structural: a database-local key is stored in a shared artifact, so each database overwrites the other's value on every sync. It also inverts ADR-001 — a file carrying a hub's private key is the file holding hub state.</p>
<p><em>Target state (C2).</em> <code>state_hub_workstream_id</code> and <code>state_hub_task_id</code> become <strong>deterministic</strong>: UUIDv5 derived from the workplan identifier. Per <code>ADR-011</code> decision 3 the derivation input is the pair <code>(namespace, identifier)</code>, not the identifier alone — deriving from the identifier alone would make two forks holding unrelated work under the same number compute the same UUID. Every instance computes the same value independently, writeback becomes idempotent, and any number of hub instances may coexist without coordination. The field shape is unchanged, so consumers keep working; only the provenance of the value changes.</p>
<p>This has a hard prerequisite: deterministic derivation from a <strong>non-unique</strong> identifier would manufacture collisions rather than remove them. Two project repos sharing <code>PRJ-WP-</code> would compute the same UUID for different workplans. Decision 1 must therefore be enforced before derivation ships.</p>
<p><em>Interim state (A).</em> Until derivation lands, exactly one instance writes hub identifiers into repository files. Other instances may read, project, and serve, but must not mint workplan or task UUIDs into git-tracked files.</p>
<div class="rule-quote"><p><strong>Corrected 2026-08-17, superseded by <code>ADR-010</code> decisions 1–3.</strong> This decision originally described workstation hubs as "development read replicas". That was wrong on both counts: the workstation instance was not a replica, and it was the <em>larger</em> of the two, holding 306 more workplans than the primary. The two instances were peer databases. <code>ADR-010</code> establishes the central hub as authoritative and local instances as rebuildable caches, which is what makes this interim rule coherent.</p></div>
<p>The interim is policy, enforced by discipline, and it has a real cost: registration requires connectivity to the registrar, so disconnected work cannot register. That cost is accepted only until C2 removes the need for it, at which point the number of hub instances becomes an availability choice rather than a correctness constraint.</p>
<p><em>Rejected.</em> Collapsing to a single shared database (workstation hubs pointing at the production database) would also make identifiers consistent by construction, but it eliminates offline capability — cutting directly against <code>STATE-WP-0068</code> (offline write buffer and edge relay) — and couples all local work to tunnel availability.</p>
<p><em>Ownership.</em> Both the interim guard and the derivation belong to <code>repo-manager</code> under decision <code>747011c6</code>, which already places file-backed record indexing and reconciliation there. Building either in <code>state-hub</code> would invest in a component being retired under <code>STATE-WP-0079</code>.</p>
<p>Migration scope for C2: <strong>758 workplan files</strong> across the fleet currently carry these fields.</p>
<div class="rule-quote"><p><strong>Amended 2026-08-21 — derivation scope for C2.</strong> <code>ADR-011</code> decision 7 keys derivation on <code>(namespace, identifier)</code>, which separates <em>forks</em>. It does not separate collisions inside one namespace, and the ecosystem's posture is <code>N1</code> — a single implied namespace. A fleet scan on 2026-08-21 found <strong>20 reused identifiers across 48 files</strong>, all within that one namespace, so the prerequisite above is not satisfied by <code>ADR-011</code> alone. Ruled: <strong>C2 derives only for live records; archived records keep their minted identifiers, frozen.</strong> This is what reconciles § Migration option 2 — under which historical files keep colliding identifiers — with the uniqueness derivation requires. Of the 20, only <strong>five</strong> collide among live files, so the remediation surface is 11 files rather than 48. Two consequences follow, and both are load-bearing: 1. <strong>Un-archiving a record with a frozen identifier is a collision hazard.</strong> A record returning to live status must be checked against the live namespace before it is re-derived, and renumbered if it clashes. 2. <strong>Derivation is not retroactive.</strong> Existing live records keep their minted UUIDs until they are re-derived deliberately; C2 changes provenance for new and re-registered records, not the whole corpus at once. Rejected: treating a <em>repository</em> as the namespace. That would make the collisions vanish by construction, but it redefines the term <code>ADR-011</code> decision 1 fixes as "a fleet instance, a client deployment, an autonomous domain", and <code>ADR-011</code> decision 9 warns specifically against reading N-plane movement into claims it does not support.</p></div>
<p><strong>3. Lifecycle status is not automatically promoted.</strong> An automated normalization pass may report drift; it may not move a workplan from <code>proposed</code> to <code>active</code>. <code>proposed</code> means awaiting human review, and an automation that promotes it destroys the meaning of the review gate.</p>
<p><strong>4. Repository manipulation is performed by a worker agent in that repository.</strong> This is the default topology.</p>
<ul><li>A worker acting in repo X owns changes to repo X.</li><li>Multiple independent top-level workers inside a single repository are an <strong>exception</strong>, requiring an explicit reason, not a routine mode of operation.</li><li>Concurrent independent writers are what turned a two-registrar bug into repeated git divergence.</li></ul>
<p><strong>5. Project (<code>prj-</code>) repositories may act across their participating repositories.</strong> When work is governed by a project repo, its tasks may direct changes across every repository the project names, through the project's work agent, where that is more efficient than delegating.</p>
<p>This is a deliberate, scoped exception to decision 4: the project repo already owns cross-repo sequencing and its <code>SCOPE.md</code> names its participants, so its authority is declared rather than ad hoc. It does not license a worker in an arbitrary repository to reach into others.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Positive.</strong> Workplan identifiers become citable without qualification. Hub IDs stop flip-flopping in git. The <code>proposed</code> status regains meaning. Cross-repo authority becomes something a repository declares rather than something any session assumes.</p>
<p><strong>Negative.</strong> Existing collisions must be remediated (see below), which is disruptive. Workstation sessions lose the ability to register workplans directly and must route through the registrar or a worker in the owning repo. Prefix allocation needs a fleet-level registry, which is new machinery.</p>
<p><strong>Enforcement.</strong> Prefix ownership, uniqueness, and forward-only numbering are repository standards, so they belong to Repo Manager under decision <code>747011c6</code> (<code>RMGR-WP-0004</code>), not to a hub. Canon defines the rule; Repo Manager checks it.</p>
</section>
<section id="migration-needs-a-separate-ruling"><h2>Migration — needs a separate ruling</h2>
<p>Three prefixes and five identifiers are already colliding. Remediation options, in increasing cost:</p>
<ol><li><strong>Freeze and forward-fix.</strong> Accept existing collisions as historical, enforce uniqueness only for new workplans. Cheapest; leaves <code>RAILIANCE-WP-0015</code> permanently ambiguous.</li><li><strong>Renumber the live collisions only.</strong> Fix identifiers that are still cited or active; leave <code>finished</code>/<code>archived</code> duplicates alone.</li><li><strong>Full renaming.</strong> Give <code>railiance-apps</code>, <code>railiance-forge</code>, <code>railiance-platform</code>, <code>railiance-telemetry</code> distinct prefixes, likewise <code>railiance-bootstrap</code>/<code>railiance-cluster</code> and <code>state-hub</code>'s legacy <code>CUST-WP-</code> files. Touches six repositories and every inbound reference.</li></ol>
<p><strong>Ruled 2026-08-17: option 2.</strong> Renumber live collisions; leave <code>finished</code>/<code>archived</code> duplicates as historical record.</p>
<h3>The live renumber list is empty</h3>
<p>Verified against the fleet scan. All five duplicated identifiers are <code>finished</code>:</p>
<pre>CUST-WP-0000 the-custodian ×2 finished
CUST-WP-0010 the-custodian ×2 finished
CUST-WP-0045 the-custodian ×2 finished
RAILIANCE-WP-0015 apps, platform finished
RAILIANCE-WP-0016 apps, platform ×2 finished</pre>
<p>No workplan in a <code>proposed</code>, <code>ready</code>, <code>active</code>, <code>blocked</code>, or <code>backlog</code> state shares an identifier with another. <strong>Option 2 therefore requires no renumbering today.</strong> Historical duplicates stay, including the <code>RAILIANCE-WP-0015</code> ambiguity between <code>railiance-apps</code> and <code>railiance-platform</code>; citations of it must name the repository.</p>
<h3>The structural cause is not historical</h3>
<p>Option 2 governs <em>remediation</em>. It does not exempt anything from decision 1, which is accepted canon: one prefix, one repository, forward-only numbering.</p>
<p>Three shared prefixes are still in use across seven repositories, and each is a <strong>single number line being allocated from concurrently</strong>:</p>
<pre>RAIL-BS-WP- bootstrap 8, 9
cluster 7, 10, 11, 12, 13, 14
RAILIANCE-WP- platform 5, 8-17 (16 twice — an internal duplicate)
apps 15, 16 &lt;- already collided with platform
forge 2
telemetry 1
CUST-WP- the-custodian 50 plans
state-hub 4 legacy plans (canonical prefix is STATE-WP)</pre>
<p><code>RAIL-BS-</code> and <code>RAILIANCE-</code> are actively growing — <code>RAIL-BS-WP-0014</code> (<code>ready</code>), <code>RAILIANCE-WP-0002</code> (<code>ready</code>), <code>RAILIANCE-WP-0001</code> (<code>proposed</code>), all created 2026-08-11 or later. The <code>RAILIANCE-WP-0015</code>/<code>0016</code> collisions were not a historical accident; they are what concurrent allocation from a shared sequence produces, and it will recur at the next concurrent allocation.</p>
<p><code>CUST-</code> is dormant on the <code>state-hub</code> side — four legacy plans, one in <code>backlog</code> — and needs no split, only a prefix-ownership assertion.</p>
<h3>Prefix assignments</h3>
<p><code>RAIL-BS-WP-</code> is <strong>retired</strong> (2026-08-17). Neither repository keeps it: <code>railiance-cluster</code> adopts <code>RCLUSTER-WP-</code> for active and future plans; <code>railiance-bootstrap</code> adopts <code>RBS-WP-</code> for future plans. Finished and archived files keep <code>RAIL-BS-WP-</code> as historical record, consistent with option 2.</p>
<p>Migrating plans keep their running numbers — the prefix changes, the number does not. This preserves traceability and cannot violate forward-only allocation, because neither new prefix has prior history. <code>railiance-bootstrap</code> begins at <code>RBS-WP-0010</code>, above its historical maximum, leaving the lower range free should its finished plans ever be adopted into the new prefix.</p>
<p><code>RAILIANCE-WP-</code> should follow the same pattern — retired rather than awarded to one repository, since it names a family rather than a repository and so fails decision 1 for the same reason <code>PRJ-WP-</code> does. Assignment of the four successor prefixes is outstanding.</p>
<p>Execution of each rename belongs to a worker in the owning repository under decision 4. <code>RMGR-WP-0004-T09</code> records assignments and the numbering rule; it does not perform renames.</p>
<p><strong>Consequence.</strong> Prefix ownership must be assigned for all three shared prefixes before the next workplan is created in the affected repositories. This is forward conformance under decision 1, not migration, and is tracked as <code>RMGR-WP-0004-T09</code>. Renaming the <em>historical</em> files is explicitly not required — that would be option 3, which was rejected.</p>
</section>
<section id="references"><h2>References</h2>
<ul><li>Decision <code>747011c6</code> — repository standards belong to Repo Manager</li><li>ADR-001 — workplans originate as repo files; hub is a read model</li><li><code>RMGR-WP-0004</code> — repository standards conformance and governed scaffolding</li><li><code>STATE-WP-0080</code> — register scaffolding handoff</li><li>Fleet scan 2026-08-16: 955 hub workplans, 525 parseable identifiers, 3 reused prefixes, 5 reused identifiers</li></ul>
</section><footer><span>CUST-ADR-007 · accepted-2 · accepted</span><span>the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</span></footer></main></div></div></html>

253
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-010.html Normal file
View file

@ -0,0 +1,253 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d3c6f13d7aed9784b6f31c23d2b2777668493ba5">
<meta name="policy-source-digest" content="5979da20799118259fc19246f51e8cc8f2c0c1be3d414318bd51d5a27d9ad565">
<title>Hub Authority, Local Cache, and the Two Kinds of Hub Data</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-010</span> <span class="stat">proposed · draft-2</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Hub Authority, Local Cache, and the Two Kinds of Hub Data</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#orphan-disposition"><span class="n">·</span>Orphan disposition</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#implementation"><span class="n">·</span>Implementation</a></li><li><a href="#references"><span class="n">·</span>References</a></li><li><a href="#outcome-2026-08-24"><span class="n">·</span>Outcome (2026-08-24)</a></li><li><a href="#outcome-2026-08-28"><span class="n">·</span>Outcome (2026-08-28)</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Proposed, and <strong>partially superseded by <code>ADR-012</code></strong> (accepted 2026-08-25). Decisions 1, 5 and 6 are sharpened or given a mechanism there; see the notes on each below. Everything else in this ADR remains in force.</p>
</section>
<section id="context"><h2>Context</h2>
<p>Investigating a workplan-identifier flip-flop (<code>ADR-007</code>) revealed that two State Hub instances were operating as <strong>peer databases</strong>, not as a primary and a replica:</p>
<div class="scroll"><table><thead><tr><th>Address</th><th>Instance</th><th>Workplans</th></tr></thead><tbody><tr><td><code>127.0.0.1:8000</code> (IPv4)</td><td>local uvicorn on docker postgres</td><td>955</td></tr><tr><td><code>[::1]:8000</code> (IPv6)</td><td>ssh tunnel <code>state-hub-primary</code> → railiance01</td><td>649</td></tr></tbody></table></div>
<p>Both listen on port 8000, separated only by IP family, so every tool defaulting to <code>127.0.0.1</code> reached the local instance while believing it was the primary.</p>
<div class="rule-quote"><p><strong>Mechanism identified 2026-08-24 by <code>CUST-WP-0067</code>.</strong> This ADR recorded the shared port as the hazard but not why it was <em>silent</em>, which is the part that let it persist. An <code>ssh -L</code> forward with no bind address listens on every loopback family, and <code>ExitOnForwardFailure=yes</code> fires only when <strong>every</strong> requested bind fails. The IPv4 bind lost to the local uvicorn, the IPv6 bind succeeded, and the tunnel therefore reported success while serving an address nothing resolved to by default. The collision was declared in <code>~/.config/bridge/tunnels.yaml</code>, and <code>ops-bridge</code> guarded only tunnel against tunnel, so a non-bridge listener was invisible to it. Fixed by pinning local forwards to <code>127.0.0.1</code>, so a contested port fails loudly (<code>ops-bridge</code> commit <code>2213847</code>). A shared port is recoverable; a shared port that reports healthy is not.</p></div>
<p>Measured divergence — 320 records exist locally but not on the primary:</p>
<pre>backed by a file that exists on disk 288 fully rebuildable
no backing file recorded 28 not rebuildable as-is
same filename, different UUID 4 duplicate registration</pre>
<p><strong>No file was missing for any of the 288.</strong> The divergence is therefore almost entirely redundant: it can be discarded and rebuilt from repositories without losing anything.</p>
<p><code>ADR-001</code> already says work originates as repository files and the hub is a read model. The two-peer-database situation contradicts that in practice: a second database accumulated 306 net records of its own.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. One authoritative hub, deriving from repository files.</strong> The central State Hub — running on railiance — is authoritative. It is authoritative <em>as a reading of the repositories</em>, not as a second place data lives. Repository files remain the source of truth (<code>ADR-001</code>).</p>
<div class="rule-quote"><p><strong>Sharpened 2026-08-25 by <code>ADR-012</code> decision 1.</strong> "A reading of the repositories" never said <em>which</em> copy of them, and the honest answer was neither the forge nor any particular working copy: the projection derived from whichever checkout last ran the sync. The hub holds no repository files at all and never reads one. <code>ADR-012</code> names the forge as the projection source.</p></div>
<p><strong>2. A local hub is a cache, never a database.</strong> Local instances hold a rebuildable projection. A cache may be discarded and reconstructed from the repositories at any time, and losing it must never lose work.</p>
<p>This replaces the peer-database arrangement. It is also why the divergence is tractable: a divergent database is a merge problem, a stale cache is a refresh problem.</p>
<div class="rule-quote"><p><strong>Corrected 2026-08-24 by <code>CUST-WP-0067</code>.</strong> Those two shapes are not exhaustive, and repository records took a third one. Measured that day: 122 repositories on the cache, 78 on central, <strong>zero central-only</strong>. A strict subset in the cache's favour is neither a merge problem nor a refresh problem — refreshing the cache would have <em>destroyed</em> the 44 extra records rather than reconciling them, and central held no path to re-derive repositories it had never been told existed. The third shape: <strong>cache-only records whose authoritative source exists and is reachable, but was never introduced to central.</strong> Its remedy is re-derivation from source — not refresh, not merge. Of the 44, 43 had a working copy, all 43 were pushed, and 34 carried a classification file; nothing was unrecoverable, but nothing would have recovered itself either. Onboarding by date showed a clean break: central's repository registrations stopped at 2026-07-08 while the workstation kept accepting them.</p></div>
<p><strong>3. Local work requires no hub at all.</strong> Repository files are self-describing — identifier, status, tasks, all in frontmatter. Working in a repository requires reading files, not querying an index. A cache is an optimization for cross-repo questions, never a prerequisite for doing work.</p>
<p><strong>4. Hub data is classified by origin, and the two kinds have opposite rules.</strong></p>
<div class="scroll"><table><thead><tr><th></th><th>File-derived</th><th>Hub-native</th></tr></thead><tbody><tr><td>Examples</td><td>workplans, tasks, statuses, dependencies</td><td>progress events, decisions, inbox messages, token events</td></tr><tr><td>Source of truth</td><td>the repository file</td><td>the hub</td></tr><tr><td>Offline behaviour</td><td>write the file and commit — the commit <em>is</em> the write</td><td>buffer locally, replay when reachable</td></tr><tr><td>Conflict model</td><td><strong>none</strong>; conflicts are git conflicts, resolved in git</td><td><strong>none</strong>; append-only merges regardless of order</td></tr><tr><td>Central accepts pushes?</td><td>no — it derives</td><td>yes</td></tr></tbody></table></div>
<p>Neither kind needs a hub-side conflict model. That is the point of the split: if central derives file-backed state, it cannot hold a conflicting version of it — it re-derives whatever git settles on. Two people editing one workplan is a git conflict and belongs to git.</p>
<p><strong>5. Central derives file-backed state; it does not accept pushes of it.</strong> "Authoritative" means authoritative <em>reading</em>, so nothing may inject derived state directly. Hub-native records are the exception and keep a real write path.</p>
<div class="rule-quote"><p><strong>Sharpened 2026-08-25 by <code>ADR-012</code> decision 6.</strong> This was policy, not practice: nothing derived, and the workstation pushed everything. <code>ADR-012</code> retires push-based sync as the primary path so that "central derives" becomes true rather than aspirational.</p></div>
<p><strong>6. Preliminary until confirmed.</strong> Locally registered data and uncommitted repository state are preliminary until the central service has seen them. Mitigation is by changing the repository files and the local cache — never by editing central to match a local view.</p>
<div class="rule-quote"><p><strong>Given a mechanism 2026-08-25 by <code>ADR-012</code> decisions 3 and 4.</strong> "Preliminary" was named here but never built, so in practice locally registered data was indistinguishable from derived state once it arrived. It is now a labelled overlay within the same projection — explicitly not a second store — and it retires when the commit carrying it reaches the forge. The prohibition on editing central to match a local view is unchanged.</p></div>
<p>Combined with <code>ADR-007</code> decision 2 (identifiers derived from <code>PREFIX-WP-NNNN</code>), "preliminary" largely stops mattering: a cache computes the same identifier central will, so offline-registered data is already correct on arrival and needs confirmation rather than reconciliation.</p>
<p><strong>7. Every record has exactly one authoritative hub.</strong> The State Hub retirement splits one hub into several. Multiple central hubs are permitted only under this rule: the owning hub is determined by the record's repository and domain. Without it, the same peer-database divergence recurs at larger scale.</p>
<p><strong>8. Cache reads are advisory and must carry their age.</strong> Cross-repo answers from a cache are advisory and should be presented with staleness. For the repository an agent is working in, the file is truth and the cache is never consulted for correctness.</p>
</section>
<section id="orphan-disposition"><h2>Orphan disposition</h2>
<p>The 28 records with no backing file are the only ones a cache rebuild would drop. They fall into three classes, to be separated before any rebuild:</p>
<ol><li><strong>Broken links</strong> — a file exists but <code>backing_filename</code> was never recorded. <code>RMGR-WP-0004</code> is one: the workplan file exists and is committed. These are metadata repairs, not data loss, and are likely the largest class.</li><li><strong>Live hub-first records</strong> — <code>proposed</code>, <code>ready</code>, or <code>backlog</code> with no file, in <code>activity-core</code>, <code>core-hub</code>, <code>hub-core</code>, <code>issue-core</code>, <code>ops-hub</code>, <code>prj-forgejo-org-refactor</code>, <code>railiance-enablement</code>, <code>railiance-infra</code>, <code>reef-railiance</code>. Each needs a repository file written or an explicit drop. These are <code>ADR-001</code> violations and must not be preserved as hub-only records.</li><li><strong>Closed hub-first records</strong> — <code>finished</code> or <code>archived</code> with no file. Retain as historical provenance where cheap; do not reconstruct plans that are done.</li></ol>
<p>A cache rebuild enforces <code>ADR-001</code> retroactively: the only casualties are records that broke it.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Positive.</strong> The divergence becomes discardable rather than mergeable. Offline work is fully supported without a write buffer for file-backed state — the git commit is the write. No hub-side conflict model is needed for either data kind. Authority stops being a policy claim and becomes a structural property.</p>
<p><strong>Negative.</strong> The 28 orphans require case-by-case disposition before a rebuild. Any consumer that treats a local hub as authoritative must be corrected. The one-hub-per-record rule constrains the retirement's hub split.</p>
<p><strong>Rescoping.</strong> <code>STATE-WP-0068</code> (offline write buffer and edge relay) is scoped as a single mechanism. Under decision 4, most of what it buffers does not need buffering — only the append-only hub-native stream does. Its scope should be re-examined before more is built on it; this may reduce work rather than add it.</p>
<p><strong>Correction to <code>ADR-007</code>.</strong> Decision 2 there calls the workstation instance a "development read replica". It was neither a replica nor smaller — it held 306 more workplans than the primary. Superseded by decisions 1–3 here.</p>
</section>
<section id="implementation"><h2>Implementation</h2>
<p>Owned by <code>repo-manager</code> for file-derived state (decision <code>747011c6</code>; it already owns repository representation, file-backed record indexing, and reconciliation) and by <code>hub-core</code> for hub-native records. Tracked under <code>RMGR-WP-0005</code>.</p>
</section>
<section id="references"><h2>References</h2>
<ul><li>ADR-001 — workplans originate as repo files; hub is a read model</li><li>ADR-007 — identifier uniqueness, derived identifiers, worker topology</li><li>Decision <code>747011c6</code> — repository standards belong to Repo Manager</li><li><code>RMGR-WP-0005</code> — registrar consolidation and deterministic identifiers</li><li><code>STATE-WP-0068</code> — offline write buffer and edge relay (rescope candidate)</li><li>Divergence measurement, 2026-08-17: 955 local / 649 primary / 320 local-only</li></ul>
</section>
<section id="outcome-2026-08-24"><h2>Outcome (2026-08-24)</h2>
<div class="rule-quote"><p>Added by <code>CUST-WP-0067</code>. This ADR read as though its remediation had landed. It had not: the two-instance condition it measured on 2026-08-17 was still live seven weeks later, and had continued to accumulate records the whole time. An ADR that describes a fix in the present tense is easily mistaken for a fix that happened — worth stating plainly for the ones that follow.</p></div>
<p>The peer-database arrangement is now resolved, by deletion rather than by reconciliation:</p>
<ul><li><strong>The local hub instance is retired.</strong> Rather than making two instances coexist safely, the second one was removed. Exactly one process binds <code>127.0.0.1:8000</code> and it is the tunnel to central. Nothing remains that could impersonate the primary, and no call site needed editing — retiring the impersonator made the existing <code>127.0.0.1:8000</code> defaults correct.</li><li><strong>Decision 3 carried the argument.</strong> Because local work requires no hub at all, and Repo Manager already maintains a file-derived index, the local instance was redundant rather than load-bearing.</li><li><strong>Repo Manager gained the write path it was already assigned.</strong> <code>hub-record-authority.yaml</code> gives it <code>managed_repos</code> as <code>file-derived</code>, but it exposed no command for it; the only working path lived in the State Hub repo and defaulted to a local address. <code>rmgr repo-onboard</code> closes that, and refuses to onboard a repository whose backing file is uncommitted, unpushed, or has no upstream — a record whose source is only local cannot be re-derived, which is the failure this ADR exists to prevent.</li><li><strong>33 of the 44 were re-derived onto central</strong>, taking it from 78 to 111 repositories. The remaining 11 carry written dispositions rather than guessed values, per the orphan-disposition principle above.</li></ul>
<p>One cause sat deeper than the topology: the hub resolved its classification allowed-values file from three hardcoded developer-workstation checkouts, so in a container every classification write failed. Repository classification could <em>only</em> be written from a workstation. That is a second instance of this ADR's own theme — authority that depends on where a process happens to run is not authority — and is why "central derives" had never been achievable for this record type.</p>
</section>
<section id="outcome-2026-08-28"><h2>Outcome (2026-08-28)</h2>
<div class="rule-quote"><p>Added by <code>CUST-WP-0068</code>. The 2026-08-24 outcome closed the <em>repository</em> divergence. The work-record divergence this ADR originally measured — 955 local / 649 primary — remained, because the retired instance's database was still load-bearing. That is now closed.</p></div>
<ul><li><strong>Central holds 1167 workplans.</strong> Records that existed only in the cache were re-derived from their files, renamed onto the canonical scheme, or given a written disposition (<code>docs/recovery/cache-only-disposition-2026-08-28.md</code>).</li><li><strong>No open work record exists only in the cache.</strong> Remaining cache-only slugs are aliases of recovered records, clay-borg product files (not workplans), or prefix-migration residue.</li><li><strong>The cache database is discarded.</strong> Final dump <code>~/backups/state-hub-cache-2026-08-28.dump</code>. Container <code>infra-postgres-1</code> and volume <code>infra_pg_data</code> removed. Port 5432 is free.</li><li><strong>The local instance is no longer load-bearing for any record type.</strong> Decision 3 is now true in operation, not only in argument.</li></ul>
</section><footer><span>CUST-ADR-010 · draft-2 · proposed</span><span>the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</span></footer></main></div></div></html>

284
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-011.html Normal file
View file

@ -0,0 +1,284 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
<meta name="policy-source-digest" content="f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0">
<title>Federated Namespaces</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-011</span> <span class="stat">proposed · draft-2</span> <span>the-custodian</span> <span>reviewed 2026-08-17</span><span>generated from canonical source — do not edit</span></div><h1>Federated Namespaces</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2027-02-17</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#reconciliation-tiers-and-where-automation-stops"><span class="n">·</span>Reconciliation tiers, and where automation stops</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#open-question"><span class="n">·</span>Open question</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Proposed, draft-2. Amends <code>ADR-007</code> decisions 1 and 2; extends <code>ADR-010</code> decision 4; adopts the plane/ladder/posture form and the accuracy-not-altitude conformance rule from <code>ADR-008</code> (Multi-Tenancy Framework).</p>
</section>
<section id="context"><h2>Context</h2>
<p>The ecosystem must be <strong>federation-capable</strong> — able to work without a live link to central services — and <strong>chain-of-command efficient</strong>. <code>federated-organization-standard_v1.0</code> already resolves the organizational half:</p>
<div class="rule-quote"><p>global coherence is achieved through policy, escalation, and shared protocols rather than through monolithic control (<code>:51</code>) bounded autonomy plus disciplined coordination (<code>:86</code>)</p></div>
<p>Authority is a <strong>policy</strong> layer; availability is a <strong>mechanism</strong>. Distributed version control makes the same separation: an integration branch is privileged by agreement, never by a technical property.</p>
<p><strong>One accepted decision violates this.</strong> <code>ADR-007</code> decision 1 requires running numbers that are <em>globally</em> unique and allocated forward only. Global sequential allocation requires a coordinator — precisely the central dependency federation must survive. Two disconnected forks each allocating <code>RCLUSTER-WP-0015</code> is a certainty, not an edge case.</p>
<p>This is not hypothetical. Instance-per-client tenancy (<code>CUST-WP-0058</code>) already makes every client deployment a fork of the stack; the business model committed to forking before the identifier scheme could express it.</p>
<h3>Why this draft changed form</h3>
<p>Draft-1 stated federation as a set of binary rules — notably "records fork, effects do not". That is a single verdict where a graduated declaration belongs, and it is the same conflation <code>ADR-008</code> §03 diagnoses for multi-tenancy: <em>"'Is this multi-tenant?' is treated as one question. It is four, and they are independent."</em></p>
<p>"Is this federation-capable?" is likewise not one question. A namespace can be strong on identity and incapable of disconnected operation; it can operate disconnected and have no way to reconcile afterwards. Draft-1 could not say so.</p>
<p>This draft reuses <code>ADR-008</code>'s vocabulary rather than inventing a parallel one. Two competing maturity vocabularies in one canon would be its own collision.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. Records live in a namespace.</strong> A namespace is a federated branch of the ecosystem — a fleet instance, a client deployment, an autonomous domain that may operate disconnected. It is the unit of sovereignty in FOS terms and the unit of divergence here.</p>
<p><strong>2. Federation is four orthogonal planes.</strong></p>
<div class="scroll"><table><thead><tr><th>Plane</th><th>Question</th><th>Vocabulary owner</th></tr></thead><tbody><tr><td>Namespace <strong>N</strong></td><td>How are records named and disambiguated across branches?</td><td>this ADR</td></tr><tr><td>Autonomy <strong>U</strong></td><td>Can work proceed with no link to central services?</td><td>repo-manager</td></tr><tr><td>Reconciliation <strong>R</strong></td><td>What happens when branches meet again?</td><td>repo-manager</td></tr><tr><td>Substrate <strong>S</strong></td><td>Does this namespace hold independently diverging operational state?</td><td>railiance-platform</td></tr></tbody></table></div>
<p><strong>3. Each plane carries a ladder.</strong> Higher is stronger, not better. The right level is the one a namespace can evidence and its risk warrants.</p>
<pre>N0 no namespace concept; identifiers assume one global space
N1 namespace implied by deployment, never recorded
N2 namespace declared; identifiers namespace-scoped; qualification available
N3 N2 + lineage recorded, and derived identifiers keyed on (namespace, identifier)
U0 routine work requires the central service
U1 degraded read-only; writes blocked while disconnected
U2 work proceeds locally: file-derived state written to files, hub-native buffered
U3 U2 + exercised — a dated disconnection drill with evidence
R0 no defined path; divergence is unrecoverable
R1 manual, per-record comparison and hand resolution
R2 append-only events plus derived state: union and re-derive, deterministic
R3 R2 + lineage-aware; distinguishes divergence from collision automatically
S0 shares operational substrate with another namespace — cannot fork safely
S1 shared substrate, namespace-keyed
S2 dedicated substrate, no independent state divergence yet
S3 independent operational substrate with diverged state — the fork is real</pre>
<p><strong>4. A namespace declares a posture vector</strong>, in the repository rather than the hub, consistent with <code>ADR-010</code> decision 4 (file-derived state) and <code>ADR-008</code> decision 5.1.</p>
<pre>federation:
current: { N: 1, U: 1, R: 1, S: 1 }
target: { N: 3, U: 2, R: 2, S: 1 }
reviewed: &quot;2026-08-18&quot;
gap:
U: &quot;Registration requires the registrar under ADR-007 decision 2 interim.
Lifts when derived identifiers land (RMGR-WP-0005-T03).&quot;</pre>
<p><strong>The ecosystem's own posture today is <code>N1 U1 R1 S1</code></strong> — one implied namespace, disconnected registration blocked, reconciliation manual, substrate shared. Declaring that is conformant. Claiming better is not.</p>
<p><strong>5. Conformance is accuracy, not altitude.</strong> Adopted verbatim in force from <code>ADR-008</code> §06: a namespace is conformant when its declared posture is accurate, its target recorded, and it claims no level it cannot evidence. It is non-conformant when it overclaims, at any altitude.</p>
<p>Declaring <code>S0</code> is conformant. Concealing <code>S0</code> is not. A repository may join at any posture; it may not join silently. This matters more here than it does for tenancy: the cost of discovering a true posture during reconciliation is the whole difference between T2 and T3.</p>
<p><strong>6. Identifiers are unique within a namespace, qualified across.</strong> <code>ADR-007</code> decision 1 is amended: uniqueness and forward-only allocation are <strong>namespace-scoped</strong>. Global identity is the pair <code>(namespace, identifier)</code>.</p>
<pre>RCLUSTER-WP-0015 this namespace — the common case, unchanged
RCLUSTER-WP-0015@railiance01 a foreign namespace, explicitly qualified</pre>
<p>Unqualified always means "in my own namespace", exactly as <code>main</code> does against <code>origin/main</code>. A suffix preserves existing sorting, grep, and tooling; a prefix would break them.</p>
<p><strong>7. Derived identifiers key on the pair.</strong> <code>ADR-007</code> decision 2 (C2) derives UUIDv5 from the identifier. Under federation the input must be <code>(namespace, identifier)</code>. Deriving from the identifier alone would make two forks holding unrelated work under the same number compute the <em>same</em> UUID — a collision manufactured by the fix. C2 is not yet built, so this is free now and expensive later.</p>
<p><strong>8. The planes couple at their upper levels. State the coupling; do not use it to argue the planes are one.</strong></p>
<ul><li><code>R3</code> requires <code>N3</code> — distinguishing divergence from collision requires lineage.</li><li>A namespace may not sustain <code>U2</code> or above while below <code>R2</code>. Operating disconnected without deterministic reconciliation accumulates divergence that cannot later be merged. Autonomy without reconciliation is not federation; it is an unplanned fork.</li><li><code>T3</code> is entailed by <code>S3</code> in any participant (decision 10).</li></ul>
<p><strong>9. Anti-overclaim.</strong> This is the most misusable fact in the framework, and it is the direct analogue of <code>ADR-008</code>'s <code>P0 → P1 → P2</code> warning.</p>
<div class="rule-quote"><p>Adopting namespace-qualified identifiers is movement on the <strong>N plane only</strong>. It buys disambiguation, citability, and coordinator-free allocation. It does <strong>not</strong> raise autonomy, reconciliation, or substrate independence by one step. A system at <code>N3 U0 R0 S0</code> cannot operate disconnected and cannot reconcile.</p></div>
<p>No namespace may be described as "federation-capable", "independently operable", or "able to run disconnected" on N-plane evidence alone. Such a claim requires declared <code>U</code> and <code>R</code> levels with evidence behind them.</p>
<p><strong>Commercially</strong>, client-facing claims about instance independence must cite the <code>S</code> and <code>U</code> levels, never the identifier scheme. Instance-per-client tenancy is sold on substrate independence; the qualifier does not supply it.</p>
<p><strong>10. The reconciliation tier is derived from participants' postures, not judged after the fact.</strong></p>
<pre>any participant at S3 -&gt; T3 (regardless of other planes)
all participants S&lt;=S2 and R&gt;=R2 -&gt; T2 feasible
any participant below R2 -&gt; T1 at best; manual thereafter</pre>
<p>This is the practical payoff of declaring postures: the cost of rejoining is <strong>computable before a fork is created</strong>, rather than discovered when reconciliation is attempted.</p>
<p><strong>11. Coexistence is the normal case; merging is the exception.</strong> The qualifier is primarily a coexistence mechanism, not merge preparation. Most forks — client instances above all — are never intended to return. Permanent parallel operation is a first-class outcome, not a failure to reconcile.</p>
<p><strong>12. Evidence.</strong> A claimed level requires evidence, per <code>ADR-008</code> §13.</p>
<div class="scroll"><table><thead><tr><th>Level</th><th>Evidence</th></tr></thead><tbody><tr><td><code>N2</code></td><td>namespace declared in the repo; qualified references resolve</td></tr><tr><td><code>N3</code></td><td>lineage fields present; a derived identifier reproduced by an independent implementation</td></tr><tr><td><code>U2</code></td><td>work completed with central unreachable, committed, later accepted without rework</td></tr><tr><td><code>U3</code></td><td>dated disconnection drill record</td></tr><tr><td><code>R2</code></td><td>replaying the union of events reproduces identical derived state</td></tr><tr><td><code>R3</code></td><td>a collision and a divergence, correctly distinguished, in test</td></tr><tr><td><code>S2</code> / <code>S3</code></td><td>substrate inventory naming the stateful systems and whether their state has diverged</td></tr></tbody></table></div>
<p><strong>13. Guard.</strong> Declared postures regress silently. Posture is checked by the same consistency machinery that checks repository standards (<code>RMGR-WP-0004-T02</code>, <code>rmgr conform</code>), so a namespace that drops below its declared level is a reported defect rather than a discovery. A regression found by guarding is a defect; a regression declared in advance is a decision.</p>
</section>
<section id="reconciliation-tiers-and-where-automation-stops"><h2>Reconciliation tiers, and where automation stops</h2>
<div class="scroll"><table><thead><tr><th>Tier</th><th>Situation</th><th>Mechanism</th><th>Automatable</th></tr></thead><tbody><tr><td><strong>T0 Fork</strong></td><td>namespace created, lineage recorded</td><td>metadata</td><td>yes</td></tr><tr><td><strong>T1 Sync</strong></td><td>pull canon, plans, or knowledge from another namespace</td><td>append events, re-derive</td><td>largely</td></tr><tr><td><strong>T2 Reintegration</strong></td><td>records diverged, no participant above <code>S2</code></td><td>union events, re-derive, human-resolve genuine contradictions</td><td>partly</td></tr><tr><td><strong>T3 Amalgamation</strong></td><td>any participant at <code>S3</code></td><td>governed programme — see below</td><td><strong>no</strong></td></tr></tbody></table></div>
<p><strong>T3 is not a merge.</strong> It resembles the merger or acquisition of distinct companies far more than a version-control merge, and must be planned as such:</p>
<ul><li>due diligence — inventory both sides, item by item;</li><li>survivor decisions per subsystem — keep, move, replace, retire;</li><li>migration with evidence, and decommissioning of what does not survive;</li><li>governance integration — reconciling two bodies of canon is a human act, never automated;</li><li>identity, credential, and data custody consolidation.</li></ul>
<p><strong>T3 may legitimately end without integration.</strong> Permanent coexistence, or divestment, are valid outcomes. Real mergers most often fail at systems integration; an architecture that assumes eventual convergence is lying about its own limits.</p>
<h3>Known cost</h3>
<p><code>prj-state-hub-retirement</code> is a T3 reconciliation inside a <em>single</em> organization — two hub implementations, distinct infrastructure. It required a dedicated project repository, a 425-item disposition inventory (<code>SHR-INV-0001</code>), staged migration with strangler adapters, and explicit retirement gates. That is the realistic cost of T3 under the most favourable conditions possible: one owner, one canon, one credential authority.</p>
<p>Nothing here reduces that cost. Declared postures make it <strong>visible before</strong> a fork is created rather than discovered when reconciliation is attempted.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Positive.</strong> Disconnected operation stops requiring a coordinator for identity. <code>ADR-007</code> decision 1's contradiction is resolved rather than tolerated. A namespace mid-journey can describe itself honestly instead of being non-conformant. Reconciliation cost becomes computable in advance. Client instances become expressible.</p>
<p><strong>Negative.</strong> Every namespace gains a posture to declare and keep accurate, and tooling must learn qualified references. Decision 8's coupling rule constrains disconnected operation to namespaces that can reconcile — deliberately.</p>
<p><strong>Deferred.</strong> Merge machinery for T2 is <strong>not</strong> specified here and should not be built until a real fork needs it. T3 needs no machinery by definition; it needs a project repository and human judgement.</p>
<p><strong>Amended.</strong> <code>ADR-007</code> decision 1 — uniqueness is namespace-scoped. <code>ADR-007</code> decision 2 — derivation input becomes <code>(namespace, identifier)</code>.</p>
</section>
<section id="open-question"><h2>Open question</h2>
<p><strong>What is the namespace boundary in practice?</strong> Candidates: a fleet instance (<code>railiance01</code>), a client deployment, or an FOS autonomous domain. FOS's recursion — "from projects to companies to foundation-like umbrella structures" — suggests namespaces <strong>nest</strong>, which would make qualification relative rather than absolute, closer to DNS than to a flat handle. The notation survives either answer, so implementation is not blocked, but the data model is unfinished until it is settled.</p>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>canon/standards/federated-organization-standard_v1.0.md</code> — bounded autonomy, escalation, sovereignty by default, rebuildability</li><li>ADR-001 — workplans originate as repo files</li><li>ADR-007 — identifier uniqueness and derived identifiers (amended here)</li><li>ADR-008 — Multi-Tenancy Framework; source of the plane/ladder/posture form and the accuracy-not-altitude conformance rule</li><li>ADR-010 — hub authority, local cache, and the two kinds of hub data</li><li><code>CUST-WP-0058</code> — instance-per-client tenancy</li><li><code>SHR-INV-0001</code> — 425-item disposition inventory, T3 cost evidence</li><li><code>RMGR-WP-0004-T02</code> — <code>rmgr conform</code>, the guard machinery</li></ul>
</section><footer><span>CUST-ADR-011 · draft-2 · proposed</span><span>the-custodian · canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>

248
docs/evidence/2026-10-11-served-publication-history/pages/CUST-ADR-012.html Normal file
View file

@ -0,0 +1,248 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="6475a2e1ca590682888b77ce32ea056fd02e272a">
<meta name="policy-source-digest" content="b5e8582459f546ae789ad5fd62f458454aa19997b520e32b6b9f792d6af55987">
<title>What the Hub Projects</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-012</span> <span class="stat">accepted · 1.0</span> <span>the-custodian</span> <span>reviewed 2026-08-25</span><span>generated from canonical source — do not edit</span></div><h1>What the Hub Projects</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-012-projection-source-and-preliminary-overlay.md · 6475a2e1ca590682888b77ce32ea056fd02e272a</code></p><p class="sub">Review due: 2027-02-25</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#relationship-to-prior-decisions"><span class="n">·</span>Relationship to prior decisions</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p><strong>Accepted 2026-08-25</strong> by Bernd Worsch. Supersedes <code>ADR-010</code> decision 1's phrase "authoritative as a reading of the repositories" by making the reading concrete, and implements decision 6's unbuilt notion of "preliminary".</p>
</section>
<section id="context"><h2>Context</h2>
<p><code>ADR-001</code> says work originates as repository files and the hub is a read model. <code>ADR-010</code> says central is authoritative <em>as a reading of the repositories</em>. Both leave one question unanswered, and it turns out to be the load-bearing one:</p>
<div class="rule-quote"><p><strong>Which</strong> repository files? The forge, or a working copy?</p></div>
<p>Verified on 2026-08-25, the answer today is <strong>neither</strong>.</p>
<p>Central runs one FastAPI pod on railiance01 with a CNPG database. Inspected from inside, it holds <code>/app</code> — its own source — and nothing else. No clone tree, no repository mount; the <code>sweep</code> hostPath that would give it one is disabled. <strong>The hub never reads a repository.</strong> It cannot see the forge, and it cannot see a workstation.</p>
<p>What actually happens is the inverse of the ADR language: <code>fix-consistency</code> and <code>registrar-reconcile</code> run <em>on a workstation</em>, read files in <code>/home/&lt;user&gt;/&lt;repo&gt;</code>, and POST the result over a tunnel. The <code>host_paths</code> field records this plainly — 117 repositories carry a path on <code>bnt-lap001</code>, a laptop.</p>
<p>So the projection derives from <strong>whichever checkout most recently ran the sync</strong>. That is a third thing, distinct from both the forge and any particular working copy, and it is written down nowhere.</p>
<h3>Why this is not academic</h3>
<p>Every failure investigated under <code>CUST-WP-0067</code> and <code>CUST-WP-0068</code> is downstream of it:</p>
<ul><li>A local hub and central both served port 8000, and every default reached the local one for seven weeks. Neither could be distinguished by what it projected.</li><li>50 repository records pointed at a retired forge, so the sync could not match the checkout and silently registered nothing.</li><li>Duplicate registrations accumulated: the same file registered twice under two identifiers, because two environments each believed they were projecting it.</li><li><code>git_fingerprint</code> — the field that should say which commit a projection reflects — still holds the <em>initial commit</em> for <code>the-custodian</code>, while <code>last_state_synced_at</code> is minutes old. There is no reliable way to ask central what state it is a projection <em>of</em>.</li></ul>
<h3>The forcing function</h3>
<p>With one contributor, "last writer wins" is invisible, because there is only one writer. With several, each pushes a projection of a different repository state into one shared read model, and each will look locally consistent while disagreeing with the others. That is the peer-database problem <code>ADR-010</code> diagnosed, relocated one layer up and made harder to see.</p>
<p>The window to fix this cheaply is before the second contributor, not after.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. The forge is the projection source.</strong> Central derives its projection from Forgejo — the pushed state of the default branch — not from any working copy. "Authoritative as a reading of the repositories" now names a specific reading: what the forge holds.</p>
<p>Forgejo runs in the same cluster as central, so this is an in-cluster fetch. No tunnel, no cross-network credentials, and central already carries a <code>git</code> binary.</p>
<p><strong>2. Every projected record carries the commit it derived from.</strong> A projection without provenance cannot be audited, and the existing <code>git_fingerprint</code> proves the point by being wrong and silent about it. Records must reference the commit that produced them, and a projection whose commit is older than the forge's head must be visibly stale rather than quietly current.</p>
<p><strong>3. Unpushed local work is a preliminary overlay, never the baseline.</strong> A working copy may contribute records the forge does not yet hold. They are marked preliminary, attributed to their environment, and never silently merged into the derived baseline. When the commit that carries them reaches the forge, the baseline absorbs them and the overlay entry retires.</p>
<p>This implements <code>ADR-010</code> decision 6, which named "preliminary" but left it unbuilt.</p>
<p><strong>4. The overlay is a label, not a second store.</strong> Preliminary records live in the same projection, flagged. They are not a parallel database and not a local hub. Every local projection this ecosystem has had was eventually mistaken for authority; the defence is that there is nothing separate to mistake.</p>
<p><strong>5. A working copy is a workspace, not a source of authority.</strong> Deleting a checkout after pushing must lose nothing and invalidate nothing. Validation of a projection must not require a local clone of the repository being validated.</p>
<p><strong>6. Push-based sync is retired as the primary path.</strong> Workstation tooling stops being how records reach central. It may continue to <em>propose</em> preliminary records under decision 3, but the baseline is derived, not received. This closes the gap where "central derives" was policy while "the laptop pushes" was practice.</p>
<p><strong>7. The projection must be resettable from the forge, as a routine operation.</strong> There must be a supported way to reconcile the projection — for one repository or for the whole fleet — against what Forgejo holds: create what is missing, update what differs, and <strong>retire what no longer derives</strong>.</p>
<div class="rule-quote"><p><strong>Amended 2026-08-25, before implementation.</strong> This decision originally said <em>discard and rebuild</em>. That operation cannot exist, and the reason is a good one. <code>progress_events</code>, <code>tasks</code>, <code>decisions</code> and <code>review_contracts</code> all reference workplans with <code>ON DELETE RESTRICT</code>, and 1067 of 1075 workplans carry at least one such reference. Deleting a workplan would mean deleting the hub-native records attached to it — which <code>ADR-010</code> decision 4 forbids, and which the schema refuses to allow. The database is enforcing this ADR's own boundary one layer down. A progress event recording work on a workplan is a fact that happened; destroying it to tidy a derived projection would be losing hub-native truth to fix a derived-state problem, which is exactly backwards. Retirement achieves what reset is for — the projection converges on the forge, and records that no longer derive stop appearing as live work — without erasing anything that only the hub holds. Reset reconciles; it does not destroy.</p></div>
<p>This is the decision that makes the others checkable rather than merely stated. A read model that cannot be rebuilt from its source is not a projection; it is a database with a projection's reputation, and the difference only becomes visible on the day someone needs to rebuild it. <code>ADR-010</code> decision 2 already asserts that a cache "may be discarded and reconstructed from the repositories at any time" — that claim has never been executed, and an untested rebuild path is an assumption, not a capability.</p>
<p>Three properties make it real rather than ceremonial:</p>
<ul><li><strong>Routine, not emergency.</strong> It should be run deliberately and often enough that it is known to work, not discovered under pressure. A reset that has never been performed is indistinguishable from one that does not work.</li><li><strong>Per repository is the unit.</strong> Not a convenience over a fleet-wide operation — the repository <em>is</em> the unit of reconstruction, and the fleet-wide form is defined as iteration over it.</li></ul>
<p>This follows from the source. Each repository is a separate forge repository with its own history and its own head commit, so its projection is derivable in isolation and provable in isolation: fetch that repository, rebuild its records, compare against that repository's head. Nothing about that requires knowing the state of any other repository, and a design that made it require so would be inventing a dependency the source does not have.</p>
<p>It also bounds the blast radius, which is what makes decision 7's "routine" achievable. A rebuild that can only run fleet-wide is an operation nobody runs casually, and therefore an operation nobody runs — which is precisely how <code>ADR-010</code>'s never-executed reconstruction claim came to be believed. Scoped to one repository, a rebuild is small enough to be ordinary, and ordinary is the only state in which it stays known-working.</p>
<p>It is also the only form that composes with the refusals below. A repository holding projection-only records can be held back and dispositioned while every healthy repository around it is rebuilt; an all-or-nothing reset is blocked entirely by a single bad repository, which in practice means it is blocked permanently.</p>
<p>With contributors, per-repository scope is what keeps one person's rebuild from touching another person's records.</p>
<p>The fleet-wide form must therefore be a loop over the per-repository form, sharing one implementation. The rarely-used dangerous path and the frequently used safe path must be the same code, so the rare one is exercised by the common one rather than trusted on the strength of never having been run.</p>
<ul><li><strong>Idempotent and verifiable.</strong> A reset followed by a reset produces the same projection, and the result can be compared against the forge to show it matches. Derived identifiers (<code>ADR-007</code>) are what make this possible: the same commit yields the same record identities every time.</li></ul>
<p><strong>Retirement must be visible, not silent.</strong> A retired record states that the forge no longer derives it, and remains inspectable — including from whatever hub-native history is still attached. A record that merely disappears from a listing is indistinguishable from one that was never there.</p>
<p><strong>Reset does not restore the preliminary overlay.</strong> Overlay records exist precisely because the forge does not hold them, so a rebuild from the forge cannot reproduce them and must not pretend to. Reset therefore discards preliminary state, and must say so plainly before it runs.</p>
<p><strong>A reset must refuse when records exist only in the projection.</strong> If the hub holds records with no counterpart in the forge, rebuilding destroys them. That is not hypothetical: as of 2026-08-25, 111 work records existed only in a retired local database, and a rebuild at that moment would have erased them. The reset path must detect that condition and stop, naming what would be lost, rather than proceed and report success.</p>
<p>The refusal is evaluated per repository, in keeping with the scope above. A repository whose records all exist in the forge is rebuildable regardless of what any other repository holds, and a fleet-wide run must skip and report the repositories it refuses rather than abort the whole pass. Otherwise one unresolved repository blocks reconstruction everywhere, and the capability decays back into the untested assumption this decision exists to prevent.</p>
<p><strong>8. Formal git review stays optional.</strong> Deriving from the default branch gives a shared baseline without requiring pull requests. Review can be adopted per repository where it earns its keep; this ADR neither mandates nor forbids it.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Positive.</strong> The hub becomes provably a projection: reconcilable on demand against its source, and therefore knowable to be one. Truth becomes checkable by anyone, from anywhere, without a clone. Multiple contributors share one baseline instead of overwriting each other's views. Provenance becomes auditable — every record can name its commit. The "push then delete the working copy" case simply works. The distinction between committed and uncommitted work becomes visible in the model rather than a matter of who ran which command last.</p>
<p><strong>Negative.</strong> Git becomes load-bearing for the hub: Forgejo availability now affects projection freshness. A derive loop needs a cadence, and freshness becomes a property to monitor rather than assume. Unpushed work becomes explicitly second-class — which is its honest status, but it will feel like a restriction to a solo developer used to local-first behaviour.</p>
<p><strong>Migration.</strong> The <code>sweep</code> hostPath — central reading a node-local clone tree — is a half-measure toward this decision and was disabled pending "governed remote reconciliation" while railiance01 checkouts still targeted Gitea. As of 2026-08-25 all 79 node checkouts track Forgejo, so that stated blocker has cleared. Sweep should be evaluated as a stepping stone or retired in favour of a direct forge fetch, not left dormant with an obsolete justification.</p>
<p><strong>Unresolved.</strong> This ADR does not settle the derive cadence, whether central clones or uses the Forgejo API, how preliminary records are surfaced in the dashboard and MCP, or what happens to a preliminary record whose commit never arrives. Nor does it settle how hub-native records — progress events, decisions, inbox messages, which <code>ADR-010</code> decision 4 classes as originating in the hub — survive a reset. They are not forge-derived and must not be destroyed by a rebuild of forge-derived state; the boundary needs drawing before reset is built. Those belong to implementation.</p>
</section>
<section id="relationship-to-prior-decisions"><h2>Relationship to prior decisions</h2>
<ul><li><strong><code>ADR-001</code></strong> — unchanged. Work still originates as repository files; this ADR says which copy of them the hub reads.</li><li><strong><code>ADR-010</code></strong> — decisions 1 and 5 are sharpened, not reversed: central still derives and still does not accept pushes of derived state. Decision 6's "preliminary" gains a mechanism. The local-cache-versus-database framing stands.</li><li><strong><code>ADR-003</code></strong> — partially superseded. Decision 2 composes fingerprints from filesystem <code>mtime</code>, which is a property of one workstation rather than of the source; under decision 1 here the input is the commit. Decision 5 already stated the rebuild principle correctly but had never been exercised; decision 7 here makes it an operation with a source, a scope and a verification.</li><li><strong><code>ADR-007</code></strong> — derived identifiers become more valuable here: a forge-derived projection and a preliminary overlay compute the same identifier for the same record, so absorbing an overlay entry needs no reconciliation.</li></ul>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>ADR-001</code> — workplans originate as repo files; hub is a read model</li><li><code>ADR-010</code> — hub authority, local cache, and the two kinds of hub data</li><li><code>ADR-007</code> — identifier uniqueness and derived identifiers</li><li><code>CUST-WP-0067</code> — hub target resolution; retired the impersonating local instance</li><li><code>CUST-WP-0068</code> — cache-only work-record recovery; surfaced the stale <code>git_fingerprint</code> and the duplicate registrations</li><li>Verification, 2026-08-25: central pod holds no repository files; <code>sweep</code> disabled; 117 repositories record a laptop path; <code>the-custodian</code> <code>git_fingerprint</code> is the initial commit while <code>last_state_synced_at</code> is current</li></ul>
</section><footer><span>CUST-ADR-012 · 1.0 · accepted</span><span>the-custodian · canon/architecture/adr-012-projection-source-and-preliminary-overlay.md · 6475a2e1ca590682888b77ce32ea056fd02e272a</span></footer></main></div></div></html>

219
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0006.html Normal file
View file

@ -0,0 +1,219 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="e92a43649bb6e14e53ec62ecc819405bf3a44bda9557487f7177402f107bbd13">
<title>Recursive Multi-Tenant Identity and Authorization Architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0006</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Recursive Multi-Tenant Identity and Authorization Architecture</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#follow-up"><span class="n">·</span>Follow-Up</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-05-17 <strong>Deciders:</strong> Bernd Worsch</p>
<section id="context"><h2>Context</h2>
<p>The Coulomb platform is being built from the same repositories and services that will later support other use cases. This creates a recursive architecture problem: Coulomb needs to use the shared identity, security, policy, and deployment capabilities, while those capabilities are themselves part of the infrastructure being built.</p>
<p>If this recursion is left implicit, the first internal use case can drift into being treated as the platform root of trust. That would make future multi-tenant use harder, blur operational authority, and make secure bootstrap/recovery decisions harder to reason about.</p>
<p>NetKingdom already owns identity and security architecture concerns. key-cape provides a lightweight IAM implementation of the NetKingdom IAM Profile. Keycloak remains the expanded production IAM option. privacyIDEA is relevant for MFA/token lifecycle. flex-auth is emerging as the canonical authorization control plane and practical reference implementation of CARING authorization semantics. Topaz is the most likely first delegated authorization runtime behind flex-auth.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>We will document and implement the platform security architecture as a recursive multi-tenant architecture with three explicit planes:</p>
<ul><li><strong>Bootstrap plane</strong> - establishes the first trusted runtime and recovery authority before normal platform services exist.</li><li><strong>Platform control plane</strong> - operates shared identity, MFA, secrets, authorization, policy, audit, and explanation services.</li><li><strong>Tenant plane</strong> - runs Coulomb and future workloads under scoped tenant authority.</li></ul>
<p>Coulomb will be treated as the first internal/reference tenant, not as the platform root of trust.</p>
<p>NetKingdom will own the canonical security architecture and standards. Railiance will own deployment layering and orchestration boundaries. flex-auth will own the canonical authorization interface and CARING-based policy/decision model. Topaz will be the first delegated PDP runtime, with other authorization engines treated as adapters where useful.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Architecture documentation must separate platform-root authority from tenant administration, even for Coulomb.</li><li>Workplans for identity, authorization, and bootstrapping must include explicit tenant and control-plane boundaries.</li><li>Bootstrap design must include trust-state transitions and recovery procedures rather than assuming the final IAM service already exists.</li><li>flex-auth should model tenants, platform resources, CARING descriptors, decision envelopes, and runtime adapters in a provider-neutral way.</li><li>key-cape and Keycloak should be treated as implementations of the IAM Profile, not as the canonical source of resource authorization semantics.</li><li>A future orchestration repo may be useful, but only to coordinate safe sequencing across Railiance and NetKingdom capabilities. It must not bypass Railiance stack ownership.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Treat Coulomb As The Platform Root</h3>
<p>This is simpler during early development but creates long-term coupling between one internal use case and the shared platform. It makes later multi-tenant operation and secure bootstrap harder.</p>
<h3>Put All Security Semantics Into Keycloak</h3>
<p>Keycloak is useful for expanded IAM and can provide authorization features, but making it the canonical model would make lightweight mode and future authorization backends harder to support. The preferred model keeps identity provider concerns separate from canonical authorization semantics.</p>
<h3>Create An Orchestration Repo Immediately</h3>
<p>A dedicated orchestration repo may become appropriate. Creating it before we define trust states and repo boundaries would risk encoding accidental sequence logic too early. The immediate step is to document the state machine and update workplans.</p>
</section>
<section id="follow-up"><h2>Follow-Up</h2>
<ul><li>Refine bootstrapping around explicit trust-state transitions.</li><li>Add tenant/control-plane language to flex-auth authorization workplans.</li><li>Define the first production Topaz integration boundary for flex-auth.</li><li>Decide when key-cape is sufficient and when Keycloak expanded mode is required.</li><li>Decide what, if anything, should live in a future orchestration repo.</li></ul>
</section><footer><span>NK-ADR-0006 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

230
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0007.html Normal file
View file

@ -0,0 +1,230 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="b4fcff8448f07aca1fcb6908618bdb19f6c0e7dce25d4c5c8b85eec2f175233b">
<title>Security Orchestration Boundary</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0007</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Security Orchestration Boundary</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0007-security-orchestration-boundary.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#future-repo-trigger"><span class="n">·</span>Future Repo Trigger</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#refinement-2026-05-21-meta-orchestration-layer"><span class="n">·</span>Refinement (2026-05-21): Meta-Orchestration Layer</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-05-18 <strong>Refined:</strong> 2026-05-21 (meta-orchestration layer — see below) <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>The recursive platform security architecture needs careful sequencing: host trust, cluster trust, bootstrap secrets, runtime secret authority, runtime identity, runtime authorization, tenant onboarding, and readiness verification.</p>
<p>That sequencing crosses NetKingdom and Railiance ownership boundaries. NetKingdom owns the canonical security architecture, IAM Profile, credential/bootstrap standards, and authorization semantics. Railiance owns deployment layering for infrastructure, clusters, platform services, and applications. OpenBao adds an important runtime-secret authority to the platform control plane, but it does not change those ownership boundaries.</p>
<p>Creating a dedicated orchestration repo too early would risk encoding temporary bootstrap order and accidental stack assumptions as a permanent interface. Leaving every sequence implicit would also be risky: platform root actions, OpenBao initialization, policy import, and tenant onboarding must be auditable and repeatable.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Security orchestration will stay in Railiance playbooks for now.</p>
<p>NetKingdom will define the trust-state model, readiness checks, policy semantics, OpenBao boundaries, and tenant/control-plane rules. Railiance playbooks will own the concrete deployment sequencing across <code>railiance-infra</code>, <code>railiance-cluster</code>, <code>railiance-platform</code>, and <code>railiance-apps</code>.</p>
<p>A dedicated orchestration repo is deferred until the sequencing surface is stable enough to justify its own product boundary. If created later, it must coordinate safe sequencing and readiness reporting; it must not own security policy semantics or bypass Railiance stack ownership.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>NK-WP-0006 is implemented as architecture, standards, ADRs, and workplan constraints rather than a new repo.</li><li>OpenBao bootstrap, unseal/recovery, audit, backup, and workload-secret delivery belong in Railiance platform playbooks, governed by NetKingdom standards.</li><li>Cross-repo readiness should be reported as checks against explicit trust states, not as a hidden imperative script.</li><li>A future orchestration repo needs a new ADR before creation.</li></ul>
</section>
<section id="future-repo-trigger"><h2>Future Repo Trigger</h2>
<p>Revisit a dedicated orchestration repo only if at least two of these are true:</p>
<ul><li>multiple Railiance deployments need the same security sequencing interface;</li><li>readiness reporting becomes a reusable artifact consumed by operators, agents, or CI;</li><li>rollback and recovery workflows need a cross-repo state machine that no single Railiance layer can own cleanly;</li><li>tenant onboarding becomes a repeatable workflow spanning identity, flex-auth, Topaz, OpenBao, object storage, and application repos.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Create A Dedicated Orchestration Repo Now</h3>
<p>This would give sequencing a visible home, but it would probably encode unstable details before OpenBao runtime operations, flex-auth/Topaz policy import, and tenant onboarding have enough implementation feedback.</p>
<h3>Put Orchestration In NetKingdom</h3>
<p>NetKingdom owns the security model, but it should not become the deployment repo for every stack layer. This would blur architecture ownership with platform deployment ownership.</p>
<h3>Leave Sequencing Entirely Informal</h3>
<p>This avoids premature structure but leaves bootstrap and runtime trust transitions too dependent on operator memory. The accepted approach keeps the sequence explicit while leaving concrete deployment in the Railiance stack.</p>
</section>
<section id="refinement-2026-05-21-meta-orchestration-layer"><h2>Refinement (2026-05-21): Meta-Orchestration Layer</h2>
<p>The original decision left "what NetKingdom does about orchestration" defined only negatively (it does not own deployment mechanics). This refinement names the positive role. It sharpens, and does not overturn, the accepted decision: execution stays in Railiance.</p>
<p>There are two distinct layers:</p>
<ul><li><strong>Railiance — execution orchestration (the "how").</strong> A library of scenario playbooks plus the tools that run them. Each playbook provisions a slice of the landscape, ships <strong>sensible defaults</strong>, and <strong>exposes parameters</strong> for tuning. Multiple playbooks exist for multiple scenarios.</li><li><strong>NetKingdom — meta-orchestration (the "what" and "who").</strong> NetKingdom does not re-implement deployment mechanics. It (1) <strong>selects</strong> the services and playbooks a given scenario requires, (2) <strong>decides parametrization</strong> where tuning is warranted and otherwise relies on playbook defaults, and (3) <strong>holds the responsibility map</strong> — which element (a Railiance layer, an external provider, a tenant-owned piece) owns what across the whole IT landscape.</li></ul>
<p>The relationship is architect ↔ contractor (or conductor ↔ players): NetKingdom composes the score and assigns parts; Railiance executes them. This is the same discipline used elsewhere — the IAM Profile is the contract while key-cape/Keycloak are implementations, and the State Hub is a read model over execution. Meta-orchestration is a <strong>decide/compose</strong> layer over Railiance's <strong>execute</strong> layer.</p>
<p>This binds directly to the capability ladder (<code>docs/platform-identity-security-architecture.md</code> → <em>Capability Progression</em>): the ladder is the menu, a scenario selects a subset of tiers, and meta-orchestration is the act of binding that subset to playbooks + parameters + a responsibility map, producing a turn-key landscape.</p>
<h3>New Dependency — Playbook / Capability Contract</h3>
<p>For NetKingdom to select and parametrize reliably, <strong>Railiance playbooks must publish a declared interface</strong>: the capability each playbook provisions, its parameters (with defaults and constraints), and the responsibility it claims. This catalog is the orchestration-layer analog of the IAM Profile. Without it, meta-orchestration composes against implicit behavior and breaks when a playbook changes. Establishing this contract is the prerequisite for any concrete meta-orchestration work.</p>
<h3>Effect on the Future Repo Trigger</h3>
<p>Meta-orchestration logic now has a clear home (NetKingdom) regardless of whether a dedicated <strong>execution</strong>-orchestration repo is later created under the Future Repo Trigger above. A future repo, if created, would host reusable execution sequencing — not the scenario-composition and responsibility-mapping role, which remains NetKingdom's.</p>
</section><footer><span>NK-ADR-0007 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0007-security-orchestration-boundary.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

216
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0008.html Normal file
View file

@ -0,0 +1,216 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="f47276f4953f62b783397ee7fb1d3693da060103247e425a9a5b40d019fb4272">
<title>Object Storage STS Credential Vending Boundary</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0008</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Object Storage STS Credential Vending Boundary</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0008-object-storage-sts-credential-vending.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-05-18 <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>NetKingdom needs a canonical pattern for issuing short-lived object-storage credentials to platform and tenant workloads. The first known consumer is <code>artifact-store</code>, but the pattern must work for future S3-compatible consumers without making each application repo own identity, authorization, root object-store credentials, or backend-specific STS differences.</p>
<p>The backend landscape is not uniform. AWS S3, Ceph RGW, and MinIO/AIStor can use web-identity STS-style flows. Cloudflare R2 exposes temporary credentials through a provider API or local signing with parent access material. OpenBao is now part of the Railiance platform stack as runtime secret authority, but it is not an identity provider or authorization policy engine.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>NetKingdom will define a provider-neutral credential-vending interface backed by provider-native temporary credential mechanisms where possible.</p>
<p>The trust path is:</p>
<ol><li>IAM Profile token proves the actor or workload.</li><li>flex-auth decides whether the actor may receive credentials for the requested protected system, tenant, bucket, prefix, action set, TTL, and assurance level.</li><li>The credential-vending service exchanges the approved request with the backend-specific temporary credential mechanism.</li><li>OpenBao stores parent credentials, broker configuration, lease metadata, and audit evidence where useful, but it does not replace flex-auth authorization.</li><li>Consumers receive normalized temporary credentials containing access key id, secret access key, session token, and expiration.</li></ol>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>artifact-store</code> needs temporary credential support, especially <code>AWS_SESSION_TOKEN</code> and refresh behavior, before it can fully consume the production vending pattern.</li><li>Backend-specific differences are isolated in the vending service, not leaked into application policy.</li><li>OpenBao remains runtime secret infrastructure and audit support; it does not become the object-storage policy source.</li><li>Provider-native STS is preferred when available because it gives the storage backend direct lease/expiration semantics.</li><li>Cloudflare R2 requires a broker path that protects parent access material, most likely through OpenBao custody.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Give Applications Long-Lived Access Keys</h3>
<p>This is simple but leaves applications holding durable credentials and pushes policy into ad hoc bucket configuration. It is acceptable only as a transitional bridge with scoped credentials and explicit rotation.</p>
<h3>Put Object-Storage Policy In Keycloak Or key-cape</h3>
<p>Identity providers can assert who the actor is and coarse groups or roles, but they should not become the canonical source of bucket, prefix, action, TTL, and explanation semantics.</p>
<h3>Use OpenBao As The Credential Vending Policy Engine</h3>
<p>OpenBao is valuable for secret custody, broker configuration, leases, and audit records. Making it the policy decision point would duplicate flex-auth, blur the platform/tenant boundary, and make authorization semantics backend-specific.</p>
<h3>Require One Backend Everywhere</h3>
<p>A single backend would simplify implementation but does not match the platform direction. Railiance and NetKingdom need a stable security interface across AWS, self-hosted S3-compatible stores, and Cloudflare R2-like APIs.</p>
</section><footer><span>NK-ADR-0008 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0008-object-storage-sts-credential-vending.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

221
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0010.html Normal file
View file

@ -0,0 +1,221 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="b7c4f6a13f2f5add08bd03cb39c4f18ca25b202747dde883a309d1b3eaa1f571">
<title>Orchestration vs Dependency, and Self-Coherent Intent</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0010</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Orchestration vs Dependency, and Self-Coherent Intent</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li></ol></nav><main><p><strong>Status:</strong> Accepted (repo classification subject to ongoing refinement) <strong>Date:</strong> 2026-05-21 <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>While aligning the ecosystem's <code>INTENT.md</code> files, two relationships that had been blurred turned out to be fundamentally different, and a content principle for intent emerged. Both are foundational enough that future interface and boundary refinements should be measured against them.</p>
<p>NetKingdom performs meta-orchestration (ADR-0007): it selects, parametrizes, and assigns responsibility across an IT landscape. But "things NetKingdom meta-orchestrates" is not the same as "things NetKingdom depends on," and the two had been conflated.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>Principle 1 — Orchestration is not dependency</h3>
<p>NetKingdom relates to other repositories in two distinct ways:</p>
<ul><li><strong>Orchestrated</strong> — the repo provides a service that <strong>holds resources NetKingdom must manage</strong>: users, roles, scopes, policies, credentials, infrastructure resources, and the like. NetKingdom composes, parametrizes, and holds responsibility for those resources.</li><li><strong>Dependency</strong> — NetKingdom <strong>uses the repo as a tool</strong> to provide its own interface, without managing resources the tool holds.</li></ul>
<p><strong>The defining question:</strong> <em>does the repo provide a service holding resources that NetKingdom needs to orchestrate?</em></p>
<ul><li>Yes → <strong>orchestrated</strong>.</li><li>No, it is merely used → <strong>dependency</strong>.</li></ul>
<p>Worked examples:</p>
<ul><li><code>railiance-fabric</code> is a tool NetKingdom uses to provide an interface; it holds no NetKingdom-managed resources → <strong>dependency</strong>.</li><li><code>railiance-infra</code>, <code>railiance-cluster</code>, <code>railiance-platform</code> define and hold resources → <strong>orchestrated</strong>.</li><li>An IAM directory (users, groups) or a policy store (roles, scopes, policies) holds exactly the resource kinds in the criterion → <strong>orchestrated</strong>.</li></ul>
<p>This classification is applied now (see the responsibility map) and will be refined as interfaces and boundaries mature. Borderline cases are expected.</p>
<h3>Principle 2 — Intent is self-coherent</h3>
<p>Every repository's <code>INTENT.md</code> describes <strong>that repository's own</strong> purpose and direction, abstractly and stably. Therefore:</p>
<ul><li>It must <strong>not</strong> define itself in terms of NetKingdom.</li><li>It must <strong>not</strong> reference the intent of sister projects.</li><li>It must <strong>not</strong> even encode dependencies — dependencies are more concrete and less stable than intent should be.</li></ul>
<p>Intent is the most abstract, most stable layer. Relationships — orchestration, dependency, interfaces, boundaries — are recorded <strong>outside</strong> intent: in NetKingdom's responsibility map, architecture docs, ADRs, and interface contracts. This keeps every repo's intent free of external reference points, so it stays stable while the interfaces and boundaries between repos are refined over time.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>The earlier idea of adding a "place in the NetKingdom-orchestrated landscape" block to downstream <code>INTENT.md</code> files is <strong>rejected</strong>. It would violate Principle 2.</li><li>Cross-repo <code>INTENT.md</code> work becomes: ensure each orchestrated repo has a <strong>self-coherent</strong> intent — author one where missing, and remove external references (to NetKingdom or sister projects) where present.</li><li>The orchestration/dependency relationship and the per-repo <strong>responsibility map</strong> live in net-kingdom, not in the downstream repos.</li><li>A responsibility-map artifact in net-kingdom enumerates, per orchestrated repo, which resources NetKingdom manages: <code>docs/responsibility-map.md</code>.</li><li>ADR-0007's meta-orchestration layer is unchanged; this ADR clarifies <em>what</em> NetKingdom orchestrates versus merely uses.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Treat every related repo uniformly</h3>
<p>Simpler, but it conflates "manages the resources this service holds" with "uses this tool," which produces an incoherent responsibility map and tempts downstream repos to encode NetKingdom into their intent.</p>
<h3>Record relationships inside each repo's intent</h3>
<p>Convenient for a reader of a single repo, but it couples intents to each other and to NetKingdom, making the most-stable layer the least stable. Relationships belong in interface contracts and the responsibility map.</p>
</section><footer><span>NK-ADR-0010 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

227
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0011.html Normal file
View file

@ -0,0 +1,227 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="b5c7fd1e78026063b4a2ca4017202512d4f94ab5e12dc8498a34d04d3a48c7a9">
<title>NetKingdom IAM Profile Ownership And Version Governance</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0011</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom IAM Profile Ownership And Version Governance</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#versioning"><span class="n">·</span>Versioning</a></li><li><a href="#breaking-change-governance"><span class="n">·</span>Breaking-Change Governance</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-05-22 <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>The IAM Profile is the identity contract that applications, flex-auth, key-cape, Keycloak, and bootstrap identity tooling all target. It defines the OIDC discovery, flow, token, claim, assurance, tenant, and conformance requirements that make lightweight and expanded identity modes interchangeable at the application boundary.</p>
<p>A draft IAM Profile v0.1 existed in the-custodian canon with an all-hubs scope. That draft captured useful material: OIDC discovery, Authorization Code + PKCE, service-account tokens, required claims, token lifecycle, emergency access, and local-development behavior. However, NetKingdom now owns the platform identity domain. SCOPE.md names the NetKingdom IAM Profile as an in-scope, versioned standard, and ADR-0006 requires key-cape and Keycloak to be implementations of the profile rather than the canonical source of authorization semantics.</p>
<p>The v0.1 draft also used hub-specific scope and role vocabulary. That made sense for the Custodian hub landscape, but the core NetKingdom profile must be platform-neutral so it can serve tenant, service, application, and agent use cases without encoding one downstream system's scope names.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>NetKingdom is the canonical owner of the IAM Profile.</p>
<p>The profile is versioned under <code>canon/standards/</code> in this repository. The first canonical NetKingdom version is <code>canon/standards/iam-profile_v0.2.md</code>.</p>
<p>The relationship to the earlier the-custodian draft is:</p>
<ul><li>the-custodian IAM Profile v0.1 is superseded as a core/platform standard;</li><li>NetKingdom owns the provider-neutral core profile;</li><li>downstream systems may define hub-, tenant-, or application-specific scopes and roles as extensions, but those extensions must map back to the core identity and authorization input contract;</li><li>key-cape lightweight mode and Keycloak expanded mode are interchangeable implementations of the same profile;</li><li>flex-auth consumes the profile as normative identity input and must not re-derive identity facts from provider-specific state.</li></ul>
</section>
<section id="versioning"><h2>Versioning</h2>
<p>The IAM Profile uses explicit document versions:</p>
<ul><li>Patch/editorial changes clarify wording, examples, or non-normative guidance without changing the token contract.</li><li>Minor versions add optional claims, optional flows, or additional conformance checks that existing implementations can pass unchanged.</li><li>Major or breaking versions change required claims, claim meanings, validation rules, flow requirements, assurance semantics, tenant semantics, or token acceptance rules.</li></ul>
<p>Every versioned profile file remains immutable enough for downstream references to cite. New versions are added as new files rather than rewriting historical versions in place, except for clearly editorial fixes that do not affect semantics.</p>
</section>
<section id="breaking-change-governance"><h2>Breaking-Change Governance</h2>
<p>A breaking profile change requires:</p>
<ol><li>a new ADR or ADR refinement that explains the change and migration path;</li><li>a new versioned profile document;</li><li>an update to the executable conformance suite;</li><li>a coexistence window that lets at least one previous supported profile version and the new version be accepted where practical;</li><li>notification in workplans or interface docs for known consumers, especially key-cape, Keycloak/expanded-mode work, flex-auth, and application integration docs.</li></ol>
<p>Breaking changes include:</p>
<ul><li>removing or renaming a required claim;</li><li>changing the meaning, type, or allowed values of required claims such as <code>tenant</code>, <code>principal_type</code>, <code>roles</code>, <code>groups</code>, <code>scope</code>/<code>scp</code>, or <code>assurance</code>;</li><li>changing accepted issuer, audience, or signing validation rules;</li><li>weakening PKCE, MFA/assurance, local-development rejection, or emergency-access requirements;</li><li>moving authorization decisions into an identity provider instead of flex-auth.</li></ul>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>canon/standards/iam-profile_v0.2.md</code> is the canonical profile.</li><li>the-custodian's v0.1 draft should carry a relocation/deprecation note pointing to this repository.</li><li>Hub-specific scopes such as <code>hub:*</code>, <code>ops:*</code>, and <code>fin:*</code> are downstream extensions, not core profile vocabulary.</li><li>key-cape and Keycloak must emit or normalize to the same claim contract before applications and flex-auth consume tokens.</li><li>The conformance suite in <code>tools/iam-profile-conformance/</code> is the executable contract for implementations.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Keep The Custodian Draft As Canonical</h3>
<p>The draft is useful, but keeping ownership there would conflict with NetKingdom's repository scope and with ADR-0006's responsibility split. It would also leave the profile coupled to Custodian hub vocabulary.</p>
<h3>Make Keycloak The Reference Provider</h3>
<p>Keycloak is the expanded-mode implementation and remains important for enterprise federation. Making it the reference provider would make lightweight mode, local bootstrap, and future identity adapters secondary to one implementation. The accepted model keeps providers interchangeable behind the profile.</p>
<h3>Put Scope And Role Vocabulary In The Core Profile</h3>
<p>A shared vocabulary is useful, but core identity must stay stable across applications and tenants. Downstream systems can define extension scopes and roles as long as they map to the core claim shapes and flex-auth decision inputs.</p>
</section><footer><span>NK-ADR-0011 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

227
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0012.html Normal file
View file

@ -0,0 +1,227 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="e269fabfc376f97f2a03ea66e34059d54016a445a7f30b351a6774b65c96c2ee">
<title>Playbook Capability Contract Ownership</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0012</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Playbook Capability Contract Ownership</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0012-playbook-capability-contract-ownership.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#versioning"><span class="n">·</span>Versioning</a></li><li><a href="#breaking-change-governance"><span class="n">·</span>Breaking-Change Governance</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-05-22 <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>ADR-0007 refined NetKingdom's orchestration role into a meta-orchestration layer. NetKingdom selects the services and playbooks a scenario needs, decides which parameters may be tuned, and holds the responsibility map. Railiance remains the execution-orchestration layer: Railiance playbooks provision and converge the actual infrastructure, cluster, platform services, and application layers.</p>
<p>That split requires a stable interface. If a Railiance playbook only describes behavior implicitly, NetKingdom cannot safely compose it into a scenario, compare it with another playbook, or know which parameter changes are safe. The IAM Profile provides the precedent: the consumer that needs a stable contract defines the contract, and providers conform to it.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>NetKingdom owns the Playbook Capability Contract schema and vocabulary. Railiance owns playbook implementation and publishes one conformant declaration per playbook.</p>
<p>The first canonical contract is <code>canon/standards/playbook-capability-contract_v0.1.md</code>, backed by the machine-readable schema in <code>canon/schemas/playbook-capability-declaration_v0.1.schema.json</code> and the validator in <code>tools/playbook-capability-contract/</code>.</p>
<p>The contract is NetKingdom-owned with Railiance co-design:</p>
<ul><li>NetKingdom defines the schema, controlled vocabulary, trust-state language, parameter-sensitivity rules, and conformance criteria.</li><li>Railiance authors and maintains declarations beside the playbooks they describe.</li><li>Railiance execution stays unchanged. The declaration never becomes the playbook runner.</li><li>NetKingdom meta-orchestration consumes declarations to select, parametrize, sequence, and build responsibility maps for scenarios.</li></ul>
<p>ADR-0007 remains unchanged: execution stays in Railiance.</p>
</section>
<section id="versioning"><h2>Versioning</h2>
<p>The contract uses explicit document versions:</p>
<ul><li>Patch/editorial changes clarify wording or examples without changing declaration semantics.</li><li>Minor versions add optional fields, vocabulary entries, or validator warnings that existing declarations can ignore.</li><li>Breaking versions change required fields, field meanings, allowed vocabulary, parameter-sensitivity semantics, trust-state semantics, or catalog consumption rules.</li></ul>
<p>Declarations carry <code>metadata.contract_version</code>. A catalog may accept more than one contract version during a migration window, but must report the version used for each selected playbook.</p>
</section>
<section id="breaking-change-governance"><h2>Breaking-Change Governance</h2>
<p>A breaking change requires:</p>
<ol><li>an ADR or ADR refinement explaining the change and migration path;</li><li>a new versioned standard and schema;</li><li>an updated validator;</li><li>a coexistence window for the previous supported version where practical;</li><li>notice to known declaration publishers, especially Railiance repos.</li></ol>
<p>Breaking changes include:</p>
<ul><li>removing or renaming required fields;</li><li>changing capability ids or resource-kind vocabulary;</li><li>changing trust-state meanings;</li><li>changing which parameter sensitivities are tenant-tunable;</li><li>changing catalog selection or override semantics;</li><li>moving execution responsibility out of Railiance into NetKingdom.</li></ul>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Playbook declaration files live beside Railiance playbooks, normally at <code>capabilities/playbooks/*.yaml</code>.</li><li>NetKingdom can validate declarations before consuming them.</li><li>A playbook interface change becomes visible and versioned instead of an implicit break.</li><li>The responsibility map can be assembled from declarations, while Railiance keeps execution ownership.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Put The Contract In Railiance</h3>
<p>Railiance owns execution, so this is tempting. But NetKingdom is the consumer that needs stable scenario composition and responsibility-map inputs. Keeping the contract in NetKingdom mirrors the IAM Profile pattern and keeps scenario semantics close to the responsibility map.</p>
<h3>Make Declarations Free-Form Documentation</h3>
<p>Free-form docs are readable but not safely composable. NetKingdom needs a validator and controlled vocabulary so a playbook change cannot silently break a scenario.</p>
<h3>Build A Dedicated Execution-Orchestration Repo Now</h3>
<p>ADR-0007 explicitly defers that. The contract is useful now and does not require a new runner or repo boundary.</p>
</section><footer><span>NK-ADR-0012 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0012-playbook-capability-contract-ownership.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

241
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0013.html Normal file
View file

@ -0,0 +1,241 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="3a6030a8958176a902942ffd29154104ba3441a09d06edf3deaeadc7291ee0d4">
<title>Tenant Onboarding Grouping Taxonomy</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0013</span> <span class="stat">accepted · 2</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Tenant Onboarding Grouping Taxonomy</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#scope-and-governance-classification"><span class="n">·</span>Scope and Governance Classification</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#follow-up"><span class="n">·</span>Follow-Up</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-07-23 <strong>Amended:</strong> 2026-08-22 (current classification versus historical identifier segment) <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p><code>canon/standards/iam-profile_v0.2.md</code>'s "Tenant Claim" section lists four <em>suggested</em> (not exhaustive) tenant identifiers: <code>tenant:platform</code>, <code>tenant:coulomb</code>, <code>tenant:sandbox:&lt;name&gt;</code>, <code>tenant:customer:&lt;name&gt;</code>.</p>
<p>Separately, an unratified exploration (<code>docs/princedom-isolation-exploration.md</code>) proposes a non-exclusive <strong>capability-role</strong> model for tenants: <code>PLTF</code> (operates the platform), <code>IAM</code> (organizes its own users/secrets), <code>VEN</code> (provides apps/services to others), <code>CUS</code> (consumes apps/services from <code>PLTF</code> or <code>VEN</code> tenants) — one tenant can hold multiple roles simultaneously.</p>
<p>Binky Hedgehog GmbH is being onboarded as the platform's first tenant outside <code>tenant:coulomb</code> (<code>key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md</code>), forcing a concrete identifier decision. Binky already exercises both <code>CUS</code> (consumes <code>qonto-assistant</code>) and, per <code>binky-control/INTENT.md</code>, will exercise <code>VEN</code> (packages and sells offers built on the ecosystem to real external customers) — it is not purely a "customer" in the role sense.</p>
<p>Using a capability-role word (<code>customer</code>, <code>vendor</code>, ...) as the tenant <em>grouping</em> segment collides with that separate role dimension: a tenant labeled <code>tenant:customer:binky</code> would carry a stale, misleading label the moment it also starts acting as a vendor, and tenant identifiers are expensive to rename once tokens, OpenBao paths, and downstream config reference them.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Adopt an onboarding-risk / entity-shape <strong>grouping</strong> taxonomy for the tenant identifier's second segment, replacing the <code>sandbox</code>/<code>customer</code> suggested identifiers in <code>iam-profile_v0.2.md</code>'s "Tenant Claim" section:</p>
<pre>tenant:&lt;grouping&gt;:&lt;name&gt;
trial - test/trial/showcase tenants only
friendly - known, easily reached, tolerant of experimentation/instability
single - one-person business entities (freelance consultants)
small - up to 10 employees at time of onboarding (attoo)
medium - up to 100 employees (attoo)
large - up to 1000 employees (attoo)
enterprise - 1001+ employees (attoo)
consumer - private individuals
family - a legal family
community - a non-legal group of people
association - a legal association of people
agentic - financially enabled AI entities</pre>
<p>The taxonomy has two deliberately different uses:</p>
<ul><li>At creation, the identifier's grouping segment records the tenant's onboarding-time classification. The complete identifier is immutable, so this segment is historical after creation.</li><li>The tenant record's <code>grouping</code> field records current classification. It may change as the entity changes and is authoritative for present-day policy, including guardrails and spend ceilings.</li></ul>
<p>No consumer may parse the identifier's middle segment and treat it as current grouping. Consumers needing current grouping MUST read it from <code>tenant-engine</code>. Identifier creation still validates the segment against this vocabulary; historical does not mean free-form or optional.</p>
<p>Grouping is deliberately <strong>orthogonal to capability role</strong> (<code>PLTF</code>/<code>IAM</code>/<code>VEN</code>/<code>CUS</code>, subsequently ratified by ADR-0014): grouping describes <em>what kind of entity a tenant is and its current onboarding-risk classification</em>; role describes <em>what it does on the platform</em>. Both are carried as tenant metadata, but never conflated into the immutable identifier segment — that conflation is exactly what this ADR avoids.</p>
<p><code>tenant:platform</code> and <code>tenant:coulomb</code> remain <strong>reserved, ungrouped identifiers outside this taxonomy</strong>: <code>tenant:platform</code> is the control-plane root, not a business entity being onboarded; <code>tenant:coulomb</code> is the reference tenant established by ADR-0006, predating this taxonomy, and none of the twelve groupings meaningfully describe "the platform building itself." The taxonomy applies to tenants onboarded from here forward. <em>(This sub-point completes an open question raised during KEY-WP-0004 drafting and is Codex's reasoned proposal — flagged for Bernd's explicit confirmation rather than assumed settled.)</em></p>
<p>First application: Binky Hedgehog GmbH maps to <code>friendly</code> — known, reachable, tolerant of early instability — giving <strong><code>tenant:friendly:binky</code></strong> (<code>key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md</code>).</p>
</section>
<section id="scope-and-governance-classification"><h2>Scope and Governance Classification</h2>
<p>Per ADR-0011's breaking-change governance, this does <strong>not</strong> meet the breaking-change bar: it doesn't add, remove, or rename a required claim; it doesn't change <code>tenant</code>'s type or validation rule (still an opaque string); it doesn't affect acceptance of any previously-issued token (<code>tenant:platform</code>, <code>tenant:coulomb</code> tokens remain valid as-is, and no <code>tenant:customer:*</code> or <code>tenant:sandbox:*</code> tokens have been issued yet). It only replaces non-normative suggested-identifier guidance for tenants onboarded going forward.</p>
<p>Per ADR-0011's own versioning rule ("New versions are added as new files... except for clearly editorial fixes that do not affect semantics"), this qualifies as an <strong>editorial update</strong> to <code>iam-profile_v0.2.md</code>'s Tenant Claim section — not a new versioned profile document.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>canon/standards/iam-profile_v0.2.md</code>'s "Tenant Claim" section needs a follow-up edit replacing the <code>sandbox</code>/<code>customer</code> suggested identifiers with this taxonomy. Not made by this ADR itself — tracked as follow-up so the change is reviewable on its own.</li><li><code>key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md</code> already reflects this decision (<code>tenant:friendly:binky</code>).</li><li>Future tenant onboarding work should classify a tenant against this list before minting an identifier, rather than reaching for a role word.</li><li>Tenant identifiers never change when current grouping changes. The middle segment is creation-time history; <code>tenant-engine</code> is authoritative for the current grouping value.</li><li>Policy and commercial consumers, including spend-ceiling resolution, MUST query <code>tenant-engine</code> and MUST NOT derive current grouping by splitting a tenant identifier.</li><li>The capability-role model (<code>PLTF</code>/<code>IAM</code>/<code>VEN</code>/<code>CUS</code>) remains a separate dimension, now ratified by ADR-0014. Role metadata is carried alongside — not instead of — current grouping and the historical identifier segment.</li><li><code>tenant:platform</code> and <code>tenant:coulomb</code> are reserved outside the taxonomy, pending Bernd's explicit confirmation (see Decision).</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Keep using capability-role words as the tenant grouping</h3>
<p>Rejected: tenants are already known to hold multiple roles at once (Binky is <code>CUS</code> now, <code>VEN</code> later); a role-word grouping would need renaming as a tenant's roles evolve, which tenant identifiers are specifically expensive to do once tokens, OpenBao paths, and config reference them.</p>
<h3>Retrofit <code>tenant:coulomb</code> into the new taxonomy</h3>
<p>Considered <code>tenant:friendly:coulomb</code> or similar. Rejected for now: Coulomb is structurally the reference tenant from ADR-0006, predating this taxonomy, and none of the twelve entity-shape groupings describe "the platform's own ecosystem-development tenant." Revisit if a future grouping is ever added that genuinely fits it.</p>
<h3>Do nothing / keep the four original suggested identifiers</h3>
<p>Rejected: <code>tenant:customer:binky</code> was the working default going into Binky's onboarding despite the role-collision problem above; the fleet needs this resolved before the first non-Coulomb tenant goes live, not after.</p>
</section>
<section id="follow-up"><h2>Follow-Up</h2>
<ul><li>Edit <code>canon/standards/iam-profile_v0.2.md</code>'s Tenant Claim section to replace the old suggested identifiers with this taxonomy (separate, reviewable change).</li><li>Confirm the <code>tenant:platform</code>/<code>tenant:coulomb</code> reserved/ungrouped treatment explicitly.</li><li>ADR-0014 and the Tenant Engine Boundary Contract define how capability-role metadata is carried alongside grouping.</li><li>Keep <code>tenant-engine</code>'s identifier parser vocabulary-validating for creation and lookup compatibility, but do not expose parsed grouping as current classification.</li></ul>
</section><footer><span>NK-ADR-0013 · 2 · accepted</span><span>net-kingdom · docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

225
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0014.html Normal file
View file

@ -0,0 +1,225 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="843f7a65f0fc145d08a73e364bc9a1dee0f7b8af934abf1584ee39dffa903ee0">
<title>Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownership</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0014</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>Tenant Capability Roles, Carrying Mechanism, and Tenant-Engine Ownership</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#follow-up"><span class="n">·</span>Follow-Up</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-07-23 <strong>Deciders:</strong> Bernd Worsch, Codex</p>
<section id="context"><h2>Context</h2>
<p>ADR-0013 introduced the tenant onboarding grouping taxonomy (<code>trial</code>/<code>friendly</code>/<code>single</code>/.../<code>agentic</code>), deliberately orthogonal to a separate, unratified <strong>capability-role</strong> model sketched in <code>docs/princedom-isolation-exploration.md</code>: <code>PLTF</code> (operates the platform), <code>IAM</code> (organizes its own users/auth/secrets), <code>VEN</code> (provides apps/services to others), <code>CUS</code> (consumes apps/services from <code>PLTF</code> or <code>VEN</code> tenants) — non-exclusive, a tenant may hold several at once.</p>
<p>That exploration left open where capability roles actually live (a per-token claim vs. a registry), who owns them, how they're granted or revoked, and how this interacts with the IAM Profile's existing <code>roles</code> claim — which is a <em>per-subject</em> claim ("coarse identity roles" for the human/service/agent holding the token), a different concept from a <em>per-tenant</em> capability fact. Conflating the two would be a category error: <code>roles: [&quot;VEN&quot;]</code> on a token would ambiguously mean "this subject has vendor-role" vs. "this subject's tenant is a vendor."</p>
<p>No existing service owns tenant-as-an-entity facts (existence, grouping, capability roles, plan/subscription state) as a queryable resource. <code>user-engine</code>'s own boundary contract (<code>canon/standards/user-engine-boundary-contract_v0.1.md</code>) explicitly scopes <code>user-engine</code> to <em>consuming</em> tenant identifiers and <em>storing tenant-scoped records</em>, not owning tenant identity or capability facts.</p>
<p>Bernd's direction (2026-07-23):</p>
<ul><li>Implement the previously-discussed hybrid carrying approach: cache a tenant's capability roles on the token for ordinary decisions, but require a live check for critical/high-stakes actions.</li><li>Role grants are usually tied to a payment plan — most concretely, <code>IAM</code> means the tenant has its own dedicated key-cape/Keycloak instance for isolation, scale, and performance, which is itself a paid capability.</li><li><code>trial</code>-grouped tenants may hold <strong>any</strong> capability role without restriction, specifically so the platform can showcase, test, and explore every role. Safety for trial tenants comes from resource guardrails (spend limits defaulting to zero budget, entity/action count limits), not from role gating — guardrail design itself is future work, not this ADR.</li><li>A new service, <code>tenant-engine</code>, will be built (Bernd) as the owner of this domain, organized beside <code>user-engine</code> rather than inside it — smaller, single-purpose services are easier to reason about and drift less, matching the fleet's existing convention (<code>activity-core</code>, <code>audit-core</code>, <code>user-engine</code>, and others).</li></ul>
</section>
<section id="decision"><h2>Decision</h2>
<ol><li><strong>Capability-role vocabulary ratified as core NetKingdom vocabulary</strong>: <code>PLTF</code>, <code>IAM</code>, <code>VEN</code>, <code>CUS</code>, non-exclusive. <code>IAM</code> specifically means: the tenant operates its own dedicated IAM implementation instance (lightweight key-cape or expanded Keycloak) rather than sharing the platform's, for isolation/scale/performance — not "any tenant that happens to have users."</li></ol>
<ol><li><strong><code>tenant-engine</code> is the canonical owner</strong> of tenant-domain facts: tenant existence, grouping (ADR-0013), capability roles (this ADR), plan/ subscription assignment, and — reserved for future design, not built now — guardrail/quota policy. It is a new, separate service, not a module inside <code>user-engine</code>. Its ownership boundary is defined in the companion contract, <code>canon/standards/tenant-engine-boundary-contract_v0.1.md</code>.</li></ol>
<ol><li><strong>Carrying mechanism: hybrid cache + live re-validation.</strong> <code>tenant-engine</code> is the single source of truth. <code>key-cape</code> stamps a cached, optional <code>tenant_roles</code> claim onto issued tokens at issuance time, sourced from <code>tenant-engine</code> (added to the IAM Profile as a new optional claim — <code>canon/standards/iam-profile_v0.3.md</code>). Consumers may trust the cached claim for ordinary decisions. <code>flex-auth</code> <strong>MUST</strong> re-validate live against <code>tenant-engine</code> — never trust the cached claim alone — before authorizing privileged or high-stakes actions, using the same threshold class the profile already defines for <code>assurance.level &gt;= aal2</code> (privileged, destructive, platform-root, secret, credential-vending flows). This bounds staleness risk for ordinary actions to a token's short lifetime (5–30 minutes for service/agent tokens, per the profile's Token Lifecycle table) while guaranteeing freshness exactly where it matters most.</li></ol>
<ol><li><strong>Role governance is plan-linked.</strong> Granting a role is normally a consequence of a tenant's payment-plan state in <code>tenant-engine</code>, not a separate manual workflow — starting with <code>IAM</code>. <code>tenant-engine</code> records which plan grants which role(s); <code>adaptive-pricing</code> remains the source of plan/pricing-model <em>definitions</em>, <code>tenant-engine</code> owns the tenant's <em>current</em> plan/subscription assignment, referenced by id, never duplicated locally. Whether <code>VEN</code> needs an approval gate beyond payment (reselling access carries legal/compliance exposure a payment alone doesn't cover) is <strong>not resolved by this ADR</strong> — left to <code>tenant-engine</code>'s own workplan.</li></ol>
<ol><li><strong>Trial tenants may hold any capability role, unrestricted.</strong> The <code>trial</code> grouping's purpose (showcase, test, explore) requires demonstrating every role. Safety is enforced through resource guardrails instead: trial tenants default to a <strong>spend budget of zero</strong>, with entity and action count limits to follow. Guardrail policy design (exact limits, enforcement point, override process) is real, near-term future work, reserved as <code>tenant-engine</code>'s to own once designed — not specified by this ADR.</li></ol>
<ol><li><strong>Grouping and capability role are independent axes</strong> recorded on the same tenant record in <code>tenant-engine</code>. Neither constrains the other except where a future guardrail policy explicitly says so.</li></ol>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>canon/standards/iam-profile_v0.3.md</code> adds the optional <code>tenant_roles</code> claim and folds in ADR-0013's tenant-identifier vocabulary update (both non-breaking per ADR-0011's own minor-version rule — no existing implementation is invalidated by either change). Supersedes <code>iam-profile_v0.2.md</code>.</li><li><code>tenant-engine</code> becomes a new repository with its own workplans (Bernd). <code>canon/standards/tenant-engine-boundary-contract_v0.1.md</code> defines its ownership boundary now, before code exists — the same sequencing <code>user-engine</code>'s contract followed.</li><li><code>flex-auth</code> policy packages gating high-stakes actions must add a <code>tenant-engine</code> live-lookup step; they cannot trust <code>tenant_roles</code> alone for those decisions.</li><li><code>key-cape</code> needs a <code>tenant-engine</code> integration at token-issuance time to source the cached claim — tracked in <code>key-cape</code>'s own workplans, not here.</li><li><code>docs/platform-identity-security-architecture.md</code>'s Tenant Model section is updated to reflect the grouping + role split and <code>tenant-engine</code>'s role (companion change alongside this ADR).</li><li>Guardrail/quota policy is named as required near-term work and given an owner (<code>tenant-engine</code>), but is explicitly not designed by this ADR.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<h3>Token-claim-only, no live re-validation</h3>
<p>Rejected: staleness would be unbounded within a token's lifetime for genuinely high-stakes actions. A stale <code>VEN</code> grant surviving a plan downgrade or cancellation is not an acceptable risk for money-movement or credential-vending flows — exactly the class the profile already treats as requiring the strongest assurance.</p>
<h3>Registry-only, no cached claim</h3>
<p>Rejected: every ordinary request would pay a <code>tenant-engine</code> round-trip even for non-critical checks, adding latency and a hard runtime dependency for every consumer, not just the ones handling privileged actions.</p>
<h3>Restrict role eligibility by tenant grouping (e.g., <code>trial</code> cannot hold <code>VEN</code>)</h3>
<p>Rejected per Bernd's direction: <code>trial</code> tenants exist specifically to showcase every role. Resource guardrails are the intended safety mechanism instead, keeping the two axes (grouping, role) independent.</p>
<h3>Put tenant-role/plan storage inside <code>user-engine</code></h3>
<p>Rejected. <code>user-engine</code>'s own boundary contract scopes it to consuming tenant identifiers and storing tenant-<em>scoped</em> user records, not owning tenant-as-an-entity facts. A dedicated service avoids coupling a security-critical, high-frequency lookup (used by <code>flex-auth</code> on every privileged decision, and by <code>key-cape</code> on every token issuance) to <code>user-engine</code>'s much larger surface (registration flows, factor models, family dataspace onboarding) that has nothing to do with tenant capability state.</p>
</section>
<section id="follow-up"><h2>Follow-Up</h2>
<ul><li><code>tenant-engine</code> repository creation and its own workplan (Bernd).</li><li><code>key-cape</code> integration: source <code>tenant_roles</code> from <code>tenant-engine</code> at token issuance.</li><li><code>flex-auth</code> policy package updates: live <code>tenant-engine</code> re-validation gate for privileged actions.</li><li>Guardrail/quota policy design for <code>trial</code> (and eventually all) tenants: spend limits, entity/action count limits, enforcement point, override process.</li><li>Resolve whether <code>VEN</code> needs an approval gate beyond payment-plan state.</li></ul>
</section><footer><span>NK-ADR-0014 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

229
docs/evidence/2026-10-11-served-publication-history/pages/NK-ADR-0015.html Normal file
View file

@ -0,0 +1,229 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="2000985ef211aeedd3656e15cedb289e655526c2dcc4a161a64ffc27f0289db1">
<title>NetKingdom Railiance Workload Packaging and Relational Platform</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>NK-ADR-0015</span> <span class="stat">accepted · 1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Railiance Workload Packaging and Relational Platform</h1><p class="sub">Source: <code>net-kingdom · docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#follow-up"><span class="n">·</span>Follow-Up</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-08-11 <strong>Deciders:</strong> Bernd Worsch, Claude</p>
<section id="context"><h2>Context</h2>
<p>NetKingdom's runtime services are deployed today outside the Railiance reef/rail/<code>rapp</code> model. <code>tenant-engine</code> and <code>user-engine</code> run on the coulomb substrate with digest-pinned images (<code>forgejo.coulomb.social/coulomb/{tenant,user}-engine@sha256:…</code>), but their Kubernetes manifests live in this repo at <code>sso-mfa/k8s/&lt;service&gt;/runtime.yaml</code> — a canon repo holding runtime YAML — applied imperatively, with <code>verify-t0*.sh</code> scripts as verification. Neither service declares <code>railiance/app.toml</code>, appears in <code>reef-railiance/bindings/rapps.yaml</code>, or is reconciled by a GitOps controller.</p>
<p>The decision to bring NetKingdom under Railiance governance forces two questions this ADR settles.</p>
<p><strong>Packaging granularity.</strong> <code>railiance-master/docs/repository-axes.md</code> maps <code>rapp-*</code> to "one Railiance-managed workload" and states that a <code>rapp</code> "does not replace the responsibility repo that owns the broader domain. It is explicitly about managed wrapping, not ownership." Precedent exists in two shapes: <code>rapp-qonto</code> (<code>ownership_repo: qonto-assistant</code>, one workload, thin package repo pointing back at the domain repo) and <code>rapp-postgres</code> (<code>ownership_repo: railiance-platform</code>, one workload with a <code>consumers:</code> list and a <code>consumer_contract</code>). The open question was whether NetKingdom's engines are one workload or several.</p>
<p><strong>Relational storage.</strong> The engines have diverged. <code>user-engine</code> already runs CloudNative PG (<code>kind: Cluster</code> in its own namespace) with NetworkPolicies and a <code>migrations/</code> surface. <code>tenant-engine</code> runs SQLite on a 1 Gi RWO PVC, chosen in TEN-WP-0004 for expedience. <code>railiance-platform</code> (S3) declares CloudNative PG the canonical database operator, and <code>rapp-postgres</code> packages it with a <code>database-per-consumer</code> boundary unit and OpenBao dynamic credentials. Separately, <code>rail-kubernetes</code>'s wave-1 contract explicitly states the rail must <strong>not</strong> assume "a generic persistent-storage contract" — so a per-workload PVC is unsupported by the rail regardless of which database is chosen.</p>
<p>TEN-WP-0005 was drafted against PostgreSQL and implemented against SQLite, because T05 must roll out against the runtime that exists. That workplan's <code>TenantStore</code> Protocol was kept as an explicit seam for this decision.</p>
</section>
<section id="decision"><h2>Decision</h2>
<h3>1. Separate <code>rapp-*</code> repos per engine</h3>
<p>Each deployed NetKingdom engine gets its own managed workload package repo:</p>
<pre>rapp-tenant-engine ownership_repo: tenant-engine
rapp-user-engine ownership_repo: user-engine</pre>
<p>Following <code>rapp-qonto</code>'s shape: the <code>rapp</code> owns Railiance packaging, rail compatibility, workload-specific smoke/health checks, rollout and rollback expectations, secret references, and dependency declarations. The engine repo retains domain ownership; <code>net-kingdom</code> retains canon.</p>
<p>This follows the one-workload rule rather than working around it. The engines are already independent on every axis a <code>rapp</code> declaration must state: separate namespaces, separate image digests, separate release cadence, and (until decision 2 lands) different storage. A single <code>rapp-netkingdom</code> would have to declare one <code>workload_identity</code>, one <code>rollout_contract</code>, and one <code>rollback_contract</code> across services that genuinely differ.</p>
<p>The decisive property is <strong>independent rollback</strong>: rolling back a bad <code>tenant-engine</code> revision must not force a <code>user-engine</code> revision change. A single rapp would make that either impossible or fictional.</p>
<p>Rollout ordering between the engines is a declared constraint between rapps, not a reason to merge them: <code>tenant-engine</code> before <code>user-engine</code>, following the dependency direction.</p>
<h3>2. <code>secrets-engine</code> is not packaged as a <code>rapp</code></h3>
<p><code>secrets-engine</code> has no deployed workload — no Containerfile, no Makefile, no Kubernetes manifests. It is a catalog/policy/workflow layer over OpenBao, whose packaging already belongs to <code>rapp-openbao</code> with custody and lane policy in <code>railiance-platform</code>.</p>
<p>A <code>rapp</code> wraps a workload; <code>secrets-engine</code> has none to wrap. Revisit only if it becomes a runtime service, at which point this decision reopens for that repo alone and not for the packaging model.</p>
<h3>3. CloudNative PG is the default relational platform for production</h3>
<p>Production NetKingdom services requiring relational storage use CloudNative PG via <code>rapp-postgres</code>, consuming the <code>database-per-consumer</code> boundary unit and the <code>openbao-dynamic-database-credential</code> lane, with tenant-keying per <code>business-app-service-contract_v0.1</code> section 1.3.</p>
<p>Per-workload SQLite-on-a-PVC is not a production pattern. It remains acceptable for local development and tests.</p>
<p><code>tenant-engine</code> migrates from SQLite to cnpg. Its <code>TenantStore</code> Protocol makes this a backend swap behind an existing seam rather than a rewrite; the lifecycle semantics proven in TEN-WP-0005 (atomic compare-and-swap, durable idempotency receipts, forward-only migration) are the conformance bar the PostgreSQL backend must meet, and its store-conformance suite is already parametrised across backends to enforce exactly that.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Two new <code>rapp-*</code> repos to create, each requiring a <code>declarations/rapp.yaml</code>, a binding in <code>reef-railiance/bindings/rapps.yaml</code>, and its own readiness evidence progression (<code>declared</code> → <code>installed</code> → <code>verified</code> → <code>production-approved</code>).</li><li>Per-binding evidence multiplies, but per-reef evidence does not — the <code>reef-production-readiness-contract</code> puts substrate, ingress, storage, network, and backup evidence on the reef, once. What multiplies is the critical-workload gate (threat model, negative authorization tests, rollback rules, residual-risk owner), which identity-plane services warrant individually. A shared NetKingdom threat model may be referenced by both bindings rather than duplicated.</li><li>Runtime manifests move out of <code>net-kingdom/sso-mfa/k8s/</code> into the respective <code>rapp</code> repos. This repo stops holding runtime YAML and returns to canon, standards, and ADRs.</li><li><code>tenant-engine</code> requires a data migration from SQLite to cnpg, including migration of existing tenants, grants, plan assignments, and idempotency receipts. TEN-WP-0005-T05's rollout plan is affected: it currently targets the SQLite runtime.</li><li>NetKingdom services become subject to the <code>railiance/app.toml</code> staged promotion contract (Stage 1 local → Stage 2 canary → Stage 3 production), including declared rollback commands and health endpoints. Digest-pinned images already satisfy <code>digest_policy = &quot;required&quot;</code>.</li><li>The reef must accept or mitigate its single-server and shared-control-plane risk for each NetKingdom binding, as it must for <code>rapp-qonto</code>. The reef name and a <code>high</code> criticality label are not evidence.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
<p><strong>One <code>rapp-netkingdom</code> for all associated repos.</strong> Rejected. It would reduce binding-evidence count and match the current coupled deployment (both engines' manifests share one tree; <code>flex-auth</code> runs per-consumer instances <code>flex-auth-tenant-engine</code> and <code>flex-auth-user-engine</code>). But it contradicts the one-workload rule in <code>repository-axes.md</code>, and would force a single rollback contract across independently versioned services. A rollback contract that depends on which service failed is not a contract. This alternative would be correct only if the engines were always promoted and rolled back as one atomic cutover — which their separate digests and release cadences contradict.</p>
<p><strong>Keep SQLite for <code>tenant-engine</code>, standardise later.</strong> Rejected. It leaves the two engines operationally dissimilar, which is the opposite of the intent, and <code>rail-kubernetes</code> does not support the per-workload persistent-storage contract the PVC depends on. Deferring also grows the migration: every tenant, grant, and receipt written between now and the cutover is data to move.</p>
<p><strong>A <code>rapp</code> per NetKingdom concern with a <code>consumers:</code> list, mirroring <code>rapp-postgres</code>.</strong> Rejected as a category error. <code>rapp-postgres</code>'s consumers are consumers <em>of one workload</em> (PostgreSQL); NetKingdom's engines are distinct workloads, not consumers of a shared one.</p>
</section>
<section id="follow-up"><h2>Follow-Up</h2>
<ul><li>Create <code>rapp-tenant-engine</code> and <code>rapp-user-engine</code>; move runtime manifests out of <code>net-kingdom/sso-mfa/k8s/</code>.</li><li>Add both bindings to <code>reef-railiance/bindings/rapps.yaml</code> at <code>declared</code>.</li><li>Add <code>railiance/app.toml</code> to <code>tenant-engine</code> and <code>user-engine</code>.</li><li>Open a <code>tenant-engine</code> workplan for the cnpg backend and data migration; reconcile with TEN-WP-0005-T05, whose rollout currently targets SQLite.</li><li>Confirm whether <code>secrets-engine</code> is intended to remain a non-deployed control layer. This ADR assumes it is.</li><li>Record the NetKingdom-wide threat model that both bindings will reference.</li></ul>
</section><footer><span>NK-ADR-0015 · 1 · accepted</span><span>net-kingdom · docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

211
docs/evidence/2026-10-11-served-publication-history/pages/RINFRA-ADR-0005.html Normal file
View file

@ -0,0 +1,211 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="f3e8bf3ab4b1dafa4d0b251b88ab2ef23a30c37b">
<meta name="policy-source-digest" content="4d93643d00d19b9d7c46843cd9be674c24e4cd613dc8e780c1684d97a6a9030a">
<title>k3s API is tunnel-only</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RINFRA-ADR-0005</span> <span class="stat">accepted · accepted-1</span> <span>railiance-infra</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>k3s API is tunnel-only</h1><p class="sub">Source: <code>railiance-infra · docs/adr/ADR-005-k3s-api-tunnel-only.md · f3e8bf3ab4b1dafa4d0b251b88ab2ef23a30c37b</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><p><strong>Status:</strong> Accepted <strong>Date:</strong> 2026-08-15 <strong>Deciders:</strong> implementation of RAIL-HO-WP-0009-T04 <strong>Workplans:</strong> <code>RAIL-HO-WP-0009</code></p>
<section id="context"><h2>Context</h2>
<p>Operator addresses on this network rotate with the ISP lease. A public UFW allowlist for <code>6443/tcp</code> is therefore a treadmill:</p>
<ul><li>miss a rotation and <code>kubectl</code> breaks mid-session</li><li>leave the old grant standing and it becomes a grant to a stranger</li><li>hand-add the new address and the declaration drifts again</li></ul>
<p>That cycle produced this workplan. The live allowlist drifted by hand <em>during the session that was fixing allowlist drift</em>, and again before the next session (<code>89.244.90.248</code> appeared undeclared). On 2026-08-15 the workstation egress address was <code>85.132.220.102</code> — already on the revoked list as a "historic" operator address.</p>
<p><code>docs/deploy-stack.md</code> already documents API access over the ops-bridge SSH tunnel for CoulombCore (<code>k3s-api-coulombcore</code>, local port 16443). The same tunnel already exists for Railiance01 (<code>k3s-api-railiance01</code>, local port 16444). SSH itself stays public, so the host remains recoverable.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>The public k3s API allowlist is <strong>empty</strong>. Operator and agent <code>kubectl</code> access uses the ops-bridge tunnels:</p>
<div class="scroll"><table><thead><tr><th>Cluster</th><th>Tunnel</th><th>Local port</th><th>Remote</th></tr></thead><tbody><tr><td>CoulombCore</td><td><code>k3s-api-coulombcore</code></td><td>16443</td><td>6443</td></tr><tr><td>Railiance01</td><td><code>k3s-api-railiance01</code></td><td>16444</td><td>6443</td></tr></tbody></table></div>
<pre>bridge up k3s-api-railiance01
# kubeconfig server: https://127.0.0.1:16444</pre>
<p>Trade: every operator <code>kubectl</code> action depends on ops-bridge. That is accepted. A rotating public allowlist is the worse dependency.</p>
<p>Emergency break-glass remains SSH: <code>ssh railiance01 -- sudo k3s kubectl …</code>. Do not re-open <code>6443/tcp</code> to Anywhere.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>k3s_api_allowed_sources</code> stays <code>[]</code>.</li><li>Former public grants live in <code>k3s_api_revoked_sources</code> so a firewall-tagged converge deletes them.</li><li>Goss asserts the 6443 allowlist size is exactly the declared length (zero) and that no revoked address remains.</li><li>Amending this ADR is required before adding any new public 6443 source.</li></ul>
</section><footer><span>RINFRA-ADR-0005 · accepted-1 · accepted</span><span>railiance-infra · docs/adr/ADR-005-k3s-api-tunnel-only.md · f3e8bf3ab4b1dafa4d0b251b88ab2ef23a30c37b</span></footer></main></div></div></html>

245
docs/evidence/2026-10-11-served-publication-history/pages/RISK-F-0001.html Normal file
View file

@ -0,0 +1,245 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="b2d1d0c526d5c9b5729b8353877bb9f29096667145f1498cfde73c9711206fda">
<title>flex-auth /v1/check authenticates no caller</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-F-0001</span> <span class="stat">fixed · published-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>flex-auth /v1/check authenticates no caller</h1><p class="sub">The estate&#x27;s authorization oracle authenticated no caller for as long as the endpoint existed. Found by reading, not by monitoring; fixed in two days.</p><p class="sub">Source: <code>risk-nexus · findings/RISK-F-0001-flex-auth-unauthenticated-check.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#what-is-true"><span class="n">·</span>What is true</a></li><li><a href="#how-it-was-found"><span class="n">·</span>How it was found</a></li><li><a href="#exposure-as-far-as-the-reporter-stated-it"><span class="n">·</span>Exposure, as far as the reporter stated it</a></li><li><a href="#what-makes-it-worse-than-a-single-service-s-defect"><span class="n">·</span>What makes it worse than a single service&#x27;s defect</a></li><li><a href="#owner-and-state"><span class="n">·</span>Owner and state</a></li><li><a href="#what-this-repo-is-asked-to-decide"><span class="n">·</span>What this repo is asked to decide</a></li><li><a href="#related-reported-at-the-same-time-and-not-yet-filed"><span class="n">·</span>Related, reported at the same time and not yet filed</a></li><li><a href="#register-ruling-2026-08-19"><span class="n">·</span>Register ruling — 2026-08-19</a></li><li><a href="#reviews"><span class="n">·</span>Reviews</a></li><li><a href="#re-grade-and-close-2026-08-19-same-day"><span class="n">·</span>Re-grade and close — 2026-08-19 (same day)</a></li><li><a href="#reviews"><span class="n">·</span>Reviews</a></li></ol></nav><main><section id="what-is-true"><h2>What is true</h2>
<p><code>POST /v1/check</code> and <code>POST /v1/batch_check</code> authenticate no caller. Any workload with network reach to the ClusterIP Service can assert any subject and any tenant and receive an authoritative <strong>allow</strong>.</p>
<p><code>flex-auth</code> is the estate's authorization oracle. Every service that delegates a decision to it is relying on an answer that anyone able to reach the pod can obtain for any identity they care to name.</p>
<p>Self-reported by <code>flex-auth</code> as <code>A0</code> on their own inbound surface, in their Tenancy Posture review. Their words: "flex-auth is the estate's authorization oracle and it trusts its callers completely."</p>
</section>
<section id="how-it-was-found"><h2>How it was found</h2>
<p>Not by a probe, an incident, or an alert. By <code>flex-auth</code> assessing themselves against the Tenancy Posture A ladder during a review they were asked to do — and their own note says they did not know they were carrying it.</p>
<p>That provenance matters for triage: nothing was watching for this, and nothing would have found it. It has presumably been true for as long as the endpoint has existed.</p>
</section>
<section id="exposure-as-far-as-the-reporter-stated-it"><h2>Exposure, as far as the reporter stated it</h2>
<ul><li>The Service is <code>ClusterIP</code>, so reach requires a workload inside the cluster.</li><li>No claim was made that network policy restricts which workloads can reach it, and this record does not assume one. <strong>If a default-deny NetworkPolicy fronts the service, that materially changes the exposure and should be verified rather than inferred</strong> — <code>flex-auth</code> did not state it either way, and I have not checked, because doing so would be reporting on a system I do not own.</li></ul>
</section>
<section id="what-makes-it-worse-than-a-single-service-s-defect"><h2>What makes it worse than a single service's defect</h2>
<p>A false allow from this endpoint is not confined to <code>flex-auth</code>. It is the answer other services act on. <code>tenant-engine</code> separately reports that its own mutations are authorized by <code>flex-auth</code> and that direct authority over its rows would mean "privilege escalation across NetKingdom rather than data tampering confined to one store". The same reasoning applies to a forged allow.</p>
</section>
<section id="owner-and-state"><h2>Owner and state</h2>
<p><code>flex-auth</code> owns the fix and has tracked it as <code>FLEX-WP-0015-T02</code>, to ship through the staged-promotion path rather than a direct apply. They classify it as the only urgent item of their five follow-ups. Nothing is asked of them by this record beyond what they have already committed to.</p>
</section>
<section id="what-this-repo-is-asked-to-decide"><h2>What this repo is asked to decide</h2>
<ol><li><strong>Severity.</strong> Not the reporter's to set.</li><li><strong>Disclosure.</strong> Build mode is currently public-by-default, and this is precisely the class of finding where that stops being obviously right — a live authorization bypass in the service every other service trusts. The controlled-disclosure scheme this repo anticipates does not exist yet, so the choice today is publish or hold, with no mechanism between them.</li><li><strong>Escalation.</strong> Whether this reaches the operator personally. The candidate triggers in INTENT include "anything exposing real tenant data" — this exposes the decision that governs access to it, which may or may not be the same thing, and that judgement is this repo's.</li></ol>
</section>
<section id="related-reported-at-the-same-time-and-not-yet-filed"><h2>Related, reported at the same time and not yet filed</h2>
<p>Three further defects surfaced from the same review round. They are recorded here so they are visible, not filed as findings, because filing them was not asked for:</p>
<ul><li><code>tenant-engine</code> — <code>events()</code> returns the entire event log unfiltered. A live cross-tenant read at <code>E2</code>.</li><li><code>audit-core</code> — read path applies no tenant filter; a credential with <code>may_read</code> can read any tenant's events. Bounded by deployment (<code>may_read: false</code> on the production sender) and not by code. Tracked <code>AUDIT-WP-0008-T04</code>.</li><li><code>apps-pg</code> (<code>railiance-platform</code>) — no backup configured at all: no <code>barmanObjectStore</code>, no retention policy, <code>BestEffort</code> QoS. <code>R0</code> there means no recovery, not merely no erasure policy.</li></ul>
<p>All four were found the same way, by repos reading their own code against a ladder, within a day of each other. That is a fact about the estate's observability worth carrying into triage: <strong>four live defects, none found by monitoring.</strong></p>
</section>
<section id="register-ruling-2026-08-19"><h2>Register ruling — 2026-08-19</h2>
<p><code>critical</code> (<code>I4</code> × <code>L3</code>, no fidelity modifier), embargoed until <code>FLEX-WP-0015-T02</code> ships, <strong>escalated</strong> to the operator on trigger 1.</p>
<p>The question this finding put — whether governing access to tenant data counts as exposing it — is answered <strong>yes</strong>. An authorization oracle that can be forged is not one step removed from the data; it is the step.</p>
<p>Impact is <code>I4</code> because a forged allow does not stay here: it is the answer other services act on, and <code>tenant-engine</code> has stated what direct authority over its rows would mean. Likelihood is <code>L3</code> — the normal working set, inside the cluster, no additional step — and the register follows the reporter in neither assuming a default-deny NetworkPolicy nor assuming its absence.</p>
<p>No fidelity modifier: this endpoint answers honestly about a caller it never checked. The false-record hazard lives in <code>RISK-F-0002</code>'s constraint, where a consumer of this endpoint would begin signing records asserting an authorization that was never made. <strong>That constraint binds this finding's remediation</strong>: <code>ops-warden</code>'s <code>policy.enabled</code> must not be turned on until <code>/v1/check</code> authenticates its callers, and the ordering is</p>
<pre>flex-auth warn-only -&gt; ops-warden gate presents its SA token -&gt; logs clean
-&gt; flex-auth fail-closed -&gt; ops-warden policy.enabled: true</pre>
<p>Nothing further is asked of <code>flex-auth</code> beyond what they have committed to, except one fact only they can supply: <strong>is there a default-deny NetworkPolicy in front of the Service?</strong> It is the single fact that would most change this grade, and it is the first question at review.</p>
<p>Reasoning: <code>docs/rulings/2026-08-19-first-grading.md</code>.</p>
</section>
<section id="reviews"><h2>Reviews</h2>
<ul><li><strong>2026-08-19</strong> — graded. Next review 2026-08-26 (<code>critical</code> → 7 days). Open at review: the NetworkPolicy question; whether <code>FLEX-WP-0015-T02</code> has moved; whether the embargo still holds.</li></ul>
</section>
<section id="re-grade-and-close-2026-08-19-same-day"><h2>Re-grade and close — 2026-08-19 (same day)</h2>
<p><strong>Corrected from <code>critical</code> to <code>high</code>, and closed as <code>fixed</code>.</strong> Both changes come from messages that were already in this repo's inbox when the first grade was set. The register graded before it read them.</p>
<p><strong>The exposure was narrower than graded.</strong> <code>flex-auth</code> answered the NetworkPolicy question on 2026-08-18: both production Deployments ship a NetworkPolicy in the same manifest, and it is <em>narrower</em> than default-deny — ingress restricted to one <code>namespaceSelector</code> plus one <code>podSelector</code> on port 8080, egress empty. In force since before the period the <code>A0</code> describes. So the reachable set was never "any pod in the cluster"; it was the single paired workload per Deployment.</p>
<p>That is <code>L2</code>, not <code>L3</code>. Impact stays <code>I4</code> — what a forged allow reaches does not change — so the grade is <code>high</code>. <code>flex-auth</code> also corrected their own earlier phrasing to <code>ops-warden</code> in the same message, unprompted, and that correction is why the fact reached this register at all.</p>
<p>Three caveats <code>flex-auth</code> asked to be recorded rather than taken from them, and they are why the grade did not fall further: label selectors are network position, not identity; the policy could not bind the asserted <code>resource.system</code>, which is what made cross-system impersonation possible; and enforcement depends on a CNI they could not verify from a cluster where <code>kubectl</code> returned <code>Unauthorized</code>. They said so rather than letting a manifest stand in for a probe.</p>
<p><strong>It is fixed.</strong> On 2026-08-19 <code>flex-auth</code> reported both production Deployments enforcing ADR-0004 TokenReview, with live unbound-request probes returning 401 rather than a decision, on both the <code>user-engine</code> and <code>tenant-engine</code> pins. <code>FLEX-WP-0015</code> is finished and <code>tenancy.current.A</code> is 2. That is a probe against the running system, which is the standard <code>docs/method/review.md</code> sets for closing: something concrete read, not something been told.</p>
<p><strong>Disclosure flips to <code>public</code>.</strong> The embargo condition was "FLEX-WP-0015-T02 ships to production" and it is met. Handover to <code>policy-nexus</code> is the next step and is not done yet.</p>
<p><strong>The escalation is withdrawn without being sent.</strong> It was <code>pending-operator</code> for roughly four hours, and the fix landed first. Withdrawing it is correct — escalating a fixed defect makes the operator the queue for history — but the register does not get to be pleased about it. The escalation would have been sent on facts that were already stale, and only luck put the fix on the same day.</p>
<p><strong>What this cost, recorded because it is the register's own defect.</strong> The NetworkPolicy answer arrived 2026-08-18. The fix notice arrived 2026-08-19 at 12:35. The first grading ran at 21:14 the same day, on neither. Reading the inbox is now step 0 of grading and question 0 of every review — see <code>docs/method/review.md</code> — and this finding is the case that bought it.</p>
</section>
<section id="reviews"><h2>Reviews</h2>
<ul><li><strong>2026-08-19</strong> — re-graded <code>high</code>, closed <code>fixed</code>, disclosure <code>public</code>, escalation withdrawn. Remaining: handover to <code>policy-nexus</code>; the CNI enforcement question is <code>flex-auth</code>'s and no longer this finding's.</li><li><strong>2026-08-20</strong> — not clean: Publication handover requested; publication front-matter applied and the wait on policy-nexus typed. Cadence instant → instant; checked again immediately.</li></ul>
</section><footer><span>RISK-F-0001 · published-1 · fixed</span><span>risk-nexus · findings/RISK-F-0001-flex-auth-unauthenticated-check.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

274
docs/evidence/2026-10-11-served-publication-history/pages/RISK-F-0008.html Normal file
View file

@ -0,0 +1,274 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="8bf47414a9f958afb57649f087a2617f91a8f2aeaa4f34d04d8fb3a0f453e840">
<title>The legal basis for retaining audit facts against an erasure request has been assumed, never established</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-F-0008</span> <span class="stat">accepted · published-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>The legal basis for retaining audit facts against an erasure request has been assumed, never established</h1><p class="sub">The estate retains personal data in audit records on grounds nobody had established. Published as a question, because it is one.</p><p class="sub">Source: <code>risk-nexus · findings/RISK-F-0008-audit-retention-legal-basis-assumed.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#what-is-true"><span class="n">·</span>What is true</a></li><li><a href="#why-this-repo-owns-it"><span class="n">·</span>Why this repo owns it</a></li><li><a href="#the-three-questions-as-asked"><span class="n">·</span>The three questions, as asked</a></li><li><a href="#register-ruling-2026-08-19"><span class="n">·</span>Register ruling — 2026-08-19</a></li><li><a href="#how-it-got-here"><span class="n">·</span>How it got here</a></li><li><a href="#reviews"><span class="n">·</span>Reviews</a></li><li><a href="#suggested-disposition-2026-08-20-proposed-by-risk-nexus"><span class="n">·</span>Suggested disposition — 2026-08-20, proposed by risk-nexus</a></li><li><a href="#operator-decision-2026-08-20-minimise-the-identity-keep-the-accountability"><span class="n">·</span>Operator decision — 2026-08-20: minimise the identity, keep the accountability</a></li><li><a href="#the-determination-exists-2026-08-20"><span class="n">·</span>The determination exists — 2026-08-20</a></li><li><a href="#operator-decision-2026-08-20-no-external-determination-and-a-policy-set-instead"><span class="n">·</span>Operator decision — 2026-08-20: no external determination, and a policy set instead</a></li></ol></nav><main><section id="what-is-true"><h2>What is true</h2>
<p><code>audit-core</code> holds audit evidence across tenants, targets <code>R2</code> on the Tenancy Posture retention ladder, and has declared <code>R4</code> — verified erasure — unreachable by design. The technical reasoning is sound and documented (<code>audit-core/docs/erasure-and-audit.md</code>, framework Decision 4.5.3): crypto-shredding would destroy the evidence the service exists to hold, and their integrity chain commits to a SHA-256 of the cleartext record, which survives key destruction as a confirmation oracle against low-entropy audit rows. Destroying a key does not erase content a surviving commitment can still be tested against.</p>
<p>The consequence is that if an Article 17 request arrives naming a data subject in the audit trail, <code>audit-core</code> has no mechanism. The answer would rest on audit evidence being exempt — legal obligation, or legitimate interest in fraud and security investigation.</p>
<p><strong>Those grounds are ordinary. Nobody in this estate has actually reached them.</strong> <code>audit-core</code> routed the question here on 2026-08-18 rather than absorbing it, saying plainly that they are not competent to answer it and that they have been assuming it. §19.11 of the framework says the same in its own words: the legal basis for retaining audit facts remains a risk/legal question outside the framework.</p>
</section>
<section id="why-this-repo-owns-it"><h2>Why this repo owns it</h2>
<p>This is the first finding where <code>fix_owner</code> is <code>risk-nexus</code>.</p>
<p><code>INTENT.md</code> moved regulatory intake here from <code>policy-nexus</code> on 2026-08-17, precisely because deciding what a rule demands of us is a judgement about risk rather than an act of publishing. <code>audit-core</code> routed it by both available routes and asked for an owner rather than an opinion. Refusing it would be this repo declining its own remit.</p>
<p>What this repo owns is the <strong>record</strong>: what the source says, when, and what therefore is or is not established. It does not own legal advice — <code>INTENT.md</code> is explicit — and it does not own the redesign. If the basis does not hold, <code>audit-core</code> owns encrypt-then-hash at accept time, and that is not retrofittable onto events already accepted.</p>
</section>
<section id="the-three-questions-as-asked"><h2>The three questions, as asked</h2>
<ol><li>On what basis does the estate retain personal data inside audit records against an erasure request, and does that basis hold for the categories <code>audit-core</code> stores?</li><li>Does it hold across the full 30-day recoverable window and beyond, given that at <code>P1</code> the real erasure horizon is the maximum across every co-resident on <code>platform-pg</code>, not the value <code>audit-core</code> declares?</li><li>If it does not hold, <code>R4</code> is urgent rather than theoretical, and the answer is a substantial redesign with a long lead time.</li></ol>
</section>
<section id="register-ruling-2026-08-19"><h2>Register ruling — 2026-08-19</h2>
<p><code>medium</code> today (<code>I3</code> × <code>L2</code>), <code>high</code> at production, <code>public</code>, <strong>escalated on trigger 2</strong>.</p>
<p><code>I3</code>: an unmet retention obligation in the audit store crosses from a technical question to an obligation with an outside counterparty, and the remediation is a non-retrofittable redesign rather than a patch. <code>L2</code>: no request has arrived and the estate holds no real data subject's records yet, but the trigger is somebody else's to pull and needs no foothold here.</p>
<p><code>production_rescore: true</code>. The likelihood of an Article 17 request is a function of having real users; that is exactly what production means.</p>
<p><strong>Escalation, trigger 2</strong> — "creates or reveals an obligation with an outside counterparty". It reveals one. The estate cannot decide unilaterally that this obligation is small, and the operator is the only party who can commission an answer that is more than an assumption. The ask is narrow: authorise someone to establish the basis, or record that the estate knowingly runs on the assumption and for how long.</p>
<p><strong>Disclosure <code>public</code>.</strong> Nothing here shortens a path to a defect: it is a question about a legal basis, published as a question. <code>audit-core</code>'s technical reasoning is already written down and worth reading.</p>
</section>
<section id="how-it-got-here"><h2>How it got here</h2>
<p>Ruled a note on 2026-08-19 (<code>RISK-N-0002</code>) on the reasoning that no obligation exists yet. That ruling was made without reading <code>audit-core</code>'s message, which had been in this repo's inbox since 2026-08-18 and asks specifically for an owner. The note was wrong on the second floor test: recording this <em>does</em> change a decision, because the redesign it might force cannot be retrofitted and therefore has to be decided early or not at all.</p>
<p><code>RISK-N-0002</code> is superseded by this record.</p>
</section>
<section id="reviews"><h2>Reviews</h2>
<ul><li><strong>2026-08-19</strong> — promoted from note, graded, escalated. Open at review: has the basis been established or the assumption recorded; has anything changed about what categories <code>audit-core</code> stores.</li></ul>
</section>
<section id="suggested-disposition-2026-08-20-proposed-by-risk-nexus"><h2>Suggested disposition — 2026-08-20, proposed by risk-nexus</h2>
<p>Offered because this repo owns the finding and the operator asked for a direction. It is not legal advice, and this repo cannot make it into one: what follows is a <em>route to an answer</em> and a hedge against the answer being no.</p>
<h3>The reframe: the expensive thing is not the legal question</h3>
<p><code>audit-core</code> asks whether the exemption holds. That question is cheap to answer badly and expensive to answer properly, and the temptation is to schedule the proper version and wait.</p>
<p>But the cost of a "no" is not fixed — it grows daily. The remedy they name, encrypt-then-hash at accept time, cannot be retrofitted onto events already accepted. <strong>Every day the estate accepts events under the current scheme, the un-erasable set grows by one day.</strong> So the decision that actually needs taking now is not "is it exempt" but "do we keep manufacturing records we could never erase while we find out".</p>
<p>That splits the finding into two decisions with very different prices.</p>
<h3>1. Establish the basis internally, now, for the cost of an afternoon</h3>
<p>Not a legal opinion — a <strong>written determination</strong> that says which ground is being relied on, for which category of data, and for how long. Today the estate has no such document; that is the whole finding.</p>
<p>The shape it should take, per category of personal data in the audit trail:</p>
<div class="scroll"><table><thead><tr><th>Category</th><th>Likely ground</th><th>The part that is actually arguable</th></tr></thead><tbody><tr><td>Operator and agent identifiers</td><td>Art 6(1)(f) legitimate interest in security, with Recital 49 squarely on point</td><td>little — this is the ordinary case</td></tr><tr><td>Counterparty or end-user identifiers in event payloads</td><td>Art 17(3)(e), defence of legal claims; Art 6(1)(f)</td><td><strong>duration</strong>, not existence</td></tr><tr><td>Commercial records that happen to pass through audit</td><td>Art 17(3)(b) plus German §257 HGB / §147 AO retention</td><td>scope — retention duties cover books and invoices, not application logs generally</td></tr></tbody></table></div>
<p>Where such determinations usually fail is <strong>not</strong> the ground. It is the retention period: a blanket "we keep audit forever under legitimate interest" is much weaker than "we keep these fields for N months because X". That lands precisely on <code>audit-core</code>'s question 2 — the real horizon being the maximum across every co-resident on <code>platform-pg</code> rather than the declared value.</p>
<p>Recording the determination converts an assumption into a position that can be argued with. That is what this register exists to produce, and it does not require a lawyer to write down.</p>
<h3>2. Stop the un-erasable set from growing — a cheaper hedge than the redesign</h3>
<p><code>audit-core</code>'s stated obstacle is precise and correct: their chain commits to <code>SHA-256(cleartext)</code>, audit records are low-entropy, so the retained hash survives key destruction as a confirmation oracle. Guess, hash, compare.</p>
<p>The oracle exists because the commitment is over cleartext with no secret in it. A <strong>keyed commitment</strong> removes it: replace the digest with an HMAC (or a hash over record plus a high-entropy per-subject salt) where the key or salt lives outside the audit store and is destroyable per subject.</p>
<p>What that buys, and why it is cheaper than the redesign they costed:</p>
<ul><li>Destroying the per-subject key makes the commitment untestable — no guess can be confirmed. That is crypto-shredding restored, which their analysis correctly found unavailable under a plain hash.</li><li>The integrity chain still verifies. It chains over commitment values, and those persist after key destruction; what is lost is the ability to re-derive a commitment from cleartext, which is exactly what erasure means.</li><li>It is a change at accept time only. No re-processing of stored events, no new storage layer, no change to the read path.</li></ul>
<p>This is a suggestion to <code>audit-core</code>, not an instruction, and they own whether it is sound — they know their chain and this repo does not. The claim worth testing with them is narrow: <strong>does a keyed commitment restore erasability without breaking chain verification?</strong> If yes, the expensive redesign becomes a contingency rather than a plan, and the daily accrual stops.</p>
<h3>3. Buy the real answer only when something triggers it</h3>
<p>An external determination costs money and needs a real question. Propose three triggers, any of which fires it:</p>
<ul><li>the estate first holds a real person's data;</li><li>a counterparty contract requires a stated erasure position;</li><li>an actual Art 17 request arrives.</li></ul>
<p>Until one fires, the internal determination plus the hedge is a proportionate posture, and <code>severity_at_production: high</code> plus <code>production_rescore: true</code> already guarantee this is re-read before production completes.</p>
<h3>What this repo would record if the operator agrees</h3>
<p><code>status: accepted</code> with the determination attached, <code>escalation</code> answered as <code>rule</code>, and the review kept at 90 days. The finding stays open and visible until the determination exists — an accepted risk with no written basis is the same assumption it started as, wearing a different word.</p>
<h3>Also worth saying, because it is the cheapest fix of all</h3>
<p>Every field of personal data that never enters the audit trail is a field with no erasure question. Where an opaque subject identifier would carry the same evidentiary weight as a name or an address, the identifier is strictly better, and that is a <code>audit-core</code> design choice available today at no legal cost.</p>
</section>
<section id="operator-decision-2026-08-20-minimise-the-identity-keep-the-accountability"><h2>Operator decision — 2026-08-20: minimise the identity, keep the accountability</h2>
<p>The custodian ruled on what goes into an audit record, which is the half of this finding that shrinks the question rather than answering it:</p>
<ol><li><strong>Opaque subject identifiers are preferred.</strong> Where an opaque id carries the same evidentiary weight as a name or an address, it is the id that goes in.</li><li><strong>Agent identifiers where possible.</strong> Agents act; attribute to the acting agent identity rather than to a person behind it.</li><li><strong>Operator credentials only where necessary.</strong> Not as a convenience, not as a default — where the record genuinely requires the operator.</li><li><strong>Policy decisions are tracked to the responsible party.</strong> Accountability is preserved by linking a decision to who is answerable for it, not by retaining personal data in the record itself.</li><li><strong>Zone guarantees may raise the floor.</strong> If a zone establishes additional privacy, pseudonymity or anonymity guarantees, those apply — the current level is not a permanent ceiling. That work is <code>zone-engine</code>'s (<code>ZONE-WP-0001</code>), and this finding should be re-read when a zone lands one.</li></ol>
<p><strong>Why this is more than a preference.</strong> Personal data that never enters the audit trail has no erasure question, no exemption to establish, and nothing to argue about with a regulator. Points 1-3 shrink the population the legal basis has to cover; point 4 is what stops that shrinking from costing accountability, which is the usual objection to minimising an audit log.</p>
<p>It also changes the shape of the accrual problem. The un-erasable set still grows daily, but each day's records now carry less that would need erasing — so the cost of a "no" answer falls with every event accepted under the new rule rather than rising.</p>
<p><strong>What is still outstanding</strong>, and stays escalated:</p>
<ul><li>The <strong>written determination</strong> of the retention basis — which ground, for which category, for how long. <code>risk-nexus</code> owns writing it; it needs no further authorisation and is scheduled into the next workplan.</li><li>The <strong>trigger list</strong> for buying an external answer (first real person's data, first counterparty contract requiring a stated position, first Art 17 request). Proposed, not yet ruled on.</li></ul>
<p>The escalation is therefore <code>partially-answered</code>, not closed. <code>make check</code> will keep listing it.</p>
<p><strong>Routed to <code>audit-core</code> on 2026-08-20</strong>, together with the keyed-commitment question — which remains theirs to judge, because they know their chain.</p>
</section>
<section id="the-determination-exists-2026-08-20"><h2>The determination exists — 2026-08-20</h2>
<p><code>docs/regulatory/RISK-REG-0001</code> (<code>audit-retention-basis.md</code>). The estate now has a written position rather than an assumption, which was this finding's substance.</p>
<p>What it says, in short: Art 6(1)(f) with Art 32 for operator and agent audit records; Art 17(3)(e) for records evidencing a counterparty transaction; Art 17(3)(b) only where a commercial or tax retention duty independently applies, and not extended to application logs generally.</p>
<p><strong>The weak part is duration, not existence</strong>, and the record says so rather than sounding confident. A position of the form "we keep audit forever because it is audit" is the one that fails; a period per category is what holds. The estate does not have one yet, and the reason is <code>audit-core</code>'s own question 2 — at <code>P1</code> the real horizon is the maximum across every co-resident on <code>platform-pg</code>, not the declared value. <strong>That infrastructure fact is the most likely point of failure in the whole position.</strong></p>
<p>The operator's minimisation ruling improves this materially: it shrinks the category whose retention is hardest to justify, leaving mostly the row where the ground is strong. A weak argument avoided by holding less data beats a strong one relied upon.</p>
<p>The finding stays open. What remains is a retention period per category, which waits on the co-residency horizon, and the trigger list for buying an external determination. The record is reviewed every 90 days with this finding, or immediately on any trigger.</p>
<ul><li><strong>2026-08-20</strong> — not clean: The determination now exists: RISK-REG-0001 states the grounds per category and names duration as the weak point. Cadence instant → instant; checked again immediately.</li></ul>
</section>
<section id="operator-decision-2026-08-20-no-external-determination-and-a-policy-set-instead"><h2>Operator decision — 2026-08-20: no external determination, and a policy set instead</h2>
<p>Ruled: <strong>the estate will not buy an external determination while it is building.</strong> The internal determination (<code>RISK-REG-0001</code>) stands as the recorded position, and the finding moves to <code>accepted</code> — deliberately carried, with a named accepter and a condition that ends it.</p>
<p>That is not the same as the trigger list being rejected. The triggers survive as what ends the acceptance: a real person's data, or a counterparty requiring a stated position. What was declined is spending money in advance of either.</p>
<p><strong>The compensating control is the thing that makes this defensible.</strong> Rather than defer the question, the operator directed that the estate <strong>define and keep a set of legal policies for reuse</strong>, because future work contexts will need specific positions in place and should retrieve them rather than research them.</p>
<p><code>docs/regulatory/policies/</code> now catalogues thirteen, keyed by activation condition. Two of them turned out to be <strong>already active and unowned</strong>: commercial and tax retention (<code>RISK-POL-0009</code>), and the e-invoicing receiving obligation (<code>RISK-POL-0012</code>), live since 2025 with no system in the estate named as the receiving point.</p>
<p>Finding an unnoticed live obligation in the first hour of building the catalogue is the argument for having built it. The reason this repo exists is that regulation was previously "consulted and discarded"; a set that answers "what applies if we do X" before anyone does X is the opposite of that.</p>
<p><strong>Still open under the acceptance</strong>, and unchanged by this ruling: <code>audit-core</code> on whether a keyed commitment restores erasability, and the <code>platform-pg</code> co-residency horizon that decides whether the stated retention periods are achievable. An accepted risk still gets checked.</p>
<ul><li><strong>2026-08-20</strong> — not clean: Trigger list ruled: no external determination in build mode; accepted with the legal policy set as the compensating control. Cadence instant → instant; checked again immediately.</li></ul>
</section><footer><span>RISK-F-0008 · published-1 · accepted</span><span>risk-nexus · findings/RISK-F-0008-audit-retention-legal-basis-assumed.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

238
docs/evidence/2026-10-11-served-publication-history/pages/RISK-METHOD-DEPENDENCIES.html Normal file
View file

@ -0,0 +1,238 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="a5e7b42043b0bb366add9bbc5f606e134ef5b0454532480203d5d87099296240">
<title>Waiting</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-METHOD-DEPENDENCIES</span> <span class="stat">adopted · adopted-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>Waiting</h1><p class="sub">Source: <code>risk-nexus · docs/method/dependencies.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#the-principle"><span class="n">·</span>The principle</a></li><li><a href="#the-four-rules"><span class="n">·</span>The four rules</a></li><li><a href="#what-this-does-not-solve"><span class="n">·</span>What this does not solve</a></li><li><a href="#waits-outlive-statuses"><span class="n">·</span>Waits outlive statuses</a></li><li><a href="#a-wait-is-not-a-findings-only-idea"><span class="n">·</span>A wait is not a findings-only idea</a></li><li><a href="#where-the-waits-are-visible"><span class="n">·</span>Where the waits are visible</a></li></ol></nav><main><p>By 2026-08-20 the register had accumulated nine waits in four days, one of them four hops deep: <code>RISK-F-0003</code>'s embargo waited on <code>RISK-F-0009</code>, which waited on <code>railiance-platform</code> fixing a deny set, which waited on someone verifying it against live OpenBao, which waited on a credential nobody has.</p>
<p>Nothing in that chain is anyone's fault, and every link was individually reasonable. That is exactly why it needs a rule: deep dependencies are not built deliberately, they accrete one sensible step at a time.</p>
<section id="the-principle"><h2>The principle</h2>
<p><strong>The register never waits to decide. It decides, and revises when told.</strong></p>
<p>A wait is a <em>refinement</em> pending, not a decision pending. If the register cannot act until someone answers, the register has made that person's silence into its own paralysis — and <code>INTENT.md</code> is explicit that a register nobody acts on is worse than none.</p>
</section>
<section id="the-four-rules"><h2>The four rules</h2>
<h3>1. Every wait is typed</h3>
<p>No record may say "waiting on X". A wait carries six things:</p>
<pre>waiting_on:
- who: tenant-engine
what: &quot;confirm or correct the unfiltered events() read; open fix tracking&quot;
since: &quot;2026-08-19&quot;
would_change: &quot;grade rises if the log carries payload rather than metadata&quot;
default: &quot;grade stands as recorded; absent fix tracking noted as a stall&quot;
default_at: &quot;2026-09-03&quot;</pre>
<p><code>would_change</code> is the discipline. If nobody can say what the answer would change, there is nothing being waited for, and the wait should be deleted rather than carried.</p>
<h3>2. Depth one</h3>
<p><strong>A record may wait on at most one other record, and never on a record that is itself waiting.</strong></p>
<p>When the chain would go deeper, the far end is cut: the record takes its own default and says which unresolved thing it declined to wait for. Two hops is the point at which nobody can see the whole line any more, and a wait nobody can see is indistinguishable from a thing that was dropped.</p>
<p>Applied 2026-08-20: <code>RISK-F-0009</code>'s embargo condition was "verified against live OpenBao", which no one in the estate can currently do. It now lifts on <strong><code>railiance-platform</code> reporting the coverage</strong>, with live verification recorded as a refinement rather than a condition. That cut the <code>RISK-F-0003</code> chain from four hops to two.</p>
<h3>3. Defaults are dates, and defaults are pessimistic</h3>
<p>Every wait resolves on a date whether or not anyone answers. The default is <strong>the reading the stated facts already support</strong> — never a hold, never a downgrade earned by silence.</p>
<p>This is what removes the incentive to wait. Silence does not buy an owner a softer grade or a quieter register; it costs them the grade the evidence supports, which is usually the one they would want corrected. Answering is how a grade improves, and that is the right shape for the incentive.</p>
<p>The register says so in advance, to the owner, in writing. A default nobody was warned about is an ambush, not a rule.</p>
<h3>4. A condition naming somebody else's action carries a date beside it</h3>
<p>"Embargo lifts when X ships" is a dependency with no end. "Lifts when X ships, or is re-decided on 2026-09-20" terminates.</p>
<p>Re-decided is not the same as lifted — the re-decision may extend the hold with a fresh reason. What it may not do is extend by default, which is how holds quietly become permanent.</p>
</section>
<section id="what-this-does-not-solve"><h2>What this does not solve</h2>
<p>Some dependencies are real and cannot be defaulted away. Nobody can verify an OpenBao policy without a token, and no rule here conjures one.</p>
<p>What the rules do is stop that from propagating: the register grades on what is stated, records what it could not verify, and keeps its own position independent of the blockage. <code>docs/method/verification.md</code> bounds what this repo can establish itself, and every grade resting on a document rather than a probe says so on its face.</p>
</section>
<section id="waits-outlive-statuses"><h2>Waits outlive statuses</h2>
<p>A finding that is <code>fixed</code> can still owe something. <code>RISK-F-0001</code> was closed on 2026-08-19 and is still waiting on <code>policy-nexus</code> for the publication entry that turns <code>disclosure: public</code> into an actual address.</p>
<p>So the waiting list is built from <strong>every</strong> finding, not from the watched ones. A closed record with an open obligation is precisely the thing that goes quiet, because nothing is prompting anyone to look at it any more.</p>
</section>
<section id="a-wait-is-not-a-findings-only-idea"><h2>A wait is not a findings-only idea</h2>
<p>Adopting a rule is nobody's finding. Registering a canon kind is nobody's finding. Publishing a document is nobody's finding. All three are obligations someone owes, and each one that lived outside the mechanism was invisible to it.</p>
<p>So waits attach to <strong>any</strong> record this repo keeps — findings, regulatory records, workplans — and <code>make check</code> reports them together. <code>RISK-WP-0001</code> carries two: the escalation rule that is producing decisions while still <code>status: proposed</code>, and the canon question about what kind of thing a finding is.</p>
<p>The first of those has the most uncomfortable default in the register, and it points inward: <strong>if the rule is not adopted by 2026-09-17, it is recorded as de facto in force but unratified, and every escalation sent under it says so on its face.</strong> That is worse than either adopting or rejecting it, which is the point — a draft that quietly governs is the thing this register was built to notice.</p>
</section>
<section id="where-the-waits-are-visible"><h2>Where the waits are visible</h2>
<p><code>make check</code> reports every open wait with its age, its owner and its default date, flags any default that has come due, and flags any wait that points at a record which is itself waiting — a depth-two violation, caught by tooling rather than by someone noticing.</p>
</section><footer><span>RISK-METHOD-DEPENDENCIES · adopted-1 · adopted</span><span>risk-nexus · docs/method/dependencies.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

232
docs/evidence/2026-10-11-served-publication-history/pages/RISK-METHOD-DISCLOSURE.html Normal file
View file

@ -0,0 +1,232 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="bd825a87736c8fb019d4224c3ef4fe3882b8f3028035225b4b8ff8cad62fdb81">
<title>Disclosure</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-METHOD-DISCLOSURE</span> <span class="stat">adopted · adopted-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>Disclosure</h1><p class="sub">Source: <code>risk-nexus · docs/method/disclosure.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#what-disclosure-is-not"><span class="n">·</span>What disclosure is not</a></li><li><a href="#the-states"><span class="n">·</span>The states</a></li><li><a href="#embargo-is-a-record-not-a-silence"><span class="n">·</span>Embargo is a record, not a silence</a></li><li><a href="#the-build-mode-deferral-re-taken"><span class="n">·</span>The build-mode deferral, re-taken</a></li><li><a href="#test-for-shortens-the-path"><span class="n">·</span>Test for &quot;shortens the path&quot;</a></li><li><a href="#publication-happens-elsewhere"><span class="n">·</span>Publication happens elsewhere</a></li><li><a href="#the-standing-route-when-an-embargo-lifts"><span class="n">·</span>The standing route, when an embargo lifts</a></li></ol></nav><main><p>Whether and when a finding is published. <code>policy-nexus</code> is the surface; this document decides what it is handed.</p>
<section id="what-disclosure-is-not"><h2>What disclosure is not</h2>
<p><strong>A finding file in this repo is not a publication.</strong> This repo is a private checkout on a private forge. Holding a finding means not routing it to <code>policy-nexus</code>; it does not mean hiding it from the estate, from the owning repo, or from the operator. Every state below is fully visible internally.</p>
</section>
<section id="the-states"><h2>The states</h2>
<div class="scroll"><table><thead><tr><th>State</th><th>Meaning</th><th>Entry condition</th></tr></thead><tbody><tr><td><code>public</code></td><td>Published through <code>policy-nexus</code> now.</td><td>The finding is fixed, or reading it gives no one an advantage they do not already have.</td></tr><tr><td><code>embargoed</code></td><td>Held, with a stated condition that lifts it.</td><td>Live, unfixed, and the text would help someone reach the defect faster than they could without it.</td></tr><tr><td><code>restricted</code></td><td>Held with no expected lift.</td><td>Publication would remain harmful after the fix — third-party material, a named person, or a credential-shaped detail that survives remediation.</td></tr></tbody></table></div>
<p>There is no fourth state and no <code>unset</code> after grading. A finding whose disclosure has not been decided is an ungraded finding.</p>
</section>
<section id="embargo-is-a-record-not-a-silence"><h2>Embargo is a record, not a silence</h2>
<p><code>INTENT.md</code> requires the record that a delay was deliberate rather than a document quietly going missing. An <code>embargoed</code> finding therefore carries:</p>
<pre>disclosure: embargoed
embargo_condition: &quot;FLEX-WP-0015-T02 ships to production&quot;
embargo_since: &quot;2026-08-19&quot;
embargo_review: &quot;2026-08-26&quot;</pre>
<p><code>embargo_condition</code> must be an event someone can observe, not a mood. "Until it is safer" is not a condition. <code>embargo_review</code> follows the finding's severity interval from <code>docs/method/review.md</code>; when it passes, the embargo is re-decided, not extended by default.</p>
<p>An embargo that has outlived two consecutive reviews without its condition moving is itself a finding — the remediation has stalled, and the hold is now doing the work the fix was supposed to do.</p>
</section>
<section id="the-build-mode-deferral-re-taken"><h2>The build-mode deferral, re-taken</h2>
<p><code>INTENT.md</code> recorded controlled disclosure as deferred to production, reasoning that build mode has no users to expose. <code>RISK-F-0001</code> arrived and tested it: a live authorization bypass in the service every other service trusts, with publish-or-forget as the only available choice.</p>
<p><strong>The deferral is narrowed, not kept and not abandoned.</strong></p>
<p>What was right about it: build mode does have no consumers to protect, and building an embargo <em>mechanism</em> — timed release, staged notification, coordinated disclosure with third parties — before there is anyone to coordinate with would be machinery for its own sake.</p>
<p>What was wrong about it: it conflated the mechanism with the decision. The argument for publishing in build mode is that there are no users to expose. That argument says nothing about attackers, and <code>RISK-F-0001</code> is exactly the class where the two come apart — the finding names an unauthenticated decision surface and the service that carries it. Publishing that while it is live helps precisely one kind of reader.</p>
<p>So the ruling is:</p>
<ol><li><strong>Build-mode default stays publish.</strong> Architecture, method, fixed findings, and findings whose exposure is already bounded go out. The estate publishing what it knows is wrong remains the norm and does not need a case made for it each time.</li><li><strong>Live-and-reachable is the exception, and it exists now.</strong> A finding that is unfixed <em>and</em> whose text shortens the path to the defect is <code>embargoed</code> until the fix lands. That is the missing middle <code>INTENT.md</code> said did not exist. It costs one front-matter field and a line in <code>REGISTER.md</code>.</li><li><strong>The mechanism stays deferred.</strong> No timed release, no coordinated disclosure protocol, no notification tiers. Those wait for real users, as originally reasoned. What is not deferred is the <em>decision</em>, because <code>RISK-F-0001</code> demonstrated the decision is needed before the machinery is.</li></ol>
<p>This is a decision of this repo, taken 2026-08-19 with <code>RISK-F-0001</code>, <code>RISK-F-0002</code> and <code>RISK-F-0003</code> in hand rather than hypothetically. It is revisable, and the production transition is the scheduled moment to revisit it.</p>
</section>
<section id="test-for-shortens-the-path"><h2>Test for "shortens the path"</h2>
<p>Ask: does the finding tell a reader something that materially reduces the work of reaching the defect, beyond what reading the repo would give them?</p>
<ul><li>A file path and line number in a private repo — no, that is already there.</li><li>"This surface authenticates nobody, here is its cluster address" — yes.</li><li>"These five named lanes vend real secret values without the boundary firing" — yes.</li><li>"This system had no backups configured" — no, once backups exist; yes, while they do not, because it names when destruction is unrecoverable.</li></ul>
<p>When the answer is genuinely unclear, embargo and re-decide at the review. The cost of a wrong embargo is a delayed publication; the cost of a wrong publish is not recoverable.</p>
</section>
<section id="publication-happens-elsewhere"><h2>Publication happens elsewhere</h2>
<p>A <code>public</code> finding is handed to <code>policy-nexus</code> under its publication contract and gets a permanent address there. This repo never serves it and never edits it after handover; corrections go through the same route as the original.</p>
</section>
<section id="the-standing-route-when-an-embargo-lifts"><h2>The standing route, when an embargo lifts</h2>
<p><code>RISK-WP-0002-T03</code>. Written down because publication will arrive in a trickle as conditions clear, not as a batch, and a route improvised each time is a route that eventually is not taken.</p>
<ol><li><strong>The check that lifts the embargo records it.</strong> <code>make checked</code> on the finding, with the lift as the reason. An embargo lifting is never a clean check — something moved.</li><li><strong>The finding gets publication front-matter</strong>, in the shape <code>policy-nexus</code> already requires of everyone: <code>owner</code>, <code>revision</code>, <code>last_reviewed</code>, <code>review_interval</code>. No body rewrite.</li><li><strong>This repo asks <code>policy-nexus</code> for an entry</strong>, giving <code>source_repo</code>, <code>source_path</code>, a proposed <code>canonical_path</code> under <code>findings/&lt;id&gt;/&lt;version&gt;/</code>, and a one-line subtitle. Addressing and permanence are theirs (<code>POLICY-NEXUS-WP-0001</code>); this repo does not invent a scheme.</li><li><strong><code>publication: published</code> is recorded back on the finding</strong>, with the URL. A finding that says <code>public</code> but has no address is a claim, not a publication — the same class of error as a backup nobody has restored from.</li></ol>
<p>The contract publishes <strong>a file from the owning repo</strong>, so what is handed over is exactly what a reader gets. That makes the whole-versus-summary decision (T01) a decision about what a finding <em>file</em> contains, not about how it is rendered.</p>
</section><footer><span>RISK-METHOD-DISCLOSURE · adopted-1 · adopted</span><span>risk-nexus · docs/method/disclosure.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

244
docs/evidence/2026-10-11-served-publication-history/pages/RISK-METHOD-REVIEW.html Normal file
View file

@ -0,0 +1,244 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="8f873d105bf6bd711a1a15ebd739b2abe97365b4e854be9d1c82e3ff3b162cfd">
<title>Review and expiry</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-METHOD-REVIEW</span> <span class="stat">adopted · adopted-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>Review and expiry</h1><p class="sub">Source: <code>risk-nexus · docs/method/review.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#the-cadence-ladder"><span class="n">·</span>The cadence ladder</a></li><li><a href="#what-a-review-is"><span class="n">·</span>What a review is</a></li><li><a href="#when-a-check-is-missed"><span class="n">·</span>When a check is missed</a></li><li><a href="#the-production-re-score"><span class="n">·</span>The production re-score</a></li><li><a href="#front-matter-this-adds"><span class="n">·</span>Front-matter this adds</a></li><li><a href="#closing-a-finding"><span class="n">·</span>Closing a finding</a></li></ol></nav><main><p><code>INTENT.md</code>: a finding that has sat untouched past its review date is itself a finding. Silence is not resolution. This document makes that operable.</p>
<section id="the-cadence-ladder"><h2>The cadence ladder</h2>
<p>Operator ruling, 2026-08-20. <strong>Intervals are not set by severity. They are earned by outcomes.</strong></p>
<p>A finding is checked, and the check comes back clean or it does not. Clean climbs one rung. Anything wrong drops straight back to the bottom.</p>
<div class="scroll"><table><thead><tr><th>Rung</th><th>Wait before the next check</th></tr></thead><tbody><tr><td><code>instant</code></td><td>now, and again immediately until a check comes back clean</td></tr><tr><td><code>1h</code></td><td>one hour</td></tr><tr><td><code>8h</code></td><td>eight hours</td></tr><tr><td><code>24h</code></td><td>one day</td></tr><tr><td><code>48h</code></td><td>two days</td></tr><tr><td><code>96h</code></td><td>four days</td></tr><tr><td><code>7d</code></td><td>one week</td></tr><tr><td><code>14d</code></td><td>two weeks</td></tr><tr><td><code>1mo</code></td><td>one month</td></tr><tr><td><code>1q</code></td><td>one quarter — <strong>the ceiling; nothing is ever checked less often than this</strong></td></tr></tbody></table></div>
<p>Two rules and one escape:</p>
<ul><li><strong>Climb on clean.</strong> One rung per clean check, never two.</li><li><strong>Reset on anything wrong.</strong> Not a slide down one rung — straight to <code>instant</code>. A matter that has just moved has no track record, whatever it had before.</li><li><strong>The operator may defer.</strong> An <code>instant</code> finding can be deferred to a stated future date by explicit operator decision, recorded as <code>deferred_to</code>. That is the only way out of the bottom rung other than a clean check, and it is a decision with a name on it rather than a check quietly not happening.</li></ul>
<h3>Who checked, and when anyone last did</h3>
<p><code>RISK-WP-0005-T06</code>. Two defences against the rung telling a lie:</p>
<ul><li><strong><code>checked_by</code> on every check.</strong> <code>record_check.py</code> writes it. A rung earned by nobody in particular is visible as such.</li><li><strong>A heartbeat.</strong> If nothing anywhere in the register has been checked for two days, <code>make check</code> says so <strong>before anything else</strong>. A <code>1q</code> rung means "stable for a quarter" and "nobody looked for a quarter", and those read identically from the outside — the heartbeat is what separates them.</li></ul>
<h3>The rung is the signal</h3>
<p>This is the point of the design, not a side effect. <strong>The cadence a finding sits on is a statement about how stable the estate has been on that matter.</strong></p>
<p><code>RISK-F-0002</code> at <code>1q (9)</code> says the signing gate has been examined ten times over three months and nothing has moved. <code>RISK-F-0002</code> at <code>instant (0)</code> says something changed within the day. The number carries information that no severity does — severity says how bad it would be, the rung says how settled it is — and the two are independent. A <code>low</code> finding that keeps resetting is telling you something a <code>critical</code> one at the ceiling is not.</p>
<p>It is also self-correcting in the direction that matters. Anything volatile gets attention often, automatically, without anyone deciding it deserves it; anything genuinely quiet stops consuming attention, without anyone deciding to stop looking. Neither of those judgements has to be made by a person who might be wrong or busy.</p>
<h3>What "clean" means</h3>
<p>A check is <strong>clean</strong> when nothing about the assessment moved: the grade still holds, every stated blocker is still true, the fix state is unchanged, the disclosure state is still right, and no new fact has arrived.</p>
<p>A check is <strong>not clean</strong> when any of those moved — including when they moved in a good direction. <code>RISK-F-0001</code> being fixed is not a clean check; it is a large change, and the next check comes immediately. Good news resets the ladder exactly like bad news, because the ladder measures stillness, not health.</p>
<h3>Starting position</h3>
<p>Every finding starts at <code>instant</code>. A register with no check history has no grounds to wait, and the first clean check is what buys the first hour.</p>
<p>The whole register sat at <code>instant (0)</code> on 2026-08-20, which is correct and temporary: everything in it had been graded, re-graded or ruled on within the preceding day.</p>
</section>
<section id="what-a-review-is"><h2>What a review is</h2>
<p>Five questions, answered in writing on the finding. It takes minutes; it is not an investigation.</p>
<ol><li><strong>Has the inbox said anything?</strong> Read the messages addressed to this repo before anything else. This is question zero because on 2026-08-19 the register graded <code>RISK-F-0001</code> <code>critical</code> while two messages sat unread in its own inbox — one narrowing the exposure, one reporting the fix. Both changed the grade. A register that does not read its own inbox is guessing with a straight face.</li><li><strong>Is the grade still right?</strong> Re-read impact and likelihood against what has changed. New facts move the grade in both directions.</li><li><strong>Is the blocker still true?</strong> This is the one <code>RISK-F-0002</code> bought with evidence: <em>a blocker is a claim about the world at a date</em>. Its own stated blocker — "<code>flex-auth</code> is not deployed yet" — was invalidated within a day by <code>RISK-F-0001</code>, and nothing would have re-checked it. Every review re-checks every stated blocker.</li><li><strong>Has the fix moved?</strong> Read the owner's tracking record, not our memory of it. Confirm the record still exists and still refers to this defect.</li><li><strong>Is the disclosure state still right?</strong> An embargo whose condition has been met is published; an embargo whose condition has not moved in two reviews is a stall.</li></ol>
<p>The finding gets a dated line under <code>## Reviews</code>, <code>last_reviewed</code> is updated, and <code>review_by</code> is pushed by one interval. A review that changes nothing still writes the line — "checked, nothing moved" is the evidence that the silence was observed rather than accidental.</p>
</section>
<section id="when-a-check-is-missed"><h2>When a check is missed</h2>
<p>Overdue is not a status change on the finding. It is a fact about <em>this repo</em>, and it surfaces in three places:</p>
<ul><li><code>make check</code> lists it under "Checks due", with how late it is and which rung it is on.</li><li><code>REGISTER.md</code> shows the next check as <strong>due</strong>.</li><li>A finding sitting at the bottom rung for more than fourteen days with no movement fires escalation trigger 5. Bottom rung means it keeps failing or keeps being skipped; fourteen days of that is a stall whichever it is.</li></ul>
<p>The register does not auto-escalate severity for lateness and does not auto-close anything. Both would be the register lying about its own state to make a number look better.</p>
</section>
<section id="the-production-re-score"><h2>The production re-score</h2>
<p>Every finding carries <code>severity_at_production</code> alongside <code>severity</code> (<code>docs/method/severity.md</code>). Where the two differ, the finding is flagged <code>production_rescore: true</code>.</p>
<p>On the day any part of the estate declares production readiness, every flagged finding is re-scored before that declaration completes. This is not a review date — it is an event, and it fires regardless of where the review dates happen to sit.</p>
<p>Until then, <code>make check</code> lists the flagged findings so the size of that obligation is visible rather than discovered on the day.</p>
</section>
<section id="front-matter-this-adds"><h2>Front-matter this adds</h2>
<pre>last_checked: &quot;2026-08-20T05:40:00Z&quot;
next_check: &quot;2026-08-20T06:40:00Z&quot;
cadence: 1h
clean_streak: 1
production_rescore: true
deferred_to: &quot;&quot; # only by explicit operator decision</pre>
<p><code>next_check</code> is what the nag reads, and it is an absolute moment rather than a duration, so nothing has to recompute an interval to know whether a check is late. The rungs run in hours as well as days, so it carries a time.</p>
</section>
<section id="closing-a-finding"><h2>Closing a finding</h2>
<p>A finding leaves <code>open</code> for exactly one of:</p>
<ul><li><code>fixed</code> — the owner's record shows the defect gone, and this repo has read something concrete rather than been told. Publication follows if the disclosure state was <code>embargoed</code>.</li><li><code>accepted</code> — the estate is deliberately carrying it. Requires who accepted it, why, and what ends the acceptance. <code>accepted</code> is not closed: it stays on the ladder forever, and it climbs like anything else.</li><li><code>mitigated</code> — the live gap is closed but the finding is not. <code>RISK-F-0003</code> is the case: the boundary now fires, and the omission that let it not fire is still there. Stays watched.</li><li><code>withdrawn</code> — the finding was wrong, or the defect never existed. Say which.</li></ul>
<p><strong>Any status the tooling does not recognise keeps the finding watched, and the unrecognised word is reported.</strong> <code>RISK-F-0003</code> arrived as <code>mitigated</code> on 2026-08-20, before that word existed here, and dropped silently out of <code>make check</code> — a finding vanishing from the nag because someone used an unfamiliar word is precisely the failure this register exists to prevent. The tooling now fails loud instead of quiet.</p>
<p>There is no <code>stale</code>, no <code>wontfix</code> and no silent expiry. A finding that nobody will fix and nobody will accept stays <code>open</code> and keeps arriving in the nag, because that is the true state.</p>
</section><footer><span>RISK-METHOD-REVIEW · adopted-1 · adopted</span><span>risk-nexus · docs/method/review.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

256
docs/evidence/2026-10-11-served-publication-history/pages/RISK-METHOD-SEVERITY.html Normal file
View file

@ -0,0 +1,256 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="f064c591aeef9425bbfbd5fa2aae659abb0ef83b8586848300077f41dd4ffaab">
<title>Severity</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-METHOD-SEVERITY</span> <span class="stat">adopted · adopted-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>Severity</h1><p class="sub">Source: <code>risk-nexus · docs/method/severity.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#the-two-axes"><span class="n">·</span>The two axes</a></li><li><a href="#the-grid"><span class="n">·</span>The grid</a></li><li><a href="#the-fidelity-modifier"><span class="n">·</span>The fidelity modifier</a></li><li><a href="#which-state-is-scored"><span class="n">·</span>Which state is scored</a></li><li><a href="#build-mode"><span class="n">·</span>Build mode</a></li><li><a href="#non-adversarial-findings"><span class="n">·</span>Non-adversarial findings</a></li><li><a href="#live-incidents"><span class="n">·</span>Live incidents</a></li><li><a href="#the-floor"><span class="n">·</span>The floor</a></li><li><a href="#provenance-is-a-grading-input"><span class="n">·</span>Provenance is a grading input</a></li><li><a href="#recording-a-grade"><span class="n">·</span>Recording a grade</a></li></ol></nav><main><p>This is <code>risk-nexus</code>'s judgement instrument. It is not canon, it is not a standard, and it binds nobody else. It exists so that two findings graded a month apart are graded the same way, and so that a grade can be argued with.</p>
<p>It was written against three real findings (<code>RISK-F-0001</code>, <code>RISK-F-0002</code>, <code>RISK-F-0003</code>) and it must keep grading those three sensibly or it is wrong.</p>
<section id="the-two-axes"><h2>The two axes</h2>
<h3>Impact — what happens if it goes wrong once</h3>
<div class="scroll"><table><thead><tr><th>Band</th><th>Name</th><th>Test</th></tr></thead><tbody><tr><td><code>I1</code></td><td>negligible</td><td>Confined to one component. No data leaves it, no record is falsified, no recovery is lost.</td></tr><tr><td><code>I2</code></td><td>limited</td><td>One system's data or availability. Recoverable. Confined to a single tenant, actor or lane.</td></tr><tr><td><code>I3</code></td><td>serious</td><td>Crosses a boundary — tenant, system, or trust — or removes recoverability for one system.</td></tr><tr><td><code>I4</code></td><td>severe</td><td>Crosses the estate. What is compromised here propagates to everything that trusts it, or the data loss is unbounded.</td></tr></tbody></table></div>
<p>Impact is scored at <strong>one occurrence</strong>, not at the worst imaginable campaign. "An attacker who already owns the cluster could do this too" is not an impact argument.</p>
<h3>Likelihood — how far anyone has to reach</h3>
<div class="scroll"><table><thead><tr><th>Band</th><th>Name</th><th>Test</th></tr></thead><tbody><tr><td><code>L1</code></td><td>remote</td><td>Requires access nobody currently holds and no ordinary process grants.</td></tr><tr><td><code>L2</code></td><td>possible</td><td>Requires a foothold the estate does grant somewhere — an in-cluster workload, an agent session, a scoped token.</td></tr><tr><td><code>L3</code></td><td>likely</td><td>Reachable from inside the normal working set with no additional step.</td></tr><tr><td><code>L4</code></td><td>present</td><td>No barrier at all, or it is already happening.</td></tr></tbody></table></div>
<p>Likelihood is about <strong>reach</strong>, not about intent or about whether anyone has bothered. <code>risk-nexus</code> does not model attackers; it models what the system permits.</p>
<p>Where the reporter has not established exposure, the finding says so and the grade uses the band the <em>stated</em> facts support — not the worst case, and not zero. <code>RISK-F-0001</code> explicitly declines to assume a default-deny NetworkPolicy exists; the grade must decline with it, and the unverified fact becomes a review item rather than a silent assumption in either direction.</p>
</section>
<section id="the-grid"><h2>The grid</h2>
<div class="scroll"><table><thead><tr><th></th><th><code>L1</code></th><th><code>L2</code></th><th><code>L3</code></th><th><code>L4</code></th></tr></thead><tbody><tr><td><code>I4</code></td><td>medium</td><td>high</td><td><strong>critical</strong></td><td><strong>critical</strong></td></tr><tr><td><code>I3</code></td><td>low</td><td>medium</td><td>high</td><td><strong>critical</strong></td></tr><tr><td><code>I2</code></td><td>low</td><td>low</td><td>medium</td><td>high</td></tr><tr><td><code>I1</code></td><td>note</td><td>low</td><td>low</td><td>medium</td></tr></tbody></table></div>
<p>Four severities: <code>low</code>, <code>medium</code>, <code>high</code>, <code>critical</code>. <code>note</code> is not a severity; see the floor.</p>
</section>
<section id="the-fidelity-modifier"><h2>The fidelity modifier</h2>
<p><strong>A control that lies is one impact band worse than the same control absent.</strong></p>
<p>Apply <code>+1</code> impact band (capped at <code>I4</code>) when the failure mode produces a <em>false record</em> rather than <em>no record</em>: an attestation that a check passed when nothing checked, an audit line asserting an authorization that was never made, a green signal derived from an unreachable test.</p>
<p>The reasoning is <code>RISK-F-0002</code>'s and the register adopts it: an absent control is a gap you can find by looking; a lying control is a gap that survives looking, because the evidence you would look at is the thing that is wrong. Only one of the two states misleads the person investigating afterwards.</p>
<p>The modifier applies to the state being scored. A finding that describes both states — control absent today, control lying if switched on in the wrong order — gets <strong>two scores and one of them is the register's headline</strong>; see "Which state is scored".</p>
</section>
<section id="which-state-is-scored"><h2>Which state is scored</h2>
<p>The headline <code>severity</code> is the state of the world <strong>today</strong>. A hazard that would be created by a <em>future</em> action is not the headline, because a register that scores hypotheticals stops describing the estate.</p>
<p>The hazard is not lost. It is recorded on the finding as a named <strong>constraint</strong> with its own grade, and it attaches to whatever action would trigger it — usually another finding's remediation. <code>RISK-F-0002</code> is the worked example: the gate being off is today (headline), the gate being switched on while the oracle is forgeable is a constraint on <code>RISK-F-0001</code>'s fix, graded separately and higher.</p>
<p>If the constraint's grade is higher than the headline, the finding says so in its ruling. A reader must not be able to come away with the low number and miss the high one.</p>
</section>
<section id="build-mode"><h2>Build mode</h2>
<p>Every finding is graded twice:</p>
<ul><li><code>severity</code> — today, in build mode, with today's likelihood.</li><li><code>severity_at_production</code> — the same impact, with likelihood re-read for a system carrying real users and real tenant data.</li></ul>
<p>Build mode legitimately lowers <strong>both</strong> axes, for different reasons: likelihood, where the reach itself depends on a production deployment that has not happened; and impact, where the data that would be exposed does not exist yet. What it must never lower is <code>severity_at_production</code> — the defect does not improve because the calendar has not reached it.</p>
<div class="rule-quote"><p><em>Amended 2026-08-19 (<code>RISK-WP-0001-T07</code>).</em> This paragraph originally said build mode was a likelihood input and never an impact one. Grading the unverified tenant boundary broke that: what build mode changes there is the consequence of an occurrence, not the reach of it. The instrument was wrong on first hard use and is corrected rather than worked around.</p></div>
<p>Where the two grades differ, the production transition is a mandatory re-score. <code>docs/method/review.md</code> binds the review date to it, so the re-score is a scheduled event and not somebody's memory.</p>
</section>
<section id="non-adversarial-findings"><h2>Non-adversarial findings</h2>
<p>Likelihood is written as reach because most findings are about someone getting somewhere. Where a finding is about loss, corruption or outage — no backup, no recovery path, an eviction-prone deployment — there is no attacker to model.</p>
<p>For those, likelihood reads as <strong>the chance of the triggering event inside one review interval</strong>: <code>L1</code> would be surprising, <code>L2</code> is an ordinary failure the estate has seen before, <code>L3</code> is expected in the normal course of running, <code>L4</code> is already happening. Impact is unchanged: what is lost, and whether it comes back.</p>
<div class="rule-quote"><p><em>Added 2026-08-19 (<code>RISK-WP-0001-T07</code>).</em> Forced by <code>RISK-F-0006</code>, where the defect is an absent backup and the reach reading produced nonsense.</p></div>
</section>
<section id="live-incidents"><h2>Live incidents</h2>
<p>Everything above assumes a latent defect — something reachable that nobody is currently reaching. When someone is, three things change:</p>
<ul><li><strong>Likelihood is <code>L4</code>.</strong> The band means "already happening" and this is what it is for.</li><li><strong>Impact is scored on what has occurred plus what is still reachable</strong>, not on the worst case. An incident in progress has facts; use them.</li><li><strong>The grade is provisional and expected to move.</strong> File first, grade within the hour, re-grade as facts arrive. <code>docs/method/intake.md</code> has the rest, including the 72-hour clock that <code>first_observed</code> starts.</li></ul>
</section>
<section id="the-floor"><h2>The floor</h2>
<p><code>INTENT.md</code>: if a finding would not change anyone's decision, it is a note, not a risk. Concretely, a register entry requires <strong>both</strong>:</p>
<ol><li><strong>An owner who could act.</strong> Some repo, or the operator, can do something about it. No actor, no entry.</li><li><strong>A decision that changes.</strong> Recording it alters what someone does, when they do it, or what they must not do first.</li></ol>
<p>Fails either test → it is a note in <code>notes/</code>, not a finding in <code>findings/</code>. Notes are not graded, not reviewed, and not published. They exist so that "we saw it" survives without inflating the register.</p>
<p>An <code>I1</code>/<code>L1</code> cell is <code>note</code> in the grid for the same reason: something that is both negligible and unreachable is a thing we know, not a risk we carry.</p>
<p>Two things the floor does <strong>not</strong> exclude:</p>
<ul><li><strong>Known and deliberate.</strong> <code>RISK-F-0002</code> is a decision somebody made on purpose. It still passes the floor, because it changes what may be switched on and in what order. Deliberate is not the same as tracked.</li><li><strong>Omission-shaped.</strong> <code>RISK-F-0003</code> is a default that silently produces ungoverned lanes. The individual lane is small; the default is not.</li></ul>
</section>
<section id="provenance-is-a-grading-input"><h2>Provenance is a grading input</h2>
<p>All four defects known to this register were found by repos reading their own code against a ladder, within days of each other. None was found by monitoring.</p>
<p>Where a finding's provenance is "we happened to look", the register does not get to assume that similar defects would have been caught. That raises likelihood for the class, not for the instance, and it belongs in the ruling's reasoning rather than in a modifier — the register grades what is filed, and notes when the filing was luck.</p>
</section>
<section id="recording-a-grade"><h2>Recording a grade</h2>
<p>The finding's front-matter carries:</p>
<pre>severity: critical # headline, today
severity_at_production: critical
impact: I4 # band, before modifiers
likelihood: L3
fidelity_modifier: false # true if +1 applied, with the reason in the ruling</pre>
<p>and the ruling section states impact, likelihood, any modifier, and the one sentence that would have to become false for the grade to change.</p>
</section><footer><span>RISK-METHOD-SEVERITY · adopted-1 · adopted</span><span>risk-nexus · docs/method/severity.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

222
docs/evidence/2026-10-11-served-publication-history/pages/RISK-METHOD-VERIFICATION.html Normal file
View file

@ -0,0 +1,222 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a13d954f8597fd92201746e2d52f031a5a88d969">
<meta name="policy-source-digest" content="562b6eb3031ffe35e712c5e11e35aae23ce84a90e0090438dc89513f9685052b">
<title>What this register may verify for itself, and what it must take from owners</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RISK-METHOD-VERIFICATION</span> <span class="stat">adopted · adopted-1</span> <span>risk-nexus</span> <span>reviewed 2026-08-20</span><span>generated from canonical source — do not edit</span></div><h1>What this register may verify for itself, and what it must take from owners</h1><p class="sub">Source: <code>risk-nexus · docs/method/verification.md · a13d954f8597fd92201746e2d52f031a5a88d969</code></p><p class="sub">Review due: 2027-02-20</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#the-rule"><span class="n">·</span>The rule</a></li><li><a href="#what-this-host-can-actually-reach-established-2026-08-20"><span class="n">·</span>What this host can actually reach — established 2026-08-20</a></li><li><a href="#a-file-is-not-a-safe-proxy-for-the-server"><span class="n">·</span>A file is not a safe proxy for the server</a></li><li><a href="#recording-a-verification"><span class="n">·</span>Recording a verification</a></li><li><a href="#verification-and-the-cadence-ladder"><span class="n">·</span>Verification and the cadence ladder</a></li></ol></nav><main><p><code>RISK-WP-0004-T05</code> asked what this repo can legitimately establish itself, because two gradings were resting on file comparison. The answer was found by trying, on 2026-08-20, rather than by reasoning about it.</p>
<section id="the-rule"><h2>The rule</h2>
<p><strong>A register may look. It may not touch, and it may not conclude on a system's behalf.</strong></p>
<p>Verification here means: running a read-only command a reporter has already named, or that answers a question the register itself wrote down as open, and recording exactly what came back.</p>
<p>Permitted:</p>
<ul><li>read-only reads of live state (<code>kubectl get</code>, <code>bao policy read</code>, an HTTP probe of a documented endpoint);</li><li>comparing what is deployed against what a repo said is deployed;</li><li>recording the discrepancy and routing it as a <strong>question</strong>.</li></ul>
<p>Not permitted:</p>
<ul><li>any write, apply, patch, restart or rotation — including one that would obviously improve things;</li><li>concluding what a defect means for a system this repo does not own. The system stays authoritative about itself (<code>INTENT.md</code>);</li><li>verifying instead of asking. The owner is asked first; verification settles what an owner cannot see or has invited someone to check.</li></ul>
<p><code>rapp-postgres</code> declined to check the NetworkPolicy on <code>flex-auth</code>'s behalf, saying that would be reporting on a system they do not own. That was right <strong>for a reporter</strong>. This register is the downstream party whose grade depended on the answer, and <code>flex-auth</code> explicitly named the command and asked for someone with credentials to run it. Those two positions are compatible.</p>
</section>
<section id="what-this-host-can-actually-reach-established-2026-08-20"><h2>What this host can actually reach — established 2026-08-20</h2>
<div class="scroll"><table><thead><tr><th>Target</th><th>Result</th><th>Consequence</th></tr></thead><tbody><tr><td>Kubernetes (<code>railiance01</code>)</td><td><strong>reads work</strong> — <code>kubectl get ns</code>, <code>get networkpolicy -o json</code></td><td>Live cluster state is verifiable by this register</td></tr><tr><td>OpenBao (<code>bao.coulomb.social</code>)</td><td><strong>403 permission denied</strong> on <code>token lookup</code> and <code>policy read</code></td><td>Policy claims are not verifiable here; <code>RISK-F-0009</code> rests on file comparison</td></tr></tbody></table></div>
<p>The asymmetry is worth stating plainly: <strong>the register can check what the cluster admits, and cannot check what the secret store permits.</strong> Every grade touching an OpenBao policy is therefore a grade on a document, and says so.</p>
<p>That is not a gap to close by acquiring credentials. A risk register holding production secret-store access has traded a verification problem for a much worse one. If OpenBao claims need verifying, the right answer is for the owner to run the read and report it, which is what <code>ops-warden</code> did — the obstacle there was an expired token, not the arrangement.</p>
</section>
<section id="a-file-is-not-a-safe-proxy-for-the-server"><h2>A file is not a safe proxy for the server</h2>
<p>Established 2026-08-21, by evidence rather than by caution. <code>ops-warden</code> ran the live OpenBao read that <code>RISK-F-0009</code> had been graded without, and <strong>the deployed policy differs from the committed file.</strong> No lane maps to the drifted path, so nothing was exposed — but the general claim is now proven rather than suspected.</p>
<p>Consequences this register accepts:</p>
<ul><li><strong>Every grade made off a checkout is a grade on a document</strong>, and says so on its face. <code>RISK-F-0009</code> does.</li><li>A verification that reads a file is a <strong>weaker artifact</strong> than one that reads a server, and the record must not blur them. <code>RISK-V-0001</code> reads a server; the OpenBao comparison in <code>RISK-F-0009</code> reads a file.</li><li>Where only the owner can reach the server, the owner's probe is the evidence and the register says whose it is. That is not a lesser standard — it is the correct one, given <code>verification.md</code>'s own limits.</li></ul>
<p>The corollary is uncomfortable and worth stating: <strong>drift between file and server is invisible to anyone reading files</strong>, which is most of this estate's tooling, including <code>fix_tracker.py</code>. What that tool reads is what a repo <em>recorded</em>, and a record can be as stale as any other claim — as four self-reported stale blockers in twelve hours demonstrated on 2026-08-21.</p>
</section>
<section id="recording-a-verification"><h2>Recording a verification</h2>
<p>One file per verification in <code>docs/verifications/</code>, <code>RISK-V-NNNN</code>, stating the command, the raw result, what it confirms, what it contradicts, and what it does not establish. It names the findings it bears on, and those findings link back.</p>
<p>A verification is evidence, not a ruling. It can move a grade; it does not close a finding on its own, and it never speaks for the owning repo.</p>
</section>
<section id="verification-and-the-cadence-ladder"><h2>Verification and the cadence ladder</h2>
<p>A verification that contradicts something is a check that is <strong>not clean</strong>: the affected findings reset to <code>instant</code>. A verification that confirms what was already recorded is clean, and may be exactly the evidence a rung is built on.</p>
<p>The first one (<code>RISK-V-0001</code>) did both — it confirmed the ingress claim <code>RISK-F-0001</code> was graded on, contradicted the egress claim in the same message, and surfaced a third policy nobody had mentioned that bears on <code>RISK-F-0002</code>.</p>
</section><footer><span>RISK-METHOD-VERIFICATION · adopted-1 · adopted</span><span>risk-nexus · docs/method/verification.md · a13d954f8597fd92201746e2d52f031a5a88d969</span></footer></main></div></div></html>

235
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0001.html Normal file
View file

@ -0,0 +1,235 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="debbc13b4018f20db0997516b99afc1cc21084d7">
<meta name="policy-source-digest" content="b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497">
<title>Repository Prefix Architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0001</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-07-25</span><span>generated from canonical source — do not edit</span></div><h1>Repository Prefix Architecture</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · debbc13b4018f20db0997516b99afc1cc21084d7</code></p><p class="sub">Review due: 2027-01-25</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#meaning-of-each-family"><span class="n">·</span>Meaning Of Each Family</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#current-interpretation-for-existing-repos"><span class="n">·</span>Current Interpretation For Existing Repos</a></li><li><a href="#notes"><span class="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-07-25 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Railiance already has a meaningful set of ownership repos such as <code>railiance-infra</code>, <code>railiance-cluster</code>, <code>railiance-platform</code>, <code>railiance-enablement</code>, <code>railiance-apps</code>, <code>railiance-forge</code>, and <code>railiance-fabric</code>.</p>
<p>That structure is useful, but it does not by itself capture all of the dimensions Railiance now needs.</p>
<p>In particular, the architecture needs clear source-controlled homes for:</p>
<ul><li>workload execution contracts across different operations architectures,</li><li>managed workload packages as first-class repos,</li><li>and concrete substrate boundaries such as named servers, workstations, or grouped environments.</li></ul>
<p>Without that separation, Kubernetes-specific workload semantics remain mixed into <code>railiance-cluster</code>, workload wrappers remain mixed into ownership repos, and concrete substrates remain under-described.</p>
<p>Railiance also operates inside a wider ecosystem around Railiance, Net Kingdom, and the Helix Forge software factory. That wider context needs architecture that can support both exploratory operation and production-grade evolution without leaving key responsibilities ambiguous.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Railiance adopts four canonical repository families:</p>
<ol><li><code>railiance-*</code> for ownership and responsibility areas</li><li><code>rail-*</code> for workload execution contracts</li><li><code>rapp-*</code> for Railiance-managed workload packages</li><li><code>reef-*</code> for durable substrate boundaries</li></ol>
<p>The current implementation wave is explicitly centered on <code>rail-kubernetes</code> as the default base rail. Additional rails are introduced only when a concrete workload has a sound reason to run on a distinct execution architecture.</p>
<p><code>rail-knative</code> is the first expected follow-on rail, motivated by the need to support <code>qonto-assistent</code>, but it should follow the <code>rail-kubernetes</code> boundary cleanup rather than bypass it.</p>
</section>
<section id="meaning-of-each-family"><h2>Meaning Of Each Family</h2>
<h3><code>railiance-*</code></h3>
<p>Owns major architectural responsibilities, shared policies, and durable layer boundaries.</p>
<h3><code>rail-*</code></h3>
<p>Owns how workloads run on a specific execution architecture such as Kubernetes, Knative, KEDA, Fission, or Nuclio.</p>
<p>In the current phase, <code>rail-kubernetes</code> is the default path for platform services and managed applications.</p>
<h3><code>rapp-*</code></h3>
<p>Owns the managed workload package for one service or application, whether it is an internal workload or a wrapped upstream product.</p>
<p>Its role is to provide the managed wrapper and scaffolding needed to run that workload in the Railiance and Net Kingdom context. It does not replace responsibility ownership.</p>
<h3><code>reef-*</code></h3>
<p>Owns the concrete substrate reality where rails and <code>rapp</code>s are bound, such as a named server, cluster, workstation, or grouped substrate class.</p>
<p>A reef is about purpose-bound compute resources, not merely about individual machines.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>Ownership, execution, workload identity, and substrate identity become separate concerns.</li><li>Railiance can support multiple execution architectures without forcing all workload semantics into <code>railiance-cluster</code>.</li><li>Platform services and applications can both become first-class managed workload packages where appropriate.</li><li>Concrete substrates gain a clear architectural home without overloading the ownership repos.</li><li>The framework gains a disciplined default path for introducing new rails instead of proliferating them speculatively.</li></ul>
<h3>Required Follow-On Work</h3>
<ul><li>Define the initial <code>rail-*</code> contracts, starting with <code>rail-kubernetes</code>.</li><li>Evolve the current <code>railiance/app.toml</code> and overlay pattern into a rail-aware, eventually rail-neutral workload packaging contract.</li><li>Identify which current workloads should become <code>rapp-*</code> repos.</li><li>Extend <code>railiance-fabric</code> so rails, <code>rapp</code>s, and reefs become graph-native.</li><li>Define when mixed-rail reefs are acceptable and when clearer substrate separation should be preferred.</li></ul>
<h3>Constraints</h3>
<ul><li><code>reef-*</code> must not become a default one-repo-per-machine pattern.</li><li>Generic logic stays in the appropriate ownership repo.</li><li>A named machine gets its own reef only when that machine is itself a durable substrate boundary.</li><li><code>rapp-*</code> repos must not become shadow ownership repos.</li><li>Transitional substrate labels should not be canonized before the pattern is operationally stable.</li></ul>
</section>
<section id="current-interpretation-for-existing-repos"><h2>Current Interpretation For Existing Repos</h2>
<ul><li><code>railiance-*</code> repos remain the primary ownership axis.</li><li>Current workload-execution logic in <code>railiance-cluster</code> is a candidate to migrate into <code>rail-kubernetes</code>.</li><li>Current workload wrappers inside <code>railiance-apps</code>, <code>railiance-platform</code>, or <code>railiance-forge</code> may evolve into <code>rapp-*</code> repos over time.</li><li>Current named substrates such as COULOMBCORE, RAILIANCE01, and WORKSTATION may justify <code>reef-*</code> repos when they represent real operational boundaries.</li><li>A reef may host more than one rail in early or mixed environments, but production-critical substrates should prefer clearer purpose and primary-rail boundaries unless a mixed design is justified.</li></ul>
</section>
<section id="notes"><h2>Notes</h2>
<p>This ADR defines the repository taxonomy. It does not yet mandate a full migration or rename of existing repos. Migration should happen when it produces clearer ownership and lower ambiguity, not merely for naming purity.</p>
</section><footer><span>RMASTER-ADR-0001 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · debbc13b4018f20db0997516b99afc1cc21084d7</span></footer></main></div></div></html>

218
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0002.html Normal file
View file

@ -0,0 +1,218 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="debbc13b4018f20db0997516b99afc1cc21084d7">
<meta name="policy-source-digest" content="7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d">
<title>Wave 1 rail-kubernetes Boundary</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0002</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-07-25</span><span>generated from canonical source — do not edit</span></div><h1>Wave 1 rail-kubernetes Boundary</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · debbc13b4018f20db0997516b99afc1cc21084d7</code></p><p class="sub">Review due: 2027-01-25</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#notes"><span class="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-07-25 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Railiance wants <code>rail-*</code> repos to represent workload execution contracts rather than abstract naming ideas.</p>
<p>Today, the concrete Kubernetes workload contract already exists, but it is embedded in <code>railiance-cluster</code>. That repo currently owns both:</p>
<ul><li>the S2 Kubernetes substrate</li><li>and the generic workload lifecycle and tooling that run on top of it</li></ul>
<p>That mixed ownership is the main blocker to introducing the first real rail.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Railiance will treat <code>rail-kubernetes</code> as the wave-1 base rail.</p>
<p>The boundary is:</p>
<ul><li><code>railiance-cluster</code> owns the Kubernetes substrate and its prerequisites</li><li><code>rail-kubernetes</code> owns the generic workload-on-Kubernetes execution contract</li></ul>
<p>Workload-specific helper flows currently living in <code>railiance-cluster</code> are temporary exceptions and must be rehomed rather than carried forward as part of the generic rail.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>The first real rail gains a concrete ownership boundary.</li><li><code>railiance-cluster</code> can return to a clean S2 substrate identity.</li><li>Future rails such as <code>rail-knative</code> get a stable base boundary to extend from.</li><li><code>rapp-*</code> repos gain a clearer execution-contract home for Kubernetes-managed workloads.</li></ul>
<h3>Required Follow-On Work</h3>
<ul><li>Create the detailed <code>rail-kubernetes</code> boundary contract and migration map.</li><li>Split generic lifecycle docs, schema, examples, and Stage 1-3 tooling out of <code>railiance-cluster</code>.</li><li>Leave a compatibility path so current users of the cluster repo are not broken during the migration.</li><li>Rehome workload-specific helpers that do not belong in either boundary.</li></ul>
<h3>Constraints</h3>
<ul><li><code>rail-kubernetes</code> must not take ownership of cluster bootstrap, operators, or kubeconfig management.</li><li><code>railiance-cluster</code> must not continue as the owner of generic workload promotion semantics after the split.</li><li><code>rail-knative</code> should follow this cleanup, not bypass it.</li></ul>
</section>
<section id="notes"><h2>Notes</h2>
<p>This ADR does not require all current files to move immediately.</p>
<p>It requires the ownership line to be explicit now, so practical repo separation can proceed without ambiguity.</p>
</section><footer><span>RMASTER-ADR-0002 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · debbc13b4018f20db0997516b99afc1cc21084d7</span></footer></main></div></div></html>

216
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0003.html Normal file
View file

@ -0,0 +1,216 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="debbc13b4018f20db0997516b99afc1cc21084d7">
<meta name="policy-source-digest" content="28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc">
<title>First-Wave rapp Selection</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0003</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-07-25</span><span>generated from canonical source — do not edit</span></div><h1>First-Wave rapp Selection</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · debbc13b4018f20db0997516b99afc1cc21084d7</code></p><p class="sub">Review due: 2027-01-25</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#notes"><span class="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-07-25 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Railiance wants <code>rapp-*</code> repos to represent managed workload packages rather than new ownership layers.</p>
<p>The current workload surfaces already suggest several candidates:</p>
<ul><li>OpenBao in <code>railiance-platform</code></li><li>the forge workload in <code>railiance-forge</code></li><li>multiple S5 workloads in <code>railiance-apps</code></li></ul>
<p>But they are not equally ready for first extraction.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>The first-wave <code>rapp-*</code> order is:</p>
<ol><li><code>rapp-openbao</code></li><li><code>rapp-vergabe-teilnahme</code></li><li>later <code>rapp-forgejo</code> after the forge runtime target stabilizes</li></ol>
<p>The forge workload is explicitly deferred from the first wave because current Gitea operation and future Forgejo direction are both active realities.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>The first <code>rapp-*</code> extraction proves the third-party platform-service wrapper model.</li><li>The second proves the user-facing self-built app wrapper model.</li><li>The deferred forge wrapper avoids immediate rename churn and packaging ambiguity.</li></ul>
<h3>Required Follow-On Work</h3>
<ul><li>Write repo-local extraction work for <code>rapp-openbao</code>.</li><li>Write repo-local extraction work for <code>rapp-vergabe-teilnahme</code>.</li><li>Reassess the forge wrapper when the production package target is no longer split between current Gitea and future Forgejo.</li></ul>
<h3>Constraints</h3>
<ul><li><code>rapp-*</code> repos must stay packaging-focused and must not become shadow ownership repos.</li><li>Shared S3 policy stays in <code>railiance-platform</code>.</li><li>Shared S5 release patterns stay in <code>railiance-apps</code>.</li></ul>
</section>
<section id="notes"><h2>Notes</h2>
<p>This ADR chooses sequence, not a mandatory destination for every workload in the ecosystem.</p>
</section><footer><span>RMASTER-ADR-0003 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · debbc13b4018f20db0997516b99afc1cc21084d7</span></footer></main></div></div></html>

217
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0004.html Normal file
View file

@ -0,0 +1,217 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="debbc13b4018f20db0997516b99afc1cc21084d7">
<meta name="policy-source-digest" content="36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e">
<title>First-Wave reef Rollout</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0004</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-07-26</span><span>generated from canonical source — do not edit</span></div><h1>First-Wave reef Rollout</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · debbc13b4018f20db0997516b99afc1cc21084d7</code></p><p class="sub">Review due: 2027-01-26</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#notes"><span class="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-07-25 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Railiance now has a reef model, but it needs a concrete first rollout.</p>
<p>The current substrate reality is not uniform:</p>
<ul><li>Railiance01 is the clearest new-workload home</li><li>CoulombCore is still active but transitional</li><li>the workstation role is operator edge compute rather than server substrate</li></ul>
<p>At the same time, S1 ownership is ambiguous because <code>railiance-hosts</code> and <code>railiance-infra</code> duplicate each other.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>The first-wave reef rollout is:</p>
<ol><li><code>reef-railiance</code></li><li><code>reef-coulombcore</code></li><li><code>reef-ops-workstations</code></li></ol>
<p><code>railiance-infra</code> is the canonical S1 ownership repo going forward.</p>
<p><code>railiance-hosts</code> is treated as predecessor or duplicate state to be retired, frozen, or reduced later rather than as a second canonical S1 architecture home.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<h3>Positive</h3>
<ul><li>Railiance gets a grouped home-reef seed whose name remains stable as more home servers are added.</li><li>Transitional CoulombCore reality is acknowledged without being treated as the long-term preferred production pattern.</li><li>Operator edge compute is modeled without defaulting to one repo per machine.</li><li>Reef planning now rests on one canonical S1 ownership line.</li></ul>
<h3>Required Follow-On Work</h3>
<ul><li>Create repo-local rollout work for the first reef repos.</li><li>Define how additional Railiance home servers join <code>reef-railiance</code> and what future split criteria would justify narrower reefs.</li><li>Plan the <code>railiance-hosts</code> cleanup direction relative to <code>railiance-infra</code>.</li></ul>
<h3>Constraints</h3>
<ul><li>Multi-rail reefs are acceptable early, especially on transitional substrates.</li><li>Production-grade separation should still prefer clearer purpose and primary rail boundaries as criticality rises.</li><li>Transitional substrate nicknames should remain provisional until the pattern is stable enough to canonize.</li></ul>
</section>
<section id="notes"><h2>Notes</h2>
<p>This ADR chooses the first rollout set. It does not require that every future substrate be modeled the same way.</p>
</section><footer><span>RMASTER-ADR-0004 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · debbc13b4018f20db0997516b99afc1cc21084d7</span></footer></main></div></div></html>

205
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0005.html Normal file
View file

@ -0,0 +1,205 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="debbc13b4018f20db0997516b99afc1cc21084d7">
<meta name="policy-source-digest" content="e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e">
<title>Derived Rail Composition</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0005</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-07-26</span><span>generated from canonical source — do not edit</span></div><h1>Derived Rail Composition</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0005-derived-rail-composition.md · debbc13b4018f20db0997516b99afc1cc21084d7</code></p><p class="sub">Review due: 2027-01-26</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><p>Date: 2026-07-26 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Knative provides distinct workload activation and revision semantics but runs on Kubernetes. Treating it as an unrelated peer rail would duplicate generic workload lifecycle and substrate assumptions.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Railiance distinguishes base and derived rails.</p>
<p><code>rail-kubernetes</code> is the default base rail for platform workloads. <code>rail-knative</code> is a derived rail that inherits a versioned <code>rail-kubernetes</code> common contract and overrides only Knative-specific activation, revision, autoscaling, traffic, cold-start, and rollback semantics.</p>
<p>The detailed contract is <a href="../rail-composition-contract.md"><code>docs/rail-composition-contract.md</code></a>.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>New platform workloads continue to use <code>rail-kubernetes</code> unless a specialized rail is justified.</li><li>Derived rails declare base-rail compatibility rather than copying lifecycle contracts.</li><li>Fabric and conformance tooling must understand rail dependency and readiness.</li><li>Knative installation stays with the S2 substrate owner.</li></ul>
</section><footer><span>RMASTER-ADR-0005 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0005-derived-rail-composition.md · debbc13b4018f20db0997516b99afc1cc21084d7</span></footer></main></div></div></html>

207
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0006.html Normal file
View file

@ -0,0 +1,207 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="5ffd7d1b40d56249f490a318e728047fd3517c4c">
<meta name="policy-source-digest" content="9839d8a4a4617b745cfacab6a0fb72157e88cddf53f40226d8246a64864de533">
<title>Reef Production Admission</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0006</span> <span class="stat">accepted · accepted-2</span> <span>railiance-master</span> <span>reviewed 2026-08-29</span><span>generated from canonical source — do not edit</span></div><h1>Reef Production Admission</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><p>Date: 2026-07-26 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>Fabric topology can say that a reef hosts a rail or binds a workload, but that does not demonstrate capacity, isolation, recoverability, or approval for a critical internet-facing service.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Rail and <code>rapp</code> bindings use explicit readiness states: <code>declared</code>, <code>installed</code>, <code>verified</code>, <code>production-approved</code>, and <code>deprecated</code>.</p>
<p>Critical workloads require machine-readable conformance evidence plus explicit acceptance of residual risks that cannot be automated. Mixed-rail reefs use defined split triggers.</p>
<p>The detailed contract is <a href="../reef-production-readiness-contract.md"><code>docs/reef-production-readiness-contract.md</code></a>.</p>
<p>Who may reach a listener is a different axis: <a href="ADR-0008-private-by-default-exposure.md"><code>ADR-0008</code></a>. Production admission does not imply a public surface. A public surface requires this admission <strong>and</strong> an exposure grant.</p>
<p>Neither admission nor exposure is an authorization decision. Whether an actor may perform an action on a resource is <code>access-engine</code> (<a href="ADR-0009-netkingdom-security-layer-interaction.md"><code>ADR-0009</code></a>). <code>production-approved</code> MUST NOT be read as permission to act.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>hosts_rail</code> and <code>binds_rapp</code> no longer imply deployability.</li><li><code>reef-railiance</code> may host Knative in wave 2, but Qonto cannot be called production-approved solely from that declaration.</li><li>Repeated evidence collection should become functional automation.</li><li><code>production-approved</code> is not permission to publish a listener. See ADR-0008.</li><li><code>production-approved</code> is not an authorization decision. See ADR-0009.</li></ul>
</section><footer><span>RMASTER-ADR-0006 · accepted-2 · accepted</span><span>railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</span></footer></main></div></div></html>

213
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0007.html Normal file
View file

@ -0,0 +1,213 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="51747ca793d830c42bd86ce0ca43e34db9e8a1c1">
<meta name="policy-source-digest" content="b1185388ded53188dc624fbda9bee517dd3ac80b35e881cd4a7962531bec52ff">
<title>Rapp Declaration Contract</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0007</span> <span class="stat">accepted · accepted-2</span> <span>railiance-master</span> <span>reviewed 2026-08-23</span><span>generated from canonical source — do not edit</span></div><h1>Rapp Declaration Contract</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 51747ca793d830c42bd86ce0ca43e34db9e8a1c1</code></p><p class="sub">Review due: 2027-02-23</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><p>Date: 2026-08-13 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p><code>RMASTER-WP-0017</code> through <code>RMASTER-WP-0019</code> established the four-axis model and materialized the first family repos. The model held up. Its enforcement did not.</p>
<p>A 2026-08-11 survey by <code>railiance-platform</code> found that the three live <code>rapp.yaml</code> files were mutually unreadable: rollout, smoke, and rollback contracts used different shapes; metadata that both rails carry consistently appeared in only one rapp; <code>reef-railiance</code> <code>bound_rapps</code> listed <code>rapp-qonto</code> only, while <code>rapp-openbao</code> and <code>rapp-postgres</code> were already live on the same reef. <code>docs/repo-family-bootstrap-contract.md</code> named fields in prose and could not catch any of this.</p>
<p>The same survey treated rapp grouping as something that might be derived from Forgejo organizations or from State Hub domains. Neither works. A repo lives in exactly one Forgejo org, so <code>org:repo</code> is one-to-many. A repo may legitimately contribute to more than one rapp, so <code>rapp:repo</code> is many-to-many. A many-to-many grouping cannot be derived from a one-to-many one. Domains fail in both directions. The three dimensions also change at different speeds.</p>
<p>Canon OAS P1 requires independent perspectives to be separate orthogonal dimensions. Decision <code>d07ee5f9</code> already recorded this from the <code>railiance-platform</code> side; this ADR is the framework record.</p>
</section>
<section id="decision"><h2>Decision</h2>
<ol><li><strong>Bounded rapp context is its own dimension.</strong> It is derived neither from Forgejo organizations nor from State Hub domains. Grouping is a first-class declaration, not a projection of some other axis.</li></ol>
<ol><li><strong>Two cardinalities stay distinct.</strong> Repos to rapps is many-to-many: a repo may appear in the <code>composition.member_repos</code> of more than one rapp. Deployables to rapps is one-to-one: every running deployable has exactly one rapp that owns its rollout. The coverage question — <em>does every live deployable belong to exactly one rapp?</em> — is well-formed only if these stay distinct.</li></ol>
<ol><li><strong>Granularity is grouped-by-bounded-context.</strong> One rapp per cohesive group that deploys, versions, and rolls back together, not one rapp per deployable. Grouping is legitimate only where members share rollout and rollback fate. A single-repo rapp is the one-member case of the same <code>composition</code> block, not a second shape.</li></ol>
<ol><li><strong>The schema is normative.</strong> <code>schemas/rapp.schema.json</code>, <code>schemas/rail.schema.json</code>, and <code>schemas/reef.schema.json</code> define the shapes. Framework prose cites those files. It does not restate their fields. Reef <code>bound_rapps</code> is a derived projection of <code>rapp.bound_reefs</code>, not a hand-maintained registry.</li></ol>
<ol><li><strong>Coverage includes every managed running deployable.</strong> Application, operational, and tooling runtimes participate in the same exactly-one-rapp invariant when they are installed, scheduled, or otherwise operated as a managed deployable. This includes a managed one-shot Job; it does not turn a human command or approval act into a workload. Human access, credential patterns, broker actions, one-off operational acts, and infrastructure resources that are not workloads retain their native actor, lane, activity, or resource identity.</li></ol>
<p>A running deployable that predates rapp extraction is migration debt. Until an authoritative declaration claims it, workload-based controls report it as <code>unknown</code>; they do not infer a rapp from its repository, namespace, path, labels, or apparent owner. A subject explicitly established as not being a workload is <code>not-applicable</code>. <code>unknown</code> and <code>not-applicable</code> are different outcomes and omission must not collapse them.</p>
<p>Railiance Master remains the sole owner of the normative rapp vocabulary and schemas. Consumer catalogs may store explicit references and integration owners may resolve them, but neither creates a parallel declaration surface or copies rapp metadata as another source of truth.</p>
<p>The detailed shapes, including the single normative form of the rollout, smoke, and rollback contracts, live in the schema files and <code>schemas/README.md</code>.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Drift across family declarations fails in <code>tools/validate-family-declarations.py</code> instead of accumulating in prose.</li><li><code>railiance-platform</code> <code>RAILIANCE-WP-0015-T02</code> can converge <code>rapp-openbao</code> and <code>rapp-postgres</code> onto one shape. Migration belongs to the owning repos; this ADR does not move any declaration.</li><li><code>reef-railiance</code> must stop treating <code>bound_rapps: [rapp-qonto]</code> as source of truth. The list is already stale.</li><li>Three further <code>rapp-*</code> repos (<code>rapp-secrets-engine</code>, <code>rapp-tenant-engine</code>, <code>rapp-user-engine</code>) carry the family prefix and no declaration. They are visible to the validator as undeclared and must be declared, renamed, or retired by their owners.</li><li>Operational and tooling deployables are not exempt from family coverage. Existing pre-rapp runtimes may continue during migration, but their workload identity remains visibly <code>unknown</code> to controls until declared.</li><li>Runtime inventory is still required to prove universal coverage. Repository discovery alone cannot establish that every running unit has exactly one authoritative rapp.</li><li>Calling the validator from <code>fix-consistency</code> still waits on <code>the-custodian</code> admitting the family prefixes into the classification standard. That sequencing is not this repo's.</li></ul>
</section><footer><span>RMASTER-ADR-0007 · accepted-2 · accepted</span><span>railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 51747ca793d830c42bd86ce0ca43e34db9e8a1c1</span></footer></main></div></div></html>

218
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0008.html Normal file
View file

@ -0,0 +1,218 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="5ffd7d1b40d56249f490a318e728047fd3517c4c">
<meta name="policy-source-digest" content="bd97ec8ee663bb416fae53c8cfe29c7066e4fd3a51a5bc364895297e6eb994b7">
<title>Private-by-default Exposure</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0008</span> <span class="stat">accepted · accepted-2</span> <span>railiance-master</span> <span>reviewed 2026-08-29</span><span>generated from canonical source — do not edit</span></div><h1>Private-by-default Exposure</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><p>Date: 2026-08-15 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>ADR-0006 says a topology binding is not permission to run a workload in production. It does not say who may reach a listener. A working deploy, a <code>hosts_rail</code> / <code>binds_rapp</code> line, or an Ingress object has been enough to put something on the public internet.</p>
<p>Family readiness vocabularies are deliberately not unified (<code>schemas/README.md</code>). Reef <code>lifecycle_state</code> has no <code>production-approved</code>. Rapp <code>readiness_state</code> has no <code>production-approved</code> either. Exposure cannot be derived from those enums.</p>
<p>Live public surfaces already exist on <code>reef-railiance</code>. They must be named as grants, not silently grandfathered and not taken down by this decision.</p>
<p>Ratified 2026-08-15 under <code>RMASTER-WP-0023-T01</code>.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>New reefs, rails, and rapps are unreachable from the public internet until they are production-safe <strong>and</strong> explicitly granted. The field name is <code>exposure</code>. Missing field means <code>private</code>.</p>
<div class="scroll"><table><thead><tr><th>Posture</th><th>Meaning</th><th>Who may reach it</th></tr></thead><tbody><tr><td><code>private</code></td><td>No extra listener we control</td><td>in-cluster DNS, same-reef services</td></tr><tr><td><code>operator</code></td><td>Same listener as <code>private</code>, plus a named ops-bridge / SSH tunnel</td><td>operator and approved agents</td></tr><tr><td><code>public</code></td><td>Internet listener we publish</td><td>anyone the Ingress / DNS / UFW surface allows</td></tr></tbody></table></div>
<p><code>operator</code> is an access annotation, not a different packet posture. It does not open a host port or a public Ingress.</p>
<p>Default for a new reef, rail, or rapp is <code>private</code>. Use <code>operator</code> only for a named admin or API surface that must be reachable before admission (k3s API, OpenBao UI). Do not prefer <code>operator</code> as the debug default.</p>
<p><code>public</code> requires both an ADR-0006 binding of <code>production-approved</code> and an explicit grant. A deploy, a binding line, or an Ingress object is not a grant. Do not key <code>public</code> off rapp <code>readiness_state</code> and do not add <code>production-approved</code> to the rapp enum for this purpose.</p>
<p>A reef public surface (host port or public DNS we publish) is a <strong>substrate grant</strong>, not reef <code>lifecycle_state</code>. A rapp cannot be <code>public</code> on a reef that has not granted a public surface. Conflicting declarations fail closed.</p>
<p>The shared vocabulary is one enum. It is not one schema shape and not one admission check:</p>
<div class="scroll"><table><thead><tr><th>Family</th><th>What the field means</th><th>What makes <code>public</code> legal</th></tr></thead><tbody><tr><td><code>rapp-*</code></td><td>intended consumer-facing listener</td><td>binding <code>production-approved</code> + grant</td></tr><tr><td><code>rail-*</code></td><td>which listener classes the rail may emit</td><td>rail may emit public Ingress only when a bound grant exists</td></tr><tr><td><code>reef-*</code></td><td>host ports and public DNS we publish</td><td>substrate grant</td></tr></tbody></table></div>
<p>A grant is accepted residual risk, not a self-serve wish. Required fields: hostname or port, reason, <code>approved_on</code>, residual-risk owner.</p>
<p><code>6443</code> / the k3s API is not a grantable public surface.</p>
<p>This contract covers listeners we control: host ports, Ingress, Service types, and public DNS we publish. Provider-native internet APIs (Scaleway S3 and other provider-delegated endpoints) are outside this enum.</p>
<p>Ops-bridge is the normal path to a shielded thing.</p>
<p>The detailed per-family reading lives in <a href="../exposure-posture-contract.md"><code>docs/exposure-posture-contract.md</code></a>.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>ADR-0006 still answers "may this binding run in production?" This ADR answers "who may reach the listener?" Do not merge the axes.</li><li>Neither question is an authorization decision. Whether an actor may perform an action is <code>access-engine</code> (<a href="ADR-0009-netkingdom-security-layer-interaction.md"><code>ADR-0009</code></a>). <code>exposure: public</code> MUST NOT be read as permission to act.</li><li>The three readiness enums stay distinct on purpose.</li><li>Family schemas grow an additive <code>exposure</code> field. Rapp <code>data_classification: public</code> is a different field and must not be reused as the posture name.</li><li>Implementation stays in the owning repos. This ADR does not install NetworkPolicy, UFW, Ingress, or tunnels.</li><li>Existing public surfaces on <code>reef-railiance</code> remain up until named as grants. This ADR is not a shutdown plan.</li><li>CoulombCore host inventory and Q7 / Goss reaction stay outside this decision.</li></ul>
</section><footer><span>RMASTER-ADR-0008 · accepted-2 · accepted</span><span>railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</span></footer></main></div></div></html>

214
docs/evidence/2026-10-11-served-publication-history/pages/RMASTER-ADR-0009.html Normal file
View file

@ -0,0 +1,214 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="51747ca793d830c42bd86ce0ca43e34db9e8a1c1">
<meta name="policy-source-digest" content="c2f81c9718715fc08ea7a2e3021d0d3159958ace23b60a16430020637b9f57f2">
<title>NetKingdom Security-Layer Interaction Boundary</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0009</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-08-29</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Security-Layer Interaction Boundary</h1><p class="sub">Source: <code>railiance-master · docs/adr/ADR-0009-netkingdom-security-layer-interaction.md · 51747ca793d830c42bd86ce0ca43e34db9e8a1c1</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#notes"><span class="n">·</span>Notes</a></li></ol></nav><main><p>Date: 2026-08-29 Status: Accepted</p>
<section id="context"><h2>Context</h2>
<p>NetKingdom Security Layer Model v0.7 is accepted. Section 20 restates Railiance workload-operation definitions owned by this repository and states consumption rules every Railiance consumer of NetKingdom security owes. Companion v0.2 §9 is the operative form of the same boundary.</p>
<p>This repository had declared the four axes and the workload coverage rule in its own voice, but had no machine-readable layer declaration, no recorded assent to §20, and no framework contract that bound rails, rapps, and reefs to those consumption rules. Admission (ADR-0006) and exposure (ADR-0008) were live and were not demarcated from authorization.</p>
<p>Statute §20.4: an interaction boundary between two frameworks is owned by neither alone. Changes to §20 require this repository's assent for the axis definitions and <code>glas-harness</code> assent for the session and tool-policy seam.</p>
<p>Ratified 2026-08-29 under <code>RMASTER-WP-0026</code>.</p>
</section>
<section id="decision"><h2>Decision</h2>
<ol><li><strong>This repository is Taxonomy of Railiance workload operations.</strong> The machine-readable declaration is <a href="../../layer.yaml"><code>layer.yaml</code></a>. It is not a NetKingdom §4 catalog row. It is not PEP-shaped. It holds no Tooling-layer client.</li></ol>
<ol><li><strong>Statute §20.1 restates our definitions and does not author them.</strong> Workload, the four axes, and the rule that <code>rein-*</code> is not a fifth axis remain this repository's. NetKingdom may cite them; it may not redefine them without our assent.</li></ol>
<ol><li><strong>Statute §20.2 is the consumption constitution</strong> for every Railiance consumer of NetKingdom security. The detailed contract is <a href="../netkingdom-security-consumption-contract.md"><code>docs/netkingdom-security-consumption-contract.md</code></a>.</li></ol>
<ol><li><strong>Statute §20.3 remains unset.</strong> This repository will not imply a mapping of rails, rapps, reefs, or ownership onto Taxonomy, Tooling, Engine, or Staff. The five questions are tracked, unanswered, in <a href="../netkingdom-axis-layer-open-questions.md"><code>docs/netkingdom-axis-layer-open-questions.md</code></a>.</li></ol>
<ol><li><strong>Admission, exposure, and authorization stay three questions.</strong> ADR-0006 answers whether a binding may run in production. ADR-0008 answers who may reach a listener we control. <code>access-engine</code> answers whether an actor may perform an action. <code>production-approved</code> and <code>exposure: public</code> are not authorization decisions.</li></ol>
<ol><li><strong>Changes to this boundary</strong> require this repository's assent for the axis definitions. Changes that touch the glas-harness seam require <code>glas-harness</code> assent as well.</li></ol>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Rails, rapps, and reefs consume <code>access-engine</code>, <code>approval-engine</code>, <code>secrets-engine</code>, and <code>audit-core</code>. They do not grow local substitutes.</li><li>This repository does not host a PDP, an approval store, a credential plane, an evidence archive, or an actuation surface.</li><li>PEP stance maps belong in the repositories that cause protected side effects, inventoried in statute §13.1, not here.</li><li>Observation-in-production and automatic containment remain estate-wide zeros. Framework plans must not assume they exist.</li><li><code>gate-house</code> can cite this ADR as this repository's own-voice declaration and §20 assent, rather than a review note about us.</li></ul>
</section>
<section id="notes"><h2>Notes</h2>
<p>This ADR does not amend ADR-0001 through ADR-0008. It adds the security consumption axis those records did not have to name.</p>
</section><footer><span>RMASTER-ADR-0009 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0009-netkingdom-security-layer-interaction.md · 51747ca793d830c42bd86ce0ca43e34db9e8a1c1</span></footer></main></div></div></html>

209
docs/evidence/2026-10-11-served-publication-history/pages/RPLAT-ADR-0001.html Normal file
View file

@ -0,0 +1,209 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="56d516e10cdad6691f254ec9cb11f11ea364f7de">
<meta name="policy-source-digest" content="63697581401b53a8437835c2bb8b40f8054cc40d0bc7a2972f83a4a10377f6ba">
<title>ADR-0001 — S3 owns platform services, not the substrate beneath them</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RPLAT-ADR-0001</span> <span class="stat">accepted · 1.0</span> <span>railiance-platform</span> <span>reviewed 2026-08-17</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0001 — S3 owns platform services, not the substrate beneath them</h1><p class="sub">Source: <code>railiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</code></p><p class="sub">Review due: 2027-02-17</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li></ol></nav><main><section id="context"><h2>Context</h2>
<p><code>railiance-platform</code> is S3 on the OAS Stack: the shared services several applications depend on — PostgreSQL, secrets, cache, object storage. The layers around it are S1 <code>railiance-infra</code> (OS and host concerns), S2 <code>railiance-cluster</code> (Kubernetes runtime, ingress), S4 <code>railiance-enablement</code> (tooling and CI), S5 <code>railiance-apps</code> (workloads).</p>
<p>This boundary has been stated in <code>SCOPE.md</code> and in ADR-003 of <code>railiance-infra</code> since the five-repo split, and it has been tested twice. <code>RAIL-PL-WP-0001</code> existed to extract platform services <em>out</em> of S2 subcharts. On 2026-08-17 <code>POLICY-NEXUS-WP-0001</code> assigned this repo "the substrate — DNS, TLS, ingress, hosting" for <code>policy.coulomb.social</code>, which would move the boundary back the other way.</p>
<p>The pressure is predictable and will recur: S3 is the layer that looks like it owns infrastructure, because it owns things that feel infrastructural. Recording the rule as an ADR rather than as a line in <code>SCOPE.md</code> gives future requests something to be answered against.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>**S3 owns shared platform <em>services</em> and the interfaces consumers bind to. It does not own DNS, TLS, Kubernetes ingress, host configuration, or CI.** A request that would place any of those here is redirected to S1, S2 or S4 rather than absorbed, even when this repo is the closest available owner and even when absorbing it would be faster.</p>
<p>Where S3 has a genuine part in such a request — an object-storage bucket, a credential lane, a database — it supplies that part and co-signs the rest. It does not become the owner of the whole by being the first repo asked.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>POLICY-NEXUS-WP-0001</code> T04 needs splitting: ingress and TLS to S2, DNS to S1 or the reef boundary, storage and credentials here. Routed as <code>RPF-WP-0018</code> finding F1.</li><li>A request this repo declines does not thereby become nobody's. Declining carries an obligation to name the owner, which is why F1 names two.</li><li>The rule cuts against this repo's convenience in the common case. That is what makes it a rule rather than a preference.</li><li><code>rapp-openbao</code> and <code>rapp-postgres</code> are the same principle applied inward: the deployable package left, custody and policy stayed. See <code>docs/rapp-openbao-boundary.md</code> and <code>docs/rapp-postgres-boundary.md</code>.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives considered</h2>
<p><strong>Accept the substrate assignment as written.</strong> Fastest, and the requester had already resolved it with the operator. Rejected: it re-imports the coupling <code>RAIL-PL-WP-0001</code> spent a workplan removing, and a boundary that yields to whoever asks most recently is not a boundary.</p>
<p><strong>Own ingress for S3-adjacent services only.</strong> A narrower version, and it fails on the first argument about what counts as adjacent. The line has to be drawn where it can be checked.</p>
</section><footer><span>RPLAT-ADR-0001 · 1.0 · accepted</span><span>railiance-platform · docs/adr/ADR-0001-s3-platform-service-boundary.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</span></footer></main></div></div></html>

212
docs/evidence/2026-10-11-served-publication-history/pages/RPLAT-ADR-0002.html Normal file
View file

@ -0,0 +1,212 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="56d516e10cdad6691f254ec9cb11f11ea364f7de">
<meta name="policy-source-digest" content="cfc0ad202c2eeeefd963127ff1defa127c715c001ecc684ab8759733bd8fb9f8">
<title>ADR-0002 — S3 owns the placement rule; the package repo owns the number</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RPLAT-ADR-0002</span> <span class="stat">proposed · 1.0</span> <span>railiance-platform</span> <span>reviewed 2026-08-17</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0002 — S3 owns the placement rule; the package repo owns the number</h1><p class="sub">Source: <code>railiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</code></p><p class="sub">Review due: 2027-02-17</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li></ol></nav><main><section id="context"><h2>Context</h2>
<p>An earlier draft of <code>net-kingdom/canon/standards/tenancy-posture_v0.1.md</code> §8.2 proposed that database placement policy — dedicated versus shared, and when that changes — be owned by <code>railiance-platform</code>, co-signed by <code>adaptive-pricing</code>. <code>tenant-engine</code> raised the same gap independently on 2026-08-16: both patterns are live on railiance01, neither is written down, and each new service copies whichever neighbour it looked at.</p>
<p>The complication is that this repo no longer holds the specs. <code>RAILIANCE-WP-0012</code> and <code>RAILIANCE-WP-0015</code> moved the deployable surface to the <code>rapp-*</code> repos. <code>platform-pg</code>'s <code>instances</code>, <code>max_connections</code>, memory limit and retention are <code>rapp-postgres</code>'s cluster CR. Tenancy Posture §19.8 nonetheless asks <em>this repo</em> for <code>platform-pg</code>'s declared maximum size — a question one hop from where its answer lives.</p>
<p>Accepting ownership without stating this would produce either an answer we cannot substantiate or a quiet non-answer.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Accept placement ownership, split along rule and number.</strong></p>
<p><em>This repo owns the rule:</em> the default placement level, what overrides it, who is accountable for each workload's placement, that a shared cluster must publish a ceiling and an overflow target before its third consumer, that retention has a floor and a ceiling, and that a consumer's erasure horizon on shared substrate is disclosed rather than inherited silently.</p>
<p><em>The package repo owns the number:</em> what the ceiling actually is, which resource binds first, what the retention values are, and the validator that enforces them where the CR lives.</p>
<p><strong>Placement ownership per workload sits with the consuming repo; this repo co-signs.</strong> The consumer knows its latency requirement, erasure horizon and compliance position; S3 knows the substrate. A placement change needs both. Putting the decision solely here would recreate the problem §8.2 exists to avoid — an operations-shaped repo holding a commercial decision alone.</p>
<p><code>adaptive-pricing</code> declined the standing co-signature on 2026-08-17. The replacement is binding and machine-reconcilable: it publishes typed tier minimums; this policy validates placement against them. Ownership stays here.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>docs/placement-policy.md</code> is the operative document; this ADR is the decision behind it.</li><li>§19.8 is answered for <code>platform-pg</code> by <code>rapp-postgres</code> ADR-0004: four consumers, with <code>platform-pg-2</code> named as the still-absent overflow target. Rule P-4.1 still requires <code>apps-pg</code> to declare its own ceiling before its third consumer.</li><li>This repo owes <code>apps-pg</code>'s ceiling under its own rule. A policy whose author is exempt is not a policy.</li><li>§8.1 requires triggers to be <em>monitored</em>. This repo has no monitoring plane, so the connection-and-memory-ceiling trigger is recorded <code>unmonitored</code> pending <code>railiance-telemetry</code>. Declaring a ceiling is a partial substitute — a written threshold is checkable by a human at provisioning, which beats a limit discovered by an OOM kill.</li><li><code>adaptive-pricing</code>'s decline is recorded as single policy ownership plus a mandatory typed constraint join, not as an absent signature.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives considered</h2>
<p><strong>Decline ownership; route it to <code>rapp-postgres</code>.</strong> They hold the specs and the operational knowledge. Rejected: placement is a cross-cluster question and <code>rapp-postgres</code> owns one package. A policy owned by one substrate's operator cannot govern movement between substrates.</p>
<p><strong>Accept whole, including the numbers.</strong> Rejected: it would either re-import the deployable surface this repo deliberately gave up, or produce numbers restated here that drift from the CR — a second source of truth for exactly the values a consumer must be able to trust.</p>
</section><footer><span>RPLAT-ADR-0002 · 1.0 · proposed</span><span>railiance-platform · docs/adr/ADR-0002-placement-policy-ownership.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</span></footer></main></div></div></html>

211
docs/evidence/2026-10-11-served-publication-history/pages/RPLAT-ADR-0003.html Normal file
View file

@ -0,0 +1,211 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="56d516e10cdad6691f254ec9cb11f11ea364f7de">
<meta name="policy-source-digest" content="9b12ab6aa0e6f9eba03465782c35d6ff4683b682191599e38f4f9614cde9fa1b">
<title>ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>RPLAT-ADR-0003</span> <span class="stat">accepted · 1.0</span> <span>railiance-platform</span> <span>reviewed 2026-08-17</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0003 — Decisions that bind others live in docs/adr, not only in the State Hub</h1><p class="sub">Source: <code>railiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</code></p><p class="sub">Review due: 2027-02-17</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li></ol></nav><main><section id="context"><h2>Context</h2>
<p>This repo recorded decisions with the State Hub's <code>record_decision()</code> and wrote governing content as prose in <code>docs/</code> — 24 files on 2026-08-17, none carrying a status, owner, revision or review date. It held no ADRs at all.</p>
<p>Two things made that a defect rather than a style.</p>
<p><strong>The hub is a read model.</strong> The estate's standing rule is that local files are the source of truth and the hub reflects them. A decision that exists only as a hub record inverts that for the one class of content where it matters most.</p>
<p><strong><code>policy-nexus</code> publishes canon and ADRs only</strong>, globbing <code>docs/adr/*.md</code> from each repo. A repo with no ADRs is invisible to the estate's publication surface no matter how much governing content it holds. This repo owns S3 boundary rules, the credential-lane model and the consumption-mode gate — all binding on other repos, all unpublishable.</p>
<p>The gap was structural, not an oversight: nothing in the session protocol ever told anyone to write an ADR here.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>A decision that binds anyone outside this repo is recorded as an ADR in <code>docs/adr/</code>, with the frontmatter in <code>docs/adr/README.md</code>, before or alongside any hub record.</strong> The hub record points at the ADR; it does not replace it.</p>
<p>Runbooks and procedures stay as prose in <code>docs/</code> and stay unpublished. The test is not importance — several runbooks are critical — but whether the document <em>decides</em> something for someone else.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li><code>docs/adr/</code> exists, with a convention, a template and this repo's first three ADRs.</li><li>Existing prose is not converted wholesale. Content is promoted when it is next touched, or when a consumer needs to cite it.</li><li><code>last_reviewed</code> and <code>review_interval</code> are mandatory here, which is stricter than the estate norm — of 69 ADRs across 19 repos on 2026-08-17, 21 had YAML frontmatter and 2 had any notion of a review date. <code>POLICY-NEXUS-WP-0001</code> T05 cannot compute staleness without those fields and must not invent them, since inventing them would make the publication a second source of truth, which is that workplan's own top risk. Routed as <code>RPF-WP-0018</code> finding F5.</li><li>Session protocol guidance should follow, so the next agent writes an ADR without being told. Not done in this ADR.</li></ul>
</section>
<section id="alternatives-considered"><h2>Alternatives considered</h2>
<p><strong>Keep decisions in the hub and have <code>policy-nexus</code> read it.</strong> Rejected on both sides: it would make a read model authoritative, and it would give the publication surface a source that no repo can diff or review.</p>
<p><strong>Add frontmatter to all 24 existing <code>docs/</code> files.</strong> Rejected. Most are runbooks that should not be published, and stamping them with a status would assert a decision that was never made.</p>
</section><footer><span>RPLAT-ADR-0003 · 1.0 · accepted</span><span>railiance-platform · docs/adr/ADR-0003-decisions-live-in-the-repo.md · 56d516e10cdad6691f254ec9cb11f11ea364f7de</span></footer></main></div></div></html>

222
docs/evidence/2026-10-11-served-publication-history/pages/canon-autonomy-lanes.html Normal file
View file

@ -0,0 +1,222 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4b951be3947f9457cc091a7d359d9232646b4c93">
<meta name="policy-source-digest" content="106cb0c99f73983199c9f1d8491143aa2a2eb41ee450a02ec7968d3763f30399">
<title>Autonomy Lanes (Fleet) v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>canon-autonomy-lanes</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Autonomy Lanes (Fleet) v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/autonomy-lanes_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#the-rule"><span class="n">·</span>The rule</a></li><li><a href="#lanes"><span class="n">·</span>Lanes</a></li><li><a href="#lane-as-a-spine-field"><span class="n">·</span>Lane as a spine field</a></li><li><a href="#approval-packages-yellow-and-above"><span class="n">·</span>Approval packages (yellow and above)</a></li><li><a href="#human-attention-is-a-wip-limited-workstation"><span class="n">·</span>Human attention is a WIP-limited workstation</a></li><li><a href="#raising-autonomy"><span class="n">·</span>Raising autonomy</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><div class="rule-quote"><p>Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Promotes the binky-control AutonomyPolicy lane model to fleet canon, unchanged in substance. binky-control's <code>AutonomyPolicy.md</code> remains the company-level policy instance; this standard makes the lane vocabulary and enforcement rules fleet-wide.</p></div>
<section id="the-rule"><h2>The rule</h2>
<div class="rule-quote"><p>If the responsible human is unavailable, the system must either continue safely, prepare the next decision, or explicitly defer with evidence. It must not silently idle.</p></div>
<p>Valid states: <code>proceeding</code> | <code>prepared for review</code> | <code>deferred by policy</code>. Invalid state: <code>waiting because unsure</code>. Uncertainty triggers research, comparison, preparation, or risk classification — not paralysis. "Ask the human" is never the default.</p>
</section>
<section id="lanes"><h2>Lanes</h2>
<div class="scroll"><table><thead><tr><th>Lane</th><th>Name</th><th>Agent may</th><th>Human involvement</th></tr></thead><tbody><tr><td><strong>green</strong></td><td>Safe autonomous</td><td>research, summarize, classify, draft, organize, test, prepare</td><td>none (human-on-the-loop via logs)</td></tr><tr><td><strong>blue</strong></td><td>Reversible execution</td><td>internal docs, backlog updates, local scripts, reports, local commits</td><td>none, but logged</td></tr><tr><td><strong>yellow</strong></td><td>Deferred approval</td><td>prepare external emails, invoices, offers, releases, payments</td><td>async approval via decision records</td></tr><tr><td><strong>orange</strong></td><td>Time-window approval</td><td>customer/legal/accounting/banking actions needing business hours</td><td>engagement records, batched into command days</td></tr><tr><td><strong>red</strong></td><td>Human-only</td><td>signing, strategic commitments, bank/credential changes, sensitive legal/HR/security</td><td>always; agents prepare packages only</td></tr></tbody></table></div>
<p>Optimization target: <strong>maximize green+blue throughput, queue yellow, batch orange, protect red from automation.</strong> Risk-tiered gating (in-the-loop for irreversible actions, on-the-loop for recoverable ones) is the only oversight pattern that scales.</p>
</section>
<section id="lane-as-a-spine-field"><h2>Lane as a spine field</h2>
<p><code>lane</code> is a <strong>mandatory field on every work record</strong> (see <code>work-record-types_v0.1.md</code>) and on every agent instance manifest. The chain is closed end-to-end:</p>
<pre>work record.lane → view routing (autopilot / decision / engagement)
→ harness tool profile (enforced allow-list)
→ ops-warden credential lane (catalog access)</pre>
<p>Declaring a lane an item does not hold is a policy violation the harness must catch (tool profile refuses the run).</p>
</section>
<section id="approval-packages-yellow-and-above"><h2>Approval packages (yellow and above)</h2>
<p>An agent hitting a lane boundary prepares a complete decision package, never a bare question: recommended action, reason, evidence links, risk level, reversibility, deadline (<code>needed_by</code>), attention cost, fallback if no response, options.</p>
</section>
<section id="human-attention-is-a-wip-limited-workstation"><h2>Human attention is a WIP-limited workstation</h2>
<p>The responsible human's capacity is modeled like any lane capacity: attention budget (minutes/day, max decisions/day, max deep topics/day) and availability as first-class state (<code>available | evening_window | unavailable | office_hour_day</code>), with an explicit escalation allow-list when unavailable (critical security incident, payment failure, legal deadline). Yellow routes to the decision view, orange to the engagement view, both subject to that capacity.</p>
<p><strong>Time-boxing is hub-owned:</strong> <code>needed_by</code> / <code>fallback_if_no_response</code> windows are watched by the hub → NATS → activity-core; a lapsed window raises the escalation or executes the declared fallback — never a human re-reading a file.</p>
</section>
<section id="raising-autonomy"><h2>Raising autonomy</h2>
<p>Autonomy per area is raised only after the system proves reliable there, by explicit human decision recorded as a decision work record. Lane assignments are auditable history; lowering a lane needs no approval.</p>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>binky-control/AutonomyPolicy.md</code> (origin instance)</li><li><code>canon/standards/work-record-types_v0.1.md</code></li><li><code>research/2026-07-19-work-orchestration-best-practices.md</code> §2</li></ul>
</section><footer><span>canon-autonomy-lanes · accepted-1 · accepted</span><span>the-custodian · canon/standards/autonomy-lanes_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</span></footer></main></div></div></html>

273
docs/evidence/2026-10-11-served-publication-history/pages/canon-contrib-convention.html Normal file
View file

@ -0,0 +1,273 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4b951be3947f9457cc091a7d359d9232646b4c93">
<meta name="policy-source-digest" content="6dfc1d7b2b82ab18228a84660c1c7dff607aad1d9da37ac12084cdd2ab8ae112">
<title>Contribution Convention v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>canon-contrib-convention</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Contribution Convention v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/contribution-convention_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#artifact-types"><span class="n">·</span>Artifact Types</a></li><li><a href="#directory-layout"><span class="n">·</span>Directory Layout</a></li><li><a href="#frontmatter-schema"><span class="n">·</span>Frontmatter Schema</a></li><li><a href="#id-schemes"><span class="n">·</span>ID Schemes</a></li><li><a href="#status-lifecycle"><span class="n">·</span>Status Lifecycle</a></li><li><a href="#relationship-to-state-hub"><span class="n">·</span>Relationship to State Hub</a></li></ol></nav><main><section id="purpose"><h2>Purpose</h2>
<p>This document defines the canonical convention for tracking upstream contributions across all custodian-ecosystem repositories. A <em>contribution</em> is any intentional engagement with an external upstream project: a bug report, feature request, extension-point proposal, or pull request.</p>
<p>Contributions are tracked as Markdown artifacts with typed YAML frontmatter, committed to the repository that authors them, and indexed in the State Hub DB. This enables the Custodian to maintain a full audit trail of all upstream engagement across all six project domains.</p>
</section>
<section id="artifact-types"><h2>Artifact Types</h2>
<div class="scroll"><table><thead><tr><th>Code</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>br</code></td><td>Bug Report</td><td>A defect reported to an upstream project</td></tr><tr><td><code>fr</code></td><td>Feature Request</td><td>A capability requested from an upstream project</td></tr><tr><td><code>ep</code></td><td>Extension-Point Proposal</td><td>A proposed extension point in an upstream project</td></tr><tr><td><code>upr</code></td><td>Upstream PR</td><td>A pull request submitted or planned for upstream</td></tr></tbody></table></div>
</section>
<section id="directory-layout"><h2>Directory Layout</h2>
<pre>&lt;repo-root&gt;/
contrib/
bug-reports/ # BR artifacts
feature-requests/ # FR artifacts
extension-points/ # EP artifacts
upstream-prs/ # UPR artifacts</pre>
<p>Each artifact file follows the naming pattern:</p>
<pre>&lt;YYYY-MM-DD&gt;--&lt;org&gt;--&lt;repo&gt;--&lt;slug&gt;.md</pre>
<p>Examples:</p>
<ul><li><code>contrib/bug-reports/2026-03-01--observablehq--framework--plot-tooltip-flicker.md</code></li><li><code>contrib/upstream-prs/2026-02-26--observablehq--framework--toc-sidebar-inject.md</code></li><li><code>contrib/extension-points/EP-CUST-002--anthropic--claude-code--hook-on-tool-result.md</code></li></ul>
</section>
<section id="frontmatter-schema"><h2>Frontmatter Schema</h2>
<p>All contribution artifacts share a common base frontmatter:</p>
<pre>---
id: &lt;type&gt;-&lt;YYYY-MM-DD&gt;--&lt;org&gt;--&lt;repo&gt;--&lt;slug&gt; # unique string ID
type: br | fr | ep | upr # required
target_org: &lt;github-org-or-owner&gt; # required
target_repo: &lt;repository-name&gt; # required
title: &quot;Human-readable title&quot; # required
status: draft | submitted | acknowledged | accepted | rejected | merged | withdrawn
domain: infotech | agents | communication | ... # current sector domain; see Repo Classification Standard §6
related_workstream: &lt;workstream-slug&gt; # optional
state_hub_contribution_id: &lt;uuid&gt; # set once registered in State Hub
created: &quot;YYYY-MM-DD&quot;
updated: &quot;YYYY-MM-DD&quot;
---</pre>
<h3>BR — Bug Report (additional fields)</h3>
<pre>upstream_version: &quot;1.2.3&quot; # version where bug was observed
reproduction_steps: |
1. …
2. …
expected: &quot;What should happen&quot;
actual: &quot;What actually happens&quot;
workaround: &quot;Any known workaround&quot; # optional
upstream_issue_url: &quot;https://…&quot; # optional — link once filed</pre>
<h3>FR — Feature Request (additional fields)</h3>
<pre>motivation: &quot;Why this feature is needed&quot;
proposed_api: |
# Sketch of the proposed interface
alternatives: &quot;What we do instead today&quot;
upstream_issue_url: &quot;https://…&quot; # optional</pre>
<h3>EP — Extension-Point Proposal (additional fields)</h3>
<pre>ep_id: EP-&lt;DOMAIN&gt;-NNN # e.g. EP-RAIL-007
location: &quot;src/file.ts:42&quot; # file:line in upstream where hook would live
proposed_interface: |
# Interface or callback signature sketch
rationale: &quot;Why this extension point is valuable&quot;
upstream_issue_url: &quot;https://…&quot; # optional</pre>
<h3>UPR — Upstream PR (additional fields)</h3>
<pre>local_component_path: &quot;relative/path/in/this/repo&quot;
target_upstream_file: &quot;path/in/upstream/repo&quot;
upstream_pr_url: &quot;https://…&quot; # set once submitted
draft_pr_body: |
## Summary
…
## Motivation
…</pre>
</section>
<section id="id-schemes"><h2>ID Schemes</h2>
<ul><li><strong>BR / FR / UPR</strong>: <code>&lt;type&gt;-&lt;YYYY-MM-DD&gt;--&lt;org&gt;--&lt;repo&gt;--&lt;slug&gt;</code> — date-prefixed slug</li><li><strong>EP</strong>: <code>EP-&lt;DOMAIN&gt;-NNN</code> where <code>&lt;DOMAIN&gt;</code> is uppercase (CUST, RAIL, MARK, etc.) and <code>NNN</code> is a zero-padded three-digit sequence per domain (EP-CUST-001, EP-CUST-002, …). This scheme is an extension of the Railiance EP convention defined in the staged-promotion-lifecycle workstream; this canon document is the authoritative master spec.</li></ul>
</section>
<section id="status-lifecycle"><h2>Status Lifecycle</h2>
<pre>draft → submitted → acknowledged → accepted → merged
↘ ↘
rejected withdrawn</pre>
<ul><li><code>draft</code>: artifact created locally, not yet sent upstream</li><li><code>submitted</code>: issue filed or PR opened upstream</li><li><code>acknowledged</code>: upstream team has responded</li><li><code>accepted</code>: upstream has agreed to the proposal</li><li><code>rejected</code>: upstream has declined</li><li><code>merged</code>: PR merged / fix released</li><li><code>withdrawn</code>: we decided not to pursue</li></ul>
</section>
<section id="relationship-to-state-hub"><h2>Relationship to State Hub</h2>
<p>Once an artifact is registered via <code>register_contribution()</code> MCP tool or <code>POST /contributions/</code> API, the State Hub assigns a UUID and returns it. That UUID is written back into <code>state_hub_contribution_id</code> in the frontmatter.</p>
<p>The State Hub is a <strong>read/cache layer</strong> — the Markdown file is always the authoritative source of truth. If the DB is reset, contributions can be re-ingested from the files.</p>
</section><footer><span>canon-contrib-convention · accepted-1 · accepted</span><span>the-custodian · canon/standards/contribution-convention_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</span></footer></main></div></div></html>

279
docs/evidence/2026-10-11-served-publication-history/pages/canon-project-repository-flavor.html Normal file
View file

@ -0,0 +1,279 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4b951be3947f9457cc091a7d359d9232646b4c93">
<meta name="policy-source-digest" content="61889b2f18a82a08b66ef90d758efe5c028a4f52aced1721a23e69c6f24a8224">
<title>Project Repository Flavor (prj-) v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>canon-project-repository-flavor</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Project Repository Flavor (prj-) v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/project-repository-flavor_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#when-to-use-a-project-repository"><span class="n">·</span>When to use a project repository</a></li><li><a href="#naming"><span class="n">·</span>Naming</a></li><li><a href="#authority-boundary"><span class="n">·</span>Authority boundary</a></li><li><a href="#required-files"><span class="n">·</span>Required files</a></li><li><a href="#lifecycle"><span class="n">·</span>Lifecycle</a></li><li><a href="#residuals-before-completion"><span class="n">·</span>Residuals before completion</a></li><li><a href="#completion-record"><span class="n">·</span>Completion record</a></li><li><a href="#archive-procedure"><span class="n">·</span>Archive procedure</a></li><li><a href="#workplan-and-agent-conventions"><span class="n">·</span>Workplan and agent conventions</a></li><li><a href="#minimal-layout-example"><span class="n">·</span>Minimal layout example</a></li><li><a href="#reference-instance"><span class="n">·</span>Reference instance</a></li><li><a href="#conformance-checklist"><span class="n">·</span>Conformance checklist</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="purpose"><h2>Purpose</h2>
<p>Define the durable <strong>project repository</strong> flavor used for complex cross-repository efforts: naming, required files, authority boundary, lifecycle, residual handoff, and archive procedure.</p>
<p>This standard implements and completes <strong>ADR-005</strong> (<em>Cross-Repo Workplans Live in Dedicated Project Repos</em>). It does <strong>not</strong> replace the Repo Classification Standard: project repositories still use <code>category: project</code> in <code>.repo-classification.yaml</code>.</p>
</section>
<section id="when-to-use-a-project-repository"><h2>When to use a project repository</h2>
<p>Create a project repository when <strong>all</strong> of the following hold:</p>
<ol><li>The work coordinates change across <strong>two or more</strong> functional repositories.</li><li>Binding the coordination workplan to any single product/tooling repo would misrepresent ownership or pollute that repo's history.</li><li>The effort has a <strong>bounded outcome</strong> with explicit success and retirement conditions (not an open-ended product roadmap).</li></ol>
<p>Do <strong>not</strong> create a project repository for:</p>
<ul><li>single-repo workplans;</li><li>small cross-cutting fixes that fit one lead repo's workplan plus dependency links;</li><li>durable products, libraries, or services (those use <code>INTENT.md</code> and ordinary product/tooling/research categories);</li><li>long-lived domain charters (those remain under <code>the-custodian/canon/projects/</code>).</li></ul>
</section>
<section id="naming"><h2>Naming</h2>
<div class="scroll"><table><thead><tr><th>Element</th><th>Convention</th></tr></thead><tbody><tr><td>Git / local directory</td><td><code>prj-&lt;kebab-slug&gt;</code></td></tr><tr><td>Hub <code>repo</code> slug</td><td>same as directory name</td></tr><tr><td>Workplan prefix</td><td>short uppercase prefix derived from the project, ending in <code>-WP-</code> (example: <code>SHR-WP-</code> for State Hub Retirement)</td></tr><tr><td>Classification</td><td><code>category: project</code></td></tr></tbody></table></div>
<p><strong>Canonical prefix is <code>prj-</code>.</strong> ADR-005's illustrative <code>proj-</code> form is superseded for new repositories. Do not invent parallel prefixes (<code>project-</code>, <code>xrepo-</code>, …).</p>
<p>Slug rules:</p>
<ul><li>lowercase kebab-case;</li><li>outcome-oriented (<code>prj-state-hub-retirement</code>), not a random ticket id;</li><li>stable for the life of the project (rename only with an explicit migration note in <code>history/</code>).</li></ul>
</section>
<section id="authority-boundary"><h2>Authority boundary</h2>
<div class="scroll"><table><thead><tr><th>Concern</th><th>Owner</th></tr></thead><tbody><tr><td>Project goal, success gates, retirement conditions</td><td>project repo (<code>GOAL.md</code>)</td></tr><tr><td>Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidence</td><td>project repo</td></tr><tr><td>Cross-repo workplans that coordinate the effort</td><td>project repo (<code>workplans/</code>)</td></tr><tr><td>Production implementation, tests, deployables</td><td><strong>participating functional repositories</strong></td></tr><tr><td>Per-repo implementation workplans and local evidence</td><td>each functional repository</td></tr><tr><td>Durable post-project standards and ADRs</td><td>permanent homes (<code>the-custodian</code> canon, or the owning product/tooling repo)</td></tr></tbody></table></div>
<p><strong>Hard rules:</strong></p>
<ol><li>Project repositories <strong>MUST NOT</strong> host production implementation code for the systems being changed.</li><li>Project workplans <strong>link</strong> child workplans by stable ID; they <strong>MUST NOT</strong> copy or replace child task lists.</li><li>The hub remains a read/index layer; work records originate as files (ADR-001).</li><li>Results of the project live primarily in the modified functional repositories and promoted canon. The project repo is coordination + provenance.</li></ol>
</section>
<section id="required-files"><h2>Required files</h2>
<p>At registration / first meaningful commit:</p>
<div class="scroll"><table><thead><tr><th>Path</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>GOAL.md</code></td><td><strong>yes</strong></td><td>Outcome, invariants, success gates, project retirement conditions. <strong>Replaces <code>INTENT.md</code> for this flavor.</strong></td></tr><tr><td><code>SCOPE.md</code></td><td><strong>yes</strong></td><td>Project authority, participating repos, in/out of scope, work-record rule.</td></tr><tr><td><code>README.md</code></td><td><strong>yes</strong></td><td>Short entry point linking <code>GOAL.md</code>, <code>SCOPE.md</code>, genesis/history, active workplans.</td></tr><tr><td><code>AGENTS.md</code></td><td><strong>yes</strong></td><td>Agent session protocol for this project (orient → work → close; hub integration).</td></tr><tr><td><code>.repo-classification.yaml</code></td><td><strong>yes</strong></td><td><code>category: project</code> plus domain / capability tags for the <em>effort</em>.</td></tr><tr><td><code>workplans/</code></td><td><strong>yes</strong></td><td>At least one foundation workplan; prefix unique to the project.</td></tr><tr><td><code>history/</code></td><td>recommended</td><td>Genesis and significant milestones (why the project exists).</td></tr><tr><td><code>WORK-RECORDS.md</code></td><td>generated</td><td>Hub index; do not hand-edit.</td></tr><tr><td><code>.custodian-brief.md</code></td><td>generated</td><td>Offline orientation brief.</td></tr></tbody></table></div>
<h3><code>GOAL.md</code> (not <code>INTENT.md</code>)</h3>
<p>Durable product and tooling repositories explain <strong>why they exist</strong> with <code>INTENT.md</code>. Project repositories are temporary and outcome-bounded; they use <strong><code>GOAL.md</code></strong> instead.</p>
<p><code>GOAL.md</code> MUST include:</p>
<ol><li><strong>Outcome</strong> — what success looks like in one short section.</li><li><strong>Invariants</strong> — rules that must hold during the project.</li><li><strong>Success gates</strong> — checkable conditions for “goal achieved”.</li><li><strong>Project retirement</strong> — conditions under which <em>this repository</em> may be archived (usually: gates met + residuals handed off + durable decisions promoted).</li></ol>
<p>Recommended frontmatter:</p>
<pre>---
repo: prj-&lt;slug&gt;
repo_flavor: project
project_status: draft | active | completed | archived
started: &quot;YYYY-MM-DD&quot;
reviewed: &quot;YYYY-MM-DD&quot;
---</pre>
<p><strong>Anti-pattern:</strong> shipping both <code>INTENT.md</code> and <code>GOAL.md</code> in a <code>prj-</code> repo. If a durable intent emerges, promote it into a permanent repository's <code>INTENT.md</code> (or canon) and keep the project goal as the temporary outcome document.</p>
<h3>Relation to durable <code>INTENT.md</code></h3>
<div class="scroll"><table><thead><tr><th>Repository kind</th><th>Purpose document</th></tr></thead><tbody><tr><td>product / tooling / research / business / experimental</td><td><code>INTENT.md</code></td></tr><tr><td><strong>project (<code>prj-</code>)</strong></td><td><strong><code>GOAL.md</code> only</strong></td></tr></tbody></table></div>
<p>Tooling that scaffolds repositories (e.g. <code>statehub register</code>) MUST treat <code>GOAL.md</code> + <code>repo_flavor: project</code> as sufficient purpose documentation for <code>prj-</code> repos and MUST NOT require inventing an <code>INTENT.md</code> that pretends the project is a permanent product.</p>
</section>
<section id="lifecycle"><h2>Lifecycle</h2>
<pre>draft → active → completed → archived</pre>
<div class="scroll"><table><thead><tr><th>Status</th><th>Meaning</th><th>Repo / hub signals</th></tr></thead><tbody><tr><td><code>draft</code></td><td>Convention and foundation still forming; may not yet be registered</td><td><code>project_status: draft</code>; workplans often <code>proposed</code> / <code>ready</code></td></tr><tr><td><code>active</code></td><td>Coordination and child implementation in progress</td><td><code>project_status: active</code>; at least one workplan <code>active</code> or <code>ready</code></td></tr><tr><td><code>completed</code></td><td>All success gates have accepted evidence; residuals have live owners outside this repo</td><td><code>project_status: completed</code>; project workplans <code>finished</code> or cancelled with rationale</td></tr><tr><td><code>archived</code></td><td>Repository is read-only provenance</td><td>forge archive flag; hub repo/workplan <code>archived</code>; no normal writes</td></tr></tbody></table></div>
<p>Promotion rules:</p>
<ul><li><code>draft → active</code> when <code>GOAL.md</code> / <code>SCOPE.md</code> are reviewable and the foundation workplan is <code>ready</code> or <code>active</code>.</li><li><code>active → completed</code> only when <strong>every</strong> <code>GOAL.md</code> success gate has accepted evidence <strong>and</strong> residuals are live work records elsewhere (see below).</li><li><code>completed → archived</code> after the completion record is written, durable decisions are promoted, and a final consistency/link check passes.</li></ul>
</section>
<section id="residuals-before-completion"><h2>Residuals before completion</h2>
<p>Actionable leftovers MUST NOT live only in finished workplan prose or <code>SCOPE.md</code>. Before any project workplan is set to <code>finished</code>, and again before <code>project_status: completed</code>, each residual becomes a <strong>live work record</strong> outside the closing narrative:</p>
<ul><li>intake with <code>origin: residual</code> + <code>origin_ref: &lt;WP-id&gt;</code>, or</li><li>a next workplan / decision / engagement / register-entry in a permanent repo.</li></ul>
<p>Canon: <code>work-record-types_v0.1.md</code> § Residuals. Fleet residual listing is a State Hub concern, not a project-local queue file.</p>
</section>
<section id="completion-record"><h2>Completion record</h2>
<p>Before archival, the project repository MUST contain a completion record (recommended path: <code>history/YYYY-MM-DD-completion.md</code>) that lists:</p>
<ol><li>deployed or merged revisions that realize the outcome;</li><li>every participating repository touched, with links to merged PRs/commits or child workplan IDs;</li><li>promoted durable artefacts (canon paths, ADRs, standards);</li><li>migration and retirement evidence pointers (counts, cutover windows, backups);</li><li>residual work-record IDs and their owning repos;</li><li>rollback expiry or remaining operational obligations, if any.</li></ol>
<p>Without this record, do not archive.</p>
</section>
<section id="archive-procedure"><h2>Archive procedure</h2>
<ol><li>Verify all success gates and retirement conditions in <code>GOAL.md</code>.</li><li>Confirm residuals are live and owned outside this repository.</li><li>Promote remaining durable decisions/standards to permanent homes; leave pointers from the project repo.</li><li>Finish or cancel project workplans; move finished files to <code>workplans/archived/YYMMDD-&lt;id&gt;-&lt;slug&gt;.md</code> per workplan convention.</li><li>Write the completion record.</li><li>Set <code>project_status: archived</code> in <code>GOAL.md</code> frontmatter.</li><li>Run <code>statehub fix-consistency</code> (or equivalent) so the hub reflects finished workplans and the archived status.</li><li>Archive the repository in the forge (read-only); do <strong>not</strong> delete it.</li><li>Optionally mark the hub registration archived / read-only.</li></ol>
<p><strong>Archive means read-only provenance, never deletion.</strong> Historical evidence and coordination narrative remain queryable.</p>
</section>
<section id="workplan-and-agent-conventions"><h2>Workplan and agent conventions</h2>
<ul><li>Workplan files: <code>workplans/&lt;PREFIX&gt;-WP-NNNN-&lt;slug&gt;.md</code> with fleet status vocabulary (<code>proposed</code> … <code>archived</code>).</li><li>Session start order for agents: <code>GOAL.md</code> → <code>SCOPE.md</code> → genesis/history → active workplans (see project <code>AGENTS.md</code>).</li><li>Progress and task status follow ordinary State Hub / fix-consistency rules.</li><li>Ad-hoc low-risk fixes may use <code>workplans/ADHOC-YYYY-MM-DD.md</code> with canonical id <code>{PREFIX}-WP-ADHOC-YYYY-MM-DD</code>; anything multi-step belongs in a normal workplan.</li></ul>
</section>
<section id="minimal-layout-example"><h2>Minimal layout example</h2>
<pre>prj-example-cutover/
GOAL.md
SCOPE.md
README.md
AGENTS.md
.repo-classification.yaml
history/
2026-08-09-genesis.md
workplans/
EX-WP-0001-foundation.md</pre>
</section>
<section id="reference-instance"><h2>Reference instance</h2>
<p>The first repository under this standard is <code>prj-state-hub-retirement</code> (State Hub retirement / hub-core consolidation). Use it as the structural reference when scaffolding later <code>prj-</code> repos; do not copy its domain-specific content.</p>
</section>
<section id="conformance-checklist"><h2>Conformance checklist</h2>
<p>A repository conforms to the <code>prj-</code> flavor when:</p>
<ul><li>[ ] Named <code>prj-&lt;slug&gt;</code> and classified <code>category: project</code>.</li><li>[ ] Has <code>GOAL.md</code> with outcome, invariants, success gates, and retirement.</li><li>[ ] Has no durable-product <code>INTENT.md</code> (or documents an explicit temporary exception during migration of a mis-scaffolded repo).</li><li>[ ] Has <code>SCOPE.md</code>, <code>README.md</code>, <code>AGENTS.md</code>, and <code>.repo-classification.yaml</code>.</li><li>[ ] Hosts coordination workplans only; implementation lives in child repos.</li><li>[ ] Links child workplans by ID rather than duplicating their tasks.</li><li>[ ] Defines archive/completion discipline consistent with this standard.</li><li>[ ] On completion, writes a completion record and archives read-only.</li></ul>
</section>
<section id="related"><h2>Related</h2>
<ul><li>ADR-001 — Workplans and Work Items Are Repository Artefacts</li><li>ADR-005 — Cross-Repo Workplans Live in Dedicated Project Repos</li><li><code>repo-classification-standard_v1.0.md</code> — <code>category: project</code></li><li><code>work-record-types_v0.1.md</code> — residuals and work-record kinds</li><li><code>workplan-terminology-fleet_v0.1.md</code> — workplan vocabulary</li></ul>
</section><footer><span>canon-project-repository-flavor · accepted-1 · accepted</span><span>the-custodian · canon/standards/project-repository-flavor_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</span></footer></main></div></div></html>

246
docs/evidence/2026-10-11-served-publication-history/pages/canon-work-record-types.html Normal file
View file

@ -0,0 +1,246 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4b951be3947f9457cc091a7d359d9232646b4c93">
<meta name="policy-source-digest" content="1a40de294be332ee713cdaab532a32a83718f3952c339fbff835ecee899a8dbc">
<title>Work Record Types &amp; Identity (Fleet) v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>canon-work-record-types</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Work Record Types &amp; Identity (Fleet) v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/work-record-types_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#core-definition"><span class="n">·</span>Core definition</a></li><li><a href="#kind-registry-closed-list"><span class="n">·</span>Kind registry (closed list)</a></li><li><a href="#identity-layering"><span class="n">·</span>Identity layering</a></li><li><a href="#abstract-lifecycles-canon-fixed-minimal"><span class="n">·</span>Abstract lifecycles (canon-fixed, minimal)</a></li><li><a href="#residuals-role-not-kind"><span class="n">·</span>Residuals (role, not kind)</a></li><li><a href="#source-files-index-and-views"><span class="n">·</span>Source files, index, and views</a></li><li><a href="#tags"><span class="n">·</span>Tags</a></li><li><a href="#budgets"><span class="n">·</span>Budgets</a></li><li><a href="#reconciliation-loop-normative"><span class="n">·</span>Reconciliation loop (normative)</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><div class="rule-quote"><p>Ratified by founder 2026-07-20 (CUST-WP-0060-T01, hub decision f4640f9e). Source: <code>research/WorkOrchestrationArchitectureDraft.md</code> v0.2 (founder-reviewed 2026-07-20). Extends — does not replace — <code>workplan-terminology-fleet_v0.1.md</code> and ADR-001/ADR-005.</p></div>
<section id="purpose"><h2>Purpose</h2>
<p>Define <strong>work record</strong> as the umbrella term for every identified, lifecycle-bearing coordination artefact in the fleet; register the closed list of work-record <strong>kinds</strong>, their id schemes and abstract lifecycles; and fix the two-layer identity rule. This is the backbone convention for all work — planning, development, testing, operations, security &amp; compliance, controlling, billing, marketing, sales — under one conceptual framework (different demands are met by flow profiles and kind-specific fields, never by parallel ontologies).</p>
</section>
<section id="core-definition"><h2>Core definition</h2>
<p>A <strong>work record</strong> is any identified, lifecycle-bearing coordination artefact. A <strong>task</strong> is one <em>kind</em> of work record — the smallest executable unit. Every work record, regardless of kind, carries the <strong>conventional spine</strong>:</p>
<div class="scroll"><table><thead><tr><th>Field</th><th>Convention</th></tr></thead><tbody><tr><td><code>id</code></td><td>canonical name per the type registry below</td></tr><tr><td><code>uuid</code></td><td>UUIDv7, hub-assigned at first index, written back to the source file</td></tr><tr><td><code>kind</code></td><td>one of the registered kinds</td></tr><tr><td><code>lane</code></td><td>autonomy lane (<code>autonomy-lanes_v0.1.md</code>)</td></tr><tr><td><code>status</code></td><td>abstract lifecycle of the kind (below)</td></tr><tr><td><code>owner</code></td><td>agent identity (<code>agt-…</code>) or human</td></tr><tr><td><code>repo</code></td><td>owning repo (ADR-001/ADR-005 anchor)</td></tr><tr><td><code>tags</code></td><td>policy + derived tags (§ Tags)</td></tr><tr><td><code>created</code> / <code>updated</code></td><td>dates (UUIDv7 supplies fine-grained internal time)</td></tr></tbody></table></div>
<p>Kind-specific fields (budget, evidence, counterparty, deadline_pressure, attention_cost, …) extend the spine; they never replace it.</p>
</section>
<section id="kind-registry-closed-list"><h2>Kind registry (closed list)</h2>
<div class="scroll"><table><thead><tr><th>Kind</th><th>Id scheme</th><th>Meaning</th><th>Absorbs / legacy</th></tr></thead><tbody><tr><td><span class="kind ">`workplan`</span></td><td><code>{PREFIX}-WP-NNNN</code> · <code>{PREFIX}-WP-ADHOC-YYYY-MM-DD</code></td><td>structured, dependency-bearing body of work; repository-qualified daily container for small same-day tasks</td><td>unqualified <code>ADHOC-YYYY-MM-DD</code>; <code>MASON-0001</code> (grandfathered)</td></tr><tr><td><span class="kind ">`task`</span></td><td><code>{WP-ID}-TNN</code></td><td>smallest executable unit</td><td>unqualified <code>ADHOC-YYYY-MM-DD-TNN</code>; <code>MASON-0001-TNN</code> (grandfathered); issue-core issues become external projections only</td></tr><tr><td><span class="kind ">`intake`</span></td><td><code>{PREFIX}-IN-NNNN</code></td><td>spark: idea, finding, directive, request</td><td>hub suggestions (legacy, read-only close-out); <code>AWQ-NNN</code> (grandfathered)</td></tr><tr><td><span class="kind ">`decision`</span></td><td><code>{PREFIX}-DEC-YYYY-NNN</code></td><td>approval package + resolution</td><td><code>DEC-YYYY-NNN</code> (binky, grandfathered as-is)</td></tr><tr><td><span class="kind ">`engagement`</span></td><td><code>{PREFIX}-ENG-YYYY-NNN</code></td><td>scheduled external interaction (counterparty, prepared material, time window)</td><td><code>OH-YYYY-NNN</code> (grandfathered)</td></tr><tr><td><span class="kind ">`register-entry`</span></td><td>existing schemes: <code>RISK-NNN</code>, <code>RISK-F-NNNN</code>, <code>RISK-REG-NNNN</code>, <code>TD-…</code>, <code>CAP-…</code>, <code>CCR-YYYY-NNNN</code>, <code>ADR-NNN</code></td><td>risks/findings, regulatory records, technical debt, capability requests, credential change requests, architecture decisions</td><td>unchanged semantics, brought under the spine</td></tr></tbody></table></div>
<p>Rules:</p>
<ol><li><strong>Prefix grammar:</strong> <code>{PREFIX}</code> is one or more uppercase alphanumeric segments, each beginning with a letter, joined by hyphens. Both compact prefixes such as <code>CUST</code> and repository-derived prefixes such as <code>RAPP-OPENBAO</code> or <code>RAIL-K8S</code> are canonical. The final <code>-WP-</code> token remains the unambiguous kind separator.</li><li><strong>The registry is closed.</strong> An id pattern not registered in <code>work-record-types.yaml</code> fails CI and <code>fix-consistency</code> (the <em>sidetrack detector</em>). New kinds/prefixes are added by canon PR — deliberately cheap (one YAML entry + one schema) so the legitimate path is easier than any workaround.</li><li><strong>Grandfathering:</strong> existing ids are never renamed. Legacy prefixes map to kinds in the registry; retirement of a <em>scheme</em> (never of records) follows the legacy-meter discipline of <code>workplan-terminology-fleet_v0.1.md</code>.</li></ol>
<p>Compatibility correction 2026-08-23: State Hub message <code>24504ce7-4f73-47da-a150-629b07b37073</code> exposed that the machine pattern did not accept the already owner-registered <code>RAPP-OPENBAO-WP</code> prefix. The grammar now matches ADR-007's repository-derived prefix model; prefix ownership and uniqueness remain separate registry checks and are not weakened by this syntax correction.</p>
<p>The same compatibility review initially registered unqualified <code>ADHOC-YYYY-MM-DD</code> containers. A same-day collision between Activity Core and Net Kingdom then demonstrated that this form violates ADR-007's fleet-namespace uniqueness rule and cannot be used with deterministic UUID derivation. New daily records therefore use <code>{PREFIX}-WP-ADHOC-YYYY-MM-DD</code>; the filename remains <code>workplans/ADHOC-YYYY-MM-DD.md</code>. Existing unqualified ids are grandfathered and are never silently re-derived or disambiguated. Ad-hoc containers remain only for low-risk work completed directly.</p>
<p>Risk Nexus findings (<code>RISK-F-*</code>) and regulatory records (<code>RISK-REG-*</code>) are registered as variants of <code>register-entry</code>, not as parallel work kinds. Their lifecycles remain owned by the register convention. <code>RISK-N-*</code> notes are deliberately not registered: a note has no lifecycle, so it does not meet the core definition of a work record. A note becomes part of the backbone only when an event promotes its substance into a lifecycle-bearing kind.</p>
</section>
<section id="identity-layering"><h2>Identity layering</h2>
<ul><li><strong>UUIDv7 is primary</strong> for bookkeeping, relations, dependencies, and history. It is stable across renames, migrations, and terminology transitions.</li><li><strong>Canonical names are primary for humans and agents</strong> — UI, CLI, API output, prose, commits. UUIDs stay inspectable on demand but are never required reading.</li><li>The hub writes the UUID back into the source file at first index (pattern: today's <code>state_hub_*_id</code> fields).</li><li>A repeated source block with the same canonical id <strong>and the same UUID</strong> is one record with duplicate source occurrences. Index it once, retain every source location as diagnostic provenance, and report the duplication for governed cleanup. The repetition must not mint a second record. The same canonical id with different UUIDs is an identity collision and fails closed.</li></ul>
</section>
<section id="abstract-lifecycles-canon-fixed-minimal"><h2>Abstract lifecycles (canon-fixed, minimal)</h2>
<div class="scroll"><table><thead><tr><th>Kind</th><th>Lifecycle</th></tr></thead><tbody><tr><td><span class="kind ">task</span></td><td>`wait → todo → progress → done \</td><td>cancel` (InfoTechCanon)</td></tr><tr><td><span class="kind ">workplan</span></td><td><code>proposed → ready → active → blocked → backlog → finished → archived</code></td></tr><tr><td><span class="kind ">intake</span></td><td>`open → vetted → routed → closed(promoted \</td><td>declined \</td><td>absorbed)`</td></tr><tr><td><span class="kind ">decision</span></td><td>`prepared → resolved(approved \</td><td>rejected \</td><td>revised \</td><td>deferred)`</td></tr><tr><td><span class="kind ">engagement</span></td><td><code>queued → prepared → done</code></td></tr><tr><td><span class="kind ">register-entry</span></td><td>per existing register conventions (unchanged)</td></tr></tbody></table></div>
<p><strong>Promotion is a first-class transition:</strong> <code>intake.routed → workplan | task | decision | engagement</code>, executed by one CLI/MCP call that writes both artefacts, sets <code>promoted_to</code> / <code>origin</code> back-links, and re-syncs. Manual transcription of an intake item into other kinds is a process defect.</p>
<p><strong>Kind-specific rigor lives in flow profiles</strong>, not extra states: named task-flow-engine workstation definitions whose entry/exit assertions encode per-work-kind gates (e.g. compliance tasks cannot exit <code>progress</code> without an evidence link). Profiles are YAML in repos, in the same reconciliation loop.</p>
</section>
<section id="residuals-role-not-kind"><h2>Residuals (role, not kind)</h2>
<p>A <strong>residual</strong> is work intentionally left after a workplan (or large task bundle) finishes. It is <strong>not</strong> a registered kind — inventing a parallel “residuals queue” or parking leftovers only in <code>SCOPE.md</code> / finished-file prose is a process defect. Residuals must be <strong>live work records</strong> so the hub can list them across repos and domains.</p>
<div class="scroll"><table><thead><tr><th>Residual shape</th><th>Capture as</th><th>Required links</th></tr></thead><tbody><tr><td>Small Green/Blue follow-up, parkable</td><td><strong>intake</strong> (e.g. AWQ / <code>*-IN-*</code>)</td><td><code>origin: residual</code>, <code>origin_ref: &lt;parent-WP-id&gt;</code></td></tr><tr><td>Multi-step / dependency-bearing</td><td><strong>workplan</strong> (spawn next WP)</td><td>body or frontmatter names parent WP; optional <code>origin</code>/<code>origin_ref</code> when promoted from intake</td></tr><tr><td>Needs founder choice</td><td><strong>decision</strong></td><td>same origin fields when created from residual intake</td></tr><tr><td>Needs founder time window</td><td><strong>engagement</strong></td><td>same</td></tr><tr><td>Persistent gap / risk</td><td><strong>register-entry</strong> (risk, tech debt, …)</td><td>cross-link parent WP in notes</td></tr></tbody></table></div>
<p><strong>Close discipline for finished workplans:</strong></p>
<ol><li>Short residual <strong>narrative</strong> may remain under the closing task (human context).</li><li><strong>Before</strong> <code>status: finished</code>, each residual that is still actionable becomes a live record (intake and/or child workplan). Prose alone is not the backlog.</li><li>Progress milestone may name the handoff ids.</li><li><code>statehub fix-consistency</code> so the index (<code>WORK-RECORDS.md</code>, hub) reflects the handoff.</li></ol>
<p><strong>Fleet list (future CLI):</strong> filter open/vetted/routed intakes (and ready/ active workplans) with <code>origin ∈ {residual, handoff}</code> and optional <code>topic_id</code> / <code>repo</code> / <code>origin_ref</code>. Implementation home for that query is <strong>state-hub</strong> (<code>statehub residuals</code> / API), not domain repos.</p>
</section>
<section id="source-files-index-and-views"><h2>Source files, index, and views</h2>
<ol><li><strong>Any repo file is a potential source of work records.</strong> Records are authored as schema-valid YAML blocks in context — thematic live documents, meeting notes, design docs, triage logs. The schema is the contract, not the location. Workplans keep dedicated files.</li><li><strong>A generated per-repo work-record index</strong> references every registered record in its source location (transclusion-style; markitect-family tooling). It is the "everything across all files" orientation view and a concurrency cross-check.</li><li><strong>Every working list is a generated view</strong> (<code>[auto]</code>-marked) over indexed records — autopilot views, decision queues, engagement batches, briefs. Hand-maintained completed-logs and queue tails are retired.</li><li>Ordering of views is <strong>lane + priority + age</strong> by default; dependency capture optional; WSJF optional and situational (overload triage only).</li></ol>
</section>
<section id="tags"><h2>Tags</h2>
<p>Two classes, both in <code>tags</code>, never in <code>status</code>:</p>
<ul><li><strong>Derived tags</strong> — computed, read-only in files: <code>stalled</code>, <code>stale</code>, <code>overdue-decision</code>, <code>budget-breached</code>, <code>orphaned</code>.</li><li><strong>Policy tags</strong> — assigned under tagging policies: <code>automatable</code>, <code>needs-human</code>, <code>unclear-implementation</code>, <code>red-adjacent</code>, <code>compliance-relevant</code>, <code>residual</code> (optional badge when origin is not used).</li></ul>
<p>States migrate badly; tags migrate trivially. Anything situational is a tag.</p>
<p><strong>Origin values (intake and promoted children):</strong> use stable strings, not free prose. For residuals prefer <code>origin: residual</code> (or <code>handoff</code>) and <code>origin_ref: &lt;parent canonical id&gt;</code> (e.g. <code>BINKY-WP-0006</code>). Other established origins (e.g. <code>legacy-suggestion:&lt;uuid&gt;</code>, mail-triage ids) remain valid.</p>
</section>
<section id="budgets"><h2>Budgets</h2>
<p>Guardrail envelopes resolve programmatically at run start: workplan-frontmatter override → per-repo <code>budgets.yaml</code> (lane/default envelopes) → <strong>global best-guess default</strong>. Nothing runs unbounded. Budget resolution and enforcement is automation infrastructure, never agentic effort; metering via token events; breach ⇒ <code>budget-breached</code> + escalation.</p>
</section>
<section id="reconciliation-loop-normative"><h2>Reconciliation loop (normative)</h2>
<pre>author (any repo file) → CI schema validation → commit
→ fix-consistency: register/sync, UUID write-back
→ hub read model → generated index + views → NATS events → activity-core</pre>
<p>The hub remains a read model per ADR-001; runtime operations data (logs, metrics, run histories, token events) is the sanctioned DB-only exception.</p>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>research/WorkOrchestrationArchitectureDraft.md</code> (v0.2)</li><li><code>research/2026-07-19-work-orchestration-infrastructure-survey.md</code></li><li><code>research/2026-07-19-work-orchestration-best-practices.md</code></li><li><code>canon/architecture/adr-001-workplans-as-repo-artefacts.md</code>, <code>adr-005-…</code></li><li><code>canon/standards/workplan-terminology-fleet_v0.1.md</code></li><li><code>canon/standards/autonomy-lanes_v0.1.md</code></li><li><code>state-hub/docs/task-flow-engine-spec.md</code></li></ul>
</section><footer><span>canon-work-record-types · accepted-1 · accepted</span><span>the-custodian · canon/standards/work-record-types_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</span></footer></main></div></div></html>

236
docs/evidence/2026-10-11-served-publication-history/pages/canon-workplan-terminology-fleet.html Normal file
View file

@ -0,0 +1,236 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4b951be3947f9457cc091a7d359d9232646b4c93">
<meta name="policy-source-digest" content="199812632ac342ca3231498e545e3701e10c191ca144035b36a23c1a0b717712">
<title>Workplan Terminology (Fleet) v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>canon-workplan-terminology-fleet</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Workplan Terminology (Fleet) v0.1</h1><p class="sub">Source: <code>the-custodian · canon/standards/workplan-terminology-fleet_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#canonical-term"><span class="n">·</span>Canonical term</a></li><li><a href="#work-record-umbrella-v0-2-addendum-cust-wp-0060"><span class="n">·</span>Work-record umbrella (v0.2 addendum, CUST-WP-0060)</a></li><li><a href="#legacy-bridges-keep-until-retired"><span class="n">·</span>Legacy bridges (keep until retired)</a></li><li><a href="#event-subjects-normative"><span class="n">·</span>Event subjects (normative)</a></li><li><a href="#agent-and-documentation-rules"><span class="n">·</span>Agent and documentation rules</a></li><li><a href="#retirement-rule-unchanged"><span class="n">·</span>Retirement rule (unchanged)</a></li><li><a href="#verification"><span class="n">·</span>Verification</a></li><li><a href="#out-of-scope-this-standard"><span class="n">·</span>Out of scope (this standard)</a></li><li><a href="#references"><span class="n">·</span>References</a></li></ol></nav><main><section id="purpose"><h2>Purpose</h2>
<p>Define <strong>workplan</strong> as the canonical fleet term for repo-backed deliverable work indexed by State Hub. Preserve explicit <strong>legacy bridges</strong> where APIs, events, generated fields, or historical documents still say <code>workstream</code>, until metered retirement criteria are met.</p>
<p>This standard complements:</p>
<ul><li><strong>ADR-001</strong> — workplans originate as repo files; the hub indexes them.</li><li><strong>STATE-WP-0054</strong> — State Hub compatibility layer and <code>legacy-meter</code>.</li><li><strong>STATE-WP-0069</strong> — State Hub legacy interface retirement (child plan).</li><li><strong>CUST-WP-0055</strong> — fleet-wide coordination and prose migration.</li></ul>
<p>Authoritative interface matrix for State Hub: <code>state-hub/docs/workplan-terminology-transition.md</code>.</p>
</section>
<section id="canonical-term"><h2>Canonical term</h2>
<div class="scroll"><table><thead><tr><th>Concept</th><th>Fleet term</th><th>Meaning</th></tr></thead><tbody><tr><td>Repo-backed body of work</td><td><strong>workplan</strong></td><td>Markdown file under <code>workplans/</code> per ADR-001</td></tr><tr><td>Workplan file id</td><td><code>{PREFIX}-WP-NNNN</code></td><td>e.g. <code>CUST-WP-0055</code>, <code>STATE-WP-0069</code></td></tr><tr><td>Hub index row</td><td><strong>workplan</strong> (product term)</td><td>DB entity keyed by UUID; may still use legacy column names internally</td></tr><tr><td>Task within a workplan</td><td><strong>task</strong></td><td><code>id: {WP}-TNN</code> in workplan file blocks</td></tr></tbody></table></div>
</section>
<section id="work-record-umbrella-v0-2-addendum-cust-wp-0060"><h2>Work-record umbrella (v0.2 addendum, CUST-WP-0060)</h2>
<p>The workplan and task definitions above are unchanged. Since v0.2 they are two <em>kinds</em> of the fleet umbrella term <strong>work record</strong> — any identified, lifecycle-bearing coordination artefact. The full kind registry (workplan, task, <strong>intake item</strong>, <strong>decision</strong>, <strong>engagement</strong>, <strong>register entry</strong>), the conventional spine, identity layering (UUIDv7 internal, canonical names external), and grandfathered legacy id schemes (<code>AWQ-</code>, <code>DEC-</code>, <code>OH-</code>) are normative in <code>work-record-types_v0.1.md</code> (+ machine registry <code>work-record-types.yaml</code>). Autonomy-lane vocabulary is normative in <code>autonomy-lanes_v0.1.md</code>. "Suggestion" is a legacy bridge name for the intake kind (state-hub suggestions table: read-only legacy pending close-out). This file keeps its <code>_v0.1</code> name for reference stability; the frontmatter <code>version</code> field is authoritative.</p>
<p>Use <strong>workplan</strong> in human-facing prose: <code>SCOPE.md</code>, <code>AGENTS.md</code>, <code>INTENT.md</code>, README, workplan bodies, operator runbooks, and agent session guidance.</p>
</section>
<section id="legacy-bridges-keep-until-retired"><h2>Legacy bridges (keep until retired)</h2>
<p>Do <strong>not</strong> mass-rename these in the CUST-WP-0055 migration window:</p>
<div class="scroll"><table><thead><tr><th>Surface</th><th>Canonical</th><th>Legacy bridge</th><th>Retirement owner</th></tr></thead><tbody><tr><td>Workplan frontmatter link</td><td>(implicit workplan UUID)</td><td><code>state_hub_workstream_id</code></td><td>Separate bridge-field migration</td></tr><tr><td>REST/MCP parameters</td><td><code>workplan_id</code></td><td><code>workstream_id</code></td><td><code>STATE-WP-0069</code> + legacy-meter</td></tr><tr><td>REST routes</td><td><code>/workplans/</code></td><td><code>/workstreams/</code></td><td><code>STATE-WP-0069</code></td></tr><tr><td>MCP procedures</td><td><code>create_workplan</code>, etc.</td><td><code>create_workstream</code>, etc.</td><td><code>STATE-WP-0069</code></td></tr><tr><td>State Hub completion event</td><td><code>org.statehub.workplan.completed</code></td><td><code>org.statehub.workstream.completed</code></td><td><code>STATE-WP-0069</code> T05</td></tr><tr><td>activity-core catalog (custodian-era)</td><td><code>org.statehub.workplan.completed</code></td><td><code>org.workstream.completed</code></td><td><code>CUST-WP-0055</code> T03</td></tr><tr><td>Archived workplan prose</td><td>workplan (when editing)</td><td>historical "workstream" text</td><td>Grandfathered; header note only</td></tr><tr><td>Grandfathered filenames</td><td>—</td><td>paths containing <code>workstream</code></td><td>ADR-001 non-rename policy</td></tr></tbody></table></div>
<p><strong>Do not</strong> introduce a bare <code>org.workplan.completed</code> event subject. State Hub uses the <code>org.statehub.*</code> namespace.</p>
</section>
<section id="event-subjects-normative"><h2>Event subjects (normative)</h2>
<div class="scroll"><table><thead><tr><th>Subject</th><th>Status</th><th>Notes</th></tr></thead><tbody><tr><td><code>org.statehub.workplan.completed</code></td><td><strong>preferred</strong></td><td>Emitted on workplan finish; subscribe here</td></tr><tr><td><code>org.statehub.workstream.completed</code></td><td>legacy (metered)</td><td>Dual-published today; retire per legacy-meter</td></tr><tr><td><code>org.workstream.completed</code></td><td>legacy (catalog)</td><td>activity-core custodian-era type; align to State Hub subject</td></tr></tbody></table></div>
</section>
<section id="agent-and-documentation-rules"><h2>Agent and documentation rules</h2>
<ol><li><strong>Write workplan</strong> in instructions, orientation steps, and error messages aimed at humans or coding agents.</li><li><strong>Mention workstream only</strong> in an explicit compatibility footnote, e.g.: &gt; Legacy term: State Hub still exposes <code>/workstreams</code> and <code>workstream_id</code> &gt; aliases until legacy-meter retires them (<code>STATE-WP-0069</code>).</li><li><strong>Leave unchanged</strong> in code or docs when the string is a wire key, route, legacy-meter registry entry, or <code>state_hub_workstream_id</code> frontmatter field.</li><li><strong>Prefer</strong> <code>GET /workplans/</code> and <code>workplan_id</code> in new examples and scripts.</li></ol>
<p>Regenerated agent files (<code>state-hub/scripts/update_agent_instruction_files.py</code>) should follow rules 1–2. Templates live under <code>state-hub/scripts/project_rules/*.template</code>.</p>
</section>
<section id="retirement-rule-unchanged"><h2>Retirement rule (unchanged)</h2>
<p>A legacy interface may be removed only when <strong>all</strong> are true:</p>
<ul><li>registered in State Hub <code>legacy-meter</code>;</li><li>replacement reference verified;</li><li>no manual hold;</li><li>zero measured calls in the review window.</li></ul>
<p>State Hub owns usage evidence; activity-core may run weekly review activities. See <code>state-hub/docs/workplan-terminology-transition.md</code>.</p>
</section>
<section id="verification"><h2>Verification</h2>
<p>Fleet terminology drift is measured with:</p>
<pre>python tools/scan_workstream_terminology.py
python tools/scan_workstream_terminology.py --repo &lt;slug&gt; --json</pre>
<p>Baseline artefact (2026-07-08): <code>docs/evidence/workstream-terminology-baseline-20260708.json</code>.</p>
<p>Exit criteria and scan exclusions: <code>CUST-WP-0055</code> T08.</p>
</section>
<section id="out-of-scope-this-standard"><h2>Out of scope (this standard)</h2>
<ul><li>Renaming <code>state_hub_workstream_id</code> in workplan frontmatter.</li><li>Database table or ORM model renames (completed in <code>STATE-WP-0065</code>).</li><li>Rewriting archived workplan bodies in bulk (<code>CUST-WP-0055</code> T07).</li></ul>
</section>
<section id="references"><h2>References</h2>
<ul><li><code>canon/architecture/adr-001-workplans-as-repo-artefacts.md</code></li><li><code>state-hub/docs/workplan-terminology-transition.md</code></li><li><code>state-hub/workplans/STATE-WP-0054-workplan-terminology-transition-legacy-meter.md</code></li><li><code>state-hub/workplans/STATE-WP-0069-workplan-terminology-legacy-retirement.md</code></li><li><code>workplans/CUST-WP-0055-workplan-terminology-fleet-refactor.md</code></li></ul>
</section><footer><span>canon-workplan-terminology-fleet · accepted-1 · accepted</span><span>the-custodian · canon/standards/workplan-terminology-fleet_v0.1.md · 4b951be3947f9457cc091a7d359d9232646b4c93</span></footer></main></div></div></html>

274
docs/evidence/2026-10-11-served-publication-history/pages/coulomb-estate-architecture.html Normal file
View file

@ -0,0 +1,274 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d3c6f13d7aed9784b6f31c23d2b2777668493ba5">
<meta name="policy-source-digest" content="3b4f93acdedc6f6d1a1c737c3327d9d55061506c5a879be09e6b0a2ea7f5f9bc">
<title>Coulomb estate architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>coulomb-estate-architecture</span> <span class="stat">proposed · draft-3</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Coulomb estate architecture</h1><p class="sub">Source: <code>the-custodian · canon/architecture/coulomb-estate_v0.1.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#about-this-document"><span class="n">·</span>About this document</a></li><li><a href="#s1"><span class="n">1</span>Introduction and Goals</a></li><li><a href="#s2"><span class="n">2</span>Architecture Constraints</a></li><li><a href="#s3"><span class="n">3</span>System Scope and Context</a></li><li><a href="#s4"><span class="n">4</span>Solution Strategy</a></li><li><a href="#s5"><span class="n">5</span>Building Block View</a></li><li><a href="#s6"><span class="n">6</span>Runtime View</a></li><li><a href="#s7"><span class="n">7</span>Deployment View</a></li><li><a href="#s8"><span class="n">8</span>Cross-Cutting Concepts</a></li><li><a href="#s9"><span class="n">9</span>Architecture Decisions</a></li><li><a href="#s10"><span class="n">10</span>Quality Requirements</a></li><li><a href="#s11"><span class="n">11</span>Risks and Technical Debt</a></li><li><a href="#s12"><span class="n">12</span>Glossary</a></li></ol></nav><main><section id="about-this-document"><h2>About this document</h2>
<p>This is the first-wave <strong>estate map</strong>. It describes how the Coulomb / Custodian estate is put together: canons, hubs, rails, and publication. System-level arc42 documents (Railiance, NetKingdom, State Hub, Policy Nexus) live in their owning repos. Chapter 9 lists estate ADRs; it does not paste them.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Introduction and Goals</h2>
<p>the-custodian holds meaning, boundaries, and continuity for a local-first agent estate. Implementation lives in product repos. Coordination state is a read-model of repository files, not the origin of those files.</p>
<h3>1.1 Requirements Overview</h3>
<ul><li>Work, decisions, and canon originate as files in the owning repo.</li><li>A publication surface keeps governing documents at permanent URLs.</li><li>Runtime (Rails, rApps, identity, storage) is consumed from platform packages, not reimplemented in the custodian.</li><li>Cross-repo work is coordinated, not owned, by a dedicated project repo when it does not belong to one product.</li></ul>
<h3>1.2 Quality Goals</h3>
<ol><li>Rebuildability — State Hub can be reconstructed from registered repository files (ADR-001).</li><li>Concept ownership — canons import, they do not redefine (ADR-006).</li><li>Permanence of published policy addresses (policy-nexus ADR-0001).</li><li>Honest currency — stale documents are visibly stale.</li></ol>
<h3>1.3 Stakeholders</h3>
<div class="scroll"><table><thead><tr><th>Role</th><th>Concern</th></tr></thead><tbody><tr><td>Operator</td><td>What must be discussed in person; ratification.</td></tr><tr><td>the-custodian</td><td>Canon, values, constitution, estate ADRs.</td></tr><tr><td>Product repos</td><td>Implementation and per-repo ADRs.</td></tr><tr><td>railiance-platform</td><td>Substrate: DNS, TLS, ingress, hosting.</td></tr><tr><td>policy-nexus</td><td>Publication only.</td></tr><tr><td>info-tech-canon</td><td>Semantic model, not this estate's building blocks.</td></tr></tbody></table></div>
</section>
<section id="s2"><h2><span class="sn">02</span>Architecture Constraints</h2>
<p>N/A in this revision — local-first files, no second source of truth, stdlib-preferring tooling, single-node rail availability. To be written as first-wave complete.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>System Scope and Context</h2>
<p><strong>In:</strong> estate canon (<code>constitution</code>, <code>standards</code>, <code>architecture</code> ADRs), the federation of canons, the publication contract, the hub-as-read-model rule, and the map of first-wave systems.</p>
<p><strong>Out:</strong> product implementation, InfoTechCanon's landscape model, regulatory intake (<code>risk-nexus</code>), and per-system deployment detail (those belong in the system arc42).</p>
<h3>3.1 Business Context</h3>
<p>The estate is a set of repositories that together run Coulomb products and the agent work-factory. Readers need one map of what governs what. Owners need a place that is not also the implementation.</p>
<h3>3.2 Technical Context</h3>
<div class="scroll"><table><thead><tr><th>Neighbour</th><th>Interface</th></tr></thead><tbody><tr><td>Owning git repos</td><td>Source of workplans, ADRs, canon.</td></tr><tr><td>State Hub</td><td>Derived index / cache of those files.</td></tr><tr><td>policy.coulomb.social</td><td>Generated publication of canon and ADRs.</td></tr><tr><td>Railiance reef</td><td>Runtime for hubs, rApps, Forgejo.</td></tr><tr><td>NetKingdom</td><td>Identity, tenancy, IAM profile.</td></tr><tr><td>info-tech-canon</td><td>Imported semantics, not estate structure.</td></tr></tbody></table></div>
</section>
<section id="s4"><h2><span class="sn">04</span>Solution Strategy</h2>
<ul><li><strong>Files first.</strong> Workplans and ADRs are markdown in git. The hub rebuilds from them (ADR-001, ADR-003).</li><li><strong>One registrar.</strong> Workplan identifiers are globally unique; this workstation is not the registrar (ADR-007).</li><li><strong>Three canons, federated.</strong> Custodian (governance), InfoTechCanon (information-system semantics), CommerceCanon (counterparty semantics). They import, they do not redefine (ADR-006).</li><li><strong>Publish, do not author.</strong> policy-nexus reads owning repos and emits static addresses. It never writes back.</li><li><strong>Project repos for cross-repo work</strong> (<code>prj-*</code>), not an unbound hub workplan (ADR-005).</li></ul>
</section>
<section id="s5"><h2><span class="sn">05</span>Building Block View</h2>
<h3>5.1 Level 1 – System/Top-Level</h3>
<pre> ┌─────────────────────────┐
│ the-custodian │
│ constitution, values, │
│ estate ADRs, memory │
└────────────┬────────────┘
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌────────────────┐ ┌─────────────────┐
│ info-tech- │ │ commerce-canon │ │ net-kingdom │
│ canon │ │ │ │ (identity / │
│ (semantics) │ │ │ │ tenancy) │
└───────────────┘ └────────────────┘ └────────┬────────┘
│
┌───────────────┐ ┌────────────────┐ │
│ state-hub │◄───│ product repos │◄────────────┘
│ (read model) │ │ + project repos│
└───────────────┘ └────────┬───────┘
│
┌────────────┴────────────┐
▼ ▼
┌────────────────┐ ┌─────────────────┐
│ railiance │ │ policy-nexus │
│ (reef, rApps) │ │ (publication) │
└────────────────┘ └─────────────────┘</pre>
<h3>5.2 Level 2 – Key Components</h3>
<p>N/A in this revision.</p>
<h3>5.3 Level 3 – Internal Structure (as needed)</h3>
<p>N/A in this revision.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Runtime View</h2>
<p>N/A — estate coordination is file sync plus hub rebuild, not a single runtime scenario. System runtimes belong in their own arc42.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Deployment View</h2>
<p>N/A — Railiance owns where things run. This document names the substrate; it does not map nodes.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Cross-Cutting Concepts</h2>
<p>N/A in this revision. Concept ownership and the hub/cache split are already in §4 and the ADRs in §9.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
<p>Estate ADRs in <code>the-custodian/canon/architecture/</code>. Status is the source front-matter.</p>
<div class="scroll"><table><thead><tr><th>Id</th><th>Status</th><th>Decision</th></tr></thead><tbody><tr><td><code>CUST-ADR-001</code></td><td>accepted</td><td>File-backed work originates in repositories; the Hub projects it and separately owns declared Hub-native records.</td></tr><tr><td><code>CUST-ADR-002</code></td><td>accepted</td><td>Custodian agent runtime design.</td></tr><tr><td><code>CUST-ADR-003</code></td><td>accepted</td><td>Hub state is derived and fingerprint-invalidated.</td></tr><tr><td><code>CUST-ADR-004</code></td><td>accepted</td><td>Connectivity-first network posture.</td></tr><tr><td><code>CUST-ADR-005</code></td><td>accepted</td><td>Cross-repo work lives in a <code>prj-*</code> repo.</td></tr><tr><td><code>CUST-ADR-006</code></td><td>accepted</td><td>Three canons; import, do not redefine.</td></tr><tr><td><code>CUST-ADR-007</code></td><td>accepted</td><td>Namespace-aware work-record identity, deterministic Hub ids, and repository worker topology.</td></tr><tr><td><code>adr-008</code></td><td>superseded</td><td>Relocated to NetKingdom Tenancy Posture.</td></tr><tr><td><code>CUST-ADR-010</code></td><td>proposed</td><td>Two kinds of hub data; local cache vs authority.</td></tr><tr><td><code>CUST-ADR-011</code></td><td>proposed</td><td>Federated namespaces and reconciliation limits.</td></tr><tr><td><code>CUST-ADR-012</code></td><td>accepted</td><td>Forge is the projection source; unpushed working-copy state is preliminary.</td></tr></tbody></table></div>
<p>Related and published elsewhere: policy-nexus ADR-0001; Tenancy Posture and IAM Profile v0.3 plus the current NetKingdom security standards; NetKingdom ADR-0006–0008 and 0010–0015; railiance-master ADR-0001–0009; activity-core ACT-ADR-001–007; ops-warden ADR-0001–0005 and 0007–0010; railiance-platform RPLAT-ADR-0001–0003.</p>
<p>Unresolved WP-0003 conflicts (hosts/infra duplicate ADR-003/004, coulomb-social ADR-0002 partial supersession) are <strong>not</strong> listed as current.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Quality Requirements</h2>
<p>N/A in this revision — rebuildability and currency already have mechanical checks (<code>fix-consistency</code>, <code>make currency</code>).</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Risks and Technical Debt</h2>
<p>N/A in this revision. Known residuals are the Forge-derived reset and preliminary-overlay implementation under ADR-012. Markitect <code>arc42-v1</code> is not registered yet.</p>
</section>
<section id="s12"><h2><span class="sn">12</span>Glossary</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Meaning</th></tr></thead><tbody><tr><td>Estate</td><td>The set of Coulomb / Custodian repos, canons, hubs, and rails.</td></tr><tr><td>Canon</td><td>Governing documents owned by one of the three federated canons.</td></tr><tr><td>Read model</td><td>A derived index. Never the origin of work or decisions.</td></tr><tr><td>Publication entry</td><td>One explicit object in policy-nexus <code>publication.json</code>.</td></tr><tr><td>First-wave complete</td><td>Chapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.</td></tr><tr><td>Project repo</td><td>A <code>prj-*</code> repo that coordinates cross-repo work (ADR-005).</td></tr></tbody></table></div>
</section><footer><span>coulomb-estate-architecture · draft-3 · proposed</span><span>the-custodian · canon/architecture/coulomb-estate_v0.1.md · d3c6f13d7aed9784b6f31c23d2b2777668493ba5</span></footer></main></div></div></html>

244
docs/evidence/2026-10-11-served-publication-history/pages/net-kingdom-architecture.html Normal file
View file

@ -0,0 +1,244 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d4e57e63126d2cca1d381c025170e4b1f678c3f3">
<meta name="policy-source-digest" content="b9f89f706a801d54961fc67d725ca433b7c3b6a083c54793de6e8b60d1dd42a8">
<title>NetKingdom architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>net-kingdom-architecture</span> <span class="stat">proposed · draft-3</span> <span>net-kingdom</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom architecture</h1><p class="sub">Source: <code>net-kingdom · docs/architecture/net-kingdom_v0.1.md · d4e57e63126d2cca1d381c025170e4b1f678c3f3</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#about-this-document"><span class="n">·</span>About this document</a></li><li><a href="#s1"><span class="n">1</span>Introduction and Goals</a></li><li><a href="#s2"><span class="n">2</span>Architecture Constraints</a></li><li><a href="#s3"><span class="n">3</span>System Scope and Context</a></li><li><a href="#s4"><span class="n">4</span>Solution Strategy</a></li><li><a href="#s5"><span class="n">5</span>Building Block View</a></li><li><a href="#s6"><span class="n">6</span>Runtime View</a></li><li><a href="#s7"><span class="n">7</span>Deployment View</a></li><li><a href="#s8"><span class="n">8</span>Cross-Cutting Concepts</a></li><li><a href="#s9"><span class="n">9</span>Architecture Decisions</a></li><li><a href="#s10"><span class="n">10</span>Quality Requirements</a></li><li><a href="#s11"><span class="n">11</span>Risks and Technical Debt</a></li><li><a href="#s12"><span class="n">12</span>Glossary</a></li></ol></nav><main><section id="about-this-document"><h2>About this document</h2>
<p>First-wave arc42 for NetKingdom: the estate's identity and tenancy security core. Chapter 9 lists governing ADRs and standards; it does not paste them.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Introduction and Goals</h2>
<p>NetKingdom is the open security core for DevSecOps on Kubernetes. It owns identity, tenancy posture, and the contracts that flex-auth, key-cape, tenant-engine, and railiance workloads implement.</p>
<h3>1.1 Requirements Overview</h3>
<ul><li>One IAM profile, versioned, owned here.</li><li>Tenancy described as graduated axes, not a single on/off switch.</li><li>Workload packaging and credential vending have explicit boundaries.</li></ul>
<h3>1.2 Quality Goals</h3>
<ol><li>Provider-neutral identity contract.</li><li>Recursive multi-tenant authorization that implementers can declare.</li><li>Honest about what is not there yet (Tenancy Posture).</li></ol>
<h3>1.3 Stakeholders</h3>
<div class="scroll"><table><thead><tr><th>Role</th><th>Concern</th></tr></thead><tbody><tr><td>net-kingdom</td><td>Canon owner for identity and tenancy.</td></tr><tr><td>flex-auth / key-cape / tenant-engine</td><td>Implementers of the contracts.</td></tr><tr><td>railiance-master</td><td>Workload packaging on the rail.</td></tr><tr><td>the-custodian</td><td>Federation; does not redefine these concepts.</td></tr></tbody></table></div>
</section>
<section id="s2"><h2><span class="sn">02</span>Architecture Constraints</h2>
<p>N/A for this stub.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>System Scope and Context</h2>
<p><strong>In:</strong> IAM profile, tenancy posture, tenant/user-engine boundaries, credential management, playbook capability contract, NetKingdom ADRs. <strong>Out:</strong> publication (policy-nexus), rail runtime (railiance), estate work-factory (the-custodian).</p>
<h3>3.1 Business Context</h3>
<p>Security here is dynamic and adversarial. The system exists so implementers share one contract instead of copying a neighbour.</p>
<h3>3.2 Technical Context</h3>
<p>Consumers: flex-auth, key-cape, tenant-engine, audit-core, rApps. Published today: Tenancy Posture <code>/standards/tenancy-posture/v0.1/</code>.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Solution Strategy</h2>
<p>N/A for this stub — recursive multi-tenant identity (ADR-0006) and the IAM profile ownership rule (ADR-0011) are the spine.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Building Block View</h2>
<h3>5.1 Level 1 – System/Top-Level</h3>
<p>N/A for this stub.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Runtime View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Deployment View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Cross-Cutting Concepts</h2>
<p>N/A for this stub.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
<div class="scroll"><table><thead><tr><th>Publication id</th><th>Status</th><th>Decision or standard</th></tr></thead><tbody><tr><td><code>netkingdom-tenancy-posture</code></td><td>proposed</td><td>Graduated multi-tenancy posture.</td></tr><tr><td><code>netkingdom-iam-profile-v0.3</code></td><td>accepted</td><td>Current provider-neutral identity contract.</td></tr><tr><td><code>netkingdom-posture-feedback-v0.1</code></td><td>proposed</td><td>Governed posture feedback.</td></tr><tr><td><code>netkingdom-security-layer-model-v0.7</code></td><td>accepted</td><td>Current security-layer interaction model.</td></tr><tr><td><code>netkingdom-security-scenario-composition-v0.1</code></td><td>proposed</td><td>Security scenario composition.</td></tr><tr><td><code>netkingdom-security-zones-v0.1</code></td><td>proposed</td><td>Security-zone vocabulary and boundaries.</td></tr><tr><td><code>NK-ADR-0006</code></td><td>accepted</td><td>Recursive multi-tenant identity and authorization.</td></tr><tr><td><code>NK-ADR-0007</code></td><td>accepted</td><td>Security orchestration boundary.</td></tr><tr><td><code>NK-ADR-0008</code></td><td>accepted</td><td>Object-storage STS credential vending.</td></tr><tr><td><code>NK-ADR-0010</code></td><td>accepted</td><td>Orchestration, dependency, and self-coherent intent.</td></tr><tr><td><code>NK-ADR-0011</code></td><td>accepted</td><td>IAM Profile ownership and version governance.</td></tr><tr><td><code>NK-ADR-0012</code></td><td>accepted</td><td>Playbook capability-contract ownership.</td></tr><tr><td><code>NK-ADR-0013</code></td><td>accepted</td><td>Tenant onboarding grouping taxonomy.</td></tr><tr><td><code>NK-ADR-0014</code></td><td>accepted</td><td>Tenant capability roles and tenant-engine ownership.</td></tr><tr><td><code>NK-ADR-0015</code></td><td>accepted</td><td>Railiance workload packaging and relational platform.</td></tr></tbody></table></div>
<p>Custodian ADR-008 is superseded by Tenancy Posture and is not current.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Quality Requirements</h2>
<p>N/A for this stub.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Risks and Technical Debt</h2>
<p>N/A for this stub. The IAM Profile publication id is now globally qualified.</p>
</section>
<section id="s12"><h2><span class="sn">12</span>Glossary</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Meaning</th></tr></thead><tbody><tr><td>IAM Profile</td><td>Provider-neutral OIDC contract owned here.</td></tr><tr><td>Tenancy Posture</td><td>Graduated axes for describing multi-tenancy.</td></tr><tr><td>Tenant-engine</td><td>Lifecycle and capability roles for tenants.</td></tr></tbody></table></div>
</section><footer><span>net-kingdom-architecture · draft-3 · proposed</span><span>net-kingdom · docs/architecture/net-kingdom_v0.1.md · d4e57e63126d2cca1d381c025170e4b1f678c3f3</span></footer></main></div></div></html>

319
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-iam-profile-v0.3.html Normal file
View file

@ -0,0 +1,319 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="d4e57e63126d2cca1d381c025170e4b1f678c3f3">
<meta name="policy-source-digest" content="6c47b596ea145fa197c9665081c84902482d90f5bb94d185c1223af65279be1d">
<title>NetKingdom IAM Profile v0.3</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-iam-profile-v0.3</span> <span class="stat">accepted · accepted-1</span> <span>net-kingdom</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom IAM Profile v0.3</h1><p class="sub">Source: <code>net-kingdom · canon/standards/iam-profile_v0.3.md · d4e57e63126d2cca1d381c025170e4b1f678c3f3</code></p><p class="sub">Review due: 2027-02-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#purpose"><span class="n">·</span>Purpose</a></li><li><a href="#ownership"><span class="n">·</span>Ownership</a></li><li><a href="#design-principles"><span class="n">·</span>Design Principles</a></li><li><a href="#discovery-contract"><span class="n">·</span>Discovery Contract</a></li><li><a href="#required-flows"><span class="n">·</span>Required Flows</a></li><li><a href="#core-claims"><span class="n">·</span>Core Claims</a></li><li><a href="#tenant-claim"><span class="n">·</span>Tenant Claim</a></li><li><a href="#tenant-roles"><span class="n">·</span>Tenant Roles</a></li><li><a href="#assurance-evidence"><span class="n">·</span>Assurance Evidence</a></li><li><a href="#identity-to-authorization-contract"><span class="n">·</span>Identity To Authorization Contract</a></li><li><a href="#token-lifecycle"><span class="n">·</span>Token Lifecycle</a></li><li><a href="#local-development-profile"><span class="n">·</span>Local Development Profile</a></li><li><a href="#emergency-and-break-glass-access"><span class="n">·</span>Emergency And Break-Glass Access</a></li><li><a href="#conformance"><span class="n">·</span>Conformance</a></li><li><a href="#validation-checklist"><span class="n">·</span>Validation Checklist</a></li></ol></nav><main><div class="rule-quote"><p>Minor version. Per ADR-0011's versioning rule, this adds an optional claim and clarifies non-normative guidance — no required claim, validation rule, or previously-issued token is invalidated. Existing v0.2 implementations remain conformant; <code>tenant_roles</code> and the revised Tenant Claim guidance are additive.</p></div>
<section id="purpose"><h2>Purpose</h2>
<p>The NetKingdom IAM Profile is the provider-neutral OIDC contract that identity implementations issue and applications consume.</p>
<p>It defines:</p>
<ul><li>OIDC discovery and endpoint requirements;</li><li>Authorization Code + PKCE for human login;</li><li>service-account and workload identity token requirements;</li><li>human, service, and agent principal representation;</li><li>tenant, tenant-grouping, and platform-boundary claims;</li><li>tenant capability roles and their carrying mechanism;</li><li>explicit assurance evidence;</li><li>the identity-to-authorization claim contract consumed by flex-auth;</li><li>local-development and emergency-access behavior;</li><li>executable conformance expectations.</li></ul>
<p>Applications target this profile, not a concrete identity provider. key-cape is the lightweight implementation. Keycloak is the expanded-mode implementation. Both are interchangeable at the application and authorization boundary when they conform to this document.</p>
</section>
<section id="ownership"><h2>Ownership</h2>
<p>NetKingdom owns the core/platform profile. See ADR-0011.</p>
<p>Downstream systems may define extension scopes, roles, resource names, and tenant policy vocabularies. Those extensions are not part of the core profile unless a future version explicitly adopts them. Extension vocabularies must map back to the core claims in this document before flex-auth or applications consume them.</p>
</section>
<section id="design-principles"><h2>Design Principles</h2>
<ul><li>Consumers trust signed OIDC tokens, not provider-specific sessions.</li><li>Identity providers assert identity and authentication evidence; they do not make final resource authorization decisions.</li><li>The same profile works in lightweight key-cape mode and expanded Keycloak mode.</li><li>Tenancy is explicit. <code>tenant:platform</code> is distinct from tenant planes such as <code>tenant:coulomb</code> and from later tenants grouped per ADR-0013.</li><li>A tenant's onboarding <strong>grouping</strong> (ADR-0013) and its <strong>capability roles</strong> (ADR-0014) are independent axes. Neither is encoded in the other; a tenant's roles may change without renaming its identifier.</li><li>Human, service, and agent principals are distinguishable.</li><li>Assurance evidence is explicit enough for flex-auth policy.</li><li>Local-development issuers are useful but never accepted by production.</li><li>Emergency access is auditable, time-bounded, and reviewable.</li></ul>
</section>
<section id="discovery-contract"><h2>Discovery Contract</h2>
<p>Every IAM Profile implementation MUST expose OIDC discovery at:</p>
<pre>GET &lt;issuer&gt;/.well-known/openid-configuration</pre>
<p>The discovery response MUST include:</p>
<div class="scroll"><table><thead><tr><th>Field</th><th>Requirement</th></tr></thead><tbody><tr><td><code>issuer</code></td><td>Exact issuer identifier used in tokens</td></tr><tr><td><code>authorization_endpoint</code></td><td>Required for human Authorization Code + PKCE</td></tr><tr><td><code>token_endpoint</code></td><td>Required for token exchange and service accounts</td></tr><tr><td><code>jwks_uri</code></td><td>Required for signature validation</td></tr><tr><td><code>userinfo_endpoint</code></td><td>Required when userinfo is supported by the flow</td></tr><tr><td><code>scopes_supported</code></td><td>MUST include <code>openid</code>; SHOULD include <code>profile</code> and <code>email</code></td></tr><tr><td><code>response_types_supported</code></td><td>MUST include <code>code</code></td></tr><tr><td><code>grant_types_supported</code></td><td>MUST include <code>authorization_code</code>; MUST include <code>client_credentials</code> or a documented workload-token exchange for service identities</td></tr><tr><td><code>id_token_signing_alg_values_supported</code></td><td>MUST include the implementation signing algorithm; RS256 is required for v0.2+ conformance</td></tr><tr><td><code>code_challenge_methods_supported</code></td><td>MUST include <code>S256</code></td></tr></tbody></table></div>
<p>The response SHOULD include <code>end_session_endpoint</code> where logout is supported and <code>claims_supported</code> listing the core claims below.</p>
<p>Consumers MUST discover endpoints and key material from the issuer metadata instead of hardcoding provider-specific paths.</p>
</section>
<section id="required-flows"><h2>Required Flows</h2>
<h3>Human Interactive Flow</h3>
<p>Human users authenticate with Authorization Code + PKCE.</p>
<p>Required properties:</p>
<ul><li>PKCE with <code>S256</code> is mandatory for browser and CLI clients.</li><li>Implicit flow is not part of the profile.</li><li>MFA or equivalent strong assurance is mandatory for privileged, destructive, platform-root, and emergency access in production.</li><li>Access tokens are short-lived.</li><li>Refresh tokens are allowed only for trusted clients with explicit rotation and revocation.</li></ul>
<h3>Service Account Flow</h3>
<p>Service-to-service traffic uses client credentials or a deployment's documented workload identity token-exchange equivalent.</p>
<p>Required properties:</p>
<ul><li>Service subjects are stable and named for service plus environment.</li><li>Secrets or workload credentials are delivered through the credential-management standard, not plaintext configuration.</li><li>Tokens include an audience that identifies the target service.</li><li>Tokens carry <code>principal_type: service</code>.</li><li>Service accounts receive only required scopes and roles.</li><li>Credentials are rotated and never shared between environments.</li></ul>
<h3>Agent Principal Flow</h3>
<p>Agents are automation principals that may act autonomously or under delegated authority.</p>
<p>Required properties:</p>
<ul><li>Tokens carry <code>principal_type: agent</code>.</li><li>Tokens include an <code>agent</code> object with <code>id</code> and <code>mode</code>.</li><li><code>agent.mode</code> is <code>autonomous</code> or <code>delegated</code>.</li><li>Delegated agents MUST identify the delegating actor using <code>actor_sub</code> or an equivalent <code>act.sub</code> claim.</li><li>Agent tokens MUST carry the tenant they operate within.</li><li>Agent tokens MUST include assurance evidence for both the agent credential and any delegated human authority when policy needs it.</li></ul>
</section>
<section id="core-claims"><h2>Core Claims</h2>
<p>Access tokens accepted by production consumers MUST provide the following claims after provider mapping or normalization:</p>
<div class="scroll"><table><thead><tr><th>Claim</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>iss</code></td><td>string</td><td>OIDC issuer URL or issuer identifier</td></tr><tr><td><code>sub</code></td><td>string</td><td>Stable subject identifier unique within <code>iss</code></td></tr><tr><td><code>aud</code></td><td>string or array</td><td>Intended audience; MUST include the receiving service</td></tr><tr><td><code>exp</code></td><td>number</td><td>Expiry timestamp</td></tr><tr><td><code>iat</code></td><td>number</td><td>Issued-at timestamp</td></tr><tr><td><code>nbf</code></td><td>number</td><td>Not-before timestamp, recommended for production tokens</td></tr><tr><td><code>jti</code></td><td>string</td><td>Token identifier, recommended for audit and replay controls</td></tr><tr><td><code>tenant</code></td><td>string</td><td>Tenant identifier such as <code>tenant:platform</code> or <code>tenant:friendly:binky</code></td></tr><tr><td><code>principal_type</code></td><td>string</td><td><code>human</code>, <code>service</code>, or <code>agent</code></td></tr><tr><td><code>groups</code></td><td>array</td><td>Group memberships, possibly empty</td></tr><tr><td><code>roles</code></td><td>array</td><td>Coarse <strong>identity</strong> roles for the subject, possibly empty</td></tr><tr><td><code>scope</code> or <code>scp</code></td><td>string or array</td><td>Granted OAuth scopes</td></tr><tr><td><code>assurance</code></td><td>object</td><td>Authentication and credential assurance evidence</td></tr></tbody></table></div>
<p>Recommended human claims:</p>
<div class="scroll"><table><thead><tr><th>Claim</th><th>Meaning</th></tr></thead><tbody><tr><td><code>preferred_username</code></td><td>Human-readable username</td></tr><tr><td><code>email</code></td><td>Contact identity</td></tr><tr><td><code>name</code></td><td>Display name</td></tr></tbody></table></div>
<p>Recommended service claims:</p>
<div class="scroll"><table><thead><tr><th>Claim</th><th>Meaning</th></tr></thead><tbody><tr><td><code>azp</code> or <code>client_id</code></td><td>Authorized client/service identifier</td></tr><tr><td><code>service</code></td><td>Object naming the service and environment</td></tr></tbody></table></div>
<p>Recommended agent claims:</p>
<div class="scroll"><table><thead><tr><th>Claim</th><th>Meaning</th></tr></thead><tbody><tr><td><code>agent.id</code></td><td>Stable agent identifier</td></tr><tr><td><code>agent.mode</code></td><td><code>autonomous</code> or <code>delegated</code></td></tr><tr><td><code>actor_sub</code> or <code>act.sub</code></td><td>Delegating subject for delegated agents</td></tr></tbody></table></div>
<p>Optional claims (new in v0.3):</p>
<div class="scroll"><table><thead><tr><th>Claim</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>tenant_roles</code></td><td>array</td><td>Cached tenant <strong>capability</strong> roles (<code>PLTF</code>/<code>IAM</code>/<code>VEN</code>/<code>CUS</code>), possibly empty. See "Tenant Roles" below — this is a point-in-time cache, not the authoritative source.</td></tr></tbody></table></div>
<h3>Role Claim</h3>
<p>The canonical <strong>subject</strong>-level role claim is <code>roles</code>, an array of strings. This is distinct from <code>tenant_roles</code> (below) — a subject's own coarse identity roles are not the same fact as which capability roles the subject's tenant holds.</p>
<p>Expanded-mode Keycloak deployments may also expose provider-native roles such as <code>realm_access.roles</code>, but conforming tokens consumed by flex-auth or applications MUST either emit <code>roles</code> directly or pass through a normalizing adapter that produces <code>roles</code>.</p>
<h3>Scope Vocabulary</h3>
<p>The core profile defines only OAuth/OIDC base scopes:</p>
<div class="scroll"><table><thead><tr><th>Scope</th><th>Meaning</th></tr></thead><tbody><tr><td><code>openid</code></td><td>Required for OIDC login</td></tr><tr><td><code>profile</code></td><td>Basic profile claims</td></tr><tr><td><code>email</code></td><td>Email claim where appropriate</td></tr><tr><td><code>offline_access</code></td><td>Refresh-token capable access where explicitly allowed</td></tr></tbody></table></div>
<p>Hub-, application-, and resource-specific scopes such as <code>hub:*</code>, <code>ops:*</code>, <code>fin:*</code>, or storage actions are downstream extensions. They are valid only when the consuming system defines them and maps them to flex-auth resource/action semantics.</p>
</section>
<section id="tenant-claim"><h2>Tenant Claim</h2>
<p><code>tenant</code> is required for every token accepted by profile consumers.</p>
<p>Tenant identifiers follow <code>tenant:&lt;grouping&gt;:&lt;name&gt;</code>, where <code>&lt;grouping&gt;</code> is one of the taxonomy ratified by ADR-0013 at identifier creation:</p>
<pre>trial - test/trial/showcase tenants only
friendly - known, easily reached, tolerant of experimentation/instability
single - one-person business entities (freelance consultants)
small - up to 10 employees at time of onboarding (attoo)
medium - up to 100 employees (attoo)
large - up to 1000 employees (attoo)
enterprise - 1001+ employees (attoo)
consumer - private individuals
family - a legal family
community - a non-legal group of people
association - a legal association of people
agentic - financially enabled AI entities</pre>
<p><code>tenant:platform</code> and <code>tenant:coulomb</code> remain <strong>reserved, ungrouped</strong> identifiers outside this taxonomy: <code>tenant:platform</code> is the platform control-plane tenant, not a business entity being onboarded; <code>tenant:coulomb</code> is the first internal/reference tenant established by ADR-0006, predating this taxonomy. Tenant administration for <code>tenant:coulomb</code> or any grouped tenant must never imply platform-root authority.</p>
<p>Subjects may have access to multiple tenants, but a token used for a request MUST identify the tenant context for that request. If a client needs to switch tenant context, it obtains a new token or uses an approved token-exchange flow that records the target tenant.</p>
<p>The grouping segment is an immutable record of the tenant's <strong>onboarding-time</strong> onboarding-risk / entity-shape classification. It remains vocabulary-valid but becomes historical if the tenant's classification later changes. The authoritative current grouping is the <code>grouping</code> field held by <code>tenant-engine</code>; consumers MUST NOT split <code>tenant</code> and treat its middle segment as current policy input. Changing current grouping never renames the tenant. Neither the historical segment nor current grouping gates which capability roles (below) a tenant may hold — see Tenant Roles.</p>
</section>
<section id="tenant-roles"><h2>Tenant Roles</h2>
<p>Tenant <strong>capability roles</strong> are a separate fact from the grouping above and from the subject-level <code>roles</code> claim: <code>PLTF</code>, <code>IAM</code>, <code>VEN</code>, <code>CUS</code> (ratified by ADR-0014), non-exclusive — a tenant may hold several simultaneously, and holding one does not require or restrict any grouping.</p>
<p><strong>Source of truth:</strong> <code>tenant-engine</code> (<code>canon/standards/tenant-engine-boundary-contract_v0.1.md</code>), not this profile and not any token. <code>tenant-engine</code> records role grants/revocations, their link (if any) to a plan/subscription, and emits domain events on change.</p>
<p><strong>Carrying mechanism — hybrid, not claim-only:</strong></p>
<ul><li><code>key-cape</code> (or Keycloak) MAY stamp a cached <code>tenant_roles</code> claim onto an issued token at issuance time, sourced from <code>tenant-engine</code>.</li><li>Consumers MAY trust the cached claim for ordinary, non-privileged decisions.</li><li>Consumers <strong>MUST NOT</strong> trust the cached claim for privileged, destructive, platform-root, secret, credential-vending, or otherwise <code>assurance.level &gt;= aal2</code>-class decisions. Those decisions <strong>MUST</strong> query <code>tenant-engine</code> live for current role state before authorizing the action.</li><li>This bounds staleness for ordinary actions to the issuing token's lifetime (5-30 minutes for service/agent tokens, see Token Lifecycle) while guaranteeing freshness exactly where a stale grant (e.g. <code>VEN</code> surviving a plan cancellation) would matter most.</li></ul>
<p><code>trial</code>-grouped tenants may hold any capability role without restriction — the grouping exists to showcase, test, and explore every role. Safety for <code>trial</code> tenants is enforced through <code>tenant-engine</code>-owned resource guardrails (spend limits, entity/action counts — reserved, not yet specified), not through role gating.</p>
</section>
<section id="assurance-evidence"><h2>Assurance Evidence</h2>
<p>The canonical assurance claim is <code>assurance</code>.</p>
<p>It is an object with these fields:</p>
<div class="scroll"><table><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>level</code></td><td>string</td><td><code>aal0</code>, <code>aal1</code>, <code>aal2</code>, <code>aal3</code>, or <code>break_glass</code></td></tr><tr><td><code>methods</code></td><td>array</td><td>Authentication methods, e.g. <code>pwd</code>, <code>otp</code>, <code>webauthn</code>, <code>client_secret</code>, <code>workload_identity</code>, <code>upstream_mfa</code></td></tr><tr><td><code>mfa</code></td><td>boolean</td><td>Whether the authentication included multiple factors or equivalent upstream evidence</td></tr><tr><td><code>source</code></td><td>string</td><td>Provider of the evidence, e.g. <code>key-cape</code>, <code>keycloak</code>, <code>privacyidea</code>, <code>entra</code>, <code>local-identity</code></td></tr><tr><td><code>at</code></td><td>number</td><td>Authentication time, recommended</td></tr></tbody></table></div>
<p>Level meanings:</p>
<div class="scroll"><table><thead><tr><th>Level</th><th>Meaning</th></tr></thead><tbody><tr><td><code>aal0</code></td><td>Local/dev or unauthenticated bootstrap evidence; never production privileged</td></tr><tr><td><code>aal1</code></td><td>Single-factor or service credential evidence</td></tr><tr><td><code>aal2</code></td><td>MFA or equivalent strong upstream assurance</td></tr><tr><td><code>aal3</code></td><td>Phishing-resistant or hardware-backed assurance</td></tr><tr><td><code>break_glass</code></td><td>Time-bounded emergency access with post-event review</td></tr></tbody></table></div>
<p>Privileged, destructive, platform-root, secret, credential-vending, and emergency flows require <code>aal2</code> or stronger unless a policy explicitly permits a narrower service or workload identity path. Emergency access MUST use <code>break_glass</code> and short token lifetimes. This is the same threshold class that gates when <code>tenant_roles</code> MUST be re-validated live against <code>tenant-engine</code> rather than trusted from the token — see Tenant Roles.</p>
<p>Provider-native claims such as <code>acr</code> and <code>amr</code> may be present, but consumers use <code>assurance</code> as the normalized profile claim.</p>
</section>
<section id="identity-to-authorization-contract"><h2>Identity To Authorization Contract</h2>
<p>flex-auth consumes IAM Profile tokens as normative identity input. flex-auth MUST NOT re-derive identity, tenant, group, role, or assurance facts from provider-specific session state.</p>
<p>The profile guarantees these inputs for authorization decision envelopes:</p>
<div class="scroll"><table><thead><tr><th>Decision input</th><th>Source claim</th></tr></thead><tbody><tr><td>Subject</td><td><code>sub</code></td></tr><tr><td>Issuer</td><td><code>iss</code></td></tr><tr><td>Audience</td><td><code>aud</code></td></tr><tr><td>Tenant</td><td><code>tenant</code></td></tr><tr><td>Principal type</td><td><code>principal_type</code></td></tr><tr><td>Groups</td><td><code>groups</code></td></tr><tr><td>Subject roles</td><td><code>roles</code></td></tr><tr><td>Tenant capability roles</td><td><code>tenant_roles</code> (cached); <code>tenant-engine</code> live lookup required for high-stakes decisions</td></tr><tr><td>Scopes</td><td><code>scope</code> or <code>scp</code></td></tr><tr><td>Assurance</td><td><code>assurance</code></td></tr><tr><td>Authorized client</td><td><code>azp</code> or <code>client_id</code>, where present</td></tr><tr><td>Agent/delegation context</td><td><code>agent</code>, <code>actor_sub</code>, or <code>act</code>, where present</td></tr><tr><td>Token lifetime/audit ids</td><td><code>iat</code>, <code>nbf</code>, <code>exp</code>, <code>jti</code>, where present</td></tr></tbody></table></div>
<p>Authorization decisions are made by flex-auth and its delegated PDP adapters. Identity providers may assert roles or scopes, but those claims are inputs to policy, not final permission to act on a resource.</p>
</section>
<section id="token-lifecycle"><h2>Token Lifecycle</h2>
<p>Recommended production defaults:</p>
<div class="scroll"><table><thead><tr><th>Token</th><th>Lifetime</th><th>Notes</th></tr></thead><tbody><tr><td>Human access token</td><td>5-15 minutes</td><td>Short-lived bearer token</td></tr><tr><td>Refresh token</td><td>8-12 hours</td><td>Rotated and revoked on logout or suspicion</td></tr><tr><td>Service token</td><td>5-30 minutes</td><td>Reissued by client credentials or workload identity</td></tr><tr><td>Agent token</td><td>5-30 minutes</td><td>Shorter when delegated or platform-scoped</td></tr><tr><td>Emergency token</td><td>5-15 minutes</td><td>Requires incident/review record</td></tr></tbody></table></div>
<p>Consumers MUST reject expired tokens and tokens with invalid issuer, audience, signature, <code>nbf</code>, or algorithm. Clock skew tolerance SHOULD be small, normally no more than 60 seconds.</p>
<p>JWKS material may be cached, but consumers MUST tolerate key rotation by refreshing JWKS when a token uses an unknown <code>kid</code>.</p>
</section>
<section id="local-development-profile"><h2>Local Development Profile</h2>
<p>A local file-backed provider may be used for development, tests, and bootstrap contexts where the full platform is unavailable.</p>
<p>It MUST:</p>
<ul><li>expose OIDC discovery;</li><li>issue signed JWTs;</li><li>support deterministic test users and service accounts;</li><li>use local-only issuer URLs or a clearly local issuer identifier;</li><li>mark tokens as local/development through issuer, audience, or assurance evidence;</li><li>be rejected by production consumers.</li></ul>
<p>Production consumers MUST reject:</p>
<ul><li>issuer <code>local-identity</code>;</li><li><code>http://</code> issuers;</li><li>loopback issuers such as <code>localhost</code> or <code>127.0.0.1</code>;</li><li>tokens with <code>assurance.level: aal0</code>;</li><li>tokens where the environment marks the issuer as local/dev.</li></ul>
</section>
<section id="emergency-and-break-glass-access"><h2>Emergency And Break-Glass Access</h2>
<p>Emergency access is allowed only as a break-glass path.</p>
<p>Requirements:</p>
<ul><li>Emergency identities are disabled by default.</li><li>Activation requires an incident, decision, or human-recorded review reference.</li><li>Tokens are short-lived and carry the <code>emergency</code> role.</li><li>Tokens carry <code>assurance.level: break_glass</code>.</li><li>Every emergency action emits an audit/progress/incident event.</li><li>Emergency access is reviewed after use and then disabled again.</li></ul>
<p>Emergency access MUST NOT bypass audit logging or flex-auth policy.</p>
</section>
<section id="conformance"><h2>Conformance</h2>
<p>An implementation conforms to IAM Profile v0.3 when it passes the executable conformance suite in:</p>
<pre>tools/iam-profile-conformance/</pre>
<p>The suite validates:</p>
<ul><li>discovery document completeness;</li><li>PKCE <code>S256</code> advertisement and rejection of authorization requests that omit a code challenge;</li><li>JWKS structure and key ids;</li><li>token issuer, audience, expiry, <code>nbf</code>, <code>iat</code>, and RS256 signature;</li><li>tenant, principal type, groups, roles, scopes, and assurance claim shape;</li><li><code>tenant_roles</code> claim shape when present (array of ratified role strings);</li><li>agent and delegated-agent claim shape;</li><li>local-development issuer rejection in production mode.</li></ul>
<p>Conformance must be runnable against both key-cape lightweight issuers and Keycloak expanded-mode issuers. Implementations may add provider adapters, but the token consumed by applications and flex-auth must match the core claim contract above. <code>tenant_roles</code> conformance does not require an implementation to emit the claim (it is optional); when emitted, it must match the ratified vocabulary.</p>
</section>
<section id="validation-checklist"><h2>Validation Checklist</h2>
<p>A service or implementation is profile-ready when:</p>
<ul><li>it reads OIDC discovery rather than hardcoding endpoints;</li><li>it validates issuer, audience, expiry, <code>nbf</code>, algorithm, and signature;</li><li>it refreshes JWKS on unknown <code>kid</code>;</li><li>it supports Authorization Code + PKCE for human login;</li><li>it supports service-account or workload identity tokens;</li><li>it emits <code>tenant</code>, <code>principal_type</code>, <code>groups</code>, <code>roles</code>, <code>scope</code>/<code>scp</code>, and <code>assurance</code>;</li><li>it uses the ADR-0013 grouping vocabulary for new tenant identifiers;</li><li>if it consumes <code>tenant_roles</code>, it treats the claim as a cache and re-validates live against <code>tenant-engine</code> before any <code>aal2</code>-class decision;</li><li>it maps provider-native claims into the canonical core claims;</li><li>it rejects local-development issuers in production;</li><li>it logs emergency access with a durable audit trail;</li><li>flex-auth receives identity facts from the profile, not from provider-specific sessions.</li></ul>
</section><footer><span>netkingdom-iam-profile-v0.3 · accepted-1 · accepted</span><span>net-kingdom · canon/standards/iam-profile_v0.3.md · d4e57e63126d2cca1d381c025170e4b1f678c3f3</span></footer></main></div></div></html>

224
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-posture-feedback-v0.1.html Normal file
View file

@ -0,0 +1,224 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="dd2628b9f0c2a662ac44af22657d91918da228f307ebc7ceb09fc856162985db">
<title>NetKingdom Posture Feedback v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-posture-feedback-v0.1</span> <span class="stat">proposed</span> <span>net-kingdom</span> <span>reviewed 2026-08-23</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Posture Feedback v0.1</h1><p class="sub">Source: <code>net-kingdom · canon/standards/posture-feedback_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2026-11-23</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#s1"><span class="n">1</span>Purpose</a></li><li><a href="#s2"><span class="n">2</span>Deterministic time</a></li><li><a href="#s3"><span class="n">3</span>Owner resolution</a></li><li><a href="#s4"><span class="n">4</span>Finding classes</a></li><li><a href="#s5"><span class="n">5</span>Proposal and safety boundary</a></li><li><a href="#s6"><span class="n">6</span>Exit behavior</a></li></ol></nav><main><section id="s1"><h2><span class="sn">01</span>Purpose</h2>
<p>This contract is the first bounded C6 feedback mechanism. It turns explicit posture review dates, evidence freshness, implemented-but-unevidenced controls, and declared gaps into deterministic remediation <strong>proposals</strong>.</p>
<p>It does not modify a posture level, policy, declaration, workplan, State Hub, or runtime. Human or separately governed automation decides whether a proposal becomes work.</p>
</section>
<section id="s2"><h2><span class="sn">02</span>Deterministic time</h2>
<p>Evaluation requires an explicit RFC 3339 <code>as_of</code> timestamp. Wall-clock time is never read implicitly. A date-only <code>review_due</code> remains current through that calendar date in UTC and becomes overdue on the following UTC date.</p>
<p>A non-negative horizon in days identifies items due soon. Changing the horizon changes the report digest and is therefore visible.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>Owner resolution</h2>
<p>The evaluator routes only from authoritative declaration fields:</p>
<ul><li>posture review, gaps, and implemented controls: <code>responsible_repo</code>;</li><li>evidence replacement: <code>evidence_freshness.&lt;level&gt;.responsible_repo</code>;</li><li>security-zone review: <code>zones.responsible_party</code>.</li></ul>
<p>If the relevant field is absent, owner resolution is <code>unknown</code>. The evaluator must not infer ownership from the service name, repository path, Git remote, previous work, or another policy subject.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Finding classes</h2>
<div class="scroll"><table><thead><tr><th>Finding</th><th>Trigger</th><th>Severity</th></tr></thead><tbody><tr><td><code>posture-review-overdue</code></td><td><code>as_of</code> is after <code>tenancy.review_due</code></td><td>high</td></tr><tr><td><code>posture-review-due-soon</code></td><td>review is within the horizon</td><td>medium</td></tr><tr><td><code>zone-review-overdue</code></td><td><code>as_of</code> is after <code>zones.review_due</code></td><td>high</td></tr><tr><td><code>zone-review-due-soon</code></td><td>zone review is within the horizon</td><td>medium</td></tr><tr><td><code>evidence-freshness-unknown</code></td><td>a current adversarial level has no complete freshness entry</td><td>high</td></tr><tr><td><code>evidence-expired</code></td><td><code>as_of</code> is after <code>valid_until</code></td><td>high</td></tr><tr><td><code>evidence-due-soon</code></td><td>evidence expires within the horizon</td><td>medium</td></tr><tr><td><code>implemented-not-evidenced</code></td><td>an <code>implemented</code> level is above <code>current</code></td><td>medium</td></tr><tr><td><code>declared-gap</code></td><td>a non-empty <code>tenancy.gap</code> entry exists</td><td>low</td></tr></tbody></table></div>
<p>The review horizon does not generate a due-soon finding for an item already overdue or expired. Exact equality with a timestamp is still valid; expiry is strictly <code>as_of &gt; valid_until</code>.</p>
<p>Current adversarial levels are <code>E2</code>, <code>R4</code>, and <code>V2</code>–<code>V4</code>. This vocabulary comes from Tenancy Posture §13. Mechanical evidence is evaluated for expiry only when its declaration explicitly supplies <code>valid_until</code>.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Proposal and safety boundary</h2>
<p>Every finding receives a stable id derived from its source declaration, service, finding class, control, and due value. It contains the authoritative owner or <code>unknown</code>, current evidence state, reason, and recommended action. For declarations under the workspace containing this repository, the source is normalized to <code>&lt;repo&gt;/&lt;path&gt;</code> so absolute checkout locations do not perturb the identity. This source normalization identifies an input only; it is never an ownership inference.</p>
<p>Every report declares:</p>
<pre>automation:
mode: proposal-only
external_write_permitted: false
policy_mutation_permitted: false
declaration_mutation_permitted: false</pre>
<p>Expired or unknown evidence does not silently inherit freshness and does not silently downgrade a level. It makes the uncertainty visible for governed review. Consumers that use the report as an admission gate may fail closed on high findings, but that is a separate owner decision.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Exit behavior</h2>
<p>The CLI emits a report conforming to <code>posture-feedback-report_v0.1.schema.json</code>. <code>--fail-on high</code> exits non-zero when at least one high-severity finding exists; <code>medium</code> includes medium and high; <code>low</code> includes every finding; <code>none</code> reports without a finding-based failure. Invalid declarations always exit non-zero.</p>
</section><footer><span>netkingdom-posture-feedback-v0.1 · · proposed</span><span>net-kingdom · canon/standards/posture-feedback_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

461
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-security-layer-model-v0.7.html Normal file
View file

@ -0,0 +1,461 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="8155e7b123be1e84377d8278525b1bad8961007b6bb8ff012dd01ba24ff8065b">
<title>NetKingdom Security Layer Model v0.7</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-security-layer-model-v0.7</span> <span class="stat">accepted</span> <span>gate-house</span> <span>reviewed 2026-08-28</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Security Layer Model v0.7</h1><p class="sub">Source: <code>net-kingdom · canon/standards/security-layer-model_v0.7.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2026-11-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#s1"><span class="n">1</span>Purpose</a></li><li><a href="#s2"><span class="n">2</span>Authority and conformance</a></li><li><a href="#s3"><span class="n">3</span>The layers</a></li><li><a href="#s4"><span class="n">4</span>Layer catalog</a></li><li><a href="#s5"><span class="n">5</span>The binding rule</a></li><li><a href="#s6"><span class="n">6</span>One decision point</a></li><li><a href="#s7"><span class="n">7</span>Relationship to the Active Secrets Management Canon</a></li><li><a href="#s8"><span class="n">8</span>Vocabulary demarcations</a></li><li><a href="#s9"><span class="n">9</span>Capability assignment</a></li><li><a href="#s10"><span class="n">10</span>Changing layer</a></li><li><a href="#s11"><span class="n">11</span>Conformance</a></li><li><a href="#s12"><span class="n">12</span>The conformance loop</a></li><li><a href="#s13"><span class="n">13</span>Open gaps</a></li><li><a href="#s14"><span class="n">14</span>Adoption</a></li><li><a href="#s15"><span class="n">15</span>Change log</a></li><li><a href="#s16"><span class="n">16</span>Open questions</a></li><li><a href="#s17"><span class="n">17</span>Taxonomy artifacts</a></li><li><a href="#s18"><span class="n">18</span>Composition with the sibling standards</a></li><li><a href="#s20"><span class="n">20</span>The Railiance interaction boundary</a></li></ol></nav><main><section id="s1"><h2><span class="sn">01</span>Purpose</h2>
<p>This standard states how NetKingdom's IT-security estate is layered, and what each layer may and may not do. It answers one question:</p>
<div class="rule-quote"><p><strong>Given a repository, which layer is it in, and what does that permit it to own?</strong></p></div>
<p>The layers are distinguished by <strong>determinism</strong> and by <strong>the kind of artifact the layer produces</strong>, not by technical tier, deployment topology, or team.</p>
<p>It is not an org chart, not a network model, not a deployment topology, and not a dependency graph. It does not assign work, and it does not replace any repository's boundary contract; it constrains what such a contract may claim.</p>
<p><strong>What changed in v0.7.</strong> v0.6 announced a rule it never wrote: §1 and §15 said the standard separates human and agent principals inside Staff, and §3.4 was byte-identical to v0.5. <code>kings-guard</code> found it and put it correctly — <em>a rule stated about a standard in its own change log is not a rule</em>, which is §11's own principle turned on the standard. §3.4 is now written.</p>
<p>The rest are collisions between rules written for the clean case: §6.4's first obligation forbade what its third obligation blesses, and its second forbade the session-bound allow §9.7.1 permits. §9.4's atomicity was described as closing a threat it does not close. §19 graded the document it lived in. And §20 records the interaction boundary with Railiance operations, on definitions from <code>railiance-master</code> rather than inference. §15 records the change list.</p>
<p><strong>What changed in v0.6.</strong> An independent assessment against industry practice (<code>net-kingdom/history/2026-08-29-layering-standard-assessment.md</code>) found the model sound as a layering constitution and incomplete as a <em>self-healing</em> one: cognition, authority, and execution are specified, but the two verbs that close a healing loop — observe in production and actuate through a deterministic surface — are pending, and one is unstaffed. It also found the Engine layer untyped, so that "we need an engine for X" drifts toward "X now decides", and the enforcement point unnamed.</p>
<p>v0.6 types the engines (§3.3), names the enforcement point (§6.4), replaces the containment assignment with an actuation surface held at zero (§9.2), separates human and agent principals inside Staff (§3.4), puts time into the model (§9.7), requires the Taxonomy artifacts that make §6.2 compileable rather than reviewable (§17), and composes the sibling standards it had only cited (§18). Section numbers below §14 are unchanged: the estate cites them.</p>
<p><strong>What changed in v0.5.</strong> All four reviewing repositories returned findings on v0.4, and one contested a rule. §9.3 was wrong: it collapsed <em>engine reachable but degraded</em> with <em>engine not reachable at all</em>, and the second case has no evaluator in the path to express anything. §9.1 collapsed <em>no route exists</em> with <em>route exists under a declared gap</em>, which would have forced a false "pending" onto a production capability. §11 claimed mechanical checkability for a rule that cannot be checked in prose. §13 filed two opposite conformance states in one table and recorded proposed owners as owners. §9.6 needed the load-bearing distinction it implied but never drew. §15 records the change list.</p>
<p><strong>What changed in v0.4.</strong> <code>audit-core</code> assented to the approval evidence half and corrected the rationale twice. v0.3 rested §9.4 on that repository's INTENT principle 6, which is an aspiration; the shipped bound in its <code>docs/integrity.md</code> is weaker and conditional. More consequentially, no append-only archive can prove <strong>omission at source</strong> — a suppressed revocation leaves the chain intact — which is now stated as an estate-wide doctrine constraint (§9.6) rather than left implicit. <code>audit-core</code> was also referenced as an owner in v0.3 without appearing in the §4 catalog at all; it is catalogued here, as an Engine, on its own declaration. §15 records the change list.</p>
<p><strong>What changed in v0.3.</strong> Two engines were seeded to own concepts v0.2 recorded as unowned: <code>approval-engine</code> takes the approval object that §13 left homeless, and <code>maturity-engine</code> takes graded progression — closing a §9.1 defect in gate-house's own catalog claim, which asserted conformance review with no engine to act through. §15 records the change list. v0.3 is <strong>proposed</strong>: the two new engines are seeded by owner direction and have no other side to assent yet, and the evidence half of the approval split needs <code>audit-core</code>'s assent.</p>
<p><strong>What changed in v0.2.</strong> v0.1 was assented to by all three repositories whose boundaries moved, and each returned a finding. v0.1 had one lane for a Staff repository that legitimately touches Tooling — read-only diagnostics — which is narrower than the estate as it actually stands, and a rule with no lane for a real sanctioned case is satisfied by relabelling rather than by closing the gap. v0.1 also catalogued a capability (§4, containment) that §5 forbade discharging, and applied its reconstructability test to engines but not to the doctrine gate-house feeds them. §15 records the full change list.</p>
</section>
<section id="s2"><h2><span class="sn">02</span>Authority and conformance</h2>
<div class="scroll"><table><thead><tr><th>Fact or rule</th><th>Authority</th></tr></thead><tbody><tr><td>The layers, their definitions, and the rules between them</td><td>This standard, owned by gate-house</td></tr><tr><td>Which layer a given repository is in</td><td>This standard, §4 catalog</td></tr><tr><td>What a repository owns within its layer</td><td>That repository's <code>INTENT.md</code> and boundary contract</td></tr><tr><td>Whether a specific request is permitted</td><td><code>access-engine</code> — never this standard</td></tr><tr><td>Whether a Tooling contact is sanctioned</td><td>The declaring repository, under the shapes in §5, reviewable by gate-house</td></tr><tr><td>Security doctrine and invariants</td><td>gate-house</td></tr><tr><td>Publication</td><td>net-kingdom canon</td></tr><tr><td>Whether an invariant is <em>watched in practice</em></td><td>the observing repository's own report — never this standard, and never §12's diagram</td></tr></tbody></table></div>
<p>A repository conforms when its <code>INTENT.md</code> declares its layer, its claims fall within that layer's permissions (§3), and its Tooling contacts take one of the sanctioned shapes in §5 or are declared as gaps under §5.3.</p>
<p><strong>No estate argument may cite observation that has not happened.</strong> §12 lists <code>kings-guard</code> against the loop's fourth step, and that repository has reported that it has never observed a real event. Until it reports otherwise, no assessment, review, or decision in this estate may treat an invariant as being watched in practice on the strength of the diagram. Lifted here from §12 so it cannot be lost in a summary.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>The layers</h2>
<div class="scroll"><table><thead><tr><th>Layer</th><th>Character</th><th>Produces</th><th>Deterministic</th></tr></thead><tbody><tr><td><strong>Taxonomy</strong></td><td>cross-cutting language</td><td>terms, semantic contracts, standards</td><td>n/a — describes</td></tr><tr><td><strong>Tooling</strong></td><td>infrastructure and state</td><td>data structures, persistence</td><td>yes</td></tr><tr><td><strong>Engines</strong></td><td>interfaces for a modeled concept</td><td>APIs, contracts</td><td>yes</td></tr><tr><td><strong>Staff</strong></td><td>management, operations, change, controlling</td><td>specifications, decisions, workplans, tasks</td><td><strong>no</strong></td></tr></tbody></table></div>
<h3>3.1 Taxonomy</h3>
<p>Cross-cutting language. Taxonomy repositories define terms and semantic contracts so the other layers interoperate without integration by interpretation. They own no runtime position and no state any layer depends on.</p>
<p><code>info-tech-canon</code> holds ecosystem-wide semantic contracts. NetKingdom-specific security architecture — including this standard — is net-kingdom canon's.</p>
<h3>3.2 Tooling</h3>
<p>Deterministic infrastructure: data structures, persistence, and the consistent, performant, scalable keeping of state. Much of it is third-party.</p>
<h3>3.3 Engines</h3>
<p>Deterministic APIs for a modeled concept — a user, a tenant, a zone, a secret, an access rule. An engine's defining property is that <strong>the same authoritative input state yields the same result</strong>. Engines are where the estate's deterministic guarantees live, and therefore where every enforcement boundary MUST sit.</p>
<p>A repository whose core function is inference or judgment fails this test by construction and is Staff, however much of its work happens at runtime.</p>
<p><strong>Engines are typed.</strong> "Engine" is one layer but four roles, and collapsing them hides different failure modes. Every §4 Engine row carries a role:</p>
<div class="scroll"><table><thead><tr><th>Role</th><th>Meaning</th><th>Outage means</th></tr></thead><tbody><tr><td><strong>PDP</strong></td><td>renders the authorization decision — <code>access-engine</code>, and only it (§6)</td><td>consumer residue (§9.3)</td></tr><tr><td><strong>PIP</strong></td><td>supplies facts a decision consumes as claims — user, tenant, zone, approval, maturity</td><td>input degradation, engine's own fallback (§9.3)</td></tr><tr><td><strong>Evidence</strong></td><td>records what happened and proves integrity of what it holds — <code>audit-core</code></td><td>MUST NOT block the operation being recorded — a default, not a property; see below</td></tr><tr><td><strong>Lifecycle</strong></td><td>a deterministic API over Tooling it owns — <code>secrets-engine</code></td><td>the owning engine's failure semantics</td></tr></tbody></table></div>
<p>The roles are why <em>"we need an engine for X"</em> does not mean <em>"X now decides"</em>. A new engine is a PIP unless this standard is amended to say otherwise, and §6 means it can never be a second PDP.</p>
<p>The Evidence row's outage rule is an estate <strong>trade</strong>, not a property of evidence engines. Choosing availability there means accepting that a compromised source can suppress a record and that detection is the answer (§9.6). The opposite shape — <em>do not proceed unless an independent custodian already holds the record</em> — is the only one that puts evidence outside the actor's blast radius <strong>before</strong> the act. The estate has not needed it, so it is not ruled out by a table cell: an operation whose control genuinely requires independent recording before effect is a declared exception, raised when needed. Raised by <code>audit-core</code> against its own row.</p>
<p>The industry vocabulary is deliberately mirrored here — PDP, PIP, PEP as in NIST ZTA and XACML — because it is how the estate talks to the outside and how a PEP is stopped from quietly becoming a PDP. The determinism cut in §3 stays primary where the two disagree.</p>
<h3>3.4 Staff</h3>
<p>Interactive and non-deterministic. Staff is the management layer: operations, change, innovation, and controlling. It works through agentic capability — assistants and autonomous agents — and its artifacts are specifications, decisions, workplans, and tasks.</p>
<p>Staff repositories MUST NOT hold state that another layer depends on at runtime, and MUST NOT render or cache any decision an Engine is responsible for.</p>
<p>Acting at runtime does not make a repository an Engine. Being agentic makes it Staff, and §5 governs how it acts.</p>
<p><strong>Two principals, one layer.</strong> Humans and agents are both non-deterministic and both Staff, so they share the layer's permissions. They do not share blast radius. Four rules bind the agent principal specifically:</p>
<ol><li><strong>No standing credential.</strong> An agent holds no long-lived credential of its own. Authority is issued per task, time-bounded under §9.7, and attributable to the principal on whose behalf it acts.</li><li><strong>Tool use is a conduit or an Engine API.</strong> An agent acts through §5.2 — the owner's tool under the caller's identity, presenting no authority of its own — or through an engine. There is no third route. Tool availability is not permission: a callable tool means the operation exists, not that this actor may invoke it.</li><li><strong>Agent memory is not a state plane.</strong> Agent memory, tool-call traces, and prompt caches are the agent's own. They MUST NOT become state another layer depends on at runtime unless catalogued as Tooling in §4, which subjects them to §5 like anything else, and to §5's sunset.</li><li><strong>Every agent action is reconstructable as the caller's action</strong>, bounded by §9.6 — the archive shows the actions it received, not that it received all of them.</li></ol>
<p>Session semantics — session loops, tool policy, harness routing, model selection — are <strong>not</strong> governed here. They belong to <code>glas-harness</code> and its <code>rein-*</code> backends (§20). This standard governs what an agent may be authorized to do; <code>glas-harness</code> governs how an agent session is conducted. Rule 2 is the seam between them, and neither side may treat its own half as sufficient.</p>
<p>v0.6 claimed these rules in its change log and did not write them. Found by <code>kings-guard</code>, which is the repository they bind hardest and which offered to assent to them sight-unseen.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Layer catalog</h2>
<div class="scroll"><table><thead><tr><th>Repository</th><th>Layer</th><th>Role</th><th>Owns</th></tr></thead><tbody><tr><td><code>info-tech-canon</code></td><td>Taxonomy</td><td>—</td><td>ecosystem-wide semantic contracts and terminology</td></tr><tr><td><code>net-kingdom</code></td><td>Taxonomy</td><td>—</td><td>NetKingdom standards of record; publication</td></tr><tr><td><code>key-cape</code></td><td>Tooling</td><td>—</td><td>packaged identity tooling; IAM profile; authentication</td></tr><tr><td><code>OpenBao</code></td><td>Tooling</td><td>—</td><td>secret storage, leases, PKI, dynamic secret engines</td></tr><tr><td><code>user-engine</code></td><td>Engine</td><td>PIP</td><td>users, accounts, memberships</td></tr><tr><td><code>tenant-engine</code></td><td>Engine</td><td>PIP</td><td>tenant-as-an-entity facts</td></tr><tr><td><code>zone-engine</code></td><td>Engine</td><td>PIP</td><td>zone identity and membership — offline reference conformance per its 2026-08-23 disposition</td></tr><tr><td><code>secrets-engine</code></td><td>Engine</td><td>Lifecycle</td><td>credential abstraction, custody, lifecycle</td></tr><tr><td><code>audit-core</code></td><td>Engine</td><td>Evidence</td><td>audit event custody, retention, integrity verification, export — explicitly not a decision point (§9.6)</td></tr><tr><td><code>access-engine</code></td><td>Engine</td><td><strong>PDP</strong></td><td><strong>the policy decision</strong> — the only decision point (§6)</td></tr><tr><td><code>approval-engine</code></td><td>Engine</td><td>PIP</td><td>the approval object — durable, authenticated, consumable, atomically supersedable (§9.4)</td></tr><tr><td><code>maturity-engine</code></td><td>Engine</td><td>PIP</td><td>graded progression against declared criteria and evidence; the gap register; capability readiness (§9.5)</td></tr><tr><td><code>gate-house</code></td><td>Staff</td><td>—</td><td>security doctrine, authority context, curriculum; <strong>conformance review — through <code>maturity-engine</code> (§9.5)</strong></td></tr><tr><td><code>ops-mason</code></td><td>Staff</td><td>PEP-shaped</td><td>building and tearing down access routes and perimeters</td></tr><tr><td><code>ops-warden</code></td><td>Staff</td><td>PEP-shaped</td><td>operational access lanes, stewardship, runbooks; SSH certificate issuance — <strong>declared-gap</strong> (§9.1, §13)</td></tr><tr><td><code>kings-guard</code></td><td>Staff</td><td>—</td><td>adaptive defence and judgment; observation of Staff-reachable sources — identity and secret observation <strong>pending</strong>; <strong>proposes</strong> containment, which it does not own (§9.2)</td></tr><tr><td><code>whitehat-security</code></td><td>Staff</td><td>—</td><td>offensive validation</td></tr></tbody></table></div>
<p>An <strong>actuation surface</strong> — reduce authority, require step-up, isolate a workload — is catalogued nowhere because it does not exist. See §9.2: it is an Engine concept held at zero, not a Staff capability.</p>
<p><code>access-engine</code> is the ruled name for the repository currently called <code>flex-auth</code>; both denote the same authority until the governed rename completes. Execution conditions for that rename are recorded in its migration decision, not here.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>The binding rule</h2>
<div class="rule-quote"><p><strong>Staff never touches Tooling directly. It acts only through Engine APIs.</strong></p></div>
<p>A Staff repository MUST NOT hold a direct client for a Tooling-layer system — no direct database connection, no direct OpenBao client, no direct cluster mutation — outside the shapes below. This is the architectural form of <em>no privilege from cognition</em>, and it is deliberately mechanically checkable.</p>
<p><strong>Scope.</strong> "Tooling-layer system" means a system catalogued as Tooling in §4. Infrastructure the estate runs but has not catalogued — the State Hub, <code>llm-connect</code>, and similar — is outside this rule, because a rule that silently covered them would put every Staff repository in undeclared violation on adoption day: they all write progress events. Such clients SHOULD be recorded in the repository's declaration as non-Tooling for completeness of the check, and the way to bring one under §5 is to catalogue it in §4, deliberately.</p>
<p>Raised by <code>ops-warden</code>, which held clients for both and declined to resolve the scope question on gate-house's behalf.</p>
<p><strong>The carve-out sunsets.</strong> It is a pressure valve, and a valve left open becomes a second persistence plane under the Staff layer — which §3.4 forbids in spirit. Three rules bound it: every non-Tooling client MUST be listed in the repository's declaration; an uncatalogued store that another layer <strong>reads</strong> MUST, within two review intervals, either be catalogued as Tooling in §4 or be declared a gap under §5.3; and a Staff-owned event bus or memory store MUST NOT become the estate's de facto state plane. Today's instances are the State Hub and <code>llm-connect</code>; tomorrow's are agent memory, tool-call traces, and prompt caches (§3.4).</p>
<p>Three shapes are sanctioned. Everything else is a violation.</p>
<h3>5.1 Read-only diagnostic observation</h3>
<p>A Staff repository MAY read Tooling state for diagnostics where the owning engine exposes no equivalent. It MUST be declared in the repository's <code>INTENT.md</code>. It grants no write, and it is an engine gap to close, not a standing arrangement.</p>
<h3>5.2 Conduit</h3>
<p>A Staff repository MAY run the <strong>owner's</strong> tool under the <strong>caller's</strong> identity, supplying no authority of its own. The test is the supplied-authority property: the conduit MUST NOT present its own credential, MUST NOT widen what the caller could already do, and MUST be reconstructable as the caller's action in audit.</p>
<p>A conduit that presents its own token is not a conduit; it is §5.3 or a violation. This shape MUST be declared, and the no-authority property SHOULD be covered by a test.</p>
<p>The reconstructability requirement is an audit-dependent claim and is therefore bounded by §9.6: the archive shows the conduit actions it received, not that it received all of them.</p>
<h3>5.3 Declared engine gap</h3>
<p>Where a Staff repository must contact Tooling directly and no engine exposes the capability, it MUST declare the contact rather than take an exemption. A declared gap carries, machine-readably:</p>
<div class="scroll"><table><thead><tr><th>Field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>capability</code></td><td>what the contact does</td></tr><tr><td><code>intended_owner</code></td><td>the engine that should own it</td></tr><tr><td><code>blocked_on</code></td><td>why it cannot move today</td></tr><tr><td><code>review</code></td><td>a date, not "when convenient"</td></tr></tbody></table></div>
<p>A declared gap is <strong>tracked non-conformance</strong>, not conformance. It does not expire on its own and it is not a licence to add more. It exists because a rule offering no lane for a real sanctioned case gets satisfied by relabelling rather than by closing the gap — and a tracked gap is visible, whereas a relabelled one is not.</p>
<p>Prior art: <code>ops-warden</code> runs equivalent machinery for delegated lanes (27 catalog entries carrying <code>delegation:</code>, queryable via <code>warden route gaps</code>), and has offered it as reusable.</p>
<p><strong>No fourth "operator of third-party Tooling" shape.</strong> It has been proposed, on the argument that someone must operate <code>OpenBao</code> and every operational necessity otherwise looks like a gap. Declined: §5.3 already sanctions the operation while keeping it visible, and a clean "operator" shape would convert a tracked gap into a permanent allowance — the relabelling failure this standard exists to prevent. A permanent operational necessity is a declared gap whose review interval keeps returning, which is the correct amount of friction. If the review becomes ceremonial, that is an argument for closing the gap, not for renaming it.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>One decision point</h2>
<p><code>access-engine</code> is the only policy decision point in NetKingdom. No other repository, in any layer, may render or cache authorization decisions.</p>
<p>First ruled in <code>zone-engine/INTENT.md</code> §5 — <em>"flex-auth is the policy decision point. It stays the only one."</em> The failure mode, from the same source: <em>"It becomes a second decision point… it would arrive as a small convenience."</em></p>
<h3>6.1 Compiled data that determines an outcome is still deciding</h3>
<p>A registry, cache, or schema that resolves a result before the engine runs has decided early. Provenance MUST remain reconstructable from the engine's decision record.</p>
<h3>6.2 Doctrine reaches the decision as an input, or it is not applied</h3>
<p>This rule binds gate-house on the same terms. <strong>An authority ceiling, mandate constraint, or operating-mode restriction that determines an outcome MUST reach the decision either as an input claim on the request or as a rule in the versioned policy package</strong>, so that its application is reconstructable from the decision record.</p>
<p>Doctrine that influences outcomes by any other route is a second decision point wearing an author's hat. This is not a limit on gate-house's authorship; it is what keeps that authorship auditable at decision time.</p>
<h3>6.3 No Staff repository may host a decision point</h3>
<p>A deterministic authority boundary inside a non-deterministic layer contradicts the invariant the estate is built on. gate-house was re-cut on this ground.</p>
<h3>6.4 The enforcement point</h3>
<p>The standard has been precise about the decision and silent about the gate. A decision that nothing refuses to proceed without is advice.</p>
<p>A <strong>PEP</strong> is any runtime that causes a protected side effect. It is a <em>shape</em>, not a repository: <code>ops-warden</code> issuing a certificate, <code>ops-mason</code> opening a route, and any protected system acting on a verdict are all PEP-shaped. Being PEP-shaped does not move a repository out of its layer.</p>
<p>Four obligations, and they are normative:</p>
<ol><li><strong>No side effect without a decision record, or a recorded stance.</strong> A PEP MUST NOT perform the protected action unless it holds a decision from <code>access-engine</code> identifying the request it was rendered for, <strong>or</strong> its declared §9.3 stance for the applicable scope permits proceeding without one <strong>and the application of that stance is recorded in place of the decision</strong>. The second limb is stricter than silence, not looser: a fail-open result is metadata, never an absent record. <code>ops-warden</code> <code>ca.py</code> writes the zone, the failure mode, and a decision id present only where a decision was rendered.</li></ol>
<p>v0.6's unqualified form made the shipped stance §9.3 sanctions into a violation — the same defect as v0.5's §9.1, a rule written for the clean case producing a false result on the adjacent case already sanctioned elsewhere. Raised by <code>ops-warden</code>, which is the reference shape for limb two.</p>
<ol><li><strong>No recaching of the verdict beyond its own binding.</strong> A stored verdict replayed <strong>outside the decision's stated binding and lifetime</strong> is a second decision point deciding early (§6.1). Within them it is the decision being used as issued — a session-bound allow under §9.7.1 is used across later requests by construction, and v0.6 forbade what §9.7.1 permits.</li></ol>
<p>The test is mechanical, not a matter of implementer judgement: replay is permitted <strong>iff the canonical request digest matches and the decision's lifetime holds</strong>. <code>access-engine</code> computes that digest over normalised subject, action, resource, and context, and it is already in every decision binding. A retry after a transport failure is therefore the same request; a different resource is not.</p>
<p><strong>Negative caching is permitted, narrowly.</strong> A cached DENY cannot manufacture authority — §8's asymmetry holds — and protects against retry storms. It is permitted where the refusal is itself recorded against the request that was refused (obligation 4), and where the cache lifetime is declared alongside the stance map. A stale deny is an availability failure and will be misdiagnosed as a policy one, so it must be visible as what it is. Ruled explicitly because it is the first thing an implementer under load reaches for. Raised by <code>access-engine</code>.</p>
<ol><li><strong>A declared unreachable-engine stance</strong> (§9.3): total, per zone or equivalent scope, no implicit default, no per-call discretion, published rather than held in code comments or in a dataclass default. <code>ops-warden</code> <code>ADR-0009</code> and its <code>pep-stance.yaml</code> are the reference shape.</li></ol>
<p>The published map MUST equal the shipped behaviour, and that equality SHOULD be asserted by a test. A published map free to drift from the code is worse than none, because it invites reliance it cannot support. Raised by <code>ops-warden</code>, which found its own map unpublished while being cited as the reference for this obligation.</p>
<ol><li><strong>Reconstructability</strong>, bounded by §9.6.</li></ol>
<p>Every PEP-shaped consumer MUST publish its stance map at a path named in its layer declaration, and those maps MUST be inventoried in the §13.1 register until <code>maturity-engine</code> can hold them. §9.3 is otherwise a ruling with no register behind it, and <em>"<code>z0</code>–<code>z2</code> and unknown fail open"</em> becomes the estate's real policy without anyone having compiled it into a versioned package.</p>
<p>v0.6 named a register that did not exist — a requirement whose register is missing is a capability catalogued without a surface, by §9.1's own logic. Raised independently by <code>ops-warden</code> and <code>access-engine</code>; §13.1 now exists, and its first inventory has one row, which is itself the finding.</p>
<p>Raised by the 2026-08-29 independent assessment: NIST ZTA splits decide from enforce, and this standard had only the first half.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Relationship to the Active Secrets Management Canon</h2>
<pre>Staff interactive, non-deterministic ≈ Cognitive Plane
Engines deterministic APIs ≈ Authority Plane
Tooling deterministic state ≈ Execution Plane
Taxonomy cross-cutting language</pre>
<p><em>Cognition proposes. Authority disposes. Infrastructure executes.</em> is therefore NetKingdom's layering rule, not only its security maxim. §5 and §6 are that principle applied to repositories rather than to requests.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Vocabulary demarcations</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Belongs to</th><th>Not</th></tr></thead><tbody><tr><td><strong>access lane</strong></td><td>ops-warden, ops-mason (Staff) — how a worker reaches a host</td><td>the decision whether they may</td></tr><tr><td><strong>access rule</strong></td><td>access-engine (Engine) — whether an actor may act</td><td>the route by which they arrive</td></tr><tr><td><strong>control plane</strong></td><td>Engine layer</td><td>a Staff repository's self-description</td></tr><tr><td><strong>doctrine</strong></td><td>gate-house</td><td>a lane owner's runbook</td></tr><tr><td><strong>runbook</strong></td><td>the Staff repository stewarding the lane</td><td>a substitute for doctrine</td></tr><tr><td><strong>posture</strong></td><td>kings-guard publishes; gate-house defines its authority meaning; access-engine renders it</td><td>a privilege source</td></tr></tbody></table></div>
<p>Posture carries an asymmetry that MUST hold: adaptive systems may reduce authority, require step-up, or request containment. They MUST NOT probabilistically manufacture additional authority.</p>
<p>The asymmetry is what bounds the damage when observation is incomplete (§9.6): suppressed evidence can only prevent a tightening that should have happened, never engineer a loosening. That is an argument for keeping it absolute rather than situational.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Capability assignment</h2>
<h3>9.1 The catalog may not assign what the rules forbid discharging</h3>
<p>A Staff repository MUST NOT be catalogued in §4 as owning a capability it cannot discharge under these rules. Two marks distinguish the two ways that happens, and they are not interchangeable:</p>
<div class="scroll"><table><thead><tr><th>Mark</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>pending</strong></td><td>No route exists. No engine exposes the capability, the repository makes no Tooling contact, and the capability is <strong>zero</strong> — not degraded.</td></tr><tr><td><strong>declared-gap</strong></td><td>A route exists through a §5.3 declared gap. The capability <strong>works</strong> and is tracked, with an intended owner and a review date in §13.</td></tr></tbody></table></div>
<p>v0.4 had only <code>pending</code>, which forced a false choice. <code>ops-warden</code> holds production-verified SSH certificate issuance through a declared OpenBao contact; marking it <code>pending</code> would have told readers the repository does not do the one thing it demonstrably does daily, while leaving it unmarked left §4 disagreeing with §13. Neither is acceptable, and the defect was in this section rather than in the catalog.</p>
<p><code>pending</code> was written for <code>kings-guard</code>'s containment — no route, capability zero — and remains correct there. <code>declared-gap</code> is the case §5.3 was added to sanction. Raised by <code>ops-warden</code>.</p>
<p>Both marks apply per capability, not per repository. A repository may hold one capability outright, another under a declared gap, and a third pending.</p>
<h3>9.2 Actuation does not exist, and containment is not Staff's to own</h3>
<p>Self-healing needs four verbs: observe, evaluate, decide, actuate. Observation is <code>kings-guard</code> and is unstaffed (§12). Evaluation is <code>maturity-engine</code> and is seeded. Decision is <code>access-engine</code> and works. <strong>Actuation has no surface at all</strong>, and a model with no actuation surface describes a diagnosis machine rather than a healing one.</p>
<p>v0.5 marked containment <code>pending</code> against <code>kings-guard</code>, which was the right mark on the wrong repository. Containment is not a Staff capability that happens to lack a route: <strong>reduce authority, require step-up, isolate a workload</strong> are authority-changing operations, and under §6 an authority-changing operation is rendered by an Engine and enforced by a PEP (§6.4). A Staff repository proposes containment; it never performs it.</p>
<p>The <strong>actuation surface</strong> is therefore an Engine concept — likely a small surface on <code>access-engine</code> together with runtime PEPs — carrying the same reconstructability rules as any other decision: a containment action is a decision record, not a side channel.</p>
<p>It is <strong>unowned and held at zero</strong>. <code>access-engine</code> is recorded in §13 as a <em>proposed</em> owner and has explicitly not reviewed it (<code>FLEX-DEC-2026-002</code>). No repository may be catalogued as owning containment until the surface exists — §9.1 applied to the estate's most operationally tempting gap, and the standard's own medicine.</p>
<p>Until then <code>kings-guard</code> proposes and judges, its containment claim stays at zero rather than degraded, and no argument may assume the estate can contain anything automatically.</p>
<h3>9.3 Degraded mode: two failure cases, two owners</h3>
<p>v0.4 collapsed two failures into one rule. They have different owners because one has an evaluator in the path and the other does not.</p>
<p><strong>Input degradation — the engine's.</strong> Where <code>access-engine</code> is reachable but cannot reach its own inputs, the deterministic <em>fail to reduced authority</em> default belongs to the engine. This keeps the decision at the decision point and keeps the fallback deterministic, which a Staff-layer fallback could never be.</p>
<p><strong>Engine unreachable — necessarily the consumer's.</strong> Where <code>access-engine</code> is not reachable at all, it applies nothing, because it is not running. Whatever happens next is the consumer's behaviour by construction: fail-open is not expressible by a policy decision point, since there is no evaluator in the path to express it. A standard that assigns this to the engine assigns it to nobody.</p>
<p>The consumer's residue is bounded rather than free. A protected system MUST declare its unreachable-engine stance ahead of time, per zone or equivalent scope, and that stance MUST be auditable and total — no implicit default, no per-call discretion. <code>ops-warden</code> <code>ADR-0009</code> already satisfies this: a total per-zone map, open for <code>z0</code>–<code>z2</code> and unknown, closed for <code>z3-critical</code>, replacing the global <code>policy.enabled</code> / <code>policy.fail_closed</code> switches it superseded.</p>
<p><strong>Unchanged: engine-unavailable is not grounds for a Staff break-glass path.</strong> The distinction is whether an engine is there to ask. A bypass around a <em>reachable</em> engine is a second decision point, and an incident is when an attacker most wants that shortcut. A consumer choosing its declared behaviour when there is no engine to ask is not a bypass; it is the only thing left.</p>
<p>Contested by <code>flex-auth</code> (<code>FLEX-DEC-2026-002</code>), which has held since 2026-08-19 that fail-open is not expressible by a PDP, and which noted v0.4 collided with shipped behaviour in a repository that had assented to this standard.</p>
<h3>9.4 Approvals are an engine concept, not a Staff or audit concern</h3>
<p>The approval object — durable, authenticated entries, distinct-approver counting, atomic supersession, single consumption, revocation without holder cooperation — is owned by <code>approval-engine</code>.</p>
<p>It is not Staff's: §3.4 forbids Staff holding state another layer depends on at runtime. It is not the decision point's: an evaluator that owns the object it evaluates is self-dealing. It is not the audit fabric's: an approval needs mutable, in-path, current-state semantics, and an append-only archive is built for the opposite property.</p>
<p><code>access-engine</code> consumes approvals as <strong>input claims</strong> under §6.2 and never mutates them. Every issuance, use, supersession, and revocation is emitted to <code>audit-core</code>: the operative state and the evidence record are different artifacts with different owners.</p>
<p>The evidence guarantee is bounded, and the bound is <code>audit-core</code>'s <code>docs/integrity.md</code>, not its INTENT principle 6. An in-database hash chain detects a rewritten payload only if the attacker does not also recompute the suffix — which a database owner can. Detection against that class requires the external chain-head attestation, and even with it the store is not WORM, object lock, or archival custody. <code>tamper_evidence</code> is therefore conditional on live preconditions, not a property of the store at rest, and approval events receive exactly the guarantee every other source receives.</p>
<p><strong>Emission atomicity is <code>approval-engine</code>'s obligation.</strong> An approval MUST NOT be issued, consumed, superseded, or revoked without the corresponding event being durably queued in the same transaction.</p>
<p><strong>The queue MUST be local.</strong> The durable queue MUST live in <code>approval-engine</code>'s own transactional store, and <strong>no synchronous dependency on <code>audit-core</code> may sit inside the state-change transaction</strong>. With a genuine local outbox, fail-closed triggers only when <code>approval-engine</code>'s own store is unavailable — where the change could not have been recorded anyway — and an <code>audit-core</code> outage does not block a revocation. Satisfying the requirement by emitting synchronously to <code>audit-core</code> inside the transaction is also atomic, and turns an audit outage into an inability to revoke: the operation least tolerable to block during an incident, and the same coupling this section rejects for reads. Raised by <code>audit-core</code>. <code>audit-core</code> reports what it received and does not imply it is everything that happened; without atomic emission the evidence half is silently incomplete and nothing detects the gap. This is a condition of <code>audit-core</code>'s assent (<code>AUDIT-IN-0001</code>) and belongs in <code>approval-engine</code>'s contract before the evidence half is treated as load-bearing.</p>
<p><code>audit-core</code> MUST NOT expose an approval-validity query. Records, yes; a verdict on whether an approval is still valid, never — a consumer branching on that answer would route an authorization decision through the audit fabric, which is what this section exists to prevent. Callers needing current state ask <code>approval-engine</code>.</p>
<h3>9.5 Graded progression is an engine concept</h3>
<p>Maturity — how far a subject has progressed against declared criteria and submitted evidence — is owned by <code>maturity-engine</code>. Given the same criteria and the same evidence it MUST return the same level; that determinism is what makes it an Engine rather than an opinion.</p>
<p>The division with Staff: <strong>gate-house judges and proposes; maturity-engine computes and remembers.</strong> Interpretation is inference and stays Staff. A criterion that cannot be evaluated by rule is not yet a criterion.</p>
<p>This closes a defect in v0.2's own catalog: <code>gate-house</code> was assigned conformance review with no engine to act through, which is exactly the §9.1 problem raised against the containment claim. Staff acts only through Engine APIs, including gate-house.</p>
<p><strong>A maturity level MUST NOT be compiled into registry content.</strong> Until <code>access-engine</code>'s decision provenance carries a registry-snapshot digest — a gap it self-declared in §13 — a level reaching a decision through the registry is not reconstructable from the decision record. Levels arrive as request claims or as versioned policy rules. Same constraint, and same reason, as zone stance.</p>
<p><strong>A maturity level MUST NOT gate a decision directly.</strong> Under §6.1, compiled data that determines an outcome is still deciding. If a level determines whether an action is permitted, it MUST reach <code>access-engine</code> as an input claim or a versioned policy rule under §6.2, never by a consumer branching on a fetched level.</p>
<p>Approvals and maturity are deliberate opposites — a closed binary state machine against an open graded ladder — and neither engine may drift toward the other.</p>
<h3>9.6 Evidence proves alteration and truncation, not omission at source</h3>
<p>An append-only archive with a verified hash chain proves that records were not <strong>altered or truncated after arrival</strong>. It cannot prove that a record was never sent. Against a compromised or buggy source, a suppressed event leaves the chain perfectly intact and verification reports intact.</p>
<p>This bound is estate-wide. Statements of the form <em>"the audit record proves it happened"</em> are unsound; the sound form is <em>"the archive proves the records it holds were not altered or truncated after arrival"</em>. Its mirror is equally unsound: <strong>absence of a record is not evidence of non-occurrence</strong>, and no control may read it as such.</p>
<p><strong>Load-bearing versus attributive evidence.</strong> The atomicity obligation attaches to the first, not to both:</p>
<div class="scroll"><table><thead><tr><th>Kind</th><th>Test</th><th>Obligation</th></tr></thead><tbody><tr><td><span class="kind ">Load-bearing</span></td><td>a control's soundness depends on the event being present or absent — an approval revocation, a containment action, a denial</td><td>emission MUST be atomic with the state change (§9.4)</td></tr><tr><td><span class="kind ">Attributive</span></td><td>the event supports forensic reconstruction and attribution, and no control branches on its presence</td><td>atomicity SHOULD be sought; where it is deliberately traded away, the trade MUST be declared and completeness MUST NOT be claimed</td></tr></tbody></table></div>
<p>Where a repository deliberately makes emission non-atomic — <code>ops-warden</code>'s <code># audit must not block signing</code> is the estate's live example, chosen so that an audit-store failure cannot remove production host access — the trade is legitimate for attributive evidence, MUST be declared where the trail is documented, and MUST NOT be described in terms that imply completeness. The availability argument is real in both directions: making it atomic gives the estate's operational access lane a new dependency on its own evidence store.</p>
<p><strong>Consequence for adaptive systems.</strong> Suppression does not degrade observation neutrally, it biases it optimistic, and silently: an event never emitted is never evaluated, so no finding is raised and the last posture stands. A confidence score computed from the richness of the record in hand cannot express doubt about the completeness of the stream — a well-formed observation from a 90%-suppressed stream scores high. That is this section's failure reproduced one layer up, in the consumer.</p>
<p>Two things follow.</p>
<p><strong>Which control covers which threat.</strong> v0.6 read as though emission atomicity closed this section's opening sentence. It does not, and the decomposition is owed to the reader:</p>
<div class="scroll"><table class="tm"><thead><tr><th>Threat</th><th>Covered by</th><th>When</th></tr></thead><tbody><tr><td><strong>Accidental omission</strong> — process dies between mutation and emit</td><td class="">emission atomicity, local outbox (§9.4)</td><td class="">prevented</td></tr><tr><td><strong>Adversarial omission</strong> — a compromised source declines to insert, deletes before drain, or drains to nowhere</td><td class="">cadence and reconciliation</td><td class=""><strong>detected, after the fact</strong></td></tr><tr><td>Adversarial omission at a compromised source</td><td class="">—</td><td class=""><strong>nothing in this model prevents it</strong></td></tr></tbody></table></div>
<p>The outbox sits inside the blast radius of the component whose compromise this section posits, so it makes emission atomic against crash and partial failure and nothing more. That residual is real and is stated rather than implied. Raised by <code>audit-core</code>, correcting a remedy it had itself proposed.</p>
<ol><li><strong>The §8 asymmetry bounds the damage, and this is its clearest payoff.</strong> Because an adaptive system may only reduce authority and never manufacture it, suppression can only prevent a tightening that should have happened. It cannot be used to engineer a loosening. The harm is a missed reduction, not an invented privilege — which is an argument for keeping the asymmetry absolute.</li><li><strong>Silence is a signal, and for load-bearing evidence it is the only control in its class.</strong> A source of <strong>attributive</strong> evidence SHOULD declare an expected emission cadence; a source of <strong>load-bearing</strong> evidence <strong>MUST</strong>. A drop below the declared rate is a finding in its own right — the stream observed, not only its contents — and needs no Tooling contact, because the source publishes its own stream.</li></ol>
<p><strong>Rate monitoring is the wrong form for rare events</strong>, and rare is exactly where the stakes are highest: the most valuable event to suppress is the negative one, and revocations, denials, and containment actions are infrequent by nature. A source emitting a handful of revocations a month has no rate to drop below, and suppression is indistinguishable from a quiet month. For <strong>low-volume load-bearing classes</strong> the required form is therefore <strong>positive reconciliation or a heartbeat</strong>: compare the source's own state transitions against the evidence engine's event count per class and treat divergence as a finding, or assert <em>nothing to report</em> as a signed positive claim that can itself go missing. Rate monitoring never produces a claim that can be missing; a heartbeat does. <code>GH-WP-0002-T04</code> is the reference instance. Raised by <code>audit-core</code>.</p>
<p>Raised by <code>audit-core</code> against its own principle; extended by <code>kings-guard</code> from its own evaluator and confidence model.</p>
<h3>9.7 Decisions have a lifetime</h3>
<p>A single decision point deciding on stale claims is a single decision point deciding wrongly. The model has had no temporal law, and the approval race in §16 was its first symptom.</p>
<ol><li><strong>Every allow has an explicit lifetime</strong> — a TTL, or a binding to a session or obligation that ends. An allow with no stated end is a standing grant, and standing grants are what this estate exists to remove.</li><li><strong>Revocation and supersession have a visibility deadline</strong>, and its shape differs by role. A <strong>PEP</strong> has one boundary and MUST state one deadline. A <strong>PDP</strong> MUST state a deadline <strong>per input class</strong>, because a decision is a join over sources with unrelated refresh behaviour — approval-claim freshness, registry snapshot cadence, policy package activation, directory ETag. A single number at a PDP is either a fiction or the worst case, and the worst case is the slowest and least visible input. "Eventually" is not a stance; an unstated deadline is an unbounded replay window.</li></ol>
<p>A consequence worth naming: a stated deadline for a fact carried by a registry snapshot is unfalsifiable while decision provenance holds no snapshot digest, since nobody can determine afterwards which snapshot a decision read. The deadline and the digest are one gap seen from two sides, which promotes <code>access-engine</code>'s self-declared provenance gap (§13) from housekeeping to a conformance prerequisite. Raised by <code>access-engine</code> against its own backlog.</p>
<ol><li><strong>Consumption is a state change, never an inference.</strong> An approval is consumed by a mutation in <code>approval-engine</code> (§9.4). It MUST NOT be inferred from the existence of a decision record — the decision precedes the action and the action precedes consumption, so a decision record proves an intent to act, not an act.</li><li><strong>Three failure modes are named, and each needs an owner</strong>: an allow rendered then never consumed; a double consumption by racing callers; consumption after the authorized action has already failed. Neither engine closes these alone. Recorded in §16 and <code>GH-WP-0002-T06</code>.</li></ol>
<h3>9.8 Partition is not one-dimensional</h3>
<p>§9.3 handles <em>engine unreachable</em>. A real estate spends most of its incident time in the band between reachable and gone: partial PIP reachability, clock skew across a decision and its enforcement, and two consumers with different declared stances seeing different worlds at the same moment.</p>
<p>Two rules hold today, and the rest is open (§16). A PEP MUST resolve its own stance from its declared map without consulting another consumer — divergent views are expected and are not a coordination problem to be solved at enforcement time. And where clock skew could extend a lifetime under §9.7, the shorter reading governs.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Changing layer</h2>
<p>A repository's layer is not permanent. <code>zone-engine</code> changed layer in practice when its runtime hypothesis was falsified.</p>
<p>A layer change MUST be recorded as a decision, MUST update the repository's <code>INTENT.md</code>, and MUST obtain assent from the repositories whose boundaries move. A repository MUST NOT acquire a new layer's permissions by gradual practice.</p>
<p>"No gradual practice" needs a check rather than a sentence. A layer change MUST carry six artifacts, written from the <code>zone-engine</code> case that the procedure should have been derived from in the first place:</p>
<div class="scroll"><table><thead><tr><th>Artifact</th><th>Why</th></tr></thead><tbody><tr><td>before/after <code>INTENT.md</code></td><td>the declaration is the conformance surface (§11)</td></tr><tr><td>client inventory</td><td>what the repository holds against Tooling, before and after</td></tr><tr><td>gap inventory</td><td>which §5.3 gaps close, open, or transfer</td></tr><tr><td>assent list</td><td>every repository whose boundary moves</td></tr><tr><td>state-migration decision</td><td>what happens to live state and to consumers reading it</td></tr><tr><td>permission freeze</td><td>no new permissions of the target layer are exercised until the cut completes</td></tr></tbody></table></div>
<p>The freeze is the one that makes the rule checkable: a repository mid-change holds its old permissions, not the union of both.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Conformance</h2>
<p>Conformance has four states, and the distinction between the last two is the point:</p>
<div class="scroll"><table><thead><tr><th>State</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>Conforming</strong></td><td>no Tooling contact, or only §5.1/§5.2 shapes, declared</td></tr><tr><td><strong>Blocked-clean</strong></td><td>the capability does not exist because no engine exposes it, and the repository makes <strong>no</strong> Tooling contact — §9.1 <code>pending</code>, and not a non-conformance</td></tr><tr><td><strong>Declared gap</strong></td><td>a §5.3 contact with owner, blocker, and review date — tracked non-conformance</td></tr><tr><td><strong>Undeclared violation</strong></td><td>anything else — a finding</td></tr></tbody></table></div>
<p><strong>Blocked-clean is not a lesser state than conforming.</strong> A repository that declined a break-glass path and left a capability at zero has complied at cost; a repository that quietly opened a direct client and declared nothing has not. Any downstream scoring — <code>maturity-engine</code> included (§9.5) — MUST NOT rank the first below the second. Raised by <code>kings-guard</code>, whose three gaps are all of this kind and which would otherwise have been graded down three times for having taken the standard seriously.</p>
<p><strong>Who must declare.</strong> A repository the estate authors declares its layer in its own <code>INTENT.md</code>. For a component the estate catalogues but does not author — third-party or vendored, such as <code>OpenBao</code> — the §4 catalog row <strong>is</strong> the declaration, and no <code>INTENT.md</code> obligation attaches. A rule that assigns an obligation the holder cannot discharge is the §9.1 defect applied to conformance rather than capability.</p>
<p>A layer stated <em>about</em> a repository by another repository is not a declaration. Review notes, catalog rows, and correspondence record an intent to adopt; only the repository's own file conforms.</p>
<p><strong>Declaration form.</strong> Because prose cannot distinguish a declaration from a transcribed review, a declaration MUST carry a machine-readable form: a <code>layer:</code> key in the <code>INTENT.md</code> frontmatter, or an equivalent declaration file. Without it this section asserts a property it cannot deliver — the defect this standard has now corrected three times elsewhere. <code>ops-warden</code> has implemented a reference form (<code>layer.yaml</code>, a conformance script, and a test covering the §5.2 no-authority property) and offered it to the repositories that have yet to declare. Raised by <code>audit-core</code>, which noted that <code>flex-auth</code>'s conforming declaration is legible as one only by following its decision trail.</p>
<p>Mechanically checkable:</p>
<ul><li>every estate-authored repository in §4 carries a machine-readable layer declaration;</li><li>every direct Tooling client in a Staff repository maps to a declared §5.1, §5.2, or §5.3 entry, and non-Tooling clients are recorded so the check is total;</li><li>no repository other than <code>access-engine</code> exposes an authorization decision surface;</li><li>no §4 capability is catalogued without an engine surface, a <code>pending</code> mark, or a <code>declared-gap</code> mark.</li></ul>
<p>Requires review: whether claims stay inside layer permissions; whether compiled or cached data has become an early decision (§6.1); whether doctrine is reaching decisions as declared inputs (§6.2); whether the §8 vocabulary is used correctly.</p>
</section>
<section id="s12"><h2><span class="sn">12</span>The conformance loop</h2>
<p>Doctrine no engine implements is fiction. The loop is normative, not aspirational:</p>
<pre>gate-house asserts an invariant
→ the engines implement it, or declare a gap
→ whitehat-security tries to break it
→ kings-guard observes it in operation
→ findings return to gate-house as doctrine change</pre>
<p>A finding that a rule is unsatisfiable is a <strong>success</strong> of this loop, not a failure of the reporting repository. Four of this standard's five versions exist because a reviewing repository used it.</p>
<p><strong>Step four is currently aspiration.</strong> <code>kings-guard</code> has disclosed that it has never observed anything in operation: the pilot is specified and scaffolded, every input is a hand-built fixture, and no test has met a real event. Until it reports otherwise, no argument in this estate may assume an invariant is being watched in practice because §12 lists a repository against that step.</p>
</section>
<section id="s13"><h2><span class="sn">13</span>Open gaps</h2>
<p>Two different things are recorded here, and they are opposite conformance states (§11). A <strong>declared contact</strong> means the repository touches Tooling because no engine exposes the capability. An <strong>unowned capability</strong> means no route exists and the repository makes no contact at all. Reading them as one list would grade restraint as though it were non-conformance.</p>
<p>An <code>intended owner</code> is a <strong>proposal to</strong> the named repository, not an assignment <strong>onto</strong> it. §2 keeps ownership in the repository's own <code>INTENT.md</code>, so the register distinguishes proposed from assented.</p>
<div class="scroll"><table><thead><tr><th>Gap</th><th>State</th><th>Declared by</th><th>Owner</th><th>Owner status</th></tr></thead><tbody><tr><td>SSH-CA signing write (<code>VaultCA</code>, <code>bao kv put</code>)</td><td>declared-contact</td><td>ops-warden</td><td>secrets-engine</td><td>proposed</td></tr><tr><td>Authentication / assurance evidence</td><td>unowned-capability</td><td>kings-guard</td><td>identity layer + audit-core</td><td><strong>access-engine declined</strong></td></tr><tr><td>Secret-use evidence</td><td>unowned-capability</td><td>kings-guard</td><td>secrets-engine</td><td>proposed</td></tr><tr><td>Actuation / containment surface</td><td>unowned-capability</td><td><strong>gate-house (estate-wide)</strong></td><td>access-engine + runtime engines</td><td>proposed</td></tr><tr><td>Identity and secret observation</td><td>unowned-capability</td><td>kings-guard</td><td>as above</td><td>proposed</td></tr><tr><td>Stance-map register had no implementation</td><td>declared-contact</td><td>ops-warden, access-engine</td><td>gate-house</td><td>resolved in §13.1</td></tr><tr><td>Registry-snapshot digest in decision provenance</td><td>declared-contact</td><td>flex-auth</td><td>flex-auth</td><td>self-declared</td></tr><tr><td>Approval storage and lifecycle</td><td>—</td><td>flex-auth</td><td>approval-engine</td><td>assigned (§9.4)</td></tr><tr><td>Approval evidence</td><td>—</td><td>gate-house</td><td>audit-core</td><td><strong>assented</strong> (<code>AUDIT-IN-0001</code>)</td></tr><tr><td>Approval evidence custody stronger than the shipped bound — WORM, object lock, transparency log</td><td>unowned-capability</td><td>audit-core</td><td>—</td><td>unassigned</td></tr><tr><td>Emission atomicity for approval state changes</td><td>—</td><td>audit-core</td><td>approval-engine</td><td>assigned (§9.4)</td></tr><tr><td>Non-atomic audit emission on the SSH signing lane</td><td>declared-contact</td><td>ops-warden</td><td>ops-warden</td><td>self-declared, attributive (§9.6)</td></tr></tbody></table></div>
<p>The actuation row is no longer attributed to <code>kings-guard</code>. §9.2 ruled that containment is not a Staff capability lacking a route, so <code>kings-guard</code> is not its declarer: the gap is estate-wide and blocks every repository's ability to act. Raised by <code>kings-guard</code>, which asked not to carry a row for a capability the standard had just ruled was never theirs.</p>
<p><code>access-engine</code> declined authentication and assurance evidence (<code>FLEX-DEC-2026-002</code>): it consumes assurance claims as input and never redefines them, so evidence of authentication belongs to the identity layer and <code>audit-core</code>. It owns evidence of the decision, which it already emits. The containment surface is recorded as proposed and remains <code>pending</code> under §9.2.</p>
<p>Whether approvals warrant custody stronger than every other source is doctrine work not yet done; until it is, approval evidence carries the same guarantee as any other source and §9.6 bounds what may be claimed from it.</p>
<p><strong>What is normative here, and what is a snapshot.</strong> Three rules are part of this standard and survive wherever the register lives:</p>
<ol><li>the two marks — <code>pending</code> and <code>declared-gap</code> (§9.1);</li><li>the owner-status rule — a proposed owner is not an assigned one (§2);</li><li>the scoring rule — <code>blocked-clean</code> MUST NOT rank below conforming (§11).</li></ol>
<p><strong>The table above is a snapshot, not statute.</strong> It moves into <code>maturity-engine</code> as soon as that engine can store state, and the <code>state</code> and owner-status columns MUST survive the migration. A standard that is also a backlog keeps attracting findings that belong in the register, and its review interval is far slower than the register's real rate of change.</p>
<h3>13.1 PEP stance-map register</h3>
<p>Every PEP-shaped consumer publishes an unreachable-engine stance map (§6.4, obligation 3). This is the inventory until <code>maturity-engine</code> can hold it.</p>
<div class="scroll"><table><thead><tr><th>Consumer</th><th>Stance map</th><th>Shape</th></tr></thead><tbody><tr><td><code>ops-warden</code></td><td><code>ops-warden/pep-stance.yaml</code></td><td>total per-zone; open <code>z0</code>–<code>z2</code> and unknown, closed <code>z3-critical</code>; test asserts the published map equals the shipped default (<code>ADR-0009</code>)</td></tr><tr><td><code>ops-mason</code></td><td>—</td><td><strong>not published</strong>; catalogued PEP-shaped in §4</td></tr></tbody></table></div>
<p><strong>One row is the finding.</strong> The aggregate of consumer stances is the estate's real authorization behaviour, and it is currently one published map and one absence. <code>access-engine</code> has noted it is the repository positioned to notice when that aggregate diverges from what the policy packages say — which it cannot do while the register is nearly empty.</p>
</section>
<section id="s14"><h2><span class="sn">14</span>Adoption</h2>
<p>Status is <strong>accepted</strong>, on the owner's decision of 2026-08-29.</p>
<p>Two things that acceptance does and does not mean, kept apart because <code>ops-warden</code> asked for the distinction:</p>
<div class="scroll"><table><thead><tr><th><strong>Boundary assent</strong></th><th>given by the four repositories below, at the version named in each record, and undisturbed since</th></tr></thead><tbody><tr><td><strong>Revision review</strong></td><td>each of the four reviewed v0.6 and returned findings; <strong>every change in v0.7 is the adopted remedy of a finding they raised</strong></td></tr><tr><td><strong>Not claimed</strong></td><td>no repository has reviewed v0.7 <em>as text</em>. The first revision review will confirm or correct it</td></tr></tbody></table></div>
<p>Accepting a standard nobody has re-read is a deliberate call: the estate learns more from using it than from another round of prose refinement, and the changes in v0.7 were requested rather than invented. Findings against the accepted text remain welcome and are §12's normal business, not an exception.</p>
<div class="scroll"><table><thead><tr><th>Repository</th><th>Record</th><th>Outcome</th></tr></thead><tbody><tr><td>flex-auth</td><td><code>FLEX-DEC-2026-001</code></td><td>assent to all three items; one self-declared non-conformance; two rename conditions</td></tr><tr><td>kings-guard</td><td><code>KG-DEC-2026-001</code></td><td>assent; declined the offered §5 relaxation; raised §9.1</td></tr><tr><td>ops-warden</td><td><code>ADR-0010</code></td><td>assent to all three; veto not exercised; offered the §5.3 amendment</td></tr><tr><td>audit-core</td><td><code>AUDIT-IN-0001</code></td><td>assent to the evidence half with conditions; corrected the rationale twice; raised §9.6</td></tr></tbody></table></div>
<p>Adoption for a repository means its <code>INTENT.md</code> declares its layer, its ownership claims fall inside that layer, its Tooling contacts are declared under §5, and any shared boundary has been assented to by the other side.</p>
<p><strong>Adoption status as of 2026-08-29: seven of sixteen</strong> estate-authored §4 repositories have declared in their own voice — <code>gate-house</code>, <code>flex-auth</code>, <code>kings-guard</code>, <code>ops-warden</code>, <code>audit-core</code>, <code>approval-engine</code>, <code>maturity-engine</code>. The remaining nine — <code>info-tech-canon</code>, <code>net-kingdom</code>, <code>key-cape</code>, <code>user-engine</code>, <code>tenant-engine</code>, <code>zone-engine</code>, <code>secrets-engine</code>, <code>ops-mason</code>, <code>whitehat-security</code> — carry a layering review note authored by <code>gate-house</code> and have not answered it. Those notes state a layer but do not constitute a declaration, and this standard does not claim estate-wide adoption on their basis. Declaration requests are open as intakes in each.</p>
</section>
<section id="s15"><h2><span class="sn">15</span>Change log</h2>
<p>v0.1 → v0.2:</p>
<ol><li><strong>§5 restructured</strong> into three sanctioned shapes. Added §5.2 conduit (ops-warden's question, ruled) and §5.3 declared engine gap (ops-warden's amendment, accepted).</li><li><strong>§6.2 added</strong> — doctrine must reach the decision as an input claim or a versioned policy rule (flex-auth's boundary drawn back, accepted).</li><li><strong>§9 added</strong> — the catalog may not assign a capability the rules forbid discharging; containment marked pending; degraded-mode fallback ruled into the engine (kings-guard's finding).</li><li><strong>§11 restructured</strong> — conformance now has three states, distinguishing a tracked gap from an undeclared violation.</li><li><strong>§12 made normative</strong>, with the explicit statement that an unsatisfiability finding is a success of the loop.</li><li><strong>§13 added</strong> — open gaps register, including the unowned approval storage and lifecycle capability.</li><li>§4 catalog gained the pending mark and ops-warden's SSH certificate lane.</li></ol>
<p>v0.2 → v0.3:</p>
<ol><li><strong>§9.4 added</strong> — approvals assigned to <code>approval-engine</code>, with the operative state and the evidence record separated between it and <code>audit-core</code>.</li><li><strong>§9.5 added</strong> — graded progression assigned to <code>maturity-engine</code>, closing the §9.1 defect in gate-house's own conformance-review claim, and carrying the guardrail that a level may never gate a decision directly.</li><li>§4 catalog gained both engines; gate-house's conformance-review claim now names the engine it acts through.</li><li>§13 register updated: the approval hole is assigned, two new entries added.</li></ol>
<p>v0.6 → v0.7, from four reviews:</p>
<ol><li><strong>§3.4 is written.</strong> v0.6 announced the human/agent principal separation in §1 and §15 and left §3.4 byte-identical to v0.5 — a silent edit failure. A rule stated about a standard in its own change log is not a rule. Found by <code>kings-guard</code>. The same failure had also dropped two §16 entries, restored here.</li><li><strong>§6.4 obligation 1 rewritten</strong> — it forbade what obligation 3 blesses. A PEP may proceed under its declared §9.3 stance provided the application of that stance is <em>recorded in place of</em> the decision. Stricter than v0.6 where it counts: a fail-open result is metadata, never silence. Raised by <code>ops-warden</code>.</li><li><strong>§6.4 obligation 2 rewritten</strong> — it forbade the session-bound allow §9.7.1 permits. Scoped to replay outside the decision's own binding and lifetime, with the canonical request digest as the mechanical test, and negative caching ruled permitted where the refusal is recorded and the cache lifetime declared. Raised by <code>access-engine</code>.</li><li><strong>§6.4 obligation 3</strong> gained the requirement that the published stance map equal shipped behaviour, asserted by test. <strong>§13.1</strong> now exists as the register §6.4 mandated and v0.6 did not implement.</li><li><strong>§9.6 gained a threat decomposition</strong> — atomicity prevents accidental omission; cadence and reconciliation detect the adversarial case after the fact; nothing prevents it at a compromised source. Raised by <code>audit-core</code> against its own proposed remedy.</li><li><strong>§9.6 cadence is now MUST for load-bearing sources</strong>, with positive reconciliation or a heartbeat as the required form for low-volume classes, because rate monitoring fails exactly where the stakes are highest.</li><li><strong>§9.7.2 splits by role</strong> — a PDP states a deadline per input class, a PEP one at its boundary. Promotes <code>access-engine</code>'s provenance gap to a conformance prerequisite.</li><li><strong>§3.3's Evidence row</strong> is stated as an estate trade rather than a property, leaving independent-recording-before-effect raisable as a declared exception.</li><li><strong>§17</strong> moves the decision-record schema to <code>access-engine</code>, which argued it against its own interest; <code>kings-guard</code> drafts the emission-cadence schema.</li><li><strong>§13</strong> no longer attributes the actuation gap to <code>kings-guard</code>; it is estate-wide. <strong>§19 removed</strong> — a verdict inside a standard grades the document it lives in. <strong>§17/§18</strong> demoted from H1 to H2.</li><li><strong>§20 added</strong> — the Railiance interaction boundary, on <code>railiance-master</code>'s definitions, including that <code>rein-*</code> is not a fifth axis.</li></ol>
<p>v0.5 → v0.6, from the independent assessment of 2026-08-29:</p>
<ol><li><strong>§3.3 types the engines</strong> — PDP, PIP, Evidence, Lifecycle, with a role column in §4. A new engine is a PIP unless this standard says otherwise, so "we need an engine for X" cannot drift into "X now decides".</li><li><strong>§6.4 names the enforcement point</strong> — a PEP shape with four obligations: no side effect without a decision record, no local recaching of the verdict, a declared unreachable-engine stance, reconstructability. The standard had the decision and not the gate.</li><li><strong>§9.2 replaced</strong> — containment was marked pending against the wrong repository. Actuation is an Engine concept, unowned, held at zero; Staff proposes containment and never performs it.</li><li><strong>§3.4 separates the two Staff principals</strong> — human and agent share the layer but not blast radius: no standing credential, conduit or engine API only, agent memory is not a state plane, every action reconstructable as the caller's.</li><li><strong>§9.7 puts time into the model</strong> — explicit lifetimes, revocation visibility deadlines, consumption as a state change never inferred, and the three race modes named. <strong>§9.8</strong> states what holds under partition and leaves the rest open.</li><li><strong>§17 requires the Taxonomy artifacts</strong> — claim, decision-record, gap-record, and emission-cadence schemas — without which §6.2 and §11 are reviewable but not compileable. Ownership proposed, not assigned.</li><li><strong>§18 composes the sibling standards</strong> — how zone stance, tenancy posture, and a credential lifecycle event each enter a decision as a claim. They were cited in frontmatter and nowhere in the rules.</li><li><strong>§5 gained a sunset</strong> on the uncatalogued-infrastructure carve-out, and §5.3 <strong>declines</strong> a proposed fourth "operator of third-party Tooling" shape: it would convert a tracked gap into a permanent allowance.</li><li><strong>§10 gained the six artifacts</strong> a layer change must carry, written from the <code>zone-engine</code> case, including a permission freeze during the cut.</li><li><strong>§2 lifts the observation rule</strong> — no estate argument may cite observation that has not happened. <strong>§13</strong> separates its three normative rules from the table, which is now a snapshot due to move into <code>maturity-engine</code>.</li><li><strong>§16</strong> the approval custody question is <strong>decided: no</strong>, rather than left open. <strong>§19</strong> records the fitness verdict, including that the estate can propose and decide but cannot yet watch or act.</li></ol>
<p>v0.4 → v0.5, all from review findings:</p>
<ol><li><strong>§9.1 split into two marks</strong> — <code>pending</code> (no route, capability zero) and <code>declared-gap</code> (route exists under §5.3, capability works and is tracked). v0.4's single mark would have forced a false <code>pending</code> onto ops-warden's production SSH issuance. Raised by <code>ops-warden</code>.</li><li><strong>§9.3 rewritten</strong> — input degradation is the engine's; engine-unreachability is necessarily the consumer's, bounded by a declared, auditable, total stance. Contested by <code>flex-auth</code>: fail-open is not expressible by a PDP, and v0.4 collided with <code>ops-warden</code> <code>ADR-0009</code>.</li><li><strong>§5 gained a scope rule</strong> — "Tooling-layer system" means a §4 Tooling row; uncatalogued infrastructure is outside §5 and recorded rather than policed. Without it every Staff repository was in undeclared violation for writing progress events. Raised by <code>ops-warden</code>.</li><li><strong>§9.4 requires a local outbox</strong> — no synchronous dependency on <code>audit-core</code> inside the state-change transaction, so an audit outage cannot block a revocation. Raised by <code>audit-core</code>.</li><li><strong>§9.5 forbids compiling maturity levels into registry content</strong> until decision provenance carries a registry-snapshot digest. Raised by <code>flex-auth</code>.</li><li><strong>§9.6 gained the load-bearing / attributive distinction</strong>, the mirror rule that absence is not evidence of non-occurrence, the optimistic-bias consequence for adaptive systems, and silence-as-signal. Raised by <code>kings-guard</code> on top of <code>audit-core</code>'s original.</li><li><strong>§11 gained a fourth state</strong> — blocked-clean, which MUST NOT rank below conforming — and a machine-readable declaration form. Raised by <code>kings-guard</code> and <code>audit-core</code>.</li><li><strong>§13 gained state and owner-status columns</strong> — declared-contact versus unowned-capability, proposed versus assented owner. <code>access-engine</code>'s decline of authentication evidence is recorded. Raised by <code>kings-guard</code> and <code>flex-auth</code>.</li><li><strong>§8</strong> records the asymmetry's payoff under incomplete observation; <strong>§12</strong> records that its fourth step is unstaffed; <strong>§14</strong> corrects the adoption arithmetic and the status contradiction.</li></ol>
<p>Amended in place while <code>proposed</code>, 2026-08-28: §11 gained the who-must-declare rule after a conformance sweep found the standard required an <code>INTENT.md</code> declaration from <code>OpenBao</code>, which the estate does not author; and §14 gained the honest adoption count.</p>
<p>v0.3 → v0.4:</p>
<ol><li><strong>§4 catalog gained <code>audit-core</code></strong> as an Engine, on its own declaration. v0.3 named it as an owner in §9.4 and §13 without cataloguing it — a §11 defect in the standard itself, raised by <code>audit-core</code>.</li><li><strong>§9.4 evidence rationale rewritten</strong> to cite <code>audit-core</code>'s shipped <code>docs/integrity.md</code> bound rather than its INTENT principle 6, and to state that <code>tamper_evidence</code> is conditional on live preconditions.</li><li><strong>§9.4 gained emission atomicity</strong> as <code>approval-engine</code>'s obligation, and the prohibition on <code>audit-core</code> exposing an approval-validity query.</li><li><strong>§9.6 added</strong> — evidence proves alteration and truncation, not omission at source. Estate-wide; the sound and unsound forms of the claim are stated.</li><li><strong>§13</strong> — evidence half recorded as assented with conditions; two new gaps: stronger approval custody (unassigned) and emission atomicity (<code>approval-engine</code>).</li></ol>
</section>
<section id="s16"><h2><span class="sn">16</span>Open questions</h2>
<ul><li>~~Whether approvals warrant archival custody stronger than every other audit source.~~ <strong>Decided (§13): no.</strong> Approval evidence carries the same bound as every other source. The acute risk for approvals is <em>omission</em> — a suppressed revocation — and archival custody does not address omission at all; emission atomicity with a local outbox (§9.4) and a detection surface (<code>GH-WP-0002-T04</code>) do. Leaving it open while calling the evidence half load-bearing created a promise the archive cannot cash. If a future requirement genuinely needs WORM or a transparency log, that is a different store with a different owner, raised then.</li><li>Whether SSH certificate issuance evidence is load-bearing or attributive (§9.6). Ruled attributive here on the argument that no control branches on the presence of a signing record; <code>ops-warden</code> asked for the ruling and the trade is genuinely two-sided, so it is flagged rather than settled.</li><li>Who marks an approval consumed, and at what point relative to the decision (§9.4). <code>flex-auth</code> notes the decision precedes the action and the action precedes consumption, so an allow rendered against an approval then never consumed, or consumed twice by a racing caller, is a gap neither engine closes alone. Needed before <code>FLEX-WP-0017</code> T05.</li><li>Whether other §4 repositories are missing layer declarations; <code>audit-core</code> flagged its own absence and asked whether the catalog needs the same correction elsewhere.</li><li>Whether the gap register migrates from this standard into <code>maturity-engine</code> once that engine exists, leaving the standard to state the rules only.</li><li>Whether Tooling warrants subdivision between third-party and homegrown.</li><li>How a future <code>role-engine</code> divides responsibility with <code>access-engine</code>.</li><li>Whether declared gaps need an estate-wide register rather than per-repository declarations; ops-warden's <code>warden route gaps</code> is candidate machinery.</li><li>Whether non-security repositories adopt the same model. The determinism cut is not security-specific; if non-security Staff also may not hold runtime-dependent state, the estate gets one constitution rather than a security ghetto.</li><li>The rest of §9.8: split brain, partial PIP reachability, and clock skew beyond the two rules stated.</li><li>Publication integrity of the Taxonomy layer itself. This standard demands reconstructability of decisions while its own publication path has no digest, freeze, or rollback discipline.</li><li>The fitness verdict formerly at §19 now lives in <code>net-kingdom/history/2026-08-29-layering-standard-assessment.md</code>. A grade inside a standard of record becomes normative by adjacency and ages against the text it grades. Raised by <code>access-engine</code>. Its two substantive points remain live: observation in production is unstaffed (§12) and actuation has no surface (§9.2).</li><li>The <strong>working companion</strong> (<code>net-kingdom/SECURITY-COMPANION.md</code>, v0.2, root of the repository for onboarding) is the operative form of this statute. The statute governs on disagreement, and a disagreement is a finding. The v0.1 gap <code>access-engine</code> found — publish your stance map, but nowhere saying where, and no inventory obligation — is fixed in v0.2 §5.3.</li><li>How the Railiance operational axes meet this model beyond §20's first statement, which is deliberately minimal.</li></ul>
</section>
<section id="s17"><h2><span class="sn">17</span>Taxonomy artifacts</h2>
<p>§6.2 says doctrine reaches a decision as an input claim or a versioned policy rule. As prose that is a rule a reviewer can apply. As an interface it does not exist, because nothing defines what a claim <em>is</em>. §11 calls itself mechanically checkable while resting on that gap.</p>
<p>Four artifacts are therefore required, owned by Taxonomy and versioned like any standard:</p>
<div class="scroll"><table><thead><tr><th>Artifact</th><th>Contents</th></tr></thead><tbody><tr><td><strong>request-claim schema</strong></td><td>identity, tenant, zone stance, posture, approval, maturity, assurance — each with its issuer and freshness rule</td></tr><tr><td>~~decision-record schema~~</td><td><strong>moved to <code>access-engine</code></strong> — see below</td></tr><tr><td><strong>gap-record schema</strong></td><td>the §5.3 fields — <code>capability</code>, <code>intended_owner</code>, <code>blocked_on</code>, <code>review</code> — plus the §13 <code>state</code> and owner-status</td></tr><tr><td><strong>emission-cadence declaration</strong></td><td>the expected rate a source publishes, so silence is a finding (§9.6)</td></tr></tbody></table></div>
<p>Until these exist, §6.2 and §11 are reviewable but not compileable, and every engine invents its own claim shape at its own boundary.</p>
<p><strong>The decision-record schema is not Taxonomy's.</strong> A decision record is the PDP's output artifact — the one thing in the estate only <code>access-engine</code> produces — and §2 keeps ownership in the producing repository's own <code>INTENT.md</code>. Taxonomy authoring the schema for an artifact only one engine emits would invert the ownership rule this standard applies everywhere else. <code>access-engine</code> publishes it as a contract; Taxonomy holds only the shared field vocabulary the claim schema references.</p>
<p>Raised by <code>access-engine</code> <strong>against its own interest</strong> — the same §2 argument it used to decline authentication evidence, applied where it takes work on rather than off. Symmetry of that kind is what makes the ownership rule credible.</p>
<p><strong>The emission-cadence declaration has a drafter.</strong> <code>kings-guard</code> is its only consumer, cannot implement silence-as-signal without it, and has offered to draft it against <code>qonto-assistant</code> and hand it to whichever Taxonomy repository takes ownership — rather than inventing a local shape, which is the drift §17 exists to prevent. Accepted as a draft; ownership still rests with Taxonomy.</p>
<p><strong>Ownership is proposed, not assigned.</strong> <code>info-tech-canon</code> holds ecosystem-wide semantic contracts and <code>net-kingdom</code> holds NetKingdom standards of record; the split between them for these four artifacts is theirs to draw, and §2 keeps ownership in the owning repository's <code>INTENT.md</code>. Neither has assented.</p>
</section>
<section id="s18"><h2><span class="sn">18</span>Composition with the sibling standards</h2>
<p>The related-standards list has been frontmatter and little else. If the following sentences cannot be written, the list is decoration — so they are written here rather than in the siblings.</p>
<p><strong>Zone stance</strong> (<code>security-zones_v0.1</code>). A zone answers which scrutiny a workload has qualified for; membership is <code>zone-engine</code>'s. The <em>effect</em> of a zone on a decision belongs in a versioned <code>access-engine</code> policy package, never in registry content — that ruling is zone-engine's §5, and §6.1 is its generalization. Zone stance therefore enters a decision as a <strong>claim on the request or a rule in the package</strong>, and a decision that turned on a zone must name the package version that read it.</p>
<p><strong>Tenancy posture</strong> (<code>tenancy-posture_v0.1</code>). Posture is a bounded security-state input, published by its owner and never a privilege source (§8). It enters as a <strong>claim</strong>, carries its own freshness, and the §8 asymmetry binds it: posture may tighten a decision and may never loosen one. A posture too stale to trust is a missing claim, and a missing claim is not permission.</p>
<p><strong>Credential lifecycle</strong> (<code>credential-management_v0.2</code>). Issuance, rotation, and revocation are <code>secrets-engine</code>'s and <code>OpenBao</code>'s, downstream of a decision — a credential is an artifact of authority, never its source. A lifecycle event becomes an <strong>input</strong> to a later decision as a claim (this credential is current, this lease is bound to this task), never a side channel that changes an outcome without appearing in the decision record. Revocation visibility is bounded by §9.7.</p>
<p>Each of the three composes the same way, which is the point: <strong>facts arrive as claims, effects live in versioned policy, and anything that changes an outcome appears in the decision record.</strong></p>
</section>
<section id="s20"><h2><span class="sn">20</span>The Railiance interaction boundary</h2>
<p>Operations is not NetKingdom's. Workload operations are organized by <strong>Railiance</strong>, whose framework repository is <code>railiance-master</code>, and NetKingdom provides the security and approval framework those operations consume. This section states the boundary as it stands today. It is expected to evolve, and it is written here so that evolution is visible rather than inferred.</p>
<p>Definitions are <code>railiance-master</code>'s and are restated, not authored, here.</p>
<h3>20.1 What Railiance organizes</h3>
<p>A <strong>workload</strong> is a managed running deployable. Human commands, credential patterns, broker actions, approvals, and infrastructure resources that are not themselves deployables <strong>are not workloads</strong> — which is why an approval object (§9.4) is not a Railiance axis and never becomes one.</p>
<p>Every workload is operated through four composable axes, each answering a different question about the same workload:</p>
<div class="scroll"><table><thead><tr><th>Prefix</th><th>Axis</th><th>Question</th></tr></thead><tbody><tr><td><code>railiance-*</code></td><td>ownership</td><td>Who owns this capability?</td></tr><tr><td><code>rail-*</code></td><td>execution contract</td><td>How does this workload run?</td></tr><tr><td><code>rapp-*</code></td><td>managed package</td><td>What exactly is packaged and operated?</td></tr><tr><td><code>reef-*</code></td><td>substrate</td><td>Where is it bound, and as what operational reality?</td></tr></tbody></table></div>
<p><code>rein-*</code> is <strong>not a fifth axis</strong>. Reins are <code>glas-harness</code> agent-harness backends; the name echoes <code>rail-*</code> analogically, not taxonomically. Agentic session semantics — session loops, tool policy, harness routing, model selection — belong to <code>glas-harness</code>. When a rein is installed and operated as a managed service it is a workload like any other, packaged and bound through the four axes above.</p>
<h3>20.2 What holds today</h3>
<p>For any Railiance consumer of NetKingdom security, without exception:</p>
<ol><li>Authorization decisions come from <code>access-engine</code> and from nowhere else (§6).</li><li>Approvals are objects in <code>approval-engine</code>, consumed as claims (§9.4).</li><li>Credentials are materialized by <code>secrets-engine</code> <strong>after</strong> a decision, never as a substitute for one.</li><li>Evidence goes to <code>audit-core</code> under the bound in §9.6.</li><li>Anything causing a protected side effect is <strong>PEP-shaped</strong> and owes the four obligations in §6.4 — including a published unreachable-engine stance in the §13.1 register.</li></ol>
<h3>20.3 What is not settled</h3>
<p>The mapping between the axes and this model is deliberately thin, because guessing it would be worse than admitting it:</p>
<ul><li>A <strong><code>rapp-*</code></strong> is the most likely <em>resource</em> a decision is rendered about, but nothing states its identity form in a request claim.</li><li>A <strong><code>rail-*</code></strong> describes how a workload runs and is therefore where PEP shape is most likely to live — but §6.4 obligations attach to repositories, and a rail is a contract, so whether a rail can <em>carry</em> an obligation is unwritten.</li><li>A <strong><code>reef-*</code></strong> answers where a workload is bound, which is adjacent to a security zone (<code>security-zones_v0.1</code>) without being one. <code>zone-engine</code> records that a reef capping availability for everything bound to it is a canon composition problem. That composition is unwritten.</li><li>The <strong><code>railiance-*</code> ownership axis</strong> names who owns a capability, which is adjacent to the principal a decision is rendered for. Adjacent is not equal, and no rule connects them.</li><li><strong><code>glas-harness</code> and reins</strong> hold tool policy and session semantics for agents, while §3.4 rule 2 holds that an agent acts only through a conduit or an engine API. Those two must compose, and neither side may treat its own half as sufficient. That seam is the most consequential of the five, because it is where "tool availability is not permission" is actually enforced or lost.</li></ul>
<h3>20.4 How this boundary changes</h3>
<p>An interaction boundary between two frameworks is owned by neither alone. Changes to §20 require assent from <code>railiance-master</code> for the axis definitions and from <code>glas-harness</code> for the session and tool-policy seam, on the same terms as any other boundary in this standard (§10). NetKingdom states what a consumer owes; it does not define what a rail, rapp, reef, or rein <em>is</em>.</p>
</section><footer><span>netkingdom-security-layer-model-v0.7 · · accepted</span><span>net-kingdom · canon/standards/security-layer-model_v0.7.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

239
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-security-scenario-composition-v0.1.html Normal file
View file

@ -0,0 +1,239 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="17b715d78e04470a0f83b8bc8c7313ab16e13e9e741d5ec445172d9008fce937">
<title>NetKingdom Security Scenario Composition v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-security-scenario-composition-v0.1</span> <span class="stat">proposed</span> <span>net-kingdom</span> <span>reviewed 2026-08-23</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Security Scenario Composition v0.1</h1><p class="sub">Source: <code>net-kingdom · canon/standards/security-scenario-composition_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2026-11-23</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#s1"><span class="n">1</span>Purpose</a></li><li><a href="#s2"><span class="n">2</span>Authority boundary</a></li><li><a href="#s3"><span class="n">3</span>Scenario input</a></li><li><a href="#s4"><span class="n">4</span>Fail-closed selection rules</a></li><li><a href="#s5"><span class="n">5</span>Trust sequencing</a></li><li><a href="#s6"><span class="n">6</span>Composition output</a></li><li><a href="#s7"><span class="n">7</span>Conformance</a></li></ol></nav><main><section id="s1"><h2><span class="sn">01</span>Purpose</h2>
<p>This contract defines the deterministic, plan-only boundary between a requested NetKingdom capability set and the independently owned playbook entry points that can realize it. It consumes conformant Playbook Capability Contract v0.1 declarations and produces an owner-routed responsibility, trust, parameter, and readiness handoff.</p>
<p>Composition answers <strong>what is selected, in which trust order, with which safe parameters, and who must execute and evidence it</strong>. It does not run a playbook, mint a credential, infer authority, or declare a runtime ready.</p>
</section>
<section id="s2"><h2><span class="sn">02</span>Authority boundary</h2>
<ul><li>NetKingdom owns scenario intent, provider selection, parameter-policy checks, trust sequencing, and the composed responsibility map.</li><li>The declaration owner owns the playbook or stable entry point, execution, rollback, and readiness evidence.</li><li>Railiance retains deployment execution for Railiance-owned declarations.</li><li>A composed plan is not authorization to execute. Any approval, custody, credential, or change-window gate named by an owner remains in force.</li></ul>
</section>
<section id="s3"><h2><span class="sn">03</span>Scenario input</h2>
<p>Scenario files conform to <code>canon/schemas/security-scenario_v0.1.schema.json</code>:</p>
<pre>id: scenario:c0-local-identity-reference
authority: netkingdom
initial_trust:
- bare_host_trust
requires:
capabilities:
- c0.bootstrap-identity
providers:
c0.bootstrap-identity: net-kingdom.local-identity
parameter_overrides:
net-kingdom.local-identity:
bootstrap_username: bootstrap-admin</pre>
<p><code>authority</code> uses the Playbook Capability Contract vocabulary: <code>platform</code>, <code>netkingdom</code>, or <code>tenant</code>. Parameter sensitivity and tuning-authority rules are applied before a plan is emitted.</p>
<p><code>initial_trust</code> lists trust states established outside this composition. The composer never assumes an initial trust state. A required state must be present there or be satisfied by an earlier selected declaration.</p>
<p><code>providers</code> pins a required capability to an exact declaration id. A pin is mandatory when more than one valid declaration provides the capability. A pin may not name an unrequested capability or a declaration that does not provide the keyed capability.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Fail-closed selection rules</h2>
<p>Composition fails when any of the following is true:</p>
<ul><li>a declaration is invalid or declaration ids are duplicated;</li><li>a capability is unknown, duplicated, or has no provider;</li><li>multiple providers match and the scenario does not pin one;</li><li>a provider pin does not match the requested capability;</li><li>an override targets an unselected declaration or unknown parameter;</li><li>an override violates type, constraint, sensitivity, or tuning authority;</li><li>a required parameter has neither a default nor an override;</li><li>a required trust state cannot be established without a cycle or inference.</li></ul>
<p>Selection order never resolves ambiguity. Filesystem order, catalog order, lexical order, and prior deployment state are not provider authority.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Trust sequencing</h2>
<p>The composer starts only with the scenario's explicit <code>initial_trust</code> set. It then selects the lexically first <strong>eligible</strong> declaration, where eligible means all of that declaration's required trust states have already been established. After the step, and only for composition purposes, the declaration's satisfied states become available to later steps.</p>
<p>Lexical ordering makes independent eligible steps reproducible; it does not grant one provider precedence during selection. If no remaining declaration is eligible, composition fails and reports the unresolved trust states.</p>
<p>Readiness checks attached to a satisfied state are obligations for the owning executor. They are not marked satisfied merely because the plan contains them.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Composition output</h2>
<p>A successful output has <code>apiVersion: netkingdom.io/security-scenario-composition/v0.1</code> and <code>kind: SecurityScenarioComposition</code>. It contains:</p>
<ul><li>the requested capabilities and exact selected declaration ids;</li><li>effective parameter values with their source, sensitivity, and tuning authority;</li><li>ordered execution handoffs containing owner, repository, entry point, required trust, produced trust, and readiness obligations;</li><li>a flattened responsibility map attributable to declaration ids;</li><li>the final <em>planned</em> trust-state set;</li><li>an explicit <code>execution.permitted: false</code> boundary.</li></ul>
<p>The output is non-secret planning material. Declarations and scenarios must use secret references rather than secret values as required by the Playbook Capability Contract.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Conformance</h2>
<p>Use the canonical tool:</p>
<pre>python3 tools/security-scenario-composer/security_scenario_composer.py \
--scenario &lt;scenario.yaml&gt; &lt;declaration.yaml&gt; [&lt;declaration.yaml&gt; ...]</pre>
<p>Exit zero means the declarations and scenario compose deterministically. It does not mean the plan was executed or its readiness evidence was observed.</p>
</section><footer><span>netkingdom-security-scenario-composition-v0.1 · · proposed</span><span>net-kingdom · canon/standards/security-scenario-composition_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

320
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-security-zones-v0.1.html Normal file
View file

@ -0,0 +1,320 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="32e71e9c0d6946bb14099eb66193822da26f199de0e11d8488464207f3bd9906">
<title>NetKingdom Security Zones v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-security-zones-v0.1</span> <span class="stat">proposed</span> <span>zone-engine</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Security Zones v0.1</h1><p class="sub">Source: <code>net-kingdom · canon/standards/security-zones_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2026-11-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#s1"><span class="n">1</span>Purpose</a></li><li><a href="#s2"><span class="n">2</span>Authority and conformance</a></li><li><a href="#s3"><span class="n">3</span>Resolution is authoritative</a></li><li><a href="#s4"><span class="n">4</span>Zone catalog</a></li><li><a href="#s5"><span class="n">5</span>Stance and failure-mode model</a></li><li><a href="#s6"><span class="n">6</span>Declaration in `tenancy.yaml`</a></li><li><a href="#s7"><span class="n">7</span>Compilation and resolved view</a></li><li><a href="#s8"><span class="n">8</span>Membership-change observability</a></li><li><a href="#s9"><span class="n">9</span>Time-boxed exceptions</a></li><li><a href="#s10"><span class="n">10</span>Adoption</a></li></ol></nav><main><section id="s1"><h2><span class="sn">01</span>Purpose</h2>
<p>A security zone is a named workload-admission standard. It answers which scrutiny a workload has qualified for; control-owner policy then answers what a particular control does in that zone. A zone is not a repository label, a credential lane, a network segment, a reef, or a temporary exception.</p>
<p>This standard is a sibling of <code>tenancy-posture_v0.1</code>. It owns zone identity, membership, admission, resolution, and the time-boxed exception lifecycle. <code>flex-auth</code> remains the only PDP for decisions it renders. Every other control continues to be owned and evaluated at its existing enforcement point.</p>
</section>
<section id="s2"><h2><span class="sn">02</span>Authority and conformance</h2>
<p>Authority is split deliberately:</p>
<div class="scroll"><table><thead><tr><th>Fact or rule</th><th>Authority</th></tr></thead><tbody><tr><td>Workload identity and requested membership</td><td>Workload's responsible repo</td></tr><tr><td>Zone identities and admission standards</td><td>This standard, owned by zone-engine</td></tr><tr><td>Per-zone stance</td><td>Owner of the control that renders the effect</td></tr><tr><td>Failure behavior when a dependency is unavailable</td><td>Owner of the PEP</td></tr><tr><td>Publication</td><td>net-kingdom canon</td></tr></tbody></table></div>
<p>Conformance is <strong>accuracy, not altitude</strong>. A lower zone declared with evidence is conformant. A stricter zone that the workload cannot evidence is not. Changing membership to evade a control is not an exception mechanism.</p>
<p>The workload is the sole <strong>zone</strong> policy subject. It includes independently governed application, automation, maintenance, and operational/control-plane execution units. The workload executing a tunnel, credential broker, policy service, or maintenance operation requires identity; the tunnel, grant, lane, pattern, action, human, or agent does not become a workload merely because a control observes it. Those retain native typed identity and caller/resource context.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>Resolution is authoritative</h2>
<p>The stable <code>workload_identity.name</code> is the join key. Runtime principals, resources, credential lanes, and controls reference it explicitly. A resolver MUST NOT infer membership from repository ownership, paths, lane types, actor classes, environment, criticality, reefs, organization posture, or naming conventions.</p>
<p>For a managed deployable, the authoritative cross-repository reference is the Repo Manager v1 tuple <code>(rapp_id, workload_identity.name)</code>, optionally narrowed by <code>deployable</code>. A catalog also declares whether its subject is workload applicable. Resolution returns both the reference result and admission result:</p>
<ul><li><code>satisfied</code> — the workload has an authoritative identity and evidence meeting the declared zone's floor; <code>effective_zone</code> is the declared zone;</li><li><code>unsatisfied</code> — identity and membership are declared, but evidence is below the admission floor; <code>effective_zone</code> is <code>unknown</code>;</li><li><code>unknown</code> — identity, membership, or a required floor/evidence input cannot be resolved for a workload-applicable subject; <code>effective_zone</code> is <code>unknown</code>;</li><li><code>not-applicable</code> — the owning catalog explicitly establishes that the subject is an action, actor, lane, pattern, or resource rather than a workload; no zone is resolved and the control uses that subject's native identity.</li></ul>
<p><code>unknown</code> is a result, not a zone. A control MUST declare an explicit treatment for it. That treatment may deny, escalate, or use a reviewed build-stage rule; it never manufactures membership and never grants an exception.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Zone catalog</h2>
<p>The initial catalog follows the estate's existing <code>M0</code>–<code>M3</code> maturity ladder and adds one non-monotone continuity band required by ops-warden <code>ADR-0006</code>.</p>
<div class="scroll"><table><thead><tr><th>Zone id</th><th>Admission floor</th><th>Environment/data boundary</th><th>Purpose</th></tr></thead><tbody><tr><td><code>z0-experimental</code></td><td><code>M0</code> promotion evidence</td><td>Synthetic only; no real credential or user data</td><td>Experiments where advisory controls preserve iteration speed</td></tr><tr><td><code>z1-operational</code></td><td><code>M1</code> promotion evidence</td><td>Production secret handling for at most <code>internal</code> data</td><td>Early operational workloads with an owned front door</td></tr><tr><td><code>z2-protected</code></td><td><code>M2</code> promotion evidence</td><td><code>prod</code>; at most <code>confidential</code> data</td><td>Production workloads requiring review, SLO/on-call, and incident readiness</td></tr><tr><td><code>z3-critical</code></td><td><code>M3</code> promotion evidence</td><td><code>prod</code>; at most <code>restricted</code> data</td><td>Critical or regulated workloads with the strongest normal failure behavior</td></tr><tr><td><code>z2-continuity</code></td><td><code>M2</code> plus dependency/recovery evidence</td><td><code>prod</code>; at most <code>confidential</code> data</td><td>Foundational access or recovery workloads where fail-closed dependency cycles would cause an outage</td></tr></tbody></table></div>
<p><code>z2-continuity</code> is a sibling of <code>z2-protected</code>, not a relaxation of its admission floor. It exists because enforcement stance is not monotone: a tunnel or credential-issuance path can require production scrutiny while deliberately remaining fail-open for one availability-sensitive control. Placement on a reef is never evidence for any zone.</p>
<h3>4.1 Context floor</h3>
<p>The declared zone must be at least as strict as the workload context requires. The context floor is the maximum of every resolved input:</p>
<div class="scroll"><table><thead><tr><th><code>criticality</code></th><th>Minimum maturity</th></tr></thead><tbody><tr><td><code>low</code></td><td><code>M0</code></td></tr><tr><td><code>medium</code></td><td><code>M1</code></td></tr><tr><td><code>high</code></td><td><code>M2</code></td></tr><tr><td><code>critical</code></td><td><code>M3</code></td></tr></tbody></table></div>
<p>Data-class floors are consumed from the canon-owned classification mapping; the current <code>synthetic → M0</code>, <code>internal → M1</code>, <code>confidential → M2</code>, and <code>restricted → M3</code> mapping is already used by ops-warden. An absent or unresolved floor makes admission <code>unknown</code>. In particular, <code>public</code> is disclosure policy and <code>synthetic</code> is data origin: they are not aliases, and this standard does not invent a floor while info-tech-canon's ruling is pending.</p>
<p><code>organization_posture</code> may select a versioned control profile, but it never changes identity, membership, or admission.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Stance and failure-mode model</h2>
<p>Every owner-qualified control publishes a total mapping over all zone ids plus <code>unknown</code>. There is no implicit default.</p>
<ul><li><code>enforced</code> — the control's deny or escalation effect changes the outcome;</li><li><code>advisory</code> — the control evaluates fully and records the outcome it would have produced, but does not block;</li><li><code>exempt</code> — the control is deliberately not evaluated for this zone and emits the versioned exemption reason.</li></ul>
<p>Failure mode is separate and PEP-side:</p>
<ul><li><code>fail_closed</code> — an unavailable or invalid evaluator produces the control's safe blocking/escalation outcome;</li><li><code>fail_open</code> — the PEP proceeds and records that the control was unavailable.</li></ul>
<p><code>exempt</code> has no failure mode. A local control with no remote dependency uses <code>fail_closed</code> to describe evaluator errors. Changing stance is a policy-package change owned by the control owner, not a membership change.</p>
<h3>5.1 Initial build-stage control profile</h3>
<p>This profile is the v0.1 proposal for the first consumer. It is not stored in a workload's <code>zones:</code> declaration. flex-auth owns the pre-sign rows; ops-warden owns the other rows and every PEP failure mode.</p>
<div class="scroll"><table><thead><tr><th>Zone</th><th>flex-auth pre-sign stance / ops-warden PEP</th><th>agent high-risk read boundary</th><th><code>warden plan</code> zone rule</th></tr></thead><tbody><tr><td><code>z0-experimental</code></td><td><code>advisory</code> / <code>fail_open</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>advisory</code>; evaluator failure cannot produce <code>autonomous</code></td></tr><tr><td><code>z1-operational</code></td><td><code>advisory</code> / <code>fail_open</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>advisory</code>; evaluator failure cannot produce <code>autonomous</code></td></tr><tr><td><code>z2-protected</code></td><td><code>enforced</code> / <code>fail_open</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>enforced</code>; minimum <code>founder_required</code> when the zone rule matches</td></tr><tr><td><code>z3-critical</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>enforced</code>; minimum <code>founder_required</code> when the zone rule matches</td></tr><tr><td><code>z2-continuity</code></td><td><code>enforced</code> / <code>fail_open</code></td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>enforced</code>; minimum <code>founder_required</code> when the zone rule matches</td></tr><tr><td><code>unknown</code></td><td><code>advisory</code> / <code>fail_open</code> under the versioned <code>build</code> profile</td><td><code>enforced</code> / <code>fail_closed</code></td><td><code>enforced</code>; never <code>autonomous</code> from zone evidence</td></tr></tbody></table></div>
<p>The <code>unknown</code> pre-sign treatment is an explicit organization-build policy, not a permissive membership default. It must change through a versioned control profile when the organization posture graduates.</p>
<p>The agent read boundary stays enforced in every zone: build-stage permissiveness does not extend to disclosing high-risk credentials. For a missing lane risk:</p>
<ul><li><code>z0-experimental</code> may resolve to <code>standard</code> only when admission proves the lane can expose synthetic material exclusively;</li><li><code>z1-operational</code> and <code>z2-protected</code> resolve to at least <code>high</code>;</li><li><code>z3-critical</code> resolves to <code>critical</code>, treated by the boundary as at least <code>high</code>; and</li><li>unresolved membership resolves to at least <code>high</code>.</li></ul>
<p>An explicit grade always remains preferable. <code>accepted</code> is an acceptance record, not a risk grade.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Declaration in <code>tenancy.yaml</code></h2>
<p>For a single-service declaration, <code>zones:</code> is a sibling of <code>tenancy:</code> and <code>workload_identity</code>. For a <code>services:</code> declaration, both <code>workload_identity</code> and <code>zones</code> occur inside the same service entry. A multi-service file MUST NOT use a top-level <code>zones:</code> block.</p>
<p>Every managed running deployable has an authoritative <code>rapp-*/declarations/rapp.yaml</code>. Its <code>workload_identity.declaration_ref</code> points to that declaration, and consuming catalogs reference it using the Repo Manager v1 tuple. A pre-rapp deployable is migration debt and resolves <code>unknown</code>. An independently governed operational execution unit that is not a managed deployable may declare directly in its responsible repo's <code>tenancy.yaml</code>; this does not turn a human action or infrastructure resource into a fictional rapp or workload.</p>
<pre>schema_version: &quot;0.1&quot;
framework: netkingdom-tenancy-posture
service: ops-bridge-tunnel
role: operational-access-path
workload_identity:
name: ops-bridge-tunnel
kind: operational-control-plane
responsible_repo: ops-bridge
identity_bindings:
- scheme: ssh-certificate
authority: ops-warden
subject: agt-ops-bridge
principal_type: agent
environment: prod
tenancy:
# tenancy-posture_v0.1 content omitted
zones:
standard: security-zones_v0.1
membership: z2-continuity
responsible_party: ops-bridge
justification: foundational tunnel path must retain availability under PDP loss
context:
maturity: M2
criticality: high
data_classification: confidential
evidence:
- ref: docs/evidence/ops-bridge-tunnel-zone.md
supports: [M2, continuity-dependency, recovery]
reviewed: &quot;2026-08-22&quot;
review_due: &quot;2026-11-22&quot;</pre>
<p>The <code>zones:</code> block contains only membership evidence. It MUST NOT contain control stance, failure mode, organization posture, or exceptions.</p>
<p>Required fields are:</p>
<ul><li><code>standard</code> — exactly <code>security-zones_v0.1</code>;</li><li><code>membership</code> — one zone id from §4;</li><li><code>responsible_party</code> — the party answering for this membership;</li><li><code>justification</code> — why the zone fits the workload's actual context;</li><li><code>context</code> — the evidenced <code>maturity</code>, <code>criticality</code>, and <code>data_classification</code> used for admission. A managed workload's latter two values must agree with its resolved rapp projection; <code>n/a</code> requires an evidence-backed reason;</li><li><code>evidence</code> — one or more references and the admission facts each supports;</li><li><code>reviewed</code> and <code>review_due</code> — ISO dates, with review due after review.</li></ul>
<p>Permanent membership changes are reviewed source changes. A change to a lower floor also records its reason and approver in the change review. Temporary relaxation uses an exception and never changes <code>membership</code>.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Compilation and resolved view</h2>
<p>Compilation produces a workload-addressable resolved record. At minimum it contains:</p>
<pre>workload_id: ops-bridge-tunnel
workload_ref:
applicability: applicable
rapp_id: null # required for a managed deployable
name: ops-bridge-tunnel
deployable: null # optional for a managed deployable
identity_binding: ssh-certificate/ops-warden/agt-ops-bridge
declared_zone: z2-continuity
admission: satisfied
effective_zone: z2-continuity
membership_revision: sha256:&lt;digest&gt;
guarantees:
- authoritative-workload-identity
- explicit-zone-membership
- non-inferred-resolution
- enforcement-time-exception-expiry
controls:
- id: flex-auth/pre-sign
policy_owner: flex-auth
stance: enforced
pep_owner: ops-warden
failure_mode: fail_open
policy_ref: &lt;versioned-package&gt;</pre>
<p>The <code>membership_revision</code> covers the authoritative workload binding, <code>zones:</code> block, and source revision. Control results include their policy/profile version and any active exception id and expiry. This is the machine-readable answer to “which zone is this workload in, and what applies there?” It may be compiled into existing consumer artifacts; it is not a synchronous zone-engine lookup.</p>
<p>For managed deployables, compilation consumes the exact Repo Manager reference projection:</p>
<pre>workload_ref:
applicability: applicable
rapp_id: rapp-issue-core
name: issue-core
deployable: issue-core # optional</pre>
<p>The owning catalog uses <code>applicability: not-applicable</code> for a native non-workload subject. Absence of either applicability or an expected reference is <code>unknown</code>, not <code>not-applicable</code>. Zone-engine consumes these outcomes; it does not parse a path or repository name to repair them.</p>
<p>For flex-auth's pre-sign control, the governed workload is the target of the certificate or grant, so the compiler writes <code>workload_id</code>, <code>security_zone</code>, <code>security_zone_admission</code>, and <code>security_zone_revision</code> on the resource attributes. Caller identity remains in the subject. A control that governs the requesting workload must declare that role explicitly and use separately named caller-workload attributes.</p>
<p>The dormant <code>trust_zone: platform</code> constant is not security-zone membership and MUST be retired before adoption. The new concept is named <code>security_zone</code>; the two fields must not coexist as competing zone sources.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Membership-change observability</h2>
<p>A membership change becomes effective only through a reviewed declaration and a newly compiled artifact. The compiler emits the source and membership revision, rejects ambiguous identities, and reports additions, removals, and changes against the preceding snapshot. Controls expose the membership revision in their decision or verdict evidence.</p>
<p>A zone that can be widened by editing an unversioned runtime label is not conformant.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Time-boxed exceptions</h2>
<p>The normative lifecycle is the ZONE-WP-0001-T04 decision in <code>zone-engine/docs/exception-lifecycle-2026-08-22.md</code>: only the control owner's designated authority grants a named-workload, named-zone, named-control relaxation within a declared maximum duration. Enforcement applies it only for <code>not_before &lt;= now &lt; not_after</code>; invalid or unevaluable records are inactive, expiry restores the base rule automatically, and no minted credential, lease, or session may outlive the exception.</p>
<p>Exceptions live with the versioned control policy or PEP configuration and are evaluated where their effects occur. This requires no zone-engine runtime.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Adoption</h2>
<p>Net-kingdom published this standard at revision <code>337484a</code>. Adoption requires:</p>
<ol><li>flex-auth and ops-warden accept the initial control profile or publish a versioned replacement with total zone and <code>unknown</code> coverage;</li><li>at least two workload owners declare authoritative identities and zones;</li><li>a third consumer compiles or reads the resolved view; and</li><li>ops-warden retires <code>policy.enabled</code> and the dormant <code>trust_zone</code> constant in the same migration.</li></ol>
<p>All four gates were met on 2026-08-22. The owning zone-engine repository records the exact consumer revisions, tests, resolved membership digests, and live caller decision in <code>docs/evidence/security-zone-adoption-2026-08-22.md</code>.</p>
</section><footer><span>netkingdom-security-zones-v0.1 · · proposed</span><span>net-kingdom · canon/standards/security-zones_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

496
docs/evidence/2026-10-11-served-publication-history/pages/netkingdom-tenancy-posture.html Normal file
View file

@ -0,0 +1,496 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="ce198fc2905687ea90a2892346b6860281ac87f8">
<meta name="policy-source-digest" content="27d6878c68310619877de516000d9af78d5456a92572a709884ed052d765b876">
<title>NetKingdom Tenancy Posture v0.1</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-tenancy-posture</span> <span class="stat">proposed · draft-14</span> <span>net-kingdom</span> <span>reviewed 2026-08-23</span><span>generated from canonical source — do not edit</span></div><h1>NetKingdom Tenancy Posture v0.1</h1><p class="sub">A framework for describing, holding and improving multi-tenancy — including where we are not there yet.</p><p class="sub">Source: <code>net-kingdom · canon/standards/tenancy-posture_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</code></p><p class="sub">Review due: 2027-02-23</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#s0"><span class="n">0</span>Terminology: axes, not planes</a></li><li><a href="#s1"><span class="n">1</span>Context</a></li><li><a href="#s2"><span class="n">2</span>What this document is</a></li><li><a href="#s3"><span class="n">3</span>Six orthogonal axes</a></li><li><a href="#s4"><span class="n">4</span>Graduated levels</a></li><li><a href="#s5"><span class="n">5</span>The posture vector</a></li><li><a href="#s6"><span class="n">6</span>Conformance is accuracy, not altitude</a></li><li><a href="#s7"><span class="n">7</span>Portability across placement levels</a></li><li><a href="#s8"><span class="n">8</span>Placement triggers</a></li><li><a href="#s9"><span class="n">9</span>Credentials as a tenancy control</a></li><li><a href="#s10"><span class="n">10</span>Blast radius must be published</a></li><li><a href="#s11"><span class="n">11</span>Commercial expression</a></li><li><a href="#s12"><span class="n">12</span>Methodology — analyze, establish, improve, guard</a></li><li><a href="#s13"><span class="n">13</span>Evidence per level</a></li><li><a href="#s14"><span class="n">14</span>Adoption stance — structure, not tooling</a></li><li><a href="#s15"><span class="n">15</span>Alternatives considered</a></li><li><a href="#s16"><span class="n">16</span>Held against outside practice</a></li><li><a href="#s17"><span class="n">17</span>Scaling demands</a></li><li><a href="#s18"><span class="n">18</span>Consequences</a></li><li><a href="#s19"><span class="n">19</span>Review resolutions and residual questions</a></li><li><a href="#s20"><span class="n">20</span>Ratification path</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p><strong>Proposed, draft-13; ratification-ready.</strong> Relocated from <code>the-custodian/canon/architecture</code> on 2026-08-17: multi-tenancy is part of the IT-security framework NetKingdom provides, so this framework belongs in NetKingdom canon beside the IAM Profile and the tenant-engine boundary contract, not in the work-factory canon.</p>
<ul><li><strong>draft-1</strong> proposed a single model with fixed characteristics. Rejected: it could not describe a repo that is not there yet.</li><li><strong>draft-2</strong> reframed to graduated levels per axis. Externally corroborated (§16), but four of its statements were wrong and one thing it needed was missing.</li><li><strong>draft-3</strong> applied those corrections, added the retention axis, and recorded an adoption stance.</li><li><strong>draft-4</strong> closed the two gaps draft-3 left open: <code>R4</code> had no mechanism beyond waiting, and the noisy-neighbour evidence artifact asserted something shared infrastructure cannot provide.</li><li><strong>draft-5</strong> relocated to NetKingdom and renamed the dimensions from <em>planes</em> to <em>axes</em>, because the word was already taken (§0).</li><li><strong>draft-6</strong> applied <code>tenant-engine</code>'s review: five changes, including an axis that did not fit its data shape.</li><li><strong>draft-7</strong> applies <code>audit-core</code>, <code>railiance-platform</code> and <code>flex-auth</code>. Eleven further changes, two of them corrections to statements this document made as fact about other repos. <strong>Every posture I guessed was too generous, on every repo that has now self-reported.</strong></li><li><strong>draft-8</strong> applies <code>adaptive-pricing</code>'s review, the last of the six, and the consistency review across all declarations. It adds the missing availability axis, a canonical declaration schema, explicit authority for tier assurance, retention/placement coupling, downgrade propagation, and honest sanctioned customer language. It also corrects the distinction between an implemented control and an evidenced current level.</li></ul>
<ul><li><strong>draft-9</strong> answers <code>zone-engine</code>'s <code>ZONE-WP-0001-T01</code>. It rules that enforcement stance is <strong>not</strong> a seventh axis (Decision 5.6) while reserving <code>zones:</code> in <code>tenancy.yaml</code> so the estate keeps one declaration surface, and it records the reef/<code>P</code>/<code>V</code> reconciliation as an open defect of this document rather than of the repo that noticed it (Decision 8.4).</li><li><strong>draft-10</strong> answers <code>zone-engine</code>'s <code>ZONE-WP-0001-T03</code>. It keeps the workload as the sole security-zone policy subject, makes operational and control-plane execution units part of that term, and requires unresolved workload identity or membership to remain <code>unknown</code> without zone inference (Decision 5.6.1). It also closes the textual reef/<code>P</code> boundary while leaving the substrate-provider declaration and mechanical <code>V</code> join as implementation work (Decision 8.4.2).</li><li><strong>draft-11</strong> makes that ruling declarable. A <code>zones:</code> block now requires an authoritative <code>workload_identity</code> beside it, including for non-<code>rapp</code> operational workloads; multi-service files carry both per service. Missing identity remains absence rather than a guessed join (Decision 5.6.2).</li><li><strong>draft-12</strong> reconciles that declaration with RMGR-ADR-004 and the published <code>security-zones_v0.1</code> proposal. Managed deployables use their authoritative rapp declaration and the exact Repo Manager reference tuple; independently governed operational execution units that are not managed deployables may declare locally. Native actions, actors, lanes, patterns, and resources are explicitly <code>not-applicable</code>, while omitted or unresolved workload references remain <code>unknown</code> (Decision 5.6.2).</li><li><strong>draft-13</strong> advances the <code>audit-core</code> worked example from E1 to E2 after bounded adversarial run <code>WH-ENG-20260822-AUDIT-E2-03</code> supplied the artifact required by §13.2. The claim remains explicitly bounded and freshness-dated: the attempted cross-tenant attacks did not work; this is not a universal isolation proof.</li><li><strong>draft-14</strong> makes evidence freshness and remediation ownership declarable. Adversarial evidence may now carry its observation and expiry timestamps, bounded scope, responsible repository, and replacement action. A separate proposal-only evaluator treats absent authoritative owner or freshness as <code>unknown</code>; it does not infer either or mutate the declared posture.</li></ul>
<p><strong>Reviewed by all six. The score:</strong> six repos found three live defects in their own code by reading the ladders — <code>tenant-engine</code>'s unfiltered event accessor, <code>audit-core</code>'s unfiltered read path, <code>flex-auth</code>'s unauthenticated <code>/v1/check</code> — and <code>railiance-platform</code> found <code>apps-pg</code> running with no backup configured at all while writing its §10.2 disclosure. The framework changed to fit the repos; no repo was told to fabricate a posture.</p>
<p>Informed by five external research digests plus their index in <code>the-custodian/research/2026-08-17-adr008-*</code>, which carry full citations for the external claims made here.</p>
</section>
<section id="s0"><h2><span class="sn">00</span>Terminology: axes, not planes</h2>
<p><code>docs/platform-identity-security-architecture.md</code> — accepted, 2026-07-23 — already uses <strong>plane</strong> for a trust and deployment layer: the <em>bootstrap plane</em>, the <em>platform control plane</em>, and <em>tenant planes</em>. That meaning is established, ratified, and owned by this repo.</p>
<p>Drafts 1–4 of this document, written elsewhere, used <strong>plane</strong> for something different: an independent dimension of concern. Two incompatible senses of one word inside one canon is exactly the concept-ownership collision the estate has been careful about elsewhere, and the newcomer yields.</p>
<p>This framework therefore describes six <strong>axes</strong>. They are orthogonal to NetKingdom's planes, not a subdivision of them:</p>
<ul><li>A <strong>plane</strong> is <em>where</em> something runs and what trust it carries — bootstrap, platform control, tenant.</li><li>An <strong>axis</strong> is <em>which property</em> of tenancy is being described — identity, authorization, enforcement, placement, retention, availability.</li></ul>
<p>A workload in the tenant plane has a position on all six axes. A platform control plane service does too. The two vocabularies compose and neither replaces the other.</p>
<p>The rename is also an improvement. A posture vector is literally a point in six-dimensional space, and "axis" says that where "plane" did not.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Context</h2>
<p>Drafts 1–4 opened by claiming the estate "has never written down what it is building". Relocation proved that wrong, and the correction is worth keeping visible: <code>docs/platform-identity-security-architecture.md</code> has described the trust model, the tenant model and a capability progression since 2026-07-23. The accurate claim is narrower — <strong>what was missing is a way to say how far a given service has got, and to hold several answers at once.</strong> Seven documents cover slices of the subject and none of them does that:</p>
<div class="scroll"><table><thead><tr><th>Document</th><th>Covers</th><th>Status</th></tr></thead><tbody><tr><td><code>iam-profile_v0.3</code> (NetKingdom)</td><td>Tenant identifier shape, <code>tenant_roles</code> claim, staleness rules</td><td>Ratified</td></tr><tr><td><code>tenant-engine-boundary-contract_v0.1</code> (NetKingdom)</td><td>Who owns tenant records, roles, plan assignment</td><td>Ratified</td></tr><tr><td><code>business-app-service-contract_v0.1</code> §1 (Custodian)</td><td>Business apps: instance-per-client, tenant-keyed data</td><td>Ratified</td></tr><tr><td><code>rapp-postgres</code> ADR-0001</td><td>Consumer + tenant isolation in PostgreSQL</td><td>Proposed, governs one repo</td></tr><tr><td><code>rapp-postgres</code> ADR-0002</td><td>Per-consumer retention and the erasure horizon</td><td>Proposed, governs one repo</td></tr><tr><td><code>shared-platform-relational-storage_v0.1</code></td><td>The stacked-boundary gap</td><td>Routed 2026-08-10, <strong>still unratified</strong></td></tr><tr><td><code>platform-identity-security-architecture</code> (NetKingdom)</td><td>Trust model, planes, tenant model, capability progression</td><td>Accepted 2026-07-23</td></tr></tbody></table></div>
<p>This document is downstream of that architecture and must not restate it. It answers one question the architecture leaves open: given the model, <strong>where is this particular service today, and how would anyone know?</strong></p>
<p>Four failures existed when drafting began.</p>
<p><strong>The gap was diagnosed once and the fix stalled.</strong> The v0.1 draft was written to fill this hole and has sat unratified in neither canon directory. §20 attaches a ratification path so this one does not join it.</p>
<p><strong>Placement was owned by nobody.</strong> <code>user-engine-pg</code> and <code>target-revenue-pg</code> are dedicated; <code>apps-pg</code>, <code>net-kingdom-pg</code>, <code>platform-pg</code>, <code>state-hub-db</code> and <code>forgejo-db</code> are shared. Both live, neither written down. <code>tenant-engine</code> raised this with <code>railiance-platform</code> on 2026-08-16. Draft-8 resolves the authority split in §8.2.</p>
<p><strong>Two contradictory defaults were already ratified.</strong> Business apps get instance-per-client; platform services pool. Nothing says which shape a new service takes, and no definition separates the categories. Decision 4.4.1 now supplies the default; §19.4 retains the missing classification rule.</p>
<p><strong>There is no honest way to describe a repo that is not there yet.</strong> The estate absorbs repos with weak or absent tenant separation. Today such a repo is simply non-conformant, leaving it two bad options: misrepresent its posture, or stay outside the framework.</p>
</section>
<section id="s2"><h2><span class="sn">02</span>What this document is</h2>
<p><strong>A framework, not a model.</strong> It specifies no single correct implementation. It supplies terminology (§3, §4), a declaration (§5), a conformance rule (§6), methodology (§12), and evidence definitions (§13).</p>
<p>A service is conformant when its declared posture is accurate and its trajectory recorded. A service is non-conformant when it claims a level it cannot evidence — regardless of how high or low that level is.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>Six orthogonal axes</h2>
<p>"Is this multi-tenant?" is treated as one question. It is six, and they are independent:</p>
<div class="scroll"><table><thead><tr><th>Axis</th><th>Question</th><th>Vocabulary owner</th></tr></thead><tbody><tr><td><strong>Identity (I)</strong></td><td>How is a tenant named and validated?</td><td><code>tenant-engine</code> / IAM Profile</td></tr><tr><td><strong>Authorization (A)</strong></td><td>How is a request bound to the tenants it may act for?</td><td><code>flex-auth</code></td></tr><tr><td><strong>Enforcement (E)</strong></td><td>Where, mechanically, is the tenant boundary enforced?</td><td>This framework</td></tr><tr><td><strong>Placement (P)</strong></td><td>Which substrate holds a tenant's data?</td><td><code>railiance-platform</code></td></tr><tr><td><strong>Retention (R)</strong></td><td>How long does data persist, and how is it erased?</td><td>The storage platform; policy by the consumer</td></tr><tr><td><strong>Availability (V)</strong></td><td>What failure can the complete service path survive, and within what recovery objective?</td><td>The delivering service; substrate facts by its providers</td></tr></tbody></table></div>
<p>Conflation produces errors today. <code>rapp-postgres</code>'s <code>PostgresConsumer</code> carries <code>tenantIsolation: consumer-service-boundary</code> — an <strong>E</strong>-axis fact in a <strong>P</strong>-axis artifact, reading as though storage enforces something it does not. The "dedicated versus shared" argument mixes P (capacity, blast radius) with E (correctness).</p>
<p>The axes are separated <em>precisely so each may sit at a different level</em>.</p>
<p><span class="dec">Decision 3.1:</span> every document, declaration and plan tier that says "isolation" MUST name which axis it means.</p>
<p><span class="dec">Decision 3.2:</span> the axes couple at their tops and the couplings MUST be stated where they apply, not used to argue the axes are one:</p>
<ul><li><code>E4</code> is reachable only at <code>P3</code> or above.</li><li><code>R</code>'s erasure horizon is bounded below by <code>P</code> — on shared substrate, a consumer's horizon is the instance maximum (§4.5).</li><li><code>R4</code> by key destruction is bounded by the <strong>key boundary</strong>, which is an E-axis property. Shredding a single tenant's data requires the application to encrypt under a per-tenant key before writing; the storage platform cannot supply it. <strong>Reaching the top of the retention ladder is not a retention project.</strong></li><li><code>V</code> composes as the <strong>minimum across the critical request path</strong>, not the maximum of its components. A replicated application on a single-instance database is not V2. A tested degraded mode may remove a dependency from that path, but the bypass itself is part of the V evidence.</li></ul>
<p><span class="dec">Decision 3.3 — scope.</span> The P and R ladders describe a service's <strong>primary datastore</strong>. The V ladder describes the service's complete critical request path, including providers it synchronously depends on. Caches, search indices, message queues and background jobs are named leak surfaces in the external baselines and are assessed separately, not silently covered by a datastore level. A declaration names material secondary stores and asynchronous paths as exceptions rather than implying that one vector proves them safe.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Graduated levels</h2>
<p>Each axis carries an ordered ladder. Higher is stronger, not better: the right level is the one a service can evidence and its risk warrants.</p>
<h3>4.1 Identity (I)</h3>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Identity<span>axis I</span></div><div class="rungs"><div class="rung r0"><span class="code">I0</span><span class="txt">No tenant concept. Data not attributable to a tenant.</span></div><div class="rung r1"><span class="code">I1</span><span class="txt">A local tenant notion exists but is not canonical, <strong>or</strong> the tenant is taken from the request rather than from a verified token.</span></div><div class="rung r2"><span class="code">I2</span><span class="txt">Canonical identifiers, bound at the identity provider and carried as a verified claim, <strong>and verified by this service on its own inbound calls</strong>.</span></div><div class="rung r3"><span class="code">I3</span><span class="txt">I2 plus capability roles honoured, with live <code>tenant-engine</code> re-query for privileged, destructive, credential-vending or <code>aal2</code>-class decisions.</span></div><div class="rung na"><span class="code">—</span><span class="txt">Ladder ends at I3.</span></div></div></div>
</div></div>
<p>I1 now explicitly absorbs request-supplied tenant identifiers. "Never trust client-supplied tenant IDs without validation" is a named anti-pattern; a service reading the tenant from a header is at I1 however canonical the string.</p>
<p><strong>An axis is assessed on a service's own inbound surface, never on its authority over the concept.</strong> <code>tenant-engine</code> is the source of existence for tenant records and is nonetheless at I1, because it takes the acting identity from the request body rather than from a verified token. Draft-5 conflated these by naming the authority inside the I2 definition, which made the level describing canonical identity unclaimable by the service that provides it. Corrected on tenant-engine's review — a reader would otherwise assume the authority must be at I2 by definition.</p>
<p><code>business-app-service-contract</code> §2.1 sets app-local accounts as the v1 baseline for business apps — a sanctioned low level with recorded triggers for moving up. That is the pattern this framework generalises.</p>
<h3>4.2 Authorization (A)</h3>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Authorization<span>axis A</span></div><div class="rungs"><div class="rung r0"><span class="code">A0</span><span class="txt">No authorization, or tenant context not carried.</span></div><div class="rung r1"><span class="code">A1</span><span class="txt">Ad-hoc checks scattered through handlers.</span></div><div class="rung r2"><span class="code">A2</span><span class="txt">A single local authorization boundary; tenant context bound once, centrally.</span></div><div class="rung r3"><span class="code">A3</span><span class="txt">Decisions delegated to <code>flex-auth</code> as PDP, with live re-query where the IAM Profile requires it.</span></div><div class="rung r4"><span class="code">A4</span><span class="txt">A3 over a <strong>standard</strong> PDP interface (OpenID AuthZEN Authorization API 1.0), so the decision point is swappable and the enforcement point is not coupled to one engine's request shape.</span></div></div></div>
</div></div>
<p><strong>This ladder describes enforcement points.</strong> A decision point cannot occupy A3 — "delegated to <code>flex-auth</code>" is not something <code>flex-auth</code> can do. A service that <em>is</em> a PDP declares <strong>two numbers</strong>: its own inbound level, and the maximum it enables for consumers. <code>flex-auth</code> reads <code>A0, enables A3</code> — accurate, and considerably more alarming than <code>A3</code>, which is the point. Raised by <code>flex-auth</code>, whose absence from the §5 worked examples was this surfacing implicitly.</p>
<p>A4 is new. The specification reached Final in January 2026 and Keycloak shipped experimental support in May; the argument for it is <strong>interoperability</strong> — a swappable decision point and an enforcement point not coupled to one engine's request shape.</p>
<p><em>Correction from flex-auth's review:</em> earlier drafts also justified A4 as ending the copying of action strings between repos. <strong>It does not.</strong> AuthZEN standardises the envelope — subject, action, resource, context, endpoint — and deliberately does not standardise the action vocabulary or the policy language. At A4, <code>tenant.guardrail.set</code> still has to be agreed and still gets copied. Those are two problems with different fixes, and the cheaper one is not A4: <code>flex-auth</code>'s registry already carries action definitions per system and could serve them read-only. The vocabulary argument is withdrawn.</p>
<p><strong>Internal service-to-service calls are in scope for this axis.</strong> "Skipping tenant validation for internal services" is a named anti-pattern and our estate is mostly internal calls.</p>
<p><em>Correction from flex-auth's review:</em> earlier drafts asserted that <code>flex-auth</code> calls <code>tenant-engine</code> synchronously on the authorization path. <strong>That is not true.</strong> The adapter is built and complete and has no non-test caller, so the IAM Profile's live re-query exists and is unwired — which is also why <code>flex-auth</code> cannot reach I3. Built-and-unwired is the worst of the three states because it reads as capability.</p>
<p>The requirement, narrowed on their proposal because the original was too strong to be met and would have made <code>tenant-engine</code> a hard availability dependency of every decision in the estate:</p>
<div class="rule-quote"><p>Tenant context MUST be carried on every internal hop and MUST NOT be re-derived from a service identity. It MUST be revalidated against <code>tenant-engine</code> at least once per request chain — at the service that holds or mutates the tenant's data, or before a privileged, destructive, credential-vending or <code>aal2</code>-class decision, whichever comes first. A hop that neither holds tenant data nor makes such a decision may carry the context without revalidating it.</p></div>
<p><strong>And carrying tenant context is worthless without an authenticated hop to carry it over.</strong> <code>flex-auth</code> found this in itself: it carries tenant context faithfully and cannot distinguish "user-engine asking on behalf of tenant X" from "any pod asking on behalf of tenant X".</p>
<h3>4.3 Enforcement (E)</h3>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Enforcement<span>axis E</span></div><div class="rungs"><div class="rung r0"><span class="code">E0</span><span class="txt">None. Data not tenant-keyed; separation incidental or absent.</span></div><div class="rung r1"><span class="code">E1</span><span class="txt">Data tenant-keyed, filtering applied per query at call sites.</span></div><div class="rung r2"><span class="code">E2</span><span class="txt">Filtering centralised at a single service-side choke point binding authenticated identity to permitted tenants.</span></div><div class="rung r3"><span class="code">E3</span><span class="txt">E2 <strong>plus</strong> platform-assisted filtering: row-level security keyed on a tenant GUC set transaction-locally, or an equivalent enforced data-access layer.</span></div><div class="rung r4"><span class="code">E4</span><span class="txt">Structural: the credential a workload holds cannot address another tenant's data at all. Requires per-tenant credentials and per-tenant substrate.</span></div></div></div>
</div></div>
<p><strong>Correction from draft-2.</strong> Draft-2 described E3 as something "the application cannot trivially route around". That is false and it was this document overclaiming in exactly the way §6 prohibits. Any session can re-issue <code>SET</code> on a custom GUC, so an attacker with SQL execution can reset the tenant and read across the boundary. What E3 buys is precise, and the ladder must say so:</p>
<div class="scroll"><table class="tm"><thead><tr><th>Threat</th><th>E1</th><th>E2</th><th>E3</th><th>E4</th></tr></thead><tbody><tr><td>A developer forgets a tenant predicate</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr><tr><td>A new code path bypasses the choke point</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td><td class="yes">✓</td></tr><tr><td>SQL injection reaching the connection</td><td class="no">✗</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td></tr><tr><td>The application process is compromised</td><td class="no">✗</td><td class="no">✗</td><td class="no">✗</td><td class="yes">✓</td></tr></tbody></table></div>
<p>E3 is a strong control against <strong>accident</strong> — the common case, and the one that causes real breaches — and no control at all against <strong>compromise</strong>. Only E4 holds against both, because the credential itself cannot address another tenant's data.</p>
<p><strong>Correction: E3 layers on E2, it does not replace it.</strong> External practice treats application-layer and database-layer filtering as complementary. A service that dropped its choke point on reaching E3 would be <em>worse</em> off, since E3 fails open under injection. Claiming E3 therefore requires the E2 evidence artifact as well.</p>
<p><strong>Correction: the GUC is set transaction-locally.</strong> Draft-2 said "at pool checkout", which is session scope and the wrong instrument. Under a pooler in statement mode, <code>SET</code> leaks between clients and returns other tenants' rows — a failure that appears only under production concurrency and produces no error. Use <code>SET LOCAL</code> inside an explicit transaction.</p>
<p><strong>Platform enforcement is a platform obligation.</strong> Reaching E3 requires the storage platform to <em>offer</em> the mechanism: provisioned policies, a documented GUC contract, and a probe. Where a consumer wants E3 and the platform has not supplied it, the gap is the platform's. §19.6 asks <code>rapp-postgres</code> to define that contract, which must carry <code>FORCE ROW LEVEL SECURITY</code> on every tenant table (without it the table owner bypasses policies silently, and ADR-0001 already established that our migration role owns the tables it creates), no <code>BYPASSRLS</code> on leased roles, <code>SECURITY INVOKER</code> for ordinary logic, and an <code>EXPLAIN</code> comparison because RLS disables functional indexes built on non-leakproof functions.</p>
<p><strong>Not all data is tenant-keyed, and the ladder must not pretend otherwise.</strong> A registry whose rows <em>are</em> the tenants has no per-tenant predicate to scope a policy by; enforcing one would break the service's function rather than secure it. <code>tenant-engine</code>'s <code>tenants</code> table is the worked example — <code>key-cape</code> enumerates it at token issuance and <code>flex-auth</code> queries it live, both of which are cross-tenant reads by design.</p>
<p>A service with mixed data shapes declares <strong>E-level plus a registry exception</strong>: the level its tenant-keyed tables hold, and a named list of tables excluded because they are registries rather than tenant data. The exception is part of the claim and is reviewable; an unnamed exception is an overclaim. Without this, mixed-shape services either overclaim or stay at E2 permanently, and <code>tenant-engine</code> declined to claim E3 on precisely that reasoning.</p>
<p><strong>Default expectation</strong> for a new platform service: E2 at first serve, E3 recorded as target. Services whose cross-tenant exposure would be a reportable breach SHOULD target E3 or above.</p>
<h3>4.4 Placement (P)</h3>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Placement<span>axis P</span></div><div class="rungs"><div class="rung r0"><span class="code">P0</span><span class="txt">Shares a database with another consumer.</span></div><div class="rung r1"><span class="code">P1</span><span class="txt">Database per consumer, shared cluster.</span></div><div class="rung r2"><span class="code">P2</span><span class="txt">Dedicated cluster per consumer.</span></div><div class="rung r3"><span class="code">P3</span><span class="txt">Dedicated cluster per tenant.</span></div><div class="rung r4"><span class="code">P4</span><span class="txt">P3 plus separate region or jurisdiction.</span></div></div></div>
</div></div>
<p>Enforcement and placement are independent axes. Plotted together, with where each service actually sits — parenthesised entries are targets or defaults rather than current positions, and <code>—</code> marks a cell the coupling in §3.2 makes unreachable:</p>
<div class="matrix-shell"><div class="ylab">Enforcement →</div><div class="mgrid"><div class="rlab">E4</div><div class="mcell void"></div><div class="mcell void"></div><div class="mcell void"></div><div class="mcell tint4"><span class="pin ghost">business app</span></div><div class="mcell tint4"></div><div class="rlab">E3</div><div class="mcell tint3"></div><div class="mcell tint3"><span class="pin ghost">target</span></div><div class="mcell tint3"></div><div class="mcell tint3"></div><div class="mcell tint3"></div><div class="rlab">E2</div><div class="mcell tint2"><span class="pin ghost">tenant-engine</span></div><div class="mcell tint2"><span class="pin">audit-core</span></div><div class="mcell tint2"></div><div class="mcell tint2"></div><div class="mcell tint2"></div><div class="rlab">E1</div><div class="mcell tint1"><span class="pin ghost">absorbed repo</span></div><div class="mcell tint1"></div><div class="mcell tint1"></div><div class="mcell tint1"></div><div class="mcell tint1"></div><div class="rlab">E0</div><div class="mcell"></div><div class="mcell"></div><div class="mcell"></div><div class="mcell"></div><div class="mcell"></div><div class="rlab"></div><div class="clab">P0</div><div class="clab">P1</div><div class="clab">P2</div><div class="clab">P3</div><div class="clab">P4</div></div></div><div class="mnote"><span class="k"><span class="sw"></span>Where a service sits today</span><span class="k"><span class="sw g"></span>Target or default</span><span class="k"><span class="sw v"></span>Unreachable at this placement</span></div>
<p><strong>P0 → P1 → P2 is movement along the horizontal axis only.</strong> Those steps buy consumer isolation, capacity predictability, independent retention and a smaller operational blast radius. They do not raise the tenant boundary by one step. Only P3 makes E4 reachable. This is the most misusable fact in the framework and §11 governs how it may be described.</p>
<p><span class="dec">Decision 4.4.1:</span> P1 is the default for platform services; P3 for client-facing business apps, as already ratified. A service unsure which it is must resolve that first (§19.4).</p>
<p><span class="dec">Decision 4.4.2 — placement scopes to data substrate.</span> Identity-provider placement (realm-per-tenant versus Organizations) is the same silo/pool decision on a different substrate, is live in our estate, and is undecided. Realm-per-tenant carries a stated ceiling around 5–20 tenants, far below our target. Recorded here as a parallel question (§19.7), not folded into P.</p>
<h3>4.5 Retention and erasure (R)</h3>
<p>New in draft-3. Implemented abstractly by the storage platform for any dataset; policy is built on top of that interface by the consumer or its governance layer. Reference implementation: <code>rapp-postgres</code> ADR-0002.</p>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Retention<span>axis R</span></div><div class="rungs"><div class="rung r0"><span class="code">R0</span><span class="txt">No retention or deletion position. Data kept indefinitely by default; no deletion path exists.</span></div><div class="rung r1"><span class="code">R1</span><span class="txt">Platform default retention applies (N=30 days). The consumer has declared no requirement.</span></div><div class="rung r2"><span class="code">R2</span><span class="txt">Retention declared as N days per dataset; the <strong>erasure horizon</strong> is published, and the consumer makes no promise shorter than it.</span></div><div class="rung r3"><span class="code">R3</span><span class="txt">Policy-driven deletion: the consumer or its governance layer declares what is due, the platform sweeps whole datasets on that instruction and evidences each run.</span></div><div class="rung r4"><span class="code">R4</span><span class="txt">Verified erasure: data proven unrecoverable across live storage, backups and derived copies, by one of the two routes below.</span></div></div></div>
</div></div>
<p><strong>R4 has two routes and a service MUST name which one it uses.</strong></p>
<div class="scroll"><table><thead><tr><th>Route</th><th>Mechanism</th><th>Cost</th></tr></thead><tbody><tr><td><strong>Horizon-elapsed</strong></td><td>Wait out the published erasure horizon; the data ages out of every retained copy.</td><td>Available to everyone, proves little, and the wait is set by a co-resident's retention requirement rather than your own.</td></tr><tr><td><strong>Key-destroyed</strong></td><td>Encrypt per entity, then destroy the key. Retained copies survive but are unreadable.</td><td>Requires per-entity keys, strong encryption, and an auditable destruction record. Immediate.</td></tr></tbody></table></div>
<p><span class="dec">Decision 4.5.3 — key destruction is not sufficient on its own.</span> The key-destroyed route requires that <strong>no retained commitment reveals the erased content</strong>. Found by <code>audit-core</code>, and it is a general defect rather than a fact about them:</p>
<ul><li>A SHA-256 over a canonical record whose fields are low-entropy — event type, actor, tenant, subject, timestamp — is a <strong>confirmation oracle</strong>. Anyone holding the hash can guess the payload, hash the guess, and confirm a match. Destroying the key does not make the content unrecoverable while that hash survives.</li><li>Shreddability is <strong>not retrofittable</strong> onto an integrity chain that commits to cleartext. It has to be built as encrypt-then-hash at accept time, with the chain committing to ciphertext. Retrofitting means rewriting the chain — the exact thing a tamper-evident log exists to make detectable.</li></ul>
<p>So a service claiming R4 by key destruction must show that its retained commitments — hashes, chains, indexes, search keys — do not reveal what was erased. The remedies are an HMAC under a per-subject key that dies with the key, or a per-record salt destroyed alongside it. <strong><code>audit-core</code> cannot reach R4 under its current design and targets R2; a fleet R4 target must exempt it explicitly.</strong></p>
<p><strong>Regulatory standing of the key-destroyed route, stated carefully because overclaiming here is worse than anywhere else in this framework.</strong> Data protection authorities have accepted key destruction as erasure where physical deletion would be manifestly disproportionate, and the practice is recognised under conditions — strong encryption, irreversible destruction, and an auditable record of it. <strong>The EDPB has not formally endorsed it as Article 17 erasure.</strong> A service reaching R4 by key destruction is making a defensible claim, not a settled one, and must say so rather than reporting a clean "deleted".</p>
<p>Three further properties.</p>
<p><strong>The erasure horizon is the interval between deleting data and it ceasing to be recoverable from anything the platform holds.</strong> Deleting a row does not remove it from yesterday's backup. With an N-day window, deleted data remains recoverable for N days. That is the difference between "deleted" and "erased" and the estate had never written it down.</p>
<p><strong>On shared substrate, retention is not per-consumer.</strong> Physical backup is instance-wide — one WAL stream, one window — so the instance retention is <em>derived</em> as the maximum across co-resident consumers, and every consumer's horizon is that maximum. A consumer declaring 7 days beside one declaring 90 gets 90. This is the retention analogue of ADR-0001's blast-radius disclosure: state the coupling rather than imply an isolation that is not there.</p>
<p><strong>Retention is therefore a placement trigger.</strong> A consumer needing a horizon shorter than the instance floor cannot have one at P1. It moves to P2 for a reason with nothing to do with performance — which is exactly why it needs recording, since nobody looks for a retention argument when reviewing placement.</p>
<p><span class="dec">Decision 4.5.4 — a retention promise binds both R and P.</span> A tier making a retention claim records an R minimum and a maximum erasure horizon in days. It also requires P2 or above <strong>unless</strong> its provider contract guarantees that the shared-substrate horizon stays within that maximum and rejects or notifies before a co-resident change would extend it. A bare <code>R2</code> minimum is insufficient: at P1 another consumer can change the promise without changing the tier or its holder.</p>
<p>Deletion splits mechanism from policy. The platform deletes whole <strong>datasets</strong> on instruction and records an opaque policy reference it never interprets, so every deletion traces to what authorised it. Rows are not a dataset: row expiry is the consumer's own DML under its migration lease. Dropping a consumer's whole database is an operator-gated offboarding step, never a scheduled one.</p>
<h3>4.6 Availability (V)</h3>
<p>New in draft-8. <code>adaptive-pricing</code> found that §11 required availability claims to map to a minimum level while the framework supplied no availability vocabulary. Placement is not a substitute: a dedicated cluster can still be a single instance on a single node.</p>
<div class="breakout"><div class="ladders">
<div class="ladder"><div class="pname">Availability<span>axis V</span></div><div class="rungs"><div class="rung r0"><span class="code">V0</span><span class="txt">No availability or recovery position. Recovery is untested or depends on improvisation.</span></div><div class="rung r1"><span class="code">V1</span><span class="txt">Restart or recreate recovery in one failure domain is documented and exercised. Interruption is expected; this is recovery, not failover.</span></div><div class="rung r2"><span class="code">V2</span><span class="txt">Redundant instances provide automated service failover, with measured RTO/RPO; a shared failure domain or critical dependency may remain.</span></div><div class="rung r3"><span class="code">V3</span><span class="txt">The complete critical path survives loss of one declared failure domain, with measured RTO/RPO from an exercise.</span></div><div class="rung r4"><span class="code">V4</span><span class="txt">The complete critical path survives regional loss through tested multi-region failover, with measured RTO/RPO.</span></div></div></div>
</div></div>
<p><span class="dec">Decision 4.6.1 — V is end-to-end.</span> A service declares the minimum across the components and synchronous providers required to serve the operation. An application with three replicas over a V1 database is V1. A status page or replica count is not evidence of a higher level.</p>
<p><span class="dec">Decision 4.6.2 — availability claims name the operation.</span> A read-only degraded mode and a mutation path may have different V levels. Decision 5.2 applies: declare the paths and quote the minimum unless the customer-facing claim explicitly and unambiguously names the narrower operation.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>The posture vector</h2>
<p>A service states one level per axis, plus a target, review dates, evidence and any exceptions. <code>current</code> is the highest <strong>evidenced</strong> level; a control present in code but still awaiting the evidence required by §13 goes in <code>implemented</code>, not in <code>current</code>:</p>
<pre>schema_version: &quot;0.1&quot;
framework: netkingdom-tenancy-posture
service: example-service
role: tenant-data-service
tenancy:
current: { I: 2, A: 3, E: 2, P: 1, R: 1, V: 1 }
implemented: { E: 3 }
target: { I: 2, A: 3, E: 3, P: 1, R: 2, V: 2 }
reviewed: &quot;2026-08-17&quot;
review_due: &quot;2027-02-17&quot;
service_class: interactive
gap:
E: &quot;RLS is implemented; the §13 E3 probe is still absent.&quot;
R: &quot;Retention declared; erasure horizon not yet published to consumers.&quot;
V: &quot;Automated failover is not implemented or exercised.&quot;
evidence:
A3: &quot;docs/evidence/authorization-denial.md&quot;
E2: &quot;docs/evidence/cross-tenant-review.md&quot;
P1: &quot;rapp-postgres/docs/evidence/isolation-2026-08-10.md&quot;</pre>
<p><strong>Placement exceptions.</strong> Draft-2 assigned one P level per service, which cannot express the vertically partitioned model — most tenants pooled, some dedicated — that §11's isolation tiers require. A tier requiring <code>P2</code> bought by three tenants would put the service at two levels at once, forcing an over- or under-claim. Placement is therefore declared as a default plus exceptions:</p>
<pre> placement_exceptions:
- tenants: [&quot;tenant:enterprise:*&quot;]
P: 3
reason: &quot;isolation tier; see adaptive-pricing tier definition&quot;</pre>
<p>A service with exceptions must be able to say which tenants are on which substrate. That mapping is a first-class artifact, not archaeology.</p>
<p><span class="dec">Decision 5.5 — a provider declares what it makes reachable, not where it sits.</span> The six ladders describe a <em>consumer</em> of infrastructure. They describe a <em>provider</em> of it badly, and <code>railiance-platform</code>'s review demonstrated how badly: <code>apps-pg</code> is <code>I0 A0 E0</code> because a database has no tenant concept, carries no tenant claim and applies no tenant predicate. Those zeros are <strong>structural, not weak</strong> — the cluster is exactly as strong as its consumers make it.</p>
<p>The sharp case is OpenBao at <code>E0</code>. Literally correct, and actively misleading: the mechanism in place is credential-scoped structural separation — <code>E4</code> machinery — pointed at a <em>consumer</em> boundary rather than a tenant one. A reader scanning a column of E values would rank it below a service doing per-query filtering in application code, inverting the real security position.</p>
<p>So a platform service additionally declares, per axis, <strong>the level available now, the maximum it can make reachable, and what a consumer must do to reach it</strong>. For <code>apps-pg</code>: E4 unreachable (shared credential per consumer, no per-tenant credential), E3 conditional on the GUC contract, R2 blocked on a backup target, V1 at most on the single-node rail. That is the sentence a consumer actually needs, and no arrangement of the consumer ladders produces it.</p>
<p>A provider's own <code>P</code> is <code>n/a</code>, not a number. <code>apps-pg</code> <em>provides</em> <code>P1</code>; it is not <em>at</em> <code>P1</code>, and writing <code>P: 1</code> there would later read as an isolation claim.</p>
<p><span class="dec">Decision 5.6 — enforcement stance is not a seventh axis, and <code>zones:</code> is reserved in this file.</span> <code>zone-engine</code> asked whether <em>enforcement stance</em> — whether a given control is enforced, advisory or exempt in a given band of the estate — should fold in here rather than become a second standard. It should not, for a reason that is structural rather than territorial.</p>
<p><strong>Every one of the six ladders is monotone: higher is stronger, and higher is what a service wants.</strong> That assumption is load-bearing throughout. §12's <em>improve</em> step moves a service up. §12's <em>guard</em> checks that none is below what it declared. §6 has to make a special allowance for a level that is <em>permanently</em> low by design, and §12's guard is told not to nag it — the allowance exists because low-is-normal is the exception here.</p>
<p>Enforcement stance is not monotone. The correct stance for a bootstrap lane is deliberately and permanently <em>below</em> the top rung, and the top rung is sometimes the wrong answer outright: <code>ops-warden</code>'s <code>ADR-0006</code> is exactly the finding that a fail-closed authorization gate on the SSH lane the tunnels depend on is not a stronger position, it is an outage. A ladder whose top is sometimes wrong is an enumeration, not a ladder, and putting one inside this vector would break <code>current</code>/<code>target</code>/<code>gap</code>, the guard, and §6 for the six that are.</p>
<p>§8.3 already refused an axis for a weaker reason than this one — that a QoS level would be an unenforced claim. Enforcement stance <em>is</em> enforced. It fails the other half of the same test.</p>
<p>There is a second, sharper reason. §6's conformance rule is <em>accuracy, not altitude</em>, and it works because this framework is <strong>descriptive</strong>: it never blocks anything by itself. Prescription enters only through §11 and Decision 8.2, where a <strong>requirer</strong> — never the declaring repo — sets a minimum level and the two are machine-reconciled. Enforcement stance is prescriptive by nature. Fold it in as an axis and an accurately declared <code>exempt</code> becomes conformant <em>and</em> exempt: a conformance rule that hands out the exemption it exists to audit. The declarer must not be the party that sets the stance.</p>
<p>So the split is the one <code>flex-auth</code> already argued to <code>zone-engine</code>: <strong>membership is data and is declared; stance is a rule and belongs to the control's owner.</strong> Membership is posture-shaped and behaves like a level. Stance behaves like a tier minimum under Decision 8.2 — asserted elsewhere, joined by machine.</p>
<p><strong>What canon rules, and it is binding on the sibling standard:</strong></p>
<ul><li>A security-zone standard is a <strong>separate document</strong> in this family, drafted by <code>zone-engine</code> and published in NetKingdom canon beside this one and the <code>*-engine</code> boundary contracts. It carries over §6 verbatim and §13's evidence discipline.</li><li><strong>Zone membership is declared in <code>tenancy.yaml</code></strong>, under a reserved top-level <code>zones:</code> key, sibling to <code>tenancy:</code> and <code>provider:</code> — <em>not</em> inside <code>tenancy.current</code>. Decision 5.4 makes this file the repo's single posture declaration surface, and a second root file would recreate the divergence §5.4 was written to end. One file, one review cadence, one validator; two standards, because the two have different owners and different conformance semantics.</li><li><code>organization_posture</code> (<code>ops-warden</code> WP-0029) does <strong>not</strong> belong in this file at all, under either key. It is a fleet-wide, time-varying scalar describing the estate, not a property of the declaring service, and a per-repo copy of a global would go stale in as many places as there are repos. It is an <em>input</em> to stance selection and should be read by the zone model, not absorbed into a declaration.</li></ul>
<p><span class="dec">Decision 5.6.1 — the workload remains the sole zone policy subject, and absence resolves to <code>unknown</code>.</span> Here <strong>workload</strong> means an independently governed execution unit that performs application, automation, or operational control-plane work and can be attributed at enforcement time to both a responsible party and an authoritative workload identity. The independently governed executing unit behind operator-driven or automated SSH access, tunnel operation, credential brokering, policy compilation or enforcement, or maintenance is a workload when such a unit exists. The observed access, tunnel, grant, lane, pattern, or action is not itself a workload. A human or agent identity remains caller context; it does not replace the workload whose execution is being governed.</p>
<p>A repository, credential lane, grant template, pattern, or software package is not an alternative <strong>zone</strong> policy subject. A broker runtime is a workload; the grants and lanes it handles retain native resource identity and may explicitly be <code>not-applicable</code> to workload resolution. Every managed running deployable, including operational and tooling runtimes, has one authoritative <code>rapp-*/declarations/rapp.yaml</code> under RMGR-ADR-004. A pre-rapp managed runtime is migration debt and resolves <code>unknown</code>. An independently governed operational execution unit that is not a managed deployable may declare directly in its responsible repo's <code>tenancy.yaml</code>. The declaration surface broadens to cover real workloads; the subject model does not broaden merely to totalize an incomplete registry.</p>
<p>When a workload-applicable subject lacks an authoritative workload identity, when its reference is absent or ambiguous, or when that identity has no authoritative zone membership, the resolved membership MUST be <code>unknown</code>. It MUST NOT be inferred from a repository owner, credential path, lane type, actor class, environment, criticality, reef, organization posture, or a default zone. A control owner MAY define an explicit, reviewable fail-safe treatment for <code>unknown</code> — including denial, escalation, or a build-stage rule — but that treatment is stance, not membership. <code>unknown</code> never silently inherits a permissive zone or exception.</p>
<p><span class="dec">Decision 5.6.2 — zone membership requires an authoritative workload binding in the same declaration entry.</span> A bare service name is a label, not identity evidence. Any single-service declaration carrying <code>zones:</code> MUST also carry <code>workload_identity</code>; in a layer repo using <code>services:</code>, both fields live on the same service entry. Top-level <code>zones:</code> is not valid for a multi-service file, because it would make membership ambiguous.</p>
<p>The binding states:</p>
<ul><li><code>name</code> — the stable workload id, exactly equal to the declaration's <code>service</code>;</li><li><code>kind</code> — application, platform service, automation, operational control plane, or maintenance job;</li><li><code>responsible_repo</code> — the repository accountable for the identity and zone declaration;</li><li>one or more <code>identity_bindings</code>, each naming the identity scheme, authoritative issuer or registry, exact subject, IAM Profile principal type, and optional environment and evidence; and</li><li>for a managed deployable, a <code>declaration_ref</code> to its authoritative rapp declaration. Consuming catalogs reference it with the exact Repo Manager v1 tuple <code>(rapp_id, workload_identity.name)</code> and optional <code>deployable</code>.</li></ul>
<p>An identity binding uses <code>principal_type: service</code> or <code>agent</code>. A human identity may still be required as actor or delegation context, but cannot be the sole workload identity. A managed application, operational runtime, or tooling runtime references its rapp declaration. Only an independently governed operational execution unit that is not a managed deployable declares directly in its responsible repo's <code>tenancy.yaml</code>; native actions and resources do not acquire a fictional workload or rapp merely to enter policy.</p>
<p>The stable workload id is the join key. Credential lanes, grants, controls, and compiled policy resources reference that id explicitly; compilers MUST NOT recover it by parsing a credential path or repository name. Multiple runtime principals may bind to one workload when environments or mechanisms differ, but the bindings must be unique and remain owner-reviewed. If no authoritative binding matches the runtime principal, Decision 5.6.1 returns <code>unknown</code>.</p>
<pre>service: ops-bridge-tunnel
role: operational-access-path
workload_identity:
name: ops-bridge-tunnel
kind: operational-control-plane
responsible_repo: ops-bridge
identity_bindings:
- scheme: ssh-certificate
authority: ops-warden
subject: agt-ops-bridge
principal_type: agent
environment: prod
zones:
standard: security-zones_v0.1
membership: z2-continuity
responsible_party: ops-bridge
justification: foundational tunnel path must retain availability under PDP loss
context:
maturity: M2
criticality: high
data_classification: confidential
evidence:
- ref: docs/evidence/ops-bridge-tunnel-zone.md
supports: [M2, continuity-dependency, recovery]
reviewed: &quot;2026-08-22&quot;
review_due: &quot;2026-11-22&quot;</pre>
<p>Worked examples after applying the evidence rule and minimum-across-paths rule consistently:</p>
<div class="scroll"><table><thead><tr><th>Service</th><th>Current</th><th>Notes</th></tr></thead><tbody><tr><td><code>tenant-engine</code></td><td><code>I1 A0 E1 P n/a R0 V0</code></td><td>Acting identity is caller-supplied; unauthorised read paths set the A minimum; E2-shaped child-table controls are not evidenced; SQLite is outside P; no erasure or availability evidence. This corrects draft-7, which quoted A2/E2 despite its own minimum/evidence rules.</td></tr><tr><td><code>audit-core</code></td><td><code>I1 A2 E2 P1 R2 V0</code></td><td>Bounded adversarial run <code>WH-ENG-20260822-AUDIT-E2-03</code> passed all three calibrated cross-tenant probes over ten operations, so E2 is evidenced as of 2026-08-22. This establishes only that the attempted attacks did not work. The 24-hour facility baseline requires review or replacement by <code>2026-08-23T22:10:25Z</code>. Its 30-day retention and erasure horizon remain declared and published.</td></tr><tr><td><code>flex-auth</code></td><td><code>I1 A0 E1 P n/a R n/a V0</code></td><td>Enables A3 for consumers. <code>/v1/check</code> authenticates no caller; E2 is implemented but not evidenced.</td></tr><tr><td><code>platform-pg</code> (provider)</td><td><code>I0 A0 E0 P n/a R2 V1</code></td><td>Provides P1; backup/restore and single-node recovery are evidenced. Provides no tenant boundary by itself.</td></tr><tr><td><code>apps-pg</code> (provider)</td><td><code>I0 A0 E0 P n/a R0 V0</code></td><td>Zeros are structural, except R0/V0 are live gaps: no backup and no recovery evidence.</td></tr><tr><td><code>adaptive-pricing</code> observatory</td><td><code>I0 A0 E0 P n/a R n/a V0</code></td><td>Local, unauthenticated, single-user analysis surface; not a production service.</td></tr><tr><td>A newly absorbed repo</td><td><code>I1 A1 E1 P0 R0 V0</code></td><td>Conformant <strong>if declared</strong>, with a recorded path.</td></tr></tbody></table></div>
<p><span class="dec">Decision 5.1:</span> the posture vector is declared in the repo, not in the hub, consistent with local-files-are-source-of-truth.</p>
<p><span class="dec">Decision 5.2 — declare per path, quote the minimum.</span> A service whose mutations are authorized and whose reads are not is at the reads' level. The quoted number is the minimum across paths; the per-path detail is declared beside it.</p>
<p>Draft-6 required only the minimum, on <code>tenant-engine</code>'s review. <code>audit-core</code> then showed why that is insufficient on its own: a bare minimum destroys signal, because <code>E3</code>-write/<code>E1</code>-read declares identically to <code>E1</code>/<code>E1</code>. Bare per-path invites "our write path is E3", which is the sentence §6 exists to stop. Both, related explicitly, is the rule.</p>
<p>Two services found this shape in themselves within a day of each other — <code>tenant-engine</code> (writes authorized, three read routes not) and <code>audit-core</code> (write path tenant-filtered, read path not filtered at all). Most services enforce harder on write than read, so this is the common case, not the corner.</p>
<p><span class="dec">Decision 5.3 — <code>n/a</code> is a level, and it is conformant.</span> <code>P0</code> presupposes a shared database and <code>R0</code> presupposes retained data. A service holding nothing at rest — <code>flex-auth</code> runs with its registry and policy baked read-only into the image and no decision log persisted — is neither. A datastore outside a ladder's substrate vocabulary, such as <code>tenant-engine</code>'s current SQLite PVC, also uses <code>n/a</code> rather than inventing a level. Without an admissible <code>n/a</code>, a missing rung <strong>forces</strong> the fabrication §6 prohibits, which is precisely what draft-1 was rejected for. <code>n/a</code> is declared with a stated reason.</p>
<p><span class="dec">Decision 5.4 — the vector lives at <code>tenancy.yaml</code> in the repo root.</span> Draft-6 said "in the repo" and not where or in what shape, which left §12's guard needing per-repo archaeology. <code>flex-auth</code> adopted <code>tenancy.yaml</code> speculatively; adopted here as the convention. A repo representing one service uses the single-service form above. A layer repo uses the schema's <code>services</code> list in the same root file — one vector per service, never an average. The normative schema is <code>canon/schemas/tenancy-posture_v0.1.schema.json</code>; prose documents may explain a declaration but do not replace it. The schema carries <code>current</code>, <code>implemented</code>, <code>target</code>, <code>reviewed</code>, <code>review_due</code>, <code>gap</code>, <code>placement_exceptions</code>, <code>service_class</code> (§8.3), per-path detail (§5.2), and provider reachability (§5.5), plus the workload identity prerequisite for zone membership (§5.6.2). It also permits <code>responsible_repo</code> for authoritative posture routing and <code>evidence_freshness</code> for machine-readable evidence observation, expiry, scope, owner, and remediation metadata. Their absence remains valid declaration syntax; feedback resolution must report <code>unknown</code>, never infer them from a directory, service name, or previous owner. From the <code>net-kingdom</code> repo, owners validate one or more declarations with <code>uv run tools/tenancy-posture/validate.py &lt;path&gt;...</code>; the validator applies the JSON Schema and the evidence, date, implemented/current and provider-range rules that JSON Schema alone cannot express.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Conformance is accuracy, not altitude</h2>
<div class="rule-quote"><p><strong>A service is conformant when its declared posture is accurate, its target is recorded, and it does not claim a level it cannot evidence. It is non-conformant when it overclaims — at any altitude.</strong></p></div>
<ul><li>Declaring <code>E0</code> is conformant. Concealing <code>E0</code> is not.</li><li>A repo may be absorbed at any posture. It may not be absorbed silently.</li><li>No service is blocked from the estate for being low on a ladder. Services MAY be blocked from <em>specific work</em> — serving a tenant grouping, holding a data class, carrying a plan tier — by requirements expressed as minimum levels.</li><li>Downgrading is permitted and must be declared. A regression found by guarding is a defect; a regression declared in advance is a decision.</li><li><strong>A low level may be permanent by design, and the declaration must be able to say so.</strong> <code>flex-auth</code> is <code>I1</code> and always will be: a decision point evaluates the claims it is handed, and verifying its own inputs would make it the identity provider its scope refuses to be. A <code>target</code> equal to <code>current</code> with a reason is a settled position, not a stalled trajectory, and §12's guard must not nag it as though it were one.</li></ul>
<p><span class="dec">Decision 6.1 — downgrades propagate.</span> Before a planned downgrade of a current level or a provider's available level, the declaring repo MUST resolve the tier definitions and consumers that reference it. A downgrade below a recorded minimum blocks the change until the claim is changed, the workload is moved, or the affected owner explicitly accepts the gap. An unplanned regression is an incident and triggers the same notifications. Updating <code>tenancy.yaml</code> without notifying dependants is declaration drift, not a completed downgrade.</p>
<p>Without the axis separation, "not rigorous about tenant separation" is one verdict a repo passes or fails. With it, the same repo is <code>I1 A1 E1 P0 R0 V0</code> with a path — a plan, not an indictment.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Portability across placement levels</h2>
<p>Movement between P levels must be operational, not a rebuild:</p>
<ul><li>Connect by injected credential only — no cluster, host, namespace or database name in source.</li><li>Own a whole database, never tables inside someone else's.</li><li>Idempotent schema creation.</li><li>No cross-database joins or co-location assumptions.</li></ul>
<p><span class="dec">Decision 7.1:</span> mandatory at P1 and above. At P3, SHOULD rather than MUST — a per-client instance that never moves is not misconformant for naming its own database.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Placement triggers</h2>
<p>Recorded at provisioning time: noisy neighbour on a latency-critical path; a compliance or residency requirement; a plan tier requiring a higher minimum; an erasure horizon that no longer fits (§4.5); connection or memory ceiling reached.</p>
<p><span class="dec">Decision 8.1:</span> triggers MUST be <em>monitored</em>, not merely recorded. A trigger in a YAML comment nobody re-reads is documentation, not control.</p>
<p><span class="dec">Decision 8.2 — split authority, machine-reconciled.</span> <code>railiance-platform</code> owns the placement rule; the package repo owns the substrate numbers and enforcement; the consuming repo owns its workload requirements; <code>adaptive-pricing</code> owns any tier minimum. <code>adaptive-pricing</code> declined a standing co-signature and the framework accepts the replacement: typed tier minima are joined to consumer and provider declarations at tier definition and whenever one changes. A machine-checkable constraint must not depend on somebody remembering to collect a signature.</p>
<p><span class="dec">Decision 8.2.1 — trigger monitoring has an owner.</span> The provider monitors capacity ceilings and co-residency; the consumer monitors latency, compliance and erasure requirements; <code>adaptive-pricing</code> monitors tier-definition changes. The placement owner reconciles those signals. A trigger marked <code>unmonitored</code> is an explicit gap and cannot support a customer assurance claim.</p>
<h3>8.3 Service class — a placement input, never a priority</h3>
<p>A latency-critical consumer and a batch consumer can share an instance today with nothing distinguishing them. <code>tenant-engine</code> sits on <code>flex-auth</code>'s synchronous authorization path and chose a 5s statement timeout for that reason; <code>audit-core</code>, co-resident, is not latency-critical. Nothing prioritises between them.</p>
<p><strong>The framework does not add a QoS axis, because the platform cannot enforce one.</strong> Community PostgreSQL has no resource governor: no per-role CPU or I/O priority, no resource queues, no workload classes. Those exist in EDB's enterprise variant, in Greenplum, and in SQL Server — not in what we run. A declared priority level would therefore be an unenforced claim sitting in a declaration, which is precisely what retiring <code>tenantIsolation</code> was about. An axis implies graduation and enforcement; this has neither.</p>
<p><span class="dec">Decision 8.3.1 — co-residents are equal.</span> On shared substrate no consumer's query yields to another's. A consumer whose latency requirement cannot survive an unprioritised neighbour must escalate to <code>P2</code>. That is the honest mechanism and it is the only one we have.</p>
<p><span class="dec">Decision 8.3.2 — service class is declared anyway</span>, as a category rather than a level: <code>latency-critical</code>, <code>interactive</code>, or <code>batch</code>. It buys three things, none of which is priority:</p>
<ul><li><strong>A placement input.</strong> Mixing <code>latency-critical</code> with <code>batch</code> on one instance is a recognised mismatch. It may still be the right call — it is right today — but it should be a decision, not an accident of who was provisioned when.</li><li><strong>A trigger.</strong> A <code>latency-critical</code> consumer acquiring a <code>batch</code> co-resident is a recorded placement trigger under §8, on the same footing as noisy neighbour.</li><li><strong>An acceptance criterion for evidence.</strong> The noisy-neighbour artifact in §13 asks whether measured degradation is <em>acceptable</em>; without a declared class that word has no referent. Degradation tolerable for <code>batch</code> may be an outage for <code>latency-critical</code>.</li></ul>
<p><span class="dec">Decision 8.3.3 — class mixture must be visible.</span> The platform reports which classes are co-resident. An unenforceable risk that nobody can see is strictly worse than one that is stated.</p>
<h3>8.4 Substrate location is not evidence — and reefs are not reconciled with <code>P</code> or <code>V</code></h3>
<p><span class="dec">Decision 8.4.1 — location is not evidence of any property of the workload on it.</span> Three repos have now written this rule locally in three vocabularies: <code>railiance-master</code>'s <em>topology is not readiness</em>, <code>zone-engine</code>'s <em>placement is not posture</em>, and §3.1 here, which requires every use of "isolation" to name its axis. They are one rule. Stated once: <strong>the substrate a workload sits on is never, by itself, evidence for a level on any ladder in this framework.</strong> Binding to a reef, being on a dedicated instance, or naming a rail proves placement and nothing else. Other repos should cite this rather than restate it.</p>
<p><span class="dec">Decision 8.4.2 — the reef taxonomy and this framework are not reconciled, and that is this document's defect.</span> <code>zone-engine</code> asked whether canon should reconcile reefs with the posture axes, on the assumption that this was a scope question for the zone model. It is not: the unreconciled pair is not zone ↔ reef, it is <strong>reef ↔ <code>P</code> and <code>V</code></strong>, and it belongs to canon.</p>
<p><code>repo-manager</code> owns substrate placement (<code>reef-railiance</code>, <code>reef-storage</code>) with an explicit residual-risk acceptance attached to a binding. §7 and §8 of this document presuppose that placement is fully described by the <code>P</code> ladder. It is not. <code>P</code> grades <strong>tenant data isolation within a datastore</strong>; a reef is a named <strong>compute substrate carrying an accepted residual risk</strong>. The <code>P</code> ladder has no rung meaning "single node, shared control plane, risk accepted", and inventing one would be the fabrication §6 prohibits.</p>
<p>A reef binding therefore satisfies none of the <code>P</code> couplings in Decision 3.2 by itself. It records the compute substrate and its accepted residual risk; it does not establish a database-per-consumer or database-per-tenant boundary, a per-tenant credential or encryption boundary, or an erasure horizon. Those remain properties of the workload and data provider declarations. The binding does participate in <code>V</code>, because availability composes across the complete critical path and the substrate can impose a ceiling.</p>
<p>The live consequence is on <code>V</code>, not <code>P</code>. §4.6 already warns that "a dedicated cluster can still be a single instance on a single node", and Decision 4.6.1 makes <code>V</code> the minimum across the synchronous path. <code>reef-railiance</code> is single-node with a shared control plane, which <strong>caps <code>V</code> for every workload bound to it</strong> regardless of that workload's own replica count — which Decision 4.6.1 already says is not evidence. Nothing today joins the reef's facts to a consumer's <code>V</code> declaration, so a rapp can declare <code>V2</code> accurately by its own reading and be wrong by this document's own composition rule.</p>
<p>This is <code>railiance-platform</code>'s provider-declaration finding (Decision 5.5) generalised one layer down. A reef is a <strong>provider</strong> and has nowhere to state what it makes reachable. Tracked as <code>NK-WP-0027</code>; the fix is canon's, and the zone model is not blocked on it.</p>
<p>The known escalation short of P2 is gateway-level prioritisation — ordering submissions in a connection proxy by the requesting tenant's current consumption. It is real, it is where the industry puts this when it must, and it is new infrastructure we do not run. Recorded as the option, not adopted.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Credentials as a tenancy control</h2>
<p>Short-lived leased credentials re-read at connection checkout, with overlap-first rotation, bound the residual risk at every E level below E4: a leaked credential expires rather than persisting. Stronger than the industry norm of a long-lived per-service secret.</p>
<p><span class="dec">Decision 9.1:</span> static long-lived database credentials are not a sanctioned path for any service above E0.</p>
<p><span class="dec">Decision 9.2 — the rule extends to consumer-facing credentials.</span> Draft-6 named database access only. <code>audit-core</code> pointed out that its <em>ingest</em> credentials are static long-lived bearer tokens, rotated by publishing a second alongside the first — and that the argument applies with <strong>more</strong> force to the credential that actually carries the tenant claim than to the one that reaches the database behind it. Read as an accidental omission; it was. Consumer-facing credentials are named in. Where a service cannot yet meet this, it is a stated gap rather than a silent exclusion.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Blast radius must be published</h2>
<p><span class="dec">Decision 10.1:</span> every platform holding consumer data MUST publish, in concrete terms, what a leaked runtime credential can and cannot reach at the levels it operates. <code>rapp-postgres</code> ADR-0001 §5 is the reference. Where the model cannot provide a guarantee, the platform says so and names the escalation.</p>
<p><span class="dec">Decision 10.2 — quotas are disclosed, not discovered.</span> The same obligation extends from what a leaked credential can reach to what the platform will refuse to do for you. Every consumer MUST be told, at provisioning, the throttles and quotas enforced against it — connection limits, statement timeouts, idle-transaction timeouts — and told again when they change. A consumer learning its statement timeout by hitting it in production is a disclosure failure, not a consumer bug. This is how <code>tenant-engine</code> was provisioned, by good practice rather than by rule; the rule now exists.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Commercial expression</h2>
<ul><li><strong>11.1</strong> Plan tiers are expressed <em>internally</em> as typed assurance requirements. A tier may require <code>E3 P2 R2 V2</code> and a maximum erasure horizon; it need not print those labels anywhere customer-facing.</li><li><strong>11.2</strong> Marketing and product language is free. No requirement to expose level labels or this document. "Dedicated infrastructure", "isolated tenancy", "private instance" all remain available.</li><li><strong>11.3</strong> The constraint is on <strong>evidence, not vocabulary</strong>. A customer-facing isolation, availability or retention claim must map to a minimum level the delivering service actually holds, recorded once when the tier is defined. The review is internal and happens at tier definition — not per campaign.</li><li><strong>11.4</strong> Two hard lines, because these reach contracts and compliance questionnaires:</li><li>A claim that another tenant <strong>cannot</strong> reach the customer's data requires <strong>E4</strong>.</li><li>A claim that deleted data <strong>is gone</strong> requires <strong>R4</strong>, or an erasure horizon disclosed alongside it. Where R4 is reached by key destruction, the claim is defensible but not settled law (§4.5) — it may be made, and it may not be made in language that implies a regulator has blessed it.</li><li>A claim that service survives loss of a zone requires <strong>V3</strong>; regional-loss language requires <strong>V4</strong>. "High availability" without a named failure and measured recovery objective is not an assurance claim this framework can evidence.</li><li><strong>11.5 — sanctioned honest language.</strong> The strong prohibitions above must not leave a commercial writer with only silence:</li><li>E3 may be described as database-backed defence against an omitted tenant filter; it must not be paraphrased as "another tenant cannot reach".</li><li>P2 may be described as a dedicated service database cluster with an independent capacity and restore boundary; it is not tenant-dedicated.</li><li>R2 may state the declared retention and published erasure horizon.</li><li>V1 may state exercised restart recovery in one failure domain and must say that interruption and single-domain loss remain.</li><li><strong>11.6 — authority and reconciliation.</strong> The tier definition is authoritative for the minimum and customer wording. <code>tenancy.yaml</code> is authoritative for the delivering service's current level; provider declarations are authoritative for what infrastructure makes available. None is derived by copying another. Approval joins them and fails closed on a missing, stale or insufficient declaration. A performance-differentiated tier requires P2 or an enforceable resource governor; service class alone grants no priority.</li></ul>
</section>
<section id="s12"><h2><span class="sn">12</span>Methodology — analyze, establish, improve, guard</h2>
<p><strong>Analyze.</strong> Assess a repo against the ladders; produce <code>tenancy.current</code> with reasoning recorded. Applies to new and absorbed services alike.</p>
<p><strong>Establish.</strong> Declare the target and gap. The target is set by data class, tenant groupings served and plan tiers carried — not by ambition.</p>
<p><strong>Improve.</strong> Move one axis at a time. Raising P while leaving E untouched is the characteristic misstep.</p>
<p><strong>Guard.</strong> Verify continuously that the declared posture holds — <strong>against the service's own declaration</strong>, not a universal maximum. Nobody must prove every service is at E4; the check is that none is below what it declared.</p>
<p>Regression found by guarding is a defect; regression declared in advance is a decision. The estate has been bitten twice by silent pin rollbacks producing ordinary-looking 403s and 404s rather than errors. Posture regression looks the same — an RLS context leak returns correct-looking rows for the wrong tenant. Guarding must be designed for invisible failure, not for crashes.</p>
</section>
<section id="s13"><h2><span class="sn">13</span>Evidence per level</h2>
<p><span class="dec">Decision 13.1:</span> a current level is claimed only with its evidence artifact present. This turns §6's accuracy rule from an honour system into a check. <code>implemented</code> records a control observed in code or configuration whose required artifact is still absent; it never satisfies a tier minimum.</p>
<p><span class="dec">Decision 13.1a — the floor needs no artifact, only a reason.</span> Found independently by <code>audit-core</code> and <code>flex-auth</code>: the table below defines artifacts from <code>I2</code>, <code>A2</code>, <code>E1</code>, <code>P1</code>, <code>R2</code> upward and none below, so a literal 13.1 made the lowest rungs unclaimable — including §5's own worked example of a conformant absorbed repo, <code>I1 A1 E1 P0 R0</code>, which could not satisfy it on any axis. A rule that forbids the declaration §6 exists to permit is a defect in the rule.</p>
<p>At <code>I0/I1</code>, <code>A0/A1</code>, <code>E0</code>, <code>P0</code>, <code>R0/R1</code>, <code>V0</code>, or <code>n/a</code>, a declaration requires a <strong>stated reason</strong>, not an artifact. Evidence is what stops you overclaiming, and there is nothing to overclaim at those floors.</p>
<p><span class="dec">Decision 13.4 — an artifact must assert something achievable.</span> Draft-3's noisy-neighbour evidence required proof that a saturating consumer "does not breach" another's allowance. Shared infrastructure cannot provide that; the risk is inherent and cannot be wholly removed. An artifact that can only fail, or that passes by being run gently enough, is an overclaim wearing the costume of evidence. Where a property cannot be guaranteed, the artifact measures and records it instead.</p>
<p><span class="dec">Decision 13.2 — evidence is of two kinds, and conflating them is an overclaim.</span> <em>Mechanical</em> evidence is a structural assertion a machine can make and belongs in CI. <em>Adversarial</em> evidence is semantic, requires setting up separate tenant contexts and comparing responses, and carries a review date rather than a green build. Cross-tenant findings are the category external testing practice identifies as needing human review. <strong>A passing CI run is not E2 evidence.</strong></p>
<p><span class="dec">Decision 13.5 — freshness and ownership are explicit inputs.</span> A declaration may attach <code>evidence_freshness.&lt;level&gt;</code> to an evidence key. An adversarial entry requires <code>observed_at</code>, <code>valid_until</code>, <code>responsible_repo</code>, <code>scope</code>, and <code>remediation</code>; a mechanical entry may omit <code>valid_until</code> when the artifact is continuously re-established by the referenced revision or CI control. The timestamps use RFC 3339 and the responsible repository is the authority for replacement evidence.</p>
<p>The feedback evaluator does not parse prose for dates, infer ownership from a file path, or silently extend a validity window. A current adversarial claim without freshness metadata resolves to <strong>freshness <code>unknown</code></strong>. An expired artifact resolves to <strong>freshness <code>expired</code></strong>. Neither automatically rewrites the declared level: the evaluator emits a deterministic owner-routed remediation proposal so review remains observable and controlled. The proposal contract is <code>posture-feedback_v0.1</code>; it performs no State Hub write or policy mutation.</p>
<div class="scroll"><table><thead><tr><th>Level</th><th>Evidence</th><th>Kind</th></tr></thead><tbody><tr><td><strong>I2</strong></td><td>Identifiers validated against the vocabulary; rejection test for a malformed id; binding shown to come from a verified token</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>I3</strong></td><td>Live re-query demonstrated on an <code>aal2</code>-class path; cached-claim path shown unused there</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>A2</strong></td><td>Choke point identified; test that an unbound request is refused</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>A3</strong></td><td>Live decision with a denial observed at the endpoint, not only at the decision surface</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>A4</strong></td><td>Decision served over the standard interface; a second PDP substituted without PEP change, <strong>with the decision differences between the two recorded</strong> — substitution proves interface portability, not decision equivalence</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>E1</strong></td><td>Every tenant-owned table carries the tenant key</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>E2</strong></td><td>Choke point identified; identity bound to tenant A demonstrably cannot read tenant B</td><td><span class="kind adv">Adversarial, with a review date</span></td></tr><tr><td><strong>E3</strong></td><td><code>FORCE ROW LEVEL SECURITY</code> on every tenant table; no <code>BYPASSRLS</code> on leased roles; probe that a session without the GUC reads nothing; probe that a wrong GUC reads nothing; <code>EXPLAIN</code> comparison</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>E4</strong></td><td>Per-tenant credential demonstrated unable to connect to another tenant's substrate</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>P1–P4</strong></td><td>Provisioning declaration plus the platform's isolation probes</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>Shared P1–P2 capacity assurance</strong></td><td>A recorded baseline of per-consumer resource usage; a run in which one consumer saturates its declared allowance; evidence that the governance controls <strong>bind</strong> (the greedy consumer is held at its limits) and that the degradation co-residents experience is <strong>measured, recorded and judged acceptable against each one's declared service class</strong> (§8.3); the aggregate headroom at time of measurement</td><td><span class="kind adv">Adversarial, load-generated, with a review date</span></td></tr><tr><td><strong>R2</strong></td><td>Declared retention rendered; erasure horizon published and reported in the operator surface</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>R3</strong></td><td>Sweep evidence records: timestamp, dataset, identifiers removed, authorising policy reference</td><td><span class="kind ">Mechanical</span></td></tr><tr><td><strong>R4</strong></td><td>Erasure demonstrated across live data, backups and derived copies within the horizon</td><td><span class="kind adv">Adversarial</span></td></tr><tr><td><strong>V1</strong></td><td>Critical dependencies enumerated; restart/recreate recovery exercised; interruption and measured recovery time recorded</td><td><span class="kind ">Mechanical exercise</span></td></tr><tr><td><strong>V2</strong></td><td>One instance terminated while traffic continues or recovers automatically; measured RTO/RPO and remaining shared failure domains recorded</td><td><span class="kind adv">Adversarial, failure-injected</span></td></tr><tr><td><strong>V3</strong></td><td>Declared failure domain removed in an exercise; complete critical path and degraded modes observed against RTO/RPO</td><td><span class="kind adv">Adversarial, failure-injected</span></td></tr><tr><td><strong>V4</strong></td><td>Region made unavailable in an exercise; traffic and state recover in the alternate region against RTO/RPO</td><td><span class="kind adv">Adversarial, failure-injected</span></td></tr></tbody></table></div>
<p>The P1–P4 artifact proves the declared placement topology. The shared-capacity artifact is additional: it is required before a P1/P2 service can claim that a noisy-neighbour control binds, that the trigger is actively guarded, or that a customer performance assurance survives co-residency. It is not required merely to report the true topology as P1 or P2. No such capacity artifact exists in the estate today, so §11 requires P2 or an enforceable governor for a performance-differentiated tier.</p>
<p><span class="dec">Decision 13.3:</span> the tenant-boundary E2/E3 and noisy-neighbour artifacts do not exist anywhere in the estate today. <code>rapp-postgres</code> runs 19 adversarial probes, all against the <em>consumer</em> boundary, none against the tenant boundary inside a consumer. Externally, what this framework calls a tenant boundary failure is <strong>Broken Object Level Authorization</strong> — OWASP API1, top of the API Security Top 10 since that list launched, and the most commonly exploited API vulnerability in published assessments. We have no coverage for the highest-ranked risk in our class of system. §19.3 records the owner.</p>
</section>
<section id="s14"><h2><span class="sn">14</span>Adoption stance — structure, not tooling</h2>
<p><span class="dec">Decision 14.1:</span> external research is design input. This estate adopts published standards and structural patterns; it does not adopt tooling unless that tooling is an established industry standard with broad application. Everything else is built ground-up, so it can be optimised and refactored as the estate sees fit.</p>
<div class="scroll"><table><thead><tr><th>Class</th><th>Stance</th></tr></thead><tbody><tr><td>Security baselines (OWASP Multi-Tenant Security Cheat Sheet, API Security Top 10)</td><td>Adopt as the external reference our ladders answer to</td></tr><tr><td>Standards bodies (OpenID AuthZEN 1.0)</td><td>Adopt — this is what A4 is</td></tr><tr><td>Reference taxonomies (Azure tenancy models, AWS SaaS Lens, cell architecture)</td><td>Adopt as structure</td></tr><tr><td>Engine behaviour (PostgreSQL RLS mechanics)</td><td>Facts, not tooling</td></tr><tr><td>Third-party analyzers and test frameworks</td><td><strong>Do not adopt.</strong> Take their rule taxonomies as checklists for probes we write ourselves</td></tr></tbody></table></div>
<p>The practical effect is small and good: <code>rapp-postgres</code> already owns a ground-up probe harness — bash and psql, no dependency tree — that found four real defects in its own provisioning SQL. The evidence artifacts in §13 become new probes in a tool we control. One idea worth reimplementing from the external survey is <strong>policy-diff classification</strong>: labelling a change to an enforcement policy as safe or breaking <em>before</em> it lands.</p>
</section>
<section id="s15"><h2><span class="sn">15</span>Alternatives considered</h2>
<p><strong>One fixed model with a single set of characteristics</strong> (draft-1). <em>Rejected:</em> cannot describe a repo that is not there yet, forcing absorbed repos to misrepresent their posture or stay outside. A framework that can only describe its own end state is not a framework.</p>
<p><strong>A maturity model with a single overall level.</strong> <em>Rejected:</em> collapses the axis separation. A service strong on identity and weak on enforcement has a specific, actionable gap; one composite score hides it and invites averaging.</p>
<p><strong>Prohibiting row-level security</strong> (draft-2's inherited position). <em>Rejected in draft-2, refined in draft-3:</em> RLS is a real rung against the common threat. The error was never RLS — it was describing E3 in E4's language.</p>
<p><strong>Schema-per-consumer in one database.</strong> <em>Rejected:</em> <code>pg_catalog</code> is readable per-database, so every co-resident enumerates every other's table and column names regardless of grants. Retained as a describable state, never a target.</p>
<p><strong>Mandating E4 for everyone.</strong> <em>Rejected:</em> the tenant taxonomy includes <code>consumer</code> (private individuals) and <code>family</code>. A cluster per private individual is economically impossible; the taxonomy is itself evidence pooling is required.</p>
<p><strong>Per-consumer physical backup retention.</strong> <em>Rejected:</em> CNPG retention is a property of the instance's WAL archive. There is no mechanism, and claiming it would be a fabricated guarantee. Hence the derived maximum in §4.5.</p>
<p><strong>Platform-scheduled row expiry.</strong> <em>Rejected:</em> requires the platform to hold DML authority over consumer schemas and interpret consumer data semantics, both forbidden by ADR-0001. The consumer's migration lease is the correct instrument.</p>
<p><strong>Leaving each repo to its own model.</strong> <em>Rejected:</em> the status quo, which produced two contradictory ratified defaults and an unowned placement question.</p>
</section>
<section id="s16"><h2><span class="sn">16</span>Held against outside practice</h2>
<p><strong>The graduated reframe is corroborated, not invented here.</strong> Microsoft's tenancy-model guidance states it almost verbatim: <em>"Instead of viewing isolation as a discrete property, consider it a spectrum. You can deploy components of your architecture that are more isolated or less isolated than other components in the same architecture."</em> The same guidance derives our E↔P coupling independently — shared deployment means enforcement lives in application code; dedicated deployment means it is structural.</p>
<p><strong>Stronger than typical.</strong> Most multi-tenancy literature models one boundary, tenant-to-tenant. This estate has <strong>two stacked boundaries</strong>: platform-service to platform-service, and tenant to tenant inside a consumer. Naming them separately and refusing to enforce both with one mechanism is uncommon and correct. Graduated per-axis levels also beat the silo/pool/bridge trichotomy, which is approximately our P axis with the other four missing — which is why it cannot express "pooled infrastructure, structurally enforced boundary".</p>
<p><strong>Weaker than typical.</strong> The pool model's standard mitigation is a <em>verified</em> enforcement layer every service is demonstrably routed through. We have the concept and none of the verification (§13.3).</p>
<p><strong>Adopted without naming it.</strong> Short-lived leased credentials re-read at checkout beat the long-lived-secret norm. §9 promotes it to a tenancy control.</p>
<p><strong>Still unexplored.</strong> Neither P nor R describes a <strong>cell</strong> — a slice of infrastructure with a <em>fixed maximum size</em>, sized so one cell's failure is survivable and cell count scales linearly. <code>platform-pg</code> is, in these terms, an uncapped cell: §17 computes a ceiling and nothing enforces it (§19.8).</p>
<p>Sources: the five research digests in <code>the-custodian/research/2026-08-17-adr008-*</code>, which carry full citations for the claims in this section.</p>
</section>
<section id="s17"><h2><span class="sn">17</span>Scaling demands</h2>
<p>Derived from the live <code>platform-pg</code> specification. Connection arithmetic is exact; the per-backend memory estimate remains unmeasured and is explicitly a gap in <code>rapp-postgres</code> ADR-0004.</p>
<pre>instances: 1 (no HA; single-node rail)
max_connections: 100
memory limit: 1Gi
per consumer: 14 connections (12 runtime + 2 migration)</pre>
<p><strong>The hard connection bound is roughly six declarations; the enforceable operational ceiling is four.</strong> Seven declarations request 98 of 100 connections before CNPG's instance manager, metrics exporter and reserved slots. Every one of them is politely inside its declared 14-connection allowance; the instance still fails. ADR-0004 sets four because memory is expected to bind first and fails by OOM-killing every co-resident rather than refusing one connection.</p>
<p>That distinction matters because our governance addresses the wrong shape. Per-consumer <code>connection_limit</code>, <code>statement_timeout</code> and <code>idle_in_transaction_session_timeout</code> guard well against <strong>one greedy consumer</strong>. They do nothing about <strong>the aggregate of many modest ones</strong>, which is the second and less intuitive noisy-neighbour failure and the one this number describes. Two workload consumers plus the isolation probe occupy three of the four declared slots. The next workload request must trigger measurement and the overflow decision before admission.</p>
<p><strong>Memory likely binds first.</strong> 100 backends against 1Gi is ~10MB per backend. Connection exhaustion errors clearly; memory pressure OOM-kills and degrades every co-resident at once.</p>
<p><strong>E3 and pooling.</strong> <em>Corrected from draft-2, which had this backwards.</em> Transaction-scoped context (<code>SET LOCAL</code> inside an explicit transaction) is what makes E3 <strong>safe</strong> under a pooler. Statement-level pooling is what breaks it, serving other tenants' rows under concurrency with no error. E3 constrains which pooling mode is available, not whether pooling is available.</p>
<p><strong>Retention consumes the volume.</strong> WAL accumulates with the window, and §4.5 makes the window the maximum across consumers. A consumer declaring a long retention extends everyone's horizon <em>and</em> everyone's storage draw against a 20Gi volume.</p>
<p><strong>Restore time couples all consumers.</strong> Physical backup is instance-wide, so a consumer's RTO is a function of <em>total</em> instance size, not its own.</p>
<p><strong><code>platform-pg</code> is V1.</strong> <code>instances: 1</code> on a single-node rail provides exercised restart recovery and no failover. P1 describes its consumer placement and says nothing about this availability fact; the new V axis carries it.</p>
</section>
<section id="s18"><h2><span class="sn">18</span>Consequences</h2>
<ul><li>The estate gains one vocabulary and a way to be honest about partial adoption.</li><li>Absorbed repos get a described state and a path instead of a failing grade.</li><li><code>tenantIsolation</code> in <code>PostgresConsumer</code> is revealed as a mislabelled field.</li><li>The verification problem becomes tractable: guard against declaration.</li><li>Draft-2's RLS prohibition is reversed and its E3 description corrected; <code>rapp-postgres</code> acquires an obligation to define and offer the mechanism.</li><li>Adding a consumer with long retention <strong>silently extends everyone's erasure horizon</strong>. This must reach the consumer review checklist, not only this document.</li><li>A service selling an isolation tier must maintain a tenant→substrate mapping it does not have today.</li><li>Availability becomes an end-to-end, evidenced property rather than an inference from replica count or placement.</li><li>Nothing here changes a running system.</li></ul>
</section>
<section id="s19"><h2><span class="sn">19</span>Review resolutions and residual questions</h2>
<ol><li><strong><code>tenantIsolation</code> field — resolved.</strong> <code>rapp-postgres</code> retired it. A consumer declaration asks for mechanisms; posture lives in the consumer's <code>tenancy.yaml</code>.</li><li><strong>Placement ownership — resolved.</strong> §8.2 records the split. The policy has one owner; typed tier requirements replace the declined commercial co-signature.</li><li><strong>E2, E3 and noisy-neighbour evidence</strong> — <strong>owned as of 2026-08-17</strong> by <code>whitehat-security</code> (WHITEHAT-WP-0001), an independent adversarial evidence facility seeded for this purpose. <code>audit-core</code> and <code>tenant-engine</code> were right to decline it as fleet-scope work; the answer was a home of its own rather than a volunteer.</li></ol>
<p><strong>Owned by NetKingdom</strong> — corrected 2026-08-17; an earlier revision of this section proposed otherwise on independence grounds and was overruled. Offensive security is security work and belongs with the repo that owns security. The facility is framed offensively rather than as a conformance checker: it is pointed at infrastructure we choose, our own estate among them, and conformance testing is one use of a general capability.</p>
<p>The residual tension is recorded rather than resolved: NetKingdom owns this framework <em>and</em> the facility that tests conformance to it, so those findings are NetKingdom assessing NetKingdom. The mitigation is that findings leave for <code>risk-nexus</code>, under <code>the-custodian</code>, rather than being closed in place. Proportionate, not perfect. Revisit if conformance findings start getting quietly closed.</p>
<p>Two consequences land back here. <strong>Cadence is now a security parameter, not a schedule</strong> — for any control whose guarantee is detection rather than prevention, the interval between probe runs <em>is</em> the exposure window, and <code>rapp-postgres</code> ADR-0003 leaves that number to the facility. And <strong>a passing suite is not proof of isolation</strong>; it is proof that the attacks attempted did not work. §13's evidence artifacts should be read with that distinction, because a green run recorded as "E2 verified" would be exactly the overclaim §6 prohibits.</p>
<ol><li><strong>Business app vs platform service — open.</strong> Custodian canon: a classification rule. Candidate: reuse <code>repo-classification-standard_v1.0</code>.</li><li><strong>Tier → minimum level mapping — policy resolved, implementation open.</strong> <code>adaptive-pricing</code> owns typed minima and wording; <code>tenant-engine</code> owns plan assignment by id. Current tiers make no assurance claims.</li><li><strong>The E3 mechanism — resolved.</strong> <code>rapp-postgres</code> ADR-0003 publishes the GUC contract with the <code>FORCE</code>/<code>BYPASSRLS</code>/<code>SECURITY INVOKER</code>/<code>EXPLAIN</code> requirements.</li><li><strong>Identity-provider placement — open.</strong> Owner of <code>key-cape</code>: realm-per-tenant or Organizations? Realm-per-tenant's ~5–20 tenant ceiling is below our target.</li><li><strong>Cell sizing — resolved for <code>platform-pg</code>.</strong> <code>rapp-postgres</code> ADR-0004 sets four consumers and names absent overflow target <code>platform-pg-2</code>; measurement and provisioning remain live gaps.</li><li><strong>Retention floor and ceiling — resolved as policy.</strong> Both exist; requests outside them fail validation and the package repo owns the numbers.</li><li><strong>Engine neutrality — open.</strong> The P ladder rests on a PostgreSQL property. State it engine-specifically and say so, or abstract it and risk a non-Postgres implementation that silently differs?</li><li><strong>Erasure versus audit — framework resolved.</strong> <code>audit-core</code>: crypto-shredding a tenant's audit records destroys the evidence the service exists to hold, and ADR-0001 §2 deliberately built the role model so history could not be rewritten. The usual resolution separates the <em>fact</em> of an event, retained, from its <em>personal payload</em>, encrypted per subject and shreddable. Raised because a naive "R4 everywhere" target would instruct the audit service to destroy its own evidence. <code>audit-core</code> targets R2 and is explicitly not a fleet R4 target. The legal basis for retaining audit facts remains a risk/legal question outside this framework.</li><li><strong>Quality of service</strong> — <strong>resolved 2026-08-17.</strong> Co-residents are equal; a declared <em>service class</em> informs placement but never grants priority. See §8.3. The question asked whether to add a QoS dimension; the answer is no, and the reason is that we could not enforce one.</li></ol>
<p><strong>Tenant grouping ambiguity — resolved outside this framework.</strong> ADR-0013 revision 2 makes the identifier segment immutable onboarding-time history and the <code>tenant-engine</code> record authoritative for current grouping. Consumers do not parse current policy or spend-ceiling inputs from <code>tenant:&lt;grouping&gt;:&lt;name&gt;</code>.</p>
</section>
<section id="s20"><h2><span class="sn">20</span>Ratification path</h2>
<ol><li>Reviewed by <code>tenant-engine</code>, <code>flex-auth</code>, <code>audit-core</code>, <code>rapp-postgres</code>, <code>railiance-platform</code> and <code>adaptive-pricing</code> against §19. <strong>Complete in draft-8.</strong></li><li>Each publishes its own posture vector (§5) as part of review. <strong>The framework is validated by whether it can describe them accurately</strong> — if a repo cannot express itself in these six ladders, the ladders are wrong and this document changes, not the repo. <strong>Complete in draft-8; all six root declarations validate against the canonical schema.</strong></li><li>On acceptance, <strong>supersedes</strong> the routing of <code>rapp-postgres/docs/canon-drafts/shared-platform-relational-storage_v0.1-draft.md</code>, whose §§3–8 are absorbed here. That draft is withdrawn rather than left pending.</li><li>On acceptance, <code>rapp-postgres</code> ADR-0001 through ADR-0004 move to <code>accepted</code> and are annotated as the PostgreSQL implementation of the E, P, R and shared-capacity rules.</li></ol>
</section><footer><span>netkingdom-tenancy-posture · draft-14 · proposed</span><span>net-kingdom · canon/standards/tenancy-posture_v0.1.md · ce198fc2905687ea90a2892346b6860281ac87f8</span></footer></main></div></div></html>

216
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0001.html Normal file
View file

@ -0,0 +1,216 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="35aff380a33f51a512c1e1b42d52d1dc0d95930f">
<meta name="policy-source-digest" content="7df0bb364276e382cbee9383e7e67d399b0ac1b0353246e0ab323e629e732a6d">
<title>ADR-0001 — The routing catalog is a pointer layer, never a second copy</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0001</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0001 — The routing catalog is a pointer layer, never a second copy</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0001-catalog-is-a-pointer-layer.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted. Decided during WARDEN-WP-0010 (access routing charter), enforced in code since WARDEN-WP-0011. Restated here because it binds repos other than ops-warden and had, until now, no address they could cite.</p>
</section>
<section id="context"><h2>Context</h2>
<p><code>registry/routing/catalog.yaml</code> tells a worker which subsystem owns a credential need and where the authoritative procedure lives. The obvious temptation, every time someone uses it, is to add the procedure itself: the reader is already here, the steps are short, and one more copy seems cheaper than a second lookup.</p>
<p>That temptation is the failure mode. A copied procedure is correct on the day it is written and silently wrong afterwards, because the owner changes theirs without knowing ours exists. The estate has already paid for this once, between an ADR and its published page — fixed by generating the page from the markdown rather than maintaining both.</p>
<p>The catalog is consulted precisely when someone is about to touch a credential. Being confidently wrong there is worse than being absent.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>For any subsystem ops-warden does not own, a catalog entry carries identifiers and pointers only</strong> — <code>owner_repo</code>, <code>subsystem</code>, <code>wiki_ref</code>, <code>canon_ref</code>, <code>need_keywords</code>, and the secret-free handoff metadata <code>warden access</code> needs.</p>
<p><strong>Authored procedure is permitted only where <code>warden_executes: true</code>.</strong> A <code>steps:</code> block and a <code>cert_command:</code> may exist on the SSH certificate lane and nowhere else, because that is the one lane ops-warden actually owns. Rotation <code>steps:</code> are the narrow exception and describe what the <em>owner</em> does, recorded because rotation guidance had no other home; they are still pointers in spirit and must not grow into a runnable substitute for the owner's tooling.</p>
<p><strong>No secret material in this file, ever.</strong></p>
<p>This is enforced, not merely documented. <code>tests/test_routing.py</code> fails any non-SSH entry carrying a <code>steps</code> block, and checks that every <code>wiki_ref</code> anchor resolves to a real section. A rule that is only written down is a rule that erodes.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Accepted cost.</strong> Two lookups instead of one. A worker who wants the procedure follows the pointer. We consider a correct second hop cheaper than a stale first one.</p>
<p><strong>Anchors must resolve.</strong> Because the entry is only a pointer, a broken pointer is a total failure rather than a cosmetic one. Hence the anchor test — which has already caught a real break (<code>ADHOC-2026-08-11-T01</code>, a stale <code>rapp-qonto-keycape-client</code> anchor).</p>
<p><strong>Other repos are bound by this.</strong> When another repo asks us to add or rename a lane, we add the pointer and decline to absorb the procedure. That has been exercised: on 2026-08-11 railiance-platform asked ops-warden to rename an active lane, and the answer was to cross-reference the id from their CCR rather than have this repo carry a second identity for the same thing.</p>
<p><strong>It constrains what this repo may usefully become.</strong> ops-warden cannot grow into a documentation site for other people's credential procedures, however often that is asked for. The value of the catalog is that a reader knows it points at truth rather than at a copy of truth.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>registry/routing/catalog.yaml</code> — the file this governs, header comment</li><li><code>wiki/AccessRouting.md</code> — the issue-vs-route role and boundary</li><li><code>ADR-0005</code> — the narrower charter this follows from</li></ul>
</section><footer><span>ops-warden-adr-0001 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0001-catalog-is-a-pointer-layer.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</span></footer></main></div></div></html>

216
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0002.html Normal file
View file

@ -0,0 +1,216 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="35aff380a33f51a512c1e1b42d52d1dc0d95930f">
<meta name="policy-source-digest" content="7dcc31732d774ddf2c98636b69ee12e2d74034836ed0def81b7e06461309b53a">
<title>ADR-0002 — ops-warden is a transparent conduit, never a secret broker</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0002</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0002 — ops-warden is a transparent conduit, never a secret broker</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0002-conduit-not-broker.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted. Decided during WARDEN-WP-0014 (operator access assist), tightened by WARDEN-WP-0026 (disclosure hygiene).</p>
</section>
<section id="context"><h2>Context</h2>
<p><code>warden access</code> is the operator front door for every credential need in the estate. For lanes marked <code>exec_capable</code> it does more than advise: it runs the owner's tool and returns the value. Anything that fetches secrets on request looks like a broker, and the gravity toward becoming one is strong — a broker is more convenient at every individual call site.</p>
<p>The distinction is not stylistic. A broker holds authority; a conduit borrows the caller's. Only one of those creates a new thing worth attacking.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>ops-warden runs the owner's tool with the caller's own identity, and takes no custody of the value.</strong> The caller's credentials do the work. ops-warden holds nothing after the command returns, stores nothing, and caches nothing.</p>
<p><strong>Forbidden: a standing broker.</strong> ops-warden must not hold its own long-lived secret-read credential in order to serve values to callers who could not have fetched them themselves. If the caller lacks authority, the correct outcome is a denial from the owner's system — not a fetch performed on their behalf by a more privileged intermediary.</p>
<p>The test is a question: <em>could the caller have run this themselves?</em> If yes, we are a conduit and may proxy. If no, proxying is privilege laundering and is refused.</p>
<p><strong>Owner-native front doors outrank the proxy.</strong> Where an owner has shipped their own exec surface — <code>secrets-engine exec</code>, the railiance-platform credential broker — we route there and do not proxy. The proxy is a fallback for lanes nobody fronts yet, not a preferred path. This is why <code>whynot-design-npm-publish</code> and <code>ops-warden-warden-sign-token</code> are <code>native</code> rather than <code>interim</code>.</p>
<p><strong>The value must not land somewhere it will be logged.</strong> Sanctioned transports are <code>--out</code> (mode-0600 file), <code>--exec</code> (child process env), and <code>--wrap</code> (a single-use OpenBao wrapping token). Streaming to a non-terminal stdout is refused without an explicit <code>--unsafe-stdout</code>, which exists for interactive humans only.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>ops-warden never becomes a credential store, and gains no value by being compromised beyond the SSH CA it already holds.</strong> This is the whole point. An attacker who owns ops-warden gets the SSH signing lane — serious, bounded, and already the thing this repo is hardened around — not a key to every secret in the estate.</p>
<p><strong>Some requests cannot be served, and that is the correct answer.</strong> When a caller lacks authority, ops-warden routes and explains rather than fetching. This reads as unhelpfulness at the moment it happens; it is the property that makes the front door safe to point every agent at.</p>
<p><strong>Every proxied fetch is auditable and attributable to the caller</strong>, because it ran as them. <code>audit.jsonl</code> records metadata only — never values, guarded in code.</p>
<p><strong>The <code>--unsafe-stdout</code> escape hatch is a known liability.</strong> It exists because humans in terminals legitimately need to see values. It is also exactly the shape of the 2026-07-16 disclosure, where a value reached a captured stdout. <code>ADR-0004</code> constrains it further for agent sessions.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>wiki/OperatorAccessAssist.md#the-conduit-vs-broker-boundary-the-security-model</code></li><li><code>ADR-0004</code> — the agent-session read boundary built on top of this</li><li><code>ADR-0003</code> — why proxied lanes are tracked as interim rather than owned</li></ul>
</section><footer><span>ops-warden-adr-0002 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0002-conduit-not-broker.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</span></footer></main></div></div></html>

218
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0003.html Normal file
View file

@ -0,0 +1,218 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="35aff380a33f51a512c1e1b42d52d1dc0d95930f">
<meta name="policy-source-digest" content="45b47c02afa575fbfe5be980e426c331a1d99bb9cd9c7a8de80bf8e319469f81">
<title>ADR-0003 — Cover gaps, but never silently own them</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0003</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0003 — Cover gaps, but never silently own them</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0003-cover-gaps-never-silently-own-them.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted. Stated as INTENT §9, made structural by WARDEN-WP-0030 (delegation register).</p>
</section>
<section id="context"><h2>Context</h2>
<p>ops-warden owns exactly one lane: SSH certificate issuance. It nonetheless fronts around eleven credential lanes as a caller-identity proxy, because no other component fronts them yet and a worker blocked on a credential is a worker blocked.</p>
<p>Covering a gap is legitimate and this repo intends to keep doing it. The failure is subtler: <strong>a cover that is never recorded as a cover becomes ownership by default.</strong> Nobody decides to permanently own another component's lane. It happens because the interim arrangement worked, nobody wrote down that it was interim, and the intended owner never learned they were expected to build a front door.</p>
<p>By August 2026 the primitive to hand a lane back existed and was proven — <code>exec_owner</code> / <code>exec_command</code>, used by secrets-engine for npm publish and by the railiance-platform credential broker for warden-sign — and was used by 2 of 24 lanes. The other twenty-two had no record of who <em>should</em> own them.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Every catalog entry carries a <code>delegation:</code> block</strong>, with a <code>mode:</code> of:</p>
<div class="scroll"><table><thead><tr><th><code>mode</code></th><th>Meaning</th></tr></thead><tbody><tr><td><code>permanent</code></td><td>Ours forever. SSH certificate issuance, and nothing else</td></tr><tr><td><code>native</code></td><td>The owner has a front door; we route to it and execute nothing</td></tr><tr><td><code>interim</code></td><td>We are covering a gap. Requires <code>intended_owner:</code> and <code>blocked_on:</code></td></tr></tbody></table></div>
<p><strong><code>interim</code> without an <code>intended_owner</code> is not permitted.</strong> If we cannot name who should own it, we have not understood the lane well enough to be fronting it.</p>
<p><strong><code>blocked_on:</code> must name a specific condition, not a mood.</strong> "No front door yet" is not a blocker; "secrets-engine has not confirmed whether <code>exec --catalog</code> generalizes over arbitrary OpenBao lanes (asked 2026-08-11, msg 7d55d332)" is. A blocker with a question and a date can be chased. A blocker without one is an excuse with a timestamp.</p>
<p><strong>The interim set is queryable</strong>: <code>warden route gaps</code> lists it with review dates and staleness. A cover that nobody can enumerate is a cover nobody will retire.</p>
<p><strong>A blocker is a claim about the world at a date, and expires.</strong> <code>reviewed:</code> is bumped only on a real re-check, never inherited. This was learned the hard way: <code>RISK-F-0001</code> invalidated one of our blockers within a day and nothing would have re-checked it.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Retiring a cover is a normal, expected event rather than a renegotiation.</strong> When an owner ships their front door the lane flips <code>interim</code> → <code>native</code>. This has happened twice and both were routine.</p>
<p><strong>Other repos can see what we are holding for them.</strong> The register is why key-cape and user-engine were able to confirm or decline lanes in August 2026 — the question was answerable because it had been written down. One of those answers was "not ours", which is a legitimate and useful outcome.</p>
<p><strong>We accept looking worse than we are.</strong> <code>warden route gaps</code> publishes a list of things this repo is doing that it would rather not be doing. That is the intent: the alternative is a repo that looks clean because nobody counted.</p>
<p><strong>This register is not a risk register.</strong> Interim lanes are tracked work with an owner and a date, not defects. They do not get bulk-filed into <code>risk-nexus</code>, which needs to stay small enough to read. Defects go there; gaps stay here.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>INTENT.md</code> §9 — the principle this formalizes</li><li><code>history/2026-08-11-delegation-surface-assessment.md</code> — the assessment that forced it</li><li><code>.claude/rules/finding-routing.md</code> — the register-versus-findings boundary</li></ul>
</section><footer><span>ops-warden-adr-0003 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0003-cover-gaps-never-silently-own-them.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</span></footer></main></div></div></html>

216
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0004.html Normal file
View file

@ -0,0 +1,216 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="35aff380a33f51a512c1e1b42d52d1dc0d95930f">
<meta name="policy-source-digest" content="5db38dcb754af1ba639f4ceca056df842bc7b91fa48dd8bad21611aee29f682d">
<title>ADR-0004 — High-risk lanes refuse raw value streaming to agent sessions</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0004</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0004 — High-risk lanes refuse raw value streaming to agent sessions</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0004-agent-read-boundary-on-high-risk-lanes.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted. Decided during WARDEN-WP-0026 (credential disclosure hygiene), in response to a real disclosure on 2026-07-16.</p>
</section>
<section id="context"><h2>Context</h2>
<p>On 2026-07-16 a secret value reached a captured stdout. The mechanism was ordinary: <code>bao kv get -field=X</code> in an agent session. Nothing was misconfigured and nobody misused a tool. The value was read correctly, by an authorized caller, using the documented command — and an agent session records its stdout, so the value landed in a transcript that outlives the shell.</p>
<p>This is a structural mismatch, not a mistake to train away. Agent sessions are logged by design; that is what makes them reviewable. A human at a terminal sees a value and it scrolls away. An agent "seeing" a value writes it into a durable context that may be stored, replayed, or sent to an inference provider.</p>
<p>Guidance alone will not fix it. The command is correct, it is in every runbook, and the next agent that needs the value will reach for it.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>When <code>WARDEN_AGENT_ID</code> is set and the catalog lane is <code>risk: high</code>, ops-warden refuses to stream the raw value and exits 7.</strong> The agent is not blocked from doing its work — <code>--out</code>, <code>--exec</code>, <code>--wrap</code> and <code>--fingerprint</code> all remain available. It is blocked from doing its work <em>in a way that writes the secret into a transcript</em>.</p>
<p><strong>The boundary is enforced at the credential store as well as at the CLI.</strong> The OpenBao policy <code>agent-high-risk-boundary</code> denies data-read on those paths for agent tokens, allowing metadata and capabilities only. A control that lives solely in our own CLI is a control that ends the moment someone calls <code>bao</code> directly.</p>
<p><strong>Verification must not require a read.</strong> To check a lane, use <code>bao token capabilities</code> — allow/deny — never a read of the value. This is the specific habit the disclosure taught us to break.</p>
<p><strong>Exposure is reportable without reading.</strong> <code>warden taint &lt;catalog-id&gt;</code> reports KV v2 <code>custom_metadata</code> (<code>exposed_at</code>, <code>exposed_version</code>) and touches no secret data.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>Agents can still do everything they could before, by a different route.</strong> <code>--exec</code> covers nearly every real case: the child process gets the value in its environment, the agent never sees it. The friction is deliberate and small.</p>
<p><strong>Exit 7 is a contract other runtimes depend on.</strong> It is a distinguishable code, not a generic failure, so a caller can tell "refused by boundary" from "lane broken" and retry correctly. Changing it is a breaking change to every agent runtime.</p>
<p><strong><code>risk: high</code> becomes a load-bearing catalog field</strong> rather than documentation. Classifying a lane now changes runtime behaviour, so it must be set deliberately.</p>
<p><strong>We accept that <code>--unsafe-stdout</code> still exists for humans.</strong> The boundary keys on <code>WARDEN_AGENT_ID</code>, so an agent that does not set it is not caught. That is a known limit: this ADR raises the floor for cooperating runtimes and hardens the store behind them; it does not claim to stop a determined caller.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>wiki/playbooks/agent-read-boundary.md</code></li><li><code>wiki/playbooks/exposed-taint.md</code></li><li><code>ADR-0002</code> — the conduit rule this narrows for agent callers</li></ul>
</section><footer><span>ops-warden-adr-0004 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0004-agent-read-boundary-on-high-risk-lanes.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</span></footer></main></div></div></html>

214
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0005.html Normal file
View file

@ -0,0 +1,214 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="35aff380a33f51a512c1e1b42d52d1dc0d95930f">
<meta name="policy-source-digest" content="31eafe4d8d9362a3446739d63c3af83fd9138cfdc6ad120086312a67dc0d27d0">
<title>ADR-0005 — Implement one lane narrowly, route everything else</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0005</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0005 — Implement one lane narrowly, route everything else</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0005-implement-narrowly-route-broadly.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted. The founding charter decision, taken 2026-06-18 (<code>history/2026-06-18-access-routing-intent-shift-assessment.md</code>).</p>
</section>
<section id="context"><h2>Context</h2>
<p>ops-warden began as an SSH certificate manager. It then became the place workers asked when they did not know where a credential came from — which is a real need, and the obvious way to serve it is to start fetching credentials.</p>
<p>Down that path is a component that issues SSH certificates, vends API keys, brokers tokens, and holds authority over all of them: a single point whose compromise is total. NetKingdom's architecture deliberately separates identity (key-cape), authorization (flex-auth), and secrets (OpenBao). A helpful front door that absorbed all three would quietly undo that separation, one convenience at a time.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>ops-warden executes exactly one lane with its own authority: SSH certificate issuance for <code>adm</code>/<code>agt</code>/<code>atm</code> actors.</strong> <code>warden_executes: true</code> appears on one catalog entry and is expected to stay that way.</p>
<p><strong>For every other need it routes, and where the lane is <code>exec_capable</code> it may assist by proxying as the caller</strong> under <code>ADR-0002</code>. Routing is not a lesser service — it is the service. Knowing which subsystem owns a need, and being right about it, is what this repo sells.</p>
<p><strong>Scope growth is tested by ownership, not by usefulness.</strong> "Would this be handy in ops-warden?" is the wrong question and almost always answers yes. The right question is "does ops-warden have the authority to own this, permanently?" If the answer is no, the correct outcome is a pointer, or an <code>interim</code> cover recorded under <code>ADR-0003</code>.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>The blast radius stays bounded and known.</strong> Compromising ops-warden yields the SSH signing lane. That is worth defending well precisely because it is the only thing here.</p>
<p><strong>We say no to requests that would be easy to say yes to.</strong> <code>warden secret</code>, <code>warden login</code>, <code>warden bao</code>, <code>warden tunnel</code> do not exist and must not be invented; the agent instructions name them as anti-patterns because agents keep reaching for them. Each would be a day's work and a permanent widening.</p>
<p><strong>Being useful therefore depends on the pointers being right</strong>, which is the whole weight behind <code>ADR-0001</code>'s anchor enforcement and the catalog's review dates. A router that routes wrongly is worse than no router.</p>
<p><strong>It leaves real gaps visible rather than filled.</strong> Six workload lanes and three tenant lanes are covered interim because secrets-engine and tenant-engine have not shipped front doors. Under this ADR that is the correct state, tracked under <code>ADR-0003</code>, and not a signal that ops-warden should absorb them.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>SCOPE.md</code> — the issue-vs-route table</li><li><code>wiki/AccessRouting.md</code> — role and boundary</li><li><code>ADR-0001</code>, <code>ADR-0002</code>, <code>ADR-0003</code> — the three rules that follow from this one</li></ul>
</section><footer><span>ops-warden-adr-0005 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0005-implement-narrowly-route-broadly.md · 35aff380a33f51a512c1e1b42d52d1dc0d95930f</span></footer></main></div></div></html>

217
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0007.html Normal file
View file

@ -0,0 +1,217 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4e267179db741b27a3e62f81f753cd9752c97412">
<meta name="policy-source-digest" content="868f953688988b11ce48f4141833bbca51abdb4e86d5b495a8a905002830d7b0">
<title>ADR-0007 — Build-stage permissiveness stops at credential disclosure</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0007</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-19</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0007 — Build-stage permissiveness stops at credential disclosure</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0007-build-stage-stops-at-credential-disclosure.md · 4e267179db741b27a3e62f81f753cd9752c97412</code></p><p class="sub">Review due: 2027-02-19</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-19, alongside grading the last 14 ungraded catalog lanes.</p>
</section>
<section id="context"><h2>Context</h2>
<p><code>ADR-0006</code> deferred a global fail-closed authorization gate because uniform enforcement across an estate under deep refactor hardens the access needed to perform the refactor. The organization's declared posture is <code>build</code> (WP-0029), and the operator has confirmed the estate need not be tight yet.</p>
<p>That is correct, and it is also the kind of principle that quietly generalises past its warrant. Read loosely, "we are in build stage" argues for relaxing every control, including the ones that stop a credential landing in a logged agent transcript. Those are not the same class of control, and the difference is not severity — it is <strong>cost</strong>.</p>
<p><code>RISK-F-0003</code> made the distinction concrete. <code>ADR-0004</code> reads as a categorical rule: high-risk lanes refuse raw value streaming to agent sessions. The implementation was <code>risk == &quot;high&quot;</code> against an <strong>optional</strong> field, so 14 of 27 lanes never reached the control at all — five of them <code>exec_capable</code>. The control had not been relaxed by anyone's decision. It had simply never been reached, which is worse, because nothing announced it.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>Build-stage permissiveness applies to controls that gate work. It does not apply to controls that prevent credential disclosure.</strong></p>
<p>The test is friction, not severity:</p>
<ul><li>A control that can <strong>block a legitimate operation</strong> — a fail-closed authorization gate, an enforcement stance — is a candidate for relaxation while the organization is in <code>build</code>, and <code>ADR-0006</code> scopes that relaxation to zones.</li><li>A control that <strong>redirects how a value moves without preventing the work</strong> — the agent read-boundary, which refuses raw stdout but leaves <code>--out</code>, <code>--exec</code>, <code>--wrap</code> and <code>--fingerprint</code> fully available — is not relaxed by build posture, because relaxing it buys nothing. Nobody is unblocked by it.</li></ul>
<p>The asymmetry that settles it: a blocked operation is recovered by retrying. A credential written into a logged transcript is not recovered by rotation — rotation limits the damage, it does not unwrite the log. The 2026-07-16 disclosure is the case in point.</p>
<p><strong>Therefore, regardless of <code>organization_posture</code>:</strong></p>
<ol><li>Every catalog lane carries an explicit <code>risk</code> grade. <strong>Absence is not a grade</strong>, and a lane that omits it is a defect, not a default.</li><li>Grading is done on merit, per lane. This decision is not licence to grade everything <code>high</code> — an over-broad grade is its own inaccuracy, and <code>tenancy-posture</code> §6's <em>accuracy, not altitude</em> applies to this field too.</li><li>Minimum credential-handling standards — the read-boundary, the safe fetch transports, the no-secret audit guard — hold in every posture.</li></ol>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><strong>We accept</strong> the grading cost, now and on every new lane. That is the point: <code>WARDEN-WP-0032-T06</code> makes an ungraded lane impossible rather than merely discouraged, because a rule enforced by remembering is not enforced.</p>
<p><strong>We reject</strong> "build stage" as a general argument in credential-handling discussions. It is a real and useful argument about <em>gating</em>, and citing it against a disclosure control is a category error this record exists to name.</p>
<p><strong>We note what this decision is not.</strong> It does not set severity for <code>RISK-F-0003</code> — that is <code>risk-nexus</code>'s. It does not make ops-warden the judge of other repos' controls. And it does not survive contact with a zone model that says otherwise: when <code>zone-engine</code> defines admission standards, a zone may legitimately require <em>more</em> than this floor. It may not require less.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>ADR-0004</code> — high-risk lanes refuse raw value streaming to agent sessions</li><li><code>ADR-0006</code> — enforcement is zone-scoped, never a global flag</li><li><code>RISK-F-0003</code> — the read-boundary blind spot that prompted this</li><li><code>WARDEN-WP-0032-T05</code> / <code>T06</code> — the grading, and making absence impossible</li><li><code>zone-engine</code> <code>ZONE-WP-0001</code> — where admission standards will be defined</li></ul>
</section><footer><span>ops-warden-adr-0007 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0007-build-stage-stops-at-credential-disclosure.md · 4e267179db741b27a3e62f81f753cd9752c97412</span></footer></main></div></div></html>

215
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0008.html Normal file
View file

@ -0,0 +1,215 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4e267179db741b27a3e62f81f753cd9752c97412">
<meta name="policy-source-digest" content="2e22863ba592802cceb40b32d395168b42ace747741f5188307505eaa89ff764">
<title>ADR-0008 — A lane&#x27;s risk grade covers every field its path discloses</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0008</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-21</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0008 — A lane&#x27;s risk grade covers every field its path discloses</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0008-grade-the-path-not-the-field.md · 4e267179db741b27a3e62f81f753cd9752c97412</code></p><p class="sub">Review due: 2027-02-21</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-21, after <code>secrets-engine</code> found two under-graded lanes while reviewing ops-warden's own catalog metadata.</p>
</section>
<section id="context"><h2>Context</h2>
<p><code>ADR-0007</code> requires every catalog lane to carry an explicit <code>risk</code> grade. It does not say what the grade is <em>of</em>, and the omission turned out to matter.</p>
<p>The catalog describes a lane by a single <code>fetch_command</code> naming a single field — <code>bao kv get -field=ISSUE_CORE_API_KEY &lt;path&gt;</code>. Grading followed that description. But the unit of disclosure is not the field, it is the <strong>path</strong>: <code>bao kv get</code> without <code>-field</code> returns every key stored there, and an agent session that discloses one field has disclosed all of them.</p>
<p>On 2026-08-19, grading all 27 lanes, ops-warden graded <code>issue-core-ingestion-api-key</code> and <code>reuse-surface-hub-write-token</code> as <code>standard</code> — "ordinary internal workload secrets". Both grades read only the headline field. <code>CCR-2026-0002</code> records a deliberate decision to keep <code>GITEA_BACKEND_TOKEN</code> at the first path; <code>CCR-2026-0005</code> declares a dual-consumer webhook HMAC at the second. Neither is recovered by rotating the credential the lane is named after.</p>
<p>Three details make this worth a record rather than a fix:</p>
<ul><li><strong>The evidence was already ours.</strong> The field sets were in the CCRs the catalog already cites as authoritative. This was not missing data; it was unread data.</li><li><strong>A test held the error still.</strong> <code>test_high_risk_lanes_classified</code> asserted <code>issue-core-ingestion-api-key</code> was <em>not</em> high. A first grading pass had marked it high, the test contradicted it, and the test was believed. A test that encodes a judgement defends that judgement from correction.</li><li><strong>Another repo found it.</strong> <code>secrets-engine</code> graded both <code>high</code> independently while drafting catalog entries whose schema records <code>fields</code>. A schema that names the field set makes the right grade obvious; ours did not have one.</li></ul>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>A lane's <code>risk</code> grade is a property of its path, and must cover the union of everything a read of that path would disclose.</strong></p>
<ol><li>Where the field set is known, the catalog records it as <code>fields</code>, with the authority it came from.</li><li>The grade is argued against the most damaging field, not the named one.</li><li>Where the field set is unknown, that is stated — never assumed to be one field. An unverified field set is a reason to grade conservatively, matching the <code>inter-hub-bootstrap-ssh</code> precedent under <code>ADR-0007</code>.</li><li>Establishing a field set must not be done by reading the secret. Use the owning CCR, the owner's catalog, or <code>bao kv metadata</code>. <code>bao kv get</code> on a high-risk path is the 2026-07-16 vector and is forbidden by <code>ADR-0004</code> for agent sessions regardless of intent.</li></ol>
</section>
<section id="consequences"><h2>Consequences</h2>
<p><code>ADR-0007</code> is unchanged and still governs: every lane carries an explicit grade, and absence fails safe. This record says what that grade must account for.</p>
<p>Grading gets more expensive: it now requires knowing what is at a path, not just what the lane is called. That cost is the point — the cheap version produced two wrong answers in one pass and is the reason this exists.</p>
<p>A test that asserts a grade is asserting a judgement. When a grade is disputed, re-argue it from evidence before trusting the test that encodes it.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>ADR-0007</code> — every lane carries an explicit grade; build-stage permissiveness stops at credential disclosure</li><li><code>ADR-0004</code> — high-risk lanes refuse raw value streaming to agent sessions</li><li><code>ADR-0001</code> — the catalog is a pointer layer; <code>fields</code> records the owner's declared field set with its source, and does not restate their procedure</li><li><code>WARDEN-WP-0033-T02</code>; <code>secrets-engine</code> <code>SECRETS-WP-0006</code></li><li><code>history/2026-07-16-credential-disclosure-lessons.md</code></li></ul>
</section><footer><span>ops-warden-adr-0008 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0008-grade-the-path-not-the-field.md · 4e267179db741b27a3e62f81f753cd9752c97412</span></footer></main></div></div></html>

215
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0009.html Normal file
View file

@ -0,0 +1,215 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4e267179db741b27a3e62f81f753cd9752c97412">
<meta name="policy-source-digest" content="73fff22177b4bec2c56ff737e06e4225eb02d39669be3ea1b723906245f878b8">
<title>ADR-0009 — Adopt security-zones v0.1 as a consumer</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0009</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-22</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0009 — Adopt security-zones v0.1 as a consumer</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0009-adopt-security-zones-as-a-consumer.md · 4e267179db741b27a3e62f81f753cd9752c97412</code></p><p class="sub">Review due: 2026-11-22</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-22 after zone-engine completed <code>ZONE-WP-0001-T03/T05</code> and published the declaration, compilation, stance, and failure-mode contract in canon revision <code>337484a</code>; zone-engine's reference compiler is revision <code>9b6ada7</code>.</p>
</section>
<section id="context"><h2>Context</h2>
<p>ADR-0006 rejected a repo-wide <code>policy.enabled</code> switch because one boolean plus one <code>fail_closed</code> value made flex-auth a uniform dependency of every signing path, including continuity paths needed to repair that dependency. It deferred the replacement to zone-engine rather than designing an estate model here.</p>
<p>The owning model now exists. A zone is an evidenced workload-admission fact; control stance remains with the control owner, and dependency failure behavior remains with the PEP. Membership resolves only through an authoritative workload identity. Missing identity, membership, admission evidence, or a required floor is <code>unknown</code>, never an inferred permissive zone.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p>Ops-warden adopts <code>security-zones_v0.1</code> and accepts its initial build-stage rows for the controls ops-warden owns:</p>
<ul><li>the pre-sign PEP fails open for <code>z0-experimental</code>, <code>z1-operational</code>, <code>z2-protected</code>, <code>z2-continuity</code>, and build-profile <code>unknown</code>; it fails closed for <code>z3-critical</code>;</li><li>the agent high-risk read boundary remains enforced and fail-closed in every zone and for <code>unknown</code>;</li><li><code>warden plan</code> never derives <code>autonomous</code> authority from unknown zone evidence.</li></ul>
<p>The implementation follows four rules:</p>
<ol><li><code>policy.enabled</code> and the global <code>policy.fail_closed</code> setting are retired and rejected by configuration loading. The PEP chooses failure behavior from a total per-zone map.</li><li>The existing compiled flex-auth registry is the resource-membership carrier. Actor resources receive <code>workload_id</code>, <code>security_zone</code>, <code>security_zone_admission</code>, and <code>security_zone_revision</code>. The dormant <code>trust_zone: platform</code> constant is removed; it is not repurposed.</li><li>Workload joins are explicit. Managed deployables use Repo Manager's exact <code>(rapp_id, workload_identity.name, deployable?)</code> tuple. Independent operational workloads use their owner-reviewed <code>tenancy.yaml</code>. Catalog owners distinguish <code>not-applicable</code> from applicable-but-<code>unknown</code>; no path or repository-name inference is allowed.</li><li>A fail-open signing result is metadata, not silence. Signature and unified audit records carry the selected zone, failure mode, outcome, and decision id when one exists.</li></ol>
<p>Ops-warden itself declares <code>z1-operational</code>. That is an accuracy decision: the workload has M1 evidence and does not yet have the SLO history, on-call rotation, or exercised recovery evidence needed for z2 admission.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p>The global flip and its failure cycle no longer exist. An unknown target remains observable and follows the versioned build profile without manufacturing membership. A future organization-posture graduation changes the versioned control profile, not each workload declaration.</p>
<p>The flex-auth policy package still owns pre-sign stance. Ops-warden can compile and send the membership attributes, handle <code>allow</code>/<code>audit_only</code>/deny, and apply the correct PEP failure mode; it does not write flex-auth's Rego rows.</p>
<p>Catalog coverage is intentionally honest at adoption: exact references resolve where authoritative declarations exist, applicable lanes without one report <code>unknown</code> with a reason, and generic actions/patterns are explicitly <code>not-applicable</code>. Resolution coverage improves by adding owner declarations, never by adding heuristics here.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>security-zones_v0.1</code> (net-kingdom canon revision <code>337484a</code>; zone-engine compiler revision <code>9b6ada7</code>)</li><li>Repo Manager <code>helixforge.workloads.ops-warden-reference.v1</code> revision <code>890f3b0</code></li><li>NetKingdom tenancy-posture Decisions 5.6.1/5.6.2</li><li><code>WARDEN-WP-0032</code></li><li><code>ADR-0004</code>, <code>ADR-0007</code>, and <code>ADR-0008</code></li></ul>
</section><footer><span>ops-warden-adr-0009 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0009-adopt-security-zones-as-a-consumer.md · 4e267179db741b27a3e62f81f753cd9752c97412</span></footer></main></div></div></html>

218
docs/evidence/2026-10-11-served-publication-history/pages/ops-warden-adr-0010.html Normal file
View file

@ -0,0 +1,218 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="4e267179db741b27a3e62f81f753cd9752c97412">
<meta name="policy-source-digest" content="064455bcb2870abf8e243f5a8c154e50bfc1c537cfba7996a792f9e314dd78ae">
<title>ADR-0010 — ops-warden is Staff</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>ops-warden-adr-0010</span> <span class="stat">accepted · 1</span> <span>ops-warden</span> <span>reviewed 2026-08-28</span><span>generated from canonical source — do not edit</span></div><h1>ADR-0010 — ops-warden is Staff</h1><p class="sub">Source: <code>ops-warden · docs/adr/ADR-0010-ops-warden-is-staff.md · 4e267179db741b27a3e62f81f753cd9752c97412</code></p><p class="sub">Review due: 2026-11-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
<p>Accepted 2026-08-28, answering intake <code>WARDEN-IN-0001</code> from gate-house, which carries decision <code>GH-DEC-2026-001</code>. The standard being adopted — <code>net-kingdom/canon/standards/security-layer-model_v0.1.md</code> — is <code>proposed</code>, and was proposed pending assent from flex-auth, kings-guard, and ops-warden. This ADR is ops-warden's half of that assent.</p>
</section>
<section id="context"><h2>Context</h2>
<p>The estate acquired overlapping claims to the same responsibility, most visibly two repositories describing themselves as the authorization control plane. The layer model resolves the overlap by layering repositories on determinism — Taxonomy, Tooling, Engines, Staff — and by two rules: Staff never touches Tooling directly (§5), and <code>access-engine</code> is the only policy decision point (§6).</p>
<p>ops-warden is assigned Staff. Two demarcations follow that touch this repository: the security curriculum it had been carrying belongs to gate-house, and the words <em>access lane</em> and <em>access rule</em> are bound to different owners.</p>
<p>Full reasoning: <code>history/2026-08-28-security-layer-model-assent.md</code>.</p>
</section>
<section id="decision"><h2>Decision</h2>
<p><strong>1. ops-warden is Staff and declares it.</strong> <code>INTENT.md</code> carries the layer label and the §5 invariant. ops-warden holds no state another layer depends on at runtime and renders no authorization decision — it consumes them.</p>
<p><strong>2. Lanes, not rules.</strong> ops-warden owns <em>how</em> a worker reaches a host: SSH certificate issuance, the routing catalog, <code>warden access</code>, <code>warden plan</code>, <code>cert_command</code>. It never owns <em>whether</em> a worker may — that is <code>access-engine</code> (today <code>flex-auth</code>), and ops-warden neither renders nor caches that decision. This restates what <code>ADR-0002</code> and <code>ADR-0005</code> already bind; it is recorded here because the demarcation is now normative estate-wide and other repositories rely on ops-warden holding to it. The ruled rename <code>flex-auth</code> → <code>access-engine</code> is assented to; ops-warden asks only for a window in which both names resolve.</p>
<p><strong>3. Doctrine goes to gate-house; runbooks stay here.</strong> ops-warden does not restate security doctrine, the authority model, or the curriculum. It references gate-house's. It keeps everything operational about the lanes it stewards: which subsystem owns which need, how to obtain a credential lane by lane, and conformance evidence for its own lanes. <code>.claude/rules/credential-routing.md</code> is runbook, not curriculum, and stays inlined in this and every other repository.</p>
<p><strong>4. One declared engine gap, not an exemption.</strong> <code>src/warden/vault.py</code> (<code>VaultCA</code>) is a direct OpenBao client performing a write from a Staff repository. It is a §5 non-conformance. ops-warden declares it rather than arguing it away:</p>
<ul><li><strong>intended owner:</strong> <code>secrets-engine</code> (credential abstraction, custody, lifecycle)</li><li><strong>blocked on:</strong> no engine exposes an SSH certificate signing surface</li><li><strong>review:</strong> with this ADR, every 3 months</li></ul>
<p>Until that surface exists, ops-warden continues to sign — refusing to would remove production host access to close a documentation gap — and reports the position as open. <code>warden desk</code>'s <code>bao kv put</code> is declared on the same terms. <code>taint.py</code> is metadata-only observation, declared under §5's read-only allowance. <code>proxy.py</code> supplies no authority of its own: it runs the owner's tool under the caller's identity and is governed by <code>ADR-0002</code>.</p>
<p>This is <code>ADR-0003</code> turned inward. ops-warden has required an intended owner and a blocker on 27 catalog lanes it holds for other repositories; it holds itself to the same record.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<p>ops-warden's conformance under §10 is <em>declared non-conformant with a tracked closure path</em>, not clean. That is the accurate state and it is the state that gets fixed, because it names an owner who can fix it.</p>
<p>An amendment to §5 has been offered to gate-house — a second sanctioned shape alongside read-only diagnostics: a declared engine gap carrying intended owner, blocker, and review date, machine-readable so §10 can tell a tracked gap from an undeclared violation. It is offered, not assumed; §5 stays gate-house's to write. If gate-house declines it, ops-warden's position is a plain non-conformance and is reported as one.</p>
<p>The <code>NetKingdom Security Literacy</code> section stops being a prose second source for <code>registry/routing/catalog.yaml</code>, which <code>ADR-0001</code> had already ruled against for catalog procedure.</p>
</section>
<section id="related"><h2>Related</h2>
<ul><li><code>net-kingdom/canon/standards/security-layer-model_v0.1.md</code> (proposed, gate-house)</li><li><code>gate-house/decisions/decisions.md</code> — <code>GH-DEC-2026-001</code></li><li><code>history/2026-08-28-security-layer-model-assent.md</code></li><li><code>ADR-0001</code>, <code>ADR-0002</code>, <code>ADR-0003</code>, <code>ADR-0005</code>, <code>ADR-0009</code></li><li><code>WARDEN-IN-0001</code></li></ul>
</section><footer><span>ops-warden-adr-0010 · 1 · accepted</span><span>ops-warden · docs/adr/ADR-0010-ops-warden-is-staff.md · 4e267179db741b27a3e62f81f753cd9752c97412</span></footer></main></div></div></html>

214
docs/evidence/2026-10-11-served-publication-history/pages/policy-nexus-adr-0001.html Normal file
View file

@ -0,0 +1,214 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="6515ed9ef8499cb3de3397f0ae3993cc71440599">
<meta name="policy-source-digest" content="a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be">
<title>Policy addressing and permanence</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>policy-nexus-adr-0001</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>Policy addressing and permanence</h1><p class="sub">Source: <code>policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#permanence-promise"><span class="n">·</span>Permanence promise</a></li><li><a href="#publication-scope"><span class="n">·</span>Publication scope</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li></ol></nav><main><ul><li>Status: accepted</li><li>Date: 2026-08-18</li><li>Owner: the-custodian</li></ul>
<section id="decision"><h2>Decision</h2>
<p>A document has one stable current address and immutable revision addresses:</p>
<pre>/&lt;kind&gt;/&lt;document&gt;/&lt;version&gt;/
/&lt;kind&gt;/&lt;document&gt;/&lt;version&gt;/revisions/&lt;revision&gt;/</pre>
<p><code>&lt;kind&gt;</code> is one of <code>standards</code>, <code>architecture</code>, <code>constitution</code>, or <code>adr</code>. <code>&lt;document&gt;</code> is a kebab-case slug that is unique on the site. The owner-facing rules live in <code>docs/publication-contract.md</code>.</p>
<p>The publication manifest records both. Existing public paths become permanent redirect aliases; the first is <code>/tenancy-posture.html</code>. No URL is derived from a checkout path, branch name, build number or hosting implementation.</p>
<p>The current address advances only when the owning source publishes a new revision. A revision address is write-once: the builder records the exact git commit (or commit plus working-tree marker) and the full source-content digest. It refuses to replace that revision with different content. Committing the same bytes may update the current page's provenance but does not rewrite the already-published revision page. The generated publication manifest makes the source repository, path, revision and digest machine-readable.</p>
<p>Superseded and withdrawn documents are never deleted. The current page gains a status banner and link to its successor; every historical revision continues to resolve. “Withdrawn” means retained and visibly non-current. Deletion is not a lifecycle state.</p>
<p>Source Git history remains the authority for versions that predate this site. Once a revision is published, the built revision page is also retained by the hosting artifact/release. Rollback republishes a previous complete build; it does not rebuild old pages from a changed working tree.</p>
</section>
<section id="permanence-promise"><h2>Permanence promise</h2>
<p>A published URL is expected to resolve indefinitely. Breaking that promise requires an explicit the-custodian decision plus a redirect/export plan. A DNS, hosting or repository migration does not qualify: those must preserve paths.</p>
<p>This repo owns addressing, rendering and currency. It does not decide whether a draft is accepted; ratification belongs to the canon owner/the-custodian.</p>
</section>
<section id="publication-scope"><h2>Publication scope</h2>
<p>Canon <code>standards</code>, <code>architecture</code>, and <code>constitution</code> are in scope. <code>values</code>, <code>tpsc</code>, and <code>projects</code> are out until their owner marks individual documents as governing. Per-repo ADRs are in scope through explicit manifest entries. Workplans, evidence, runbooks and general docs are not.</p>
</section>
<section id="consequences"><h2>Consequences</h2>
<ul><li>Builds fail if a source disappears, an id differs, a path collides, or an immutable revision would change; stale output is not silently called fresh.</li><li>Pages show status, revision, owner, last review and exact source revision.</li><li>Availability remains restart recovery on the single-node rail. This contract promises stable addressing, not a high-availability SLA.</li></ul>
</section><footer><span>policy-nexus-adr-0001 · accepted-1 · accepted</span><span>policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 6515ed9ef8499cb3de3397f0ae3993cc71440599</span></footer></main></div></div></html>

248
docs/evidence/2026-10-11-served-publication-history/pages/policy-nexus-architecture.html Normal file
View file

@ -0,0 +1,248 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="a8fb62a3bcbff3daf03e5d3d56c3ca3a5bd991f8">
<meta name="policy-source-digest" content="179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480">
<title>Policy Nexus architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>policy-nexus-architecture</span> <span class="stat">proposed · draft-1</span> <span>the-custodian</span> <span>reviewed 2026-08-18</span><span>generated from canonical source — do not edit</span></div><h1>Policy Nexus architecture</h1><p class="sub">Source: <code>policy-nexus · docs/architecture/policy-nexus_v0.1.md · a8fb62a3bcbff3daf03e5d3d56c3ca3a5bd991f8</code></p><p class="sub">Review due: 2027-02-18</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#about-this-document"><span class="n">·</span>About this document</a></li><li><a href="#s1"><span class="n">1</span>Introduction and Goals</a></li><li><a href="#s2"><span class="n">2</span>Architecture Constraints</a></li><li><a href="#s3"><span class="n">3</span>System Scope and Context</a></li><li><a href="#s4"><span class="n">4</span>Solution Strategy</a></li><li><a href="#s5"><span class="n">5</span>Building Block View</a></li><li><a href="#s6"><span class="n">6</span>Runtime View</a></li><li><a href="#s7"><span class="n">7</span>Deployment View</a></li><li><a href="#s8"><span class="n">8</span>Cross-Cutting Concepts</a></li><li><a href="#s9"><span class="n">9</span>Architecture Decisions</a></li><li><a href="#s10"><span class="n">10</span>Quality Requirements</a></li><li><a href="#s11"><span class="n">11</span>Risks and Technical Debt</a></li><li><a href="#s12"><span class="n">12</span>Glossary</a></li></ol></nav><main><section id="about-this-document"><h2>About this document</h2>
<p>This document follows the <strong>arc42</strong> template for the publication surface at <code>policy.coulomb.social</code>. It is the first-wave architecture document this repository is allowed to author. Other first-wave systems are written in their owning repos.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Introduction and Goals</h2>
<p>Policy Nexus exists so estate canon and architecture decisions have a permanent, current, addressable public home. Before this system, governing documents were served from disposable artifact URLs.</p>
<h3>1.1 Requirements Overview</h3>
<ul><li>Publish canon (<code>standards</code>, <code>architecture</code>, <code>constitution</code>) and per-repo ADRs from the repositories that own them.</li><li>Keep one stable current URL and one immutable revision URL per document (ADR-0001).</li><li>Fail closed when a source disappears or an immutable revision would change.</li><li>Show status, owner, revision, and review currency on every page.</li></ul>
<h3>1.2 Quality Goals</h3>
<ol><li>Permanence of published addresses.</li><li>Honesty about staleness.</li><li>Source-of-truth stays upstream — this system never writes back.</li><li>Builds are deterministic and stdlib-only.</li></ol>
<h3>1.3 Stakeholders</h3>
<div class="scroll"><table><thead><tr><th>Role</th><th>Concern</th></tr></thead><tbody><tr><td>the-custodian</td><td>What counts as canon; ratification.</td></tr><tr><td>Source-repo owners</td><td>Their document is published accurately.</td></tr><tr><td>railiance-platform / rapp-policy-nexus</td><td>Substrate, Helm, promotion.</td></tr><tr><td>Readers inside and outside the estate</td><td>A URL that still resolves.</td></tr></tbody></table></div>
</section>
<section id="s2"><h2><span class="sn">02</span>Architecture Constraints</h2>
<p>N/A for this stub — first-wave complete will record stdlib-only rendering, single-node rail availability, and the no-CMS rule.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>System Scope and Context</h2>
<p><strong>In:</strong> addressing, rendering, currency, the public static site. <strong>Out:</strong> ratification, legal advice, regulatory intake (<code>risk-nexus</code>), editing surfaces, search.</p>
<h3>3.1 Business Context</h3>
<p>Source owners publish governing documents. This system makes those documents findable and durable. It does not decide what is current canon.</p>
<h3>3.2 Technical Context</h3>
<ul><li>Inputs: <code>publication.json</code>, sibling or fetched git checkouts, <code>source-inventory.json</code>.</li><li>Outputs: static HTML, <code>publication-manifest.json</code>, an OCI image.</li><li>Neighbours: owning source repos, Forgejo Actions, <code>rapp-policy-nexus</code>, <code>railiance-apps</code>, the reef Traefik/cert-manager substrate.</li></ul>
</section>
<section id="s4"><h2><span class="sn">04</span>Solution Strategy</h2>
<p>N/A for this stub — pull-on-schedule ingestion, explicit manifest entries, stdlib renderer. To be written as first-wave complete.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Building Block View</h2>
<h3>5.1 Level 1 – System/Top-Level</h3>
<p>N/A for this stub — builder, inventory auditor, currency checker, OCI artifact, Helm package in <code>rapp-policy-nexus</code>.</p>
<h3>5.2 Level 2 – Key Components</h3>
<p>N/A for this stub.</p>
<h3>5.3 Level 3 – Internal Structure (as needed)</h3>
<p>N/A for this stub.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Runtime View</h2>
<p>N/A — the published site is static files. Daily source-pull and promotion are operational scenarios for a later revision.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Deployment View</h2>
<p>N/A for this stub — see WP-0001-T04. Single-node restart recovery, not a high-availability SLA.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Cross-Cutting Concepts</h2>
<p>N/A for this stub.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
<div class="scroll"><table><thead><tr><th>Id</th><th>Status</th><th>Decision</th><th>Source</th></tr></thead><tbody><tr><td><code>policy-nexus-adr-0001</code></td><td>accepted</td><td>Stable current address + immutable revision address; no deletion</td><td><code>docs/adr/ADR-0001-addressing-and-permanence.md</code></td></tr></tbody></table></div>
<p>Later <code>publish</code> ADRs from WP-0003 land here. <code>local</code> and unresolved <code>conflict</code> rows do not.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Quality Requirements</h2>
<p>N/A for this stub — currency failure is already a build/CI failure.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Risks and Technical Debt</h2>
<p>N/A for this stub. Known residual: Markitect <code>arc42-v1</code> schema is not registered yet (WP-0002-T02).</p>
</section>
<section id="s12"><h2><span class="sn">12</span>Glossary</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Meaning</th></tr></thead><tbody><tr><td>Current address</td><td>The stable URL for the document as it now stands.</td></tr><tr><td>Revision address</td><td>Write-once URL for one source digest.</td></tr><tr><td>Publication entry</td><td>One object in <code>publication.json</code>. Discovery is not publication.</td></tr><tr><td>First-wave complete</td><td>Chapters 1, 3, 4, 5.1, 9 and 12 are real; others real or N/A.</td></tr></tbody></table></div>
</section><footer><span>policy-nexus-architecture · draft-1 · proposed</span><span>policy-nexus · docs/architecture/policy-nexus_v0.1.md · a8fb62a3bcbff3daf03e5d3d56c3ca3a5bd991f8</span></footer></main></div></div></html>

246
docs/evidence/2026-10-11-served-publication-history/pages/railiance-architecture.html Normal file
View file

@ -0,0 +1,246 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="5ffd7d1b40d56249f490a318e728047fd3517c4c">
<meta name="policy-source-digest" content="77de319978dfad02f40658bbeb96db46b246a46f1abd6a45f5b1269563de5568">
<title>Railiance architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>railiance-architecture</span> <span class="stat">proposed · draft-3</span> <span>railiance-master</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Railiance architecture</h1><p class="sub">Source: <code>railiance-master · docs/architecture/railiance_v0.1.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#about-this-document"><span class="n">·</span>About this document</a></li><li><a href="#s1"><span class="n">1</span>Introduction and Goals</a></li><li><a href="#s2"><span class="n">2</span>Architecture Constraints</a></li><li><a href="#s3"><span class="n">3</span>System Scope and Context</a></li><li><a href="#s4"><span class="n">4</span>Solution Strategy</a></li><li><a href="#s5"><span class="n">5</span>Building Block View</a></li><li><a href="#s6"><span class="n">6</span>Runtime View</a></li><li><a href="#s7"><span class="n">7</span>Deployment View</a></li><li><a href="#s8"><span class="n">8</span>Cross-Cutting Concepts</a></li><li><a href="#s9"><span class="n">9</span>Architecture Decisions</a></li><li><a href="#s10"><span class="n">10</span>Quality Requirements</a></li><li><a href="#s11"><span class="n">11</span>Risks and Technical Debt</a></li><li><a href="#s12"><span class="n">12</span>Glossary</a></li></ol></nav><main><section id="about-this-document"><h2>About this document</h2>
<p>First-wave arc42 for the Railiance runtime substrate. Deeper chapters belong to follow-on work in this repo. Chapter 9 lists the ADRs this repo already publishes; it does not paste them.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Introduction and Goals</h2>
<p>Railiance-master is the authoritative source for Railiance framework architecture: repo families, workload models, and substrate boundaries that implementation repos must not invent locally.</p>
<h3>1.1 Requirements Overview</h3>
<ul><li>Name the rails, reefs, and rApps and who owns each boundary.</li><li>Keep those decisions in <code>docs/adr/</code> with publication-grade metadata.</li><li>Consume platform packages; do not fork identity or tenancy.</li></ul>
<h3>1.2 Quality Goals</h3>
<ol><li>Reviewable boundary decisions.</li><li>Private-by-default exposure until admission.</li><li>Derived rails compose; they do not fork policy.</li></ol>
<h3>1.3 Stakeholders</h3>
<div class="scroll"><table><thead><tr><th>Role</th><th>Concern</th></tr></thead><tbody><tr><td>railiance-master</td><td>Framework language and first-wave rApp set.</td></tr><tr><td>railiance-platform</td><td>S3, placement, substrate services.</td></tr><tr><td>railiance-apps</td><td>Production digest bindings.</td></tr><tr><td>NetKingdom</td><td>Identity and tenancy posture of workloads.</td></tr></tbody></table></div>
</section>
<section id="s2"><h2><span class="sn">02</span>Architecture Constraints</h2>
<p>N/A for this stub.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>System Scope and Context</h2>
<p><strong>In:</strong> rails, reefs, rApp packaging, admission, exposure defaults. <strong>Out:</strong> tenant identity semantics (NetKingdom), publication of policy (policy-nexus), OS baseline (railiance-hosts).</p>
<h3>3.1 Business Context</h3>
<p>Implementation repos solve immediate cluster problems. This system holds the shared meaning so those repos do not drift.</p>
<h3>3.2 Technical Context</h3>
<p>Neighbours: <code>railiance-platform</code>, <code>railiance-apps</code>, <code>rapp-*</code> packages, the reef (Traefik, cert-manager), Forgejo, NetKingdom, policy-nexus.</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Solution Strategy</h2>
<p>N/A for this stub — repository-prefix architecture and rapp-first wave are already in the ADRs in §9.</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Building Block View</h2>
<h3>5.1 Level 1 – System/Top-Level</h3>
<p>N/A for this stub.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Runtime View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Deployment View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Cross-Cutting Concepts</h2>
<p>N/A for this stub.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
<p>Published on policy.coulomb.social from this repo:</p>
<div class="scroll"><table><thead><tr><th>Id</th><th>Status</th><th>Decision</th></tr></thead><tbody><tr><td><code>RMASTER-ADR-0001</code></td><td>accepted</td><td>Repository prefix architecture</td></tr><tr><td><code>RMASTER-ADR-0002</code></td><td>accepted</td><td>Wave 1 rail-kubernetes boundary</td></tr><tr><td><code>RMASTER-ADR-0003</code></td><td>accepted</td><td>First-wave rapp selection</td></tr><tr><td><code>RMASTER-ADR-0004</code></td><td>accepted</td><td>First-wave reef rollout</td></tr><tr><td><code>RMASTER-ADR-0005</code></td><td>accepted</td><td>Derived rail composition</td></tr><tr><td><code>RMASTER-ADR-0006</code></td><td>accepted</td><td>Reef production admission</td></tr><tr><td><code>RMASTER-ADR-0007</code></td><td>accepted</td><td>Rapp declaration contract</td></tr><tr><td><code>RMASTER-ADR-0008</code></td><td>accepted</td><td>Private-by-default exposure</td></tr><tr><td><code>RMASTER-ADR-0009</code></td><td>accepted</td><td>NetKingdom security-layer interaction</td></tr></tbody></table></div>
<p>Also published from <code>railiance-platform</code>: <code>RPLAT-ADR-0001</code> (S3 platform services), <code>RPLAT-ADR-0002</code> (placement rule), <code>RPLAT-ADR-0003</code> (decisions live in the repo).</p>
<p>Unresolved: identical accepted ADR-003/004 copies in railiance-hosts and railiance-infra. Not listed as current here until those owners rule.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Quality Requirements</h2>
<p>N/A for this stub.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Risks and Technical Debt</h2>
<p>N/A for this stub.</p>
</section>
<section id="s12"><h2><span class="sn">12</span>Glossary</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Meaning</th></tr></thead><tbody><tr><td>Rail</td><td>A composed runtime path.</td></tr><tr><td>Reef</td><td>The production admission environment.</td></tr><tr><td>rApp</td><td>A packaged workload bound by a declaration contract.</td></tr></tbody></table></div>
</section><footer><span>railiance-architecture · draft-3 · proposed</span><span>railiance-master · docs/architecture/railiance_v0.1.md · 5ffd7d1b40d56249f490a318e728047fd3517c4c</span></footer></main></div></div></html>

247
docs/evidence/2026-10-11-served-publication-history/pages/state-hub-architecture.html Normal file
View file

@ -0,0 +1,247 @@
<!doctype html>
<html lang="en"><meta charset="utf-8">
<meta name="policy-source-revision" content="da30ce6723f9c5e6fdd994c78bb646986e819d3f">
<meta name="policy-source-digest" content="e7104b2182612efe90c9a12168757506402490229814d454e94917ae62d2bfac">
<title>State Hub architecture</title>
<style>
:root{
--paper:#EDEEF0; --surface:#F6F7F8; --surface-2:#E4E6E9;
--ink:#171D24; --ink-2:#4A5561; --ink-3:#737E8A;
--rule:#D3D7DC; --rule-strong:#B6BCC3;
--brass:#8A6A2E; --brass-soft:#EFE5CD; --brass-line:#C9AE74;
--clay:#8A3A2C; --clay-soft:#F2DFDA;
--l0:#DCE0E2; --l1:#B9C4C7; --l2:#8CA1A6; --l3:#567D84; --l4:#23555E;
--chip-fg:#F6F7F8;
--font-display:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
--font-body:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;
--font-mono:ui-monospace,"SF Mono","Cascadia Code",Menlo,Consolas,monospace;
--measure:66ch;
}
@media (prefers-color-scheme:dark){
:root:not([data-theme="light"]){
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
}
:root[data-theme="dark"]{
--paper:#12161A; --surface:#191E24; --surface-2:#222831;
--ink:#E6E9EC; --ink-2:#A3ADB7; --ink-3:#78838E;
--rule:#2A3138; --rule-strong:#3B444D;
--brass:#C9A45C; --brass-soft:#33290F; --brass-line:#6B5426;
--clay:#D08A76; --clay-soft:#3A211B;
--l0:#262C32; --l1:#35424A; --l2:#4A626B; --l3:#6A939D; --l4:#97C4CD;
--chip-fg:#12161A;
}
*{box-sizing:border-box}
body{
margin:0; background:var(--paper); color:var(--ink);
font-family:var(--font-body); font-size:17px; line-height:1.62;
-webkit-font-smoothing:antialiased;
}
.wrap{max-width:1180px;margin:0 auto;padding:0 24px 96px}
.layout{display:grid;grid-template-columns:180px minmax(0,1fr);gap:56px;align-items:start}
@media (max-width:960px){.layout{grid-template-columns:1fr;gap:0}.rail{display:none}}
/* ---------- rail ---------- */
.rail{position:sticky;top:28px;padding-top:8px;font-family:var(--font-display);font-size:12px;line-height:1.5}
.rail ol{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:7px}
.rail a{color:var(--ink-3);text-decoration:none;display:flex;gap:9px}
.rail a:hover,.rail a:focus-visible{color:var(--brass)}
.rail .n{font-family:var(--font-mono);font-size:10px;color:var(--rule-strong);min-width:16px;padding-top:1px}
.rail .grp{margin-top:14px;font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--rule-strong)}
/* ---------- header ---------- */
header{padding:64px 0 40px;border-bottom:2px solid var(--ink);margin-bottom:44px}
.eyebrow{font-family:var(--font-mono);font-size:11.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);display:flex;flex-wrap:wrap;gap:14px;margin-bottom:22px}
.eyebrow .stat{color:var(--clay)}
h1{font-family:var(--font-display);font-weight:800;letter-spacing:-.035em;line-height:.94;font-size:clamp(46px,9vw,92px);margin:0 0 6px;text-wrap:balance}
.sub{font-family:var(--font-display);font-weight:500;font-size:clamp(16px,2.4vw,21px);letter-spacing:-.01em;color:var(--ink-2);margin:0 0 30px;max-width:34ch;line-height:1.3}
.metagrid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:20px 28px;border-top:1px solid var(--rule);padding-top:20px}
.metagrid dt{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);margin-bottom:5px}
.metagrid dd{margin:0;font-family:var(--font-display);font-size:13.5px;line-height:1.45;color:var(--ink)}
/* ---------- typography ---------- */
section{margin-bottom:60px;scroll-margin-top:24px}
h2{font-family:var(--font-display);font-weight:750;letter-spacing:-.022em;font-size:clamp(24px,3.4vw,31px);line-height:1.12;margin:0 0 18px;text-wrap:balance;display:flex;gap:14px;align-items:baseline}
h2 .sn{font-family:var(--font-mono);font-size:12px;font-weight:400;color:var(--brass);letter-spacing:.06em;flex:none;padding-top:2px}
h3{font-family:var(--font-display);font-weight:700;font-size:16px;letter-spacing:-.008em;margin:34px 0 10px;color:var(--ink)}
p{margin:0 0 15px;max-width:var(--measure)}
ul,ol{max-width:var(--measure);margin:0 0 15px;padding-left:20px}
li{margin-bottom:7px}
strong{font-weight:600}
em{font-style:italic}
code{font-family:var(--font-mono);font-size:.855em;background:var(--surface-2);padding:1px 5px;border-radius:2px}
a{color:var(--brass)}
.lede{font-size:19px;line-height:1.55;color:var(--ink-2);max-width:60ch}
/* ---------- devices ---------- */
.callout{border-left:3px solid var(--brass);background:var(--brass-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.callout p:last-child{margin-bottom:0}
.callout .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
.rule-quote{border-top:2px solid var(--ink);border-bottom:2px solid var(--ink);padding:26px 0;margin:28px 0;max-width:var(--measure)}
.rule-quote p{font-family:var(--font-display);font-weight:600;font-size:19px;line-height:1.38;letter-spacing:-.014em;margin:0;text-wrap:balance}
.hard{border-left:3px solid var(--clay);background:var(--clay-soft);padding:18px 22px;margin:0 0 24px;max-width:var(--measure)}
.hard .lbl{font-family:var(--font-mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--clay);display:block;margin-bottom:8px}
.hard p:last-child{margin-bottom:0}
.dec{font-family:var(--font-mono);font-size:10.5px;letter-spacing:.08em;color:var(--brass);text-transform:uppercase}
.vec{font-family:var(--font-mono);font-size:.9em;font-weight:600;background:var(--surface-2);padding:2px 7px;border-radius:2px;white-space:nowrap;letter-spacing:.04em}
/* ---------- tables ---------- */
.scroll{overflow-x:auto;margin:0 0 24px;-webkit-overflow-scrolling:touch}
table{border-collapse:collapse;width:100%;min-width:520px;font-family:var(--font-display);font-size:13.5px;line-height:1.45}
th{text-align:left;font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;text-transform:uppercase;color:var(--ink-3);font-weight:400;padding:0 16px 8px 0;border-bottom:1px solid var(--rule-strong);vertical-align:bottom}
td{padding:11px 16px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top;color:var(--ink-2)}
td:first-child{color:var(--ink);font-weight:600}
tbody tr:last-child td{border-bottom:none}
.lvl{font-family:var(--font-mono);font-weight:600;font-size:12px;letter-spacing:.04em;color:var(--ink)}
/* ---------- ladders ---------- */
.breakout{margin:34px 0 40px}
.bhead{display:flex;justify-content:space-between;align-items:baseline;gap:20px;border-bottom:1px solid var(--rule-strong);padding-bottom:9px;margin-bottom:22px;flex-wrap:wrap}
.bhead h3{margin:0;font-size:13px;letter-spacing:.1em;text-transform:uppercase;font-family:var(--font-mono);font-weight:400;color:var(--ink-3)}
.bhead .note{font-family:var(--font-display);font-size:12.5px;color:var(--ink-3)}
.ladders{display:grid;gap:26px}
.ladder{display:grid;grid-template-columns:126px minmax(0,1fr);gap:18px;align-items:start}
@media (max-width:700px){.ladder{grid-template-columns:1fr;gap:10px}}
.ladder .pname{font-family:var(--font-display);font-weight:700;font-size:14px;letter-spacing:-.01em;padding-top:2px}
.ladder .pname span{display:block;font-family:var(--font-mono);font-size:10px;font-weight:400;letter-spacing:.1em;text-transform:uppercase;color:var(--ink-3);margin-top:3px}
.rungs{display:grid;gap:3px;grid-template-columns:repeat(5,minmax(0,1fr))}
@media (max-width:700px){.rungs{grid-template-columns:repeat(2,minmax(0,1fr))}}
.rung{padding:9px 10px 11px;background:var(--surface);border-top:4px solid var(--l0);min-width:0}
.rung.r1{border-top-color:var(--l1)} .rung.r2{border-top-color:var(--l2)}
.rung.r3{border-top-color:var(--l3)} .rung.r4{border-top-color:var(--l4)}
.rung .code{font-family:var(--font-mono);font-size:11px;font-weight:600;letter-spacing:.06em;color:var(--ink);display:block;margin-bottom:4px}
.rung .txt{font-family:var(--font-display);font-size:11.5px;line-height:1.34;color:var(--ink-2);display:block}
.rung.na{opacity:.42}
/* ---------- matrix ---------- */
.matrix-shell{display:grid;grid-template-columns:auto minmax(0,1fr);gap:12px;align-items:stretch;margin-bottom:14px}
.ylab{writing-mode:vertical-rl;transform:rotate(180deg);font-family:var(--font-mono);font-size:9.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);text-align:center;padding-bottom:22px}
.mgrid{display:grid;grid-template-columns:34px repeat(5,minmax(0,1fr));gap:3px}
.mcell{background:var(--surface);min-height:60px;padding:6px;display:flex;flex-direction:column;justify-content:flex-end;gap:4px;min-width:0}
.mcell.tint1{background:color-mix(in srgb,var(--l1) 26%,var(--surface))}
.mcell.tint2{background:color-mix(in srgb,var(--l2) 26%,var(--surface))}
.mcell.tint3{background:color-mix(in srgb,var(--l3) 24%,var(--surface))}
.mcell.tint4{background:color-mix(in srgb,var(--l4) 22%,var(--surface))}
.mcell.void{background:repeating-linear-gradient(135deg,transparent,transparent 5px,var(--rule) 5px,var(--rule) 6px);opacity:.55}
.rlab,.clab{font-family:var(--font-mono);font-size:10px;font-weight:600;letter-spacing:.05em;color:var(--ink-3);display:flex;align-items:center;justify-content:center}
.rlab{min-height:60px}
.clab{padding-top:7px;min-height:22px}
.pin{font-family:var(--font-mono);font-size:9.5px;font-weight:600;letter-spacing:.02em;background:var(--ink);color:var(--paper);padding:2px 5px;border-radius:2px;line-height:1.3;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.pin.ghost{background:transparent;color:var(--ink-2);border:1px dashed var(--rule-strong)}
.mnote{display:flex;gap:22px;flex-wrap:wrap;font-family:var(--font-display);font-size:12px;color:var(--ink-3);padding-top:6px}
.mnote .k{display:flex;align-items:center;gap:7px}
.sw{width:13px;height:13px;flex:none;background:var(--ink)}
.sw.g{background:transparent;border:1px dashed var(--rule-strong)}
.sw.v{background:repeating-linear-gradient(135deg,transparent,transparent 4px,var(--rule) 4px,var(--rule) 5px);border:1px solid var(--rule)}
@media (max-width:640px){
.mgrid{grid-template-columns:28px repeat(5,minmax(0,1fr))}
.mcell{min-height:52px;padding:4px}
.pin{font-size:8px;padding:1px 3px}
.rlab{min-height:52px}
}
/* ---------- methodology ---------- */
.verbs{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule)}
.verb{background:var(--surface);padding:18px 18px 20px}
.verb h4{font-family:var(--font-display);font-weight:750;font-size:15px;margin:0 0 7px;letter-spacing:-.01em}
.verb p{font-family:var(--font-display);font-size:12.5px;line-height:1.46;color:var(--ink-2);margin:0;max-width:none}
.verb .step{font-family:var(--font-mono);font-size:9.5px;letter-spacing:.13em;color:var(--brass);display:block;margin-bottom:9px}
/* ---------- questions ---------- */
.qs{display:flex;flex-direction:column;gap:0;border-top:1px solid var(--rule-strong)}
.q{display:grid;grid-template-columns:34px minmax(0,1fr) 170px;gap:18px;padding:16px 0;border-bottom:1px solid var(--rule);align-items:start}
@media (max-width:760px){.q{grid-template-columns:28px minmax(0,1fr);gap:12px}.q .owner{grid-column:2}}
.q .qn{font-family:var(--font-mono);font-size:11px;color:var(--brass);padding-top:3px}
.q .qt{font-family:var(--font-display);font-size:14px;line-height:1.48;color:var(--ink-2)}
.q .qt b{color:var(--ink);font-weight:700;display:block;margin-bottom:2px;font-size:14.5px}
.owner{font-family:var(--font-mono);font-size:10px;letter-spacing:.05em;color:var(--ink-3);padding-top:4px}
.owner .tag{display:inline-block;border:1px solid var(--rule-strong);padding:2px 7px;border-radius:2px}
.owner .tag.need{border-color:var(--clay);color:var(--clay)}
/* ---------- misc ---------- */
.numbers{font-family:var(--font-mono);font-size:12.5px;line-height:1.85;background:var(--surface);border-left:3px solid var(--l3);padding:16px 20px;margin:0 0 22px;overflow-x:auto;max-width:var(--measure)}
.numbers .v{color:var(--ink);font-weight:600}
.numbers .k{color:var(--ink-3)}
pre{font-family:var(--font-mono);font-size:12.5px;line-height:1.68;background:var(--surface);border-left:3px solid var(--rule-strong);padding:16px 20px;overflow-x:auto;margin:0 0 22px;max-width:var(--measure);color:var(--ink-2)}
.alt{border-bottom:1px solid var(--rule);padding:14px 0;max-width:var(--measure)}
.alt:last-of-type{border-bottom:none}
.alt b{font-family:var(--font-display);font-size:14px;display:block;margin-bottom:3px}
.alt p{font-size:14.5px;margin:0;color:var(--ink-2)}
.alt .verdict{font-family:var(--font-mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--clay)}
footer{border-top:2px solid var(--ink);margin-top:20px;padding-top:22px;font-family:var(--font-mono);font-size:11px;letter-spacing:.06em;color:var(--ink-3);display:flex;justify-content:space-between;gap:20px;flex-wrap:wrap}
.tm td,.tm th{text-align:center}
.tm td:first-child,.tm th:first-child{text-align:left}
.yes{color:var(--l4);font-weight:700}
.no{color:var(--clay);font-weight:700}
.kind{font-family:var(--font-mono);font-size:9px;letter-spacing:.09em;text-transform:uppercase;padding:2px 6px;border-radius:2px;white-space:nowrap;border:1px solid var(--rule-strong);color:var(--ink-3)}
.kind.adv{border-color:var(--clay);color:var(--clay)}
.routes{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:2px;background:var(--rule);border:1px solid var(--rule);margin:0 0 22px}
.route{background:var(--surface);padding:16px 18px}
.route h4{font-family:var(--font-display);font-weight:750;font-size:14px;margin:0 0 6px}
.route p{font-family:var(--font-display);font-size:12.5px;line-height:1.45;color:var(--ink-2);margin:0;max-width:none}
.route .tag{font-family:var(--font-mono);font-size:9px;letter-spacing:.1em;text-transform:uppercase;color:var(--brass);display:block;margin-bottom:8px}
a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-offset:3px}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
</style>
<div class="wrap"><header><div class="eyebrow"><span>state-hub-architecture</span> <span class="stat">proposed · draft-3</span> <span>state-hub</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>State Hub architecture</h1><p class="sub">Source: <code>state-hub · docs/architecture/state-hub_v0.1.md · da30ce6723f9c5e6fdd994c78bb646986e819d3f</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#about-this-document"><span class="n">·</span>About this document</a></li><li><a href="#s1"><span class="n">1</span>Introduction and Goals</a></li><li><a href="#s2"><span class="n">2</span>Architecture Constraints</a></li><li><a href="#s3"><span class="n">3</span>System Scope and Context</a></li><li><a href="#s4"><span class="n">4</span>Solution Strategy</a></li><li><a href="#s5"><span class="n">5</span>Building Block View</a></li><li><a href="#s6"><span class="n">6</span>Runtime View</a></li><li><a href="#s7"><span class="n">7</span>Deployment View</a></li><li><a href="#s8"><span class="n">8</span>Cross-Cutting Concepts</a></li><li><a href="#s9"><span class="n">9</span>Architecture Decisions</a></li><li><a href="#s10"><span class="n">10</span>Quality Requirements</a></li><li><a href="#s11"><span class="n">11</span>Risks and Technical Debt</a></li><li><a href="#s12"><span class="n">12</span>Glossary</a></li></ol></nav><main><section id="about-this-document"><h2>About this document</h2>
<p>First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.</p>
</section>
<section id="s1"><h2><span class="sn">01</span>Introduction and Goals</h2>
<p>State Hub is a queryable, auditable memory of work: domains, repos, workplans, tasks, decisions, progress. Files remain the origin. The hub is derived state (custodian ADR-001, ADR-003).</p>
<p>It remains operational until retirement gates in <code>prj-state-hub-retirement</code> are met. Replacement ownership is moving toward <code>repo-manager</code> and <code>hub-core</code>.</p>
<h3>1.1 Requirements Overview</h3>
<ul><li>Rebuild coordination state from registered repository files.</li><li>Deterministic UUIDv5 work-record identifiers (ADR-007). Any instance may reconcile the same repository; the canonical record id produces the same database key and writeback bytes on every instance.</li><li>Preserve compatibility; do not take new permanent architectural ownership.</li></ul>
<h3>1.2 Quality Goals</h3>
<ol><li>Rebuildability from git.</li><li>Hub never becomes the origin of work.</li><li>Extraction paths stay open.</li></ol>
<h3>1.3 Stakeholders</h3>
<div class="scroll"><table><thead><tr><th>Role</th><th>Concern</th></tr></thead><tbody><tr><td>state-hub</td><td>Live read-model during retirement.</td></tr><tr><td>the-custodian</td><td>Estate rules the hub must not invert.</td></tr><tr><td>repo-manager</td><td>Incoming consistency / repo representation.</td></tr><tr><td>product repos</td><td>Workplan files the hub indexes.</td></tr></tbody></table></div>
</section>
<section id="s2"><h2><span class="sn">02</span>Architecture Constraints</h2>
<p>N/A for this stub — retirement program is the binding constraint.</p>
</section>
<section id="s3"><h2><span class="sn">03</span>System Scope and Context</h2>
<p><strong>In:</strong> indexing workplans/tasks/decisions, consistency rebuild, query API and dashboard used today. <strong>Out:</strong> being the source of work items; new cross-domain capabilities; publication of policy (policy-nexus).</p>
<h3>3.1 Business Context</h3>
<p>Files are excellent for canon and provenance. The estate still needs a live query surface while retirement proceeds.</p>
<h3>3.2 Technical Context</h3>
<p>Inputs: workplan markdown via <code>fix-consistency</code>. Outputs: HTTP/MCP APIs. Neighbours: every registered repo, activity-core (ops runs), policy-nexus (does not index the hub).</p>
</section>
<section id="s4"><h2><span class="sn">04</span>Solution Strategy</h2>
<p>N/A for this stub. The strategy is already in the estate ADRs: files first, materialized derived state, single registrar, local cache vs authority (ADR-010, proposed).</p>
</section>
<section id="s5"><h2><span class="sn">05</span>Building Block View</h2>
<h3>5.1 Level 1 – System/Top-Level</h3>
<p>N/A for this stub.</p>
</section>
<section id="s6"><h2><span class="sn">06</span>Runtime View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s7"><h2><span class="sn">07</span>Deployment View</h2>
<p>N/A for this stub.</p>
</section>
<section id="s8"><h2><span class="sn">08</span>Cross-Cutting Concepts</h2>
<p>N/A for this stub.</p>
</section>
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
<p>Estate-wide binding decisions live in the-custodian and are listed on the estate map. Service-local implementation decisions live in <code>docs/adr/</code> and do not supersede the estate decisions:</p>
<div class="scroll"><table><thead><tr><th>Estate ADR</th><th>Status</th><th>Why it binds this system</th></tr></thead><tbody><tr><td><code>CUST-ADR-001</code></td><td>accepted</td><td>File-backed work originates in repositories; the Hub projects it. Published <code>/adr/custodian-workplans-as-repo-artefacts/v1/</code>.</td></tr><tr><td><code>CUST-ADR-003</code></td><td>accepted</td><td>How derived state invalidates; ADR-012 supplies commit provenance.</td></tr><tr><td><code>CUST-ADR-007</code></td><td>accepted</td><td>Namespace-aware identity and deterministic work-record UUIDs.</td></tr><tr><td><code>CUST-ADR-010</code></td><td>proposed</td><td>Two kinds of hub data.</td></tr><tr><td><code>CUST-ADR-011</code></td><td>proposed</td><td>Namespace and reconciliation limits.</td></tr><tr><td><code>CUST-ADR-012</code></td><td>accepted</td><td>Forge projection baseline and preliminary overlays.</td></tr></tbody></table></div>
<div class="scroll"><table><thead><tr><th>Local ADR</th><th>Status</th><th>Scope</th></tr></thead><tbody><tr><td><code>STATE-ADR-001</code></td><td>accepted</td><td>Repository identity and recovery contract for canonical-name changes.</td></tr></tbody></table></div>
<p>Do not treat a State Hub <code>/decisions</code> row as the published ADR.</p>
</section>
<section id="s10"><h2><span class="sn">10</span>Quality Requirements</h2>
<p>N/A for this stub.</p>
</section>
<section id="s11"><h2><span class="sn">11</span>Risks and Technical Debt</h2>
<p>N/A for this stub. Residual: this workstation cannot mint registrar UUIDs.</p>
</section>
<section id="s12"><h2><span class="sn">12</span>Glossary</h2>
<div class="scroll"><table><thead><tr><th>Term</th><th>Meaning</th></tr></thead><tbody><tr><td>Read model</td><td>Derived index; never the origin.</td></tr><tr><td>Registrar</td><td>The single instance allowed to mint workplan UUIDs.</td></tr><tr><td>Retirement</td><td>Coordinated move of capabilities out of this repo.</td></tr></tbody></table></div>
</section><footer><span>state-hub-architecture · draft-3 · proposed</span><span>state-hub · docs/architecture/state-hub_v0.1.md · da30ce6723f9c5e6fdd994c78bb646986e819d3f</span></footer></main></div></div></html>

1230
docs/evidence/2026-10-11-served-publication-history/publication-manifest.json Normal file
View file

File diff suppressed because it is too large Load diff

1017
docs/evidence/2026-10-11-served-publication-history/receipt.json Normal file
View file

File diff suppressed because it is too large Load diff

1
docs/evidence/2026-10-11-served-publication-history/source-verification-errors.json Normal file
View file

@ -0,0 +1 @@
[]

191
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-001.md Normal file
View file

@ -0,0 +1,191 @@
---
id: ACT-ADR-001
type: architecture-decision-record
title: "Activity-Core as Coulomb Org Event Bridge"
status: accepted
owner: activity-core
revision: "accepted-2"
last_reviewed: "2026-05-14"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-05-14"
scope: cross-repo
affects:
- activity-core
- the-custodian/state-hub
- issue-facade (→ issue-core)
- repo-scoping
tags: ["architecture", "event-bridge", "activity-core", "orchestration", "event-loop"]
---
# ACT-ADR-001: Activity-Core as Coulomb Org Event Bridge
## Status
Accepted.
## Context
The Coulomb organization's set of repositories, services, and deployments is growing
beyond what a single person can coordinate manually. The state hub tracks cross-domain
state but has no mechanism to automatically respond to it. Recurring maintenance
(dependency scans, SBOM staleness checks, consistency audits) is implemented as
bespoke cron jobs baked into individual services — scattered, hard to audit, and
impossible to govern from a single vantage point.
Three forces drive the need for a dedicated orchestration layer:
1. **Scale**: as the repo count grows, manual coordination becomes the bottleneck.
2. **Reactivity**: org-level events (new repo registered, CVE published, deployment
completed) should trigger coordinated responses without human intervention.
3. **Separation of concerns**: the state hub is a read model and should remain one.
It must not accumulate automation logic to avoid becoming a God object.
## Decision
**activity-core is the org-wide Event Bridge for the Coulomb organization.**
Its responsibility is exactly three things:
1. **Receive events** — time-based (cron, one-off scheduled) and domain events (NATS,
Gitea webhooks, state hub lifecycle signals).
2. **Evaluate rules and instructions** — given event payload and resolved context,
determine what work must be created.
3. **Emit task sets** — publish structured task creation requests to issue-core.
It does not execute work. It does not track task lifecycle. It does not manage projects.
### Boundary rules
| Concern | Owner |
|---|---|
| Cross-org task scheduling and reactive automation | **activity-core** |
| Task lifecycle (create, assign, track, close) | **issue-core** |
| Project and initiative management (phased, completion-gated) | **project-core** (future) |
| Repository capability profiling | **repo-scoping** |
| Cross-domain coordination state | **state hub** |
| Execution of automatable tasks | Temporal workers (per-repo) |
### Event type registry
Event types are declared by publishers as markdown definition files (see ACT-ADR-002).
Governance is **publisher-declared by default**: a publisher registers its event types
by committing definition files to the event-types registry. In production environments,
a curator gate can be enabled — registry entries must be reviewed before the runtime
accepts events of that type. This is a configuration flag per runtime scope (dev,
staging, prod), not a hard-coded rule.
### State hub relationship
The state hub **delegates automation to activity-core** rather than implementing it
internally. Concretely:
- Maintenance jobs currently baked into the state hub (consistency sync, SBOM
staleness checks) are migrated to ActivityDefinitions in activity-core.
- The state hub becomes a **publisher** of lifecycle events on NATS
(`org.workstream.created`, `org.decision.resolved`, `org.repo.registered`, etc.).
- The state hub does not subscribe to activity-core's output directly; it reads
task state from issue-core when needed.
This preserves the state hub as a read model and makes activity-core the single
home for automation policy.
### rules-core: module-first
The rule and instruction evaluation engine starts as `src/activity_core/rules/` — a
module with a clean internal boundary (no imports from Temporal, Postgres, or FastAPI
within the module). Extraction to a standalone `rules-core` repository happens when a
**second consumer** (e.g. state hub governance, project-core) needs the engine. This
follows the same discipline as the task-flow-engine extraction plan (CUST-TFE-SCOPE).
### NATS as org infrastructure
NATS JetStream is promoted from an activity-core internal component to **org-wide
event bus infrastructure**. It runs as a standalone service (not bundled in
activity-core's docker-compose) with its own lifecycle. All services that publish
or subscribe to org events do so via NATS streams.
### issue-core integration
activity-core communicates with issue-core via a **task emission adapter** — an
abstraction layer that, in the initial implementation, calls issue-core's REST API.
The adapter interface is defined now; the transport can migrate to NATS subscription
(issue-core subscribes to `task.spawned` events) once issue-core adds that capability.
This avoids hardcoding REST coupling throughout the codebase.
### Webhook receiver
A new HTTP endpoint within activity-core accepts inbound webhooks from Gitea (and
later GitHub, other services). It normalises payloads to the canonical EventEnvelope
format, validates against the event type registry, and publishes to NATS. This runs
alongside the existing FastAPI `api.py`.
### Domain assignment
activity-core and issue-core are assigned to the **`capabilities`** domain — the
same domain as repo-scoping. These are org-wide infrastructure tools that serve all
domains equally, not artefacts of any single project or custodian's personal workflow.
issue-core is explicitly disassociated from the markitect domain.
## Trigger types
Three trigger types are supported:
| Type | Description | Temporal mechanism |
|---|---|---|
| `cron` | Recurring schedule (5-field cron + timezone + misfire policy) | Temporal Schedule (implemented WP-0002) |
| `event` | React to a named event type on NATS | Temporal workflow started by Event Router |
| `scheduled` | One-off at a future datetime | Temporal Schedule with `remaining_actions: 1` |
`scheduled` is a new trigger type added in WP-0003.
## Consequences
### Immediate
- activity-core's `INTENT.md` and `SCOPE.md` are rewritten to reflect this architecture.
- `task_spawn_log` is the local **spawn audit trail**; authoritative work-item
lifecycle state lives downstream.
- A task emission adapter (`src/activity_core/issue_sink.py`) owns downstream
creation. The unused `TaskExecutorWorkflow` and `task_instances` compatibility
surface was retired by ACTIVITY-WP-0035.
### Medium term
- State hub adds NATS publishing to its lifecycle operations.
- Gitea webhook receiver added to activity-core as a new HTTP router.
- Existing state hub maintenance crons are migrated to ActivityDefinitions.
- issue-facade is renamed issue-core and re-registered under the `capabilities` domain.
### Long term
- rules-core extracted as a standalone package when a second consumer appears.
- project-core created (depends on task-flow-engine extraction) for multi-phase
initiative management — explicitly out of scope for activity-core.
- NATS gets its own operational runbook and monitoring as org infrastructure.
## Alternatives Considered
**State hub absorbs activity-core functionality**: rejected — turns the state hub into
a God object, violates the read-model boundary, and makes automation logic impossible
to test independently.
**Per-repo automation (GitHub Actions style)**: rejected — cross-repo coordination
requires a single vantage point that can see all repos; per-repo actions can't express
org-level triggers or context.
**Activity-core as a thin Temporal wrapper only**: rejected — without the event type
registry and rule model, it's just a scheduler. The governance and introspection
properties are the point.
**Separate rules-core from day one**: rejected — premature extraction adds dependency
management overhead before a second consumer exists. Module-first with a clean boundary
costs nothing and preserves the extraction option.
## Related
- ACT-ADR-002 — Event type and ActivityDefinition definition format
- ACT-ADR-003 — Rule vs. Instruction model and DSL
- CUST-ADR-001 — Workplans as repository artefacts (canon/architecture/)
- CUST-TFE-SCOPE-2026-000001 — task-flow-engine extraction plan (canon/projects/)
- activity-core INTENT.md (to be written)
- activity-core WP-0003 (to be written)

360
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-002.md Normal file
View file

@ -0,0 +1,360 @@
---
id: ACT-ADR-002
type: architecture-decision-record
title: "Markdown-as-Definition Format for Event Types and ActivityDefinitions"
status: accepted
owner: activity-core
revision: "accepted-2"
last_reviewed: "2026-05-14"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-05-14"
scope: cross-repo
affects:
- activity-core
- any event publisher registering event types
tags: ["architecture", "format", "event-type", "activity-definition", "markdown", "documentation"]
---
# ACT-ADR-002: Markdown-as-Definition Format
## Status
Accepted.
## Context
Event type schemas and ActivityDefinition rules need to be understood and authored
by three distinct audiences simultaneously: humans reviewing and debugging automation,
agents creating and modifying definitions at runtime, and machines parsing and
evaluating them. Traditional approaches split these concerns — schemas go in JSON
Schema or YAML, documentation goes in a wiki, logic goes in code — and they drift
apart. A bug in a rule requires cross-referencing three places to understand intent,
check the schema, and read the condition.
The Custodian ecosystem already uses markdown files with YAML frontmatter as the
authoritative format for workplans, ADRs, SCOPE.md, and INTENT.md — all understood
by humans and agents without additional tooling. The same pattern should apply here.
## Decision
**Event type definitions and ActivityDefinitions are markdown files** where machine-
parseable structure (frontmatter YAML and fenced definition blocks) is embedded within
human-readable narrative. Intent, schema, logic, and debugging notes live in one file.
### Event Type Definition Files
**Location**: `event-types/{namespace}.{event-name}.md` within the activity-core repo
(or a registered event-types registry repo if volumes justify separation).
**Naming convention**: `{publisher-domain}.{noun}.{verb}.md`, e.g.:
- `org.repo.registered.md`
- `org.security.cve.published.md`
- `org.workstream.completed.md`
**Structure**:
```markdown
---
id: org.repo.registered
type: event-type
version: "1.0"
publisher: the-custodian/state-hub
governance: publisher-declared # publisher-declared | curated
status: active # active | deprecated | draft
introduced: "2026-05-14"
---
# Event: org.repo.registered
## Intent
One-paragraph statement of why this event exists and what it signals.
Written for an agent or human who has never seen it before.
## When Published
Bulleted list of the exact conditions under which the publisher fires this event.
Be precise — ambiguity here causes missed or duplicate activations.
## Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
| `repo_slug` | string | yes | URL-safe repository identifier |
| `domain` | string | yes | Domain slug the repo is assigned to |
| `tags` | string[] | no | Capability tags set at registration time |
| `registered_at` | datetime | yes | ISO 8601 UTC timestamp |
## Example Payload
​```json
{
"id": "evt-7f3a1b2c",
"type": "org.repo.registered",
"version": "1.0",
"timestamp": "2026-05-14T10:00:00Z",
"publisher": "the-custodian/state-hub",
"attributes": {
"repo_slug": "new-python-service",
"domain": "railiance",
"tags": ["python-service", "fastapi"],
"registered_at": "2026-05-14T10:00:00Z"
}
}
​```
## Consumer Notes
Guidance for agents and humans writing rules against this event type:
- Which attributes are safe for instruction prompts (trusted fields)
- Common misuses or gotchas
- Related events that are often used together
## Debugging
What to check when an activity that subscribes to this event does not fire:
- How to verify the event was published (NATS subject, log entry)
- How to inspect the event payload in the registry
- Common schema validation failures
```
### Attribute Types
The type system for event attributes is intentionally small:
| Type | Notes |
|---|---|
| `string` | UTF-8 string |
| `integer` | 64-bit signed integer |
| `float` | 64-bit float |
| `boolean` | true / false |
| `datetime` | ISO 8601 UTC string in payload, parsed to datetime in evaluator |
| `uuid` | String in payload, validated as UUID v4 |
| `string[]` | JSON array of strings |
| `integer[]` | JSON array of integers |
| `object` | Freeform JSON object — cannot be used in rule conditions; instruction-only |
`object` type attributes are available to instructions but excluded from rule
conditions deliberately — rules must be deterministic and schema-validatable.
### ActivityDefinition Files
**Location**: `activity-definitions/{slug}.md` within the repo that owns the automation.
For org-wide automations: `activity-core/activity-definitions/`.
For domain-specific automations: `{domain-repo}/activity-definitions/`.
**Structure**:
```markdown
---
id: ACT-DEF-onboard-python-repo
type: activity-definition
version: "1.0"
status: active
trigger:
type: event # event | cron | scheduled
event_type: org.repo.registered # for type: event
# cron: "0 9 * * 1" # for type: cron (5-field, UTC)
# timezone: "Europe/Berlin" # optional, cron only
# misfire_policy: skip # skip | catchup | compress (cron only)
# at: "2026-06-01T09:00:00Z" # for type: scheduled (one-off)
context_sources:
- type: repo-scoping
query: repo_profile
bind_to: context.repo_profile
- type: state-hub
query: domain_summary
bind_to: context.domain_summary
governance: publisher-declared
owner: custodian-agent
created: "2026-05-14"
---
# ActivityDefinition: Onboard New Python Service
## Purpose
One paragraph. What does this automation do and why does it exist? What problem
would accumulate if this automation were turned off?
## Trigger
Which event type fires this activity, and under what conditions does it apply?
Cross-reference the event type definition file.
## Context Sources
What context is resolved before rules are evaluated? Explain what each source
provides and why it is needed.
## Rules
Each rule is a fenced block tagged `rule`. Rules are evaluated in order; all
matching rules fire (not first-match-only). See ACT-ADR-003 for the expression
language specification.
​```rule
id: create-sbom-scan
condition: '"python-service" in event.attributes.tags'
action:
task_template: tasks/sbom-initial-scan.md
target_repo: event.attributes.repo_slug
priority: high
labels: ["onboarding", "security"]
​```
​```rule
id: create-scope-generation
condition: '"python-service" in event.attributes.tags and context.repo_profile.scope_md_exists == false'
action:
task_template: tasks/generate-scope-md.md
target_repo: event.attributes.repo_slug
priority: medium
labels: ["onboarding", "documentation"]
​```
## Instructions
Instructions are evaluated after all rules. An instruction asks an LLM to decide
what additional tasks (if any) to create. See ACT-ADR-003 for safety requirements.
​```instruction
id: domain-specific-onboarding
condition: 'event.attributes.domain != "test_domain_v2"'
trusted_fields:
- event.attributes.repo_slug
- event.attributes.domain
- event.attributes.tags
model: claude-sonnet-4-6
review_advisory: false
prompt: |
A new repository has been registered in the Coulomb organization.
Repository: {event.attributes.repo_slug}
Domain: {event.attributes.domain}
Tags: {event.attributes.tags}
Based on the domain's current standards and the repository profile above,
determine what additional domain-specific onboarding tasks should be created
beyond the standard SBOM scan and SCOPE.md generation. Return an empty list
if no additional tasks are warranted.
output_schema: tasks/task-template-list-schema.json
​```
## Task Templates
References to task template files used in rule actions. Each template is a
separate markdown file under `tasks/` that defines the task title, description
template, default labels, and default assignee logic.
- `tasks/sbom-initial-scan.md`
- `tasks/generate-scope-md.md`
## Notes
Operational notes, edge cases, and context that does not fit elsewhere.
## Debugging
Checklist for when this ActivityDefinition fires but produces unexpected output:
1. Was the triggering event published with the correct type and attributes?
2. Do the rule conditions evaluate as expected? (Use `make eval-rule` with a fixture)
3. Is issue-core reachable and configured for the target domain?
4. For instructions: check the audit log for the model response and output validation result.
## Change History
- v1.0 (2026-05-14): Initial definition
```
### Governance model
The `governance` field on an event type definition determines how the registry
runtime handles it:
| Value | Behaviour |
|---|---|
| `publisher-declared` | Accepted immediately on publish; no review required |
| `curated` | Held in `pending` state until a curator approves via registry API |
The runtime checks the **environment's curator gate configuration** — not just the
file's governance field. An environment configured with `curator_gate: disabled`
treats all event types as `publisher-declared` regardless of the field value.
An environment with `curator_gate: required` treats all event types as `curated`
regardless of the field value. The field is the publisher's declared preference;
the environment config is the enforcement point.
This means:
- **Dev / integration**: `curator_gate: disabled` — developers and agents iterate
freely; new event types take effect immediately.
- **Staging / production**: `curator_gate: required` — all new event types queue
for curator review before the runtime accepts events of that type.
### File as source of truth
Following CUST-ADR-001 (Workplans as Repository Artefacts), definition files are
the canonical source of truth. The activity-core runtime indexes them into its
database on startup and via a sync command. The database is a queryable cache,
not the origin. A definition deleted from the filesystem is disabled at next sync.
### Task Templates
Task templates are separate markdown files (`tasks/{slug}.md`) referenced from
ActivityDefinition action blocks. They define:
```markdown
---
id: tasks/sbom-initial-scan
type: task-template
---
# Task: Run Initial SBOM Scan
## Title template
`Run SBOM scan — {target_repo}`
## Description template
Initial SBOM scan required for newly registered repository `{target_repo}`.
Run: `make ingest-sbom REPO={target_repo} SCAN=1`
## Default labels
["sbom", "security", "automated"]
## Default assignee
None (unassigned)
```
This keeps task content editable separately from the routing logic in
ActivityDefinitions.
## Consequences
- A new `event-types/` directory in activity-core (and eventually a shared registry)
holds all org event type definitions.
- A new `activity-definitions/` directory in activity-core holds org-wide automations.
- Domain repos may hold their own `activity-definitions/` for domain-specific
automations, scanned by activity-core at sync time.
- The runtime requires a parser for the `rule` and `instruction` fenced blocks.
- SCOPE.md for activity-core must be updated to list these directories.
## Alternatives Considered
**Pure JSON Schema for event types, separate wiki for docs**: rejected — documentation
and schema diverge immediately; agents must cross-reference two systems to author
a rule correctly.
**OpenAPI / AsyncAPI specification**: rejected — those formats are excellent for
API and broker documentation but not designed for co-locating operational intent
and debugging guidance. They are also less readable for non-specialists.
**Code-only (Python dataclasses for event schemas, Python functions for rules)**:
rejected — requires code deployment for any definition change; agents cannot modify
definitions without write access to the codebase; non-technical stakeholders cannot
review or understand automation policies.
## Related
- ACT-ADR-001 — Event Bridge Architecture
- ACT-ADR-003 — Rule vs. Instruction model and DSL
- CUST-ADR-001 — Workplans as repository artefacts

342
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-003.md Normal file
View file

@ -0,0 +1,342 @@
---
id: ACT-ADR-003
type: architecture-decision-record
title: "Rule vs. Instruction Model and Expression DSL"
status: accepted
owner: activity-core
revision: "accepted-2"
last_reviewed: "2026-05-14"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-05-14"
scope: cross-repo
affects:
- activity-core
- rules-core (future extraction)
tags: ["architecture", "rules", "instructions", "dsl", "llm", "safety", "evaluation"]
---
# ACT-ADR-003: Rule vs. Instruction Model and Expression DSL
## Status
Accepted.
## Context
ActivityDefinitions need two distinct evaluation modes to cover the full range
of automation scenarios in the Coulomb org:
**Deterministic cases**: "if this repo has tag `python-service` AND has no SBOM
in the last 30 days, create a scan task." The condition is fully expressible as a
boolean predicate over known attributes. The output is fixed by the template. No
ambiguity, no LLM required, fully testable.
**Judgement cases**: "a new repository has been registered — based on its domain
and profile, determine what domain-specific onboarding tasks are appropriate." The
right answer depends on context that is expensive to encode as explicit rules. An
LLM is a better evaluator than a rule tree, but introduces non-determinism, cost,
and a new attack surface (prompt injection via event payload).
Conflating these two modes into one mechanism produces a system that is either
too rigid (rules only) or too unpredictable (LLM everywhere). The two modes
need different evaluation pipelines, testing strategies, and audit trails.
## Decision
**Two named, distinct evaluation modes: Rule and Instruction.**
Terminology is deliberate. A **Rule** is deterministic and mechanical — it applies
or it does not. An **Instruction** is contextual and interpretive — it guides an
LLM agent to make a judgement call. Both are expressed as fenced blocks in
ActivityDefinition markdown files (see ACT-ADR-002).
### Rules
A Rule has two parts: a **condition** (boolean predicate) and one or more
**actions** (task template references).
#### Condition expression language
The condition is a single-line string expression evaluated by a sandboxed
AST walker — never `exec()` or `eval()`. The evaluator walks the parsed AST
and whitelist-checks every node type before executing. Unknown node types
raise an `UnsafeExpression` error at parse time, not at evaluation time.
**Available operations**:
| Category | Syntax | Example |
|---|---|---|
| Equality | `==`, `!=` | `event.type == "org.repo.registered"` |
| Comparison | `>`, `<`, `>=`, `<=` | `event.attributes.sbom_age_days > 30` |
| Membership | `in`, `not in` | `"python-service" in event.attributes.tags` |
| Boolean | `and`, `or`, `not` | `a and (b or not c)` |
| Grouping | `( )` | `(a or b) and c` |
| Length | `len(x)` | `len(event.attributes.affected_repos) > 0` |
| Existence | `x is None`, `x is not None` | `event.attributes.domain is not None` |
**Attribute access** follows dot notation on the `event` object and the `context`
object (populated by context sources declared in the ActivityDefinition):
- `event.id` — UUID string
- `event.type` — event type identifier
- `event.version` — event type version
- `event.timestamp` — ISO 8601 datetime string
- `event.publisher` — publisher identifier
- `event.attributes.{name}` — typed attribute per event type schema
- `context.{source}.{field}` — resolved context data
**Explicitly forbidden** (evaluator rejects at parse time):
- Function calls other than `len()` and `None` tests
- Attribute access on arbitrary Python objects
- String interpolation or formatting
- Any control flow (`if`, `for`, `while`, `lambda`)
- Import statements
- Assignments
**Design rationale**: the expression language is intentionally small. Anything
complex enough to need more than this belongs in an Instruction, not a Rule.
When a rule condition becomes difficult to express, that is a signal that the
case requires LLM judgement, not a signal that the DSL needs more features.
#### Actions
A Rule's action block specifies:
```yaml
action:
task_template: "Run SBOM rescan for {context.repo.repo_slug}"
target_repo: context.repo.repo_slug
priority: medium
labels: ["sbom", "security", "{context.repo.repo_slug}"]
due_in_days: 7
```
`action.task_template` is the emitted task title template. It is not a path to a
repo-local file. Older design notes and the legacy `tasks/*.md` directory use
"task template" for materialized task-body templates; that is a separate legacy
surface. To avoid surprise, new rule actions should treat `task_template` as
`title_template` semantics until the field can be renamed in a schema-breaking
revision.
Action fields accept two deterministic rendering forms:
- Whole-field paths: if the whole string is a path like
`context.repo.repo_slug` or `event.attributes.repo_slug`, the rendered value
keeps the original scalar/list/object shape from that path. This is the
correct form for `target_repo` and other fields that should not become prose.
- Scalar placeholders: strings may include `{context.foo}` or `{event.foo}`
placeholders. Each placeholder must resolve to a scalar. Lists and objects are
rejected rather than stringified, which prevents accidental JSON blobs or
untrusted text from being embedded into task titles.
Unsafe action cases are rejected:
- Any action path outside `context.*` or `event.*`.
- Any path containing calls, indexing, arithmetic, filters, or boolean logic.
- Placeholder values that resolve to lists or objects.
- `for_each` values that are not a whole-field `context.*` or `event.*` path to
a list.
- `bind_as` names that are not simple identifiers.
Per-item rule expansion is explicit:
```yaml
for_each: context.repos.repos
bind_as: repo
condition: 'context.repo.sbom_age_days > 30'
action:
task_template: Run SBOM rescan for {context.repo.repo_slug}
target_repo: context.repo.repo_slug
priority: medium
labels: ["sbom", "security", "automated"]
```
The weekly SBOM staleness definition is the canonical pattern. The State Hub
bulk resolver exposes all repository entries at `context.repos.repos`, the rule
binds each item as `context.repo`, and the strict staleness definition is
`context.repo.sbom_age_days > 30`. Thirty days exactly is not stale; thirty-one
days is stale.
#### Evaluation semantics
- All rules in an ActivityDefinition are evaluated; **all matching rules fire**
(not first-match-only). There is no implicit ordering beyond the file order,
which is documented in the ActivityDefinition for human clarity.
- A rule whose condition raises an error during evaluation is skipped and logged
as `rule_error`; other rules still fire. This prevents a single malformed rule
from silencing an entire ActivityDefinition.
- An empty condition (omitted `condition` field) evaluates to `true` — the rule
always fires when the trigger fires.
### Instructions
An Instruction defers the task-creation decision to an LLM. It specifies what
context to provide, how to frame the prompt, and what output schema to enforce.
#### Structure
```yaml
# in an instruction fenced block:
id: {slug}
condition: '{expression}' # optional pre-filter (Rule DSL); runs before LLM
trusted_fields: # REQUIRED — explicit allowlist of payload fields
- event.attributes.repo_slug # safe to interpolate into prompt
- event.attributes.domain
- event.attributes.tags
model: claude-sonnet-4-6
review_advisory: false # true | false — advisory evidence, not a gate
prompt: |
{prompt template — only trusted_fields may be interpolated}
output_schema: {path to JSON schema file}
```
#### Trusted fields and prompt injection protection
The `trusted_fields` list is **required** and enforced at parse time. Any field
not listed is unavailable to the prompt template. The template engine raises
`UntrustedFieldError` if the prompt references a field not in `trusted_fields`.
The rationale: event payloads may contain free-text from untrusted sources —
commit messages, issue titles, CVE descriptions, repo descriptions. Interpolating
these directly into a prompt creates a prompt injection surface. Trusted fields
are those whose values are validated by the event type schema (typed attributes
like slugs, domain names, tag lists) and cannot carry arbitrary instruction text
by construction.
Fields of type `object` (freeform JSON) are **never eligible** for `trusted_fields`
even if listed — the evaluator rejects this at parse time.
#### Output schema enforcement
The LLM response is validated against `output_schema` using JSON Schema validation.
If validation fails, the instruction retries once with the schema error appended
to the prompt. If the second attempt also fails, the instruction records an
`instruction_output_error` audit event and emits no tasks. Tasks are **never
created from unvalidated output**.
Structured output mode (tool_use / JSON mode) is used where the model supports
it. The output schema must define `List[TaskSpec]` or a compatible envelope.
#### `review_advisory: true`
ACTIVITY-WP-0035 selected advisory-only semantics because no downstream owner
currently exposes an acknowledged proposal/decision/release contract. The
instruction's task/report evidence is marked `review_advisory=true` and
`review_gate_applied=false` so an operator can distinguish review-worthy output
without interpreting it as held for approval.
The legacy input name `review_required` is accepted during migration and
normalized to `review_advisory`; new definitions must not use it. activity-core
does **not** route proposals to a pending-review queue and does not own review
lifecycle state. A future hold/release design requires a named downstream owner,
an idempotent release reference, an ADR update, and fail-closed emission tests.
#### Evaluation semantics
- Instructions are evaluated **after** all rules in the ActivityDefinition.
- The optional `condition` field on an instruction uses the same Rule DSL as
a first-pass filter — if the condition is false, the LLM is not called.
This avoids LLM cost for events that clearly do not need instruction judgement.
- Instructions are **not** first-match-only; all instructions whose conditions
pass fire. An ActivityDefinition may have zero instructions.
### Audit trail
Every task emission records:
| Field | Rule | Instruction |
|---|---|---|
| `source_type` | `"rule"` | `"instruction"` |
| `source_id` | rule `id` from definition | instruction `id` from definition |
| `source_version` | ActivityDefinition version | ActivityDefinition version |
| `triggering_event_id` | event UUID | event UUID |
| `condition_matched` | expression string | expression string (pre-filter) |
| `prompt_hash` | — | SHA-256 of rendered prompt |
| `model` | — | model ID used |
| `output_validated` | — | `true` / `false` |
| `review_advisory` | — | `true` / `false`; no gate applied |
The audit trail is written to the `task_spawn_log` table in activity-core's database
and referenced from the task record in issue-core.
The rendered prompt and provider response are deliberately not persisted. The
prompt hash proves equality when an authorized operator can reconstruct the
same input, but the audit contract does not promise reconstruction after source
definitions or upstream event retention have changed. `activity_runs` retains
the definition version and bounded context snapshot; reports may retain
allowlisted route/usage metadata. Prompts, messages, tool output, credential
fields, and provider blobs are excluded from run, progress, and public API
evidence.
### Testing strategy
**Rules**: every rule can and should be unit-tested with fixture event payloads.
A test helper `evaluate_rule(condition_str, event_fixture)` returns `bool` and
raises on syntax errors. Tests live alongside ActivityDefinition files:
`activity-definitions/{slug}.test.json` — a list of `{event, expected_rules_fired}`
fixtures.
**Instructions**: instructions cannot be deterministically unit-tested. Instead:
- Sample evaluations are collected: given a fixture event, record the LLM response.
- Samples are committed to `activity-definitions/{slug}.samples/` for human review.
- Output schema validation is unit-tested independently of the LLM call.
- Prompt injection resistance is tested by including injection strings in fixture
event payloads and asserting they do not appear in the rendered prompt.
### rules-core module boundary
The rule evaluator and instruction executor live in `src/activity_core/rules/`.
Within this module:
- **No imports from** `temporalio`, `sqlalchemy`, `fastapi`, or any activity-core
application code.
- Public surface: `evaluate_condition(expr: str, event: EventEnvelope, context: dict) -> bool`
and `execute_instruction(instr: InstructionDef, event: EventEnvelope, context: dict) -> List[TaskSpec]`.
- The module is independently importable and testable without starting the Temporal
worker or Postgres.
This boundary makes future extraction to `rules-core` a packaging exercise, not a refactor.
## Consequences
- The `ActivityDefinition` Pydantic model gains `rules: List[RuleDef]` and
`instructions: List[InstructionDef]` fields. The current implicit "always create
tasks" behaviour is replaced by explicit rule blocks.
- A new `RuleEvaluator` class (AST walker) is added to `src/activity_core/rules/`.
- A new `InstructionExecutor` class handles prompt rendering, LLM call, output
validation, and review-required audit metadata. Pending review queue routing
remains a future issue-core integration.
- Integration tests for rule evaluation use fixture JSON; no running Temporal required.
- The `task_spawn_log` table is added to the Postgres schema (new Alembic migration).
- ActivityDefinition files that omit both `rules` and `instructions` are valid
(they fire with no output) — this supports future placeholder definitions.
## Alternatives Considered
**OPA / Rego for rule conditions**: powerful, well-established policy language,
supports complex logic. Rejected — Rego's learning curve is high for non-specialists;
agents rarely produce correct Rego without fine-tuning; it adds a runtime dependency.
The simple AST-walker DSL covers the realistic condition complexity for this org.
**Rules as Python lambdas**: maximum expressiveness. Rejected — arbitrary code
execution in a rule condition is a serious security surface, especially in an
org-wide event loop. Code deployment required for any rule change; agents cannot
write rules without code write access.
**LLM for all conditions (no Rule/Instruction split)**: simpler model, more
flexible. Rejected — non-deterministic for cases that are deterministic; expensive
for high-frequency events like cron ticks; impossible to unit-test; audit trail
for deterministic rules becomes murky.
**Instructions only, no Rules**: allows arbitrary LLM judgement for everything.
Rejected — LLM cost for every event, latency, and non-determinism are unacceptable
for high-frequency maintenance automations. Many cases (SBOM staleness check,
tag-based routing) are fully deterministic and should stay that way.
## Related
- ACT-ADR-001 — Event Bridge Architecture
- ACT-ADR-002 — Definition format (where rule/instruction blocks live)
- CUST-TFE-SCOPE-2026-000001 — task-flow-engine extraction (analogue pattern)
- `src/activity_core/rules/` — implementation home

160
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-004.md Normal file
View file

@ -0,0 +1,160 @@
---
id: ACT-ADR-004
type: architecture-decision-record
title: "The Producer Trust Boundary — Guardrails and Error-Correction for Untrusted Output"
status: accepted
owner: activity-core
revision: "accepted-2"
last_reviewed: "2026-06-26"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-06-26"
scope: cross-repo
affects:
- activity-core
- rules-core (future extraction)
tags: ["architecture", "llm", "safety", "validation", "guardrails", "trust-boundary", "resilience"]
---
# ACT-ADR-004: The Producer Trust Boundary
## Status
Accepted.
## Context
On 2026-06-26 the scheduled daily WSJF triage instruction fired on time, called
llm-connect successfully, and produced a long ranked recommendation list — but
the JSON broke at char 5268 (~rank 8–9 of ~16), failing schema validation. Because
the report was validated and consumed as a single monolithic JSON document, one
malformed delimiter discarded the **entire** run, including the 7 perfectly good
recommendations the model had already emitted. The scheduling and runtime layers
were healthy; the failure was entirely at the seam where free-form model output
meets a strict consumer.
This is not a one-off bug, it is a recurring class. activity-core has a **trust
boundary** wherever generative or human-authored output meets strict deterministic
consumers: the JSON Schema validator, the task emitter, and any classic compute
pipeline downstream. The producers on the other side of that boundary — **LLMs,
agents, and humans** — are all *untrusted producers*. Their output may be:
- **erroneous** — hallucination, truncation at a token limit, drift, type slips,
typos, a missing delimiter; or
- **malicious** — prompt injection, crafted payloads, or oversized / deeply-nested
structures intended to exhaust or confuse the consumer.
The pre-existing design treated producer output optimistically: parse the whole
document, validate the whole document, and on any failure discard the whole
document (preserving only a bounded diagnostic preview). That gives **zero error
locality** — the blast radius of any single defect is the entire activation.
## Decision
Treat the producer→consumer seam as an explicit, adversarial **trust boundary**,
and place guardrails plus error-correction tooling *at that boundary* rather than
letting raw producer output flow into deterministic consumers.
### Two non-fail-fast postures
When hard-failing on a problem is undesirable, there are two sound strategies, and
they **compose**:
- **A) Trust but handle exceptions** (optimistic / reactive). Consume the output
as-is; on exception, catch → repair → retry → or quarantine. Cheap on the happy
path; blast radius depends entirely on how granular the catch is. Best when
failures are rare and locally recoverable. Risk: failures surface late, possibly
after partial side effects.
- **B) Verify and mitigate** (defensive / proactive). Validate, sanitize, clamp,
and normalize the output to a known-good shape *before* it enters the pipeline —
drop bad items, coerce types, bound sizes/depth, allow-list references — so the
consumer only ever sees clean input. Higher upfront cost, smaller blast radius,
no partial side effects. Best when failures are common or consequences are high.
### Governing principles
1. **Push verification to the boundary; keep the interior strict.** Apply posture
**B** at the producer→consumer boundary; keep posture **A** for residual
exceptions inside the verified core. Never relax the interior schema to absorb
producer sloppiness.
2. **Make error locality match the unit of work.** One bad recommendation must
cost one recommendation, not the whole report. Structuring the payload so each
item is independently parseable and validatable is the highest-leverage change.
3. **Quarantine, never silently drop.** Invalid units are preserved as bounded,
provenance-tagged artifacts (`index`, `error`, `raw` snippet, `reason`) so they
can be debugged or replayed. Degraded-but-usable is reported distinctly from
total loss.
4. **Both human and agent input get the same rigor.** Guardrails are
producer-agnostic: the same count / length / depth caps and reference
allow-lists apply whether the producer is an LLM, an agent, or a human.
### What this means concretely in activity-core
Implemented in `src/activity_core/rules/executor.py`:
- **Strict-structure-only schema.** The daily-triage output schema is strict on
per-item *structure* (`required [rank, candidate, action, why]`, typed `wsjf`)
and carries `maxItems` as a producer *hint* — never as a hard whole-document
reject, which would reproduce the very blast-radius failure (ACT-ADR-002 governs
the schema format; `schemas/daily-triage-report.json`).
- **Item-granular recovery (posture B).** When whole-document parse + one retry
fail, `_resilient_report` recovers individually-parseable recommendation objects
via a brace/quote-aware scanner (`_extract_object_spans`) that works for both
pretty-printed and NDJSON output, attempts a best-effort `_try_repair` on a
truncated tail, validates each recovered object against the item schema, and
keeps the valid ones. Survivors are emitted with `output_validated=true`,
`partial=true`, and `review_advisory=true` (`review_gate_applied=false`).
- **Producer guardrails (`_partition_items`, applied on both the recovery and the
happy path).** Per recommendation: structural type → schema → structural caps
(`_MAX_DEPTH`, `_MAX_STRING_LEN`) → reference allow-list → count cap (top-N by
`maxItems`). The first failing check quarantines the item with provenance and a
`reason` (`malformed` / `schema` / `guardrail` / `allow_list` / `over_limit`).
- **Reference allow-list.** A recommendation whose `candidate` is not in the set of
known ids is quarantined. The set is sourced from resolved context
(`context["known_candidates"]`, via `_allow_list_from_context`); the check is
inert until a context resolver populates it, so the capability ships now and
activates with a one-line resolver change.
### Where each posture sits
| Layer | Posture | Mechanism |
|-------|---------|-----------|
| Schema / contract | B | strict per-item structure; `maxItems` as hint |
| Whole-document parse | A | tolerant parse + single retry |
| Failed parse | B | item-granular recovery + repair + quarantine |
| Per-item screening | B | schema + depth/length caps + allow-list + count cap |
| Emitted report | — | `partial` / `quarantined_*` provenance; never silent |
## Consequences
- A single malformed or oversized item no longer discards an entire activation;
the daily-triage run that failed on 2026-06-26 would now deliver its 7 valid
recommendations and quarantine the broken tail.
- Reports gain a `partial` / `quarantined_*` vocabulary; downstream report sinks
and reviewers can distinguish degraded-but-usable from total loss.
- Guardrail thresholds (`_MAX_DEPTH`, `_MAX_STRING_LEN`, `maxItems`, the
allow-list) are policy knobs that will need tuning; they are intentionally
conservative defaults, not a finished calibration.
- **Known retention gap (follow-on):** `LLMConnectClient.complete()` still returns
only `content`, discarding `finish_reason`/`usage`, and the total-loss artifact
caps raw output below realistic break points. Capturing those signals so
failures stay debuggable is tracked as a retention fix, not closed by this ADR.
## Alternatives considered
- **Hard-enforce `maxItems` in the validator.** Rejected: a hard reject of an
over-count document reproduces the whole-document blast radius. Mitigation (keep
top-N, quarantine the rest) is preferred.
- **Relax the schema to accept anything.** Rejected: violates principle 1; pushes
malformed data into downstream consumers.
- **Retry-until-valid only (pure posture A).** Rejected as the sole strategy: the
2026-06-26 failure recurred across both the initial attempt and the retry, so
retry alone does not bound the blast radius.
## References
- ACT-ADR-002 — markdown-as-definition format and output schema governance.
- ACT-ADR-003 — Rule vs. Instruction model; the Instruction prompt-injection
surface this boundary complements on the output side.
- `workplans/ACTIVITY-WP-0016-llm-output-robustness-trust-boundary.md` — the
implementing workplan.

207
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-005.md Normal file
View file

@ -0,0 +1,207 @@
---
id: ACT-ADR-005
type: architecture-decision-record
title: "Ops runs vs development work records — claim queue and plane split"
status: accepted
owner: activity-core
revision: "accepted-2"
last_reviewed: "2026-08-03"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-03"
scope: cross-repo
affects:
- activity-core
- rein-aharness
- state-hub
- issue-core
- domain repos (Binky, freedom-intelligence, …)
tags:
- architecture
- activity-core
- ops-run
- work-records
- rein-aharness
- issue-core
- forgejo
supersedes_notes: >
Clarifies ACTIVITY-WP-0022 sink practice and G2 executor gap from
ACTIVITY-WP-0023. Does not reverse WP-0022 (no default external tracker issues).
---
# ACT-ADR-005: Ops runs vs development work records
## Status
**Accepted** (2026-08-03).
## Context
The fleet has two healthy patterns that were forced into one vague “task” idea:
1. **Development / coordination work** — structured workplans and tasks as
**repo files**, indexed by **State Hub** on **coulombcore** (`fix-consistency`,
UUIDv7 write-back). This matches ADR-001 and
`work-record-types_v0.1.md` and is how humans and coding agents ship product.
2. **Operations / scheduled automation** — activity-core Temporal schedules
(when / what / where), rein-aharness execution (how), completion events
(idempotence). Instances of “today’s FI brief” or “this prune fire” are
**ephemeral runs**, not multi-day workplan bodies.
Practice collapsed (2) into broken paths:
| Path | Failure |
| ---- | ------- |
| Emit `activity_task_spawn` progress only | Append-only; **not claimable**; schedule can “succeed” while nothing runs |
| `ISSUE_SINK_TYPE=rest` → issue-core → Forgejo | Spam + 503s; issue-core INTENT forbids origin of fleet work |
| Host systemd timers dual-clocked with Temporal | Shadow scheduler; weak self-healing |
issue-core’s **correct** role is a **connector facade** over external trackers
(Forgejo, GitHub, Jira, …) so agents need not know each backend. It is **not**
the origin of work records and **not** the default internal ops queue.
**Gitea is out of scope** for this fleet; the self-hosted forge is **Forgejo**.
Canon already allows a DB-only exception for “runtime operations data (logs,
metrics, run histories, token events)” (`work-record-types_v0.1.md`). This ADR
names that exception for **ops runs**.
This is also the precise meaning of INTENT's no-task-lifecycle boundary:
`ops_run` claim/lease/outcome is durable runtime delivery state, not work-item
state. It may not grow assignment, commitments, dependencies, project phases,
or manually managed task status.
## Decision
### 1. Two planes for “work,” one vocabulary for people
| Plane | Artefact | Home | Lifecycle |
| ----- | -------- | ---- | --------- |
| **A — Development / coordination** | Work records (`workplan`, `task`, `intake`, …) | Repo files + State Hub (coulombcore) | File-backed, reviewable, multi-day |
| **B — Recurrence control** | Activity definitions + Temporal schedules | activity-core (railiance) | Git definitions; DB schedule state |
| **C — Ops execution** | **`ops_run`** (runtime claim object) | **activity-core DB + claim API** | open → claimed → succeeded \| failed \| expired |
| **D — External collab** | Tracker issues | **issue-core** optional projection to **Forgejo** (and others) | Never default for internal automation |
Coding agents orient on **Plane A** via State Hub.
Automation orients on **Planes B+C**.
Humans outside the fleet may see **Plane D** only when deliberately projected.
### 2. activity-core owns the ops_run claim queue
When a definition emits a TaskSpec for internal fleet work:
1. Write **`ops_run`** row (durable, claimable) with idempotency key
(e.g. `fi-daily:2026-08-04` for once-per-day briefs).
2. Optionally dual-write `activity_task_spawn` progress for existing observers.
3. Do **not** open a Forgejo issue.
4. Do **not** create a workplan task file for that day’s fire.
Claim API (implemented in ACTIVITY-WP-0026 and hardened in
ACTIVITY-WP-0036):
- `POST /ops-runs/claim` — lease next open run matching labels / worker id
- `POST /ops-runs/{id}/complete` — succeeded + completion metadata
- `POST /ops-runs/{id}/fail` — failed + retry policy
- `GET /ops-runs?state=open` — operator visibility
Worker mutation credentials are bound to one configured queue `worker_id`;
the request body cannot assert a different claim owner. Heartbeat, completion,
and failure lock the row and require its lease deadline to remain strictly in
the future. Operator/SSO credentials provide visibility and explicit
administration, but do not act as a normal worker identity.
activity-core remains **when / what / where** only: it does **not** run
domain LLM sessions or hold tenant git credentials.
### 3. rein-aharness owns how (approach selection + execute)
- Continuous **claim loop** (service / Deployment), not dual wall-clock timers
as source of truth.
- Host systemd timers become **break-glass** after cutover.
- **Approach selection** at claim time (minimal table v1):
| Labels / definition family | Approach |
| -------------------------- | -------- |
| mail / mail-intake | deterministic adapter (+ optional triage) |
| research-brief / fi-daily | structured llm-connect (`fi-research-brief`) |
| binky rhythm | structured llm-connect (`brief-daily`) |
| agent-session | persona + tool profile session |
| unknown | refuse; do not invent |
- Success posts **domain completion event** (e.g. `fi_daily_brief`) so
resolvers set `due=false`, and closes the `ops_run`.
### 4. State Hub remains the work-record read model
- Stays on **coulombcore**; railiance peers via edge relay / ops-bridge.
- May **project** open/failed ops runs for fleet ops UI (read-only), but is
**not** the claim authority.
- Development workplans/tasks continue file + `fix-consistency` only.
### 5. issue-core is Forgejo (and multi-tracker) facade only
- **Forgejo** is the self-hosted forge; do not plan for **Gitea** as a product.
- Optional **project / link** of an existing work-record UUID to an external
issue when collaboration needs it.
- Authenticated `POST /issues/` means “create/link **external** tracker work,”
never “spawn fleet automation.”
- Internal automation **must not** use issue-core as the ops claim queue unless
a future design adds an **internal-only** backend with projection **hard-off**
for automation labels — out of scope unless a later ADR says otherwise.
### 6. Promotion path ops → dev
When an ops run discovers multi-day product work (e.g. “collect Kimi K3 under
new quota”), the executor or human **promotes** an `intake` / workplan in the
domain repo (Plane A). Ops runs never become permanent fake workplans.
## Consequences
### Positive
- Self-healing recurrence: schedule → claimable row → claim → complete/fail.
- Aligns issue-core INTENT with practice; stops Forgejo spam path.
- Keeps activity-core thin; keeps rein-aharness as sole session/credential shell.
- Preserves the good dev loop (files + State Hub).
### Negative / cost
- New schema + API + migrator in activity-core.
- rein-aharness must leave issue-core-only poll as primary for ops.
- Temporary dual-write and dual timers until cutover proven.
### Non-goals
- Replacing workplans for development.
- Running domain briefs inside activity-core workers.
- Global `ISSUE_SINK_TYPE=rest` to Forgejo.
- Gitea support or migration paths.
## Topology
```text
coulombcore: State Hub + work-record registry
railiance: activity-core (Temporal + ops_run queue)
rein-aharness (claim loop + approach + llm-connect)
domain checkouts
forgejo: optional external collab via issue-core projection only
```
## Implementation stack
| Workplan | Owner | Role |
| -------- | ----- | ---- |
| ACTIVITY-WP-0026 | activity-core | ops_run schema, claim API, emit path, dual-write |
| REIN-A-0002 | rein-aharness | claim loop, approach table, FI/Binky cutover |
| ISSUE-WP-0006 | issue-core | Forgejo-only language; projection boundary; no ops queue |
| STATE-WP-0078 | state-hub | Read projection of ops_run for ops UI (optional consume) |
## References
- `docs/recurring-automations-playbook.md`
- `docs/task-emission-consumer-contract.md`
- `docs/issue-core-emission-boundary.md`
- ACTIVITY-WP-0022, ACTIVITY-WP-0023 (G2)
- `the-custodian/canon/standards/work-record-types_v0.1.md`
- `issue-core/INTENT.md` (work-record boundary)
- `state-hub/docs/cluster-operating-model.md` (coulombcore primary)

142
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-006.md Normal file
View file

@ -0,0 +1,142 @@
---
id: ACT-ADR-006
type: architecture-decision-record
title: "Profile-driven execution selection over the ops_run pull queue"
status: accepted
owner: activity-core
revision: "accepted-1"
last_reviewed: "2026-08-21"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-21"
scope: cross-repo
affects:
- activity-core
- glas-harness
- rein-aharness
- sand-boxer
tags:
- architecture
- activity-core
- ops-run
- glas-harness
- execution
supersedes_notes: >
Extends ACT-ADR-005. Does not change the ops_run claim/lease plane; it
changes what a queued run says about how it should execute.
---
# ACT-ADR-006: Profile-driven execution selection over the ops_run pull queue
## Status
**Accepted** (2026-08-21). Hub decision `147beec6-7fe7-4837-8e3a-4264a240379d`
("Glas contract 1.0 makes execution constellation selection explicit").
## Context
ACT-ADR-005 gave internal scheduled automation a claimable `ops_run` plane.
What an ops_run said about *how* to execute was `approach_hint` — free text,
interpreted by the claiming executor at claim time.
That binding is too late. Live failure, railiance01 2026-08-17:
```
state=failed attempt=1 claim_owner=rein-aharness@railiance01
title=Run SBOM rescan for binect-js
failure=no approach matched labels/definition;
labels=['sbom','security','automated']
```
The run was claimed and leased, *then* died because nothing could execute it.
A claim was consumed to discover the request was unroutable.
`glas-harness` GLAS-WP-0004 closed contract 1.0 and proved it by running one
bounded task through two different reins (`rein-aharness`, `rein-openweights`)
via an explicit `harness_profile_ref`, with real commits and verified sandbox
destruction. Meanwhile every activity-core claim in the week to 2026-08-21 was
`rein-aharness@railiance01` — a coupling that is now avoidable rather than
inherent.
Two shapes were considered: keep the pull queue and carry the profile as
payload, or have activity-core call the Glas gateway directly. glas-harness,
which owns the contract, advised the first for the initial migration.
## Decision
### 1. The queue stays; the payload changes
activity-core continues to insert `ops_run(open)` and executors continue to
claim under lease. Scheduling topology does not change. What changes is that a
queued run carries an exact **versioned `harness_profile_ref`** plus the
correlation / assignment / role / duty / goal / resource-envelope references.
The claiming executor passes that request into Glas, which resolves or refuses
it **before sandbox creation**.
This changes the execution contract without simultaneously changing the
scheduling topology — one variable at a time. A direct activity-core → Glas
call may be evaluated later, independently, if pull delivery stops meeting
operational needs.
### 2. `harness_profile_ref` is authoritative; `approach_hint` is legacy
The two coexist with **distinct semantics**, not as fallbacks for one another:
- `harness_profile_ref` is the authoritative execution-constellation selector.
- `approach_hint` remains only a legacy activity/definition-matching hint while
producers and consumers migrate.
`approach_hint` must **not** override, synthesize, or fall back from an absent
or invalid `harness_profile_ref` on governed execution. A missing profile is an
error, never an invitation to guess from a hint. Once inventory shows no caller
depends on `approach_hint` for runtime selection, that use is deprecated.
### 3. activity-core does not mirror the profile catalog
The catalog in glas-harness is authoritative. activity-core must not maintain
an independent list, which would drift and produce a second, disagreeing
opinion about what is executable.
Consequence, accepted knowingly: Glas exposes deterministic validation through
its package and CLI but **no network validation service** today, so
activity-core cannot remotely validate a profile ref at emission time. We
therefore validate only what is local and structural — that a ref is present
and well-formed for governed execution — and rely on the **execution-side Glas
resolver as the mandatory fail-closed check**.
This is weaker than refusing at emission, and deliberately so: an unreachable
or absent validation service must never downgrade into "emit anything". If
emit-time remote validation is later required, it needs a separately scoped
Glas API and its own decision — not a mirrored catalogue here.
Even unvalidated at emit, this is strictly better than the 2026-08-17 failure:
refusal happens deterministically before sandbox creation rather than after a
claim and lease were consumed.
### 4. activity-core does not become an executor
We emit an authorized, profile-named request and record normalized evidence.
We do not select reins, provision sandboxes, acquire credentials, or run any
inner agentic loop. Glas owns profile resolution and the outer loop; the rein
owns its inner loop; `sand-boxer` owns isolation. This is SCOPE drift risk #1
("convenience execution") and this ADR does not relax it.
The attribution references we carry (`assignment_ref`, `role_ref`, `duty_ref`,
`goal_refs`, `resource_envelope_refs`) are **passed through**, not authored
here. Their vocabulary belongs to `info-tech-canon`; activity-core must not
invent org roles (ACTIVITY-WP-0029 responsibility map).
ACT-ADR-007's bounded-operation exception does not alter this decision. A
code-registered fixed maintenance operation is not a Glas/rein execution
constellation, and the exception cannot be used to run an agent loop or execute
an `ops_run` inside activity-core.
## Consequences
- `ops_runs` grows `harness_profile_ref` and the attribution refs; the emission
path, queue projection, and run artefacts carry them.
- Definitions declare a profile; rules pass it through.
- Unroutable requests fail before sandbox creation instead of at claim time.
- activity-core is no longer coupled to one rein in practice.
- Emit-time validation remains a known gap, owned by a future Glas API.
- Implementation: **ACTIVITY-WP-0032**.

128
docs/evidence/2026-10-11-served-publication-history/sources/ACT-ADR-007.md Normal file
View file

@ -0,0 +1,128 @@
---
id: ACT-ADR-007
type: architecture-decision-record
title: "Code-registered bounded operations are the only local mutation exception"
status: accepted
state_hub_decision_id: "2b1f0c01-1d6f-4fdc-b3e7-537ce0a0a1f8"
owner: activity-core
revision: "accepted-1"
last_reviewed: "2026-08-23"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-23"
scope: repo
affects:
- activity-core
- sbom-nexus
- railiance-platform
tags:
- architecture
- activity-core
- bounded-operation
- execution-boundary
---
# ACT-ADR-007: Code-registered Bounded Operations
## Status
**Accepted** (2026-08-23) for ACTIVITY-WP-0035.
## Context
The Event Bridge principle says activity-core answers when, what, and where and
does not execute domain work. Production nevertheless contains three useful
operations whose complete outcome is a small scheduled maintenance action:
- ingest at most three Repo Manager-selected immutable sources into SBOM Nexus;
- prune Forgejo package versions under live-image protection; and
- invoke the fixed CNPG Option A backup tool for an explicit target list.
Historically the latter two ran through a generic `shell` context resolver.
That made a mutating subprocess look like a read and left extension policy to
convention. Removing the operations would recreate bespoke cron; accepting
arbitrary shell would make activity-core a general executor.
## Decision
### 1. Bounded operations are a narrow implementation exception
The governing when/what/where responsibility does not gain a general “how.” A
bounded operation is allowed only when the operation itself is the declared
automation outcome and all admission requirements below are code-reviewable.
The initial allowlist is exactly:
1. `sbom_nexus_ingest`
2. `forgejo_package_prune`
3. `cnpg_option_a_backup`
Adding an operation requires updating the code-owned registry, this ADR (or a
successor), tests, credential route, and evidence contract. A string in a
definition cannot register an operation.
### 2. Admission is fail closed during file sync
Each registry entry declares:
- source type and query;
- whether mutation intent is `apply` or `dry_run` and that it is explicit;
- fixed or maximum target bounds;
- canonical implementation and allowed configuration;
- idempotency and Temporal retry semantics;
- maximum execution timeout;
- credential owner/route; and
- mandatory non-secret evidence mode.
Unknown `shell` queries are refused unless separately registered as read-only.
Known operation queries with missing, malformed, or over-limit safety fields
are refused before database projection or Temporal schedule reconciliation.
### 3. Context resolution is read-only
The workflow first resolves and freezes context. Mutations then run in an
explicit bounded-operation stage and merge only normalized outcomes into the
snapshot before evidence and rule/instruction evaluation.
SBOM selection remains a read in the context phase; its fixed selection is the
input to the operation stage. Package prune and backup have no discovery read
inside activity-core and bind a pending marker until their operation completes.
### 4. Retry behavior is operation-specific
- SBOM ingest uses stable per-run/per-repository idempotency keys and heartbeat
checkpoints, so Activity retries resume the frozen batch.
- Forgejo prune and CNPG backup have no activity-core-verifiable remote
idempotency receipt. Their operation activity therefore has one Temporal
attempt; a failure remains visible for operator reconciliation rather than
risking an automatic second mutation.
This does not preclude future safe retries after the platform tools expose a
durable operation receipt.
### 5. Evidence is mandatory and bounded
Every operation must produce an allowlisted summary through a configured
report/evidence sink. Raw subprocess output, tokens, provider payloads, archive
URLs, kubeconfigs, and credential material are not evidence.
## Rejected alternatives
- **Keep mutating shell resolvers.** Rejected because resolution should be a
replayable read and the generic dispatcher hides mutation admission.
- **Generic command activity.** Rejected because command text/path from a
definition is remote code execution by configuration.
- **Move every operation to a rein.** Rejected for these fixed platform
operations; it adds an agent execution constellation without judgement or
repository work. Operations that exceed this ADR's bounds do belong there.
- **Remove all local operations.** Rejected because it recreates scattered cron
and loses Temporal/evidence guarantees for established maintenance.
## Consequences
- Definition parsing gains a central operation-policy validator.
- The workflow gains an explicit operation stage.
- The generic `shell` resolver becomes read-only.
- Existing definitions migrate without widening targets or permissions.
- The registry is intentionally small and architectural review is required to
expand it.

247
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-001.md Normal file
View file

@ -0,0 +1,247 @@
---
id: CUST-ADR-001
type: architecture-decision-record
title: "Workplans and Work Items Are Repository Artefacts"
status: accepted
owner: the-custodian
revision: "accepted-2"
last_reviewed: "2026-08-31"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-02-28"
tags: ["architecture", "state-hub", "workplans", "source-of-truth", "rebuild-principle", "forgejo", "projection"]
---
# ADR-001: Workplans and Work Items Are Repository Artefacts
## Status
Accepted 2026-02-28.
Amended 2026-08-31 to distinguish file-backed work records from hub-native
records, identify the Forge default branch as the central projection baseline,
and align identity, lifecycle, reconciliation, and closure with ADR-007,
ADR-010, ADR-011, ADR-012, and the work-record standards. The central decision
is unchanged.
## Context
During early State Hub development, workstreams and tasks were created directly
in PostgreSQL through bootstrap APIs. This made a database the origin of durable
work rather than a projection of repository-owned artefacts. The pattern was
convenient, but it made work difficult to audit, review, recover, and carry
between generations of tooling.
The original decision correctly moved durable workplans and their work items
into repositories. It overstated the consequence, however, by saying that the
entire Hub database and every item that matters for coordination must be
reconstructible from repository files. Later decisions established two
different persistence classes:
- **file-backed records**, whose durable meaning originates in a repository;
- **hub-native records**, such as append-only progress and runtime facts, whose
durable meaning originates in the Hub.
Later decisions also established that a central projection reads the pushed
default branch in Forgejo. An arbitrary workstation checkout is a workspace,
not the shared baseline. Unpushed local work may be represented only as an
explicit preliminary overlay.
## Decision
### 1. File-backed work originates in the owning repository
Workplans and their file-backed work items **MUST originate as repository
artefacts in the repository that owns the work**. The Hub indexes and projects
those artefacts but is not their origin.
This includes the workplan, embedded tasks, declared dependencies, residual
handoffs, and durable governed decision artefacts when those are represented as
files. No authoritative field of a file-backed record may exist solely in a Hub
database.
The owning repository is identified by repository identity, not merely by a
domain or topic. Domains and topics classify work; they do not own its source.
### 2. Authority is explicit per persistence class
Every record contract must declare whether the record is file-backed or
hub-native. The same record must not be writable as authoritative in both
places.
- For a **file-backed record**, the repository artefact is authoritative and
the Hub row is derived state.
- For a **hub-native record**, the Hub is authoritative. Progress events,
messages, token events, run history, and similar runtime facts are not made
fictional repository records merely to satisfy a rebuild slogan.
The word `decision` is used by more than one subsystem. Architecture decisions
and other governed decision artefacts remain files. A runtime decision event may
be hub-native only where its schema says so explicitly; it does not replace the
governed artefact.
This replaces the original blanket rejection of a hybrid architecture. The
architecture is hybrid **by declared record class**, never ambiguous within one
record.
### 3. Forge is the central projection baseline
For the shared central view, the source is the pushed default-branch state held
by Forgejo, as decided by ADR-012. Every projected record must be attributable
to its source repository, path, and commit.
A working copy remains the authoring workspace. Unpushed work may appear in the
Hub only as an attributed preliminary overlay. It must not silently replace or
be presented as the Forge-derived baseline. When its commit reaches Forge, the
baseline absorbs it and the overlay retires.
### 4. Mutations of file-backed state are file-first
Creating or changing a file-backed work record means changing its repository
artefact first. A convenience tool or API is conformant only when it performs a
governed repository mutation and leaves a reviewable file and commit. Writing
only the projected database row is not a durable update.
Direct Hub APIs remain valid for hub-native records. They may also provide
diagnostics or propose repository patches, but a successful database PATCH is
not evidence that a file-backed status changed.
### 5. The rebuild guarantee applies to the projection, not the whole database
Given a repository and a specific Forge commit, the system must be able to
reconcile that repository's file-derived projection so that it is equivalent to
the records derived from that commit. Reconciliation must be idempotent,
verifiable, and scoped per repository; a fleet operation is iteration over the
same per-repository operation.
Reconciliation retires file-derived records that no longer derive. It does not
delete hub-native history attached to them. It must refuse and report a
repository whose records exist only in the projection until those records have
an explicit disposition. A Forge rebuild does not reconstruct preliminary
overlays and must disclose their retirement before proceeding.
Therefore the **file-derived projection is disposable**. The database as a
whole is not disposable when it also contains hub-native facts.
### 6. Identity and lifecycle are delegated contracts
This ADR does not define a second identity or lifecycle schema.
- Workplan and task identity follow ADR-007 as amended by ADR-011: global
identity is namespace-aware, and derivable Hub identifiers are governed by
that contract. Existing historical identifiers are grandfathered according
to its migration rules.
- Work-record kinds, locations, lifecycle values, and residual handling follow
`canon/standards/work-record-types_v0.1.md` and
`canon/standards/workplan-terminology-fleet_v0.1.md`.
New normative text uses `workplan` and `work record`. `workstream` remains only
as a metered compatibility term for legacy database and API surfaces.
### 7. Reconciliation belongs at the repository boundary
Repo Manager owns discovery, parsing, identity checks, and reconciliation for
file-backed records. State Hub owns the projection and hub-native records. The
implementation may distribute fetch and parse work, but it must preserve that
authority boundary.
Legacy `create_workstream`, `create_task`, workstation-driven
`sync-workplans`, and similarly named commands are not normative interfaces.
They are conformant only if their current implementation satisfies decisions
3 and 4; otherwise they are transitional or retired.
## Workplan closure
A workplan cannot be marked `finished` merely by changing its Hub row. Before
closure, the responsible worker must:
1. review the source file and the projected view for unfinished tasks;
2. record completed and cancelled outcomes in the source task blocks using the
canonical task lifecycle;
3. turn every actionable carry-forward item into a live work record with
`origin: residual` and an `origin_ref`, or into another explicitly linked
workplan;
4. set the source workplan to `finished`, update it, and commit the result;
5. publish the commit to Forge for the shared baseline and verify that the
projection reconciles to that commit.
A local reconciliation before push may expose preliminary state, but it does
not complete step 5.
Automated stale-task cleanup must report file/projection drift. It may not
silently cancel a file-backed task only in the database. An automated repair may
change such a task only through the same governed repository mutation and
commit path as any other file-backed change. Cleanup of hub-native records is
governed by their own retention contract.
## Consequences
### Positive
- Durable work remains inspectable, reviewable, and recoverable through Git.
- The central view has an exact repository and commit provenance instead of
reflecting whichever workstation synced most recently.
- Reconciliation can be exercised per repository without destroying progress
history or other hub-native evidence.
- Multiple contributors share a published baseline while retaining an honest
representation of preliminary work.
- Service ownership is clearer: repositories own file-backed truth; the Hub
owns runtime facts and projection services.
### Negative
- File-backed changes require a repository mutation and normally a push before
they become shared baseline state.
- Forge availability affects projection freshness, although it does not prevent
local authoring.
- Preliminary, stale, and retired projection states must be visible in APIs and
user interfaces.
- Git merge conflicts become the explicit conflict mechanism for simultaneous
edits to the same authoritative artefact.
- Tools that previously corrected only database state must be changed to emit a
diagnostic or perform a governed repository update.
## Migration
No bulk rename, UUID rewrite, or historical file rewrite is required by this
amendment. Existing identifiers and legacy terminology retain the grandfathering
rules of ADR-007, ADR-011, and the terminology standard.
Implementations must audit and retire DB-first creation, closure, and stale-task
cleanup paths. Existing file-backed projection rows without a Forge source
commit are migration state: they must be matched to a repository artefact or
explicitly dispositioned before reset. Forge-derived reconciliation and
preliminary overlays are implemented under ADR-012 rather than duplicated here.
The `accepted-1` publication remains the immutable historical revision. This
document is `accepted-2`.
## Alternatives considered
**Database-first with export.** Rejected. Export can be skipped, making the
reviewable artefact secondary and stale.
**Files only, with no projection database.** Rejected. Cross-repository queries,
runtime views, and append-only operational facts need indexed services.
**Treat every Hub record as reconstructible from Git.** Rejected. This either
loses runtime truth during rebuild or creates artificial files whose only
purpose is mirroring a database.
**Let working copies push authoritative projection rows.** Rejected by ADR-012.
It makes the baseline depend on the last workstation to reconcile and cannot be
audited against a shared commit.
## Related
- ADR-003 — materialized and derived state
- ADR-005 — cross-repository work ownership
- ADR-007 — workplan identity and repository worker topology
- ADR-010 — Hub authority and local cache model
- ADR-011 — namespace-aware federation and reconciliation limits
- ADR-012 — Forge projection source and preliminary overlay
- `canon/standards/work-record-types_v0.1.md` — work-record kinds, lifecycle,
residuals, and reconciliation
- `canon/standards/workplan-terminology-fleet_v0.1.md` — canonical terminology
- `canon/values/foundational_values_v0.1.md` — local-first operation,
auditability, and reversibility

126
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-002.md Normal file
View file

@ -0,0 +1,126 @@
---
id: CUST-ADR-002
type: architecture-decision-record
title: "Custodian Agent Runtime — v0.1 Bootstrap Design"
status: accepted
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-03-12"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-03-12"
tags: ["architecture", "agent-runtime", "llm", "ooda", "bounded-agency"]
---
# ADR-002: Custodian Agent Runtime — v0.1 Bootstrap Design
## Status
Accepted.
## Context
CUST-WP-0001 requires a first working skeleton of the Custodian as an acting
agent: a loop that observes project state, reasons about it, and executes
bounded write operations — without human interaction for each step.
The dependencies (llm-connect, operational Railiance infra) are now resolved.
This ADR captures the five key architectural decisions for the v0.1 bootstrap.
## Decisions
### D1 — Location: `runtime/` inside the-custodian (not a new repo)
**Decision:** The runtime lives under `the-custodian/runtime/` as a standalone
Python package (`pyproject.toml`, own venv) rather than a new repository.
**Rationale:** The runtime is tightly coupled to canon (reads constitution,
memory) and the state-hub (its primary coordination layer). A separate repo
adds friction with no v0.1 benefit. The existing `runtime/` scaffold confirms
the original intent. Extraction to its own repo is deferred to when the
runtime has stable boundaries and multiple consumers.
### D2 — OODA loop: single-pass synchronous CLI
**Decision:** One `run()` call = one complete Observe → Orient → Decide → Act
cycle. Entry point is a CLI (`agent.py`) invoked manually or by a cron job.
```
Observe — HTTP GET to state-hub: state summary or domain summary
Orient — Load constitution + build structured LLM context prompt
Decide — Single LLM call (via llm-connect) returns a JSON action plan
Act — Execute only sanctioned write operations from the plan
```
**Rationale:** Async event loops and daemons add operational complexity that
v0.1 doesn't need. A single-pass CLI is testable, debuggable, and can be
scheduled externally. The transition to an event-driven loop is Phase 2.
### D3 — LLM backend: ClaudeCodeAdapter by default
**Decision:** The runtime uses `llm_connect.ClaudeCodeAdapter` as its default
LLM backend (shells out to `claude --print`). Provider is configurable via
`--llm` flag to support `gemini`, `openrouter`, or `openai`.
**Rationale:** `ClaudeCodeAdapter` requires no API key and honours the
Local-First value (V2). All current deployments have Claude Code available.
The llm-connect abstraction means switching providers is a one-line change.
### D4 — Action constraint: three sanctioned write operations only
**Decision:** The agent may execute exactly three state-hub write operations
without human approval:
1. `add_progress_event` — append an observation to the event log
2. `update_task_status` — mark a task done/in_progress (reversible)
3. `flag_for_human` — raise an intervention flag (escalation, not action)
All other operations (create workstream, record decision, resolve decision,
write to canon) require human approval before execution.
**Rationale:** Constitution §3/§4 require bounded agency. The three operations
are either append-only (progress events), reversible (task status), or
explicitly escalating (flag). They cannot produce irreversible harm.
### D5 — LLM response format: JSON block in markdown
**Decision:** The LLM is prompted to return a Markdown response with a
fenced ```json block containing the structured action plan:
```json
{
"observations": ["..."],
"progress_events": [
{"summary": "...", "workstream_id": "...", "event_type": "note"}
],
"tasks_to_update": [
{"task_id": "...", "status": "done"}
],
"tasks_to_flag": [
{"task_id": "...", "note": "..."}
]
}
```
The surrounding Markdown is preserved as a human-readable reasoning trace
and written to `memory/working/` as a session note.
**Rationale:** JSON blocks are robust to extraction (delimited), LLMs produce
them reliably with clear instructions, and the surrounding prose gives Bernd
an auditable reasoning trace without requiring a separate reasoning step.
## Consequences
- `runtime/` becomes a standalone Python package; `make agent-run DOMAIN=x`
invokes it.
- The runtime has no DB schema changes and no new API endpoints — it is a
pure client of the existing state-hub HTTP API.
- Autonomous actions are limited to append-only writes and escalations. Any
expansion of the action surface requires a new ADR and human approval.
- The v0.1 loop is single-user (Bernd). Multi-agent expansion is Phase 2+.
## Deferred
- Async event loop / daemon mode (Phase 2)
- RAG over canon (Phase 1 roadmap item)
- Tool adapters beyond state-hub HTTP (planned in `runtime/tool_adapters/`)
- Deployment on Railiance k3s as a scheduled CronJob

207
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-003.md Normal file
View file

@ -0,0 +1,207 @@
---
id: CUST-ADR-003
type: architecture-decision-record
title: "Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data"
status: accepted
owner: the-custodian
revision: "accepted-2"
last_reviewed: "2026-08-31"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-03-20"
tags: ["architecture", "state-hub", "caching", "read-model", "materialized-view", "derived-state"]
---
# ADR-003: Materialized Derived State with Fingerprint Invalidation
## Status
Accepted, and **partially superseded by `ADR-012`** (accepted 2026-08-25).
Decision 2's fingerprint composition is invalidated in part; decision 5's rebuild
principle is given a concrete source and a required operation. See the notes on
each.
## Context
The Custodian State Hub is a **read model** (CQRS terminology) — its data is
fully derivable from canonical sources that live in repositories and the
filesystem. No state-hub data is authoritative; it is always a derived view
of what the repos contain.
Several categories of data fit this description:
| Data | Canonical source | State-hub table |
|---|---|---|
| SBOM dependencies | `uv.lock`, `package-lock.json`, etc. | `sbom_entries` |
| Third-party service declarations | `tpsc.yaml` | `tpsc_entries` |
| Provided capabilities | `SCOPE.md` `capability` blocks | `capability_catalog` |
| DoI compliance tier | 14 criteria across repo files + DB | `doi_cache` |
| Workplan task status | `workplans/*.md` | `tasks` |
Early implementations either recomputed this data on every request (too slow)
or ingested it once without invalidation (stale data goes undetected). Neither
is acceptable for a system designed to give accurate, fast orientation.
The `doi_cache` table, introduced in CUST-WP-0024, demonstrated a pattern that
solves both problems. This ADR formalises that pattern and mandates its use
for all repo-sourced derived data.
## Pattern Name
**Materialized Derived State with Fingerprint Invalidation.**
This pattern is known under several names in the literature:
- **Materialized View** (SQL standard, PostgreSQL) — the stored result of a
query or computation, refreshed on demand when source data changes.
- **Derived Data Store** (Kleppmann, *Designing Data-Intensive Applications*,
Ch. 3 & 11) — a system whose entire dataset can be rebuilt from upstream
sources; it is never the source of truth.
- **Read Model / Projection** (CQRS / Event Sourcing) — a pre-computed view
maintained alongside a write model, rebuilt when relevant events occur.
- **Fingerprint-based / Content-addressed invalidation** — analogous to HTTP
ETags: a cache entry is valid as long as a composite hash/timestamp of its
inputs matches the stored value.
The State Hub already documents itself as a read model. This ADR extends that
principle to specify *how* the read model stays fresh.
## Decision
### 1. All repo-sourced derived data MUST be materialised in the DB
Data computed from repository files or repo records must be stored in a
dedicated table rather than recomputed per request. Direct computation on
every API call is only permissible for development tooling or when explicitly
forced by the caller.
### 2. Each materialised table MUST carry a `fingerprint` column
The fingerprint is a deterministic string encoding all inputs that affect the
computed result. It is compared on each read; if unchanged, the stored result
is returned without recomputation. If changed, the result is recomputed and
the stored value is updated.
**Fingerprint composition rules:**
- Include the `updated_at` timestamp of every DB record that feeds the
computation (repo record, related domain, goals, snapshots).
- Include the `mtime` (filesystem modification time) of every file that feeds
the computation (`SCOPE.md`, `CLAUDE.md`, lockfiles, `tpsc.yaml`, etc.).
> **Invalidated in part 2026-08-25 by `ADR-012` decisions 1 and 2.** Filesystem
> `mtime` is not a property of the source. It differs between machines, changes
> on a fresh clone, and says nothing about content — so a fingerprint built from
> it describes one workstation's filesystem rather than the repository. Under
> `ADR-012` the projection derives from the forge, and the commit that produced
> a record is both the correct input and the auditable one.
>
> This was not merely theoretical drift. `git_fingerprint` for `the-custodian`
> held the repository's *initial* commit while `last_state_synced_at` was minutes
> old: the field meant to identify what a projection reflects was wrong by the
> entire history of the repository, and nothing noticed. Replace `mtime` inputs
> with the source commit.
- Join all components with `|` as a pipe-separated string — no hashing needed
since the string is compared by equality, not transmitted to clients.
- If a file is absent, encode `filename:absent` rather than omitting it, so
file creation also triggers invalidation.
**Reference implementation:** `state-hub/api/doi_engine.py::compute_fingerprint()`
### 3. Every materialised endpoint MUST support `?force_refresh=true`
Callers must always be able to bypass the cache and trigger a fresh
computation. This is the escape hatch for debugging, post-ingest verification,
and scheduled background refresh jobs.
### 4. Writes to source data SHOULD update the repo record's `updated_at`
Operations that change source data (SBOM ingest, TPSC ingest, capability
ingest) must ensure `managed_repos.updated_at` is refreshed so the
fingerprint detects the change on the next read. Where data lives in a
related table (e.g. `tpsc_snapshots`), the fingerprint must include that
table's `max(snapshot_at)` directly rather than relying on the repo record.
### 5. The DB is never the source of truth — the rebuild principle holds
Per ADR-001, the state-hub must be rebuildable from scratch by re-ingesting
all canonical sources. Materialised tables are **caches**, not records of
authority. They may be wiped and repopulated at any time without data loss.
> **Given concrete form 2026-08-25 by `ADR-012` decision 7.** This principle was
> correct and, until now, never exercised — an untested rebuild path is an
> assumption rather than a capability, and this one was believed for long enough
> that a divergence survived seven weeks behind it. `ADR-012` requires the
> reconstruction to exist as a routine operation, scoped per repository, sourced
> from the forge, and verifiable against it.
>
> The claim "without data loss" also needs its precondition stated: it holds only
> while the rule immediately below does. On 2026-08-25, 111 work records existed
> only in the hub, so a rebuild at that moment would have destroyed them.
> `ADR-012` therefore requires reset to refuse, per repository, when records have
> no counterpart in the forge.
This means:
- No materialised table may be the only copy of any information.
- Schema migrations that wipe a materialised table are safe and expected.
- Background jobs that periodically re-ingest all repos are valid and
encouraged.
## Consequences
### Positive
- **Fast reads in steady state** — after the first computation, subsequent
reads hit the DB with no filesystem or subprocess overhead.
- **Accurate on change** — fingerprint invalidation ensures stale data is
never silently served; the cache refreshes exactly when needed.
- **Debuggable** — `force_refresh=true` and `checked_at` timestamps make it
easy to see when a value was last computed and to trigger a recheck.
- **Consistent with the read model principle** — the pattern makes explicit
what was always implied: state-hub data is derived, not authoritative.
### Negative / Trade-offs
- **First-call latency** — cache misses are expensive (filesystem reads,
subprocess calls, HTTP self-calls). Mitigated by pre-warming caches at
startup or after ingest.
- **Fingerprint completeness** — if a new input is added to a computation and
not added to the fingerprint, stale results will be silently returned. The
fingerprint must be kept in sync with the computation.
- **Filesystem dependency** — file mtimes are volatile (e.g. `git checkout`
rewrites mtimes). In practice this means a cache miss after every checkout,
not a correctness problem.
## Implementation Checklist
When adding a new category of repo-sourced derived data:
- [ ] Create a `_cache` or `_snapshots` table with `fingerprint` and
`checked_at` columns.
- [ ] Implement `compute_fingerprint(repo, ...)` in the relevant module.
- [ ] Add `?force_refresh=true` query parameter to the read endpoint.
- [ ] Ensure the ingest script (or write path) touches `managed_repos.updated_at`
or includes a related table's `max(timestamp)` in the fingerprint.
- [ ] Verify the cache can be wiped and repopulated without data loss.
- [ ] Document which inputs are included in the fingerprint in a comment
alongside `compute_fingerprint`.
## Current Implementations
| Derived data | Table | Fingerprint inputs | Force-refresh |
|---|---|---|---|
| DoI compliance tier | `doi_cache` | `repo.updated_at`, `max(tpsc_snapshots.snapshot_at)`, `max(repo_goals.updated_at)`, `mtime(SCOPE.md)`, `mtime(CLAUDE.md)`, `mtime(tpsc.yaml)` | `?force_refresh=true` |
## Planned Applications
| Derived data | Table (proposed) | Notes |
|---|---|---|
| SBOM summary stats | `sbom_cache` | Fingerprint: `max(sbom_snapshots.snapshot_at)` |
| Capability declarations | `capability_cache` | Fingerprint: `mtime(SCOPE.md)`, `repo.updated_at` |
| Workplan status summary | Already handled by consistency checker | Fingerprint: workplan file mtimes |
## Related
- ADR-001: Workplans and Work Items Are Repository Artefacts
- ADR-002: Custodian Agent Runtime Design
- `state-hub/api/doi_engine.py` — reference implementation
- `state-hub/api/models/doi_cache.py` — reference schema
- `state-hub/migrations/versions/k8f9a0b1c2d3_doi_cache.py` — reference migration

147
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-004.md Normal file
View file

@ -0,0 +1,147 @@
---
id: CUST-ADR-004
type: architecture-decision-record
title: "Connectivity-First Network Posture for Custodian Infrastructure"
status: accepted
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-03-26"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-03-26"
tags: ["architecture", "network", "ops-bridge", "connectivity", "isolation", "security-posture"]
---
# ADR-004: Connectivity-First Network Posture for Custodian Infrastructure
## Status
Accepted.
## Context
The Custodian infrastructure spans multiple machines: a primary workstation, a
shared compute node (COULOMBCORE), and Railiance cluster nodes. Agents running
on remote machines need to reach the state-hub API and MCP server, which live
on the workstation. Human operators and agents also need to reach remote
services (k3s API, Gitea, Temporal) from the workstation.
Two network postures were considered for how these components communicate:
**Option A — Connectivity-first:** Components are connected by default via
controlled, observable access paths (reverse SSH tunnels managed by ops-bridge).
Isolation is added selectively where there is a specific threat model or
compliance reason to do so.
**Option B — Isolation-first (zero-trust):** No component trusts any other by
default. Every connection requires mutual authentication, short-lived
credentials, and explicit authorisation at the point of use. Connectivity is
earned, not assumed.
This decision is architectural policy — it governs how ops-bridge tunnels are
designed, how agent-to-hub communication works, and how new infrastructure
components are onboarded.
## Decision
**Connectivity-first, with isolation as a deliberate option.**
The default posture for Custodian infrastructure is: components that need to
work together are connected. Access paths are explicit, observable, and managed
(via ops-bridge), but they are persistent by default rather than ephemeral.
Isolation is introduced where there is a specific, articulated reason — not as
a blanket policy applied uniformly.
## Rationale
### 1. Scale and team size
The infrastructure is operated by a single human and a bounded set of
automation agents. The overhead of zero-trust (credential rotation, SPIFFE/SPIRE
identity, mTLS everywhere, short-lived tokens per request) is disproportionate
for this scale. It would consume significant operational complexity without
a commensurate security return.
### 2. Observability over perimeter hardening
The primary security control at this scale is **observability**: knowing what
connected, when, from where, and what it did. ops-bridge provides this — every
tunnel is named, actor-attributed, health-checked, and audited. A perimeter of
invisible short-lived connections would actually reduce observability.
### 3. The threat model does not require zero-trust today
The main threats are:
- A runaway agent consuming resources (mitigated by nproc/memory cgroups)
- A compromised workload reaching state-hub and corrupting state (mitigated by
the read-model design of state-hub — write surface is narrow and sanctioned)
- An external attacker reaching internal services (mitigated by the tunnels
being reverse SSH — no inbound ports exposed)
Zero-trust would address a different threat model: lateral movement between
hostile tenants, or untrusted code running in the same environment as sensitive
data. That is not the current situation.
### 4. Degrade-gracefully requires persistent connectivity
The Custodian's foundational value of **local-first, degrade-gracefully**
requires that agents can orient themselves even when some connections are slow
or partially degraded. Ephemeral connectivity (zero-trust tokens, service mesh
sidecars) introduces additional failure modes that conflict with graceful
degradation. Persistent SSH tunnels with auto-reconnect are more resilient to
intermittent conditions.
### 5. Isolation remains the right choice in specific cases
Connectivity-first does not mean no isolation. The following cases call for
explicit isolation and are handled separately:
- **Tenant separation** (when/if multi-user or multi-org) — each tenant gets
its own network segment
- **Privileged execution** — CI runners and agent actions with write access to
production systems run in ephemeral, isolated environments (per the
Privileged Execution Control standard)
- **Secrets** — credentials are never transmitted over tunnels in plaintext;
age-encrypted at rest, SOPS for config
## Consequences
### Immediate
- ops-bridge tunnels are **persistent** (max_attempts: 0, auto-reconnect) and
are treated as infrastructure, not one-off connections
- Agents on remote machines check tunnel health at session start and restore
dropped tunnels before accessing state-hub (documented in global CLAUDE.md)
- New infrastructure components are onboarded with a named tunnel entry in
`~/.config/bridge/tunnels.yaml` — not ad-hoc SSH commands
### Deferred
- If the infrastructure grows to multi-tenant or multi-operator, this decision
should be revisited. At that point, isolation-first becomes proportionate.
- If a security audit identifies a specific lateral movement risk, targeted
isolation (network policy, mTLS for that service) is the response — not a
wholesale posture change.
## Alternatives Rejected
### Zero-trust / isolation-first
Rejected for current scale. The operational overhead (credential lifecycle,
service mesh, mutual TLS) is disproportionate, observability would decrease,
and the threat model does not require it. Noted for re-evaluation at multi-
tenant scale.
### VPN (WireGuard / Tailscale)
Considered briefly. VPN would solve the connectivity problem but introduces
a persistent network layer that all traffic traverses, reducing the
explicitness of individual access paths. ops-bridge tunnels are per-service
and per-actor, which gives better observability and blast-radius control.
VPN is not ruled out as a future complement but is not the primary approach.
### Ad-hoc SSH (no ops-bridge)
The pre-ops-bridge approach. Rejected because it has no health checks, no
actor attribution, no audit log, and requires manual intervention to restore.
ops-bridge formalises the same SSH tunnel pattern with operational discipline.

124
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-005.md Normal file
View file

@ -0,0 +1,124 @@
---
id: CUST-ADR-005
type: architecture-decision-record
title: "Cross-Repo Workplans Live in Dedicated Project Repos"
status: accepted
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-06-22"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-06-22"
tags: ["architecture", "state-hub", "workplans", "cross-repo", "project-repo", "source-of-truth", "lifecycle"]
---
# ADR-005: Cross-Repo Workplans Live in Dedicated Project Repos
## Status
Accepted.
## Context
ADR-001 established that workplans and work items originate as files in the
repository that owns them, so the State Hub can rebuild its coordination state
from repo-owned files alone. The repo-classification redesign (`CUST-WP-0050`)
takes the next step: it makes the **repo the primary anchor** for a workplan
(`workstreams.repo_id` becomes required) and **derives** the market-domain from
the repo's `.repo-classification.yaml` rather than maintaining a separate
`topic`/`domain` spine. Repos are the most stable, git-managed entities in the
ecosystem; binding to them is the most durable anchor available.
This raises an unavoidable question: **what anchors a genuinely cross-repo
workplan?** Some efforts coordinate change across many repositories — ecosystem
migrations, the FOS hub bootstrap (`CUST-WP-0025`), or `CUST-WP-0050` itself,
which touches ~70 repos. If every workplan must bind to exactly one repo:
- binding it to one arbitrary product repo misrepresents the work and pollutes
that repo's history with coordination it does not own;
- leaving it unbound reintroduces the hub-only orphan that ADR-001 forbids;
- modelling it as an array of `repo_id`s breaks the "one stable anchor, clear
ownership, clean lifecycle" property and complicates the rebuild principle.
## Decision
**A complex cross-repo workplan gets its own dedicated *project repo*.**
- The project repo is a real, git-managed repository. It owns the coordination
workplan, its tasks, its decisions, and any cross-cutting artefacts. It is the
required `repo` anchor for that workplan, satisfying the repo-primary-anchor
rule without distorting any single product repo.
- The project repo is classified under the Repo Classification Standard, normally
`category: project`. Its `domain`/tags describe the effort, not any one product.
- **Implementation still happens in the product repos.** Changes land via
per-repo workplans and PRs in the repos being modified. The project repo
*coordinates and references* that work (via dependency edges / links); it does
not own product code.
- **On completion, the project repo is retired to archive — not deleted.** Its
durable results live on in the product repos it modified (the merged changes
are the outcome). The archived project repo remains as an immutable provenance
record of the coordination, consistent with the append-only-memory value.
The project repo's completion record MUST list the product repos it modified and
link to the merged PRs/commits, so the trail survives archival.
## Lifecycle
```
draft → active → completed → archived
```
- **active** — work in progress; workplan `status: active`; repo live in Gitea
and registered in the Hub.
- **completed** — all tasks done; completion record written (modified repos +
links).
- **archived** — repo archived in Gitea and `status: archived` in the Hub. The
workplan moves to `workplans/archived/` per the workplan convention. Results
persist in the product repos; the project repo is read-only history.
## Naming
Project repos MUST use the `prj-<kebab-slug>` prefix.
Exact naming, required files (`GOAL.md` instead of durable-product
`INTENT.md`), authority boundary, residual handoff, and archive procedure are
defined in:
`canon/standards/project-repository-flavor_v0.1.md`
That standard closes the naming open question previously deferred to
`CUST-WP-0050` (D1a). The illustrative `proj-` form mentioned in earlier drafts
is not used for new repositories.
## Consequences
- **Pro:** every workplan — including cross-repo ones — has a stable,
git-managed anchor; no hub-only orphans; the rebuild principle (ADR-001) holds.
- **Pro:** the classification standard applies uniformly; project repos are just
repos with `category: project`.
- **Pro:** clean, explicit lifecycle; results are never lost on retirement
because they live in the modified product repos.
- **Con:** proliferation of short-lived repos; requires discipline around the
naming and archival convention.
- **Con:** cross-references between the project repo and the product repos it
modified must be recorded deliberately, or the provenance trail degrades after
archival.
- **Con:** judgement is required on *when* an effort is "complex enough" to merit
a project repo versus a single-repo workplan; small cross-cutting changes
should not spawn a repo.
## Alternatives Considered
- **Bind to a "lead" product repo.** Rejected: distorts that repo's history and
creates ambiguous ownership.
- **Keep an optional hub-only topic for cross-repo coordination.** Rejected:
reintroduces the soft, non-git-managed spine that `CUST-WP-0050` removes and
ADR-001 discourages.
- **Multi-anchor workplan (array of repo_ids, no primary).** Rejected: breaks
single-anchor simplicity, ownership clarity, and lifecycle modelling.
## Related
- ADR-001 — Workplans and Work Items Are Repository Artefacts
- `CUST-WP-0050` — Repo Classification & State Hub Registration Redesign (D1)
- `canon/standards/repo-classification-standard_v1.0.md`

278
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-006.md Normal file
View file

@ -0,0 +1,278 @@
---
id: CUST-ADR-006
type: architecture-decision-record
title: "Canon Federation and Concept Ownership Across InfoTech and Commerce"
status: accepted
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-08-17"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-16"
accepted: "2026-08-17"
tags: ["architecture", "canon", "concept-ownership", "info-tech-canon", "commerce-canon", "identity", "orthogonality"]
---
# ADR-006: Canon Federation and Concept Ownership Across InfoTech and Commerce
## Status
Accepted 2026-08-17. All seven ownership questions are resolved (see
Resolutions); content may now move under `CFED-WP-0001`.
## Context
The ecosystem currently runs two independent canons in the same market domain
(`infotech`), with **no cross-reference in either direction**:
- `info-tech-canon` — InfoTechCanon, v0.6.0, status `service-baseline`. Kernel +
12 models + 3 standards, with declared concept ownership per model, an
orthogonality rule ("standards can import but not redefine each other"), and a
live CLI/JSON/API surface built on `infospace-bench`.
- `identity-canon` — documentation-only research repo, category `research`. Three
`IDENTITY-WP-*` workplans, all `finished`; no active work since the
commercial-identity research pass. ~60 concepts in
`canon/CanonicalGlossary.md`.
Two problems follow.
**Concept-ownership collision.** `InfoTechCanonOrganizationModel` (`:55`)
declares ownership of `Actor, Person, Organization, OrganizationalUnit, Team,
Group, Role, Position, Membership, Assignment, Responsibility, Authority,
Accountability`. `InfoTechCanonAccessControlModel` (`:106`) declares `Subject,
Principal, AccessRole, Permission, ...`. identity-canon independently defines
`Actor, Natural Person, Collective Actor, Organization, Group, Role, Membership
Relationship, Authenticated Subject, Authorization Principal`. Two canons claim
the same concepts — exactly what InfoTechCanon's orthogonality rule exists to
prevent.
**An unowned gap.** `InfoTechCanonAccessControlModel` (`:214`, "Boundary with
Identity and Authentication") explicitly pushes identity provisioning,
authentication factors, identity proofing, and account lifecycle out of scope,
and `:41` does the same for generic organization modelling. So `Account,
Identity Record, Identifier, Credential, Claim, Persona, Tenant, Realm,
Synonymity Assertion, Assurance Level` belong to no model at all.
**Business semantics are accumulating in the wrong places.** Roughly a third of
identity-canon's glossary is not identity but counterparty/commercial modelling
(`Legal Entity, Beneficial Owner, Customer, Vendor, Commercial Commitment,
Payment Mandate, Pipeline Pursuit, Counterparty Assurance Gradient, ...`) —
hence the repo's `government` secondary domain. Independently,
`info-tech-canon/demand/CapabilityProvisionEconomics.md` (status `accepted`,
2026-08-15) records procurement and economics demand arriving in `ITC-CAP` from
consumer `resource-control`, domain `financials`. Two unrelated donors pushing
commercial semantics into technical canon is a domain boundary, not a
coincidence. InfoTechCanon's own Purpose/Demand extension names this
`ScopePressure`.
## Decision
**1. Three canons, federated by declared ownership.**
| Canon | Owns | Repo |
|---|---|---|
| Custodian canon | ecosystem-normative governance: constitution, values, standards, ADRs, charters | `the-custodian/canon/` |
| InfoTechCanon | semantics of information-processing systems | `info-tech-canon` |
| CommerceCanon | counterparty and commercial-relationship semantics | `commerce-canon` |
Canons import but do not redefine each other's concepts, applying InfoTechCanon's
existing orthogonality rule one level up.
**2. `identity-canon` is renamed to `commerce-canon`, in place.** Git history,
State Hub registration, `.repo-classification.yaml`, and the finished
`IDENTITY-WP-*` workplans are retained as provenance for the commercial content
that stays. Identity content emigrates; nothing is archived. Structure follows
`info-tech-canon` (`canon.yaml`, `infospace/` with kernel/models/standards,
`assimilation/`, `mappings/`, `profiles/`) per
`InfoTechCanonRepositoryLayoutStandard`.
**3. Identity becomes an InfoTechCanon model**, at
`infospace/models/identity/InfoTechCanonIdentityModel.md` (`itc-ident`),
importing rather than redefining upstream concepts. This fills the gap
`InfoTechCanonAccessControlModel:214` leaves open.
**4. Concept ownership is assigned as follows.**
*Imported by `itc-ident`, owned by `itc-org`:*
`Actor` · `Natural Person` → `Person` · `Artificial Agent` → `Agent` ·
`Organization` · `Group` · `Role` · `Membership Relationship` → `Membership`
*Imported by `itc-ident`, owned by `itc-access`:*
`Authenticated Subject` → `Subject` · `Authorization Principal` → `Principal`
This follows identity-canon's own design principles: P1 makes `Actor` the
participation root (owned upstream by `itc-org`), and P6 "Keep Authorization
Projections Separate" already treats subject/principal as projections rather
than identity-owned definitions.
*Owned by `itc-ident` (new):*
`Account` · `Service Account` · `Identity Record` · `Identifier` ·
`Scoped Identifier` · `Pseudonymous Identifier` · `Credential` · `Claim` ·
`Profile` · `Persona` · `Tenant` · `Realm` · `Synonymity Assertion` ·
`Lifecycle State` · the actor-linking relationship taxonomy
(`Relationship`, `Affiliation`, `Following`, `Representation`, `Delegation`,
`Administration`, `Trust`) · convenience terms `User`, `Subscriber`
*Owned by `commerce-canon`:*
`Legal Entity` · `Legal Person` · `Beneficial Owner` ·
`Beneficial Ownership Relationship` · `Beneficial Ownership Exemption` ·
`Customer` · `Vendor` · `Commercial Relationship` · `Commercial Commitment` ·
`Payment Instrument Reference` · `Payment Mandate` · `Pipeline Pursuit` ·
`Commercial Record` · `Counterparty Assurance Gradient` · `Reputation Signal` ·
`Performance Evidence` · `Registry Identifier` ·
`Proxy Commercial Identifier` · convenience terms `Reputation`,
`Customer Account`
*Owned by `itc-evid`, the evidence model (see R3, R5, R7):*
`Evidence` · `Evidence Source` · `Adjudication Outcome`
Identifier subtypes demonstrate the intended pattern: `itc-ident` owns
`Identifier`; `commerce-canon` owns `Registry Identifier` and `Proxy Commercial
Identifier` as specializations of it.
**5. CommerceCanon grows by demand signal, not speculative authoring.** New
content enters through the mechanism InfoTechCanon already runs — a demand
signal with named consumer evidence (see `demand/`). Plausible future consumers
(`fin-hub`, `target-revenue`, `adaptive-pricing`, `qonto-assistant`) must pull;
the canon does not push.
**6. The Federated Organization Standard stays in Custodian canon.**
`canon/standards/federated-organization-standard_v1.0.md` is ecosystem-normative
organizational architecture, human-gated — not commercial vocabulary. If it ever
moves, it becomes an InfoTechCanon organization standard, not a CommerceCanon one.
## Resolutions
The six collisions listed at draft time, resolved 2026-08-17. Two were settled
by evidence already present in the models rather than by argument.
**R1 — `Scope`: owned by `itc-ident`.** There is no head-on collision:
`itc-access` owns `ResourceScope` (`:717`, "the boundary within which access
applies"), a narrower concept, not a general `Scope`. `itc-ident` owns the
general concept, keeping it with `Tenant` and `Realm` — `Tenant` is defined as
"an administrative or isolation scope", so separating it from its genus would
split a definition from the concept it depends on. `itc-access` keeps
`ResourceScope` as a refinement.
If `landscape` or `information-space` later need general scoping, promote
`Scope` to the kernel **on that demand signal**, not pre-emptively.
**R2 — `Assurance Level`: owned by `itc-ident`, distinct from governance
assurance.** A false collision. `itc-gov` owns `AssuranceCase` (`:1178`, a
structured argument that a claim is justified) and `AssuranceConclusion`
(`:1184`). identity's `Assurance Level` is NIST SP 800-63-4 IAL/AAL/FAL —
graded confidence metadata on credentials, bindings, and federation assertions.
They share an English word and nothing else. Both models carry a disambiguation
note, because the word will keep causing this.
Design principle P12 ("Distinguish Assurance Dimensions") carries over: IAL,
AAL, and FAL must not be collapsed into a single "trust level" on an account.
**R3 — `Evidence` and `Evidence Source` are a general pair, owned together, and
not by commerce.** They are not competing definitions of one concept:
- **Evidence Source** — an addressable information container: a document, file,
or other artifact identifiable by URI.
- **Evidence** — a distinct information item, textual or descriptive, drawn from
a source: a quotation, an extracted value, a specific assertion.
Both may carry commentary. Which evidence is captured from a source depends on
the interest being served.
Worked example: an invoice PDF is an Evidence Source; the amount, the issuer,
and the due date are separate Evidence items within it. The common electronic-
invoicing pattern of an XML embedding inside a signed PDF is exactly this
structure — evidence pre-extracted and bound to its source so the extraction is
itself tamper-evident.
The pair is domain-neutral (it extends to criminal, regulatory, and scientific
evidence). Commerce, identity, and governance all **use** it; none owns it.
Consequently `itc-gov` no longer owns `Evidence`; it imports it.
**R4 — `Relationship Tuple`: owned by `itc-access`.** Already modelled there
(`:549`, under `PolicyEvaluationEntity` beside `AuthorizationRequest`,
`AuthorizationDecision`, `DecisionReason`, `EvaluationContext`). identity-canon's
own entry agrees: "Relationship tuples are not canonical identity roots. They
project from actors, accounts, memberships, and delegations into authorization
domains." `itc-ident` must not define it.
**R5 — `Adjudication Outcome`: follows R3, owned with the evidence pair.** Not
`itc-access` `AuthorizationDecision` (a PDP allow/deny, `:907`) and not `itc-gov`
`Decision` (a governance choice point). The concept is general rather than
commercial: an arbitration award, court judgment, or regulatory consent order is
evidence in employment, licensing, or compliance disputes as much as in
commercial ones. Commerce is a consumer, not the owner.
Structurally it is **Evidence** — the outcome asserted — sourced from an
Evidence Source such as the judgment document.
The `assurance_tier` dimension splits accordingly: the evidence model owns a
general evidence-strength dimension; `commerce-canon` owns the
`Counterparty Assurance Gradient` as its named four-tier application of it.
**R6 — `Community` and `Household` extend `itc-org`; `Family` is a separate
concept area.** identity-canon defines "Family Or Household" as one entry. That
conflation is rejected.
`Community` and `Household` are collective actors and slot under `itc-org`'s
existing `CollectiveActor` (`:363`, beside `Person`, `HumanActor`,
`NonHumanActor`), honouring P4 ("Model Collective Actors Without Collapsing
Them").
`Family` does not. Family carries substantial structure — kinship, guardianship,
dependency, care, and legal, biological, and social parenthood — which changes
over time and is subject to interpretation. Modelling it as one more collective
actor is the specific mistake most family-oriented software makes, and it is why
such software generally models families badly. It gets its own concept area.
Scope discipline applies: the family area is **seeded, not authored**. Record the
concept, the privacy sensitivity already flagged in identity-canon ("may have
legal implications outside the canon's scope"), and the open modelling
questions. Do not build it out inside `CFED-WP-0001`; it grows on demand signal
like any other canon content.
**R7 — the evidence pair lives in a dedicated model, `itc-evid`.** A new
InfoTechCanon model at `infospace/models/evidence/` owns `Evidence`,
`Evidence Source`, `Adjudication Outcome`, and the general evidence-strength
dimension.
`itc-gov`, `itc-ident`, and `commerce-canon` import it. Three named consumers
existed before the model did, which is the demand signal the canon requires.
Rejected alternative: leaving both with `itc-gov` as incumbent owner of
`Evidence`. That is cheaper and preserves the locality of the
Policy-Control-Evidence chain pattern (`:1391`), but it would force identity and
commerce to import "governance" in order to describe an invoice line item —
mis-signalling evidence as a governance sub-topic when it is domain-neutral.
`itc-gov` retains `AssuranceCase`, `AssuranceConclusion`, `Audit`, and the
Policy-Control-Evidence pattern, now expressed over imported evidence concepts.
## Consequences
**Positive.** Every concept gains exactly one owner. The identity gap that
`itc-access` explicitly declines is filled. Commercial semantics get a home
before they accrete further into technical canon. A dormant research repo with
no inbound references becomes a canon with declared consumers. A second canon
tests whether `InfoTechCanonRepositoryLayoutStandard` is a real standard or
merely InfoTechCanon's own shape described back to itself.
**Negative.** This is a concept-ownership reconciliation, not a file move: the
first ~15 glossary entries must be rewritten as imports. Three canons cost more
coordination than one. The `identity-canon` name disappears from tooling,
bookmarks, and any external reference.
**Risks.** CommerceCanon could repeat identity-canon's failure mode — dormant,
zero consumers, drifting — if it launches as a scaffold. Mitigated by decision 2
(it opens holding real, research-backed content) and decision 5 (growth requires
consumer evidence).
## References
- ADR-001 — workplans originate as repo files; hub is a read model
- ADR-005 — cross-repo workplans live in dedicated project repos
- `info-tech-canon/infospace/models/organization/InfoTechCanonOrganizationModel.md:55`
- `info-tech-canon/infospace/models/access-control/InfoTechCanonAccessControlModel.md:106`, `:214`
- `info-tech-canon/infospace/models/governance/InfoTechCanonGovernanceModel.md:107`
- `info-tech-canon/demand/CapabilityProvisionEconomics.md`
- `identity-canon/canon/CanonicalGlossary.md`, `canon/DesignPrinciples.md`

324
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-007.md Normal file
View file

@ -0,0 +1,324 @@
---
id: CUST-ADR-007
type: architecture-decision-record
title: "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology"
status: accepted
owner: the-custodian
revision: "accepted-2"
last_reviewed: "2026-08-31"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-16"
accepted: "2026-08-17"
tags: ["architecture", "workplans", "identity", "state-hub", "repo-manager", "agents", "registrar"]
---
# ADR-007: Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology
## Status
Accepted 2026-08-17. Identifier uniqueness, the registrar model, lifecycle
protection, and worker topology are settled.
**Remediation of existing collisions (§ Migration) remains an open ruling.** It
is disruptive, touches six repositories, and no active work depends on it — all
five duplicated identifiers are `finished`.
## Context
On 2026-08-16, `STATE-WP-0080` was found registered **twice, in two different
databases**, with two different workplan UUIDs and two disjoint sets of task
UUIDs:
| Registrar | Workplan UUID | Reachable at `127.0.0.1:8000` |
|---|---|---|
| Workstation hub (`make api`, local postgres) | `03f38314` | yes |
| A second instance, over a second database | `bbfce36a` | **404** |
The second instance is *not* identifiable from the commit author.
`custodian-sync@railiance.local` is a hardcoded default git identity in
`scripts/consistency_check.py:1899` (`GIT_SYNC_USER_NAME` /
`GIT_SYNC_USER_EMAIL`), so every machine running `fix-consistency` commits under
that name. The discriminator is the timezone: sync commits appear under both
`+0000` and `+0200` (the workstation's offset), which is independent evidence of
two machines writing to one repository.
Both write their IDs into the same git-tracked workplan file, so each sync
overwrites the other's IDs and the file flip-flops on every round trip. The same
commit (`ff909e1`, "renormalize lifecycle state [auto]") also promoted the
workplan `proposed` → `active` without human review.
A fleet scan of 955 hub workplans (525 with parseable `PREFIX-WP-NNNN`
identifiers) found this is not an isolated incident. Two distinct identity
defects are live:
**Prefix reuse across repositories:**
```text
CUST-WP- → state-hub, the-custodian
RAIL-BS-WP- → railiance-bootstrap, railiance-cluster
RAILIANCE-WP- → railiance-apps, railiance-forge, railiance-platform, railiance-telemetry
```
`PRJ-WP-` is a latent fourth: `statehub register` derives it from the `prj-`
flavor marker, so every project repository would collide (see `RMGR-WP-0004`).
**Running-number reuse:**
```text
CUST-WP-0000 the-custodian ×2
CUST-WP-0010 the-custodian ×2
CUST-WP-0045 the-custodian ×2
RAILIANCE-WP-0015 railiance-platform, railiance-apps
RAILIANCE-WP-0016 railiance-platform ×2, railiance-apps
```
`RAILIANCE-WP-0015` is actively cited in operational memory as the cnpg-backup
gate in `railiance-apps`; a second record of the same name in
`railiance-platform` makes that citation ambiguous.
The `C-26` consistency check already flags prefix nonconformance *within* a repo
against a canonical prefix, but nothing enforces uniqueness *across* repos, and
nothing prevents number reuse.
## Decision
**1. A workplan identifier is globally unique.** `PREFIX-WP-NNNN` names exactly
one workplan across the entire fleet, for all time.
> **Amended 2026-08-17 by `ADR-011` decision 2.** Uniqueness and forward-only
> allocation are **namespace-scoped**, not global; global identity is the pair
> `(namespace, identifier)`, written `PREFIX-WP-NNNN@namespace` when foreign.
> Global sequential allocation would require a central coordinator — the exact
> dependency federation must survive. Everything below holds unchanged **within**
> a namespace, which is where all current work sits.
- A workplan prefix is owned by exactly one repository. No two repositories may
use the same prefix.
- A running number is never reused within a prefix, including after a workplan is
cancelled, archived, or deleted. Numbers are allocated forward only.
- Prefixes are derived from the *project or repository identity*, never from a
flavor marker or category (`PRJ-WP-` is invalid by construction).
**2. Hub identifiers stored in repository files must be derivable, not
database-local.** The defect is structural: a database-local key is stored in a
shared artifact, so each database overwrites the other's value on every sync.
It also inverts ADR-001 — a file carrying a hub's private key is the file
holding hub state.
*Target state (C2).* `state_hub_workstream_id` and `state_hub_task_id` become
**deterministic**: UUIDv5 derived from the workplan identifier. Per `ADR-011`
decision 3 the derivation input is the pair `(namespace, identifier)`, not the
identifier alone — deriving from the identifier alone would make two forks
holding unrelated work under the same number compute the same UUID. Every instance computes the same value independently, writeback
becomes idempotent, and any number of hub instances may coexist without
coordination. The field shape is unchanged, so consumers keep working; only the
provenance of the value changes.
This has a hard prerequisite: deterministic derivation from a **non-unique**
identifier would manufacture collisions rather than remove them. Two project
repos sharing `PRJ-WP-` would compute the same UUID for different workplans.
Decision 1 must therefore be enforced before derivation ships.
*Interim state (A).* Until derivation lands, exactly one instance writes hub
identifiers into repository files. Other instances may read, project, and serve,
but must not mint workplan or task UUIDs into git-tracked files.
> **Corrected 2026-08-17, superseded by `ADR-010` decisions 1–3.** This decision
> originally described workstation hubs as "development read replicas". That was
> wrong on both counts: the workstation instance was not a replica, and it was
> the *larger* of the two, holding 306 more workplans than the primary. The two
> instances were peer databases. `ADR-010` establishes the central hub as
> authoritative and local instances as rebuildable caches, which is what makes
> this interim rule coherent.
The interim is policy, enforced by discipline, and it has a real cost:
registration requires connectivity to the registrar, so disconnected work cannot
register. That cost is accepted only until C2 removes the need for it, at which
point the number of hub instances becomes an availability choice rather than a
correctness constraint.
*Rejected.* Collapsing to a single shared database (workstation hubs pointing at
the production database) would also make identifiers consistent by construction,
but it eliminates offline capability — cutting directly against `STATE-WP-0068`
(offline write buffer and edge relay) — and couples all local work to tunnel
availability.
*Ownership.* Both the interim guard and the derivation belong to `repo-manager`
under decision `747011c6`, which already places file-backed record indexing and
reconciliation there. Building either in `state-hub` would invest in a component
being retired under `STATE-WP-0079`.
Migration scope for C2: **758 workplan files** across the fleet currently carry
these fields.
> **Amended 2026-08-21 — derivation scope for C2.** `ADR-011` decision 7 keys
> derivation on `(namespace, identifier)`, which separates *forks*. It does not
> separate collisions inside one namespace, and the ecosystem's posture is `N1`
> — a single implied namespace. A fleet scan on 2026-08-21 found **20 reused
> identifiers across 48 files**, all within that one namespace, so the
> prerequisite above is not satisfied by `ADR-011` alone.
>
> Ruled: **C2 derives only for live records; archived records keep their minted
> identifiers, frozen.** This is what reconciles § Migration option 2 — under
> which historical files keep colliding identifiers — with the uniqueness
> derivation requires. Of the 20, only **five** collide among live files, so the
> remediation surface is 11 files rather than 48.
>
> Two consequences follow, and both are load-bearing:
>
> 1. **Un-archiving a record with a frozen identifier is a collision hazard.**
> A record returning to live status must be checked against the live
> namespace before it is re-derived, and renumbered if it clashes.
> 2. **Derivation is not retroactive.** Existing live records keep their minted
> UUIDs until they are re-derived deliberately; C2 changes provenance for new
> and re-registered records, not the whole corpus at once.
>
> Rejected: treating a *repository* as the namespace. That would make the
> collisions vanish by construction, but it redefines the term `ADR-011`
> decision 1 fixes as "a fleet instance, a client deployment, an autonomous
> domain", and `ADR-011` decision 9 warns specifically against reading N-plane
> movement into claims it does not support.
**3. Lifecycle status is not automatically promoted.** An automated
normalization pass may report drift; it may not move a workplan from `proposed`
to `active`. `proposed` means awaiting human review, and an automation that
promotes it destroys the meaning of the review gate.
**4. Repository manipulation is performed by a worker agent in that
repository.** This is the default topology.
- A worker acting in repo X owns changes to repo X.
- Multiple independent top-level workers inside a single repository are an
**exception**, requiring an explicit reason, not a routine mode of operation.
- Concurrent independent writers are what turned a two-registrar bug into
repeated git divergence.
**5. Project (`prj-`) repositories may act across their participating
repositories.** When work is governed by a project repo, its tasks may direct
changes across every repository the project names, through the project's work
agent, where that is more efficient than delegating.
This is a deliberate, scoped exception to decision 4: the project repo already
owns cross-repo sequencing and its `SCOPE.md` names its participants, so its
authority is declared rather than ad hoc. It does not license a worker in an
arbitrary repository to reach into others.
## Consequences
**Positive.** Workplan identifiers become citable without qualification.
Hub IDs stop flip-flopping in git. The `proposed` status regains meaning.
Cross-repo authority becomes something a repository declares rather than
something any session assumes.
**Negative.** Existing collisions must be remediated (see below), which is
disruptive. Workstation sessions lose the ability to register workplans directly
and must route through the registrar or a worker in the owning repo. Prefix
allocation needs a fleet-level registry, which is new machinery.
**Enforcement.** Prefix ownership, uniqueness, and forward-only numbering are
repository standards, so they belong to Repo Manager under decision `747011c6`
(`RMGR-WP-0004`), not to a hub. Canon defines the rule; Repo Manager checks it.
## Migration — needs a separate ruling
Three prefixes and five identifiers are already colliding. Remediation options,
in increasing cost:
1. **Freeze and forward-fix.** Accept existing collisions as historical, enforce
uniqueness only for new workplans. Cheapest; leaves `RAILIANCE-WP-0015`
permanently ambiguous.
2. **Renumber the live collisions only.** Fix identifiers that are still cited or
active; leave `finished`/`archived` duplicates alone.
3. **Full renaming.** Give `railiance-apps`, `railiance-forge`,
`railiance-platform`, `railiance-telemetry` distinct prefixes, likewise
`railiance-bootstrap`/`railiance-cluster` and `state-hub`'s legacy `CUST-WP-`
files. Touches six repositories and every inbound reference.
**Ruled 2026-08-17: option 2.** Renumber live collisions; leave
`finished`/`archived` duplicates as historical record.
### The live renumber list is empty
Verified against the fleet scan. All five duplicated identifiers are `finished`:
```text
CUST-WP-0000 the-custodian ×2 finished
CUST-WP-0010 the-custodian ×2 finished
CUST-WP-0045 the-custodian ×2 finished
RAILIANCE-WP-0015 apps, platform finished
RAILIANCE-WP-0016 apps, platform ×2 finished
```
No workplan in a `proposed`, `ready`, `active`, `blocked`, or `backlog` state
shares an identifier with another. **Option 2 therefore requires no renumbering
today.** Historical duplicates stay, including the `RAILIANCE-WP-0015` ambiguity
between `railiance-apps` and `railiance-platform`; citations of it must name the
repository.
### The structural cause is not historical
Option 2 governs *remediation*. It does not exempt anything from decision 1,
which is accepted canon: one prefix, one repository, forward-only numbering.
Three shared prefixes are still in use across seven repositories, and each is a
**single number line being allocated from concurrently**:
```text
RAIL-BS-WP- bootstrap 8, 9
cluster 7, 10, 11, 12, 13, 14
RAILIANCE-WP- platform 5, 8-17 (16 twice — an internal duplicate)
apps 15, 16 <- already collided with platform
forge 2
telemetry 1
CUST-WP- the-custodian 50 plans
state-hub 4 legacy plans (canonical prefix is STATE-WP)
```
`RAIL-BS-` and `RAILIANCE-` are actively growing — `RAIL-BS-WP-0014` (`ready`),
`RAILIANCE-WP-0002` (`ready`), `RAILIANCE-WP-0001` (`proposed`), all created
2026-08-11 or later. The `RAILIANCE-WP-0015`/`0016` collisions were not a
historical accident; they are what concurrent allocation from a shared sequence
produces, and it will recur at the next concurrent allocation.
`CUST-` is dormant on the `state-hub` side — four legacy plans, one in
`backlog` — and needs no split, only a prefix-ownership assertion.
### Prefix assignments
`RAIL-BS-WP-` is **retired** (2026-08-17). Neither repository keeps it:
`railiance-cluster` adopts `RCLUSTER-WP-` for active and future plans;
`railiance-bootstrap` adopts `RBS-WP-` for future plans. Finished and archived
files keep `RAIL-BS-WP-` as historical record, consistent with option 2.
Migrating plans keep their running numbers — the prefix changes, the number does
not. This preserves traceability and cannot violate forward-only allocation,
because neither new prefix has prior history. `railiance-bootstrap` begins at
`RBS-WP-0010`, above its historical maximum, leaving the lower range free should
its finished plans ever be adopted into the new prefix.
`RAILIANCE-WP-` should follow the same pattern — retired rather than awarded to
one repository, since it names a family rather than a repository and so fails
decision 1 for the same reason `PRJ-WP-` does. Assignment of the four successor
prefixes is outstanding.
Execution of each rename belongs to a worker in the owning repository under
decision 4. `RMGR-WP-0004-T09` records assignments and the numbering rule; it
does not perform renames.
**Consequence.** Prefix ownership must be assigned for all three shared prefixes
before the next workplan is created in the affected repositories. This is
forward conformance under decision 1, not migration, and is tracked as
`RMGR-WP-0004-T09`. Renaming the *historical* files is explicitly not required —
that would be option 3, which was rejected.
## References
- Decision `747011c6` — repository standards belong to Repo Manager
- ADR-001 — workplans originate as repo files; hub is a read model
- `RMGR-WP-0004` — repository standards conformance and governed scaffolding
- `STATE-WP-0080` — register scaffolding handoff
- Fleet scan 2026-08-16: 955 hub workplans, 525 parseable identifiers,
3 reused prefixes, 5 reused identifiers

271
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-010.md Normal file
View file

@ -0,0 +1,271 @@
---
id: CUST-ADR-010
type: architecture-decision-record
title: "Hub Authority, Local Cache, and the Two Kinds of Hub Data"
status: proposed
owner: the-custodian
revision: "draft-2"
last_reviewed: "2026-08-31"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-17"
tags: ["architecture", "state-hub", "repo-manager", "hub-core", "authority", "cache", "offline", "adr-001"]
---
# ADR-010: Hub Authority, Local Cache, and the Two Kinds of Hub Data
## Status
Proposed, and **partially superseded by `ADR-012`** (accepted 2026-08-25).
Decisions 1, 5 and 6 are sharpened or given a mechanism there; see the notes on
each below. Everything else in this ADR remains in force.
## Context
Investigating a workplan-identifier flip-flop (`ADR-007`) revealed that two
State Hub instances were operating as **peer databases**, not as a primary and a
replica:
| Address | Instance | Workplans |
|---|---|---|
| `127.0.0.1:8000` (IPv4) | local uvicorn on docker postgres | 955 |
| `[::1]:8000` (IPv6) | ssh tunnel `state-hub-primary` → railiance01 | 649 |
Both listen on port 8000, separated only by IP family, so every tool defaulting
to `127.0.0.1` reached the local instance while believing it was the primary.
> **Mechanism identified 2026-08-24 by `CUST-WP-0067`.** This ADR recorded the
> shared port as the hazard but not why it was *silent*, which is the part that
> let it persist. An `ssh -L` forward with no bind address listens on every
> loopback family, and `ExitOnForwardFailure=yes` fires only when **every**
> requested bind fails. The IPv4 bind lost to the local uvicorn, the IPv6 bind
> succeeded, and the tunnel therefore reported success while serving an address
> nothing resolved to by default. The collision was declared in
> `~/.config/bridge/tunnels.yaml`, and `ops-bridge` guarded only tunnel against
> tunnel, so a non-bridge listener was invisible to it.
>
> Fixed by pinning local forwards to `127.0.0.1`, so a contested port fails
> loudly (`ops-bridge` commit `2213847`). A shared port is recoverable; a shared
> port that reports healthy is not.
Measured divergence — 320 records exist locally but not on the primary:
```text
backed by a file that exists on disk 288 fully rebuildable
no backing file recorded 28 not rebuildable as-is
same filename, different UUID 4 duplicate registration
```
**No file was missing for any of the 288.** The divergence is therefore almost
entirely redundant: it can be discarded and rebuilt from repositories without
losing anything.
`ADR-001` already says work originates as repository files and the hub is a read
model. The two-peer-database situation contradicts that in practice: a second
database accumulated 306 net records of its own.
## Decision
**1. One authoritative hub, deriving from repository files.** The central State
Hub — running on railiance — is authoritative. It is authoritative *as a reading
of the repositories*, not as a second place data lives. Repository files remain
the source of truth (`ADR-001`).
> **Sharpened 2026-08-25 by `ADR-012` decision 1.** "A reading of the
> repositories" never said *which* copy of them, and the honest answer was
> neither the forge nor any particular working copy: the projection derived from
> whichever checkout last ran the sync. The hub holds no repository files at all
> and never reads one. `ADR-012` names the forge as the projection source.
**2. A local hub is a cache, never a database.** Local instances hold a
rebuildable projection. A cache may be discarded and reconstructed from the
repositories at any time, and losing it must never lose work.
This replaces the peer-database arrangement. It is also why the divergence is
tractable: a divergent database is a merge problem, a stale cache is a refresh
problem.
> **Corrected 2026-08-24 by `CUST-WP-0067`.** Those two shapes are not
> exhaustive, and repository records took a third one. Measured that day:
> 122 repositories on the cache, 78 on central, **zero central-only**. A strict
> subset in the cache's favour is neither a merge problem nor a refresh problem
> — refreshing the cache would have *destroyed* the 44 extra records rather than
> reconciling them, and central held no path to re-derive repositories it had
> never been told existed.
>
> The third shape: **cache-only records whose authoritative source exists and is
> reachable, but was never introduced to central.** Its remedy is re-derivation
> from source — not refresh, not merge. Of the 44, 43 had a working copy, all 43
> were pushed, and 34 carried a classification file; nothing was unrecoverable,
> but nothing would have recovered itself either.
>
> Onboarding by date showed a clean break: central's repository registrations
> stopped at 2026-07-08 while the workstation kept accepting them.
**3. Local work requires no hub at all.** Repository files are self-describing —
identifier, status, tasks, all in frontmatter. Working in a repository requires
reading files, not querying an index. A cache is an optimization for cross-repo
questions, never a prerequisite for doing work.
**4. Hub data is classified by origin, and the two kinds have opposite rules.**
| | File-derived | Hub-native |
|---|---|---|
| Examples | workplans, tasks, statuses, dependencies | progress events, decisions, inbox messages, token events |
| Source of truth | the repository file | the hub |
| Offline behaviour | write the file and commit — the commit *is* the write | buffer locally, replay when reachable |
| Conflict model | **none**; conflicts are git conflicts, resolved in git | **none**; append-only merges regardless of order |
| Central accepts pushes? | no — it derives | yes |
Neither kind needs a hub-side conflict model. That is the point of the split: if
central derives file-backed state, it cannot hold a conflicting version of it —
it re-derives whatever git settles on. Two people editing one workplan is a git
conflict and belongs to git.
**5. Central derives file-backed state; it does not accept pushes of it.**
"Authoritative" means authoritative *reading*, so nothing may inject derived
state directly. Hub-native records are the exception and keep a real write path.
> **Sharpened 2026-08-25 by `ADR-012` decision 6.** This was policy, not
> practice: nothing derived, and the workstation pushed everything. `ADR-012`
> retires push-based sync as the primary path so that "central derives" becomes
> true rather than aspirational.
**6. Preliminary until confirmed.** Locally registered data and uncommitted
repository state are preliminary until the central service has seen them.
Mitigation is by changing the repository files and the local cache — never by
editing central to match a local view.
> **Given a mechanism 2026-08-25 by `ADR-012` decisions 3 and 4.** "Preliminary"
> was named here but never built, so in practice locally registered data was
> indistinguishable from derived state once it arrived. It is now a labelled
> overlay within the same projection — explicitly not a second store — and it
> retires when the commit carrying it reaches the forge. The prohibition on
> editing central to match a local view is unchanged.
Combined with `ADR-007` decision 2 (identifiers derived from `PREFIX-WP-NNNN`),
"preliminary" largely stops mattering: a cache computes the same identifier
central will, so offline-registered data is already correct on arrival and needs
confirmation rather than reconciliation.
**7. Every record has exactly one authoritative hub.** The State Hub retirement
splits one hub into several. Multiple central hubs are permitted only under this
rule: the owning hub is determined by the record's repository and domain. Without
it, the same peer-database divergence recurs at larger scale.
**8. Cache reads are advisory and must carry their age.** Cross-repo answers from
a cache are advisory and should be presented with staleness. For the repository
an agent is working in, the file is truth and the cache is never consulted for
correctness.
## Orphan disposition
The 28 records with no backing file are the only ones a cache rebuild would drop.
They fall into three classes, to be separated before any rebuild:
1. **Broken links** — a file exists but `backing_filename` was never recorded.
`RMGR-WP-0004` is one: the workplan file exists and is committed. These are
metadata repairs, not data loss, and are likely the largest class.
2. **Live hub-first records** — `proposed`, `ready`, or `backlog` with no file,
in `activity-core`, `core-hub`, `hub-core`, `issue-core`, `ops-hub`,
`prj-forgejo-org-refactor`, `railiance-enablement`, `railiance-infra`,
`reef-railiance`. Each needs a repository file written or an explicit drop.
These are `ADR-001` violations and must not be preserved as hub-only records.
3. **Closed hub-first records** — `finished` or `archived` with no file. Retain
as historical provenance where cheap; do not reconstruct plans that are done.
A cache rebuild enforces `ADR-001` retroactively: the only casualties are records
that broke it.
## Consequences
**Positive.** The divergence becomes discardable rather than mergeable. Offline
work is fully supported without a write buffer for file-backed state — the git
commit is the write. No hub-side conflict model is needed for either data kind.
Authority stops being a policy claim and becomes a structural property.
**Negative.** The 28 orphans require case-by-case disposition before a rebuild.
Any consumer that treats a local hub as authoritative must be corrected. The
one-hub-per-record rule constrains the retirement's hub split.
**Rescoping.** `STATE-WP-0068` (offline write buffer and edge relay) is scoped as
a single mechanism. Under decision 4, most of what it buffers does not need
buffering — only the append-only hub-native stream does. Its scope should be
re-examined before more is built on it; this may reduce work rather than add it.
**Correction to `ADR-007`.** Decision 2 there calls the workstation instance a
"development read replica". It was neither a replica nor smaller — it held 306
more workplans than the primary. Superseded by decisions 1–3 here.
## Implementation
Owned by `repo-manager` for file-derived state (decision `747011c6`; it already
owns repository representation, file-backed record indexing, and reconciliation)
and by `hub-core` for hub-native records. Tracked under `RMGR-WP-0005`.
## References
- ADR-001 — workplans originate as repo files; hub is a read model
- ADR-007 — identifier uniqueness, derived identifiers, worker topology
- Decision `747011c6` — repository standards belong to Repo Manager
- `RMGR-WP-0005` — registrar consolidation and deterministic identifiers
- `STATE-WP-0068` — offline write buffer and edge relay (rescope candidate)
- Divergence measurement, 2026-08-17: 955 local / 649 primary / 320 local-only
## Outcome (2026-08-24)
> Added by `CUST-WP-0067`. This ADR read as though its remediation had landed.
> It had not: the two-instance condition it measured on 2026-08-17 was still
> live seven weeks later, and had continued to accumulate records the whole
> time. An ADR that describes a fix in the present tense is easily mistaken for
> a fix that happened — worth stating plainly for the ones that follow.
The peer-database arrangement is now resolved, by deletion rather than by
reconciliation:
- **The local hub instance is retired.** Rather than making two instances
coexist safely, the second one was removed. Exactly one process binds
`127.0.0.1:8000` and it is the tunnel to central. Nothing remains that could
impersonate the primary, and no call site needed editing — retiring the
impersonator made the existing `127.0.0.1:8000` defaults correct.
- **Decision 3 carried the argument.** Because local work requires no hub at
all, and Repo Manager already maintains a file-derived index, the local
instance was redundant rather than load-bearing.
- **Repo Manager gained the write path it was already assigned.**
`hub-record-authority.yaml` gives it `managed_repos` as `file-derived`, but it
exposed no command for it; the only working path lived in the State Hub repo
and defaulted to a local address. `rmgr repo-onboard` closes that, and refuses
to onboard a repository whose backing file is uncommitted, unpushed, or has no
upstream — a record whose source is only local cannot be re-derived, which is
the failure this ADR exists to prevent.
- **33 of the 44 were re-derived onto central**, taking it from 78 to 111
repositories. The remaining 11 carry written dispositions rather than guessed
values, per the orphan-disposition principle above.
One cause sat deeper than the topology: the hub resolved its classification
allowed-values file from three hardcoded developer-workstation checkouts, so in
a container every classification write failed. Repository classification could
*only* be written from a workstation. That is a second instance of this ADR's
own theme — authority that depends on where a process happens to run is not
authority — and is why "central derives" had never been achievable for this
record type.
## Outcome (2026-08-28)
> Added by `CUST-WP-0068`. The 2026-08-24 outcome closed the *repository*
> divergence. The work-record divergence this ADR originally measured — 955
> local / 649 primary — remained, because the retired instance's database was
> still load-bearing. That is now closed.
- **Central holds 1167 workplans.** Records that existed only in the cache
were re-derived from their files, renamed onto the canonical scheme, or
given a written disposition (`docs/recovery/cache-only-disposition-2026-08-28.md`).
- **No open work record exists only in the cache.** Remaining cache-only
slugs are aliases of recovered records, clay-borg product files (not
workplans), or prefix-migration residue.
- **The cache database is discarded.** Final dump
`~/backups/state-hub-cache-2026-08-28.dump`. Container `infra-postgres-1`
and volume `infra_pg_data` removed. Port 5432 is free.
- **The local instance is no longer load-bearing for any record type.**
Decision 3 is now true in operation, not only in argument.

290
docs/evidence/2026-10-11-served-publication-history/sources/CUST-ADR-011.md Normal file
View file

@ -0,0 +1,290 @@
---
id: CUST-ADR-011
type: architecture-decision-record
title: "Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliation"
status: proposed
owner: the-custodian
revision: "draft-2"
last_reviewed: "2026-08-17"
review_interval: 6m
decided_by: Bernd Worsch
date: "2026-08-17"
tags: ["architecture", "federation", "namespace", "identity", "reconciliation", "posture", "fos", "adr-007", "adr-008", "adr-010"]
---
# ADR-011: Federated Namespaces — Four Planes, Declared Posture, and the Limits of Reconciliation
## Status
Proposed, draft-2. Amends `ADR-007` decisions 1 and 2; extends `ADR-010`
decision 4; adopts the plane/ladder/posture form and the accuracy-not-altitude
conformance rule from `ADR-008` (Multi-Tenancy Framework).
## Context
The ecosystem must be **federation-capable** — able to work without a live link
to central services — and **chain-of-command efficient**.
`federated-organization-standard_v1.0` already resolves the organizational half:
> global coherence is achieved through policy, escalation, and shared protocols
> rather than through monolithic control (`:51`)
>
> bounded autonomy plus disciplined coordination (`:86`)
Authority is a **policy** layer; availability is a **mechanism**. Distributed
version control makes the same separation: an integration branch is privileged by
agreement, never by a technical property.
**One accepted decision violates this.** `ADR-007` decision 1 requires running
numbers that are *globally* unique and allocated forward only. Global sequential
allocation requires a coordinator — precisely the central dependency federation
must survive. Two disconnected forks each allocating `RCLUSTER-WP-0015` is a
certainty, not an edge case.
This is not hypothetical. Instance-per-client tenancy (`CUST-WP-0058`) already
makes every client deployment a fork of the stack; the business model committed
to forking before the identifier scheme could express it.
### Why this draft changed form
Draft-1 stated federation as a set of binary rules — notably "records fork,
effects do not". That is a single verdict where a graduated declaration belongs,
and it is the same conflation `ADR-008` §03 diagnoses for multi-tenancy:
*"'Is this multi-tenant?' is treated as one question. It is four, and they are
independent."*
"Is this federation-capable?" is likewise not one question. A namespace can be
strong on identity and incapable of disconnected operation; it can operate
disconnected and have no way to reconcile afterwards. Draft-1 could not say so.
This draft reuses `ADR-008`'s vocabulary rather than inventing a parallel one.
Two competing maturity vocabularies in one canon would be its own collision.
## Decision
**1. Records live in a namespace.** A namespace is a federated branch of the
ecosystem — a fleet instance, a client deployment, an autonomous domain that may
operate disconnected. It is the unit of sovereignty in FOS terms and the unit of
divergence here.
**2. Federation is four orthogonal planes.**
| Plane | Question | Vocabulary owner |
|---|---|---|
| Namespace **N** | How are records named and disambiguated across branches? | this ADR |
| Autonomy **U** | Can work proceed with no link to central services? | repo-manager |
| Reconciliation **R** | What happens when branches meet again? | repo-manager |
| Substrate **S** | Does this namespace hold independently diverging operational state? | railiance-platform |
**3. Each plane carries a ladder.** Higher is stronger, not better. The right
level is the one a namespace can evidence and its risk warrants.
```text
N0 no namespace concept; identifiers assume one global space
N1 namespace implied by deployment, never recorded
N2 namespace declared; identifiers namespace-scoped; qualification available
N3 N2 + lineage recorded, and derived identifiers keyed on (namespace, identifier)
U0 routine work requires the central service
U1 degraded read-only; writes blocked while disconnected
U2 work proceeds locally: file-derived state written to files, hub-native buffered
U3 U2 + exercised — a dated disconnection drill with evidence
R0 no defined path; divergence is unrecoverable
R1 manual, per-record comparison and hand resolution
R2 append-only events plus derived state: union and re-derive, deterministic
R3 R2 + lineage-aware; distinguishes divergence from collision automatically
S0 shares operational substrate with another namespace — cannot fork safely
S1 shared substrate, namespace-keyed
S2 dedicated substrate, no independent state divergence yet
S3 independent operational substrate with diverged state — the fork is real
```
**4. A namespace declares a posture vector**, in the repository rather than the
hub, consistent with `ADR-010` decision 4 (file-derived state) and `ADR-008`
decision 5.1.
```yaml
federation:
current: { N: 1, U: 1, R: 1, S: 1 }
target: { N: 3, U: 2, R: 2, S: 1 }
reviewed: "2026-08-18"
gap:
U: "Registration requires the registrar under ADR-007 decision 2 interim.
Lifts when derived identifiers land (RMGR-WP-0005-T03)."
```
**The ecosystem's own posture today is `N1 U1 R1 S1`** — one implied namespace,
disconnected registration blocked, reconciliation manual, substrate shared.
Declaring that is conformant. Claiming better is not.
**5. Conformance is accuracy, not altitude.** Adopted verbatim in force from
`ADR-008` §06: a namespace is conformant when its declared posture is accurate,
its target recorded, and it claims no level it cannot evidence. It is
non-conformant when it overclaims, at any altitude.
Declaring `S0` is conformant. Concealing `S0` is not. A repository may join at
any posture; it may not join silently. This matters more here than it does for
tenancy: the cost of discovering a true posture during reconciliation is the
whole difference between T2 and T3.
**6. Identifiers are unique within a namespace, qualified across.** `ADR-007`
decision 1 is amended: uniqueness and forward-only allocation are
**namespace-scoped**. Global identity is the pair `(namespace, identifier)`.
```text
RCLUSTER-WP-0015 this namespace — the common case, unchanged
RCLUSTER-WP-0015@railiance01 a foreign namespace, explicitly qualified
```
Unqualified always means "in my own namespace", exactly as `main` does against
`origin/main`. A suffix preserves existing sorting, grep, and tooling; a prefix
would break them.
**7. Derived identifiers key on the pair.** `ADR-007` decision 2 (C2) derives
UUIDv5 from the identifier. Under federation the input must be
`(namespace, identifier)`. Deriving from the identifier alone would make two
forks holding unrelated work under the same number compute the *same* UUID — a
collision manufactured by the fix. C2 is not yet built, so this is free now and
expensive later.
**8. The planes couple at their upper levels. State the coupling; do not use it
to argue the planes are one.**
- `R3` requires `N3` — distinguishing divergence from collision requires lineage.
- A namespace may not sustain `U2` or above while below `R2`. Operating
disconnected without deterministic reconciliation accumulates divergence that
cannot later be merged. Autonomy without reconciliation is not federation; it
is an unplanned fork.
- `T3` is entailed by `S3` in any participant (decision 10).
**9. Anti-overclaim.** This is the most misusable fact in the framework, and it
is the direct analogue of `ADR-008`'s `P0 → P1 → P2` warning.
> Adopting namespace-qualified identifiers is movement on the **N plane only**.
> It buys disambiguation, citability, and coordinator-free allocation. It does
> **not** raise autonomy, reconciliation, or substrate independence by one step.
> A system at `N3 U0 R0 S0` cannot operate disconnected and cannot reconcile.
No namespace may be described as "federation-capable", "independently operable",
or "able to run disconnected" on N-plane evidence alone. Such a claim requires
declared `U` and `R` levels with evidence behind them.
**Commercially**, client-facing claims about instance independence must cite the
`S` and `U` levels, never the identifier scheme. Instance-per-client tenancy is
sold on substrate independence; the qualifier does not supply it.
**10. The reconciliation tier is derived from participants' postures, not judged
after the fact.**
```text
any participant at S3 -> T3 (regardless of other planes)
all participants S<=S2 and R>=R2 -> T2 feasible
any participant below R2 -> T1 at best; manual thereafter
```
This is the practical payoff of declaring postures: the cost of rejoining is
**computable before a fork is created**, rather than discovered when
reconciliation is attempted.
**11. Coexistence is the normal case; merging is the exception.** The qualifier
is primarily a coexistence mechanism, not merge preparation. Most forks — client
instances above all — are never intended to return. Permanent parallel operation
is a first-class outcome, not a failure to reconcile.
**12. Evidence.** A claimed level requires evidence, per `ADR-008` §13.
| Level | Evidence |
|---|---|
| `N2` | namespace declared in the repo; qualified references resolve |
| `N3` | lineage fields present; a derived identifier reproduced by an independent implementation |
| `U2` | work completed with central unreachable, committed, later accepted without rework |
| `U3` | dated disconnection drill record |
| `R2` | replaying the union of events reproduces identical derived state |
| `R3` | a collision and a divergence, correctly distinguished, in test |
| `S2` / `S3` | substrate inventory naming the stateful systems and whether their state has diverged |
**13. Guard.** Declared postures regress silently. Posture is checked by the same
consistency machinery that checks repository standards (`RMGR-WP-0004-T02`,
`rmgr conform`), so a namespace that drops below its declared level is a
reported defect rather than a discovery. A regression found by guarding is a
defect; a regression declared in advance is a decision.
## Reconciliation tiers, and where automation stops
| Tier | Situation | Mechanism | Automatable |
|---|---|---|---|
| **T0 Fork** | namespace created, lineage recorded | metadata | yes |
| **T1 Sync** | pull canon, plans, or knowledge from another namespace | append events, re-derive | largely |
| **T2 Reintegration** | records diverged, no participant above `S2` | union events, re-derive, human-resolve genuine contradictions | partly |
| **T3 Amalgamation** | any participant at `S3` | governed programme — see below | **no** |
**T3 is not a merge.** It resembles the merger or acquisition of distinct
companies far more than a version-control merge, and must be planned as such:
- due diligence — inventory both sides, item by item;
- survivor decisions per subsystem — keep, move, replace, retire;
- migration with evidence, and decommissioning of what does not survive;
- governance integration — reconciling two bodies of canon is a human act,
never automated;
- identity, credential, and data custody consolidation.
**T3 may legitimately end without integration.** Permanent coexistence, or
divestment, are valid outcomes. Real mergers most often fail at systems
integration; an architecture that assumes eventual convergence is lying about its
own limits.
### Known cost
`prj-state-hub-retirement` is a T3 reconciliation inside a *single*
organization — two hub implementations, distinct infrastructure. It required a
dedicated project repository, a 425-item disposition inventory (`SHR-INV-0001`),
staged migration with strangler adapters, and explicit retirement gates. That is
the realistic cost of T3 under the most favourable conditions possible: one
owner, one canon, one credential authority.
Nothing here reduces that cost. Declared postures make it **visible before** a
fork is created rather than discovered when reconciliation is attempted.
## Consequences
**Positive.** Disconnected operation stops requiring a coordinator for identity.
`ADR-007` decision 1's contradiction is resolved rather than tolerated. A
namespace mid-journey can describe itself honestly instead of being
non-conformant. Reconciliation cost becomes computable in advance. Client
instances become expressible.
**Negative.** Every namespace gains a posture to declare and keep accurate, and
tooling must learn qualified references. Decision 8's coupling rule constrains
disconnected operation to namespaces that can reconcile — deliberately.
**Deferred.** Merge machinery for T2 is **not** specified here and should not be
built until a real fork needs it. T3 needs no machinery by definition; it needs a
project repository and human judgement.
**Amended.** `ADR-007` decision 1 — uniqueness is namespace-scoped.
`ADR-007` decision 2 — derivation input becomes `(namespace, identifier)`.
## Open question
**What is the namespace boundary in practice?** Candidates: a fleet instance
(`railiance01`), a client deployment, or an FOS autonomous domain. FOS's
recursion — "from projects to companies to foundation-like umbrella structures" —
suggests namespaces **nest**, which would make qualification relative rather than
absolute, closer to DNS than to a flat handle. The notation survives either
answer, so implementation is not blocked, but the data model is unfinished until
it is settled.
## References
- `canon/standards/federated-organization-standard_v1.0.md` — bounded autonomy,
escalation, sovereignty by default, rebuildability
- ADR-001 — workplans originate as repo files
- ADR-007 — identifier uniqueness and derived identifiers (amended here)
- ADR-008 — Multi-Tenancy Framework; source of the plane/ladder/posture form and
the accuracy-not-altitude conformance rule
- ADR-010 — hub authority, local cache, and the two kinds of hub data
- `CUST-WP-0058` — instance-per-client tenancy
- `SHR-INV-0001` — 425-item disposition inventory, T3 cost evidence
- `RMGR-WP-0004-T02` — `rmgr conform`, the guard machinery

Some files were not shown because too many files have changed in this diff Show more