Publish estate ADRs, platform ADRs, and IAM Profile v0.3
Some checks failed
Build and publish policy-nexus image / build-and-push (push) Failing after 48s
Some checks failed
Build and publish policy-nexus image / build-and-push (push) Failing after 48s
T04 classifies the remaining corpus. Chapter 9 on the first-wave arc42 stubs now matches what is published.
This commit is contained in:
parent
5cb88edf4d
commit
25dd59a7c6
53 changed files with 9563 additions and 787 deletions
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="64b47d73b9fdf33df535db42c80db3a7435da5cf">
|
||||
<meta name="policy-source-revision" content="5cb88edf4d52a65ea31b1f2f53bcf6f71769d234">
|
||||
<meta name="policy-source-digest" content="a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be">
|
||||
<title>Policy addressing and permanence</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 64b47d73b9fdf33df535db42c80db3a7435da5cf</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>
|
||||
<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 · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234</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>/<kind>/<document>/<version>/
|
||||
|
|
@ -211,4 +211,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 64b47d73b9fdf33df535db42c80db3a7435da5cf</span></footer></main></div></div></html>
|
||||
</section><footer><span>policy-nexus-adr-0001 · accepted-1 · accepted</span><span>policy-nexus · docs/adr/ADR-0001-addressing-and-permanence.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234</span></footer></main></div></div></html>
|
||||
|
|
|
|||
242
build/adr/custodian-agent-runtime/v1/index.html
Normal file
242
build/adr/custodian-agent-runtime/v1/index.html
Normal 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>{
|
||||
"observations": ["..."],
|
||||
"progress_events": [
|
||||
{"summary": "...", "workstream_id": "...", "event_type": "note"}
|
||||
],
|
||||
"tasks_to_update": [
|
||||
{"task_id": "...", "status": "done"}
|
||||
],
|
||||
"tasks_to_flag": [
|
||||
{"task_id": "...", "note": "..."}
|
||||
]
|
||||
}</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>
|
||||
|
|
@ -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>{
|
||||
"observations": ["..."],
|
||||
"progress_events": [
|
||||
{"summary": "...", "workstream_id": "...", "event_type": "note"}
|
||||
],
|
||||
"tasks_to_update": [
|
||||
{"task_id": "...", "status": "done"}
|
||||
],
|
||||
"tasks_to_flag": [
|
||||
{"task_id": "...", "note": "..."}
|
||||
]
|
||||
}</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>
|
||||
253
build/adr/custodian-canon-federation/v1/index.html
Normal file
253
build/adr/custodian-canon-federation/v1/index.html
Normal 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>
|
||||
|
|
@ -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>
|
||||
236
build/adr/custodian-connectivity-first/v1/index.html
Normal file
236
build/adr/custodian-connectivity-first/v1/index.html
Normal 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>
|
||||
|
|
@ -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
build/adr/custodian-cross-repo-workplans/v1/index.html
Normal file
225
build/adr/custodian-cross-repo-workplans/v1/index.html
Normal 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-<kebab-slug></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 & 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>
|
||||
|
|
@ -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-<kebab-slug></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 & 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>
|
||||
284
build/adr/custodian-federated-namespaces/v1/index.html
Normal file
284
build/adr/custodian-federated-namespaces/v1/index.html
Normal 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: "2026-08-18"
|
||||
gap:
|
||||
U: "Registration requires the registrar under ADR-007 decision 2 interim.
|
||||
Lifts when derived identifiers land (RMGR-WP-0005-T03)."</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 -> T3 (regardless of other planes)
|
||||
all participants S<=S2 and R>=R2 -> T2 feasible
|
||||
any participant below R2 -> 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>
|
||||
|
|
@ -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: "2026-08-18"
|
||||
gap:
|
||||
U: "Registration requires the registrar under ADR-007 decision 2 interim.
|
||||
Lifts when derived identifiers land (RMGR-WP-0005-T03)."</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 -> T3 (regardless of other planes)
|
||||
all participants S<=S2 and R>=R2 -> T2 feasible
|
||||
any participant below R2 -> 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>
|
||||
238
build/adr/custodian-hub-authority/v1/index.html
Normal file
238
build/adr/custodian-hub-authority/v1/index.html
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="8ea4448b7729035ae6bee044867ac9fd8b4940ea7013eb2b0256407cba1a0500">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-08-17</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 · 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="#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></ol></nav><main><section id="status"><h2>Status</h2>
|
||||
<p>Proposed.</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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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><footer><span>CUST-ADR-010 · draft-1 · proposed</span><span>the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
@ -0,0 +1,238 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="8ea4448b7729035ae6bee044867ac9fd8b4940ea7013eb2b0256407cba1a0500">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-08-17</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 · 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="#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></ol></nav><main><section id="status"><h2>Status</h2>
|
||||
<p>Proposed.</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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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><footer><span>CUST-ADR-010 · draft-1 · proposed</span><span>the-custodian · canon/architecture/adr-010-hub-authority-and-local-cache-model.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
244
build/adr/custodian-materialized-derived-state/v1/index.html
Normal file
244
build/adr/custodian-materialized-derived-state/v1/index.html
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="350c26d86c573716eb12333473917d91b8cd68b8798197b0077af1a6ba8c6480">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-03-20</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-09-20</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.</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 & 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><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. 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-1 · accepted</span><span>the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="350c26d86c573716eb12333473917d91b8cd68b8798197b0077af1a6ba8c6480">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-03-20</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-09-20</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.</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 & 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><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. 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-1 · accepted</span><span>the-custodian · canon/architecture/adr-003-materialized-derived-state.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
278
build/adr/custodian-workplan-identity/v1/index.html
Normal file
278
build/adr/custodian-workplan-identity/v1/index.html
Normal file
|
|
@ -0,0 +1,278 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="69f463795bdf1769c11415e9c8afa170d6fe62f04a554f7573f269000b5c4b08">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-08-17</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 · 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="#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>
|
||||
<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 <- 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-1 · accepted</span><span>the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
@ -0,0 +1,278 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="69f463795bdf1769c11415e9c8afa170d6fe62f04a554f7573f269000b5c4b08">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-08-17</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 · 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="#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>
|
||||
<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 <- 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-1 · accepted</span><span>the-custodian · canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
298
build/adr/custodian-workplans-as-repo-artefacts/v1/index.html
Normal file
298
build/adr/custodian-workplans-as-repo-artefacts/v1/index.html
Normal file
|
|
@ -0,0 +1,298 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="64b11785b683cf21ba2aca18e3b8f3301d6070e6a022df6efc722597a8547334">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-02-28</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-08-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-file-convention"><span class="n">·</span>Workplan File Convention</a></li><li><a href="#rebuild-principle"><span class="n">·</span>Rebuild Principle</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="#workplan-closure-protocol"><span class="n">·</span>Workplan Closure Protocol</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>During early State Hub development (v0.1–v0.4), workstreams and tasks were created directly in the PostgreSQL database via MCP bootstrap tools (<code>create_workstream</code>, <code>create_task</code>). This made the database the <strong>origin</strong> of work items — not a cache or index. The pattern was convenient for rapid bootstrapping but is architecturally wrong for a system built on the values of auditability, reversibility, and local-first sovereignty.</p>
|
||||
<p>The trigger for formalising this decision was the creation of the v0.5 workplan ("Dynamic Domains & Multi-Repo") directly in the state-hub database without a corresponding file artefact in any repository.</p>
|
||||
</section>
|
||||
<section id="decision"><h2>Decision</h2>
|
||||
<p><strong>Workplans and work items MUST originate as Markdown files in the repository that owns them.</strong> The Custodian State Hub indexes and caches those artefacts but is never their origin.</p>
|
||||
<p>Formally: the state-hub must (theoretically, given sufficient compute and time) be able to <strong>rebuild its full representation</strong> of repositories, their workplans, tasks, decisions, and dependencies by reading only the files in the registered repositories. No information that matters for coordination should exist solely in the database.</p>
|
||||
<h3>Corollaries</h3>
|
||||
<ol><li><strong>Repository is authoritative.</strong> A workplan file is the canonical record. The state-hub database row is a materialized cache of that file.</li></ol>
|
||||
<ol><li><strong>Database is disposable.</strong> Dropping and re-creating the database from registered repository files must produce an equivalent state. The database is an operational convenience, not a primary store.</li></ol>
|
||||
<ol><li><strong>MCP bootstrap tools become index/sync tools.</strong> <code>create_workstream</code> and <code>create_task</code> are acceptable as convenience wrappers only if they write the file first and then register the row. Using them to write DB-only records violates this ADR.</li></ol>
|
||||
<ol><li><strong>The rebuild principle implies a sync mechanism.</strong> There must be a defined path (<code>make sync-workplans</code> or equivalent) by which the state-hub reads workplan files from registered repositories and upserts its database state.</li></ol>
|
||||
</section>
|
||||
<section id="workplan-file-convention"><h2>Workplan File Convention</h2>
|
||||
<p>Each workplan lives in a <code>workplans/</code> directory in the repository that owns the work. The owning repository is identified by domain.</p>
|
||||
<h3>Location</h3>
|
||||
<pre><repo-root>/workplans/<id>-<slug>.md</pre>
|
||||
<p>Examples:</p>
|
||||
<ul><li><code>the-custodian/workplans/CUST-WP-0005-dynamic-domains.md</code></li><li><code>railiance/workplans/RAIL-WP-0001-three-phoenix.md</code></li></ul>
|
||||
<h3>Frontmatter Schema</h3>
|
||||
<pre>---
|
||||
id: CUST-WP-0005 # human-readable workplan ID, unique per repo
|
||||
type: workplan
|
||||
title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
|
||||
domain: custodian # must match a registered domain slug
|
||||
status: active # active | completed | archived
|
||||
owner: custodian
|
||||
topic_slug: custodian # maps to a state-hub Topic slug
|
||||
created: "2026-02-28"
|
||||
updated: "2026-02-28"
|
||||
---</pre>
|
||||
<h3>Task Items</h3>
|
||||
<p>Tasks are embedded in the workplan file as headed sections. Each task section carries its own YAML block:</p>
|
||||
<pre>## P1.1 — Create `domains` table + Alembic migration
|
||||
</pre>
|
||||
<p>id: CUST-WP-0005-T001 status: todo priority: high</p>
|
||||
<pre>
|
||||
Task description prose here.</pre>
|
||||
<p>The state-hub parses these embedded task blocks during ingestion and upserts rows in the <code>tasks</code> table. The <code>id</code> field is the stable external key; the state-hub UUID is internal and opaque.</p>
|
||||
<h3>Decision Items</h3>
|
||||
<p>Decisions are separate files or embedded sections following the same pattern, using <code>type: decision</code> in frontmatter.</p>
|
||||
</section>
|
||||
<section id="rebuild-principle"><h2>Rebuild Principle</h2>
|
||||
<p>The rebuild sequence for a clean state-hub:</p>
|
||||
<ol><li><code>make migrate</code> — create schema</li><li><code>make seed-domains</code> — insert domain rows (domains.yaml in canon/)</li><li>For each registered repository: <code>make sync-workplans REPO=<slug></code> — parse workplan files and upsert workstreams, tasks, decisions</li><li><code>make sync-progress</code> — replay progress events from episodic memory logs</li></ol>
|
||||
<p>After step 4 the database must be functionally equivalent to the live state.</p>
|
||||
</section>
|
||||
<section id="consequences"><h2>Consequences</h2>
|
||||
<h3>Immediate</h3>
|
||||
<ul><li>The v0.5 and v0.3 workplans created DB-first in this session are <strong>legacy records</strong> that violate this ADR. Remediation: write the corresponding workplan files, then mark the DB rows as <code>source: db-legacy</code> until a sync mechanism can reconcile them.</li></ul>
|
||||
<ul><li>The state-hub CLAUDE.md design-boundary note must be updated: the MCP bootstrap tools are permitted only as write-through tools (file + DB), never as DB-only tools.</li></ul>
|
||||
<h3>Medium Term</h3>
|
||||
<ul><li>A <code>make sync-workplans</code> command must be implemented as part of the managed-repos / contribution-tracking infrastructure (see v0.3 workplan).</li></ul>
|
||||
<ul><li>The <code>managed_repos</code> table is the prerequisite: the state-hub must know which repositories to scan.</li></ul>
|
||||
<ul><li>Workplan file format must be versioned and parsed by a dedicated loader (<code>state-hub/scripts/sync_workplans.py</code>).</li></ul>
|
||||
<h3>Long Term</h3>
|
||||
<ul><li>When the state-hub grows to cover multiple users or teams, this principle ensures that no coordination state can be lost by a database failure. Every repository is its own resilient shard of the coordination graph.</li></ul>
|
||||
<ul><li>This is the foundation for the "transgenerational" property: workplans in git survive database migrations, cloud provider changes, and system rebuilds.</li></ul>
|
||||
</section>
|
||||
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
|
||||
<p><strong>Database-first with export:</strong> Create in DB, export to files on demand. Rejected: export is easily skipped and files become secondary/stale.</p>
|
||||
<p><strong>Files-only, no database:</strong> Parse files on every query. Rejected: impractical at scale; the database is a necessary cache for cross-repo aggregation and real-time dashboard queries.</p>
|
||||
<p><strong>Hybrid with explicit sync flag:</strong> Mark some records as "db-authoritative" and others as "file-authoritative." Rejected: introduces ambiguity about which records matter; violates the "single source of truth" principle.</p>
|
||||
</section>
|
||||
<section id="workplan-closure-protocol"><h2>Workplan Closure Protocol</h2>
|
||||
<p>When a workplan is about to be marked <code>finished</code>, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.</p>
|
||||
<h3>Steps</h3>
|
||||
<ol><li><strong>Query all non-done tasks</strong> in the workplan via <code>GET /tasks/?workplan_id=<uuid></code> (legacy alias: <code>workstream_id</code>; filter for <code>todo</code>, <code>in_progress</code>, <code>blocked</code>).</li></ol>
|
||||
<ol><li><strong>Classify each task</strong> into one of three outcomes:</li></ol>
|
||||
<div class="scroll"><table><thead><tr><th>Outcome</th><th>Action</th></tr></thead><tbody><tr><td><strong>Done</strong> — work was completed, DB record just wasn't updated</td><td><code>PATCH /tasks/{id}/ {"status": "done"}</code></td></tr><tr><td><strong>Cancelled</strong> — dropped, superseded, or out of scope</td><td><code>PATCH /tasks/{id}/ {"status": "cancelled", "blocking_reason": "<why>"}</code></td></tr><tr><td><strong>Carry-forward</strong> — genuinely unfinished, belongs in the next run</td><td>Leave open; note in closure review; trigger new workplan</td></tr></tbody></table></div>
|
||||
<ol><li><strong>Append a <code>## Closure Review</code> section</strong> to the workplan file:</li></ol>
|
||||
<pre> ## Closure Review — YYYY-MM-DD
|
||||
|
||||
**Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.
|
||||
|
||||
### Completed (DB updated)
|
||||
- TASK-ID — title
|
||||
|
||||
### Cancelled (dropped)
|
||||
| Task | Reason |
|
||||
|------|--------|
|
||||
| TASK-ID — title | Superseded by X |
|
||||
|
||||
### Carried forward
|
||||
| Task | Target workplan |
|
||||
|------|----------------|
|
||||
| TASK-ID — title | CUST-WP-XXXX |</pre>
|
||||
<ol><li><strong>If any tasks are carried forward</strong>: do not mark the workplan <code>finished</code> yet. Create the new workplan file (or amend an existing active one), then close the current workplan.</li></ol>
|
||||
<ol><li><strong>Update the workplan frontmatter</strong> <code>status: finished</code> and <code>updated:</code> date.</li></ol>
|
||||
<ol><li><strong>Mark the workplan <code>finished</code></strong> in the state hub via MCP or API (<code>update_workplan_status</code>).</li></ol>
|
||||
<h3>Daily Stale-Task Cleanup</h3>
|
||||
<p>As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:</p>
|
||||
<pre>cd ~/the-custodian/state-hub
|
||||
make cleanup-stale # run immediately
|
||||
# or add to cron:
|
||||
# 0 3 * * * cd ~/the-custodian/state-hub && make cleanup-stale</pre>
|
||||
<p>The script (<code>scripts/cleanup_stale_tasks.py</code>) emits a <code>cleanup</code> progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a <code>blocking_reason</code> noting they should be verified against the workplan file.</p>
|
||||
<p>The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.</p>
|
||||
</section>
|
||||
<section id="related"><h2>Related</h2>
|
||||
<ul><li>Custodian Constitution v0.1 §2 (Powers) — canon changes require review gate</li><li>ADR-000 (forthcoming) — overall Custodian architecture principles</li><li>State Hub v0.3 workplan — <code>sync_workplans.py</code> is a Phase 4 deliverable</li><li><code>canon/values/foundational_values_v0.1.md</code> — Local-first, Auditability, Reversibility</li></ul>
|
||||
</section><footer><span>CUST-ADR-001 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
@ -0,0 +1,298 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="64b11785b683cf21ba2aca18e3b8f3301d6070e6a022df6efc722597a8547334">
|
||||
<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-1</span> <span>the-custodian</span> <span>reviewed 2026-02-28</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-08-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-file-convention"><span class="n">·</span>Workplan File Convention</a></li><li><a href="#rebuild-principle"><span class="n">·</span>Rebuild Principle</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="#workplan-closure-protocol"><span class="n">·</span>Workplan Closure Protocol</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>During early State Hub development (v0.1–v0.4), workstreams and tasks were created directly in the PostgreSQL database via MCP bootstrap tools (<code>create_workstream</code>, <code>create_task</code>). This made the database the <strong>origin</strong> of work items — not a cache or index. The pattern was convenient for rapid bootstrapping but is architecturally wrong for a system built on the values of auditability, reversibility, and local-first sovereignty.</p>
|
||||
<p>The trigger for formalising this decision was the creation of the v0.5 workplan ("Dynamic Domains & Multi-Repo") directly in the state-hub database without a corresponding file artefact in any repository.</p>
|
||||
</section>
|
||||
<section id="decision"><h2>Decision</h2>
|
||||
<p><strong>Workplans and work items MUST originate as Markdown files in the repository that owns them.</strong> The Custodian State Hub indexes and caches those artefacts but is never their origin.</p>
|
||||
<p>Formally: the state-hub must (theoretically, given sufficient compute and time) be able to <strong>rebuild its full representation</strong> of repositories, their workplans, tasks, decisions, and dependencies by reading only the files in the registered repositories. No information that matters for coordination should exist solely in the database.</p>
|
||||
<h3>Corollaries</h3>
|
||||
<ol><li><strong>Repository is authoritative.</strong> A workplan file is the canonical record. The state-hub database row is a materialized cache of that file.</li></ol>
|
||||
<ol><li><strong>Database is disposable.</strong> Dropping and re-creating the database from registered repository files must produce an equivalent state. The database is an operational convenience, not a primary store.</li></ol>
|
||||
<ol><li><strong>MCP bootstrap tools become index/sync tools.</strong> <code>create_workstream</code> and <code>create_task</code> are acceptable as convenience wrappers only if they write the file first and then register the row. Using them to write DB-only records violates this ADR.</li></ol>
|
||||
<ol><li><strong>The rebuild principle implies a sync mechanism.</strong> There must be a defined path (<code>make sync-workplans</code> or equivalent) by which the state-hub reads workplan files from registered repositories and upserts its database state.</li></ol>
|
||||
</section>
|
||||
<section id="workplan-file-convention"><h2>Workplan File Convention</h2>
|
||||
<p>Each workplan lives in a <code>workplans/</code> directory in the repository that owns the work. The owning repository is identified by domain.</p>
|
||||
<h3>Location</h3>
|
||||
<pre><repo-root>/workplans/<id>-<slug>.md</pre>
|
||||
<p>Examples:</p>
|
||||
<ul><li><code>the-custodian/workplans/CUST-WP-0005-dynamic-domains.md</code></li><li><code>railiance/workplans/RAIL-WP-0001-three-phoenix.md</code></li></ul>
|
||||
<h3>Frontmatter Schema</h3>
|
||||
<pre>---
|
||||
id: CUST-WP-0005 # human-readable workplan ID, unique per repo
|
||||
type: workplan
|
||||
title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
|
||||
domain: custodian # must match a registered domain slug
|
||||
status: active # active | completed | archived
|
||||
owner: custodian
|
||||
topic_slug: custodian # maps to a state-hub Topic slug
|
||||
created: "2026-02-28"
|
||||
updated: "2026-02-28"
|
||||
---</pre>
|
||||
<h3>Task Items</h3>
|
||||
<p>Tasks are embedded in the workplan file as headed sections. Each task section carries its own YAML block:</p>
|
||||
<pre>## P1.1 — Create `domains` table + Alembic migration
|
||||
</pre>
|
||||
<p>id: CUST-WP-0005-T001 status: todo priority: high</p>
|
||||
<pre>
|
||||
Task description prose here.</pre>
|
||||
<p>The state-hub parses these embedded task blocks during ingestion and upserts rows in the <code>tasks</code> table. The <code>id</code> field is the stable external key; the state-hub UUID is internal and opaque.</p>
|
||||
<h3>Decision Items</h3>
|
||||
<p>Decisions are separate files or embedded sections following the same pattern, using <code>type: decision</code> in frontmatter.</p>
|
||||
</section>
|
||||
<section id="rebuild-principle"><h2>Rebuild Principle</h2>
|
||||
<p>The rebuild sequence for a clean state-hub:</p>
|
||||
<ol><li><code>make migrate</code> — create schema</li><li><code>make seed-domains</code> — insert domain rows (domains.yaml in canon/)</li><li>For each registered repository: <code>make sync-workplans REPO=<slug></code> — parse workplan files and upsert workstreams, tasks, decisions</li><li><code>make sync-progress</code> — replay progress events from episodic memory logs</li></ol>
|
||||
<p>After step 4 the database must be functionally equivalent to the live state.</p>
|
||||
</section>
|
||||
<section id="consequences"><h2>Consequences</h2>
|
||||
<h3>Immediate</h3>
|
||||
<ul><li>The v0.5 and v0.3 workplans created DB-first in this session are <strong>legacy records</strong> that violate this ADR. Remediation: write the corresponding workplan files, then mark the DB rows as <code>source: db-legacy</code> until a sync mechanism can reconcile them.</li></ul>
|
||||
<ul><li>The state-hub CLAUDE.md design-boundary note must be updated: the MCP bootstrap tools are permitted only as write-through tools (file + DB), never as DB-only tools.</li></ul>
|
||||
<h3>Medium Term</h3>
|
||||
<ul><li>A <code>make sync-workplans</code> command must be implemented as part of the managed-repos / contribution-tracking infrastructure (see v0.3 workplan).</li></ul>
|
||||
<ul><li>The <code>managed_repos</code> table is the prerequisite: the state-hub must know which repositories to scan.</li></ul>
|
||||
<ul><li>Workplan file format must be versioned and parsed by a dedicated loader (<code>state-hub/scripts/sync_workplans.py</code>).</li></ul>
|
||||
<h3>Long Term</h3>
|
||||
<ul><li>When the state-hub grows to cover multiple users or teams, this principle ensures that no coordination state can be lost by a database failure. Every repository is its own resilient shard of the coordination graph.</li></ul>
|
||||
<ul><li>This is the foundation for the "transgenerational" property: workplans in git survive database migrations, cloud provider changes, and system rebuilds.</li></ul>
|
||||
</section>
|
||||
<section id="alternatives-considered"><h2>Alternatives Considered</h2>
|
||||
<p><strong>Database-first with export:</strong> Create in DB, export to files on demand. Rejected: export is easily skipped and files become secondary/stale.</p>
|
||||
<p><strong>Files-only, no database:</strong> Parse files on every query. Rejected: impractical at scale; the database is a necessary cache for cross-repo aggregation and real-time dashboard queries.</p>
|
||||
<p><strong>Hybrid with explicit sync flag:</strong> Mark some records as "db-authoritative" and others as "file-authoritative." Rejected: introduces ambiguity about which records matter; violates the "single source of truth" principle.</p>
|
||||
</section>
|
||||
<section id="workplan-closure-protocol"><h2>Workplan Closure Protocol</h2>
|
||||
<p>When a workplan is about to be marked <code>finished</code>, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.</p>
|
||||
<h3>Steps</h3>
|
||||
<ol><li><strong>Query all non-done tasks</strong> in the workplan via <code>GET /tasks/?workplan_id=<uuid></code> (legacy alias: <code>workstream_id</code>; filter for <code>todo</code>, <code>in_progress</code>, <code>blocked</code>).</li></ol>
|
||||
<ol><li><strong>Classify each task</strong> into one of three outcomes:</li></ol>
|
||||
<div class="scroll"><table><thead><tr><th>Outcome</th><th>Action</th></tr></thead><tbody><tr><td><strong>Done</strong> — work was completed, DB record just wasn't updated</td><td><code>PATCH /tasks/{id}/ {"status": "done"}</code></td></tr><tr><td><strong>Cancelled</strong> — dropped, superseded, or out of scope</td><td><code>PATCH /tasks/{id}/ {"status": "cancelled", "blocking_reason": "<why>"}</code></td></tr><tr><td><strong>Carry-forward</strong> — genuinely unfinished, belongs in the next run</td><td>Leave open; note in closure review; trigger new workplan</td></tr></tbody></table></div>
|
||||
<ol><li><strong>Append a <code>## Closure Review</code> section</strong> to the workplan file:</li></ol>
|
||||
<pre> ## Closure Review — YYYY-MM-DD
|
||||
|
||||
**Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.
|
||||
|
||||
### Completed (DB updated)
|
||||
- TASK-ID — title
|
||||
|
||||
### Cancelled (dropped)
|
||||
| Task | Reason |
|
||||
|------|--------|
|
||||
| TASK-ID — title | Superseded by X |
|
||||
|
||||
### Carried forward
|
||||
| Task | Target workplan |
|
||||
|------|----------------|
|
||||
| TASK-ID — title | CUST-WP-XXXX |</pre>
|
||||
<ol><li><strong>If any tasks are carried forward</strong>: do not mark the workplan <code>finished</code> yet. Create the new workplan file (or amend an existing active one), then close the current workplan.</li></ol>
|
||||
<ol><li><strong>Update the workplan frontmatter</strong> <code>status: finished</code> and <code>updated:</code> date.</li></ol>
|
||||
<ol><li><strong>Mark the workplan <code>finished</code></strong> in the state hub via MCP or API (<code>update_workplan_status</code>).</li></ol>
|
||||
<h3>Daily Stale-Task Cleanup</h3>
|
||||
<p>As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:</p>
|
||||
<pre>cd ~/the-custodian/state-hub
|
||||
make cleanup-stale # run immediately
|
||||
# or add to cron:
|
||||
# 0 3 * * * cd ~/the-custodian/state-hub && make cleanup-stale</pre>
|
||||
<p>The script (<code>scripts/cleanup_stale_tasks.py</code>) emits a <code>cleanup</code> progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a <code>blocking_reason</code> noting they should be verified against the workplan file.</p>
|
||||
<p>The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.</p>
|
||||
</section>
|
||||
<section id="related"><h2>Related</h2>
|
||||
<ul><li>Custodian Constitution v0.1 §2 (Powers) — canon changes require review gate</li><li>ADR-000 (forthcoming) — overall Custodian architecture principles</li><li>State Hub v0.3 workplan — <code>sync_workplans.py</code> is a Phase 4 deliverable</li><li><code>canon/values/foundational_values_v0.1.md</code> — Local-first, Auditability, Reversibility</li></ul>
|
||||
</section><footer><span>CUST-ADR-001 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
211
build/adr/railiance-decisions-live-in-the-repo/v1/index.html
Normal file
211
build/adr/railiance-decisions-live-in-the-repo/v1/index.html
Normal 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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e">
|
||||
<title>Derived Rail Composition</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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>
|
||||
|
|
@ -202,4 +202,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0005 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0005-derived-rail-composition.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e">
|
||||
<title>First-Wave reef Rollout</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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>
|
||||
|
|
@ -214,4 +214,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0004 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0004-first-wave-reef-rollout.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
212
build/adr/railiance-placement-policy-ownership/v1/index.html
Normal file
212
build/adr/railiance-placement-policy-ownership/v1/index.html
Normal 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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="276ea38233413f1e23670bbf57c486abc361b0a275ca67efea7d677103713b32">
|
||||
<title>Private-by-default Exposure</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>railiance-master</span> <span>reviewed 2026-08-15</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</code></p><p class="sub">Review due: 2027-02-15</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0008</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-08-15</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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</code></p><p class="sub">Review due: 2027-02-15</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>
|
||||
|
|
@ -215,4 +215,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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>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-1 · accepted</span><span>railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0008 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0008-private-by-default-exposure.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d">
|
||||
<title>Wave 1 rail-kubernetes Boundary</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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>
|
||||
|
|
@ -215,4 +215,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
<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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0002 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="263431f88ba04d6ab9ab3b6c0d6a2bb08634bfe83dc0719350f0855d399c18b2">
|
||||
<title>Rapp Declaration Contract</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>railiance-master</span> <span>reviewed 2026-08-13</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</code></p><p class="sub">Review due: 2027-02-13</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0007</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-08-13</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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</code></p><p class="sub">Review due: 2027-02-13</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>
|
||||
|
|
@ -207,4 +207,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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>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-1 · accepted</span><span>railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0007 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0007-rapp-declaration-contract.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc">
|
||||
<title>First-Wave rapp Selection</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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>
|
||||
|
|
@ -213,4 +213,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0003 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0003-rapp-first-wave-selection.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="d9fbd9d21d86e461334abc24060c39127f2158ba25317b3d3dc326c4f7eaf08c">
|
||||
<title>Reef Production Admission</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>railiance-master</span> <span>reviewed 2026-08-15</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</code></p><p class="sub">Review due: 2027-02-15</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>RMASTER-ADR-0006</span> <span class="stat">accepted · accepted-1</span> <span>railiance-master</span> <span>reviewed 2026-08-15</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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</code></p><p class="sub">Review due: 2027-02-15</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>
|
||||
|
|
@ -203,4 +203,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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></ul>
|
||||
</section><footer><span>RMASTER-ADR-0006 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0006 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0006-reef-production-admission.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497">
|
||||
<title>Repository Prefix Architecture</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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>
|
||||
|
|
@ -232,4 +232,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>RMASTER-ADR-0001 · accepted-1 · accepted</span><span>railiance-master · docs/adr/ADR-0001-repository-prefix-architecture.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
209
build/adr/railiance-s3-platform-service-boundary/v1/index.html
Normal file
209
build/adr/railiance-s3-platform-service-boundary/v1/index.html
Normal 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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="5b51623198d9959793762f447f5813960c0b5df8">
|
||||
<meta name="policy-source-digest" content="0ab59ab79931e19615648da435e4a636836904a1189f5b53e3ee8467bea49841">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="4529fad986740aff58f6b5bacd3f86a8852e265714f6e0990cf3c1ab672e3d2e">
|
||||
<title>Coulomb estate architecture</title>
|
||||
<style>
|
||||
:root{
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>the-custodian</span> <span>reviewed 2026-08-18</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 · 5b51623198d9959793762f447f5813960c0b5df8</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>coulomb-estate-architecture</span> <span class="stat">proposed · draft-2</span> <span>the-custodian</span> <span>reviewed 2026-08-19</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</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="#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>
|
||||
|
|
@ -259,8 +259,8 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</section>
|
||||
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
|
||||
<p>Estate ADRs in <code>the-custodian/canon/architecture/</code>. Publication ids still need repo prefixes (WP-0003). Status is the source front-matter.</p>
|
||||
<div class="scroll"><table><thead><tr><th>Source</th><th>Status</th><th>Decision</th></tr></thead><tbody><tr><td><code>adr-001-workplans-as-repo-artefacts.md</code></td><td>accepted</td><td>Workplans and tasks originate as repo files; the hub is a read model.</td></tr><tr><td><code>adr-002-custodian-agent-runtime-design.md</code></td><td>accepted</td><td>Custodian agent runtime design.</td></tr><tr><td><code>adr-003-materialized-derived-state.md</code></td><td>accepted</td><td>Hub state is derived and fingerprint-invalidated.</td></tr><tr><td><code>adr-004-connectivity-first-network-posture.md</code></td><td>accepted</td><td>Connectivity-first network posture.</td></tr><tr><td><code>adr-005-cross-repo-workplans-project-repos.md</code></td><td>accepted</td><td>Cross-repo work lives in a <code>prj-*</code> repo.</td></tr><tr><td><code>adr-006-canon-federation-concept-ownership.md</code></td><td>accepted</td><td>Three canons; import, do not redefine.</td></tr><tr><td><code>adr-007-workplan-identity-and-repo-worker-topology.md</code></td><td>accepted</td><td>Globally unique workplan ids; one registrar.</td></tr><tr><td><code>adr-008-multi-tenancy-model.md</code></td><td>superseded</td><td>Relocated to NetKingdom Tenancy Posture.</td></tr><tr><td><code>adr-010-hub-authority-and-local-cache-model.md</code></td><td>proposed</td><td>Two kinds of hub data; local cache vs authority.</td></tr><tr><td><code>adr-011-federated-namespaces-and-reconciliation-limits.md</code></td><td>proposed</td><td>Federated namespaces and reconciliation limits.</td></tr></tbody></table></div>
|
||||
<p>Related, not estate-owned: policy-nexus ADR-0001 (addressing), NetKingdom Tenancy Posture (published), railiance-master ADR-0001–0008 (published).</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>Workplans and tasks originate as repo files; the hub is a read model.</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>Globally unique workplan ids; one registrar.</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></tbody></table></div>
|
||||
<p>Related and published elsewhere: policy-nexus ADR-0001; Tenancy Posture and IAM Profile v0.3; railiance-master ADR-0001–0008; activity-core ACT-ADR-001–005; ops-warden ADR-0001–0005; 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>
|
||||
|
|
@ -271,4 +271,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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-1 · proposed</span><span>the-custodian · canon/architecture/coulomb-estate_v0.1.md · 5b51623198d9959793762f447f5813960c0b5df8</span></footer></main></div></div></html>
|
||||
</section><footer><span>coulomb-estate-architecture · draft-2 · proposed</span><span>the-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,274 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
|
||||
<meta name="policy-source-digest" content="4529fad986740aff58f6b5bacd3f86a8852e265714f6e0990cf3c1ab672e3d2e">
|
||||
<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-2</span> <span>the-custodian</span> <span>reviewed 2026-08-19</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 · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</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="#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>. Publication ids still need repo prefixes (WP-0003). 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>Workplans and tasks originate as repo files; the hub is a read model.</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>Globally unique workplan ids; one registrar.</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></tbody></table></div>
|
||||
<p>Related and published elsewhere: policy-nexus ADR-0001; Tenancy Posture and IAM Profile v0.3; railiance-master ADR-0001–0008; activity-core ACT-ADR-001–005; ops-warden ADR-0001–0005; 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 residual: this workstation cannot mint hub UUIDs (ADR-007 registrar). 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-2 · proposed</span><span>the-custodian · canon/architecture/coulomb-estate_v0.1.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="0e0962e68b39fdcfb633b5058602174a36416a68">
|
||||
<meta name="policy-source-digest" content="dd42250edcc444fa9a5007c3f9d561984840af2b19a07cf2916cbcc8434df0f7">
|
||||
<meta name="policy-source-revision" content="ccc2618daee997bb4bd4249613d7c4c7344845cf">
|
||||
<meta name="policy-source-digest" content="3dce1bd24679c8e4ac601e6631b4de18cff7f4cef1e8e79c1a7a0ec0557a0213">
|
||||
<title>NetKingdom architecture</title>
|
||||
<style>
|
||||
:root{
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>net-kingdom</span> <span>reviewed 2026-08-18</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 · 0e0962e68b39fdcfb633b5058602174a36416a68</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>net-kingdom-architecture</span> <span class="stat">proposed · draft-2</span> <span>net-kingdom</span> <span>reviewed 2026-08-19</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 · ccc2618daee997bb4bd4249613d7c4c7344845cf</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="#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>
|
||||
|
|
@ -230,7 +230,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
<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>Source</th><th>Status</th><th>Notes</th></tr></thead><tbody><tr><td><code>canon/standards/tenancy-posture_v0.1.md</code></td><td>proposed</td><td>Published. First publication of this site.</td></tr><tr><td><code>canon/standards/iam-profile_v0.3.md</code></td><td>accepted</td><td>Current profile. Needs a unique publication id (v0.2 still shares <code>netkingdom-iam-profile</code>).</td></tr><tr><td><code>canon/standards/iam-profile_v0.2.md</code></td><td>should be superseded</td><td>v0.3 supersedes it; front-matter still <code>accepted</code>.</td></tr><tr><td><code>docs/adr/ADR-0006</code> … <code>ADR-0015</code></td><td>see files</td><td>Identity, orchestration, IAM ownership, tenant roles, packaging. Publish after <code>NK-ADR-*</code> prefix and review metadata.</td></tr></tbody></table></div>
|
||||
<div class="scroll"><table><thead><tr><th>Source</th><th>Status</th><th>Notes</th></tr></thead><tbody><tr><td><code>canon/standards/tenancy-posture_v0.1.md</code></td><td>proposed</td><td>Published. First publication of this site.</td></tr><tr><td><code>canon/standards/iam-profile_v0.3.md</code></td><td>accepted</td><td>Current profile (<code>netkingdom-iam-profile-v0.3</code>).</td></tr><tr><td><code>canon/standards/iam-profile_v0.2.md</code></td><td>superseded</td><td>Predecessor of v0.3.</td></tr><tr><td><code>docs/adr/ADR-0006</code> … <code>ADR-0015</code></td><td>see files</td><td>Identity, orchestration, IAM ownership, tenant roles, packaging. Publish after <code>NK-ADR-*</code> prefix and review metadata.</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>
|
||||
|
|
@ -241,4 +241,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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-1 · proposed</span><span>net-kingdom · docs/architecture/net-kingdom_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68</span></footer></main></div></div></html>
|
||||
</section><footer><span>net-kingdom-architecture · draft-2 · proposed</span><span>net-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf</span></footer></main></div></div></html>
|
||||
|
|
|
|||
244
build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html
Normal file
244
build/architecture/net-kingdom/v0.1/revisions/draft-2/index.html
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="ccc2618daee997bb4bd4249613d7c4c7344845cf">
|
||||
<meta name="policy-source-digest" content="3dce1bd24679c8e4ac601e6631b4de18cff7f4cef1e8e79c1a7a0ec0557a0213">
|
||||
<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-2</span> <span>net-kingdom</span> <span>reviewed 2026-08-19</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 · ccc2618daee997bb4bd4249613d7c4c7344845cf</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="#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>Source</th><th>Status</th><th>Notes</th></tr></thead><tbody><tr><td><code>canon/standards/tenancy-posture_v0.1.md</code></td><td>proposed</td><td>Published. First publication of this site.</td></tr><tr><td><code>canon/standards/iam-profile_v0.3.md</code></td><td>accepted</td><td>Current profile (<code>netkingdom-iam-profile-v0.3</code>).</td></tr><tr><td><code>canon/standards/iam-profile_v0.2.md</code></td><td>superseded</td><td>Predecessor of v0.3.</td></tr><tr><td><code>docs/adr/ADR-0006</code> … <code>ADR-0015</code></td><td>see files</td><td>Identity, orchestration, IAM ownership, tenant roles, packaging. Publish after <code>NK-ADR-*</code> prefix and review metadata.</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. Residual: IAM Profile id collision (WP-0003 packet).</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-2 · proposed</span><span>net-kingdom · docs/architecture/net-kingdom_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf</span></footer></main></div></div></html>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="64b47d73b9fdf33df535db42c80db3a7435da5cf">
|
||||
<meta name="policy-source-revision" content="5cb88edf4d52a65ea31b1f2f53bcf6f71769d234">
|
||||
<meta name="policy-source-digest" content="179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480">
|
||||
<title>Policy Nexus architecture</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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 · 64b47d73b9fdf33df535db42c80db3a7435da5cf</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>
|
||||
<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 · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234</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>
|
||||
|
|
@ -245,4 +245,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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 · 64b47d73b9fdf33df535db42c80db3a7435da5cf</span></footer></main></div></div></html>
|
||||
</section><footer><span>policy-nexus-architecture · draft-1 · proposed</span><span>policy-nexus · docs/architecture/policy-nexus_v0.1.md · 5cb88edf4d52a65ea31b1f2f53bcf6f71769d234</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="883533ed8af1703cc9bb4a2b24137e325bbbda47">
|
||||
<meta name="policy-source-digest" content="1cc0af5cdb6cae771bc134722672385b8e71df1a778adc3358862a1d8f5d7217">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="45adb3f484cbeae9423c6f01caae323d545d2d522a6baa24398cbc8ef1a3e974">
|
||||
<title>Railiance architecture</title>
|
||||
<style>
|
||||
:root{
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>railiance-master</span> <span>reviewed 2026-08-18</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 · 883533ed8af1703cc9bb4a2b24137e325bbbda47</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>railiance-architecture</span> <span class="stat">proposed · draft-2</span> <span>railiance-master</span> <span>reviewed 2026-08-19</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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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="#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>
|
||||
|
|
@ -232,6 +232,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
<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></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>
|
||||
|
|
@ -242,4 +243,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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-1 · proposed</span><span>railiance-master · docs/architecture/railiance_v0.1.md · 883533ed8af1703cc9bb4a2b24137e325bbbda47</span></footer></main></div></div></html>
|
||||
</section><footer><span>railiance-architecture · draft-2 · proposed</span><span>railiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
|
|||
246
build/architecture/railiance/v0.1/revisions/draft-2/index.html
Normal file
246
build/architecture/railiance/v0.1/revisions/draft-2/index.html
Normal file
|
|
@ -0,0 +1,246 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="468a52af2b14eba08e05be69c4d2866bfd8d9d7d">
|
||||
<meta name="policy-source-digest" content="45adb3f484cbeae9423c6f01caae323d545d2d522a6baa24398cbc8ef1a3e974">
|
||||
<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-2</span> <span>railiance-master</span> <span>reviewed 2026-08-19</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 · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</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="#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></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-2 · proposed</span><span>railiance-master · docs/architecture/railiance_v0.1.md · 468a52af2b14eba08e05be69c4d2866bfd8d9d7d</span></footer></main></div></div></html>
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="b606d5d44c6bcb3ff438656acae3bf93a786104b">
|
||||
<meta name="policy-source-digest" content="f65748fa3c861a6f399365ee5315af4e47ec91823837e3d7d89c17d4b385f2aa">
|
||||
<meta name="policy-source-revision" content="8585bb0c1d0f19e3d55e901e2041edf6aff03f0a">
|
||||
<meta name="policy-source-digest" content="dd28694239c663324b9753ac0f260cc29419fdf726129898bf42b5e776453074">
|
||||
<title>State Hub architecture</title>
|
||||
<style>
|
||||
:root{
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-1</span> <span>state-hub</span> <span>reviewed 2026-08-18</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 · b606d5d44c6bcb3ff438656acae3bf93a786104b</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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>state-hub-architecture</span> <span class="stat">proposed · draft-2</span> <span>state-hub</span> <span>reviewed 2026-08-19</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 · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a</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="#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>
|
||||
|
|
@ -232,7 +232,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</section>
|
||||
<section id="s9"><h2><span class="sn">09</span>Architecture Decisions</h2>
|
||||
<p>This repo has no <code>docs/adr/</code> corpus. Binding decisions live in the-custodian and are listed on the estate map:</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>CUST-ADR-001 (workplans as repo artefacts)</td><td>accepted</td><td>Hub is a read model.</td></tr><tr><td>CUST-ADR-003 (materialized derived state)</td><td>accepted</td><td>How the cache invalidates.</td></tr><tr><td>CUST-ADR-007 (identity and registrar)</td><td>accepted</td><td>One writer of workplan UUIDs.</td></tr><tr><td>CUST-ADR-010 (hub authority / local cache)</td><td>proposed</td><td>Two kinds of hub data.</td></tr></tbody></table></div>
|
||||
<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>Hub is a read model. 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 the cache invalidates.</td></tr><tr><td><code>CUST-ADR-007</code></td><td>accepted</td><td>One writer of workplan UUIDs.</td></tr><tr><td><code>CUST-ADR-010</code></td><td>proposed</td><td>Two kinds of hub data.</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>
|
||||
|
|
@ -243,4 +243,4 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
</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-1 · proposed</span><span>state-hub · docs/architecture/state-hub_v0.1.md · b606d5d44c6bcb3ff438656acae3bf93a786104b</span></footer></main></div></div></html>
|
||||
</section><footer><span>state-hub-architecture · draft-2 · proposed</span><span>state-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a</span></footer></main></div></div></html>
|
||||
|
|
|
|||
246
build/architecture/state-hub/v0.1/revisions/draft-2/index.html
Normal file
246
build/architecture/state-hub/v0.1/revisions/draft-2/index.html
Normal file
|
|
@ -0,0 +1,246 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="8585bb0c1d0f19e3d55e901e2041edf6aff03f0a">
|
||||
<meta name="policy-source-digest" content="dd28694239c663324b9753ac0f260cc29419fdf726129898bf42b5e776453074">
|
||||
<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-2</span> <span>state-hub</span> <span>reviewed 2026-08-19</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 · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a</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="#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>One identifier registrar (ADR-007). This workstation is not it.</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>This repo has no <code>docs/adr/</code> corpus. Binding decisions live in the-custodian and are listed on the estate map:</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>Hub is a read model. 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 the cache invalidates.</td></tr><tr><td><code>CUST-ADR-007</code></td><td>accepted</td><td>One writer of workplan UUIDs.</td></tr><tr><td><code>CUST-ADR-010</code></td><td>proposed</td><td>Two kinds of hub data.</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-2 · proposed</span><span>state-hub · docs/architecture/state-hub_v0.1.md · 8585bb0c1d0f19e3d55e901e2041edf6aff03f0a</span></footer></main></div></div></html>
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -13,7 +13,7 @@
|
|||
"source_digest": "99f802d91a0b3a65f0dac58230d8904f7c61cf3f81eff072fbbc59b634612a8a",
|
||||
"source_path": "canon/standards/tenancy-posture_v0.1.md",
|
||||
"source_repo": "net-kingdom",
|
||||
"source_revision": "0e0962e68b39fdcfb633b5058602174a36416a68",
|
||||
"source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf",
|
||||
"status": "proposed",
|
||||
"title": "NetKingdom Tenancy Posture v0.1"
|
||||
},
|
||||
|
|
@ -21,16 +21,16 @@
|
|||
"canonical_path": "architecture/coulomb-estate/v0.1/index.html",
|
||||
"currency": "current",
|
||||
"id": "coulomb-estate-architecture",
|
||||
"last_reviewed": "2026-08-18",
|
||||
"last_reviewed": "2026-08-19",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2027-02-18",
|
||||
"revision": "draft-1",
|
||||
"revision_path": "architecture/coulomb-estate/v0.1/revisions/draft-1/index.html",
|
||||
"source_digest": "0ab59ab79931e19615648da435e4a636836904a1189f5b53e3ee8467bea49841",
|
||||
"review_due": "2027-02-19",
|
||||
"revision": "draft-2",
|
||||
"revision_path": "architecture/coulomb-estate/v0.1/revisions/draft-2/index.html",
|
||||
"source_digest": "4529fad986740aff58f6b5bacd3f86a8852e265714f6e0990cf3c1ab672e3d2e",
|
||||
"source_path": "canon/architecture/coulomb-estate_v0.1.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "5b51623198d9959793762f447f5813960c0b5df8",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "proposed",
|
||||
"title": "Coulomb estate architecture"
|
||||
},
|
||||
|
|
@ -38,16 +38,16 @@
|
|||
"canonical_path": "architecture/railiance/v0.1/index.html",
|
||||
"currency": "current",
|
||||
"id": "railiance-architecture",
|
||||
"last_reviewed": "2026-08-18",
|
||||
"last_reviewed": "2026-08-19",
|
||||
"lifecycle": "active",
|
||||
"owner": "railiance-master",
|
||||
"review_due": "2027-02-18",
|
||||
"revision": "draft-1",
|
||||
"revision_path": "architecture/railiance/v0.1/revisions/draft-1/index.html",
|
||||
"source_digest": "1cc0af5cdb6cae771bc134722672385b8e71df1a778adc3358862a1d8f5d7217",
|
||||
"review_due": "2027-02-19",
|
||||
"revision": "draft-2",
|
||||
"revision_path": "architecture/railiance/v0.1/revisions/draft-2/index.html",
|
||||
"source_digest": "45adb3f484cbeae9423c6f01caae323d545d2d522a6baa24398cbc8ef1a3e974",
|
||||
"source_path": "docs/architecture/railiance_v0.1.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "proposed",
|
||||
"title": "Railiance architecture"
|
||||
},
|
||||
|
|
@ -55,16 +55,16 @@
|
|||
"canonical_path": "architecture/net-kingdom/v0.1/index.html",
|
||||
"currency": "current",
|
||||
"id": "net-kingdom-architecture",
|
||||
"last_reviewed": "2026-08-18",
|
||||
"last_reviewed": "2026-08-19",
|
||||
"lifecycle": "active",
|
||||
"owner": "net-kingdom",
|
||||
"review_due": "2027-02-18",
|
||||
"revision": "draft-1",
|
||||
"revision_path": "architecture/net-kingdom/v0.1/revisions/draft-1/index.html",
|
||||
"source_digest": "dd42250edcc444fa9a5007c3f9d561984840af2b19a07cf2916cbcc8434df0f7",
|
||||
"review_due": "2027-02-19",
|
||||
"revision": "draft-2",
|
||||
"revision_path": "architecture/net-kingdom/v0.1/revisions/draft-2/index.html",
|
||||
"source_digest": "3dce1bd24679c8e4ac601e6631b4de18cff7f4cef1e8e79c1a7a0ec0557a0213",
|
||||
"source_path": "docs/architecture/net-kingdom_v0.1.md",
|
||||
"source_repo": "net-kingdom",
|
||||
"source_revision": "0e0962e68b39fdcfb633b5058602174a36416a68",
|
||||
"source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf",
|
||||
"status": "proposed",
|
||||
"title": "NetKingdom architecture"
|
||||
},
|
||||
|
|
@ -72,16 +72,16 @@
|
|||
"canonical_path": "architecture/state-hub/v0.1/index.html",
|
||||
"currency": "current",
|
||||
"id": "state-hub-architecture",
|
||||
"last_reviewed": "2026-08-18",
|
||||
"last_reviewed": "2026-08-19",
|
||||
"lifecycle": "active",
|
||||
"owner": "state-hub",
|
||||
"review_due": "2027-02-18",
|
||||
"revision": "draft-1",
|
||||
"revision_path": "architecture/state-hub/v0.1/revisions/draft-1/index.html",
|
||||
"source_digest": "f65748fa3c861a6f399365ee5315af4e47ec91823837e3d7d89c17d4b385f2aa",
|
||||
"review_due": "2027-02-19",
|
||||
"revision": "draft-2",
|
||||
"revision_path": "architecture/state-hub/v0.1/revisions/draft-2/index.html",
|
||||
"source_digest": "dd28694239c663324b9753ac0f260cc29419fdf726129898bf42b5e776453074",
|
||||
"source_path": "docs/architecture/state-hub_v0.1.md",
|
||||
"source_repo": "state-hub",
|
||||
"source_revision": "b606d5d44c6bcb3ff438656acae3bf93a786104b",
|
||||
"source_revision": "8585bb0c1d0f19e3d55e901e2041edf6aff03f0a",
|
||||
"status": "proposed",
|
||||
"title": "State Hub architecture"
|
||||
},
|
||||
|
|
@ -98,7 +98,7 @@
|
|||
"source_digest": "179cbb86bca95f71f46f51ca1971ff1c274eed7d900adf0672b537d4bcc5b480",
|
||||
"source_path": "docs/architecture/policy-nexus_v0.1.md",
|
||||
"source_repo": "policy-nexus",
|
||||
"source_revision": "64b47d73b9fdf33df535db42c80db3a7435da5cf",
|
||||
"source_revision": "5cb88edf4d52a65ea31b1f2f53bcf6f71769d234",
|
||||
"status": "proposed",
|
||||
"title": "Policy Nexus architecture"
|
||||
},
|
||||
|
|
@ -115,7 +115,7 @@
|
|||
"source_digest": "a28668fb4b8b6c5ec8c94baac000061276d85ef1849ec7ab8d132b913dbfe3be",
|
||||
"source_path": "docs/adr/ADR-0001-addressing-and-permanence.md",
|
||||
"source_repo": "policy-nexus",
|
||||
"source_revision": "64b47d73b9fdf33df535db42c80db3a7435da5cf",
|
||||
"source_revision": "5cb88edf4d52a65ea31b1f2f53bcf6f71769d234",
|
||||
"status": "accepted",
|
||||
"title": "Policy addressing and permanence"
|
||||
},
|
||||
|
|
@ -132,7 +132,7 @@
|
|||
"source_digest": "b9c993ded8d79d6f871dba9cf08a320b2d619609a448ad3d02b632f5b6f76497",
|
||||
"source_path": "docs/adr/ADR-0001-repository-prefix-architecture.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Repository Prefix Architecture"
|
||||
},
|
||||
|
|
@ -149,7 +149,7 @@
|
|||
"source_digest": "7e1fc5aedd7294192d8702a22b9f205e5bae20793836fdc48c0c071d10d7ab9d",
|
||||
"source_path": "docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Wave 1 rail-kubernetes Boundary"
|
||||
},
|
||||
|
|
@ -166,7 +166,7 @@
|
|||
"source_digest": "28135e94758b6935518d2e83458c1e607deeabb341879b605eef6529b3168cbc",
|
||||
"source_path": "docs/adr/ADR-0003-rapp-first-wave-selection.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "First-Wave rapp Selection"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@
|
|||
"source_digest": "36ec3aad5082ceff685d66e091c0a24b52abfc65b36595d00dce2b52a7250f4e",
|
||||
"source_path": "docs/adr/ADR-0004-first-wave-reef-rollout.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "First-Wave reef Rollout"
|
||||
},
|
||||
|
|
@ -200,7 +200,7 @@
|
|||
"source_digest": "e02982ce54691cf1589ac3d04012b9b9282f9eb54ed4b8f2f0544371f9b87f3e",
|
||||
"source_path": "docs/adr/ADR-0005-derived-rail-composition.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Derived Rail Composition"
|
||||
},
|
||||
|
|
@ -217,7 +217,7 @@
|
|||
"source_digest": "d9fbd9d21d86e461334abc24060c39127f2158ba25317b3d3dc326c4f7eaf08c",
|
||||
"source_path": "docs/adr/ADR-0006-reef-production-admission.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Reef Production Admission"
|
||||
},
|
||||
|
|
@ -234,7 +234,7 @@
|
|||
"source_digest": "263431f88ba04d6ab9ab3b6c0d6a2bb08634bfe83dc0719350f0855d399c18b2",
|
||||
"source_path": "docs/adr/ADR-0007-rapp-declaration-contract.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Rapp Declaration Contract"
|
||||
},
|
||||
|
|
@ -251,7 +251,7 @@
|
|||
"source_digest": "276ea38233413f1e23670bbf57c486abc361b0a275ca67efea7d677103713b32",
|
||||
"source_path": "docs/adr/ADR-0008-private-by-default-exposure.md",
|
||||
"source_repo": "railiance-master",
|
||||
"source_revision": "883533ed8af1703cc9bb4a2b24137e325bbbda47",
|
||||
"source_revision": "468a52af2b14eba08e05be69c4d2866bfd8d9d7d",
|
||||
"status": "accepted",
|
||||
"title": "Private-by-default Exposure"
|
||||
},
|
||||
|
|
@ -424,6 +424,227 @@
|
|||
"source_revision": "35aff380a33f51a512c1e1b42d52d1dc0d95930f",
|
||||
"status": "accepted",
|
||||
"title": "ADR-0005 \u2014 Implement one lane narrowly, route everything else"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-workplans-as-repo-artefacts/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-001",
|
||||
"last_reviewed": "2026-02-28",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2026-08-28",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-workplans-as-repo-artefacts/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "64b11785b683cf21ba2aca18e3b8f3301d6070e6a022df6efc722597a8547334",
|
||||
"source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Workplans and Work Items Are Repository Artefacts"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-agent-runtime/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-002",
|
||||
"last_reviewed": "2026-03-12",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2026-09-12",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-agent-runtime/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "6aef66cd5cf71a48f5b4e14401dc19a755e2b182445b272d5952df0eb0dea8ec",
|
||||
"source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Custodian Agent Runtime \u2014 v0.1 Bootstrap Design"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-materialized-derived-state/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-003",
|
||||
"last_reviewed": "2026-03-20",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2026-09-20",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-materialized-derived-state/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "350c26d86c573716eb12333473917d91b8cd68b8798197b0077af1a6ba8c6480",
|
||||
"source_path": "canon/architecture/adr-003-materialized-derived-state.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Materialized Derived State with Fingerprint Invalidation for Repo-Sourced Data"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-connectivity-first/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-004",
|
||||
"last_reviewed": "2026-03-26",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2026-09-26",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-connectivity-first/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "3b68adfa6ab329e73f857cf691dc405136d2d66a0135e2c37c236aabe4659557",
|
||||
"source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Connectivity-First Network Posture for Custodian Infrastructure"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-cross-repo-workplans/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-005",
|
||||
"last_reviewed": "2026-06-22",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2026-12-22",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-cross-repo-workplans/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "13195a721d0e579715f5f39ca6f72b5e49c583611e6ca089e6d4618708ae917f",
|
||||
"source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Cross-Repo Workplans Live in Dedicated Project Repos"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-canon-federation/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-006",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-canon-federation/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "a454df0e1d227f99ebb36c4abd45c76cc12579086d34f0c0ccfccfd7f4790823",
|
||||
"source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Canon Federation and Concept Ownership Across InfoTech and Commerce"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-workplan-identity/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-007",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "accepted-1",
|
||||
"revision_path": "adr/custodian-workplan-identity/v1/revisions/accepted-1/index.html",
|
||||
"source_digest": "69f463795bdf1769c11415e9c8afa170d6fe62f04a554f7573f269000b5c4b08",
|
||||
"source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "accepted",
|
||||
"title": "Workplan Identity Uniqueness, Single Registrar, and Repo Worker Topology"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-hub-authority/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-010",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "draft-1",
|
||||
"revision_path": "adr/custodian-hub-authority/v1/revisions/draft-1/index.html",
|
||||
"source_digest": "8ea4448b7729035ae6bee044867ac9fd8b4940ea7013eb2b0256407cba1a0500",
|
||||
"source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "proposed",
|
||||
"title": "Hub Authority, Local Cache, and the Two Kinds of Hub Data"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/custodian-federated-namespaces/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "CUST-ADR-011",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "the-custodian",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "draft-2",
|
||||
"revision_path": "adr/custodian-federated-namespaces/v1/revisions/draft-2/index.html",
|
||||
"source_digest": "f94f429c72f6cfd01ee83f1e5689d2d10ae52d7588d7cbd3ca40aca7eef46fb0",
|
||||
"source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md",
|
||||
"source_repo": "the-custodian",
|
||||
"source_revision": "4039c9d1c08c92014ecc0a65dda63cc73ba187bb",
|
||||
"status": "proposed",
|
||||
"title": "Federated Namespaces: Four Planes, Declared Posture, and the Limits of Reconciliation"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/railiance-s3-platform-service-boundary/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "RPLAT-ADR-0001",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "railiance-platform",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "1.0",
|
||||
"revision_path": "adr/railiance-s3-platform-service-boundary/v1/revisions/1.0/index.html",
|
||||
"source_digest": "63697581401b53a8437835c2bb8b40f8054cc40d0bc7a2972f83a4a10377f6ba",
|
||||
"source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de",
|
||||
"status": "accepted",
|
||||
"title": "ADR-0001 \u2014 S3 owns platform services, not the substrate beneath them"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/railiance-placement-policy-ownership/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "RPLAT-ADR-0002",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "railiance-platform",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "1.0",
|
||||
"revision_path": "adr/railiance-placement-policy-ownership/v1/revisions/1.0/index.html",
|
||||
"source_digest": "cfc0ad202c2eeeefd963127ff1defa127c715c001ecc684ab8759733bd8fb9f8",
|
||||
"source_path": "docs/adr/ADR-0002-placement-policy-ownership.md",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de",
|
||||
"status": "proposed",
|
||||
"title": "ADR-0002 \u2014 S3 owns the placement rule; the package repo owns the number"
|
||||
},
|
||||
{
|
||||
"canonical_path": "adr/railiance-decisions-live-in-the-repo/v1/index.html",
|
||||
"currency": "current",
|
||||
"id": "RPLAT-ADR-0003",
|
||||
"last_reviewed": "2026-08-17",
|
||||
"lifecycle": "active",
|
||||
"owner": "railiance-platform",
|
||||
"review_due": "2027-02-17",
|
||||
"revision": "1.0",
|
||||
"revision_path": "adr/railiance-decisions-live-in-the-repo/v1/revisions/1.0/index.html",
|
||||
"source_digest": "9b12ab6aa0e6f9eba03465782c35d6ff4683b682191599e38f4f9614cde9fa1b",
|
||||
"source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_revision": "56d516e10cdad6691f254ec9cb11f11ea364f7de",
|
||||
"status": "accepted",
|
||||
"title": "ADR-0003 \u2014 Decisions that bind others live in docs/adr, not only in the State Hub"
|
||||
},
|
||||
{
|
||||
"canonical_path": "standards/iam-profile/v0.3/index.html",
|
||||
"currency": "current",
|
||||
"id": "netkingdom-iam-profile-v0.3",
|
||||
"last_reviewed": "2026-07-23",
|
||||
"lifecycle": "active",
|
||||
"owner": "net-kingdom",
|
||||
"review_due": "2027-01-23",
|
||||
"revision": "0.3",
|
||||
"revision_path": "standards/iam-profile/v0.3/revisions/0.3/index.html",
|
||||
"source_digest": "6287be08e35ddefc8e93d3b127cd8a1be27dc311b014becdbcfb78c4164faa0a",
|
||||
"source_path": "canon/standards/iam-profile_v0.3.md",
|
||||
"source_repo": "net-kingdom",
|
||||
"source_revision": "ccc2618daee997bb4bd4249613d7c4c7344845cf",
|
||||
"status": "accepted",
|
||||
"title": "NetKingdom IAM Profile v0.3"
|
||||
}
|
||||
],
|
||||
"generated_as_of": "2026-08-19",
|
||||
|
|
|
|||
319
build/standards/iam-profile/v0.3/index.html
Normal file
319
build/standards/iam-profile/v0.3/index.html
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="ccc2618daee997bb4bd4249613d7c4c7344845cf">
|
||||
<meta name="policy-source-digest" content="6287be08e35ddefc8e93d3b127cd8a1be27dc311b014becdbcfb78c4164faa0a">
|
||||
<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</span> <span>net-kingdom</span> <span>reviewed 2026-07-23</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 · ccc2618daee997bb4bd4249613d7c4c7344845cf</code></p><p class="sub">Review due: 2027-01-23</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 <issuer>/.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:<grouping>:<name></code>, where <code><grouping></code> is one of the taxonomy ratified by ADR-0013:</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 <strong>onboarding-risk / entity-shape</strong> classification only. It does not gate 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 >= 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</span><span>net-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf</span></footer></main></div></div></html>
|
||||
319
build/standards/iam-profile/v0.3/revisions/0.3/index.html
Normal file
319
build/standards/iam-profile/v0.3/revisions/0.3/index.html
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="ccc2618daee997bb4bd4249613d7c4c7344845cf">
|
||||
<meta name="policy-source-digest" content="6287be08e35ddefc8e93d3b127cd8a1be27dc311b014becdbcfb78c4164faa0a">
|
||||
<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</span> <span>net-kingdom</span> <span>reviewed 2026-07-23</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 · ccc2618daee997bb4bd4249613d7c4c7344845cf</code></p><p class="sub">Review due: 2027-01-23</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 <issuer>/.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:<grouping>:<name></code>, where <code><grouping></code> is one of the taxonomy ratified by ADR-0013:</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 <strong>onboarding-risk / entity-shape</strong> classification only. It does not gate 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 >= 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</span><span>net-kingdom · canon/standards/iam-profile_v0.3.md · ccc2618daee997bb4bd4249613d7c4c7344845cf</span></footer></main></div></div></html>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<!doctype html>
|
||||
<html lang="en"><meta charset="utf-8">
|
||||
<meta name="policy-source-revision" content="0e0962e68b39fdcfb633b5058602174a36416a68">
|
||||
<meta name="policy-source-revision" content="ccc2618daee997bb4bd4249613d7c4c7344845cf">
|
||||
<meta name="policy-source-digest" content="99f802d91a0b3a65f0dac58230d8904f7c61cf3f81eff072fbbc59b634612a8a">
|
||||
<title>NetKingdom Tenancy Posture v0.1</title>
|
||||
<style>
|
||||
|
|
@ -191,7 +191,7 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
|
|||
@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-8</span> <span>net-kingdom</span> <span>reviewed 2026-08-17</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 · 0e0962e68b39fdcfb633b5058602174a36416a68</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="#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>
|
||||
<div class="wrap"><header><div class="eyebrow"><span>netkingdom-tenancy-posture</span> <span class="stat">proposed · draft-8</span> <span>net-kingdom</span> <span>reviewed 2026-08-17</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 · ccc2618daee997bb4bd4249613d7c4c7344845cf</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="#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-8; 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>
|
||||
<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>
|
||||
|
|
@ -441,4 +441,4 @@ per consumer: 14 connections (12 runtime + 2 migration)</pre>
|
|||
</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-8 · proposed</span><span>net-kingdom · canon/standards/tenancy-posture_v0.1.md · 0e0962e68b39fdcfb633b5058602174a36416a68</span></footer></main></div></div></html>
|
||||
</section><footer><span>netkingdom-tenancy-posture · draft-8 · proposed</span><span>net-kingdom · canon/standards/tenancy-posture_v0.1.md · ccc2618daee997bb4bd4249613d7c4c7344845cf</span></footer></main></div></div></html>
|
||||
|
|
|
|||
|
|
@ -1,30 +1,29 @@
|
|||
# ADR review ledger summary
|
||||
|
||||
Rows: 136
|
||||
Rows: 144
|
||||
|
||||
## Inventory dispositions
|
||||
|
||||
- `excluded`: 3
|
||||
- `metadata-pending`: 100
|
||||
- `published`: 25
|
||||
- `unsupported-format`: 8
|
||||
- `metadata-pending`: 93
|
||||
- `published`: 38
|
||||
- `unsupported-format`: 10
|
||||
|
||||
## Proposed dispositions
|
||||
|
||||
- `conflict`: 5
|
||||
- `publish`: 32
|
||||
- `local`: 36
|
||||
- `publish`: 82
|
||||
- `superseded`: 5
|
||||
- `unreviewed`: 94
|
||||
- `unreviewed`: 16
|
||||
|
||||
## Front-matter `id` collisions
|
||||
|
||||
- `ADR-001`: coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md, the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md
|
||||
- `ADR-002`: coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md, the-custodian/canon/architecture/adr-002-custodian-agent-runtime-design.md
|
||||
- `ADR-003`: coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md, the-custodian/canon/architecture/adr-003-materialized-derived-state.md
|
||||
- `ADR-004`: coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md, the-custodian/canon/architecture/adr-004-connectivity-first-network-posture.md
|
||||
- `ADR-001`: coulomb-loop/docs/adr/ADR-001-workplan-prefix.md, kaizen-agentic/docs/adr/ADR-001-workplan-convention.md, rein-aharness/docs/adr/ADR-001-agent-harness-architecture.md
|
||||
- `ADR-002`: coulomb-loop/docs/adr/ADR-002-customer-supplier-boundary.md, kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md
|
||||
- `ADR-003`: coulomb-loop/docs/adr/ADR-003-cadence-ramp-policy.md, kaizen-agentic/docs/adr/ADR-003-protocols-artifact-convention.md
|
||||
- `ADR-004`: coulomb-loop/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md, kaizen-agentic/docs/adr/ADR-004-project-metrics-convention.md
|
||||
- `ADR-0001`: coulomb-social/docs/adr/ADR-0001-netkingdom-identity.md, key-cape/docs/adr/ADR-0001-choose-go-for-keycape.md, target-revenue/docs/adr/ADR-0001-stage0-library-stack.md
|
||||
- `ADR-005`: kaizen-agentic/docs/adr/ADR-005-scheduled-agent-execution.md, the-custodian/canon/architecture/adr-005-cross-repo-workplans-project-repos.md
|
||||
- `netkingdom-iam-profile`: net-kingdom/canon/standards/iam-profile_v0.2.md, net-kingdom/canon/standards/iam-profile_v0.3.md
|
||||
|
||||
## Bare ADR-NNNN collisions
|
||||
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -34,7 +34,7 @@
|
|||
6
|
||||
],
|
||||
"successor": "net-kingdom/canon/standards/iam-profile_v0.3.md",
|
||||
"review_notes": "v0.3 says it supersedes v0.2, but v0.2 is still status accepted and shares id netkingdom-iam-profile. Who rules: net-kingdom (status + unique id)."
|
||||
"review_notes": "Status set to superseded; unique id netkingdom-iam-profile-v0.2."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
|
|
@ -45,7 +45,7 @@
|
|||
6
|
||||
],
|
||||
"successor": "",
|
||||
"review_notes": "Current IAM profile. Cannot publish until id is unique (e.g. netkingdom-iam-profile-v0.3). Who rules: net-kingdom."
|
||||
"review_notes": "Id now netkingdom-iam-profile-v0.3; ready to publish."
|
||||
},
|
||||
{
|
||||
"source_repo": "railiance-hosts",
|
||||
|
|
@ -304,6 +304,694 @@
|
|||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Owner-ready; harvest request 2026-08-18."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/tenancy-posture_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Already published."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/architecture/net-kingdom_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "First-wave stub, published."
|
||||
},
|
||||
{
|
||||
"source_repo": "policy-nexus",
|
||||
"source_path": "docs/architecture/policy-nexus_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "First-wave stub, published."
|
||||
},
|
||||
{
|
||||
"source_repo": "railiance-master",
|
||||
"source_path": "docs/architecture/railiance_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "First-wave stub, published."
|
||||
},
|
||||
{
|
||||
"source_repo": "state-hub",
|
||||
"source_path": "docs/architecture/state-hub_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "First-wave stub, published."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/coulomb-estate_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "First-wave stub, published."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/README.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Directory index, not a governing record."
|
||||
},
|
||||
{
|
||||
"source_repo": "ops-warden",
|
||||
"source_path": "docs/adr/README.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Directory index, not a governing record."
|
||||
},
|
||||
{
|
||||
"source_repo": "railiance-platform",
|
||||
"source_path": "docs/adr/README.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Directory index, not a governing record."
|
||||
},
|
||||
{
|
||||
"source_repo": "key-cape",
|
||||
"source_path": "docs/adr/ADR-0001-choose-go-for-keycape.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Language choice; audience is this repo."
|
||||
},
|
||||
{
|
||||
"source_repo": "binect-js",
|
||||
"source_path": "docs/adr/001-no-listall-method.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Client API shape; no cross-repo bind."
|
||||
},
|
||||
{
|
||||
"source_repo": "markitect-main",
|
||||
"source_path": "docs/adr/ADR-001-client-side-debug-storage.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Implementation storage for debug UI."
|
||||
},
|
||||
{
|
||||
"source_repo": "markitect-main",
|
||||
"source_path": "docs/adr/ADR-002-robustness-principle-for-production-use.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Product robustness note for Markitect."
|
||||
},
|
||||
{
|
||||
"source_repo": "evidence-binder",
|
||||
"source_path": "docs/adr/ADR-0001-reference-ui-surface.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Binder-owned UI surface."
|
||||
},
|
||||
{
|
||||
"source_repo": "target-revenue",
|
||||
"source_path": "docs/adr/ADR-0001-stage0-library-stack.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Product stack choice."
|
||||
},
|
||||
{
|
||||
"source_repo": "target-revenue",
|
||||
"source_path": "docs/adr/ADR-0002-hosted-trust-service-stack.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Product stack choice."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0005-v1-tech-stack.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "V1 stack preference, not a cross-repo contract."
|
||||
},
|
||||
{
|
||||
"source_repo": "glas-harness",
|
||||
"source_path": "docs/adr/ADR-002-credential-brokering-and-composable-reins.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Partly open; not current governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "glas-harness",
|
||||
"source_path": "docs/adr/ADR-004-composable-reins-stay-deferred.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Explicitly deferred."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/contrib-templates/br-template.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Template, not governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/contrib-templates/ep-template.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Template, not governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/contrib-templates/fr-template.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Template, not governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/contrib-templates/upr-template.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Template, not governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "flex-auth",
|
||||
"source_path": "docs/adr/0001-implementation-language-and-skeleton.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Flex-auth implementers consume this."
|
||||
},
|
||||
{
|
||||
"source_repo": "flex-auth",
|
||||
"source_path": "docs/adr/0002-rego-in-markdown-policy-format.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Policy format others write."
|
||||
},
|
||||
{
|
||||
"source_repo": "flex-auth",
|
||||
"source_path": "docs/adr/0003-topaz-aligned-mvp.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Alignment contract for the evaluator."
|
||||
},
|
||||
{
|
||||
"source_repo": "flex-auth",
|
||||
"source_path": "docs/adr/0004-inbound-caller-authentication.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Caller identity binds every check client."
|
||||
},
|
||||
{
|
||||
"source_repo": "rapp-postgres",
|
||||
"source_path": "docs/adr/ADR-0001-consumer-boundary-and-tenant-isolation.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Shared storage isolation binds consumers."
|
||||
},
|
||||
{
|
||||
"source_repo": "rapp-postgres",
|
||||
"source_path": "docs/adr/ADR-0002-data-retention-and-erasure.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Retention/erasure on shared PG."
|
||||
},
|
||||
{
|
||||
"source_repo": "rapp-postgres",
|
||||
"source_path": "docs/adr/ADR-0003-e3-row-level-security-contract.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "E3 RLS contract."
|
||||
},
|
||||
{
|
||||
"source_repo": "rapp-postgres",
|
||||
"source_path": "docs/adr/ADR-0004-platform-pg-cell-ceiling.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Cell ceiling binds placement."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0001-content-addressed-storage.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Storage address contract."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0002-event-log-source-of-truth.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Event-log SoR."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0003-manifest-canonical-cbor.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Manifest canonicalisation."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0004-control-plane-data-plane-contract.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Control/data plane split."
|
||||
},
|
||||
{
|
||||
"source_repo": "artifact-store",
|
||||
"source_path": "docs/adr/0006-oci-compatibility-reachable.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "OCI reachability constraint."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/credential-management_v0.2.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Credential standard for implementers."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/playbook-capability-contract_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Playbook contract."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/tenant-engine-boundary-contract_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Tenant-engine boundary."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/user-engine-boundary-contract_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "User-engine boundary."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Identity architecture others implement."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0007-security-orchestration-boundary.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Orchestration boundary."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0008-object-storage-sts-credential-vending.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "STS vending boundary."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Orchestration vs dependency."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "IAM profile ownership."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0012-playbook-capability-contract-ownership.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Playbook ownership."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Onboarding taxonomy."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Tenant capability roles."
|
||||
},
|
||||
{
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "docs/adr/ADR-0015-netkingdom-railiance-workload-packaging-and-relational-platform.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Workload packaging."
|
||||
},
|
||||
{
|
||||
"source_repo": "railiance-infra",
|
||||
"source_path": "docs/adr/ADR-005-k3s-api-tunnel-only.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "k3s API exposure binds the fleet."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-social",
|
||||
"source_path": "docs/adr/ADR-0001-netkingdom-identity.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Identity choice for the social surface."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-social",
|
||||
"source_path": "docs/adr/ADR-0003-page-centric-markdown-sor.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Content SoR."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-social",
|
||||
"source_path": "docs/adr/ADR-0004-content-plane-thin-git-upgrades.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Content plane upgrades."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-loop",
|
||||
"source_path": "docs/adr/ADR-001-workplan-prefix.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Workplan prefix convention used fleet-wide."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-001-workplan-convention.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Workplan convention consumed by agents."
|
||||
},
|
||||
{
|
||||
"source_repo": "glas-harness",
|
||||
"source_path": "docs/adr/ADR-001-rein-harness-family.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Harness family routing."
|
||||
},
|
||||
{
|
||||
"source_repo": "glas-harness",
|
||||
"source_path": "docs/adr/ADR-003-scheduling-and-blueprint-sourcing-stay-rein-local.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Scheduling locality."
|
||||
},
|
||||
{
|
||||
"source_repo": "rein-aharness",
|
||||
"source_path": "docs/adr/ADR-001-agent-harness-architecture.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Shared harness, instances in consumers."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/constitution/custodian_constitution_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Estate constitution."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/constitution/bootstrap-protocol_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Bootstrap protocol."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/work-record-types_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Work-record type registry."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/workplan-terminology-fleet_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Fleet workplan terminology."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/repo-classification-standard_v1.0.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Repo classification."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/project-repository-flavor_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "prj- flavor."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/contribution-convention_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Contribution convention."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/autonomy-lanes_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Autonomy lanes."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/sbom-convention_v0.1.md",
|
||||
"proposed_disposition": "publish",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "SBOM convention."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-loop",
|
||||
"source_path": "docs/adr/ADR-002-customer-supplier-boundary.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Engagement boundary for the loop product."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-loop",
|
||||
"source_path": "docs/adr/ADR-003-cadence-ramp-policy.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Loop cadence policy."
|
||||
},
|
||||
{
|
||||
"source_repo": "coulomb-loop",
|
||||
"source_path": "docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Loop rotation heuristic."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-002-project-memory-convention.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen project memory."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-003-protocols-artifact-convention.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen protocols artifact."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-004-project-metrics-convention.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen metrics."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-005-scheduled-agent-execution.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen scheduler."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-006-customer-engagement-convention.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen engagement."
|
||||
},
|
||||
{
|
||||
"source_repo": "kaizen-agentic",
|
||||
"source_path": "docs/adr/ADR-007-forward-deployed-engagement-convention.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Kaizen forward-deployed engagement."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/coulombcore-production-freeze_v0.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Time-boxed freeze, not standing architecture."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/credential-management_v0.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Superseded in spirit by net-kingdom credential standard; leave local until owner marks successor."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/business-app-service-contract_v0.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "App contract; owner should confirm governing vs local."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/federated-organization-standard_v1.0.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Draft; not yet governing."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/orthogonal-architecture_v1.0.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Draft OAS."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/orthogonal-architecture-schema_v1.0.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Schema companion to draft OAS."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/privileged-execution-control-schema_v0.2.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Schema companion."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/privileged-execution-control-schema-cicd_v0.2.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Schema companion."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/privileged-execution-control-schema-kubernetes-rbac_v0.2.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Schema companion."
|
||||
},
|
||||
{
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/standards/privileged-execution-control-schema-os-sudo_v0.2.1.md",
|
||||
"proposed_disposition": "local",
|
||||
"conflict_kinds": [],
|
||||
"successor": "",
|
||||
"review_notes": "Schema companion."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
107
publication.json
107
publication.json
|
|
@ -33,6 +33,9 @@
|
|||
},
|
||||
"ops-warden": {
|
||||
"path": "../ops-warden"
|
||||
},
|
||||
"railiance-platform": {
|
||||
"path": "../railiance-platform"
|
||||
}
|
||||
},
|
||||
"documents": [
|
||||
|
|
@ -239,6 +242,110 @@
|
|||
"canonical_path": "adr/ops-warden-implement-narrowly/v1/index.html",
|
||||
"revision_path": "adr/ops-warden-implement-narrowly/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-001",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md",
|
||||
"canonical_path": "adr/custodian-workplans-as-repo-artefacts/v1/index.html",
|
||||
"revision_path": "adr/custodian-workplans-as-repo-artefacts/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-002",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md",
|
||||
"canonical_path": "adr/custodian-agent-runtime/v1/index.html",
|
||||
"revision_path": "adr/custodian-agent-runtime/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-003",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-003-materialized-derived-state.md",
|
||||
"canonical_path": "adr/custodian-materialized-derived-state/v1/index.html",
|
||||
"revision_path": "adr/custodian-materialized-derived-state/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-004",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md",
|
||||
"canonical_path": "adr/custodian-connectivity-first/v1/index.html",
|
||||
"revision_path": "adr/custodian-connectivity-first/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-005",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md",
|
||||
"canonical_path": "adr/custodian-cross-repo-workplans/v1/index.html",
|
||||
"revision_path": "adr/custodian-cross-repo-workplans/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-006",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md",
|
||||
"canonical_path": "adr/custodian-canon-federation/v1/index.html",
|
||||
"revision_path": "adr/custodian-canon-federation/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-007",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md",
|
||||
"canonical_path": "adr/custodian-workplan-identity/v1/index.html",
|
||||
"revision_path": "adr/custodian-workplan-identity/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-010",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md",
|
||||
"canonical_path": "adr/custodian-hub-authority/v1/index.html",
|
||||
"revision_path": "adr/custodian-hub-authority/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "CUST-ADR-011",
|
||||
"source_repo": "the-custodian",
|
||||
"source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md",
|
||||
"canonical_path": "adr/custodian-federated-namespaces/v1/index.html",
|
||||
"revision_path": "adr/custodian-federated-namespaces/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "RPLAT-ADR-0001",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md",
|
||||
"canonical_path": "adr/railiance-s3-platform-service-boundary/v1/index.html",
|
||||
"revision_path": "adr/railiance-s3-platform-service-boundary/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "RPLAT-ADR-0002",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_path": "docs/adr/ADR-0002-placement-policy-ownership.md",
|
||||
"canonical_path": "adr/railiance-placement-policy-ownership/v1/index.html",
|
||||
"revision_path": "adr/railiance-placement-policy-ownership/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "RPLAT-ADR-0003",
|
||||
"source_repo": "railiance-platform",
|
||||
"source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md",
|
||||
"canonical_path": "adr/railiance-decisions-live-in-the-repo/v1/index.html",
|
||||
"revision_path": "adr/railiance-decisions-live-in-the-repo/v1/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
},
|
||||
{
|
||||
"id": "netkingdom-iam-profile-v0.3",
|
||||
"source_repo": "net-kingdom",
|
||||
"source_path": "canon/standards/iam-profile_v0.3.md",
|
||||
"canonical_path": "standards/iam-profile/v0.3/index.html",
|
||||
"revision_path": "standards/iam-profile/v0.3/revisions/{revision}/index.html",
|
||||
"review_interval": "6m"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -254,8 +254,8 @@
|
|||
"source_repo": "net-kingdom"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/standards/iam-profile_v0.3.md",
|
||||
"source_repo": "net-kingdom"
|
||||
},
|
||||
|
|
@ -488,20 +488,20 @@
|
|||
"source_repo": "railiance-master"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "docs/adr/ADR-0001-s3-platform-service-boundary.md",
|
||||
"source_repo": "railiance-platform"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "docs/adr/ADR-0002-placement-policy-ownership.md",
|
||||
"source_repo": "railiance-platform"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "docs/adr/ADR-0003-decisions-live-in-the-repo.md",
|
||||
"source_repo": "railiance-platform"
|
||||
},
|
||||
|
|
@ -560,44 +560,44 @@
|
|||
"source_repo": "target-revenue"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-001-workplans-as-repo-artefacts.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-002-custodian-agent-runtime-design.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-003-materialized-derived-state.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-004-connectivity-first-network-posture.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-005-cross-repo-workplans-project-repos.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-006-canon-federation-concept-ownership.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
|
|
@ -608,14 +608,14 @@
|
|||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-010-hub-authority-and-local-cache-model.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"disposition": "published",
|
||||
"reason": "Published through an explicit publication.json document entry.",
|
||||
"source_path": "canon/architecture/adr-011-federated-namespaces-and-reconciliation-limits.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
|
|
@ -625,6 +625,54 @@
|
|||
"source_path": "canon/architecture/coulomb-estate_v0.1.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "unsupported-format",
|
||||
"reason": "Inventoried governing source is not Markdown and has no renderer yet.",
|
||||
"source_path": "canon/architecture/infospace/.gitignore",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/discipline/arc42.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/entities/coulomb-estate.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/entities/net-kingdom.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/entities/policy-nexus.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/entities/railiance.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
"source_path": "canon/architecture/infospace/entities/state-hub.md",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "unsupported-format",
|
||||
"reason": "Inventoried governing source is not Markdown and has no renderer yet.",
|
||||
"source_path": "canon/architecture/infospace/infospace.yaml",
|
||||
"source_repo": "the-custodian"
|
||||
},
|
||||
{
|
||||
"disposition": "metadata-pending",
|
||||
"reason": "In scope; awaits explicit publication addressing and owner/revision/review metadata.",
|
||||
|
|
|
|||
|
|
@ -195,7 +195,7 @@ on chapter 9 (now present on the estate stub; re-check in T04).
|
|||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T04
|
||||
status: progress
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
|
|
@ -220,6 +220,10 @@ copies. Publish (after prefix/metadata packets): estate ADRs 001–007 and
|
|||
Profile v0.3. Remainder still `unreviewed`. Kind 5 against the estate
|
||||
chapter 9: the listed estate ADRs match; no miss on that document.
|
||||
|
||||
Completed 2026-08-19. Remaining rows are classified: fleet-binding
|
||||
records `publish`, product-local notes `local`, templates and draft
|
||||
companions `local`. Unsupported formats stay inventoried, not published.
|
||||
|
||||
### T05 — Cleanup packets
|
||||
|
||||
```task
|
||||
|
|
@ -276,7 +280,7 @@ publication-ready) are registered.
|
|||
|
||||
```task
|
||||
id: POLICY-NEXUS-WP-0003-T07
|
||||
status: todo
|
||||
status: progress
|
||||
priority: medium
|
||||
```
|
||||
|
||||
|
|
@ -287,6 +291,10 @@ unresolved `conflict` rows as current.
|
|||
This is a PR in the owning repo of the arc42 document, same as T05.
|
||||
Depends on WP-0002-T04/T05 and on this workplan's T04.
|
||||
|
||||
2026-08-19: first-wave chapter 9 lists CUST-ADR-001–011, published
|
||||
Railiance/NetKingdom/activity-core/ops-warden/platform ADRs, and keeps
|
||||
hosts/infra conflicts out. Stubs bumped to draft-2.
|
||||
|
||||
## Sequencing
|
||||
|
||||
T01 → T02 → T03 and T04 (T04's kind-5 slice waits on WP-0002-T04).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue