Artifactspublic-v0

ply

main
ply4 git calls254 ms43 KiB2 cachedprotocol v2
164 lines15 KiBRaw
1// The spaces procedure, from the command line. Reads the registry (test/space/registry.js), the decision-point
2// inventory (scripts/decision-points.mjs), the git manifest (test/space/git-manifest.json) and, for gate c, the
3// fail-site records of a suite run (PLY_FAILSITES=<dir>, written by test/space/failsite-hook.mjs).
4//
5// npm run spaces the hole report, every category, ranked by severity
6// npm run spaces -- --md regenerate SPACES.md
7// npm run spaces -- --ratchet lower test/space/ratchet.json to today's holes (never adds a hole; failsites
8// and claims need PLY_FAILSITES, else they keep their stored ids)
9// npm run spaces -- --ratchet --init --reason "<why>" also add today's new holes to a stored category. With no
10// reason it exits 1, lists them and writes nothing; with one it prints the
11// `Ratchet-Change: test/space/ratchet.json: <why>` line the commit needs
12import { writeFileSync, existsSync } from 'node:fs';
13import { join, isAbsolute } from 'node:path';
14import { fileURLToPath } from 'node:url';
15import { compute, readRecords, ratchet, RATCHET, ROOT, CATEGORIES, severityOfPoint, severityOfGit, spaceByName, isSite } from '../test/space/holes.js';
16import { SPACES, SAMPLED } from '../test/space/registry.js';
18const fmt = n => n.toLocaleString('en-US');
19const esc = s => String(s).replace(/\|/g, '\\|').replace(/\n/g, '\\n').replace(/</g, '&lt;');
21// Holes in one ranked list. Each: { sev, cat, id, where, what }. Fail-site holes come from the ratchet (SPACES.md must
22// not depend on a run), the others from the code as it is.
23export function rankedHoles(all, stored = ratchet().categories) {
24 const pts = new Map(all.points.map(p => [p.id, p]));
25 const gitE = new Map(all.man.entries.map(e => [e.id, e]));
26 const out = [];
27 for (const id of all.holes.git) { const e = gitE.get(id); out.push({ sev: severityOfGit(e), cat: 'git', id, where: `git ${e.file}:${e.line} ${e.fn}()`, what: `${e.kind}: ${e.text}` }); }
28 for (const id of all.holes.decisions) { const p = pts.get(id); out.push({ sev: severityOfPoint(p), cat: 'decisions', id, where: `${p.file} ${p.fn}()`, what: `${p.code}: ${p.what}` }); }
29 for (const id of stored.failsites?.ids ?? []) { const p = pts.get(id); if (p) out.push({ sev: severityOfPoint(p), cat: 'failsites', id, where: `${p.file} ${p.fn}()`, what: `${p.code}: ${p.what}` }); }
30 for (const id of stored.claims?.ids ?? []) out.push({ sev: 2, cat: 'claims', id, where: '', what: 'the registry names a merged space that does not reach this site' });
31 const kindRank = { git: 0, decisions: 1, failsites: 2, claims: 3 };
32 return out.sort((a, b) => a.sev - b.sev || kindRank[a.cat] - kindRank[b.cat] || a.id.localeCompare(b.id));
35export function coverage(all) {
36 const tally = (ids, by) => {
37 const t = { main: 0, pending: 0, excluded: 0, none: 0 };
38 for (const id of ids) {
39 const r = by.get(id);
40 if (!r) t.none++;
41 else if ('excluded' in r) t.excluded++;
42 else t[spaceByName.get(r.space).status === 'main' ? 'main' : 'pending']++;
43 }
44 return t;
45 };
46 const kinds = by => { const k = { enumerated: 0, curated: 0, random: 0 }; for (const r of by.values()) if (r.space) k[spaceByName.get(r.space).kind]++; return k; };
47 return { decisions: tally(all.points.map(p => p.id), all.dec.by), git: tally(all.man.entries.map(e => e.id), all.git.by), decisionKinds: kinds(all.dec.by), gitKinds: kinds(all.git.by) };
50export function renderMd(all) {
51 const st = ratchet().categories;
52 const cov = coverage(all);
53 const L = [];
54 L.push('# Spaces', '');
55 L.push('<!-- generated by scripts/spaces.mjs --md from test/space/registry.js, scripts/decision-points.mjs, test/space/git-manifest.json and test/space/ratchet.json; test/space/registry.test.js fails if it drifts -->', '');
56 L.push('Every decision ply makes, and every check git makes on the same input, belongs to a **space**: a list of axes, each a tagged union, whose product is explored cell by cell and judged by real git. Random fuzzing finds a bug; only enumeration says a bug class is gone (#52 could not tell broken from fixed by fuzzing; the enumerated #51 and #62 spaces found 412,008 and 3,598 wrong cells).', '');
57 L.push('The procedure is enforced, not remembered:', '');
58 L.push('- `scripts/decision-points.mjs` extracts every decision point from `src/` (each `fail(`/`failHere(` call, each call to a fail wrapper, each produced error code, each untyped `throw new Error`, each exported `parse*`/`decode*`/`classify*`/`decide*`).');
59 L.push(`- \`scripts/git-manifest.mjs\` extracts git ${all.man.git.tag}'s own checks (fsck msg ids, die/error/ng/reject strings of the protocol files, capabilities, request arguments, ref-name rules, fsck_tree modes) into \`test/space/git-manifest.json\`.`);
60 L.push('- `test/space/registry.js` maps each one to the space and axis that covers it, or excludes it with a reason.');
61 L.push('- Gates (`test/space/registry.test.js`, `test/space/failsites.test.js`, in CI): **a** every decision point is registered; **b** every git check is covered or excluded; **c** every fail site is reached by a cell (stacks recorded at `plyError` by `test/space/failsite-hook.mjs` in node and by the plugin in `vitest.config.ts` under vitest: `src/` and the bundle are untouched), and every site the registry gives a space is reached by that space\'s runners when they ran. Reached is not judged: a test that triggers an error and asserts nothing reaches the site too, so the recorder also notes whether code outside `src/` read the error\'s `code`, and `failsites.test.js` prints the reached sites whose error nobody read (report only: that list has no ratchet baseline yet). A category with holes is in REPORT mode (holes printed; only a hole not in `test/space/ratchet.json` fails); at 0 it switches to ENFORCE. The ratchet only goes down: `npm run spaces -- --ratchet`.', '');
62 L.push('## Status', '');
63 L.push('| category | holes (ratchet) | mode |', '|---|---:|---|');
64 for (const c of CATEGORIES) L.push(`| ${c} | ${fmt(st[c].count)} | ${st[c].count === 0 ? 'ENFORCE' : 'REPORT'} |`);
65 L.push('');
66 const sites = all.points.filter(isSite).length;
67 L.push(`Decision points: **${fmt(all.points.length)}** (${fmt(sites)} fail sites, ${fmt(all.inv.producers.length)} produced codes, ${fmt(all.inv.untyped.length)} untyped throws, ${fmt(all.inv.exports.length)} exported parse/decode/classify/decide functions). Covered by a merged space ${fmt(cov.decisions.main)}, by a pending PR ${fmt(cov.decisions.pending)}, excluded ${fmt(cov.decisions.excluded)}, unregistered ${fmt(cov.decisions.none)}. Fail sites no cell reaches: ${fmt(st.failsites.count)} of ${fmt(sites)}. Of the registered points, ${fmt(cov.decisionKinds.enumerated)} are claimed by an enumerated space, ${fmt(cov.decisionKinds.random)} only by a random one and ${fmt(cov.decisionKinds.curated)} only by a curated list: a curated or random claim says a case exists, not that the class is gone.`, '');
68 L.push(`git ${all.man.git.tag} checks: **${fmt(all.man.entries.length)}** (${Object.entries(all.man.counts).map(([k, n]) => `${k} ${n}`).join(', ')}). Covered by a merged space ${fmt(cov.git.main)}, by a pending PR ${fmt(cov.git.pending)}, excluded ${fmt(cov.git.excluded)}, uncovered ${fmt(cov.git.none)}. Claimed by an enumerated space ${fmt(cov.gitKinds.enumerated)}, random ${fmt(cov.gitKinds.random)}, curated ${fmt(cov.gitKinds.curated)}.`, '');
69 if (SAMPLED.length) {
70 L.push('Sampled fail sites (reached on some runs only; reported, never ratcheted):', '');
71 for (const x of SAMPLED) L.push(`- \`${esc(x.id)}\` (${x.runner}): ${esc(x.why)}`);
72 L.push('');
73 }
74 L.push('## Spaces', '');
75 L.push('| space | status | kind | axes | cells | observed / derived | oracle | decision points | git checks | run | OS |', '|---|---|---|---|---:|---|---|---:|---:|---|---|');
76 const countBy = by => { const m = new Map(); for (const r of by.values()) if (r.space) m.set(r.space, (m.get(r.space) ?? 0) + 1); return m; };
77 const dN = countBy(all.dec.by), gN = countBy(all.git.by);
78 for (const s of SPACES) {
79 const axes = s.axes.map(a => `${a.tag}${a.n ? `(${a.n})` : ''}`).join(' × ');
80 const cells = typeof s.cells === 'number' ? fmt(s.cells) : esc(s.cells ?? '?');
81 const od = s.observed === undefined ? '—' : `${typeof s.observed === 'number' ? fmt(s.observed) : esc(s.observed)} / ${typeof s.derived === 'number' ? fmt(s.derived) : esc(s.derived ?? '—')}`;
82 L.push(`| \`${s.name}\` | ${s.status === 'main' ? 'main' : `pending ${s.pending}`} | ${s.kind} | ${esc(axes)} | ${cells} | ${od} | ${esc(s.oracle)} | ${dN.get(s.name) ?? 0} | ${gN.get(s.name) ?? 0} | ${s.run}${s.runners?.length ? ` (${s.runners.map(r => `\`${r}\``).join(', ')})` : ''} | ${s.osDependent ? 'dependent¹' : '—'} |`);
83 }
84 L.push('');
85 L.push('¹ OS-dependent cells: expectations come from what the git server does on that run, fixtures keep refs in reftable (git ≥ 2.46, fix/43-bom 716cd77), and the Linux run in CI is the pass of record (the `linux` gate: every merged CI space\'s runners must have a Linux record; a macOS pass never counts).', '');
86 for (const s of SPACES.filter(x => x.osDependent)) L.push(`- \`${s.name}\`: ${esc(s.osDependent)}`);
87 L.push('');
88 // decode sites: every bytes-to-string decode with its mode and what the registry says about it
89 const decs = all.inv.decodes;
90 L.push(`## Decode sites (${decs.length}: ${['lossless', 'strict', 'replacement'].map(m => `${m} ${decs.filter(d => d.mode === m).length}`).join(', ')})`, '');
91 L.push('git passes ref names, tree entry names, messages, idents and paths through as raw bytes. A **strict** decode (fatal TextDecoder, decodeURIComponent) refuses what git accepts; a **replacement** decode (the default TextDecoder) turns non-UTF-8 into U+FFFD and loses it. Either is a severity-1 hole unless the registry excludes it as display text or protocol keywords; the fix is a lossless decode and a space with a non-UTF-8 content axis.', '');
92 L.push('| where | mode | via | registry |', '|---|---|---|---|');
93 for (const d of decs) {
94 const r = all.dec.by.get(d.id);
95 const st = !r ? (d.mode === 'lossless' ? 'unregistered' : '**HOLE (data path)**') : 'excluded' in r ? `excluded: ${esc(r.excluded)}` : `\`${r.space}\` / ${r.axisTag}`;
96 L.push(`| \`${d.file}\` ${d.fn}() | ${d.mode} | ${esc(d.via)} | ${st} |`);
97 }
98 L.push('');
99 const holes = rankedHoles(all, st);
100 const SEV = { 1: 'Severity 1: checks on untrusted input (objects, packs, pkt-lines, reports, advertisements)', 2: 'Severity 2: decisions that claim an outcome (landed, rejected, conflict, ambiguous)', 3: 'Severity 3: the rest (caller input, limits, local I/O)' };
101 L.push(`## Holes (${fmt(holes.length)})`, '');
102 L.push('Ranked by severity, then category (`git`: a git check with no space; `decisions`: a ply decision point with no registry entry; `failsites`: a fail site no cell reaches; `claims`: a registry claim its space does not back). Fail-site and claim holes are the ratchet\'s, from the last recorded run.', '');
103 for (const sev of [1, 2, 3]) {
104 const hs = holes.filter(h => h.sev === sev);
105 L.push(`### ${SEV[sev]} (${fmt(hs.length)})`, '');
106 if (!hs.length) { L.push('None.', ''); continue; }
107 L.push('| category | id | where | what |', '|---|---|---|---|');
108 for (const h of hs) L.push(`| ${h.cat} | \`${esc(h.id)}\` | ${esc(h.where)} | ${esc(h.what.slice(0, 120))} |`);
109 L.push('');
110 }
111 return `${L.join('\n')}\n`;
114export function report(all) {
115 const holes = rankedHoles(all, { failsites: { ids: all.holes.failsites ?? ratchet().categories.failsites.ids }, claims: { ids: all.holes.claims ?? ratchet().categories.claims.ids } });
116 const cov = coverage(all);
117 console.log(`decision points ${all.points.length}: main ${cov.decisions.main}, pending ${cov.decisions.pending}, excluded ${cov.decisions.excluded}, unregistered ${cov.decisions.none}`);
118 console.log(`git checks ${all.man.entries.length}: main ${cov.git.main}, pending ${cov.git.pending}, excluded ${cov.git.excluded}, uncovered ${cov.git.none}`);
119 for (const c of CATEGORIES) console.log(`${c}: ${all.holes[c] === null ? '(no records; ratchet)' : ''} ${(all.holes[c] ?? ratchet().categories[c].ids).length}`);
120 for (const sev of [1, 2, 3]) {
121 const hs = holes.filter(h => h.sev === sev);
122 console.log(`\n== severity ${sev}: ${hs.length}`);
123 for (const h of hs) console.log(` [${h.cat}] ${h.id} ${h.where}`);
124 }
127if (process.argv[1] === fileURLToPath(import.meta.url)) {
128 const dir = process.env.PLY_FAILSITES;
129 const records = dir ? readRecords(isAbsolute(dir) ? dir : join(ROOT, dir)) : null;
130 if (dir && !records) throw new Error(`no records under ${dir}`);
131 const all = compute({ records });
132 if (process.argv.includes('--ratchet')) {
133 const init = process.argv.includes('--init');
134 const at = process.argv.indexOf('--reason');
135 const reason = at < 0 ? '' : (process.argv[at + 1] ?? '').trim();
136 const old = existsSync(RATCHET) ? ratchet().categories : {};
137 const categories = {};
138 const added = [];
139 for (const c of CATEGORIES) {
140 const now = all.holes[c];
141 let ids;
142 if (now === null) ids = old[c]?.ids ?? [];
143 else if (!old[c]) ids = now;
144 else {
145 const keep = new Set(old[c].ids);
146 ids = init ? now : now.filter(id => keep.has(id));
147 for (const id of ids) if (!keep.has(id)) added.push(`[${c}] ${id}`);
148 }
149 categories[c] = { count: ids.length, ids: [...ids].sort() };
150 }
151 // A hole enters an existing category only with a stated reason, and the commit must repeat it: ci's
152 // scripts/ratchet-guard.mjs compares ratchet.json with the base commit's and fails without the line.
153 const line = `Ratchet-Change: test/space/ratchet.json: ${reason === '' ? '<reason>' : reason}`;
154 if (added.length > 0 && reason === '') {
155 console.error(`spaces: --ratchet --init would add ${added.length} hole(s) to test/space/ratchet.json; nothing written:\n${added.map(a => ` ${a}`).join('\n')}\nClose them, or rerun with --reason "<why>" and put this line in the commit message:\n ${line}`);
156 process.exit(1);
157 }
158 if (added.length > 0) console.log(`added ${added.length} hole(s):\n${added.map(a => ` ${a}`).join('\n')}\nthe commit message must carry the line:\n ${line}`);
159 writeFileSync(RATCHET, `${JSON.stringify({ note: 'Holes per category (test/space/holes.js). Only ever lowered: npm run spaces -- --ratchet. A category at 0 is enforced.', categories }, null, 1)}\n`);
160 for (const c of CATEGORIES) console.log(`${c}: ${categories[c].count}`);
161 }
162 if (process.argv.includes('--md')) writeFileSync(join(ROOT, 'SPACES.md'), renderMd(all));
163 if (!process.argv.includes('--ratchet') && !process.argv.includes('--md')) report(all);
Diagnostics4 git calls · 254 ms
CallStatusSizeTime0254 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=4
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020038 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=38434
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=38434
git.pkt.payload.max=38339
git.sideband.band1.bytes=38338
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=63
git.pack.bytes=38338
git.pack.ofs_delta=0
git.pack.ref_delta=8
git.pack.chain.max=8
git.pack.trailer=0bc36ab7adf82d3109177f11f1ea93f1ce071f77
git.pack.full=55
Open pack map
fetch2005.4 KiB248 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=248
git.response.bytes=5517
git.response.cache=MISS
git.response.duration_ms=248
git.fetch.wants=8f989e101c1ec5dc5d63260d451e445316064acb
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=5517
git.pkt.payload.max=5496
git.sideband.band1.bytes=5495
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply.git
Ref
refs/heads/main
Commit
19912563f540228593df0c489082e5e2508e21e4
cf-ray
a5e2a4cf195b1293
Request
a9536853…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format