@runeditrun/rer 0.2.110 → 0.2.111

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +24 -0
  2. package/cli/agent-door.mjs +12 -45
  3. package/cli/agent-history-database.mjs +13 -6
  4. package/cli/bounded.mjs +3 -3
  5. package/cli/contract.mjs +5 -1
  6. package/cli/deploy-command.mjs +2 -2
  7. package/cli/hosted-output.mjs +30 -10
  8. package/cli/hosted-owner.mjs +85 -0
  9. package/cli/inspect.mjs +6 -2
  10. package/cli/lifecycle.mjs +3 -1
  11. package/cli/main.mjs +13 -0
  12. package/cli/parse.mjs +4 -4
  13. package/cli/size/build-facts.mjs +58 -0
  14. package/cli/size/build-paths.mjs +3 -0
  15. package/cli/size/check.mjs +16 -0
  16. package/cli/size/clauses.mjs +21 -0
  17. package/cli/size/clock.mjs +21 -0
  18. package/cli/size/command.mjs +64 -0
  19. package/cli/size/declaration.mjs +87 -0
  20. package/cli/size/dml-parts.mjs +108 -0
  21. package/cli/size/examples/happytohelp.json +68 -0
  22. package/cli/size/expression-depth.mjs +45 -0
  23. package/cli/size/expression.mjs +33 -0
  24. package/cli/size/fixture.mjs +139 -0
  25. package/cli/size/flows.mjs +81 -0
  26. package/cli/size/from-items.mjs +124 -0
  27. package/cli/size/grow.mjs +83 -0
  28. package/cli/size/install.mjs +136 -0
  29. package/cli/size/json-duplicates.mjs +45 -0
  30. package/cli/size/limits.mjs +9 -0
  31. package/cli/size/measure.mjs +9 -0
  32. package/cli/size/meter.mjs +167 -0
  33. package/cli/size/personas.mjs +138 -0
  34. package/cli/size/report.mjs +23 -0
  35. package/cli/size/schema-objects.mjs +80 -0
  36. package/cli/size/schema.mjs +56 -0
  37. package/cli/size/statements.mjs +53 -0
  38. package/cli/size/validate-flows.mjs +109 -0
  39. package/cli/size/validate-kit.mjs +44 -0
  40. package/cli/size/validate-shape.mjs +75 -0
  41. package/cli/size/verdict.mjs +131 -0
  42. package/cli/size/verify-step.mjs +35 -0
  43. package/global/CHANGELOG.md +31 -0
  44. package/global/README.md +24 -0
  45. package/modules/agent-door/conformance/audit.mjs +3 -0
  46. package/modules/d1-transport/limits.mjs +5 -1
  47. package/modules/deploy-kit/sql-tokens.mjs +5 -4
  48. package/modules/operator-auth/accounts/one-click.mjs +2 -0
  49. package/modules/operator-auth/dev/index.mjs +7 -1
  50. package/modules/operator-auth/dev/invited.mjs +11 -0
  51. package/modules/operator-auth/dev-gate.mjs +3 -2
  52. package/modules/operator-auth/routes.mjs +4 -0
  53. package/modules/release/README.md +8 -0
  54. package/modules/release/archive-guard.mjs +22 -0
  55. package/modules/release/archive-members.mjs +49 -0
  56. package/modules/release/export.mjs +7 -1
  57. package/package.json +2 -1
@@ -0,0 +1,44 @@
1
+ // Small pieces shared by the size-check.json validators: a problem list keyed by field path, key and number checks,
2
+ // and the {{var}} / {{persona.var}} template scan.
3
+ export const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
4
+ export const isInt = (value, low, high = Infinity) => Number.isInteger(value) && value >= low && value <= high;
5
+ export const count = number => number.toLocaleString('en-US');
6
+ export const identifier = /^[A-Za-z_][A-Za-z0-9_]*$/, slug = /^[a-z0-9][a-z0-9-]{0,63}$/, name = /^[a-z][a-z0-9_]{0,31}$/, variable = /^[A-Za-z_][A-Za-z0-9_]{0,31}$/;
7
+ export const methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
8
+
9
+ // Every problem is { path, message }: the path is the dotted field path the clause id carries.
10
+ export function problems() {
11
+ const list = [];
12
+ return { list, add: (path, message) => { list.push({ path: path.join('.'), message }); } };
13
+ }
14
+
15
+ // The value as an object with only the allowed keys; unknown keys are refused by name.
16
+ export function keyed(found, value, path, allowed, label = 'it') {
17
+ if (!isObject(value)) { found.add(path, `must be an object; write { ${allowed.slice(0, 3).join(', ')}, … } (allowed keys: ${allowed.join(', ')}).`); return false; }
18
+ for (const key of Object.keys(value)) if (!allowed.includes(key)) found.add([...path, key], `unknown key "${key}"; remove it or correct the spelling (allowed in ${label}: ${allowed.join(', ')}).`);
19
+ return true;
20
+ }
21
+
22
+ export function integer(found, value, path, low, high, fix) {
23
+ if (isInt(value, low, high)) return true;
24
+ found.add(path, `must be a whole number ${high === undefined || high === Infinity ? `of at least ${count(low)}` : `from ${count(low)} to ${count(high)}`}${fix ? `; ${fix}` : ''}.`);
25
+ return false;
26
+ }
27
+
28
+ export function* stringsIn(value) {
29
+ if (typeof value === 'string') yield value;
30
+ else if (Array.isArray(value)) for (const item of value) yield* stringsIn(item);
31
+ else if (isObject(value)) for (const item of Object.values(value)) yield* stringsIn(item);
32
+ }
33
+
34
+ // Each {{…}} in the text as { persona?, variable } or { bad } when it is neither {{var}} nor {{persona.var}}.
35
+ export function templateRefs(text) {
36
+ return [...text.matchAll(/\{\{([^{}]*)\}\}/g)].map(match => {
37
+ const parts = match[1].trim().split('.');
38
+ if (parts.length === 1 && variable.test(parts[0])) return { variable: parts[0] };
39
+ if (parts.length === 2 && name.test(parts[0]) && variable.test(parts[1])) return { persona: parts[0], variable: parts[1] };
40
+ return { bad: match[0] };
41
+ });
42
+ }
43
+
44
+ export const pathProblem = path => typeof path !== 'string' || !path || path.startsWith('/') || path.includes('\\') || path.includes('\0') || path.split('/').includes('..');
@@ -0,0 +1,75 @@
1
+ import { expressionProblem } from './expression.mjs';
2
+ import { count, identifier, integer, isInt, isObject, keyed } from './validate-kit.mjs';
3
+
4
+ const maxRows = 5_000_000;
5
+
6
+ function rowCounts(found, rows, path) {
7
+ if (isInt(rows, 1, maxRows)) return { small: rows, large: rows };
8
+ if (isObject(rows) && keyed(found, rows, path, ['small', 'large'], 'rows')) {
9
+ const small = integer(found, rows.small, [...path, 'small'], 1, maxRows), large = integer(found, rows.large, [...path, 'large'], 1, maxRows);
10
+ return small && large ? { small: rows.small, large: rows.large } : undefined;
11
+ }
12
+ if (!isObject(rows)) found.add(path, `must be a whole number from 1 to ${count(maxRows)}, or { "small": N, "large": N }.`);
13
+ }
14
+
15
+ function histogram(found, spec, path, rows) {
16
+ if (!isObject(spec) || !Object.keys(spec).length) { found.add(path, 'must map children per parent to the number of parents, for example { "3": 10, "1": 40 }.'); return; }
17
+ let total = 0;
18
+ for (const [children, parents] of Object.entries(spec)) {
19
+ if (!/^[1-9][0-9]*$/.test(children) || !isInt(parents, 1)) { found.add(path, `entry "${children}": ${JSON.stringify(parents)} must be children per parent (a whole number of at least 1) mapped to a parent count of at least 1.`); return; }
20
+ total += Number(children) * parents;
21
+ }
22
+ const wanted = rows ? [...new Set([rows.small, rows.large])] : [];
23
+ if (wanted.some(number => number !== total)) found.add(path, `children x parents sums to ${count(total)} but rows is ${wanted.map(count).join(' and ')}; make the histogram sum equal rows, or change rows.`);
24
+ return total;
25
+ }
26
+
27
+ function parentOf(found, parent, path, earlier, rows) {
28
+ const spec = isObject(parent) && 'histogram' in parent ? ['table', 'histogram'] : ['table', 'per'];
29
+ if (!keyed(found, parent, path, spec, 'parent')) return;
30
+ if (typeof parent.table !== 'string' || !identifier.test(parent.table)) found.add([...path, 'table'], 'must name the parent table.');
31
+ else if (!earlier.includes(parent.table)) found.add([...path, 'table'], `${parent.table} must be listed earlier in shape.tables than the table that belongs to it; move ${parent.table} up, or correct the name.`);
32
+ if ('histogram' in parent) histogram(found, parent.histogram, [...path, 'histogram'], rows);
33
+ else integer(found, parent.per, [...path, 'per'], 1, undefined, 'per is the number of children each parent row gets');
34
+ }
35
+
36
+ function sql(found, value, path) {
37
+ const problem = expressionProblem(value);
38
+ if (problem) found.add(path, `${problem}.`);
39
+ }
40
+
41
+ function values(found, spec, path) {
42
+ if (!isObject(spec) || !Object.keys(spec).length) { found.add(path, 'must map each column to a SQLite expression, for example { "id": "printf(\'c%06d\', n)" }.'); return; }
43
+ for (const [column, expression] of Object.entries(spec)) {
44
+ if (!identifier.test(column)) { found.add([...path, column], 'is not a column name (letters, digits and underscore).'); continue; }
45
+ if (isObject(expression)) {
46
+ if (!keyed(found, expression, [...path, column], ['jsonArray'], 'a column value')) continue;
47
+ if (keyed(found, expression.jsonArray, [...path, column, 'jsonArray'], ['length', 'item'], 'jsonArray')) {
48
+ sql(found, expression.jsonArray.length, [...path, column, 'jsonArray', 'length']);
49
+ sql(found, expression.jsonArray.item, [...path, column, 'jsonArray', 'item']);
50
+ }
51
+ } else sql(found, expression, [...path, column]);
52
+ }
53
+ }
54
+
55
+ // shape: { tables, after }. Returns the normalized shape, or undefined when it has problems.
56
+ export function validateShape(found, shape, path) {
57
+ if (!keyed(found, shape, path, ['tables', 'after'], 'shape')) return;
58
+ const tables = shape.tables, after = shape.after ?? [], normalized = { tables: [], after: [] }, before = found.list.length;
59
+ if (!Array.isArray(tables) || tables.length < 1 || tables.length > 64) found.add([...path, 'tables'], 'must list 1 to 64 tables, each with its rows and column values.');
60
+ else tables.forEach((table, index) => {
61
+ const here = [...path, 'tables', typeof table?.table === 'string' && identifier.test(table.table) ? table.table : index];
62
+ if (!keyed(found, table, here, ['table', 'rows', 'chunk', 'parent', 'values'], 'a table')) return;
63
+ if (typeof table.table !== 'string' || !identifier.test(table.table)) found.add([...here, 'table'], 'must be the table name (letters, digits and underscore).');
64
+ const rows = table.rows === undefined ? (found.add([...here, 'rows'], 'is required; give the row count or { "small": N, "large": N }.'), undefined) : rowCounts(found, table.rows, [...here, 'rows']);
65
+ if (table.chunk !== undefined) integer(found, table.chunk, [...here, 'chunk'], 100, 50_000);
66
+ if (table.parent !== undefined) parentOf(found, table.parent, [...here, 'parent'], tables.slice(0, index).map(earlier => earlier?.table), rows);
67
+ if (table.values === undefined) found.add([...here, 'values'], 'is required; map each column to a SQLite expression.');
68
+ else values(found, table.values, [...here, 'values']);
69
+ normalized.tables.push({ ...table, rows: rows ?? table.rows, chunk: table.chunk ?? 10_000 });
70
+ });
71
+ if (!Array.isArray(after) || after.length > 16) found.add([...path, 'after'], 'must list at most 16 single statements.');
72
+ else after.forEach((statement, index) => sql(found, statement, [...path, 'after', index]));
73
+ normalized.after = after;
74
+ return found.list.length === before ? normalized : undefined;
75
+ }
@@ -0,0 +1,131 @@
1
+ import { d1Limits, failAt, SIZE_MARGIN } from './limits.mjs';
2
+ import { measureStatements } from './statements.mjs';
3
+
4
+ // What the metered flows add up to. A flow fails when, at either size or between them:
5
+ // ceiling it read more rows at large than its ceiling;
6
+ // growth it read more at large than at small by over growthPercent of small plus growthRows
7
+ // (unless growth.allowed, whose why is printed on every run);
8
+ // status it answered another status than declared (any 2xx or 3xx, and 101 for a websocket);
9
+ // refused local D1 refused or failed a statement it ran;
10
+ // statement-size a distinct statement it ran is at 90 or more FROM items or depth.
11
+
12
+ const count = number => number.toLocaleString('en-US');
13
+ const preview = sql => sql.replace(/\s+/g, ' ').trim().slice(0, 160);
14
+ const sizes = ['small', 'large'];
15
+
16
+ /** The statements of `executions` that read the most rows, summed by text: [{ binding, sql, executions, rowsRead, rowsWritten }]. */
17
+ export function topStatements(executions, limit = 3) {
18
+ const groups = new Map();
19
+ for (const { binding, sql, rows_read, rows_written } of executions) {
20
+ const key = `${binding}\0${sql}`, group = groups.get(key) ?? { binding, sql, executions: 0, rowsRead: 0, rowsWritten: 0 };
21
+ group.executions++;
22
+ group.rowsRead += rows_read;
23
+ group.rowsWritten += rows_written;
24
+ groups.set(key, group);
25
+ }
26
+ return [...groups.values()].sort((a, b) => b.rowsRead - a.rowsRead).slice(0, limit);
27
+ }
28
+
29
+ // Every distinct statement text the flows ran (exec text can hold several statements and has no row meta, so it is
30
+ // not measured), measured against the schema of its own D1 binding: Map(binding -> Map(sql -> record)).
31
+ function measureDistinct(schemas, flowResults) {
32
+ const texts = new Map();
33
+ for (const result of flowResults) for (const { binding, sql, exec } of result.executions) if (!exec) texts.set(binding, (texts.get(binding) ?? new Set()).add(sql));
34
+ const measured = new Map();
35
+ for (const [binding, sqls] of texts) {
36
+ const schema = schemas.find(item => item.binding === binding);
37
+ if (!schema) continue;
38
+ const list = [...sqls], records = measureStatements(schema.db, list.map((sql, index) => ({ name: `statement ${index}`, sql })));
39
+ measured.set(binding, new Map(list.map((sql, index) => [sql, records[index]])));
40
+ }
41
+ return measured;
42
+ }
43
+
44
+ const summary = run => ({ rowsRead: run.rowsRead, rowsWritten: run.rowsWritten, statements: run.statements, status: run.status, ms: Math.round(run.ms), ...(run.error ? { error: run.error } : {}), ...(run.detail ? { detail: run.detail } : {}), ...(run.unsettled ? { unsettled: true } : {}), top: topStatements(run.executions) });
45
+
46
+ // Only the measures at the failing line: a statement at depth 105 says so and not "0 FROM items".
47
+ function sizeText({ fromItems, depth }) {
48
+ const parts = [];
49
+ if (fromItems >= failAt.fromItems) parts.push(`${fromItems} FROM items after expanding CTEs and views`);
50
+ if ((depth ?? Infinity) >= failAt.depth) parts.push(`expression depth ${depth ?? 'over the limit'}`);
51
+ return `${parts.join(', ')} (rer fails at ${failAt.fromItems} FROM items or depth ${failAt.depth}; D1 refuses at ${d1Limits.fromItems} and ${d1Limits.depth})`;
52
+ }
53
+
54
+ function statusProblem(flow, run) {
55
+ const expected = flow.status ?? (flow.scheduled === undefined ? flow.request.websocket ? [101] : null : ['ok']);
56
+ const wanted = expected === null ? 'a 2xx or 3xx status' : `status ${expected.join(' or ')}`;
57
+ if (run.error) return `${flow.scheduled === undefined ? 'its request' : 'the scheduled handler'} failed: ${run.error}`;
58
+ const ok = expected === null ? run.status >= 200 && run.status < 400 : expected.includes(run.status);
59
+ if (ok) return null;
60
+ return flow.scheduled === undefined ? `answered HTTP ${run.status}${run.detail ? ` (${run.detail})` : ''}; expected ${wanted}` : `the scheduled handler did not finish (${run.status}); expected it to run to the end`;
61
+ }
62
+
63
+ /**
64
+ * Judges every declared flow. `small` and `large` are the runFlows results of each size, in declared order;
65
+ * `schemas` are the build's D1 schemas ({ binding, db }, see schemasFromBuild) the statements are measured against.
66
+ * Resolves { ok, flows: [{ name, persona, kind, label, ok, failures: [{ rule, message }], growthAllowed, small, large }], checked }.
67
+ */
68
+ export function judgeFlows(declaration, small, large, schemas) {
69
+ const { growthPercent, growthRows } = declaration.budget;
70
+ const measured = measureDistinct(schemas, [...small, ...large]);
71
+ const verdicts = declaration.flows.map((flow, index) => {
72
+ const at = { small: small[index], large: large[index] }, failures = [];
73
+ const wrong = new Map();
74
+ for (const size of sizes) { const problem = statusProblem(flow, at[size]); if (problem) wrong.set(problem, [...wrong.get(problem) ?? [], size]); }
75
+ for (const [problem, where] of wrong) failures.push({ rule: 'status', message: `${problem} at ${where.join(' and ')}` });
76
+ const refused = new Map();
77
+ for (const size of sizes) for (const { sql, error } of at[size].executions) if (error) {
78
+ const key = `${sql}\0${error}`;
79
+ refused.set(key, { sql, error, sizes: [...refused.get(key)?.sizes ?? [], size] });
80
+ }
81
+ for (const { sql, error, sizes: where } of refused.values()) failures.push({ rule: 'refused', message: `local D1 refused or failed a statement at ${where.join(' and ')}: ${error.replace(/^D1_ERROR:\s*/, '').replace(/:\s*SQLITE_\w+(?: \(extended: \w+\))?\s*$/, '')}`, sql });
82
+ const rows = { small: at.small.rowsRead, large: at.large.rowsRead };
83
+ if (rows.large > flow.ceiling) failures.push({ rule: 'ceiling', message: `over its ceiling of ${count(flow.ceiling)} at large by ${count(rows.large - flow.ceiling)}${flow.callsInRow > 1 ? ` (${flow.callsInRow} calls in a row)` : ''}` });
84
+ const allowed = Math.floor(growthPercent / 100 * rows.small + growthRows);
85
+ if (rows.large - rows.small > growthPercent / 100 * rows.small + growthRows && !flow.growth) failures.push({ rule: 'growth', message: `grew ${count(rows.large - rows.small)} rows from small to large; allowed ${growthPercent}% of small + ${count(growthRows)} = ${count(allowed)}` });
86
+ const seen = new Set();
87
+ for (const size of sizes) for (const { binding, sql, exec } of at[size].executions) {
88
+ if (exec || seen.has(`${binding}\0${sql}`)) continue;
89
+ seen.add(`${binding}\0${sql}`);
90
+ const record = measured.get(binding)?.get(sql);
91
+ if (!record || record.ok) continue;
92
+ failures.push({ rule: 'statement-size', message: `statement size: ${record.error ?? sizeText(record)}`, sql, ...(record.error ? {} : { fromItems: record.fromItems, depth: record.depth }) });
93
+ }
94
+ return { name: flow.name, persona: flow.persona ?? null, kind: at.small.kind, label: at.small.label, callsInRow: flow.callsInRow, ceiling: flow.ceiling, ok: failures.length === 0, failures, growthAllowed: flow.growth?.why ?? null, small: summary(at.small), large: summary(at.large) };
95
+ });
96
+ const checked = [...measured.values()].reduce((all, records) => all + records.size, 0);
97
+ return { ok: verdicts.every(verdict => verdict.ok), flows: verdicts, checked };
98
+ }
99
+
100
+ /** The lines a person reads: one per flow, each failure's reasons and its three heaviest statements at large, then
101
+ * a summary. */
102
+ export function verdictLines(verdict, declaration) {
103
+ const lines = [], widths = { name: 0, persona: 0, label: 0 };
104
+ for (const flow of verdict.flows) for (const key of Object.keys(widths)) widths[key] = Math.max(widths[key], String(flow[key] ?? '').length);
105
+ for (const flow of verdict.flows) {
106
+ const status = flow.large.status ?? 'no response', extra = flow.large.unsettled ? '; work still running after 30 s is not counted' : '';
107
+ lines.push(` ${flow.ok ? 'ok ' : 'FAIL'} ${flow.name.padEnd(widths.name)} ${String(flow.persona ?? '').padEnd(widths.persona)} ${flow.label.padEnd(widths.label)} ${count(flow.small.rowsRead)} → ${count(flow.large.rowsRead)} rows, ${count(flow.large.statements)} statement${flow.large.statements === 1 ? '' : 's'}, ${status}${extra}`);
108
+ if (flow.growthAllowed) lines.push(` growth allowed: ${flow.growthAllowed}`);
109
+ if (flow.ok) continue;
110
+ for (const failure of flow.failures) {
111
+ lines.push(` ${failure.message}`);
112
+ if (failure.sql) lines.push(` ${preview(failure.sql)}`);
113
+ }
114
+ for (const top of flow.large.top.filter(top => top.rowsRead > 0)) lines.push(` ${count(top.rowsRead)} rows x${count(top.executions)} ${preview(top.sql)}`);
115
+ }
116
+ const failing = verdict.flows.filter(flow => !flow.ok).length;
117
+ lines.push(` ${failing ? `${failing} of ${verdict.flows.length} flows fail` : `All ${verdict.flows.length} flows pass`}; ${count(verdict.checked)} distinct statements checked for size. Rows are local D1's own count.`);
118
+ if (failing) lines.push(` Real D1 also refuses at ${d1Limits.fromItems} FROM items (rer fails at ${failAt.fromItems}, a margin of ${SIZE_MARGIN}) and budgets a database's reads in a 10-second window (here ceiling x calls in a row must stay under ${count(declaration.budget.windowRows)}). Confirm a fix on real D1 before relying on it.`);
119
+ return lines;
120
+ }
121
+
122
+ /** One size's statements in the fleet runner's format: { statements: [{ name: "<flow> #<i>", sql, params }] }, every
123
+ * statement each flow's last run executed, in order, with its parameters as bound. */
124
+ export function statementsFile(size, results) {
125
+ const statements = [];
126
+ for (const result of results) {
127
+ let index = 0;
128
+ for (const { sql, params, exec } of result.executions) if (!exec) statements.push({ name: `${result.name} #${++index}`, sql, params });
129
+ }
130
+ return { about: `rer size: every statement each flow ran at the ${size} size, in order, with its parameters as bound.`, statements };
131
+ }
@@ -0,0 +1,35 @@
1
+ import '../sqlite-notice.mjs';
2
+ import { realpath } from 'node:fs/promises';
3
+ import { resolve } from 'node:path';
4
+ import { RerError } from '../errors.mjs';
5
+ import { measureSize } from './command.mjs';
6
+
7
+ const join = names => names.join(', ');
8
+
9
+ // What failed, by name, for the error that fails verify. The lines that explain it were already reported as they ran.
10
+ function failureText({ statements, size = {}, flows = [] }) {
11
+ const parts = [];
12
+ const refused = statements.filter(statement => !statement.ok);
13
+ if (refused.length) parts.push(`D1 would refuse the build's schema objects ${join(refused.map(statement => statement.name))}`);
14
+ for (const name of ['small', 'large']) if (size[name]?.error) parts.push(`the ${name} size did not build: ${size[name].error}`);
15
+ const failing = flows.filter(flow => !flow.ok);
16
+ if (failing.length) parts.push(`${failing.length} of ${flows.length} declared flows fail: ${join(failing.map(flow => `${flow.name} (${[...new Set(flow.failures.map(failure => failure.rule))].join(', ')})`))}`);
17
+ return `Size check failed: ${parts.join('; ')}. Run rer size for the full report.`;
18
+ }
19
+
20
+ /**
21
+ * The last step of rer verify: `rer size`, in verify's own job-queue slot. Every view and trigger statement of each D1
22
+ * binding's migrations is measured; with a size-check.json at the checkout root the declared shape is also built at a
23
+ * small and a large size and every declared flow run on each. A failure fails verify, naming the statement or the flow.
24
+ * Resolves what `rer size --json` carries, so verify's result carries it as `size`.
25
+ */
26
+ export async function checkSizeStep(root, { report = () => {} } = {}) {
27
+ const { ok, details } = await measureSize({ cwd: root, json: false }, { human: report });
28
+ if (!ok) throw new RerError('size_check_failed', failureText(details), 1);
29
+ return details;
30
+ }
31
+
32
+ if (process.argv[1] && await realpath(new URL(import.meta.url)) === await realpath(process.argv[1])) {
33
+ try { console.log(JSON.stringify(await checkSizeStep(resolve(process.argv[2] ?? '.'), { report: line => console.error(line) }))); }
34
+ catch (error) { console.error(error.message); process.exitCode = 1; }
35
+ }
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.111
4
+
5
+ ### `rer size`: statement size and growth with data
6
+
7
+ - New `rer size`, and a last step of `rer verify`: statement size against D1's limits. D1 refuses a statement at 100 FROM items (counted with every CTE and view reference expanded in place) or expression depth 100, and local SQLite and Miniflare accept both; rer fails a statement at 90 of either. `rer size` checks the build's view and trigger statements, `--migrations DIR` another schema, and `--statements FILE` a statements file in the fleet runner's format. A seed gets it, and its `rer verify` gets the new last step, only after it adopts this rer (`rer size` runs through the seed's pinned rer); a seed whose views or triggers already sit at 90 FROM items or depth will see its verify fail at that step once it adopts.
8
+ - `rer check` validates a seed's optional `size-check.json` (its table shape, personas, flows and per-flow row ceilings) as `SC-15.size.*` clauses, offline, with no build: unknown keys, undeclared personas and crons, histogram sums, parent order, expressions with a `;`, `growth.allowed` without a `why`, and a ceiling times calls in a row over `budget.windowRows` each fail naming the field and the fix. With no file it passes `SC-15.size.undeclared`.
9
+ - `rer size` with a `size-check.json` (or `--declaration FILE`) builds the declared shape at a small and a large size, each in its own disposable local D1 install served as the hosted check serves the build: the owner is signed in with agent-door's bootstrap (that code moved unchanged into a shared file, `cli/hosted-owner.mjs`), each table is generated inside D1 by chunked `INSERT … SELECT` so the schema's own triggers fire, and each declared table is read back with the time per phase. A generation error names the size, table, row range, SQLite's message and column; `budget.timeoutSeconds` bounds the run and a timeout names the phase; it takes verify's job-queue slot. `@runeditrun/rer/size-fixture` exports the compiler so a fleet runner seeds the same statements.
10
+ - `rer size` then runs every declared flow at the small and the large size through a rows-read meter wrapped around the Worker's D1 bindings (fetch, scheduled, queue, Durable Objects and `waitUntil` work; queues are held and queue consumer work is not measured), as the owner, an anonymous visitor or a persona that signs in with a cookie jar and captured values, and fails a flow that passes its ceiling, reads more at large than at small by over 10 percent plus 200 rows, answers the wrong status, has a statement refused by local D1, or runs a statement at 90 FROM items or depth; `--write-statements DIR` writes the statements each size ran in the fleet runner's format. The meter is served only by `rer size`: nothing changes for the hosted check or agent-door conformance.
11
+ - `rer verify` now ends with the full size check: with a `size-check.json` the last step runs `rer size`'s code inside verify's own job-queue slot, builds the declared shape at a small and a large size, runs every declared flow and fails verify exactly when `rer size` fails, naming each failing flow (the result's `size` carries what `rer size --json` carries); without one it checks the schema objects and prints `Size check: undeclared (no size-check.json).` In a checkout without a seedContract, `rer size` runs from `size-check.json` `build.wrangler` and `build.deployDeclaration` (they now name the built wrangler file and the deploy declaration; the Worker, migrations and assets are read from the wrangler file's folder), allows the owner persona only where `rer-setup.json` has an owner-claim step or `agent-surface.json` has `verification.owner`, and never forwards to a declared argv.
12
+ - The growth check needs a declaration. A seed that declares no `size-check.json` is never asked to grow data: it sees `undeclared`. The HappyToHelp example in `cli/size/examples/happytohelp.json` is a snapshot of that seed's measured shape (11 Nov 2026) and must be refreshed against current measurements before any gate on it is turned on. Verification tooling only: no migration is added.
13
+
14
+ ### Local sign-in and one-click follow-ups
15
+
16
+ - A local run's `/__dev/key` guidance page now names `rer dev --as` followed by an invited person's email only when the app has someone beyond the owner and its dev personas (an active person or one with a live invitation) for it to take; the page still carries no key or address. Wording only; local runs only.
17
+ - A browser that follows a refused local one-click sign-in link (`Accept: text/html`) now reads a short plain-words line (open the link from the app, or run `rer dev --as` with the email) instead of `{"error":"not_found"}`; the status, headers and JSON for any other caller are unchanged. Local runs only.
18
+ - The default seed's operator access panel shows the "can sign in on this computer … `rer dev --as`" invitation text only when served from a local address; elsewhere an invitation that sent no email reads "Saved. No email was sent." Wording only.
19
+
20
+ ### Deploy message
21
+
22
+ - `rer deploy` with a hook that keeps a kit record now shows the cause, the step and the recovery sentence when its pre-hook settle is refused (for example `owner-state-locked` or `secret-change-unsettled`) instead of "Checking pinned pnpm failed"; the settle still stops the deploy before the hook, and the failure ends with exit code 1, the code the kit's other deploy failures already use.
23
+
24
+ ### Agent door: `policy.adopted` metadata
25
+
26
+ - The agent door's `policy.adopted` event now also carries `classes` (the classes the adopted policy has a rule for, as `{ class }` entries like `approval.pending`'s) and `decision` (`{ revision, document_sha256 }`, the adopted revision; digest `null` when no policy document is adopted), so `BASE-AGENT-010` acceptance 6 can be judged; the conformance audit checks the newest adoption for that shape. `seq`, `revision` and the event `uri` are unchanged, nothing else is added (no rule, reviewer, approver, threshold or spend value), and an older subscriber that ignores the new fields keeps working. Additive event fields; a seed's conformance audit checks the shape only after it adopts this release.
27
+
28
+ ### `rer release` archives
29
+
30
+ - `rer release` run on macOS no longer puts `._*` AppleDouble entries (one per file and directory, from extended attributes such as `com.apple.provenance`) into `public-source.tar`, and the release stops with a message if such an entry that is not a tracked path ever reaches the archive; a tracked file whose name starts with `._` is still archived. This changes only archives cut after a checkout adopts this release: no already published release archive is re-cut. No change to the statement or signing format, and archives built on Linux are unchanged.
31
+
32
+ All of the above is code and docs only: no migration is added. A seed gets it by adopting 0.2.111; nothing here is live in any deployed seed until that seed adopts and deploys it.
33
+
3
34
  ## 0.2.110
4
35
 
5
36
  ### Business roster: a teammate erased before adoption stays erased
package/global/README.md CHANGED
@@ -319,6 +319,7 @@ line that still names it. A later refresh is a version bump:
319
319
  | `@runeditrun/rer/jsonc` | JSONC reading | `scripts/base-cli/cli/jsonc.mjs` |
320
320
  | `@runeditrun/rer/parse`, `/scheduled` | CLI argument parsing, scheduled-job helpers | `scripts/base-cli/cli/parse.mjs`, `scheduled.mjs` |
321
321
  | `@runeditrun/rer/dev-identity` | dev identity helpers | `scripts/base-cli/cli/dev-identity.mjs` |
322
+ | `@runeditrun/rer/size-fixture` | `compileFixture(declaration, 'small' or 'large', { now, ownerEmail })`: a `size-check.json` shape as the ordered `[{name, sql, params}]` statements `rer size` runs on local D1 (the fleet runner's statements format), for seeding real D1 with the same rows | `scripts/base-cli/cli/size/fixture.mjs` |
322
323
  | `@runeditrun/rer/operator-installer` | `operatorInstaller`, `developmentTarget`, `previewTarget` | `scripts/base-onboarding/operator-installer.mjs` |
323
324
  | `@runeditrun/rer/local-installer` | `localInstaller` | `scripts/base-onboarding/adapter.mjs` |
324
325
  | `@runeditrun/rer/operator-install` | `installOperator` | `scripts/base-onboarding/operator-install.mjs` |
@@ -390,6 +391,29 @@ there lists its flags:
390
391
  `export`, `import`, `doctor`, `describe`, `check`, `release`,
391
392
  `release sign`, `release receipt` and `release keygen`.
392
393
 
394
+ `rer size` checks statement size against D1's limits: it fails a statement at 90
395
+ FROM items (counted with every CTE and view reference expanded) or expression
396
+ depth 90, where D1 refuses at 100 and local SQLite and Miniflare accept both.
397
+ With no flags it checks every view and trigger statement of the build's D1
398
+ migrations; `--migrations DIR` names a migrations directory instead, and
399
+ `--statements FILE` checks a statements file (`{"statements":[{"name","sql"}]}`)
400
+ against that schema. It runs in any checkout, needs no account, and exits 1 on
401
+ any failure, 0 otherwise and 3 with no build and no `--migrations`. `rer verify`
402
+ ends with the same check, inside its own job-queue slot, and fails exactly when
403
+ `rer size` would. With a `size-check.json` (or `--declaration FILE`, a
404
+ declaration kept outside the checkout) it also builds the declared shape at a
405
+ small and a large size on local D1, runs every declared flow on each through a
406
+ rows-read meter and fails a flow that passes its ceiling, reads more at large
407
+ than at small by over 10 percent plus 200 rows, answers the wrong status, has a
408
+ statement refused by local D1 or runs a statement at 90 FROM items or depth;
409
+ `--write-statements DIR` writes the statements each size ran in the fleet
410
+ runner's format. Without a `size-check.json`, verify's step checks the schema
411
+ objects and prints `Size check: undeclared (no size-check.json).` A checkout
412
+ without a seedContract runs it from the declaration's `build.wrangler` and
413
+ `build.deployDeclaration` and never forwards to a declared argv; its owner
414
+ persona needs an owner claim in `rer-setup.json` or `verification.owner` in
415
+ `agent-surface.json`.
416
+
393
417
  Anywhere: `rer list [DIR]`, `rer cli status|install|uninstall`, `rer update`,
394
418
  `rer queue NAME -- COMMAND`, `rer --version` and `rer --help`.
395
419
 
@@ -159,6 +159,9 @@ export async function auditPhase(c) {
159
159
  const applicable = type === 'policy.adopted' || rows.some(row => row.approval);
160
160
  if (applicable) c.add(`BASE-AGENT-010.6.${type}`, [...events, ...c.effectEvents ?? []].some(event => event.type === type), `Missing ${type} event while readable, including before native erasure.`);
161
161
  }
162
+ // The newest adoption carries the classes it covers and a decision reference to its revision, and nothing but policy metadata.
163
+ const adopted = [...events, ...c.effectEvents ?? []].filter(event => event.type === 'policy.adopted').at(-1);
164
+ if (adopted) c.add('BASE-AGENT-010.6.policy.adopted.shape', Array.isArray(adopted.classes) && adopted.classes.every(item => item?.class && Object.keys(item).join() === 'class') && adopted.decision?.revision === adopted.revision && Object.keys(adopted).every(key => ['id', 'type', 'uri', 'actor', 'at', 'seq', 'revision', 'classes', 'decision'].includes(key)), 'policy.adopted must carry the adopted classes as {class} entries and a decision reference to its revision, and nothing else.');
162
165
  const writeTools = new Set(rows.filter(row => row.tool !== 'resources/read' && ['done', 'replayed'].includes(row.outcome) && c.surface.tools.find(tool => tool.name === row.tool)?.readOnly === false).map(row => row.tool));
163
166
  c.add('BASE-AGENT-010.1.effects', !writeTools.size || [...events, ...c.effectEvents ?? []].some(event => event.actor?.kind === 'agent' && !['policy.decision', 'approval.pending', 'approval.decided'].includes(event.type)), 'Completed writes must produce record-change events attributed to the agent while their native resources are readable.');
164
167
  if (events.length > 1) {
@@ -1,10 +1,14 @@
1
1
  /** Cloudflare D1 per-query limits, supplied from the platform limits page
2
2
  * (updated 24 Oct 2026). Expression depth 100 is OBSERVED-NOT-DOCUMENTED:
3
3
  * native D1 rejected a concatenation tree of depth 101 on 27 Oct 2026.
4
+ * FROM items 100 is OBSERVED-NOT-DOCUMENTED (K21, 10 Nov 2026): native D1
5
+ * refuses a statement with "VIEWs and/or subqueries nested too deep" once its
6
+ * FROM-clause items, counted with every CTE and view reference expanded in
7
+ * place, reach 100. Local SQLite and Miniflare accept such a statement.
4
8
  * Node 22.20.0 ignores DatabaseSync limits options: preflight is mandatory.
5
9
  * Queries per Worker invocation (Paid 1000, Free 50, batch counts once) and
6
10
  * the 30 second query deadline are NOT-ENFORCEABLE-LOCALLY here: a database
7
11
  * connection has neither the invocation boundary nor the provider scheduler.
8
12
  */
9
13
  export const d1NativeLimits = Object.freeze({ length: 2_000_000, sqlLength: 100_000,
10
- column: 100, variableNumber: 100, functionArg: 32, likePatternLength: 50, exprDepth: 100 });
14
+ column: 100, variableNumber: 100, functionArg: 32, likePatternLength: 50, exprDepth: 100, fromItems: 100 });
@@ -2,6 +2,7 @@ import { assert } from './validation.mjs';
2
2
 
3
3
  // SQLite quotes escape themselves by doubling, except brackets, which end at ].
4
4
  // Keep quoted tokens intact: their punctuation and keywords are never syntax.
5
+ // Each token also carries its source span: sql.slice(start, end) is its text.
5
6
  export function sqlTokens(sql) {
6
7
  assert(!sql.includes('\0'), 'unsafe-migration-control');
7
8
  const tokens = [];
@@ -33,16 +34,16 @@ export function sqlTokens(sql) {
33
34
  break;
34
35
  }
35
36
  assert(closed, 'unsafe-migration-control');
36
- tokens.push({ kind: char === "'" ? 'string' : 'identifier', value });
37
+ tokens.push({ kind: char === "'" ? 'string' : 'identifier', value, start, end: offset });
37
38
  } else if (/[0-9]/.test(char) || (char === '.' && /[0-9]/.test(sql[offset] ?? ''))) {
38
39
  const number = /^(?:0[xX][0-9a-fA-F_]+|(?:[0-9][0-9_]*(?:\.[0-9_]*)?|\.[0-9][0-9_]*)(?:[eE][+-]?[0-9][0-9_]*)?)/.exec(sql.slice(start))[0];
39
40
  offset = start + number.length;
40
- tokens.push({ kind: 'number', value: number });
41
+ tokens.push({ kind: 'number', value: number, start, end: offset });
41
42
  } else if (/[A-Za-z_\u0080-\uFFFF]/.test(char)) {
42
43
  while (offset < sql.length && /[A-Za-z0-9_$\u0080-\uFFFF]/.test(sql[offset])) offset++;
43
- tokens.push({ kind: 'word', value: sql.slice(start, offset) });
44
+ tokens.push({ kind: 'word', value: sql.slice(start, offset), start, end: offset });
44
45
  } else {
45
- tokens.push({ kind: 'symbol', value: char });
46
+ tokens.push({ kind: 'symbol', value: char, start, end: offset });
46
47
  }
47
48
  }
48
49
  return tokens;
@@ -34,6 +34,8 @@ export function oneClickAccounts({ config, store, clock, sessions, authorizedLin
34
34
  return operator.status === 'active';
35
35
  }
36
36
  return {
37
+ // Only a local run's refusal can point at `rer dev`.
38
+ local: config.local === true,
37
39
  async people(request) {
38
40
  if (!await mode(request)) return null;
39
41
  requireOrigin(request, config);
@@ -18,6 +18,7 @@ import { signInRefusal } from './refusal.mjs';
18
18
  import { representation } from '../representation.mjs';
19
19
  import { decorateLabel } from '../../demo/label.mjs';
20
20
  import { oneClickPage } from '../signin/one-click.mjs';
21
+ import { hasInvitedPeople } from './invited.mjs';
21
22
 
22
23
  export const DEV_LAYER_MARKER = 'rer-dev-layer:local-only-never-deploy';
23
24
  const headers = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff', 'x-robots-tag': 'noindex, nofollow', 'x-rer-dev-layer': DEV_LAYER_MARKER };
@@ -51,7 +52,12 @@ export function withDevIdentity(worker, { bindings = env => env, config: authCon
51
52
  const gate = devGate({ key: env.RER_DEV_KEY, origin: env.AUTH_ORIGIN, local: env.AUTH_LOCAL === 'true' });
52
53
  registerDevAdmission(gate && env.RER_DEV_IDENTITY !== 'off' ? r => gate.admitsSession(r) : null);
53
54
  const path = new URL(request.url).pathname;
54
- if (path === '/__dev/key') return gate ? gate.exchange(request, authConfig(env).branding) : devNotFound();
55
+ if (path === '/__dev/key') {
56
+ if (!gate) return devNotFound();
57
+ // The guidance names `rer dev --as <email>` only when the app has someone to take.
58
+ const context = request.method === 'GET' || request.method === 'HEAD' ? identity(env, authConfig, declared) : null;
59
+ return gate.exchange(request, authConfig(env).branding, { invited: context ? await hasInvitedPeople({ store: context.store, config: context.config, declared }) : false });
60
+ }
55
61
  if (path === '/signin' && gate && env.RER_DEV_IDENTITY !== 'off' && ['GET', 'HEAD'].includes(request.method)) {
56
62
  if (!await gate.admits(request)) return new Response(null, { status: 303, headers: { ...headers, location: '/__dev/key' } });
57
63
  const context = identity(env, authConfig, declared);
@@ -0,0 +1,11 @@
1
+ // Whether /__dev/personas would list someone beyond the owner and the seed's own
2
+ // personas: an active person or one with a live invitation. The keyless guidance page
3
+ // uses this one fact to say whether `rer dev --as <email>` has anyone to take; it
4
+ // reads no name or address.
5
+ export async function hasInvitedPeople({ store, config, declared, now = Date.now() }) {
6
+ const own = [config.OWNER_EMAIL, ...declared.map(persona => persona.email)];
7
+ const row = await store.first(`SELECT 1 AS found FROM oa_operators o WHERE o.email NOT IN (${own.map(() => '?').join(',')})
8
+ AND (o.status='active' OR (o.status='invited' AND EXISTS (SELECT 1 FROM oa_tokens t WHERE t.operator_id=o.id AND t.kind='invite'
9
+ AND t.consumed_at IS NULL AND t.revoked_at IS NULL AND t.expires_at>? AND t.operator_version=o.version))) LIMIT 1`, [...own, now]);
10
+ return row !== null && row !== undefined;
11
+ }
@@ -94,7 +94,8 @@ export function devGate({ key, origin, local }) {
94
94
  admitsSession: admitted,
95
95
  setCookie,
96
96
  // GET serves the exchange page with the seed's productName, mark and theme; POST trades the key for the cookie.
97
- async exchange(request, branding) {
97
+ // `invited` says whether the app has a person beyond the owner and its personas for `rer dev --as <email>` to take.
98
+ async exchange(request, branding, { invited = false } = {}) {
98
99
  if (new URL(request.url).pathname !== DEV_KEY_PATH) return null;
99
100
  if (request.method === 'GET' || request.method === 'HEAD') {
100
101
  const { script, logo, style } = await exchangeHashes();
@@ -103,7 +104,7 @@ export function devGate({ key, origin, local }) {
103
104
  const theme = brand?.theme;
104
105
  const mark = brand?.mark ? `<img src="${escapeHtml(brand.mark)}" alt="${escapeHtml(brand.productName)}" width="40" height="40" decoding="async">` : '';
105
106
  const themeLogo = theme && !brand.mark;
106
- const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>Open the local app</title>${iconHead}${theme ? `<link rel="stylesheet" href="${escapeHtml(theme)}">` : ''}<style>${PAGE_STYLE}</style></head><body><main>${brand ? `<p class="brand">${mark}<span>${escapeHtml(brand.productName)}</span></p>` : ''}<h1>This app runs on your own computer</h1><p>It opens only from that computer. Use the link printed in the terminal where <code>rer dev</code> is running, or run <code>rer dev --as owner</code> from the project folder.</p><p>To sign in as someone who was invited, run <code>rer dev --as</code> followed by their email address.</p></main>${themeLogo ? `<script>${LOGO_SCRIPT}</script>` : ''}<script>${EXCHANGE_SCRIPT}</script></body></html>`;
107
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>Open the local app</title>${iconHead}${theme ? `<link rel="stylesheet" href="${escapeHtml(theme)}">` : ''}<style>${PAGE_STYLE}</style></head><body><main>${brand ? `<p class="brand">${mark}<span>${escapeHtml(brand.productName)}</span></p>` : ''}<h1>This app runs on your own computer</h1><p>It opens only from that computer. Use the link printed in the terminal where <code>rer dev</code> is running, or run <code>rer dev --as owner</code> from the project folder.</p>${invited ? '<p>To sign in as someone who was invited, run <code>rer dev --as</code> followed by their email address.</p>' : ''}</main>${themeLogo ? `<script>${LOGO_SCRIPT}</script>` : ''}<script>${EXCHANGE_SCRIPT}</script></body></html>`;
107
108
  return new Response(request.method === 'HEAD' ? null : body, { headers: { ...privateHeaders, 'content-type': 'text/html; charset=utf-8',
108
109
  'content-security-policy': `default-src 'none'; img-src 'self'; script-src ${script}${themeLogo ? ` ${logo}` : ''}; style-src ${theme ? "'self' " : ''}${style}${theme ? "; font-src 'self'" : ''}; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'` } });
109
110
  }
@@ -9,6 +9,7 @@ import { securityHeaders, requireLoopback } from './http.mjs';
9
9
  import { safeReturnTo } from './policy.mjs';
10
10
  import { readInput, readParameters } from './input.mjs';
11
11
  import { OWNER_SIGNIN_PATH } from './owner-signin-grant.mjs';
12
+ const ONE_CLICK_REFUSED = 'This sign-in link did not open here. Open the link from the app itself, or run rer dev --as followed by the email address from the project folder.';
12
13
  function json(value, status = 200) { return Response.json(value, { status, headers: securityHeaders() }); }
13
14
  function seeOther(location, cookie) { return new Response(null, { status: 303, headers: { ...securityHeaders(), ...(cookie ? { 'Set-Cookie': cookie } : {}), Location: location } }); }
14
15
  // A native HTML form (the sign-in page before any script) gets a page back; an
@@ -143,6 +144,9 @@ export function createAuthHandler(auth) {
143
144
  return settingsRefusalPage(request, auth.presentation, code, status);
144
145
  }
145
146
  if (form) return seeOther(notice(auth, error instanceof AuthError ? error.code : 'auth_unavailable'));
147
+ // A browser that follows a refused local one-click link gets words, with the same status and headers as the JSON.
148
+ if (path === '/auth/one-click' && auth.oneClick?.local && error instanceof AuthError && error.code === 'not_found' && representation(request) === 'html')
149
+ return new Response(ONE_CLICK_REFUSED, { status: error.status, headers: { ...securityHeaders(), 'Content-Type': 'text/plain; charset=utf-8' } });
146
150
  if (error instanceof AuthError) return json({ error: error.code }, error.status);
147
151
  // Do not put SQL, email addresses, setup tokens or provider exceptions on the wire.
148
152
  return json({ error: 'auth_unavailable' }, 503);
@@ -136,6 +136,14 @@ With `--tag`, passing gates produce `public-source.tar`, containing the checked
136
136
  exact ordinary files without Git history, and a hash-pinned site bundle:
137
137
  `site/<id>/<version>/release.json`, published documents, listing assets and
138
138
  `site/registry.json`.
139
+ The archive is built with the host `tar` from the files written out of the checked blobs, so
140
+ its bytes are not reproducible from the source alone (modes and times come from the producing
141
+ host); `publicExport.sha256` in the receipt, not a rebuild, is what the signed statement
142
+ checks the archive against. macOS `tar` would add a `._<name>` AppleDouble member for every file and
143
+ directory carrying an extended attribute: the producer runs it with `COPYFILE_DISABLE=1` and,
144
+ on macOS only, `--no-xattrs`, then reads the member names from the archive bytes and stops the
145
+ release before a digest is recorded if any `._*` member is not a tracked path (a tracked file
146
+ named `._x` is archived like any other).
139
147
  Export attributes cannot silently omit or substitute bytes. The site metadata
140
148
  comes from committed seed and contract data; no screenshots, install guarantees
141
149
  or verified maturity claims are invented. Copy the reviewed bundle into the site
@@ -0,0 +1,22 @@
1
+ import { archiveMembers } from './archive-members.mjs';
2
+
3
+ const normal = path => path.replace(/^(\.\/)+/, '').replace(/\/+$/, '');
4
+
5
+ // macOS tar writes a `._<name>` AppleDouble member beside every file and
6
+ // directory that has extended attributes. The export is the tracked tree and
7
+ // nothing else: such a member is refused unless a tracked path is that name.
8
+ export function assertTrackedMembers(members, trackedPaths) {
9
+ const tracked = new Set();
10
+ for (const path of trackedPaths) {
11
+ const parts = path.split('/');
12
+ for (let length = 1; length <= parts.length; length++) tracked.add(parts.slice(0, length).join('/'));
13
+ }
14
+ const stray = members.map(member => normal(member.path)).filter(path => path && path.split('/').pop().startsWith('._') && !tracked.has(path));
15
+ if (stray.length)
16
+ throw Error(`Public export archive holds ${stray.length} AppleDouble entr${stray.length === 1 ? 'y' : 'ies'} that are not tracked paths (first: ${stray[0]}). `
17
+ + 'macOS tar adds them from extended attributes; the release was stopped before any digest was recorded.');
18
+ }
19
+
20
+ export function assertArchiveTracked(archive, trackedPaths) {
21
+ assertTrackedMembers(archiveMembers(archive), trackedPaths);
22
+ }
@@ -0,0 +1,49 @@
1
+ import { readFileSync } from 'node:fs';
2
+
3
+ // Reads member paths straight from the tar bytes. A system `tar -t` on macOS
4
+ // merges AppleDouble members while listing, so it cannot be trusted to show
5
+ // what a Linux reader will extract.
6
+ const text = bytes => bytes.toString('utf8');
7
+ const field = (block, from, to) => text(block.subarray(from, to)).replace(/\0.*$/s, '');
8
+
9
+ function octal(bytes) {
10
+ if (bytes[0] & 0x80) {
11
+ let value = 0n;
12
+ for (const byte of bytes.subarray(1)) value = (value << 8n) | BigInt(byte);
13
+ return Number(value);
14
+ }
15
+ return parseInt(text(bytes).replace(/\0.*$/s, '').trim() || '0', 8);
16
+ }
17
+
18
+ function paxPath(data) {
19
+ let at = 0;
20
+ while (at < data.length) {
21
+ const space = data.indexOf(0x20, at);
22
+ const length = Number.parseInt(text(data.subarray(at, space)), 10);
23
+ if (!(length > 0)) break;
24
+ const record = text(data.subarray(space + 1, at + length - 1));
25
+ if (record.startsWith('path=')) return record.slice(5);
26
+ at += length;
27
+ }
28
+ return null;
29
+ }
30
+
31
+ export function archiveMembers(file) {
32
+ const bytes = readFileSync(file), members = [];
33
+ let at = 0, next = null;
34
+ while (at + 512 <= bytes.length) {
35
+ const block = bytes.subarray(at, at + 512);
36
+ if (block.every(byte => byte === 0)) break;
37
+ const type = String.fromCharCode(block[156] || 0x30);
38
+ const size = octal(block.subarray(124, 136));
39
+ const data = bytes.subarray(at + 512, at + 512 + size);
40
+ at += 512 + Math.ceil(size / 512) * 512;
41
+ if (type === 'x') { next = paxPath(data) ?? next; continue; }
42
+ if (type === 'L') { next = text(data).replace(/\0.*$/s, ''); continue; }
43
+ if (type === 'g') continue;
44
+ const prefix = field(block, 345, 500);
45
+ members.push({ path: next ?? (prefix ? `${prefix}/` : '') + field(block, 0, 100), type });
46
+ next = null;
47
+ }
48
+ return members;
49
+ }