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>
|
||||
Loading…
Add table
Add a link
Reference in a new issue