@adamchanadam/agent-handoff-kit 0.3.53 → 0.3.54
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/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +3885 -6845
- package/bin/installed-file-contract.mjs +11 -11
- package/bin/migration-baselines/official-origin-catalog.json +191 -1
- package/bin/upgrade-inventory.mjs +7 -358
- package/package.json +1 -1
- package/runtime-core/PROJECT_INDEX.md +1 -1
|
@@ -1,13 +1,10 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { lstat, readdir, readFile, realpath } from "node:fs/promises";
|
|
3
3
|
import path from "node:path";
|
|
4
|
-
import { installedFileContracts
|
|
5
|
-
import { loadOfficialOriginCatalog } from "./official-origin-catalog.mjs";
|
|
4
|
+
import { installedFileContracts } from "./installed-file-contract.mjs";
|
|
6
5
|
import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
|
|
7
6
|
|
|
8
|
-
export const UPGRADE_INVENTORY_SCHEMA = 1;
|
|
9
|
-
export const GATE5_FROZEN_SET_SCHEMA = 2;
|
|
10
|
-
export const GATE5_ROOT_SOURCE_INVENTORY_SCHEMA = 1;
|
|
7
|
+
export const UPGRADE_INVENTORY_SCHEMA = 1;
|
|
11
8
|
|
|
12
9
|
const formalEntryTargets = Object.freeze([
|
|
13
10
|
"AGENTS.md",
|
|
@@ -16,28 +13,16 @@ const formalEntryTargets = Object.freeze([
|
|
|
16
13
|
"START_NEXT_SESSION_PROMPT.txt"
|
|
17
14
|
]);
|
|
18
15
|
|
|
19
|
-
const transactionRegistryRoot = "dev/governance_migrations";
|
|
20
|
-
|
|
21
16
|
const archiveDirectories = Object.freeze([
|
|
22
17
|
{ relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
|
|
23
18
|
{ relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
|
|
24
19
|
]);
|
|
25
20
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
export function gate5SourceConservationItems(frozen) {
|
|
32
|
-
return Object.freeze((frozen?.items ?? []).filter(gate5ItemRequiresSourceConservation));
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
* Builds a read-only, hash-bound description of the Kit data that an upgrade
|
|
37
|
-
* can reach. It deliberately records whole source files before any semantic
|
|
38
|
-
* candidate tries to divide or merge their contents: a heading, language, or
|
|
39
|
-
* layout is never treated as ownership evidence.
|
|
40
|
-
*/
|
|
21
|
+
/**
|
|
22
|
+
* Builds a read-only, hash-bound description of the Kit data that an upgrade
|
|
23
|
+
* can reach now. Ordinary workspace files, generic Markdown references, and
|
|
24
|
+
* committed historical transaction receipts are not current upgrade authority.
|
|
25
|
+
*/
|
|
41
26
|
export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
|
|
42
27
|
if (!root) throw new Error("upgrade inventory requires a project root");
|
|
43
28
|
const rootPath = path.resolve(root);
|
|
@@ -114,8 +99,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
|
|
|
114
99
|
);
|
|
115
100
|
}
|
|
116
101
|
|
|
117
|
-
await addTransactionRegistry(transactionRegistryRoot);
|
|
118
|
-
|
|
119
102
|
for (const directory of archiveDirectories) {
|
|
120
103
|
await addTree(directory.relative, directory.classification);
|
|
121
104
|
}
|
|
@@ -159,49 +142,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
|
|
|
159
142
|
formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
|
|
160
143
|
});
|
|
161
144
|
|
|
162
|
-
async function addTransactionRegistry(relativeDirectory) {
|
|
163
|
-
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
164
|
-
if (!normalized) {
|
|
165
|
-
addBlocker(String(relativeDirectory), "transaction registry escapes the selected project root");
|
|
166
|
-
return;
|
|
167
|
-
}
|
|
168
|
-
const absolute = path.resolve(rootPath, normalized);
|
|
169
|
-
const stats = await lstat(absolute).catch((error) => {
|
|
170
|
-
if (error?.code === "ENOENT") return null;
|
|
171
|
-
throw error;
|
|
172
|
-
});
|
|
173
|
-
if (!stats) return;
|
|
174
|
-
if (!stats.isDirectory() || stats.isSymbolicLink()) {
|
|
175
|
-
addBlocker(normalized, "transaction registry is not a safe real directory");
|
|
176
|
-
return;
|
|
177
|
-
}
|
|
178
|
-
const resolved = await realpath(absolute);
|
|
179
|
-
if (!isInside(realRoot, resolved)) {
|
|
180
|
-
addBlocker(normalized, "transaction registry resolves outside the selected project root");
|
|
181
|
-
return;
|
|
182
|
-
}
|
|
183
|
-
for (const item of await readdir(absolute, { withFileTypes: true })) {
|
|
184
|
-
const child = `${normalized}/${item.name}`;
|
|
185
|
-
const childAbsolute = path.join(absolute, item.name);
|
|
186
|
-
const childStats = await lstat(childAbsolute).catch((error) => {
|
|
187
|
-
if (error?.code === "ENOENT") return null;
|
|
188
|
-
throw error;
|
|
189
|
-
});
|
|
190
|
-
if (!childStats) continue;
|
|
191
|
-
if (childStats.isFile()) continue;
|
|
192
|
-
if (childStats.isSymbolicLink() || !childStats.isDirectory()) {
|
|
193
|
-
addBlocker(child, "transaction registry child is not a safe real directory");
|
|
194
|
-
continue;
|
|
195
|
-
}
|
|
196
|
-
const childResolved = await realpath(childAbsolute);
|
|
197
|
-
if (!isInside(realRoot, childResolved)) {
|
|
198
|
-
addBlocker(child, "transaction registry child resolves outside the selected project root");
|
|
199
|
-
continue;
|
|
200
|
-
}
|
|
201
|
-
await addFile(`${child}/transaction.json`, "transaction-state", { from: "transaction-registry", via: normalized });
|
|
202
|
-
}
|
|
203
|
-
}
|
|
204
|
-
|
|
205
145
|
async function addTree(relativeDirectory, classification) {
|
|
206
146
|
const normalized = normalizeProjectRelative(relativeDirectory);
|
|
207
147
|
if (!normalized) {
|
|
@@ -244,297 +184,6 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
|
|
|
244
184
|
}
|
|
245
185
|
}
|
|
246
186
|
|
|
247
|
-
/**
|
|
248
|
-
* Gate 5 current scope is the typed reachable inventory. It deliberately does
|
|
249
|
-
* not walk the project root: ordinary files outside installed/runtime/formal
|
|
250
|
-
* user-rule/transaction/archive contracts are outside machine authority.
|
|
251
|
-
*/
|
|
252
|
-
export async function buildGate5RootSourceInventory({ root, reachableInventory } = {}) {
|
|
253
|
-
if (!root) throw new Error("Gate 5 root-source inventory requires a project root");
|
|
254
|
-
if (!reachableInventory || reachableInventory.schemaVersion !== UPGRADE_INVENTORY_SCHEMA) {
|
|
255
|
-
throw new Error("Gate 5 root-source inventory requires the current reachable inventory");
|
|
256
|
-
}
|
|
257
|
-
const rootPath = path.resolve(root);
|
|
258
|
-
const rootStats = await lstat(rootPath).catch((error) => {
|
|
259
|
-
if (error?.code === "ENOENT") return null;
|
|
260
|
-
throw error;
|
|
261
|
-
});
|
|
262
|
-
if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
|
|
263
|
-
throw new Error("Gate 5 root-source inventory root must be a real directory");
|
|
264
|
-
}
|
|
265
|
-
const entries = new Map();
|
|
266
|
-
const blockers = [...reachableInventory.blockers];
|
|
267
|
-
|
|
268
|
-
for (const reachable of reachableInventory.entries) {
|
|
269
|
-
const classifications = reachable.classifications ?? [];
|
|
270
|
-
const reachability = reachable.reachability ?? [];
|
|
271
|
-
entries.set(reachable.path, Object.freeze({
|
|
272
|
-
path: reachable.path,
|
|
273
|
-
sha256: reachable.sha256,
|
|
274
|
-
bytes: reachable.bytes,
|
|
275
|
-
classifications: Object.freeze(["root-source", ...classifications].sort()),
|
|
276
|
-
reachability: Object.freeze([...reachability]
|
|
277
|
-
.sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`)))
|
|
278
|
-
}));
|
|
279
|
-
}
|
|
280
|
-
const frozenEntries = [...entries.values()].sort((left, right) => left.path.localeCompare(right.path));
|
|
281
|
-
const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
|
|
282
|
-
const body = {
|
|
283
|
-
schemaVersion: GATE5_ROOT_SOURCE_INVENTORY_SCHEMA,
|
|
284
|
-
entries: frozenEntries,
|
|
285
|
-
blockers: sortedBlockers
|
|
286
|
-
};
|
|
287
|
-
return Object.freeze({
|
|
288
|
-
...body,
|
|
289
|
-
status: sortedBlockers.length === 0 ? "ready" : "blocked",
|
|
290
|
-
rootSourceSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8"))
|
|
291
|
-
});
|
|
292
|
-
}
|
|
293
|
-
|
|
294
|
-
/**
|
|
295
|
-
* Freezes the complete set that a Gate 5 upgrade may reason about before any
|
|
296
|
-
* candidate, transaction, or semantic disposition is attempted. This is not
|
|
297
|
-
* an activation record and grants no write authority: it binds every reached
|
|
298
|
-
* project source's raw bytes to the installed package contract, formal
|
|
299
|
-
* historical source, transaction/registry surface, bridges, router, and
|
|
300
|
-
* formal entry.
|
|
301
|
-
*/
|
|
302
|
-
export async function freezeGate5Set({ root, contracts = installedFileContracts, transitionContracts = upgradeStateFileContracts, catalog = null } = {}) {
|
|
303
|
-
const inventory = await buildUpgradeInventory({ root, contracts });
|
|
304
|
-
if (inventory.status !== "ready") throw new Error("Gate 5 frozen set requires a ready reachable inventory");
|
|
305
|
-
const rootSourceInventory = await buildGate5RootSourceInventory({ root, reachableInventory: inventory });
|
|
306
|
-
if (rootSourceInventory.status !== "ready") throw new Error("Gate 5 frozen set requires a complete safe root-source inventory");
|
|
307
|
-
const rootPath = path.resolve(root);
|
|
308
|
-
const officialCatalog = catalog ?? await loadOfficialOriginCatalog();
|
|
309
|
-
const packageContracts = normalizeContracts(contracts, transitionContracts);
|
|
310
|
-
const contractByTarget = new Map(packageContracts.map((contract) => [contract.targetRel, contract]));
|
|
311
|
-
const contractBody = {
|
|
312
|
-
schemaVersion: INSTALLED_FILE_CONTRACT_SCHEMA,
|
|
313
|
-
installed: contracts.map(({ sourceRel, targetRel, strategy }) => ({ sourceRel, targetRel, strategy })),
|
|
314
|
-
transition: transitionContracts.map(({ sourceRel, targetRel, strategy }) => ({ sourceRel, targetRel, strategy }))
|
|
315
|
-
};
|
|
316
|
-
const contractDigestSha256 = sha256(Buffer.from(`${JSON.stringify(contractBody)}\n`, "utf8"));
|
|
317
|
-
const installedTemplateVersion = await readProjectIndexTemplateVersion(rootPath);
|
|
318
|
-
const release = installedTemplateVersion ? officialCatalog.releases?.[installedTemplateVersion] : null;
|
|
319
|
-
const entryByPath = new Map(rootSourceInventory.entries.map((entry) => [entry.path, entry]));
|
|
320
|
-
const items = rootSourceInventory.entries.map((entry) => {
|
|
321
|
-
const contract = contractByTarget.get(entry.path) ?? null;
|
|
322
|
-
const historicalEntry = contract && release?.manifest?.[entry.path]?.state === "present"
|
|
323
|
-
? release.manifest[entry.path]
|
|
324
|
-
: null;
|
|
325
|
-
const exactPackageBytes = Boolean(historicalEntry && entry.sha256 === historicalEntry.rawSha256);
|
|
326
|
-
const discoveredReachability = entry.reachability.map(({ from, via }) => ({ reader: from, via }));
|
|
327
|
-
const readers = discoveredReachability.filter(({ reader }) => isFormalReader(reader));
|
|
328
|
-
const kitReachable = entry.classifications.some((classification) => classification !== "root-source");
|
|
329
|
-
const unresolvedReason = !kitReachable
|
|
330
|
-
? null
|
|
331
|
-
: !exactPackageBytes
|
|
332
|
-
? "non-exact-or-unknown bytes require a verified preserve destination or remain unresolved"
|
|
333
|
-
: readers.length === 0
|
|
334
|
-
? "no verified existing reader; priority and effect remain unresolved"
|
|
335
|
-
: "reader is recorded, but priority/conflict and runtime effect remain unresolved before a per-item transaction proof";
|
|
336
|
-
return Object.freeze({
|
|
337
|
-
sourcePath: entry.path,
|
|
338
|
-
sourceIdentity: Object.freeze({ sha256: entry.sha256, bytes: entry.bytes }),
|
|
339
|
-
classifications: Object.freeze([...entry.classifications]),
|
|
340
|
-
existingReaders: Object.freeze(readers),
|
|
341
|
-
discoveredReachability: Object.freeze(discoveredReachability),
|
|
342
|
-
priorityConflict: Object.freeze({
|
|
343
|
-
status: kitReachable ? "unresolved-before-runtime-validation" : "not-applicable-outside-known-kit-reachability",
|
|
344
|
-
relation: !kitReachable ? "outside-known-kit-reachability" : readers.length > 0 ? "reader-reachable-priority-not-proven" : "no-verified-reader"
|
|
345
|
-
}),
|
|
346
|
-
effect: Object.freeze({
|
|
347
|
-
status: kitReachable ? "unresolved-before-runtime-validation" : "not-applicable-outside-known-kit-reachability",
|
|
348
|
-
decision: !kitReachable ? "outside-known-kit-reachability" : readers.length > 0 ? "preserve-existing-route-or-stop" : "unresolved"
|
|
349
|
-
}),
|
|
350
|
-
packageContract: contract
|
|
351
|
-
? Object.freeze({ sourceRel: contract.sourceRel, targetRel: contract.targetRel, strategy: contract.strategy, scope: contract.scope })
|
|
352
|
-
: null,
|
|
353
|
-
historicalOrigin: historicalEntry
|
|
354
|
-
? Object.freeze({
|
|
355
|
-
packageIdentity: release.source.npm.spec,
|
|
356
|
-
installedTemplateVersion,
|
|
357
|
-
rawSha256: historicalEntry.rawSha256,
|
|
358
|
-
exactPackageBytes,
|
|
359
|
-
catalogDigestSha256: officialCatalog.catalogDigestSha256
|
|
360
|
-
})
|
|
361
|
-
: null,
|
|
362
|
-
ownership: exactPackageBytes && contract?.scope === "installed"
|
|
363
|
-
? "kit-managed-exact"
|
|
364
|
-
: "user-or-unknown",
|
|
365
|
-
unresolvedReason
|
|
366
|
-
});
|
|
367
|
-
});
|
|
368
|
-
const contractCoverage = packageContracts.map((contract) => {
|
|
369
|
-
const source = entryByPath.get(contract.targetRel) ?? null;
|
|
370
|
-
const historicalState = release?.manifest?.[contract.targetRel]?.state ?? "unavailable";
|
|
371
|
-
const status = source
|
|
372
|
-
? "source-frozen"
|
|
373
|
-
: historicalState === "absent"
|
|
374
|
-
? "not-present-in-historical-package"
|
|
375
|
-
: contract.scope === "transition"
|
|
376
|
-
? "not-present-no-formal-transition-state"
|
|
377
|
-
: "unresolved-missing-installed-source";
|
|
378
|
-
return Object.freeze({
|
|
379
|
-
sourceRel: contract.sourceRel,
|
|
380
|
-
targetRel: contract.targetRel,
|
|
381
|
-
strategy: contract.strategy,
|
|
382
|
-
scope: contract.scope,
|
|
383
|
-
sourceStatus: status,
|
|
384
|
-
sourceIdentity: source ? Object.freeze({ sha256: source.sha256, bytes: source.bytes }) : null,
|
|
385
|
-
historicalState
|
|
386
|
-
});
|
|
387
|
-
});
|
|
388
|
-
const unresolvedItems = items
|
|
389
|
-
.filter((item) => item.unresolvedReason)
|
|
390
|
-
.map((item) => Object.freeze({ sourcePath: item.sourcePath, reason: item.unresolvedReason }));
|
|
391
|
-
const unresolvedContractTargets = contractCoverage
|
|
392
|
-
.filter((item) => item.sourceStatus === "unresolved-missing-installed-source")
|
|
393
|
-
.map((item) => Object.freeze({ sourcePath: item.targetRel, reason: "installed package target is missing from the root-source set" }));
|
|
394
|
-
const bridgePaths = ["CLAUDE.md", "GEMINI.md"];
|
|
395
|
-
const sourceConservationPaths = items
|
|
396
|
-
.filter(gate5ItemRequiresSourceConservation)
|
|
397
|
-
.map((item) => item.sourcePath);
|
|
398
|
-
const body = {
|
|
399
|
-
schemaVersion: GATE5_FROZEN_SET_SCHEMA,
|
|
400
|
-
operationAuthority: "none",
|
|
401
|
-
activationStatus: "not-authorized",
|
|
402
|
-
inventory: Object.freeze({ schemaVersion: inventory.schemaVersion, sha256: inventory.inventorySha256 }),
|
|
403
|
-
rootSourceInventory: Object.freeze({
|
|
404
|
-
schemaVersion: rootSourceInventory.schemaVersion,
|
|
405
|
-
sha256: rootSourceInventory.rootSourceSha256,
|
|
406
|
-
entryCount: rootSourceInventory.entries.length
|
|
407
|
-
}),
|
|
408
|
-
packageContract: Object.freeze({
|
|
409
|
-
schemaVersion: INSTALLED_FILE_CONTRACT_SCHEMA,
|
|
410
|
-
digestSha256: contractDigestSha256,
|
|
411
|
-
installedTargets: Object.freeze(contracts.map(({ targetRel }) => targetRel)),
|
|
412
|
-
transitionTargets: Object.freeze(transitionContracts.map(({ targetRel }) => targetRel)),
|
|
413
|
-
coverage: Object.freeze(contractCoverage)
|
|
414
|
-
}),
|
|
415
|
-
historicalSource: Object.freeze({
|
|
416
|
-
catalogSchemaVersion: officialCatalog.schemaVersion,
|
|
417
|
-
catalogDigestSha256: officialCatalog.catalogDigestSha256,
|
|
418
|
-
installedTemplateVersion,
|
|
419
|
-
packageIdentity: release?.source?.npm?.spec ?? null,
|
|
420
|
-
packageIntegrity: release?.source?.npm?.integrity ?? null,
|
|
421
|
-
status: release ? "bound-to-installed-catalog-identity" : "unresolved-no-catalog-release-for-installed-version"
|
|
422
|
-
}),
|
|
423
|
-
formalSurfaces: Object.freeze({
|
|
424
|
-
entry: binding(entryByPath, "AGENTS.md"),
|
|
425
|
-
bridges: Object.freeze(bridgePaths.map((targetRel) => binding(entryByPath, targetRel))),
|
|
426
|
-
router: binding(entryByPath, "dev/USER_RULES.md"),
|
|
427
|
-
transactionRegistry: Object.freeze({
|
|
428
|
-
root: "dev/governance_migrations",
|
|
429
|
-
entries: Object.freeze(items.filter((item) => item.classifications.includes("transaction-state")).map((item) => item.sourcePath))
|
|
430
|
-
})
|
|
431
|
-
}),
|
|
432
|
-
sourceConservation: Object.freeze({
|
|
433
|
-
selection: "known-kit-reachability",
|
|
434
|
-
protectedEntryCount: sourceConservationPaths.length,
|
|
435
|
-
sourcePaths: Object.freeze(sourceConservationPaths)
|
|
436
|
-
}),
|
|
437
|
-
items: Object.freeze(items),
|
|
438
|
-
unresolved: Object.freeze([...unresolvedItems, ...unresolvedContractTargets]
|
|
439
|
-
.sort((left, right) => `${left.sourcePath}\0${left.reason}`.localeCompare(`${right.sourcePath}\0${right.reason}`)))
|
|
440
|
-
};
|
|
441
|
-
return Object.freeze({ ...body, frozenSetSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) });
|
|
442
|
-
}
|
|
443
|
-
|
|
444
|
-
export function assertGate5FrozenSet(frozen) {
|
|
445
|
-
if (!frozen || typeof frozen !== "object" || Array.isArray(frozen)) throw new Error("Gate 5 frozen set is required");
|
|
446
|
-
if (frozen.schemaVersion !== GATE5_FROZEN_SET_SCHEMA) throw new Error("unsupported Gate 5 frozen-set schema");
|
|
447
|
-
if (frozen.operationAuthority !== "none" || frozen.activationStatus !== "not-authorized") throw new Error("Gate 5 frozen set must not claim operation authority");
|
|
448
|
-
if (!Array.isArray(frozen.items) || frozen.items.length === 0) throw new Error("Gate 5 frozen set has no items");
|
|
449
|
-
if (!frozen.rootSourceInventory || frozen.rootSourceInventory.schemaVersion !== GATE5_ROOT_SOURCE_INVENTORY_SCHEMA
|
|
450
|
-
|| !/^[0-9a-f]{64}$/.test(frozen.rootSourceInventory.sha256)
|
|
451
|
-
|| !Number.isInteger(frozen.rootSourceInventory.entryCount) || frozen.rootSourceInventory.entryCount !== frozen.items.length) {
|
|
452
|
-
throw new Error("Gate 5 frozen set does not bind its scoped typed source inventory");
|
|
453
|
-
}
|
|
454
|
-
if (!frozen.packageContract || !Array.isArray(frozen.packageContract.coverage)) {
|
|
455
|
-
throw new Error("Gate 5 frozen set does not bind package-contract coverage");
|
|
456
|
-
}
|
|
457
|
-
if (!frozen.sourceConservation || frozen.sourceConservation.selection !== "known-kit-reachability"
|
|
458
|
-
|| !Number.isInteger(frozen.sourceConservation.protectedEntryCount)
|
|
459
|
-
|| !Array.isArray(frozen.sourceConservation.sourcePaths)) {
|
|
460
|
-
throw new Error("Gate 5 frozen set does not define its current-state source-conservation selection");
|
|
461
|
-
}
|
|
462
|
-
const paths = new Set();
|
|
463
|
-
const orderedPaths = [];
|
|
464
|
-
for (const item of frozen.items) {
|
|
465
|
-
if (!item || typeof item !== "object" || typeof item.sourcePath !== "string" || paths.has(item.sourcePath)) throw new Error("Gate 5 frozen set has duplicate or invalid source paths");
|
|
466
|
-
paths.add(item.sourcePath);
|
|
467
|
-
orderedPaths.push(item.sourcePath);
|
|
468
|
-
if (!/^[0-9a-f]{64}$/.test(item.sourceIdentity?.sha256) || !Number.isInteger(item.sourceIdentity?.bytes) || item.sourceIdentity.bytes < 0) throw new Error(`Gate 5 frozen set source identity is invalid: ${item.sourcePath}`);
|
|
469
|
-
if (!Array.isArray(item.classifications) || !item.classifications.includes("root-source")
|
|
470
|
-
|| !Array.isArray(item.existingReaders) || !item.priorityConflict?.status || !item.effect?.status
|
|
471
|
-
|| !(item.unresolvedReason === null || typeof item.unresolvedReason === "string")) {
|
|
472
|
-
throw new Error(`Gate 5 frozen set omits root-source, reader, priority/conflict, or effect record: ${item.sourcePath}`);
|
|
473
|
-
}
|
|
474
|
-
if (!item.historicalOrigin && item.ownership !== "user-or-unknown") throw new Error(`Gate 5 frozen set assigns ownership without historical evidence: ${item.sourcePath}`);
|
|
475
|
-
if (item.historicalOrigin?.exactPackageBytes && item.packageContract?.scope === "installed" && item.ownership !== "kit-managed-exact") throw new Error(`Gate 5 frozen set rejects exact managed ownership: ${item.sourcePath}`);
|
|
476
|
-
if (item.historicalOrigin && !item.historicalOrigin.exactPackageBytes && item.ownership !== "user-or-unknown") throw new Error(`Gate 5 frozen set accepts non-exact package bytes: ${item.sourcePath}`);
|
|
477
|
-
}
|
|
478
|
-
const expectedUnresolved = frozen.items
|
|
479
|
-
.filter((item) => item.unresolvedReason)
|
|
480
|
-
.map((item) => `${item.sourcePath}\0${item.unresolvedReason}`);
|
|
481
|
-
const actualUnresolved = frozen.unresolved?.map((item) => `${item.sourcePath}\0${item.reason}`) ?? [];
|
|
482
|
-
for (const coverage of frozen.packageContract.coverage) {
|
|
483
|
-
if (!coverage || typeof coverage.targetRel !== "string" || typeof coverage.sourceStatus !== "string") {
|
|
484
|
-
throw new Error("Gate 5 frozen set package-contract coverage is invalid");
|
|
485
|
-
}
|
|
486
|
-
if (coverage.sourceStatus === "unresolved-missing-installed-source") {
|
|
487
|
-
expectedUnresolved.push(`${coverage.targetRel}\0installed package target is missing from the root-source set`);
|
|
488
|
-
}
|
|
489
|
-
}
|
|
490
|
-
const expectedSourceConservationPaths = frozen.items
|
|
491
|
-
.filter(gate5ItemRequiresSourceConservation)
|
|
492
|
-
.map((item) => item.sourcePath);
|
|
493
|
-
if (frozen.sourceConservation.protectedEntryCount !== expectedSourceConservationPaths.length
|
|
494
|
-
|| JSON.stringify(frozen.sourceConservation.sourcePaths) !== JSON.stringify(expectedSourceConservationPaths)) {
|
|
495
|
-
throw new Error("Gate 5 frozen set source-conservation selection does not match known Kit reachability");
|
|
496
|
-
}
|
|
497
|
-
if (JSON.stringify(orderedPaths) !== JSON.stringify([...orderedPaths].sort((left, right) => left.localeCompare(right)))) {
|
|
498
|
-
throw new Error("Gate 5 frozen set items are not in canonical source-path order");
|
|
499
|
-
}
|
|
500
|
-
if (JSON.stringify(actualUnresolved) !== JSON.stringify([...actualUnresolved].sort((left, right) => left.localeCompare(right)))) {
|
|
501
|
-
throw new Error("Gate 5 frozen set unresolved list is not in canonical order");
|
|
502
|
-
}
|
|
503
|
-
if (JSON.stringify(actualUnresolved) !== JSON.stringify([...expectedUnresolved].sort((left, right) => left.localeCompare(right)))) {
|
|
504
|
-
throw new Error("Gate 5 frozen set unresolved list does not exactly match item states");
|
|
505
|
-
}
|
|
506
|
-
const { frozenSetSha256, ...body } = frozen;
|
|
507
|
-
if (frozenSetSha256 !== sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8"))) throw new Error("Gate 5 frozen-set digest does not match its contents");
|
|
508
|
-
return true;
|
|
509
|
-
}
|
|
510
|
-
|
|
511
|
-
function normalizeContracts(contracts, transitionContracts) {
|
|
512
|
-
const seen = new Set();
|
|
513
|
-
const all = [];
|
|
514
|
-
for (const [scope, source] of [["installed", contracts], ["transition", transitionContracts]]) {
|
|
515
|
-
for (const contract of source) {
|
|
516
|
-
if (seen.has(contract.targetRel)) continue;
|
|
517
|
-
seen.add(contract.targetRel);
|
|
518
|
-
all.push(Object.freeze({ ...contract, scope }));
|
|
519
|
-
}
|
|
520
|
-
}
|
|
521
|
-
return all;
|
|
522
|
-
}
|
|
523
|
-
|
|
524
|
-
function binding(entryByPath, targetRel) {
|
|
525
|
-
const entry = entryByPath.get(targetRel);
|
|
526
|
-
return Object.freeze({
|
|
527
|
-
path: targetRel,
|
|
528
|
-
present: Boolean(entry),
|
|
529
|
-
sourceIdentity: entry ? Object.freeze({ sha256: entry.sha256, bytes: entry.bytes }) : null,
|
|
530
|
-
readers: entry ? Object.freeze(entry.reachability.map(({ from, via }) => ({ reader: from, via })).filter(({ reader }) => isFormalReader(reader))) : Object.freeze([])
|
|
531
|
-
});
|
|
532
|
-
}
|
|
533
|
-
|
|
534
|
-
function isFormalReader(reader) {
|
|
535
|
-
return reader === "formal-entry" || !["managed-contract", "legacy-location", "dynamic-state"].includes(reader);
|
|
536
|
-
}
|
|
537
|
-
|
|
538
187
|
export async function readProjectIndexTemplateVersion(root) {
|
|
539
188
|
const bytes = await readFile(path.join(root, "dev", "PROJECT_INDEX.md")).catch((error) => {
|
|
540
189
|
if (error?.code === "ENOENT") return null;
|
package/package.json
CHANGED
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.3.
|
|
9
|
+
| Agent Handoff Kit template version | 0.3.54 | current template version |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|