Skip to content

Commit e0b4c21

Browse files
committed
wip: a census gate pins the call sites that set the vouched-reference mark
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibvynRbCtMndW8EHNGc
1 parent 4f78f54 commit e0b4c21

1 file changed

Lines changed: 286 additions & 0 deletions

File tree

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
#!/usr/bin/env node
2+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
3+
4+
/**
5+
* Call-site census of the vouched-reference mark.
6+
*
7+
* node scripts/check-vouch-for-reference-callers.mjs
8+
* node scripts/check-vouch-for-reference-callers.mjs --self-test
9+
*
10+
* ## The rule it holds
11+
*
12+
* A write that is not a system write may name, in a `lookup`, `user` or
13+
* `master_detail` field, only a record its caller's own read door returns
14+
* (`assertReferencesResolve`, objectql). The one exception is a reference a
15+
* service verb vouches for on its own write (`vouchForReference`,
16+
* `@objectstack/core`): a record the same call authorized for the caller, set
17+
* only after that verb's own authorization, and never on a context a request,
18+
* an import, a flow or an agent tool hands the engine. Whether a call site
19+
* honours that is a judgement a reviewer makes once, when the call site is
20+
* written. This gate makes sure no call site arrives without that review: every
21+
* production source file that sets the mark is named in {@link ALLOWED_CALLERS}
22+
* with the exact number of call sites it holds, and the gate is red when a file
23+
* outside the list sets it, when a listed file holds more or fewer call sites
24+
* than its row, and when a row names a file that no longer sets it.
25+
*
26+
* "Sets the mark" is decided three ways, each a spelling that reaches the same
27+
* context key:
28+
*
29+
* 1. a call `vouchForReference(` (not a mention in a comment or in backticks);
30+
* 2. an import that renames it (`vouchForReference as …`), which would hide
31+
* every later call from (1);
32+
* 3. the key itself, outside the module that defines it — `VOUCHED_REFERENCES`
33+
* used as a computed property, or `Symbol.for('objectstack.core.vouchedReferences')`
34+
* spelled anywhere else — a context built with the key by hand.
35+
*
36+
* Test files (`*.test.*`, `*.spec.*`, `*.testkit.*`, `__tests__/`) are outside
37+
* the census: they set the mark on purpose to pin what it admits.
38+
*
39+
* The scan surface is git's (`git ls-files --cached --others --exclude-standard`
40+
* under `packages/`), so build output never reads as a call site.
41+
*
42+
* Adding a caller is an edit to {@link ALLOWED_CALLERS} in the same change,
43+
* with the reason in the row: what the verb created or authorized for the
44+
* caller, and which authorization it asked first.
45+
*/
46+
47+
import { execFileSync } from 'node:child_process';
48+
import { readFileSync } from 'node:fs';
49+
import { dirname, join } from 'node:path';
50+
import { fileURLToPath } from 'node:url';
51+
import { isEntrypoint } from './invoked-as.mjs';
52+
53+
const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
54+
55+
/** The module that defines the mark; its own spellings are not call sites. */
56+
const DEFINING_MODULE = 'packages/core/src/security/vouched-reference.ts';
57+
58+
/**
59+
* Every production file that sets the mark, with its exact call-site count and
60+
* the reason it may. Equality, not a ceiling: one more call site is a new
61+
* vouch nobody reviewed, one fewer is a row that no longer says what the file
62+
* does.
63+
*/
64+
export const ALLOWED_CALLERS = Object.freeze({
65+
'packages/services/service-storage/src/file-attachment-service.ts': {
66+
count: 2,
67+
reason:
68+
'the file-attachments writer: attachFileAs vouches for the sys_file it created in the same call, and ' +
69+
"attachUploadAs for the caller's own unheld pending upload it commits in the same unit — each only for " +
70+
'sys_attachment.file_id, after that verb\'s own attach authorization',
71+
},
72+
});
73+
74+
const SOURCE_FILE = /\.(?:[cm]?ts|tsx|[cm]?js|jsx)$/;
75+
const TEST_FILE = /(?:\.test\.|\.spec\.|\.testkit\.|\/__tests__\/|\/__fixtures__\/)/;
76+
77+
/** A line that is a comment, by its first non-blank characters. */
78+
const isCommentLine = (line) => /^\s*(?:\/\/|\/\*|\*)/.test(line);
79+
80+
/** Strip backtick-quoted spans, so prose naming `vouchForReference(` is no call. */
81+
const withoutBacktickSpans = (line) => line.replace(/`[^`]*`/g, '``');
82+
83+
/**
84+
* The census of one file's text: its call sites and the spellings that would
85+
* hide or bypass one.
86+
*/
87+
export function censusOf(path, text) {
88+
let calls = 0;
89+
const findings = [];
90+
const lines = String(text).split('\n');
91+
lines.forEach((raw, index) => {
92+
if (isCommentLine(raw)) return;
93+
const line = withoutBacktickSpans(raw.replace(/\/\/.*$/, ''));
94+
const where = `${path}:${index + 1}`;
95+
const callHits = line.match(/\bvouchForReference\s*\(/g);
96+
if (callHits && path !== DEFINING_MODULE) calls += callHits.length;
97+
if (/\bvouchForReference\s+as\s+\w/.test(line)) {
98+
findings.push(`${where}: renames vouchForReference on import — every later call would hide from this census`);
99+
}
100+
if (path === DEFINING_MODULE) return;
101+
if (/\[\s*VOUCHED_REFERENCES\s*\]/.test(line)) {
102+
findings.push(`${where}: builds the mark's key by hand ([VOUCHED_REFERENCES]) — call vouchForReference instead`);
103+
}
104+
if (/Symbol\.for\(\s*['"]objectstack\.core\.vouchedReferences['"]\s*\)/.test(line)) {
105+
findings.push(`${where}: spells the mark's symbol by hand — call vouchForReference instead`);
106+
}
107+
});
108+
return { calls, findings };
109+
}
110+
111+
/** The verdict over a set of `{ path, text }` files against `allowed`. */
112+
export function check(files, allowed = ALLOWED_CALLERS) {
113+
const problems = [];
114+
if (files.length === 0) {
115+
problems.push('the scan found no source files at all — an empty scan proves nothing, so it is refused');
116+
return { problems, counts: new Map() };
117+
}
118+
const counts = new Map();
119+
for (const { path, text } of files) {
120+
if (!SOURCE_FILE.test(path) || TEST_FILE.test(path)) continue;
121+
const { calls, findings } = censusOf(path, text);
122+
problems.push(...findings);
123+
if (calls > 0) counts.set(path, calls);
124+
}
125+
for (const [path, calls] of counts) {
126+
const row = allowed[path];
127+
if (!row) {
128+
problems.push(
129+
`${path}: sets the vouched-reference mark ${calls} time(s) and is not in ALLOWED_CALLERS. A vouch lets one ` +
130+
"reference skip the caller's read door; add the row with its reason only after review, or write as the caller.",
131+
);
132+
} else if (row.count !== calls) {
133+
problems.push(
134+
`${path}: sets the vouched-reference mark ${calls} time(s); its ALLOWED_CALLERS row pins ${row.count}. ` +
135+
'Every call site is reviewed on its own: update the row (and its reason) in the same change.',
136+
);
137+
}
138+
}
139+
for (const path of Object.keys(allowed)) {
140+
if (!counts.has(path)) {
141+
problems.push(`${path}: is in ALLOWED_CALLERS and no longer sets the mark — remove the stale row.`);
142+
}
143+
}
144+
return { problems, counts };
145+
}
146+
147+
/** The files the census reads: what git sees under `packages/`, never build output. */
148+
function readTree() {
149+
const out = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', 'packages'], {
150+
cwd: REPO,
151+
encoding: 'utf8',
152+
maxBuffer: 256 * 1024 * 1024,
153+
});
154+
const files = [];
155+
for (const path of out.split('\0')) {
156+
if (!path || !SOURCE_FILE.test(path) || TEST_FILE.test(path)) continue;
157+
let text;
158+
try {
159+
text = readFileSync(join(REPO, path), 'utf8');
160+
} catch {
161+
continue; // listed by git, deleted in the working tree
162+
}
163+
if (!text.includes('vouchForReference') && !text.includes('VOUCHED_REFERENCES') && !text.includes('vouchedReferences')) {
164+
text = '';
165+
}
166+
files.push({ path, text });
167+
}
168+
return files;
169+
}
170+
171+
// ── Self-test ──────────────────────────────────────────────────────────────
172+
//
173+
// Table-driven, as `check-agent-model-declared.mjs`'s: each row LABEL is a
174+
// declared battery with a floor of 1, registered as the first statement of the
175+
// loop body; the roster's own size is pinned; and the verdict sets a flag the
176+
// dispatch refuses without (AGENTS.md, "Writing a --self-test").
177+
178+
let selfTestReachedVerdict = false;
179+
180+
const SELF_TEST_BATTERIES = Object.freeze({
181+
'an allow-listed file with exactly its pinned call sites → GREEN': 1,
182+
'a call from a file outside the allow-list → RED': 1,
183+
'an allow-listed file with one more call site than its row → RED': 1,
184+
'an allow-listed file with one fewer call site than its row → RED': 1,
185+
'a row naming a file that no longer sets the mark → RED (stale row)': 1,
186+
'an import that renames vouchForReference → RED': 1,
187+
'the key built by hand as [VOUCHED_REFERENCES] → RED': 1,
188+
"the symbol spelled by hand with Symbol.for → RED": 1,
189+
'a test file that sets the mark → GREEN (outside the census)': 1,
190+
'a comment or backtick mention is no call site → GREEN': 1,
191+
'the defining module’s own spellings → GREEN': 1,
192+
'an empty scan → RED, never a green skip': 1,
193+
});
194+
const SELF_TEST_BATTERY_FLOOR = 12;
195+
196+
function selfTest() {
197+
const VERB = 'packages/services/demo/src/verb.ts';
198+
const OTHER = 'packages/rest/src/door.ts';
199+
const ALLOW = { [VERB]: { count: 1, reason: 'demo' } };
200+
const call = " const ctx = vouchForReference(context, { object: 'o', field: 'f', id });\n";
201+
const filler = { path: 'packages/core/src/other.ts', text: 'export const x = 1;\n' };
202+
203+
const cases = [
204+
{ label: 'an allow-listed file with exactly its pinned call sites → GREEN', files: [{ path: VERB, text: call }], expect: 'green' },
205+
{ label: 'a call from a file outside the allow-list → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: call }], expect: 'red', names: OTHER },
206+
{ label: 'an allow-listed file with one more call site than its row → RED', files: [{ path: VERB, text: call + call }], expect: 'red', names: VERB },
207+
{ label: 'an allow-listed file with one fewer call site than its row → RED', files: [{ path: VERB, text: call }], allow: { [VERB]: { count: 2, reason: 'demo' } }, expect: 'red', names: VERB },
208+
{ label: 'a row naming a file that no longer sets the mark → RED (stale row)', files: [filler], expect: 'red', names: VERB },
209+
{ label: 'an import that renames vouchForReference → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: "import { vouchForReference as vouch } from '@objectstack/core';\n" }], expect: 'red', names: OTHER },
210+
{ label: 'the key built by hand as [VOUCHED_REFERENCES] → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: ' const ctx = { ...context, [VOUCHED_REFERENCES]: [ref] };\n' }], expect: 'red', names: OTHER },
211+
{ label: "the symbol spelled by hand with Symbol.for → RED", files: [{ path: VERB, text: call }, { path: OTHER, text: " const k = Symbol.for('objectstack.core.vouchedReferences');\n" }], expect: 'red', names: OTHER },
212+
{ label: 'a test file that sets the mark → GREEN (outside the census)', files: [{ path: VERB, text: call }, { path: 'packages/rest/src/door.test.ts', text: call + ' ({ [VOUCHED_REFERENCES]: [] });\n' }], expect: 'green' },
213+
{ label: 'a comment or backtick mention is no call site → GREEN', files: [{ path: VERB, text: call }, { path: OTHER, text: '// vouchForReference(context, ref) is the verb\'s\n * see vouchForReference( here\nconst s = `vouchForReference(x)`;\n' }], expect: 'green' },
214+
{ label: 'the defining module’s own spellings → GREEN', files: [{ path: VERB, text: call }, { path: DEFINING_MODULE, text: "export const VOUCHED_REFERENCES = Symbol.for('objectstack.core.vouchedReferences');\nexport function vouchForReference(context, reference) {\n return { ...context, [VOUCHED_REFERENCES]: [] };\n}\n" }], expect: 'green' },
215+
{ label: 'an empty scan → RED, never a green skip', files: [], expect: 'red', names: 'no source files' },
216+
];
217+
218+
const batterySeen = new Map();
219+
let failed = 0;
220+
for (const c of cases) {
221+
batterySeen.set(c.label, (batterySeen.get(c.label) ?? 0) + 1);
222+
const { problems } = check(c.files, c.allow ?? ALLOW);
223+
const red = problems.length > 0;
224+
const ok =
225+
(c.expect === 'green' && !red) ||
226+
(c.expect === 'red' && red && (!c.names || problems.some((p) => p.includes(c.names))));
227+
if (!ok) {
228+
failed += 1;
229+
console.error(`✗ ${c.label}\n expected ${c.expect}${c.names ? ` naming ${c.names}` : ''}, got: ${red ? problems.join(' | ') : 'green'}`);
230+
}
231+
}
232+
233+
const declared = Object.keys(SELF_TEST_BATTERIES);
234+
const floorFailure = (message) => {
235+
console.error(`✗ self-test floor: ${message}`);
236+
failed += 1;
237+
};
238+
if (declared.length < SELF_TEST_BATTERY_FLOOR) {
239+
floorFailure(`SELF_TEST_BATTERIES declares ${declared.length} batteries, below the pinned ${SELF_TEST_BATTERY_FLOOR}.`);
240+
}
241+
const labels = cases.map((c) => c.label);
242+
const duplicated = [...new Set(labels.filter((l, i) => labels.indexOf(l) !== i))];
243+
if (duplicated.length > 0) floorFailure(`row label(s) used more than once: ${duplicated.join(', ')}`);
244+
for (const [name] of batterySeen) {
245+
if (!declared.includes(name)) floorFailure(`battery "${name}" ran but is not declared in SELF_TEST_BATTERIES.`);
246+
}
247+
for (const name of declared) {
248+
const seen = batterySeen.get(name) ?? 0;
249+
if (seen < SELF_TEST_BATTERIES[name]) {
250+
floorFailure(`battery "${name}" DID NOT RUN — ${seen} case(s) registered, ${SELF_TEST_BATTERIES[name]} pinned.`);
251+
}
252+
}
253+
254+
if (failed > 0) {
255+
console.error(`\n✗ check-vouch-for-reference-callers self-test: ${failed} failure(s) (cases and floor).`);
256+
process.exit(1);
257+
}
258+
console.log(`✓ check-vouch-for-reference-callers self-test: ${cases.length} cases pass.`);
259+
selfTestReachedVerdict = true;
260+
}
261+
262+
function main() {
263+
if (process.argv.includes('--self-test')) {
264+
selfTest();
265+
if (!selfTestReachedVerdict) {
266+
console.error(
267+
'✗ check-vouch-for-reference-callers self-test: selfTest() returned without reaching its verdict, so no ' +
268+
'success line was printed; exiting 0 would report a self-test that never finished as one that passed.',
269+
);
270+
process.exit(1);
271+
}
272+
return;
273+
}
274+
const { problems, counts } = check(readTree());
275+
if (problems.length > 0) {
276+
console.error(`✗ check-vouch-for-reference-callers: ${problems.length} finding(s)\n`);
277+
for (const p of problems) console.error(` - ${p}`);
278+
process.exit(1);
279+
}
280+
const listed = [...counts].map(([path, n]) => `${path} (${n})`).join(', ');
281+
console.log(`✓ check-vouch-for-reference-callers: every call site that sets the vouched-reference mark is allow-listed — ${listed}.`);
282+
}
283+
284+
if (isEntrypoint(import.meta.url)) {
285+
main();
286+
}

0 commit comments

Comments
 (0)