@sema-agent/core 7.64.0 → 7.65.0

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 (103) hide show
  1. package/CHANGELOG.md +317 -0
  2. package/dist/agents/peer-held-queue.js +1 -1
  3. package/dist/agents/peer-idle.js +1 -1
  4. package/dist/agents/peer-session-drain.js +3 -3
  5. package/dist/agents/subagent.js +5 -2
  6. package/dist/core/auto-promote.d.ts +3 -2
  7. package/dist/core/background-agent-store.d.ts +7 -0
  8. package/dist/core/checkpoint-store.d.ts +2 -3
  9. package/dist/core/context-settings.d.ts +1 -2
  10. package/dist/core/context-settings.js +1 -1
  11. package/dist/core/engine-attestation.d.ts +2 -2
  12. package/dist/core/engine-notice.d.ts +13 -1
  13. package/dist/core/engine-notice.js +3 -1
  14. package/dist/core/file-history-store.d.ts +2 -2
  15. package/dist/core/file-history-store.js +0 -4
  16. package/dist/core/gate-fold.js +3 -1
  17. package/dist/core/governance-codes.d.ts +6 -4
  18. package/dist/core/governance-codes.js +4 -3
  19. package/dist/core/leg-identity.d.ts +18 -2
  20. package/dist/core/leg-identity.js +5 -7
  21. package/dist/core/mailbox-store.d.ts +1 -1
  22. package/dist/core/memory-engine/consolidation.d.ts +10 -4
  23. package/dist/core/memory-engine/consolidation.js +11 -1
  24. package/dist/core/memory-engine/control-objects.d.ts +36 -3
  25. package/dist/core/memory-engine/control-objects.js +134 -12
  26. package/dist/core/memory-engine/control-plane-adoption.d.ts +5 -2
  27. package/dist/core/memory-engine/control-plane-adoption.js +5 -3
  28. package/dist/core/memory-engine/delegation-settlement.d.ts +59 -42
  29. package/dist/core/memory-engine/delegation-settlement.js +175 -202
  30. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  31. package/dist/core/memory-engine/dual-root.js +5 -1
  32. package/dist/core/memory-engine/engine.d.ts +16 -10
  33. package/dist/core/memory-engine/engine.js +138 -145
  34. package/dist/core/memory-engine/file-backend.d.ts +17 -11
  35. package/dist/core/memory-engine/file-backend.js +53 -103
  36. package/dist/core/memory-engine/layout.d.ts +129 -49
  37. package/dist/core/memory-engine/layout.js +202 -82
  38. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  39. package/dist/core/memory-engine/memory-age.js +17 -0
  40. package/dist/core/memory-engine/memory-backend-contract.js +5 -4
  41. package/dist/core/memory-engine/memory-deployment.d.ts +1 -1
  42. package/dist/core/memory-engine/origin-clearance.js +1 -5
  43. package/dist/core/memory-engine/tools.d.ts +2 -2
  44. package/dist/core/memory-engine/tools.js +7 -7
  45. package/dist/core/memory-engine/types.d.ts +16 -10
  46. package/dist/core/memory-vector.d.ts +6 -14
  47. package/dist/core/memory.d.ts +0 -462
  48. package/dist/core/memory.js +0 -333
  49. package/dist/core/permission-rule-consent.d.ts +49 -18
  50. package/dist/core/permission-rule-consent.js +59 -38
  51. package/dist/core/permission-rule-store.d.ts +24 -14
  52. package/dist/core/retention.d.ts +2 -7
  53. package/dist/core/retention.js +0 -1
  54. package/dist/core/runner/classifier-ladder.d.ts +3 -1
  55. package/dist/core/runner/classifier-ladder.js +2 -2
  56. package/dist/core/runner/contracts.d.ts +9 -9
  57. package/dist/core/runner/delegation-owner.d.ts +0 -8
  58. package/dist/core/runner/delegation-owner.js +1 -3
  59. package/dist/core/runner/prepare-gate-stations.d.ts +8 -5
  60. package/dist/core/runner/prepare-gate-stations.js +13 -5
  61. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  62. package/dist/core/runner/prepare-memory.js +9 -9
  63. package/dist/core/runner/prepare-policy-chain.js +11 -3
  64. package/dist/core/runner/prepare-task.d.ts +5 -1
  65. package/dist/core/runner/prepare-task.js +3 -3
  66. package/dist/core/runner/run-notification-lane.js +1 -1
  67. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  68. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  69. package/dist/core/secret-env.d.ts +2 -2
  70. package/dist/core/secret-env.js +6 -20
  71. package/dist/core/session-store.d.ts +6 -6
  72. package/dist/core/session-store.js +3 -3
  73. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  74. package/dist/core/task-notification.d.ts +35 -8
  75. package/dist/core/task-notification.js +31 -13
  76. package/dist/core/task-registry-agent.js +1 -0
  77. package/dist/core/task-registry-shared.d.ts +4 -0
  78. package/dist/core/tool-errors.d.ts +3 -3
  79. package/dist/core/tool-spec.d.ts +7 -7
  80. package/dist/core/write-protect.d.ts +16 -0
  81. package/dist/core/write-protect.js +10 -0
  82. package/dist/engine/session/repo-utils.d.ts +14 -4
  83. package/dist/engine/session/repo-utils.js +5 -4
  84. package/dist/index.d.ts +6 -6
  85. package/dist/index.js +6 -6
  86. package/dist/prompts/default.d.ts +1 -2
  87. package/dist/scenarios/full-body.d.ts +1 -1
  88. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  89. package/dist/stores/file/index.d.ts +1 -15
  90. package/dist/stores/file/index.js +1 -15
  91. package/dist/stores/file/permission-rule-store.d.ts +12 -1
  92. package/dist/stores/file/permission-rule-store.js +31 -4
  93. package/dist/stores/file/session-store.js +1 -1
  94. package/package.json +2 -2
  95. package/test/export-surface.snapshot.json +9 -73
  96. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  97. package/wire-changes/core@7.65.0.json +1650 -0
  98. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  99. package/wire-changes/primitives@7.65.0.json +337 -0
  100. package/dist/core/memory-recall.d.ts +0 -208
  101. package/dist/core/memory-recall.js +0 -136
  102. package/dist/stores/file/memory-store.d.ts +0 -124
  103. package/dist/stores/file/memory-store.js +0 -353
@@ -4,6 +4,7 @@ import { homedir } from "node:os";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
6
6
  import { MEMORY_GOVERNANCE_DOC_NAMES, MEMORY_ORIGIN_CAUSES } from "./types.js";
7
+ import { parseEntryFile } from "./frontmatter.js";
7
8
  import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
8
9
  import { thrownLabel, thrownText } from "../thrown-value.js";
9
10
  import { egressText } from "../untrusted-egress.js";
@@ -748,9 +749,10 @@ export function isContainedIn(root, child) {
748
749
  const c = canonicalize(child);
749
750
  return c === r || c.startsWith(`${r}${sep}`);
750
751
  }
751
- export const STORE_FORM_REFUSAL_CODES = Object.freeze(["memory.target_outside_store", "memory.scope_home_not_directory"]);
752
+ export const STORE_FORM_REFUSAL_CODES = Object.freeze(["memory.target_outside_store", "memory.scope_home_not_directory", "memory.control_plane_links_unsupported"]);
752
753
  export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
753
754
  export const SCOPE_HOME_NOT_DIRECTORY = "memory.scope_home_not_directory";
755
+ export const CONTROL_PLANE_LINKS_UNSUPPORTED = "memory.control_plane_links_unsupported";
754
756
  export const SCOPE_HOME_FORMS = Object.freeze(["symlink", "file", "other"]);
755
757
  const SCOPE_HOME_FORM_PHRASE = {
756
758
  symlink: "a symbolic link",
@@ -775,6 +777,9 @@ export function storeRootAbsentRefusal(path, anchor) {
775
777
  export function scopeHomeRefusal(form, path) {
776
778
  return storeFormRefusal(SCOPE_HOME_NOT_DIRECTORY, `a scope home must be a real directory, but this one is ${SCOPE_HOME_FORM_PHRASE[form]} — refused (fail-closed); put the real directory back`, { path, form });
777
779
  }
780
+ export function controlPlaneLinksRefusal(path, fault) {
781
+ return storeFormRefusal(CONTROL_PLANE_LINKS_UNSUPPORTED, `the memory control plane is on a file system that cannot make hard links (link answered ${fault ?? "an error with no code"}) — the store publishes its control objects (quarantine copies, held files, pollution markers) with link, so it is not opened and no entry or control object was written; move the control plane (controlDir, or the memory engine root) to a volume that supports hard links`, { path });
782
+ }
778
783
  export function landingPathOf(p) {
779
784
  return landingPathWithin(resolve(p), 0);
780
785
  }
@@ -1313,31 +1318,109 @@ export function restoreContainedBaseline(path, committed, leftOnPlane) {
1313
1318
  }
1314
1319
  }
1315
1320
  let quarantineSeq = 0;
1316
- export function quarantineAndTombstone(path, content, quarantineDir, now) {
1317
- let captured;
1318
- let detail;
1319
- try {
1320
- ensureDirExists(quarantineDir);
1321
- const base = `${now()}-${basename(path)}`;
1322
- for (let attempt = 0; captured === undefined && attempt < 10; attempt++) {
1323
- const candidate = join(quarantineDir, attempt === 0 ? base : `${base}.${attempt}`);
1324
- try {
1325
- writeFileSync(candidate, content, { encoding: "utf8", flag: "wx" });
1326
- captured = candidate;
1327
- }
1328
- catch (err) {
1329
- if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
1330
- throw err;
1331
- }
1321
+ export async function putControlObjectOnce(objects, kind, name, bytes) {
1322
+ try {
1323
+ return await objects.putObject(kind, name, bytes);
1324
+ }
1325
+ catch (err) {
1326
+ let standing;
1327
+ try {
1328
+ standing = await objects.getObject(kind, name);
1332
1329
  }
1333
- if (captured === undefined) {
1334
- const last = join(quarantineDir, `${base}.${process.pid}.${quarantineSeq++}`);
1335
- writeFileSync(last, content, { encoding: "utf8", flag: "wx" });
1336
- captured = last;
1330
+ catch {
1331
+ throw err;
1332
+ }
1333
+ if (standing === undefined)
1334
+ throw err;
1335
+ return "existed";
1336
+ }
1337
+ }
1338
+ export function quarantineCaptureName(base, attempt) {
1339
+ return attempt === 0 ? base : attempt < 10 ? `${base}.${attempt}` : `${base}.${process.pid}.${quarantineSeq++}`;
1340
+ }
1341
+ export function quarantineCaptureBase(path, now) {
1342
+ return `${now()}-${basename(path).replace(/\\/g, "%5C")}`;
1343
+ }
1344
+ export async function captureIntoQuarantine(objects, path, content, now) {
1345
+ const bytes = new TextEncoder().encode(content);
1346
+ const base = quarantineCaptureBase(path, now);
1347
+ try {
1348
+ for (let attempt = 0; attempt <= 10; attempt++) {
1349
+ const name = quarantineCaptureName(base, attempt);
1350
+ if ((await putControlObjectOnce(objects, "quarantine", name, bytes)) === "created")
1351
+ return { name };
1337
1352
  }
1353
+ return { failed: "quarantine copy failed: every capture name already stands" };
1354
+ }
1355
+ catch (err) {
1356
+ return { failed: `quarantine copy failed: ${thrownText(err)}` };
1357
+ }
1358
+ }
1359
+ export async function eraseQuarantineCopies(objects, ids) {
1360
+ let listed;
1361
+ try {
1362
+ listed = await objects.listObjects("quarantine");
1338
1363
  }
1339
1364
  catch (err) {
1340
- detail = `quarantine copy failed: ${thrownText(err)}`;
1365
+ throw new ControlPlaneCorruptError(`memory erasure: the quarantine objects could not be listed (${thrownText(err)}) — the attestation must not silently claim an empty residual set; retry after the store's fault clears (the deletions themselves are committed and a replay converges)`, { cause: err });
1366
+ }
1367
+ if (!Array.isArray(listed) || !Array.from(listed).every((name) => typeof name === "string")) {
1368
+ throw new ControlPlaneCorruptError("memory erasure: the store's listing of its quarantine objects is not a list of names — the attestation must not silently claim an empty residual set; retry after the store's fault clears (the deletions themselves are committed and a replay converges)");
1369
+ }
1370
+ const out = { removed: 0, remaining: 0, unreadable: 0, unattributed: 0 };
1371
+ for (const name of new Set(listed)) {
1372
+ let text;
1373
+ try {
1374
+ const bytes = await objects.getObject("quarantine", name);
1375
+ if (bytes === undefined)
1376
+ continue;
1377
+ text = new TextDecoder().decode(bytes);
1378
+ }
1379
+ catch {
1380
+ text = undefined;
1381
+ }
1382
+ if (text === undefined) {
1383
+ out.remaining++;
1384
+ out.unreadable++;
1385
+ continue;
1386
+ }
1387
+ const id = parseEntryFile(text).id;
1388
+ if (id === undefined) {
1389
+ out.unattributed++;
1390
+ continue;
1391
+ }
1392
+ if (!ids.has(id))
1393
+ continue;
1394
+ try {
1395
+ const deleted = await objects.deleteObject("quarantine", name);
1396
+ if (deleted === true)
1397
+ out.removed++;
1398
+ else if (deleted !== false)
1399
+ out.remaining++;
1400
+ }
1401
+ catch {
1402
+ out.remaining++;
1403
+ }
1404
+ }
1405
+ return out;
1406
+ }
1407
+ export function clearContainedPath(path, content, capture) {
1408
+ const captured = "name" in capture ? capture.name : undefined;
1409
+ let detail = "failed" in capture ? capture.failed : undefined;
1410
+ let onDisk;
1411
+ try {
1412
+ onDisk = readFileSync(path, "utf8");
1413
+ }
1414
+ catch {
1415
+ onDisk = undefined;
1416
+ }
1417
+ if (onDisk !== undefined && onDisk !== content) {
1418
+ return {
1419
+ ...(captured !== undefined ? { dest: captured } : {}),
1420
+ removed: false,
1421
+ leftOnPlane: content,
1422
+ detail: `${detail !== undefined ? `${detail}; ` : ""}the file was rewritten after it was read — the newer bytes are not the captured copy and were left in place`,
1423
+ };
1341
1424
  }
1342
1425
  let left = content;
1343
1426
  let removed = false;
@@ -1364,11 +1447,32 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
1364
1447
  ...(detail !== undefined ? { detail } : {}),
1365
1448
  };
1366
1449
  }
1450
+ export async function keepCopiesBeforeOverwrite(text, keep, reread) {
1451
+ const failed = [];
1452
+ let held = text;
1453
+ for (let copies = 0; copies < 3; copies++) {
1454
+ const outcome = await keep(held);
1455
+ if (outcome !== true)
1456
+ failed.push(outcome);
1457
+ let onDisk;
1458
+ try {
1459
+ onDisk = reread();
1460
+ }
1461
+ catch (err) {
1462
+ return { landed: false, failed: [...failed, `the file could not be read again after its copy: ${thrownText(err)}`] };
1463
+ }
1464
+ if (onDisk === undefined || onDisk === held)
1465
+ return { landed: failed.length === 0, failed };
1466
+ held = onDisk;
1467
+ }
1468
+ return { landed: false, failed: [...failed, "the file kept being rewritten while its copy was kept — its last version was not captured"] };
1469
+ }
1367
1470
  export const ATOMIC_WRITE_TMP_PREFIX = ".tmp-";
1471
+ export const LINK_PROBE_PREFIX = ".link-probe-";
1368
1472
  export const LOCK_TOMB_INFIX = ".stale-";
1369
1473
  export const STORE_OPEN_ARTIFACTS = Object.freeze({
1370
1474
  files: Object.freeze([ROOT_ANCHOR_FILE, SCOPES_FILE, `${SCOPES_FILE}.journal`]),
1371
- filePrefixes: Object.freeze([ATOMIC_WRITE_TMP_PREFIX]),
1475
+ filePrefixes: Object.freeze([ATOMIC_WRITE_TMP_PREFIX, LINK_PROBE_PREFIX]),
1372
1476
  lockDirs: Object.freeze([`${ROOT_ANCHOR_FILE}.lock`, `${SCOPES_FILE}.lock`, STORE_TXN_LOCK_DIR]),
1373
1477
  memoryFilePrefixes: Object.freeze([CASEFOLD_PROBE_PREFIX]),
1374
1478
  });
@@ -1914,8 +2018,10 @@ export function usableSessionIncarnation(raw) {
1914
2018
  return isIncarnationSeat(raw) ? raw : undefined;
1915
2019
  }
1916
2020
  function sessionRecordPath(controlDir, dir, sessionId, incarnation) {
1917
- const name = incarnation === undefined ? `${encodeURIComponent(sessionId)}.json` : `${encodeURIComponent(sessionId)}@${encodeURIComponent(incarnation)}.json`;
1918
- return join(controlDir, dir, name);
2021
+ return join(controlDir, dir, sessionRecordName(sessionId, incarnation));
2022
+ }
2023
+ function sessionRecordName(sessionId, incarnation) {
2024
+ return incarnation === undefined ? `${encodeURIComponent(sessionId)}.json` : `${encodeURIComponent(sessionId)}@${encodeURIComponent(incarnation)}.json`;
1919
2025
  }
1920
2026
  function standingOwnerAt(path) {
1921
2027
  let raw;
@@ -1992,38 +2098,72 @@ function sessionIdOfRecordName(name) {
1992
2098
  }
1993
2099
  }
1994
2100
  export const SESSION_POLLUTION_DIR = "session-pollution";
1995
- function pollutionPath(controlDir, sessionId, incarnation) {
1996
- return sessionRecordPath(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation);
1997
- }
1998
- export function markSessionPolluted(controlDir, sessionId, reason, now, cause, incarnation) {
2101
+ export async function markSessionPolluted(objects, sessionId, reason, now, cause, incarnation) {
1999
2102
  const record = { at: now(), reason, ...(cause !== undefined ? { cause } : {}), ...(incarnation !== undefined ? { incarnation } : {}) };
2000
- return mintSessionRecordSlots(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation, `${JSON.stringify(record, null, 2)}\n`);
2103
+ return mintPollutionSlots(objects, sessionId, incarnation, new TextEncoder().encode(`${JSON.stringify(record, null, 2)}\n`));
2001
2104
  }
2002
- export function readSessionPollution(controlDir, sessionId, identity) {
2105
+ async function mintPollutionSlots(objects, sessionId, incarnation, bytes) {
2106
+ try {
2107
+ if ((await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId), bytes)) === "created")
2108
+ return "created";
2109
+ }
2110
+ catch {
2111
+ return "unpersisted";
2112
+ }
2113
+ const own = usableSessionIncarnation(incarnation);
2114
+ const standing = await pollutionOwnerOf(objects, sessionRecordName(sessionId));
2115
+ const vouches = standing !== "unattributable" && (standing.owner === undefined || standing.owner === own);
2116
+ const unnamed = vouches || own === undefined ? undefined : await pollutionOwnerOf(objects, sessionRecordName(sessionId, ""));
2117
+ if (vouches || (unnamed !== undefined && unnamed !== "unattributable" && unnamed.owner === undefined))
2118
+ return "existed";
2119
+ try {
2120
+ return (await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId, own ?? ""), bytes)) === "created" ? "created" : "existed";
2121
+ }
2122
+ catch {
2123
+ return "unpersisted";
2124
+ }
2125
+ }
2126
+ async function pollutionOwnerOf(objects, name) {
2127
+ let bytes;
2128
+ try {
2129
+ bytes = await objects.getObject("pollution", name);
2130
+ }
2131
+ catch {
2132
+ return "unattributable";
2133
+ }
2134
+ if (bytes === undefined)
2135
+ return "unattributable";
2136
+ try {
2137
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
2138
+ if (parsed !== null && typeof parsed === "object")
2139
+ return { owner: readIncarnationSeat(parsed) };
2140
+ }
2141
+ catch {
2142
+ }
2143
+ return "unattributable";
2144
+ }
2145
+ export async function readSessionPollution(objects, sessionId, identity) {
2003
2146
  const asking = usableSessionIncarnation(identity?.incarnation);
2004
2147
  if (asking !== undefined) {
2005
- const own = readPollutionAt(pollutionPath(controlDir, sessionId, asking));
2148
+ const own = await readPollutionObject(objects, sessionRecordName(sessionId, asking));
2006
2149
  if (own !== undefined)
2007
2150
  return own;
2008
2151
  }
2009
- const unnamedSlot = () => readPollutionAt(pollutionPath(controlDir, sessionId, ""));
2010
- const standing = readPollutionAt(pollutionPath(controlDir, sessionId));
2011
- return standing === undefined ? unnamedSlot() : bindOrSeparate(standing, identity, asking, unnamedSlot);
2152
+ const unnamed = await readPollutionObject(objects, sessionRecordName(sessionId, ""));
2153
+ const standing = await readPollutionObject(objects, sessionRecordName(sessionId));
2154
+ return standing === undefined ? unnamed : bindOrSeparate(standing, identity, asking, () => unnamed);
2012
2155
  }
2013
- function readPollutionAt(path) {
2014
- let raw;
2156
+ async function readPollutionObject(objects, name) {
2157
+ let bytes;
2015
2158
  try {
2016
- raw = readFileSync(path, "utf8");
2159
+ bytes = await objects.getObject("pollution", name);
2017
2160
  }
2018
2161
  catch {
2019
- try {
2020
- lstatSync(path);
2021
- }
2022
- catch {
2023
- return undefined;
2024
- }
2025
2162
  return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
2026
2163
  }
2164
+ return bytes === undefined ? undefined : pollutionRecordOf(new TextDecoder().decode(bytes));
2165
+ }
2166
+ function pollutionRecordOf(raw) {
2027
2167
  try {
2028
2168
  const parsed = JSON.parse(raw);
2029
2169
  if (parsed !== null && typeof parsed === "object") {
@@ -2040,40 +2180,24 @@ function readPollutionAt(path) {
2040
2180
  }
2041
2181
  return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
2042
2182
  }
2043
- export function listSessionPollution(controlDir) {
2044
- const dir = join(controlDir, SESSION_POLLUTION_DIR);
2045
- let names;
2046
- try {
2047
- names = readdirSync(dir);
2048
- }
2049
- catch (err) {
2050
- if (err.code === "ENOENT")
2051
- return {};
2052
- throw new ControlPlaneCorruptError(`session pollution markers could not be enumerated (${err.code ?? "io error"}) at ${dir} — an enumeration failure is not an empty set (fail-closed)`, { cause: err });
2053
- }
2183
+ export async function listSessionPollution(objects) {
2184
+ const names = await objects.listObjects("pollution");
2054
2185
  const out = Object.create(null);
2055
- for (const name of names.sort()) {
2186
+ for (const name of [...names].sort()) {
2056
2187
  const sessionId = sessionIdOfRecordName(name);
2057
2188
  if (sessionId === undefined || Object.prototype.hasOwnProperty.call(out, sessionId))
2058
2189
  continue;
2059
- const rec = readPollutionAt(join(dir, name));
2190
+ const rec = await readPollutionObject(objects, name);
2060
2191
  if (rec !== undefined)
2061
2192
  out[sessionId] = rec;
2062
2193
  }
2063
2194
  return out;
2064
2195
  }
2065
- export function importSessionPollution(controlDir, sessionId, record) {
2066
- const path = pollutionPath(controlDir, sessionId);
2067
- ensureDirExists(dirname(path));
2068
- try {
2069
- writeFileSync(path, `${JSON.stringify({ at: record.at, reason: record.reason, ...(record.cause !== undefined ? { cause: record.cause } : {}) }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
2196
+ export async function importSessionPollution(objects, sessionId, record) {
2197
+ const text = `${JSON.stringify({ at: record.at, reason: record.reason, ...(record.cause !== undefined ? { cause: record.cause } : {}) }, null, 2)}\n`;
2198
+ if ((await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId), new TextEncoder().encode(text))) === "created")
2070
2199
  return "written";
2071
- }
2072
- catch (err) {
2073
- if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
2074
- throw err;
2075
- }
2076
- const standing = readSessionPollution(controlDir, sessionId);
2200
+ const standing = await readSessionPollution(objects, sessionId);
2077
2201
  return standing !== undefined && standing.at === record.at && standing.reason === record.reason ? "already" : "divergent";
2078
2202
  }
2079
2203
  export const SESSION_CAPTURE_OPTOUT_DIR = "session-capture-optout";
@@ -2497,8 +2621,8 @@ export const IMPORT_RECEIPTS_DIR = "import-receipts";
2497
2621
  export function importLatchTxnId(bundleHash) {
2498
2622
  return `import:${bundleHash}`;
2499
2623
  }
2500
- function importReceiptPath(controlDir, bundleHash) {
2501
- return join(controlDir, IMPORT_RECEIPTS_DIR, `${bundleHash}.json`);
2624
+ export function importReceiptName(bundleHash) {
2625
+ return `${bundleHash}.json`;
2502
2626
  }
2503
2627
  export async function stageImportLatch(docs, bundleHash, rows, now) {
2504
2628
  const txnId = importLatchTxnId(bundleHash);
@@ -2517,27 +2641,23 @@ export async function stageImportLatch(docs, bundleHash, rows, now) {
2517
2641
  });
2518
2642
  return txnId;
2519
2643
  }
2520
- export async function releaseImportLatch(docs, controlDir, txnId) {
2644
+ export async function releaseImportLatch(store, txnId) {
2521
2645
  const prefix = "import:";
2522
2646
  if (!txnId.startsWith(prefix) || !/^[0-9a-f]{64}$/.test(txnId.slice(prefix.length))) {
2523
2647
  throw new ControlPlaneCorruptError(`releaseImportLatch: ${JSON.stringify(txnId)} is not an import-latch transaction id (import:<64-hex bundleHash>)`);
2524
2648
  }
2525
- const receipt = importReceiptPath(controlDir, txnId.slice(prefix.length));
2526
- let receiptPresent;
2649
+ const receipt = importReceiptName(txnId.slice(prefix.length));
2650
+ let bytes;
2527
2651
  try {
2528
- readFileSync(receipt);
2529
- receiptPresent = true;
2652
+ bytes = await store.getObject("import-receipt", receipt);
2530
2653
  }
2531
2654
  catch (err) {
2532
- if (err.code !== "ENOENT") {
2533
- throw new ControlPlaneCorruptError(`releaseImportLatch: the completion receipt at ${receipt} could not be read (${err.code ?? "io error"}) — a probe failure is not absence (fail-closed), and absence would refuse the release`, { cause: err });
2534
- }
2535
- receiptPresent = false;
2655
+ throw new ControlPlaneCorruptError(`releaseImportLatch: the completion receipt ${receipt} could not be read (${thrownText(err)}) — a probe failure is not absence (fail-closed), and absence would refuse the release`, { cause: err });
2536
2656
  }
2537
- if (!receiptPresent) {
2538
- throw new ControlPlaneCorruptError(`releaseImportLatch: no completion receipt at ${receipt} — the import's governance legs are not proven landed, the latch stays; re-run the same bundle import to converge`);
2657
+ if (bytes === undefined) {
2658
+ throw new ControlPlaneCorruptError(`releaseImportLatch: no completion receipt ${receipt} — the import's governance legs are not proven landed, the latch stays; re-run the same bundle import to converge`);
2539
2659
  }
2540
- await docs.updateDoc("lineage", coerceLineage, (rec) => {
2660
+ await store.updateDoc("lineage", coerceLineage, (rec) => {
2541
2661
  const txn = rec.pending[txnId];
2542
2662
  if (txn === undefined)
2543
2663
  return { result: undefined };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Render a memory entry's age as a natural-language phrase (CC-parity P0-1). CC's eval found
3
+ * models reason about memory age much better from natural language ("3 days ago") than from a boolean
4
+ * "older note" flag (verify-claims 0/2 → 3/3 once the age was spelled out), because the model can weigh
5
+ * staleness proportionally instead of as a single cliff. This is the relative phrase only; it is additional
6
+ * signal beside the entry, not a verdict on it.
7
+ *
8
+ * Buckets (each chooses the coarsest unit that's ≥1): `today` (<1 day, incl. future mtime / clock skew →
9
+ * clamped to today, never a negative age), `yesterday` (1–2 days), `N days ago` (2–7 days),
10
+ * `N weeks ago` (1 week – ~1 month), `N months ago` (≥ ~1 month). N is floored to the whole unit.
11
+ */
12
+ export declare function formatMemoryAge(ageMs: number): string;
@@ -0,0 +1,17 @@
1
+ const ONE_DAY_MS = 24 * 60 * 60 * 1_000;
2
+ const ONE_WEEK_MS = 7 * ONE_DAY_MS;
3
+ const ONE_MONTH_MS = 30.44 * ONE_DAY_MS;
4
+ export function formatMemoryAge(ageMs) {
5
+ if (ageMs < ONE_DAY_MS)
6
+ return "today";
7
+ if (ageMs < 2 * ONE_DAY_MS)
8
+ return "yesterday";
9
+ if (ageMs < ONE_WEEK_MS)
10
+ return `${Math.floor(ageMs / ONE_DAY_MS)} days ago`;
11
+ if (ageMs < ONE_MONTH_MS) {
12
+ const weeks = Math.floor(ageMs / ONE_WEEK_MS);
13
+ return `${weeks} ${weeks === 1 ? "week" : "weeks"} ago`;
14
+ }
15
+ const months = Math.floor(ageMs / ONE_MONTH_MS);
16
+ return `${months} ${months === 1 ? "month" : "months"} ago`;
17
+ }
@@ -1203,11 +1203,12 @@ export async function memoryGovernanceStoreContract(hooks) {
1203
1203
  assert.strictEqual(await s.deleteObject(kind, "obj-1.json"), false, `${kind}: nothing to delete`);
1204
1204
  }
1205
1205
  });
1206
- defer("an object is written once: a second put of the name answers existed and changes nothing", async () => {
1206
+ defer("an object is written once: a second put of the same bytes answers existed, a second put of other bytes is refused, and neither changes anything", async () => {
1207
1207
  const s = await hooks.make();
1208
1208
  for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
1209
1209
  assert.strictEqual(await s.putObject(kind, "once.json", enc(`first ${kind}`), { scope: "s1" }), "created", `${kind}: the first put creates`);
1210
- assert.strictEqual(await s.putObject(kind, "once.json", enc(`second ${kind}`)), "existed", `${kind}: the second put finds it`);
1210
+ assert.strictEqual(await s.putObject(kind, "once.json", enc(`first ${kind}`)), "existed", `${kind}: the same bytes find it`);
1211
+ await rejectsCoded(s.putObject(kind, "once.json", enc(`second ${kind}`)), /ControlPlaneCorruptError|corrupt/i, `${kind}: other bytes over a standing name`);
1211
1212
  assert.ok(same(await s.getObject(kind, "once.json"), enc(`first ${kind}`)), `${kind}: the first bytes stand`);
1212
1213
  }
1213
1214
  });
@@ -1259,7 +1260,7 @@ export async function memoryGovernanceStoreContract(hooks) {
1259
1260
  const s = await hooks.make();
1260
1261
  await rejectsCoded(s.putObject("ledger", "a.json", enc("x")), "memory.control_object_unknown", "an unknown kind");
1261
1262
  await rejectsCoded(s.listObjects("__proto__"), "memory.control_object_unknown", "a prototype key as a kind");
1262
- for (const name of ["", ".", "..", "a/b", "../x", "a\\b", "a\u0000b"]) {
1263
+ for (const name of ["", ".", "..", "a/b", "../x", "a\\b", "a\u0000b", "n".repeat(256), "中".repeat(86)]) {
1263
1264
  await rejectsCoded(s.putObject("pollution", name, enc("x")), "memory.control_object_unknown", `put of the name ${JSON.stringify(name)}`);
1264
1265
  await rejectsCoded(s.getObject("pollution", name), "memory.control_object_unknown", `get of the name ${JSON.stringify(name)}`);
1265
1266
  }
@@ -1270,7 +1271,7 @@ export async function memoryGovernanceStoreContract(hooks) {
1270
1271
  await s.putObject("pollution", "kept.json", enc("marker"));
1271
1272
  await hooks.corrupt(s, { object: "pollution", name: "standing.json" });
1272
1273
  await rejectsCoded(s.getObject("pollution", "standing.json"), /ControlPlaneCorruptError|corrupt/i, "an unreadable object");
1273
- assert.strictEqual(await s.putObject("pollution", "standing.json", enc("over it")), "existed", "an unreadable object still stands: a put does not overwrite it");
1274
+ await rejectsCoded(s.putObject("pollution", "standing.json", enc("over it")), /ControlPlaneCorruptError|corrupt/i, "an unreadable object still stands: a put neither overwrites it nor answers for bytes it could not compare");
1274
1275
  await hooks.corrupt(s, { listing: "quarantine" });
1275
1276
  await rejectsCoded(s.listObjects("quarantine"), /ControlPlaneCorruptError|corrupt/i, "an enumeration that fails");
1276
1277
  });
@@ -69,7 +69,7 @@ export interface MemoryDeployment {
69
69
  * set exactly when its mount holds a record: a file under `<engine root>/personal/.engine` or
70
70
  * `<engine root>/personal/memory` other than the named artifacts an open or a read leaves, matched at that place
71
71
  * and by that name only (`*` = any rest of the name): control plane top level, files `root-anchor.json` ·
72
- * `scopes.json` · `scopes.json.journal` · `.tmp-*`; control plane top level, directories as whole trees
72
+ * `scopes.json` · `scopes.json.journal` · `.tmp-*` · `.link-probe-*`; control plane top level, directories as whole trees
73
73
  * `root-anchor.json.lock` · `scopes.json.lock` · `txn.lock` · `root-anchor.json.lock.stale-*` ·
74
74
  * `scopes.json.lock.stale-*` · `txn.lock.stale-*`; memory directory top level, files `.casefold-probe-*`. A
75
75
  * directory that cannot be read, for any reason but absence (a link that leads nowhere, at it or above it, is no
@@ -25,11 +25,7 @@ function keepCustody(controlDir, clearanceId, text) {
25
25
  const bytes = new TextEncoder().encode(text);
26
26
  const digest = sha256Hex(bytes);
27
27
  const name = clearanceCustodyName(clearanceId);
28
- if (putFileControlObject(controlDir, "clearance-custody", name, bytes) === "existed") {
29
- const standing = getFileControlObject(controlDir, "clearance-custody", name);
30
- if (standing === undefined || sha256Hex(standing) !== digest)
31
- throw new ControlPlaneCorruptError(`memory origin-clearance ledger: custody ${JSON.stringify(name)} already stands with other bytes — refusing to keep a second text under it (fail-closed)`);
32
- }
28
+ putFileControlObject(controlDir, "clearance-custody", name, bytes);
33
29
  return digest;
34
30
  }
35
31
  function moveInlineCustody(controlDir, rec) {
@@ -125,9 +125,9 @@ export interface MemoryEngineToolsOptions {
125
125
  * Absent ⇒ no pollution face is wired (engine-direct hosts, tests): the empty-outcome wording is
126
126
  * then exactly the clean-session wording — nothing is inferred from the seat's absence.
127
127
  */
128
- sessionPollution?: () => {
128
+ sessionPollution?: () => Promise<{
129
129
  reason: string;
130
- } | undefined;
130
+ } | undefined>;
131
131
  /**
132
132
  * design/336 §13-3 — the provenance mode the write engine runs under. Two consumers here:
133
133
  * - the pollution sentence states what the mark actually DOES (under `"carry"` writes commit
@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
2
2
  import { Type } from "typebox";
3
3
  import { errorResult } from "../tools.js";
4
4
  import { defuseFenceMarkers, delimitUntrusted, FENCED_LANE_ENVELOPE_TAGS, inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
5
- import { formatMemoryAge } from "../memory-recall.js";
5
+ import { formatMemoryAge } from "./memory-age.js";
6
6
  import { committedOriginOf } from "./frontmatter.js";
7
7
  import { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_INDEX_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, MEMORY_SEARCH_BAND_ORDER_HEADER } from "./provenance-wording.js";
8
8
  import { deriveSupersededSet, memorySupersededNote, MEMORY_CHALLENGED_ENTRY_GUIDANCE, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
@@ -146,10 +146,10 @@ export function createMemoryEngineTools(opts) {
146
146
  }
147
147
  }
148
148
  const exposedEntry = (e) => committedOriginOf(e.frontmatter) !== undefined;
149
- const pollutionSentence = () => {
149
+ const pollutionSentence = async () => {
150
150
  let reason;
151
151
  try {
152
- reason = opts.sessionPollution?.()?.reason;
152
+ reason = (await opts.sessionPollution?.())?.reason;
153
153
  }
154
154
  catch {
155
155
  return "";
@@ -161,13 +161,13 @@ export function createMemoryEngineTools(opts) {
161
161
  }
162
162
  return ` This session is marked polluted (${inlineUntrusted(reason, 200)}): the memory it writes is not admitted to the library at harvest, so writing this down now would not make it retrievable later either.`;
163
163
  };
164
- const noMatch = (query) => {
164
+ const noMatch = async (query) => {
165
165
  const details = { outcome: "ok", hits: [] };
166
166
  return {
167
167
  content: `No memory entries matched ${JSON.stringify(inlineUntrusted(query, 120))}. Matching is lexical — other concrete ` +
168
168
  `wordings may still hit, and ${MEMORY_INDEX_TOOL_NAME} lists every mounted entry when no wording works. ` +
169
169
  `If the user expected you to know this, say that you checked memory and found nothing.` +
170
- pollutionSentence(),
170
+ (await pollutionSentence()),
171
171
  details,
172
172
  };
173
173
  };
@@ -448,7 +448,7 @@ export function createMemoryEngineTools(opts) {
448
448
  `Only entries carrying a committed entry id are served here, and a memory file written into the memory root during ` +
449
449
  `this session gets its id when the session-boundary harvest admits it — a file written in this session is not served here before then. ` +
450
450
  `If the slug is misremembered: ${MEMORY_SEARCH_TOOL_NAME} matches keywords; ${MEMORY_INDEX_TOOL_NAME} lists exact slugs.` +
451
- pollutionSentence(), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
451
+ (await pollutionSentence()), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
452
452
  }
453
453
  try {
454
454
  const names = await shadowNamesAcross(await Promise.all(planes.map((plane) => plane.challengeExclusions?.())));
@@ -741,7 +741,7 @@ export function createMemoryEngineTools(opts) {
741
741
  if (total === 0) {
742
742
  const where = scope !== undefined ? ` in scope ${inlineUntrusted(scope, 80)}` : "";
743
743
  const details = { outcome: "ok", entries: [], offset: 0, shown: 0, total: 0, ...(supersededHidden > 0 ? { supersededHidden } : {}), ...(shadowedHidden > 0 ? { shadowedHidden } : {}) };
744
- return { content: `No ${supersededHidden > 0 || shadowedHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + pollutionSentence(), details };
744
+ return { content: `No ${supersededHidden > 0 || shadowedHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + (await pollutionSentence()), details };
745
745
  }
746
746
  if (offset >= total) {
747
747
  return refusedIndex("offset_past_end", `offset ${offset} is past the end — the listing has ${total} row${total === 1 ? "" : "s"}.`);
@@ -220,7 +220,7 @@ export interface MemoryEntryHeader {
220
220
  }
221
221
  /** A scored search hit (FileBackend = lexical floor; PgBackend = design/81 vector rungs, S3). */
222
222
  export interface ScoredMemoryEntry extends MemoryEntryHeader {
223
- /** Cosine-DISTANCE ∈ [0,2], 0 = identical (same contract as {@link import("../memory.js").ScoredMemory}). */
223
+ /** Cosine-DISTANCE ∈ [0,2], 0 = identical (the scale of {@link import("../memory-vector.js").cosineDistance}). */
224
224
  score: number;
225
225
  }
226
226
  /**
@@ -283,8 +283,7 @@ export interface PatchReport {
283
283
  }>;
284
284
  }
285
285
  /**
286
- * design/138 §2.1 — the storage seam under the MemoryEngine. NOT a MemoryStore replacement shim: this
287
- * is the S1 new-architecture surface (the legacy `MemoryStore` path is untouched and switched off it).
286
+ * design/138 §2.1 — the storage seam under the MemoryEngine: the one memory contract a host implements.
288
287
  */
289
288
  export interface MemoryBackend {
290
289
  /** Headers for every entry in the given scopes (manifest surface — bodies excluded). */
@@ -367,8 +366,10 @@ export interface MemoryBackend {
367
366
  * /malformed patch refused/, never the ordinary rev-mismatch conflict (a whitewash is illegal
368
367
  * at ANY rev, and the weaker conflict would tell the caller's ladder to rebase and retry it);
369
368
  * design/339 c37: the same precedence covers the `distilled` law;
370
- * - design/336 §4 hold protocol: the backend is hold-UNAWARE — instruction holds live on the
371
- * ENGINE's control plane, so a held id keeps serving reads and ordinary add/update patches for
369
+ * - design/336 §4 hold protocol: the backend is hold-UNAWARE — instruction holds live in the
370
+ * ENGINE's governance records (the `holds` document and its `hold` / `quarantine` objects, in
371
+ * the store `governance` names when the backend carries one), never in the backend's entries,
372
+ * so a held id keeps serving reads and ordinary add/update patches for
372
373
  * it apply plainly (no queueing, no refusal). The settlement-period write interaction resolves
373
374
  * at release time through the clauses above: the release replays the capture-time anchor
374
375
  * (update+`baseRev` / `guard: "absent"` add), a mid-hold winner surfaces as the REPORTED
@@ -494,14 +495,16 @@ export interface MemoryGovernanceStore {
494
495
  result: T;
495
496
  }): Promise<T>;
496
497
  /** Write a control object ({@link MEMORY_CONTROL_OBJECT_KINDS}) once: `"created"` ⇔ this call wrote `bytes` under
497
- * `(kind, name)`, `"existed"` ⇔ that name already stood — whatever it holds, it is never overwritten. A reader never
498
+ * `(kind, name)`, `"existed"` ⇔ that name already stood holding exactly `bytes` — it is never overwritten, and a name
499
+ * that stands holding other bytes (or as an entry that cannot be read to tell) throws `ControlPlaneCorruptError`, the way
500
+ * a move over a target holding other bytes does: a put never answers as written for bytes it did not store. A reader never
498
501
  * meets half an object. `meta.scope` names the memory scope the object concerns when the writer knows one (a store
499
502
  * with a scope column keeps it; the File store has none and ignores it). A kind outside the closed set, or a name that
500
- * is not one opaque segment (empty, `.` / `..`, a `/`, a `\` or a NUL), is refused `memory.control_object_unknown`.
503
+ * is not one opaque segment (empty, `.` / `..`, a `/`, a `\` or a NUL, or longer than 255 UTF-8 bytes), is refused `memory.control_object_unknown`.
501
504
  *
502
505
  * @contract memory.governance.object_written_once — once a name of a kind stands, no store call replaces its bytes:
503
- * a second put answers `"existed"`, a move refuses a target holding other bytes, and only `deleteObject` takes it
504
- * away; core keeps the records whose silent replacement would launder what they recorded (a pollution marker, a
506
+ * a second put of the same bytes answers `"existed"`, a second put of other bytes (or over an entry that cannot be read to
507
+ * tell) is refused, a move refuses a target holding other bytes, and only `deleteObject` takes it away; core keeps the records whose silent replacement would launder what they recorded (a pollution marker, a
505
508
  * capture opt-out, a hold's captured bytes) on this promise. */
506
509
  putObject(kind: MemoryControlObjectKind, name: string, bytes: Uint8Array, meta?: {
507
510
  readonly scope?: string;
@@ -514,7 +517,8 @@ export interface MemoryGovernanceStore {
514
517
  listObjects(kind: MemoryControlObjectKind): Promise<string[]>;
515
518
  /** Move one object to a new `(kind, name)` in one step, never overwriting: `"moved"` ⇔ the object now stands only at
516
519
  * `to`; `"already-moved"` ⇔ the source was gone and `to` stands (a resumed move). A source and target that both stand
517
- * with different bytes, or a source and target both gone, throw. */
520
+ * with the same bytes finish by dropping the source; the File store drops it only onto a target that is a file of its
521
+ * own (a link there throws and keeps the source). Both standing with different bytes, or both gone, throw. */
518
522
  moveObject(from: {
519
523
  readonly kind: MemoryControlObjectKind;
520
524
  readonly name: string;
@@ -543,6 +547,8 @@ export declare const MEMORY_CONTROL_OBJECT_KINDS: readonly ["pollution", "import
543
547
  export type MemoryControlObjectKind = (typeof MEMORY_CONTROL_OBJECT_KINDS)[number];
544
548
  /** The part of a {@link MemoryGovernanceStore} the governance documents are kept through. */
545
549
  export type MemoryGovernanceDocs = Pick<MemoryGovernanceStore, "readDoc" | "updateDoc">;
550
+ /** The part of a {@link MemoryGovernanceStore} the control objects are kept through. */
551
+ export type MemoryGovernanceObjects = Pick<MemoryGovernanceStore, "putObject" | "getObject" | "listObjects" | "moveObject" | "deleteObject">;
546
552
  /** One file the engine materialized into the session memory directory. */
547
553
  export interface MaterializedFile {
548
554
  /** Absolute canonical path of the projected file. */