code wiki / _hdl_build / nx_capability_placement.nx
nx_capability_placement.nx source
↩ module page · 206 lines · 13469 B
1// nx_capability_placement.nx -- the "TRUE RACI PLACEMENT" governance instrument (operator 2026-07-16:
2// "make sure everything logically ... is getting true RACI aka what should live in workstreams, in agents,
3// in apis, in mcp, etc"). RACI answers WHO is accountable; this answers WHERE the capability should LIVE.
4// The architect (composition) + warden (policy bounds) own it. A standing rubric that gives every capability
5// a placement verdict + flags misplacements -> prevents future sprawl by construction (every new capability
6// gets a home BY RULE, not by accident).
7//
8// THE SURFACES (where a capability can live):
9// ORGAN -- internal library/primitive/gate/vocab: imported by other organs, NEVER directly exposed
10// API -- a served network surface (daemon w/ a port): machine-to-machine, HTTP
11// MCP -- an AGENT-callable tool: the crew/Claude invokes it directly (read=broad, write=cap, destr=ocap+confirm)
12// WORKSTREAM -- a multi-step, supervised/human-checkpointed BUILD or campaign (WMS work-unit), not a single call
13// AGENT -- a capability a crew ROLE owns + runs autonomously (nishi_crew dispatch); the role IS the agent
14// HUMAN -- a person's judgment (operator/sponsor); not automatable
15//
16// ★THE PURE RULE (cp_place), priority-ordered + adversarially GATED (un-gameable):
17// 0. no single Accountable role -> RACI-GAP (assign an owner BEFORE placing -- accountability first)
18// 1. internal (primitive/gate/vocab) -> ORGAN (and if currently MCP -> VIOLATION: over-exposed primitive)
19// 2. multi-step campaign / human-judg. -> WORKSTREAM
20// 3. role-autonomous -> AGENT (dispatch)
21// 4. served (daemon/port) -> API
22// 5. read-only, agent-relevant -> MCP (broad)
23// 6. write/mutating -> MCP + cap-gate
24// 7. destructive/irreversible -> MCP + ocap + confirm (never a bare API/MCP)
25// The order enforces the doctrine: accountability first, internal-never-exposed, destructive-always-guarded.
26//
27// nx_capability_placement gate -- adversarial self-test (default)
28// nx_capability_placement classify <capfile> -- placement verdict + action per crew capability row
29// license_tier: ORIGINAL module: nishi-core.architect.placement
30import "nx_syscalls.nx"
31// ★THE BUFFER IS AUTHORED; THE READ BOUND IS A CONSEQUENCE. These were CP_MAGIC_262144 and
32// CP_MAGIC_262143 -- names that restate the value and hide that the second is simply the first minus one,
33// leaving room for the terminator. The cap is the bound on the read loop below (`CP_CONF_CAP - n`), so if
34// the buffer is ever resized and the cap is not, the loop either short-reads or writes past the end --
35// and both still compile. Derived, there is nowhere left to type it wrong.
36const CP_CONF_BYTES: i64 = 262144
37const CP_CONF_CAP: i64 = CP_CONF_BYTES - 1
38
39// surfaces
40const CP_ORGAN: i64 = 1
41const CP_API: i64 = 2
42const CP_MCP: i64 = 3
43const CP_WORKSTREAM: i64 = 4
44const CP_AGENT: i64 = 5
45const CP_HUMAN: i64 = 6
46const CP_RACI_GAP: i64 = 0
47// io classes
48const CP_IO_NONE: i64 = 0
49const CP_IO_READ: i64 = 1
50const CP_IO_WRITE: i64 = 2
51const CP_IO_DESTRUCT:i64 = 3
52
53func cp_p(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
54func cp_pn_i(v: i64) -> i64 { let b: *u8 = sys_mmap(24); var m: i64 = v; var k: i64 = 0; let t: *u8 = sys_mmap(24); if m == 0 { t[0] = 48 as u8; k = 1 } while m > 0 { t[k] = (48+(m%10)) as u8; m = m/10; k = k+1 } var i: i64 = 0; while i < k { b[i] = t[k-1-i]; i = i+1 } sys_write(1, b, k); return 0 }
55func cp_streq(a: *u8, b: *u8) -> i64 { var i: i64 = 0; while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 } if b[i] != (0 as u8) { return 0 } return 1 }
56func cp_ends(s: *u8, suf: *u8) -> i64 {
57 var sl: i64 = 0; while s[sl] != (0 as u8) { sl = sl + 1 }
58 var fl: i64 = 0; while suf[fl] != (0 as u8) { fl = fl + 1 }
59 if fl > sl { return 0 }
60 var i: i64 = 0; while i < fl { if s[sl-fl+i] != suf[i] { return 0 } i = i + 1 }
61 return 1
62}
63func cp_contains(s: *u8, needle: *u8) -> i64 {
64 var sl: i64 = 0; while s[sl] != (0 as u8) { sl = sl + 1 }
65 var nl: i64 = 0; while needle[nl] != (0 as u8) { nl = nl + 1 }
66 if nl == 0 { return 1 } if nl > sl { return 0 }
67 var i: i64 = 0
68 while i + nl <= sl { var j: i64 = 0; var m: i64 = 1; while j < nl { if s[i+j] != needle[j] { m = 0; j = nl } else { j = j + 1 } } if m == 1 { return 1 } i = i + 1 }
69 return 0
70}
71func cp_sname(v: i64) -> *u8 {
72 if v == CP_ORGAN { return "ORGAN" as *u8 }
73 if v == CP_API { return "API" as *u8 }
74 if v == CP_MCP { return "MCP" as *u8 }
75 if v == CP_WORKSTREAM { return "WORKSTREAM" as *u8 }
76 if v == CP_AGENT { return "AGENT" as *u8 }
77 if v == CP_HUMAN { return "HUMAN" as *u8 }
78 return "RACI-GAP" as *u8
79}
80
81// ★THE PURE RULE (gated). is_human overrides. Order = the doctrine.
82func cp_place(has_a: i64, is_human: i64, is_internal: i64, is_multistep: i64, is_role_auto: i64, is_served: i64, io: i64) -> i64 {
83 if is_human == 1 { return CP_HUMAN }
84 if has_a != 1 { return CP_RACI_GAP } // accountability FIRST
85 if is_internal == 1 { return CP_ORGAN } // primitives/gates/vocab never exposed
86 if is_multistep == 1 { return CP_WORKSTREAM }
87 if is_role_auto == 1 { return CP_AGENT }
88 if is_served == 1 { return CP_API }
89 return CP_MCP // read/write/destruct all land on MCP (guard-level differs, below)
90}
91// the MCP guard level a given io demands (0 none/read=broad, 1 cap, 2 ocap+confirm) -- destructive is never bare
92func cp_guard(io: i64) -> i64 {
93 if io == CP_IO_DESTRUCT { return 2 }
94 if io == CP_IO_WRITE { return 1 }
95 return 0
96}
97
98// ---- adversarial gate: the doctrine must hold ----
99func cp_gate() -> i64 {
100 cp_p("=== nx_capability_placement GATE -- accountability-first, internal-never-exposed, destructive-guarded ===\n" as *u8)
101 var fail: i64 = 0
102 // T1 no Accountable -> RACI-GAP (before any placement)
103 if cp_place(0, 0, 0, 0, 0, 0, CP_IO_READ) == CP_RACI_GAP { cp_p(" [PASS] no Accountable -> RACI-GAP (assign owner first)\n" as *u8) } else { cp_p(" [FAIL] no-A\n" as *u8); fail = 1 }
104 // T2 ★internal primitive -> ORGAN even if someone wants it exposed (over-exposure is the violation)
105 if cp_place(1, 0, 1, 0, 0, 0, CP_IO_READ) == CP_ORGAN { cp_p(" [PASS] internal primitive -> ORGAN (never MCP -- over-exposing a primitive is the violation)\n" as *u8) } else { cp_p(" [FAIL] internal\n" as *u8); fail = 1 }
106 // T3 multi-step campaign -> WORKSTREAM, not a single MCP call
107 if cp_place(1, 0, 0, 1, 0, 0, CP_IO_WRITE) == CP_WORKSTREAM { cp_p(" [PASS] multi-step campaign -> WORKSTREAM (not a single call)\n" as *u8) } else { cp_p(" [FAIL] multistep\n" as *u8); fail = 1 }
108 // T4 role-autonomous -> AGENT (dispatch)
109 if cp_place(1, 0, 0, 0, 1, 0, CP_IO_READ) == CP_AGENT { cp_p(" [PASS] role-autonomous -> AGENT (nishi_crew dispatch)\n" as *u8) } else { cp_p(" [FAIL] agent\n" as *u8); fail = 1 }
110 // T5 served daemon -> API
111 if cp_place(1, 0, 0, 0, 0, 1, CP_IO_READ) == CP_API { cp_p(" [PASS] served daemon -> API\n" as *u8) } else { cp_p(" [FAIL] api\n" as *u8); fail = 1 }
112 // T6 read-only agent-relevant -> MCP (broad, guard=0)
113 if cp_place(1, 0, 0, 0, 0, 0, CP_IO_READ) == CP_MCP { if cp_guard(CP_IO_READ) == 0 { cp_p(" [PASS] read-only -> MCP broad (guard=0)\n" as *u8) } else { cp_p(" [FAIL] read-guard\n" as *u8); fail = 1 } } else { cp_p(" [FAIL] read-mcp\n" as *u8); fail = 1 }
114 // T7 ★destructive -> MCP but guard=2 (ocap+confirm), NEVER bare
115 if cp_place(1, 0, 0, 0, 0, 0, CP_IO_DESTRUCT) == CP_MCP { if cp_guard(CP_IO_DESTRUCT) == 2 { cp_p(" [PASS] destructive -> MCP + ocap + confirm (guard=2, never bare)\n" as *u8) } else { cp_p(" [FAIL] destr-guard not 2\n" as *u8); fail = 1 } } else { cp_p(" [FAIL] destr\n" as *u8); fail = 1 }
116 // T8 human -> HUMAN regardless
117 if cp_place(1, 1, 1, 1, 1, 1, CP_IO_DESTRUCT) == CP_HUMAN { cp_p(" [PASS] human judgment -> HUMAN (not automatable)\n" as *u8) } else { cp_p(" [FAIL] human\n" as *u8); fail = 1 }
118 if fail == 0 { cp_p("=== GATE GREEN: the placement doctrine holds -- every capability gets a home BY RULE ===\n" as *u8); sys_exit(0); return 0 }
119 cp_p("=== GATE RED ===\n" as *u8); sys_exit(1); return 1
120}
121
122// pipe-field n of line[ls..le) -> out
123func cp_field(buf: *u8, ls: i64, le: i64, n: i64, out: *u8, cap: i64) -> i64 {
124 var fs: i64 = ls; var seen: i64 = 0
125 while seen < n { if fs >= le { out[0] = 0 as u8; return 0 } if (buf[fs] as i64) == 124 { seen = seen + 1 } fs = fs + 1 }
126 var fe: i64 = fs; var g: i64 = 1
127 while g == 1 { if fe >= le { g = 0 } else { if (buf[fe] as i64) == 124 { g = 0 } else { fe = fe + 1 } } }
128 var o: i64 = 0; var k: i64 = fs
129 while k < fe { if (buf[k] as i64) != 13 { if o < cap - 1 { out[o] = buf[k]; o = o + 1 } } k = k + 1 }
130 out[o] = 0 as u8; return o
131}
132
133// infer capability properties from the row (organ name conventions + status), apply the rule, print verdict+action.
134// crew_capabilities.data columns: role | activity | organ | mcp_tool | status(mcp|dispatch|organ|concept|human)
135func cp_classify(path: *u8) -> i64 {
136 let fd: i64 = sys_openat_rd(path)
137 if fd < 0 { cp_p("classify: cannot read capability file\n" as *u8); return 1 }
138 let buf: *u8 = sys_mmap(CP_CONF_BYTES)
139 var n: i64 = 0; var r: i64 = 1
140 while r > 0 { r = sys_read(fd, (buf as i64 + n) as *u8, CP_CONF_CAP - n); if r > 0 { n = n + r } if n >= CP_CONF_CAP { r = 0 } }
141 sys_close(fd)
142 cp_p("=== TRUE RACI PLACEMENT -- where each crew capability should live (rule-derived) ===\n" as *u8)
143 let role: *u8 = sys_mmap(64); let act: *u8 = sys_mmap(64); let organ: *u8 = sys_mmap(96); let tool: *u8 = sys_mmap(64); let stat: *u8 = sys_mmap(32)
144 var gaps: i64 = 0; var exposeq: i64 = 0; var ok: i64 = 0; var viol: i64 = 0
145 var ls: i64 = 0; var i: i64 = 0
146 while i <= n {
147 var eol: i64 = 0; if i >= n { eol = 1 } else { if buf[i] == (10 as u8) { eol = 1 } }
148 if eol == 1 {
149 if i > ls { if buf[ls] != (35 as u8) {
150 cp_field(buf, ls, i, 0, role, 64)
151 cp_field(buf, ls, i, 1, act, 64)
152 cp_field(buf, ls, i, 2, organ, 96)
153 cp_field(buf, ls, i, 4, stat, 32)
154 if role[0] != (0 as u8) {
155 // property inference (honest heuristics)
156 let is_human: i64 = cp_streq(stat, "human" as *u8)
157 let has_a: i64 = 1 // rows in the ledger are RACI-owned by construction
158 var is_internal: i64 = 0
159 if cp_ends(organ, "_gate" as *u8) == 1 { is_internal = 1 }
160 if cp_ends(organ, "_test" as *u8) == 1 { is_internal = 1 }
161 var is_served: i64 = 0
162 if cp_contains(organ, "_daemon" as *u8) == 1 { is_served = 1 }
163 if cp_contains(organ, "_serve" as *u8) == 1 { is_served = 1 }
164 if cp_contains(organ, "hostctl" as *u8) == 1 { is_served = 1 }
165 // role-autonomous = the role dispatches this activity (status dispatch)
166 let is_role_auto: i64 = cp_streq(stat, "dispatch" as *u8)
167 let want: i64 = cp_place(has_a, is_human, is_internal, 0, is_role_auto, is_served, CP_IO_READ)
168 // current placement from status
169 cp_p(" " as *u8); cp_p(role); cp_p(" / " as *u8); cp_p(act)
170 cp_p(" now=" as *u8); cp_p(stat); cp_p(" -> should=" as *u8); cp_p(cp_sname(want))
171 // verdict
172 if cp_streq(stat, "concept" as *u8) == 1 { cp_p(" [BUILD-GAP: no organ -- build it]" as *u8); gaps = gaps + 1 }
173 else { if cp_streq(stat, "organ" as *u8) == 1 {
174 if want == CP_ORGAN { cp_p(" [OK: correctly internal]" as *u8); ok = ok + 1 }
175 else { cp_p(" [EXPOSE-GAP: built but not on " as *u8); cp_p(cp_sname(want)); cp_p("]" as *u8); exposeq = exposeq + 1 }
176 }
177 else { if cp_streq(stat, "mcp" as *u8) == 1 {
178 if is_internal == 1 { cp_p(" [VIOLATION: primitive over-exposed as MCP]" as *u8); viol = viol + 1 }
179 else { cp_p(" [OK: agent-callable]" as *u8); ok = ok + 1 }
180 }
181 else { cp_p(" [OK]" as *u8); ok = ok + 1 } } }
182 cp_p("\n" as *u8)
183 }
184 } }
185 ls = i + 1
186 }
187 i = i + 1
188 }
189 cp_p("--- placement summary: ok=" as *u8); cp_pn_i(ok)
190 cp_p(" build-gaps=" as *u8); cp_pn_i(gaps)
191 cp_p(" expose-gaps=" as *u8); cp_pn_i(exposeq)
192 cp_p(" VIOLATIONS=" as *u8); cp_pn_i(viol); cp_p("\n" as *u8)
193 if viol > 0 { return 1 }
194 return 0
195}
196
197func main(argc: i64, argv: *i64) -> i64 {
198 if argc < 2 { return cp_gate() }
199 if cp_streq(argv[1] as *u8, "gate" as *u8) == 1 { return cp_gate() }
200 if cp_streq(argv[1] as *u8, "classify" as *u8) == 1 {
201 if argc < 3 { cp_p("usage: nx_capability_placement classify <capfile>\n" as *u8); return 2 }
202 return cp_classify(argv[2] as *u8)
203 }
204 cp_p("usage: nx_capability_placement gate | classify <capfile>\n" as *u8)
205 return 2
206}