@holmes-lab/holmes-kit 0.40.1 → 0.41.1
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.
- package/CHANGELOG.md +86 -0
- package/README.md +12 -4
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve-context.js +4 -3
- package/dist/holmes/cli/approve.js +22 -12
- package/dist/holmes/cli/autonomy.d.ts +21 -0
- package/dist/holmes/cli/autonomy.js +35 -5
- package/dist/holmes/cli/doctor.js +58 -6
- package/dist/holmes/cli/index.js +371 -250
- package/dist/holmes/cli/init.js +26 -6
- package/dist/holmes/cli/ledger-witness.d.ts +61 -0
- package/dist/holmes/cli/ledger-witness.js +252 -0
- package/dist/holmes/cli/playbook-skills.d.ts +3 -56
- package/dist/holmes/cli/playbook-skills.js +63 -354
- package/dist/holmes/cli/test-platform.d.ts +6 -0
- package/dist/holmes/cli/test-platform.js +12 -0
- package/dist/holmes/config/config.d.ts +9 -1
- package/dist/holmes/config/config.js +10 -3
- package/dist/holmes/governance/approval-grants.d.ts +2 -0
- package/dist/holmes/governance/approval-grants.js +6 -5
- package/dist/holmes/governance/approval-queue.d.ts +65 -1
- package/dist/holmes/governance/approval-queue.js +279 -9
- package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
- package/dist/holmes/governance/autonomous-shell.js +157 -4
- package/dist/holmes/governance/autonomy.d.ts +209 -0
- package/dist/holmes/governance/autonomy.js +1129 -6
- package/dist/holmes/governance/install-manifest.d.ts +7 -4
- package/dist/holmes/governance/install-manifest.js +159 -15
- package/dist/holmes/governance/ledger-witness.d.ts +63 -0
- package/dist/holmes/governance/ledger-witness.js +296 -0
- package/dist/holmes/governance/provenance-chain.d.ts +8 -1
- package/dist/holmes/governance/provenance-chain.js +23 -4
- package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
- package/dist/holmes/governance/recorded-pairs.js +25 -1
- package/dist/holmes/governance/session-context.d.ts +7 -0
- package/dist/holmes/governance/session-context.js +34 -6
- package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
- package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
- package/dist/holmes/guardrail/command-traits.d.ts +102 -0
- package/dist/holmes/guardrail/command-traits.js +379 -0
- package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
- package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
- package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
- package/dist/holmes/guardrail/outward-acts.js +1102 -0
- package/dist/holmes/guardrail/refusal-codes.js +8 -1
- package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
- package/dist/holmes/guardrail/refusal-templates.js +71 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
- package/dist/holmes/guardrail/risk-classifier.js +12 -118
- package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
- package/dist/holmes/guardrail/shell-lexer.js +567 -0
- package/dist/holmes/guardrail/write-target.js +7 -1
- package/dist/holmes/hooks/pre-tool-use.d.ts +60 -0
- package/dist/holmes/hooks/pre-tool-use.js +1423 -10
- package/dist/holmes/hooks/session-start.js +11 -1
- package/dist/holmes/hooks/stop.d.ts +7 -0
- package/dist/holmes/hooks/stop.js +39 -2
- package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
- package/dist/holmes/mcp/elicit-approval.js +5 -2
- package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
- package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
- package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
- package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
- package/dist/holmes/mcp/handlers/entity-store.js +7 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
- package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
- package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
- package/dist/holmes/mcp/handlers/test-execution.d.ts +6 -0
- package/dist/holmes/mcp/handlers/test-execution.js +37 -9
- package/dist/holmes/mcp/handlers.d.ts +5 -5
- package/dist/holmes/mcp/handlers.js +2 -1
- package/dist/holmes/mcp/tool-schemas.js +4 -4
- package/dist/holmes/project/playbook-reference.d.ts +50 -0
- package/dist/holmes/project/playbook-reference.js +259 -0
- package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
- package/dist/holmes/project/playbook-skill-states.js +396 -0
- package/dist/holmes/project/root.d.ts +9 -1
- package/dist/holmes/project/root.js +23 -2
- package/dist/holmes/project/running-package.d.ts +15 -0
- package/dist/holmes/project/running-package.js +87 -0
- package/dist/holmes/review/head-worktree.js +9 -1
- package/dist/holmes/review/test-runner.d.ts +2 -0
- package/dist/holmes/review/test-runner.js +38 -11
- package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
- package/dist/holmes/spec/entity-integration-transaction.js +68 -7
- package/package.json +5 -2
|
@@ -5,18 +5,21 @@ export interface ManifestFile {
|
|
|
5
5
|
}
|
|
6
6
|
export interface ProductProblem {
|
|
7
7
|
path?: string;
|
|
8
|
-
why: 'manifest-missing' | 'manifest-invalid' | 'manifest-tampered' | 'missing' | 'changed' | 'staged' | 'in-index';
|
|
8
|
+
why: 'manifest-missing' | 'manifest-invalid' | 'manifest-tampered' | 'missing' | 'changed' | 'drifted' | 'staged' | 'in-index';
|
|
9
9
|
}
|
|
10
10
|
export declare function readInstallManifest(root: string): ManifestFile[] | null;
|
|
11
11
|
/**
|
|
12
12
|
* Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
|
|
13
13
|
* the sha256 of its content now; a path outside the target is never listed.
|
|
14
14
|
*/
|
|
15
|
-
export declare function writeInstallManifest(target: string, paths: string[], version: string
|
|
15
|
+
export declare function writeInstallManifest(target: string, paths: string[], version: string, opts?: {
|
|
16
|
+
drop?: string[];
|
|
17
|
+
}): void;
|
|
16
18
|
export declare function removeInstallManifest(target: string): void;
|
|
17
19
|
/**
|
|
18
20
|
* Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
|
|
19
|
-
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
|
|
21
|
+
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest. A recovery skill the
|
|
22
|
+
* package ships is judged against the running build's playbook instead of its digest (A-SPEC-794.100).
|
|
20
23
|
*/
|
|
21
|
-
export declare function productInstalledProblems(root: string, staged?: string[]): ProductProblem[];
|
|
24
|
+
export declare function productInstalledProblems(root: string, staged?: string[], packageRoot?: string): ProductProblem[];
|
|
22
25
|
export declare function describeProductInstalled(problems: ProductProblem[]): string;
|
|
@@ -39,7 +39,7 @@ exports.writeInstallManifest = writeInstallManifest;
|
|
|
39
39
|
exports.removeInstallManifest = removeInstallManifest;
|
|
40
40
|
exports.productInstalledProblems = productInstalledProblems;
|
|
41
41
|
exports.describeProductInstalled = describeProductInstalled;
|
|
42
|
-
// @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57
|
|
42
|
+
// @implements A-SPEC-792.16, A-SPEC-222.10, A-SPEC-794.55, A-SPEC-794.57, A-SPEC-794.100, A-SPEC-794.106, A-SPEC-794.107, A-SPEC-794.110, A-SPEC-794.111, A-SPEC-794.113, A-SPEC-794.121
|
|
43
43
|
/**
|
|
44
44
|
* The files the product installed in a target, by path and digest, as init recorded them. A self-approval must never
|
|
45
45
|
* cover one of them: a changed, staged or missing product file — or no record at all — is a reason to refuse.
|
|
@@ -48,7 +48,12 @@ const crypto = __importStar(require("node:crypto"));
|
|
|
48
48
|
const fs = __importStar(require("node:fs"));
|
|
49
49
|
const path = __importStar(require("node:path"));
|
|
50
50
|
const bounded_io_1 = require("../project/bounded-io");
|
|
51
|
+
const runningPackage = __importStar(require("../project/running-package"));
|
|
51
52
|
exports.INSTALL_MANIFEST = path.join('.ax', 'state', 'install-manifest.json');
|
|
53
|
+
const problemDetail = new WeakMap();
|
|
54
|
+
const withDetail = (p, d) => { problemDetail.set(p, d); return p; };
|
|
55
|
+
/** @implements A-SPEC-794.121 — a missing entry an earlier init recorded beside a recovery skill (a backup, a user file). */
|
|
56
|
+
const besideSkill = new WeakSet();
|
|
52
57
|
const MANIFEST_EVENT = 'install-manifest';
|
|
53
58
|
const digestOf = (abs) => {
|
|
54
59
|
try {
|
|
@@ -56,7 +61,7 @@ const digestOf = (abs) => {
|
|
|
56
61
|
}
|
|
57
62
|
catch {
|
|
58
63
|
return null;
|
|
59
|
-
}
|
|
64
|
+
} // [no-substitution: unreadable → null, which is `missing` or a mismatch]
|
|
60
65
|
};
|
|
61
66
|
const inside = (root, abs) => { const r = path.relative(root, abs); return r !== '' && !r.startsWith('..') && !path.isAbsolute(r); };
|
|
62
67
|
function readInstallManifest(root) {
|
|
@@ -74,7 +79,7 @@ function readManifestChecked(root) {
|
|
|
74
79
|
}
|
|
75
80
|
catch {
|
|
76
81
|
return null;
|
|
77
|
-
}
|
|
82
|
+
} // [no-substitution: unreadable manifest → `manifest-missing`]
|
|
78
83
|
}
|
|
79
84
|
/** @implements A-SPEC-792.18 — the digest the last init recorded for the manifest, or null when none is recorded. */
|
|
80
85
|
function recordedManifestDigest(root) {
|
|
@@ -89,17 +94,20 @@ function recordedManifestDigest(root) {
|
|
|
89
94
|
return d ? d.slice(7) : null;
|
|
90
95
|
}
|
|
91
96
|
}
|
|
92
|
-
catch { /* unreadable ledger
|
|
97
|
+
catch { /* [no-substitution: unreadable ledger → nothing is recorded → `manifest-tampered`] */ }
|
|
93
98
|
return null;
|
|
94
99
|
}
|
|
95
100
|
/**
|
|
96
101
|
* Records `paths` (absolute or target-relative) and every path the previous manifest listed that still exists, each with
|
|
97
102
|
* the sha256 of its content now; a path outside the target is never listed.
|
|
98
103
|
*/
|
|
99
|
-
function writeInstallManifest(target, paths, version) {
|
|
104
|
+
function writeInstallManifest(target, paths, version, opts = {}) {
|
|
100
105
|
const previous = (readInstallManifest(target) ?? []).map((f) => f.path);
|
|
101
|
-
|
|
102
|
-
|
|
106
|
+
// @implements A-SPEC-794.107 (B-M2) — paths init does not own (a skill it left untouched) leave the record, previous or new
|
|
107
|
+
const abs = (p) => path.normalize(path.isAbsolute(p) ? p : path.join(target, p));
|
|
108
|
+
const dropped = new Set((opts.drop ?? []).map(abs));
|
|
109
|
+
const rels = [...new Set([...paths.map(abs), ...previous.map(abs)]
|
|
110
|
+
.filter((a) => inside(target, a) && !dropped.has(a)).map((a) => path.relative(target, a)))].sort();
|
|
103
111
|
const files = rels.map((rel) => ({ path: rel, sha256: digestOf(path.join(target, rel)) })).filter((f) => f.sha256 !== null);
|
|
104
112
|
const file = path.join(target, exports.INSTALL_MANIFEST);
|
|
105
113
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
@@ -116,13 +124,75 @@ function removeInstallManifest(target) {
|
|
|
116
124
|
try {
|
|
117
125
|
fs.rmSync(path.join(target, exports.INSTALL_MANIFEST), { force: true });
|
|
118
126
|
}
|
|
119
|
-
catch { /* nothing
|
|
127
|
+
catch { /* [no-substitution: nothing was removed; a manifest that stays is judged as any other] */ }
|
|
128
|
+
}
|
|
129
|
+
/** The installed package's version and path, as the refusal names them. */
|
|
130
|
+
function referenceOf(packageRoot) {
|
|
131
|
+
let version = 'unknown';
|
|
132
|
+
try {
|
|
133
|
+
version = String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
|
|
134
|
+
}
|
|
135
|
+
catch { /* [no-substitution: the version only appears in the refusal's text] */ }
|
|
136
|
+
return { version, path: packageRoot };
|
|
137
|
+
}
|
|
138
|
+
function recoverySkillVerdicts(root, packageRoot) {
|
|
139
|
+
try {
|
|
140
|
+
// A-SPEC-794.101 — the verdict lives below the cli layer; governance reaches no cli module
|
|
141
|
+
const { skillPathFor } = require('../project/playbook-skill-states');
|
|
142
|
+
// A-SPEC-794.110 — the one reference doctor and init read too
|
|
143
|
+
const { judgedSkillStates } = require('../project/playbook-reference');
|
|
144
|
+
const relOf = (name) => path.normalize(path.relative(root, skillPathFor(root, name)));
|
|
145
|
+
const judged = judgedSkillStates(packageRoot, root);
|
|
146
|
+
const states = judged.states;
|
|
147
|
+
if (states.length === 0)
|
|
148
|
+
return null;
|
|
149
|
+
const movedNames = new Set(judged.moved);
|
|
150
|
+
const out = { verdicts: new Map(), foreign: new Set(), moved: new Map(), closed: judged.reference.kind === 'closed' ? judged.reference.reason : undefined };
|
|
151
|
+
for (const s of states) {
|
|
152
|
+
if (s.state === 'foreign') {
|
|
153
|
+
out.foreign.add(relOf(s.name));
|
|
154
|
+
continue;
|
|
155
|
+
}
|
|
156
|
+
// A-SPEC-794.113 (the census of failure branches) — against a recorded build (a checkout), a skill whose
|
|
157
|
+
// playbook is gone or cannot be read is not handed to the install record's digest: the playbook is a file the
|
|
158
|
+
// workspace can take away, and the record is one init rewrites. It is drifted, as any skill whose playbook is not
|
|
159
|
+
// the recorded one. [no-substitution: unreadable source in a checkout → drifted]
|
|
160
|
+
const unreadableInCheckout = s.state === 'source-unreadable' && judged.reference.kind !== 'package';
|
|
161
|
+
// A-SPEC-794.106 (B-1) — only current, drifted and missing are the product's verdict; an aliased, unresolvable or
|
|
162
|
+
// orphaned skill keeps the digest judgement, and so does a source-unreadable one of a deployed package (its
|
|
163
|
+
// playbooks are the package's files; with one unreadable, init refuses and does not rewrite the record — measured)
|
|
164
|
+
if (s.state !== 'current' && s.state !== 'drifted' && s.state !== 'missing' && !unreadableInCheckout)
|
|
165
|
+
continue;
|
|
166
|
+
// A-SPEC-794.106 — a linked skill file or directory is judged by its digest (where the link points is not ours)
|
|
167
|
+
const abs = skillPathFor(root, s.name);
|
|
168
|
+
const linked = [abs, path.dirname(abs)].some((p) => { try {
|
|
169
|
+
return fs.lstatSync(p).isSymbolicLink();
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
return false;
|
|
173
|
+
} }); // [no-substitution: cannot be told → not a link, so the product's verdict judges it]
|
|
174
|
+
if (linked)
|
|
175
|
+
continue;
|
|
176
|
+
const verdict = unreadableInCheckout ? 'drifted' : s.state;
|
|
177
|
+
out.verdicts.set(relOf(s.name), verdict);
|
|
178
|
+
if (verdict === 'drifted' && movedNames.has(s.name))
|
|
179
|
+
out.moved.set(relOf(s.name), `playbooks/${s.name}/PLAYBOOK.md`);
|
|
180
|
+
}
|
|
181
|
+
return out;
|
|
182
|
+
}
|
|
183
|
+
catch {
|
|
184
|
+
// [kept-judge: the skills could not be judged at all → every entry keeps the install record's digest (A-SPEC-794.100).
|
|
185
|
+
// What holds it: only init rewrites that record, and init refuses while a skill is not the product's. Named in
|
|
186
|
+
// A-SPEC-794.113 as kept, with the linked, aliased, unresolvable and orphaned skills of A-SPEC-794.106]
|
|
187
|
+
return null;
|
|
188
|
+
}
|
|
120
189
|
}
|
|
121
190
|
/**
|
|
122
191
|
* Each manifest file that is missing, changed against its digest, in `staged` (paths a command stages, target-relative)
|
|
123
|
-
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest.
|
|
192
|
+
* or staged in the index against HEAD; `manifest-missing` when there is no readable manifest. A recovery skill the
|
|
193
|
+
* package ships is judged against the running build's playbook instead of its digest (A-SPEC-794.100).
|
|
124
194
|
*/
|
|
125
|
-
function productInstalledProblems(root, staged = []) {
|
|
195
|
+
function productInstalledProblems(root, staged = [], packageRoot = runningPackage.RUNNING_PACKAGE_ROOT) {
|
|
126
196
|
const checked = readManifestChecked(root);
|
|
127
197
|
if (checked === null)
|
|
128
198
|
return [{ why: 'manifest-missing' }];
|
|
@@ -139,10 +209,37 @@ function productInstalledProblems(root, staged = []) {
|
|
|
139
209
|
const r = (0, bounded_io_1.gitOnce)(root, ['-c', 'core.fsmonitor=false', 'diff', '--cached', '--name-only', '-z', '--no-renames'], 'repo');
|
|
140
210
|
const indexChanged = new Set(r.status === 0 ? String(r.stdout).split('\0').filter(Boolean).map(norm) : []);
|
|
141
211
|
const out = [...head];
|
|
212
|
+
const skills = recoverySkillVerdicts(root, packageRoot);
|
|
213
|
+
const reference = referenceOf(packageRoot);
|
|
214
|
+
// A-SPEC-794.121 — the playbook skill directories, by the package's playbook list (a location, not a file name)
|
|
215
|
+
// (playbookNames answers [] when the playbooks cannot be listed: then the plain text, and the judgement is the same)
|
|
216
|
+
const { playbookNames, skillPathFor: skillFileOf } = require('../project/playbook-skill-states');
|
|
217
|
+
const skillDirs = new Set(playbookNames(packageRoot).map((n) => norm(path.dirname(path.relative(root, skillFileOf(root, n))))));
|
|
218
|
+
const isBesideSkill = (rel) => skillDirs.has(norm(path.dirname(rel))) && path.basename(rel) !== 'SKILL.md';
|
|
142
219
|
for (const f of files) {
|
|
220
|
+
const skill = skills?.verdicts.get(norm(f.path));
|
|
143
221
|
const now = digestOf(path.join(root, f.path));
|
|
144
|
-
|
|
145
|
-
|
|
222
|
+
// A-SPEC-794.107 (B-M2) — a recorded skill without the marker keeps the digest judgement (a product skill stripped of
|
|
223
|
+
// its marker is changed bytes); when it changed, the text names the way out for a user's own skill. init no longer
|
|
224
|
+
// records such a skill and drops an earlier record of it.
|
|
225
|
+
if (skills?.foreign.has(norm(f.path))) {
|
|
226
|
+
if (now === null)
|
|
227
|
+
out.push({ path: f.path, why: 'missing' });
|
|
228
|
+
else if (now !== f.sha256)
|
|
229
|
+
out.push(withDetail({ path: f.path, why: 'changed' }, { reference, root, foreign: true }));
|
|
230
|
+
}
|
|
231
|
+
else if (skill !== undefined) {
|
|
232
|
+
if (skill === 'drifted')
|
|
233
|
+
out.push(withDetail({ path: f.path, why: 'drifted' }, { reference, root, moved: skills?.moved.get(norm(f.path)), closed: skills?.closed }));
|
|
234
|
+
else if (skill === 'missing')
|
|
235
|
+
out.push({ path: f.path, why: 'missing' });
|
|
236
|
+
}
|
|
237
|
+
else if (now === null) {
|
|
238
|
+
const p = { path: f.path, why: 'missing' };
|
|
239
|
+
if (isBesideSkill(f.path))
|
|
240
|
+
besideSkill.add(p);
|
|
241
|
+
out.push(p);
|
|
242
|
+
}
|
|
146
243
|
else if (now !== f.sha256)
|
|
147
244
|
out.push({ path: f.path, why: 'changed' });
|
|
148
245
|
// A-SPEC-794.57 — what the command stages, and what the index already holds, are told apart
|
|
@@ -154,7 +251,54 @@ function productInstalledProblems(root, staged = []) {
|
|
|
154
251
|
return out;
|
|
155
252
|
}
|
|
156
253
|
function describeProductInstalled(problems) {
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
254
|
+
// review B (low 7) — a path with a space is quoted where a command is shown
|
|
255
|
+
const q = (p) => (/[\s"'$`\\]/.test(p) ? `'${p.replace(/'/g, '\'\\\'\'')}'` : p);
|
|
256
|
+
// review B (low 1) — one reason for every skill it closes, said once with the skills listed (it was repeated per skill:
|
|
257
|
+
// 3,503 characters for seven skills, measured)
|
|
258
|
+
const closedSkills = problems.filter((p) => p.why === 'drifted' && p.path !== undefined && problemDetail.get(p)?.closed !== undefined);
|
|
259
|
+
const closedText = closedSkills.length === 0 ? [] : [
|
|
260
|
+
`product-installed: ${closedSkills.length} recovery skill${closedSkills.length === 1 ? '' : 's'} cannot be shown to be the product (drifted: ${closedSkills.map((p) => p.path).join(', ')}) — ${problemDetail.get(closedSkills[0]).closed}`,
|
|
261
|
+
];
|
|
262
|
+
return [...closedText, ...problems.filter((p) => !closedSkills.includes(p)).map((p) => {
|
|
263
|
+
if (p.why === 'manifest-missing')
|
|
264
|
+
return 'product-installed: no install manifest (run holmes-kit init)';
|
|
265
|
+
if (p.path === undefined)
|
|
266
|
+
return `product-installed: the install manifest is ${p.why === 'manifest-invalid' ? 'invalid' : 'not the one init recorded'} (${p.why})`;
|
|
267
|
+
const d = problemDetail.get(p);
|
|
268
|
+
if (d) {
|
|
269
|
+
// @implements A-SPEC-794.107 (B-L1) — the route is that install's own entry point, runnable as written
|
|
270
|
+
const cli = `node ${q(path.join(d.reference.path, 'bin', 'holmes-kit.js'))}`;
|
|
271
|
+
const refresh = `\`${cli} skills refresh --target ${q(d.root)}\``;
|
|
272
|
+
// A-SPEC-794.107 (B-M2) — the way out for a user's own skill an earlier init recorded
|
|
273
|
+
// A-SPEC-794.110 (A-L2, B-M3) — on a path the product names the warning comes first, and the exit says what it
|
|
274
|
+
// needs and what else it does
|
|
275
|
+
if (p.why === 'changed' && d.foreign) {
|
|
276
|
+
const productNamed = /(?:^|[\\/])holmes-[^\\/]+[\\/]SKILL\.md$/.test(p.path);
|
|
277
|
+
return `product-installed: ${p.path} carries no holmes-kit marker and changed since the install record (changed) — `
|
|
278
|
+
+ (productNamed ? 'this path is one holmes-kit installs, and a product skill stripped of its marker is a changed product file: if it was holmes-kit\'s, restore or refresh it; only ' : '')
|
|
279
|
+
+ `if it is your own skill, run \`${cli} init --force --target ${q(d.root)}\` so init drops it from the record (init --force needs the operator's approval and rewrites the wiring with its defaults)`;
|
|
280
|
+
}
|
|
281
|
+
// A-SPEC-794.110 (B-M1), A-SPEC-794.113 (review B, mediums 1 and 2, low 5) — the playbook is not the one the
|
|
282
|
+
// recorded build held. What moves the reference is a person's window here and a build the hook records, so the text
|
|
283
|
+
// says that, in order; it does not open with "restore it" (the change may be another machine's legitimate one, come
|
|
284
|
+
// with a pull), and it names the playbook where it is — the gate's checkout, which need not be this project
|
|
285
|
+
if (p.why === 'drifted' && d.moved) {
|
|
286
|
+
const playbook = path.join(d.reference.path, d.moved);
|
|
287
|
+
// review B (confirming, M2) — why the recorded one is older, and how an approved spec is sealed again
|
|
288
|
+
return `product-installed: ${playbook} is not the playbook the gate last recorded in that checkout, and the recorded one is the reference (${p.path} drifted) — `
|
|
289
|
+
+ 'the recorded digest is an earlier build\'s: at the last build no person\'s window naming this playbook was open. '
|
|
290
|
+
+ 'If the change is wanted (yours, or one that came with a pull): a person seals, in a session in that checkout, an A-SPEC whose Files to Touch names the playbook '
|
|
291
|
+
+ '— `spec_approve` again on the A-SPEC that names it (the form says it is a re-seal), or a new one — '
|
|
292
|
+
+ '(and, in Holmes-Kit\'s own repository, the SKILL.md under .claude/skills, a principle 7 path there); a build run in a governed agent session inside that window records it '
|
|
293
|
+
+ `(a build run outside such a session records nothing); then run ${refresh} and commit the refreshed SKILL.md. If the change is not wanted, restore the playbook`;
|
|
294
|
+
}
|
|
295
|
+
// A-SPEC-794.106 (B-2, B-3) — the cause first, doctor's word, and the route: refresh from that install, a person commits
|
|
296
|
+
if (p.why === 'drifted')
|
|
297
|
+
return `product-installed: ${p.path} differs from the playbook of holmes-kit ${d.reference.version} at ${d.reference.path} (drifted) — run ${refresh} with that install, then a person commits the file`;
|
|
298
|
+
}
|
|
299
|
+
// A-SPEC-794.121 — the text only; the judgement is unchanged
|
|
300
|
+
if (besideSkill.has(p))
|
|
301
|
+
return `product-installed: ${p.path} (missing) — recorded by an earlier init beside a recovery skill and since removed — run \`holmes-kit init\` (a person) to refresh the record`;
|
|
302
|
+
return `product-installed: ${p.path} (${p.why === 'in-index' ? 'already in the index' : p.why})`;
|
|
303
|
+
})].join('; ');
|
|
160
304
|
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
export interface WitnessHead {
|
|
2
|
+
seq: number;
|
|
3
|
+
hash: string;
|
|
4
|
+
sha256: string;
|
|
5
|
+
}
|
|
6
|
+
export interface WitnessEntry extends WitnessHead {
|
|
7
|
+
ts: string;
|
|
8
|
+
pending?: WitnessHead;
|
|
9
|
+
}
|
|
10
|
+
/** The digest of an absent chain file: no rows is the empty content. */
|
|
11
|
+
export declare const EMPTY_CHAIN_SHA256: string;
|
|
12
|
+
/** The chain file's place: a `provenance.<replica>.jsonl` (or the legacy `provenance.jsonl`) under `<root>/.ax/ledger`. */
|
|
13
|
+
export declare function chainPlace(chainFile: string): {
|
|
14
|
+
root: string;
|
|
15
|
+
replica: string;
|
|
16
|
+
} | null;
|
|
17
|
+
/** The git directory of the checkout `root` is in (the nearest `.git` at or above it; a linked worktree's own). */
|
|
18
|
+
export declare function gitDirOf(root: string): string | null;
|
|
19
|
+
/** Where the witness lives for `root` (the hook refuses a session's write there). */
|
|
20
|
+
export declare function witnessDirOf(root: string): string | null;
|
|
21
|
+
/** The whole chain file's digest; an absent file is the empty content. Null when it cannot be read. */
|
|
22
|
+
export declare function chainDigest(chainFile: string): string | null;
|
|
23
|
+
export type AppendToken = {
|
|
24
|
+
root: string;
|
|
25
|
+
replica: string;
|
|
26
|
+
head: WitnessHead;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Before row `next` is written onto `before` (the chain file's content now): when this replica has an entry and the file
|
|
30
|
+
* is its head or its pending one, the entry's pending becomes the row about to be written. Otherwise nothing is written
|
|
31
|
+
* and null is returned — no entry (never created here), or a file the witness does not hold (not laundered).
|
|
32
|
+
*/
|
|
33
|
+
export declare function beforeAppend(chainFile: string, before: string, next: {
|
|
34
|
+
seq: number;
|
|
35
|
+
hash: string;
|
|
36
|
+
}, line: string): AppendToken | null;
|
|
37
|
+
/** After the row is written: the pending head becomes the head. */
|
|
38
|
+
export declare function afterAppend(token: AppendToken | null): void;
|
|
39
|
+
export type WitnessKind = 'no-repository' | 'no-witness' | 'replica-changed' | 'unreadable' | 'taken-back' | 'extended' | 'broken';
|
|
40
|
+
export type WitnessVerdict = {
|
|
41
|
+
ok: true;
|
|
42
|
+
head: WitnessHead;
|
|
43
|
+
} | {
|
|
44
|
+
ok: false;
|
|
45
|
+
kind: WitnessKind;
|
|
46
|
+
detail: string;
|
|
47
|
+
witnessed?: WitnessHead;
|
|
48
|
+
others?: string[];
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Whether this replica's chain file is the one this repository wrote. The one computation the judgements and the
|
|
52
|
+
* vouching form read (the form shows this verdict; it does not compute another).
|
|
53
|
+
*/
|
|
54
|
+
export declare function chainWitnessVerdict(chainFile: string): WitnessVerdict;
|
|
55
|
+
/**
|
|
56
|
+
* The person's act (cli/ledger-witness.ts, after a grant): the witness of this replica becomes the chain file as it is.
|
|
57
|
+
* `expected` is the head the request showed the person; a chain that moved since is not vouched for.
|
|
58
|
+
*/
|
|
59
|
+
export declare function vouch(chainFile: string, expected?: {
|
|
60
|
+
sha256: string;
|
|
61
|
+
}): WitnessHead;
|
|
62
|
+
/** The chain file's head as it is now: its last row's seq and hash (-1 and GENESIS when empty) and the whole digest. */
|
|
63
|
+
export declare function currentHead(chainFile: string): WitnessHead;
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.EMPTY_CHAIN_SHA256 = void 0;
|
|
37
|
+
exports.chainPlace = chainPlace;
|
|
38
|
+
exports.gitDirOf = gitDirOf;
|
|
39
|
+
exports.witnessDirOf = witnessDirOf;
|
|
40
|
+
exports.chainDigest = chainDigest;
|
|
41
|
+
exports.beforeAppend = beforeAppend;
|
|
42
|
+
exports.afterAppend = afterAppend;
|
|
43
|
+
exports.chainWitnessVerdict = chainWitnessVerdict;
|
|
44
|
+
exports.vouch = vouch;
|
|
45
|
+
exports.currentHead = currentHead;
|
|
46
|
+
// @implements A-SPEC-794.114, A-SPEC-794.115
|
|
47
|
+
/**
|
|
48
|
+
* The ledger's own chain has a witness outside the tree (A-SPEC-794.114). The provenance chain is a tracked file, so a
|
|
49
|
+
* whole-tree move took it back with the tree (and the baseline with it), and a chain extended outside this repository —
|
|
50
|
+
* a valid row, a person's seal included, made with the package's own API — came in through git plumbing and a checkout
|
|
51
|
+
* (measured 11-12, guardrail/baseline-row-reset.test.ts). The witness is a fact of the git directory, which no checkout,
|
|
52
|
+
* stash, reset, merge or pull writes: per replica, the head of that replica's chain as this repository last wrote it —
|
|
53
|
+
* its seq and hash, and the sha256 of the whole chain file — and, while an append is under way, the head it is about to
|
|
54
|
+
* write (`pending`).
|
|
55
|
+
*
|
|
56
|
+
* One writer: the chain's one write point (`ProvenanceChain.appendUnlocked`, A-SPEC-794.115), under the chain's lock,
|
|
57
|
+
* and the person's vouching act (cli/ledger-witness.ts). An append never creates an entry (no witness stays no witness:
|
|
58
|
+
* "trust the chain as it is" would be the same defect again), and never moves an entry the current file does not match
|
|
59
|
+
* (a row appended to a chain that was taken back or extended does not launder it — the hook itself appends refusal rows).
|
|
60
|
+
* Readers: the principle 7 judgement and the skills' reference. A chain is read only when the whole file is the
|
|
61
|
+
* witnessed head or the pending one; otherwise the judgement closes with the kind below. The whole file, not the last
|
|
62
|
+
* row: a chain taken back with a copy of the real last row appended would match a row-level check.
|
|
63
|
+
*
|
|
64
|
+
* Measured 11-12: reading and hashing this repository's 30.6 MB chain takes 14 ms (median, 17 ms worst) — no cache is
|
|
65
|
+
* kept, so nothing the judged workspace writes can stand in for the digest.
|
|
66
|
+
*/
|
|
67
|
+
const crypto = __importStar(require("node:crypto"));
|
|
68
|
+
const fs = __importStar(require("node:fs"));
|
|
69
|
+
const path = __importStar(require("node:path"));
|
|
70
|
+
const sha256 = (b) => crypto.createHash('sha256').update(b).digest('hex');
|
|
71
|
+
/** The digest of an absent chain file: no rows is the empty content. */
|
|
72
|
+
exports.EMPTY_CHAIN_SHA256 = sha256('');
|
|
73
|
+
/** The chain file's place: a `provenance.<replica>.jsonl` (or the legacy `provenance.jsonl`) under `<root>/.ax/ledger`. */
|
|
74
|
+
function chainPlace(chainFile) {
|
|
75
|
+
const abs = path.resolve(chainFile);
|
|
76
|
+
const m = /^provenance(?:\.([^/\\]+))?\.jsonl$/.exec(path.basename(abs));
|
|
77
|
+
const ledgerDir = path.dirname(abs);
|
|
78
|
+
if (m === null || path.basename(ledgerDir) !== 'ledger' || path.basename(path.dirname(ledgerDir)) !== ['.', 'ax'].join(''))
|
|
79
|
+
return null;
|
|
80
|
+
return { root: path.dirname(path.dirname(ledgerDir)), replica: m[1] ?? '' };
|
|
81
|
+
}
|
|
82
|
+
/** The git directory of the checkout `root` is in (the nearest `.git` at or above it; a linked worktree's own). */
|
|
83
|
+
function gitDirOf(root) {
|
|
84
|
+
for (let dir = path.resolve(root);;) {
|
|
85
|
+
const entry = path.join(dir, '.git');
|
|
86
|
+
let st = null;
|
|
87
|
+
try {
|
|
88
|
+
st = fs.lstatSync(entry);
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
st = null;
|
|
92
|
+
} // [no-substitution: no .git here → the parent is asked]
|
|
93
|
+
if (st !== null) {
|
|
94
|
+
if (st.isDirectory())
|
|
95
|
+
return entry;
|
|
96
|
+
if (st.isFile()) {
|
|
97
|
+
try {
|
|
98
|
+
const m = /^gitdir: (.+)$/m.exec(fs.readFileSync(entry, 'utf8'));
|
|
99
|
+
return m ? path.resolve(dir, m[1].trim()) : null;
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
return null;
|
|
103
|
+
} // [no-substitution: an unreadable .git file names no git directory → no witness, closed]
|
|
104
|
+
}
|
|
105
|
+
return null;
|
|
106
|
+
}
|
|
107
|
+
const up = path.dirname(dir);
|
|
108
|
+
if (up === dir)
|
|
109
|
+
return null;
|
|
110
|
+
dir = up;
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
/** Where the witness lives for `root` (the hook refuses a session's write there). */
|
|
114
|
+
function witnessDirOf(root) {
|
|
115
|
+
const g = gitDirOf(root);
|
|
116
|
+
return g === null ? null : path.join(g, 'holmes-kit');
|
|
117
|
+
}
|
|
118
|
+
const witnessFileOf = (root) => {
|
|
119
|
+
const d = witnessDirOf(root);
|
|
120
|
+
return d === null ? null : path.join(d, 'ledger-witness.json');
|
|
121
|
+
};
|
|
122
|
+
function readWitness(root) {
|
|
123
|
+
const f = witnessFileOf(root);
|
|
124
|
+
if (f === null)
|
|
125
|
+
return { state: 'none' };
|
|
126
|
+
let text;
|
|
127
|
+
try {
|
|
128
|
+
text = fs.readFileSync(f, 'utf8');
|
|
129
|
+
}
|
|
130
|
+
catch (e) {
|
|
131
|
+
return e.code === 'ENOENT' ? { state: 'none' } : { state: 'unreadable' }; // [no-substitution: unreadable → closed]
|
|
132
|
+
}
|
|
133
|
+
try {
|
|
134
|
+
const parsed = JSON.parse(text);
|
|
135
|
+
if (parsed?.version !== 1 || typeof parsed.replicas !== 'object' || parsed.replicas === null)
|
|
136
|
+
return { state: 'unreadable' };
|
|
137
|
+
return { state: 'ok', file: parsed };
|
|
138
|
+
}
|
|
139
|
+
catch {
|
|
140
|
+
return { state: 'unreadable' };
|
|
141
|
+
} // [no-substitution: malformed → closed]
|
|
142
|
+
}
|
|
143
|
+
function writeWitness(root, file) {
|
|
144
|
+
const f = witnessFileOf(root);
|
|
145
|
+
if (f === null)
|
|
146
|
+
throw new Error('no git directory for the ledger witness');
|
|
147
|
+
fs.mkdirSync(path.dirname(f), { recursive: true });
|
|
148
|
+
const tmp = `${f}.${process.pid}.${Date.now()}.tmp`;
|
|
149
|
+
fs.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o644 });
|
|
150
|
+
fs.renameSync(tmp, f);
|
|
151
|
+
}
|
|
152
|
+
/** The whole chain file's digest; an absent file is the empty content. Null when it cannot be read. */
|
|
153
|
+
function chainDigest(chainFile) {
|
|
154
|
+
try {
|
|
155
|
+
return sha256(fs.readFileSync(chainFile));
|
|
156
|
+
}
|
|
157
|
+
catch (e) {
|
|
158
|
+
return e.code === 'ENOENT' ? exports.EMPTY_CHAIN_SHA256 : null; // [no-substitution: unreadable → null, closed]
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Before row `next` is written onto `before` (the chain file's content now): when this replica has an entry and the file
|
|
163
|
+
* is its head or its pending one, the entry's pending becomes the row about to be written. Otherwise nothing is written
|
|
164
|
+
* and null is returned — no entry (never created here), or a file the witness does not hold (not laundered).
|
|
165
|
+
*/
|
|
166
|
+
function beforeAppend(chainFile, before, next, line) {
|
|
167
|
+
try {
|
|
168
|
+
const place = chainPlace(chainFile);
|
|
169
|
+
if (place === null)
|
|
170
|
+
return null;
|
|
171
|
+
const read = readWitness(place.root);
|
|
172
|
+
if (read.state !== 'ok')
|
|
173
|
+
return null;
|
|
174
|
+
const entry = read.file.replicas[place.replica];
|
|
175
|
+
if (entry === undefined)
|
|
176
|
+
return null;
|
|
177
|
+
const now = sha256(before);
|
|
178
|
+
let head;
|
|
179
|
+
if (now === entry.sha256)
|
|
180
|
+
head = { seq: entry.seq, hash: entry.hash, sha256: entry.sha256 };
|
|
181
|
+
else if (entry.pending !== undefined && now === entry.pending.sha256)
|
|
182
|
+
head = entry.pending; // an append that died after its row: settled
|
|
183
|
+
else
|
|
184
|
+
return null;
|
|
185
|
+
const pending = { seq: next.seq, hash: next.hash, sha256: sha256(before + line) };
|
|
186
|
+
read.file.replicas[place.replica] = { ...head, ts: new Date().toISOString(), pending };
|
|
187
|
+
writeWitness(place.root, read.file);
|
|
188
|
+
return { root: place.root, replica: place.replica, head: pending };
|
|
189
|
+
}
|
|
190
|
+
catch {
|
|
191
|
+
return null;
|
|
192
|
+
} // [no-substitution: the witness could not be written → the row is kept and the judgement closes]
|
|
193
|
+
}
|
|
194
|
+
/** After the row is written: the pending head becomes the head. */
|
|
195
|
+
function afterAppend(token) {
|
|
196
|
+
if (token === null)
|
|
197
|
+
return;
|
|
198
|
+
try {
|
|
199
|
+
const read = readWitness(token.root);
|
|
200
|
+
if (read.state !== 'ok')
|
|
201
|
+
return;
|
|
202
|
+
read.file.replicas[token.replica] = { ...token.head, ts: new Date().toISOString() };
|
|
203
|
+
writeWitness(token.root, read.file);
|
|
204
|
+
}
|
|
205
|
+
catch { /* [no-substitution: the pending entry stays, and a chain at the pending head is still read] */ }
|
|
206
|
+
}
|
|
207
|
+
/** The rows of a chain text, leniently: seq and hash per line (an unparsable line is null). */
|
|
208
|
+
function rowsOf(text) {
|
|
209
|
+
return text.split('\n').filter((l) => l.trim() !== '').map((l) => {
|
|
210
|
+
try {
|
|
211
|
+
const o = JSON.parse(l);
|
|
212
|
+
return typeof o.seq === 'number' && typeof o.hash === 'string' ? { seq: o.seq, hash: o.hash } : null;
|
|
213
|
+
}
|
|
214
|
+
catch {
|
|
215
|
+
return null;
|
|
216
|
+
} // [no-substitution: an unparsable line is null, which no head matches]
|
|
217
|
+
});
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Whether this replica's chain file is the one this repository wrote. The one computation the judgements and the
|
|
221
|
+
* vouching form read (the form shows this verdict; it does not compute another).
|
|
222
|
+
*/
|
|
223
|
+
function chainWitnessVerdict(chainFile) {
|
|
224
|
+
const place = chainPlace(chainFile);
|
|
225
|
+
if (place === null)
|
|
226
|
+
return { ok: false, kind: 'unreadable', detail: `${chainFile} is not a provenance chain under .ax/ledger` };
|
|
227
|
+
if (gitDirOf(place.root) === null)
|
|
228
|
+
return { ok: false, kind: 'no-repository', detail: `${place.root} is in no git repository, so it has no ledger witness` };
|
|
229
|
+
const read = readWitness(place.root);
|
|
230
|
+
if (read.state === 'unreadable')
|
|
231
|
+
return { ok: false, kind: 'unreadable', detail: `the ledger witness under ${witnessDirOf(place.root)} cannot be read` };
|
|
232
|
+
const entry = read.state === 'ok' ? read.file.replicas[place.replica] : undefined;
|
|
233
|
+
if (entry === undefined) {
|
|
234
|
+
const others = read.state === 'ok' ? Object.keys(read.file.replicas) : [];
|
|
235
|
+
return others.length > 0
|
|
236
|
+
? { ok: false, kind: 'replica-changed', detail: `this repository's witness names the chain of ${others.join(', ')}, not of ${place.replica || '(the legacy chain)'}`, others }
|
|
237
|
+
: { ok: false, kind: 'no-witness', detail: `no person has vouched for this repository's provenance chain (${path.basename(chainFile)}) yet` };
|
|
238
|
+
}
|
|
239
|
+
const witnessed = { seq: entry.seq, hash: entry.hash, sha256: entry.sha256 };
|
|
240
|
+
const now = chainDigest(chainFile);
|
|
241
|
+
if (now === null)
|
|
242
|
+
return { ok: false, kind: 'unreadable', detail: `${chainFile} cannot be read`, witnessed };
|
|
243
|
+
if (now === entry.sha256)
|
|
244
|
+
return { ok: true, head: witnessed };
|
|
245
|
+
if (entry.pending !== undefined && now === entry.pending.sha256)
|
|
246
|
+
return { ok: true, head: entry.pending };
|
|
247
|
+
let text = '';
|
|
248
|
+
try {
|
|
249
|
+
text = fs.readFileSync(chainFile, 'utf8');
|
|
250
|
+
}
|
|
251
|
+
catch { /* [no-substitution: read as empty → taken back, closed] */ }
|
|
252
|
+
const rows = rowsOf(text);
|
|
253
|
+
const at = entry.seq >= 0 ? rows[entry.seq] : undefined;
|
|
254
|
+
if (entry.seq >= 0 && (at === undefined || at === null || at.hash !== entry.hash)) {
|
|
255
|
+
return { ok: false, kind: 'taken-back', detail: `the chain holds ${rows.length} row(s); this repository last wrote it at row ${entry.seq + 1} (${entry.hash.slice(0, 12)}), which it no longer holds as written — it was taken back (a checkout, a stash, a reset) or rewritten`, witnessed };
|
|
256
|
+
}
|
|
257
|
+
if (rows.length > entry.seq + 1) {
|
|
258
|
+
return { ok: false, kind: 'extended', detail: `rows ${entry.seq + 2}–${rows.length} of the chain were not written in this repository (it last wrote row ${entry.seq + 1})`, witnessed };
|
|
259
|
+
}
|
|
260
|
+
return { ok: false, kind: 'broken', detail: 'the chain file differs from the one this repository wrote, row for row the same length', witnessed };
|
|
261
|
+
}
|
|
262
|
+
/**
|
|
263
|
+
* The person's act (cli/ledger-witness.ts, after a grant): the witness of this replica becomes the chain file as it is.
|
|
264
|
+
* `expected` is the head the request showed the person; a chain that moved since is not vouched for.
|
|
265
|
+
*/
|
|
266
|
+
function vouch(chainFile, expected) {
|
|
267
|
+
const place = chainPlace(chainFile);
|
|
268
|
+
if (place === null)
|
|
269
|
+
throw new Error(`${chainFile} is not a provenance chain under .ax/ledger`);
|
|
270
|
+
if (gitDirOf(place.root) === null)
|
|
271
|
+
throw new Error(`${place.root} is in no git repository`);
|
|
272
|
+
const head = currentHead(chainFile);
|
|
273
|
+
if (expected !== undefined && head.sha256 !== expected.sha256)
|
|
274
|
+
throw new Error('the chain changed since the request was filed — file a new one');
|
|
275
|
+
const read = readWitness(place.root);
|
|
276
|
+
const file = read.state === 'ok' ? read.file : { version: 1, replicas: {} };
|
|
277
|
+
file.replicas[place.replica] = { ...head, ts: new Date().toISOString() };
|
|
278
|
+
writeWitness(place.root, file);
|
|
279
|
+
return head;
|
|
280
|
+
}
|
|
281
|
+
/** The chain file's head as it is now: its last row's seq and hash (-1 and GENESIS when empty) and the whole digest. */
|
|
282
|
+
function currentHead(chainFile) {
|
|
283
|
+
const sha = chainDigest(chainFile);
|
|
284
|
+
if (sha === null)
|
|
285
|
+
throw new Error(`${chainFile} cannot be read`);
|
|
286
|
+
let text = '';
|
|
287
|
+
try {
|
|
288
|
+
text = fs.readFileSync(chainFile, 'utf8');
|
|
289
|
+
}
|
|
290
|
+
catch { /* [no-substitution: absent is the empty content, as its digest says] */ }
|
|
291
|
+
const rows = rowsOf(text);
|
|
292
|
+
const last = rows[rows.length - 1];
|
|
293
|
+
if (rows.length > 0 && (last === null || last === undefined))
|
|
294
|
+
throw new Error(`the last row of ${chainFile} cannot be read`);
|
|
295
|
+
return rows.length === 0 ? { seq: -1, hash: 'GENESIS', sha256: sha } : { seq: last.seq, hash: last.hash, sha256: sha };
|
|
296
|
+
}
|
|
@@ -156,7 +156,14 @@ export declare class ProvenanceChain {
|
|
|
156
156
|
* `append()` from there would deadlock against its own budget.
|
|
157
157
|
*/
|
|
158
158
|
appendInsideLock(body: AppendBody): ProvenanceEvent;
|
|
159
|
-
/**
|
|
159
|
+
/**
|
|
160
|
+
* The append itself, assuming exclusion is already held. Only callers INSIDE a hold may use it.
|
|
161
|
+
*
|
|
162
|
+
* @implements A-SPEC-794.115 — the chain's one write point, so the ledger witness of A-SPEC-794.114 moves here and
|
|
163
|
+
* nowhere else: every append, the grant spend (`consumeNonceExclusively` appends inside its own hold) and the
|
|
164
|
+
* stale-lock record. The witness's pending entry is written before the row, its head after; the witness module decides
|
|
165
|
+
* whether to move at all (it never creates an entry, and never moves one the current file does not match).
|
|
166
|
+
*/
|
|
160
167
|
private appendUnlocked;
|
|
161
168
|
/**
|
|
162
169
|
* Records a broken stale hold into the chain itself. Bound so it can be handed to the lock layer,
|