daftari 1.32.0 → 2.0.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 (181) hide show
  1. package/CHANGELOG.md +109 -1
  2. package/README.md +31 -0
  3. package/dist/access/rbac.d.ts +1 -0
  4. package/dist/access/rbac.d.ts.map +1 -1
  5. package/dist/access/rbac.js +16 -0
  6. package/dist/access/rbac.js.map +1 -1
  7. package/dist/asof/index.d.ts.map +1 -1
  8. package/dist/asof/index.js +23 -2
  9. package/dist/asof/index.js.map +1 -1
  10. package/dist/asof/report.d.ts.map +1 -1
  11. package/dist/asof/report.js +24 -0
  12. package/dist/asof/report.js.map +1 -1
  13. package/dist/asof/snapshot.d.ts +7 -1
  14. package/dist/asof/snapshot.d.ts.map +1 -1
  15. package/dist/asof/snapshot.js +28 -1
  16. package/dist/asof/snapshot.js.map +1 -1
  17. package/dist/backfill/derive.d.ts.map +1 -1
  18. package/dist/backfill/derive.js +7 -0
  19. package/dist/backfill/derive.js.map +1 -1
  20. package/dist/canary/fixtures.d.ts +12 -0
  21. package/dist/canary/fixtures.d.ts.map +1 -0
  22. package/dist/canary/fixtures.js +132 -0
  23. package/dist/canary/fixtures.js.map +1 -0
  24. package/dist/canary/index.d.ts +16 -0
  25. package/dist/canary/index.d.ts.map +1 -0
  26. package/dist/canary/index.js +105 -0
  27. package/dist/canary/index.js.map +1 -0
  28. package/dist/canary/run.d.ts +39 -0
  29. package/dist/canary/run.d.ts.map +1 -0
  30. package/dist/canary/run.js +266 -0
  31. package/dist/canary/run.js.map +1 -0
  32. package/dist/canary/stats.d.ts +36 -0
  33. package/dist/canary/stats.d.ts.map +1 -0
  34. package/dist/canary/stats.js +143 -0
  35. package/dist/canary/stats.js.map +1 -0
  36. package/dist/canon/index.d.ts +15 -0
  37. package/dist/canon/index.d.ts.map +1 -0
  38. package/dist/canon/index.js +167 -0
  39. package/dist/canon/index.js.map +1 -0
  40. package/dist/canon/resolve.d.ts +12 -0
  41. package/dist/canon/resolve.d.ts.map +1 -0
  42. package/dist/canon/resolve.js +67 -0
  43. package/dist/canon/resolve.js.map +1 -0
  44. package/dist/canon/topic.d.ts +20 -0
  45. package/dist/canon/topic.d.ts.map +1 -0
  46. package/dist/canon/topic.js +81 -0
  47. package/dist/canon/topic.js.map +1 -0
  48. package/dist/canon/types.d.ts +37 -0
  49. package/dist/canon/types.d.ts.map +1 -0
  50. package/dist/canon/types.js +9 -0
  51. package/dist/canon/types.js.map +1 -0
  52. package/dist/cli.d.ts.map +1 -1
  53. package/dist/cli.js +6 -0
  54. package/dist/cli.js.map +1 -1
  55. package/dist/curation/lint-voice.d.ts +3 -0
  56. package/dist/curation/lint-voice.d.ts.map +1 -0
  57. package/dist/curation/lint-voice.js +87 -0
  58. package/dist/curation/lint-voice.js.map +1 -0
  59. package/dist/curation/lint.d.ts +5 -1
  60. package/dist/curation/lint.d.ts.map +1 -1
  61. package/dist/curation/lint.js +36 -0
  62. package/dist/curation/lint.js.map +1 -1
  63. package/dist/curation/validity.d.ts +20 -0
  64. package/dist/curation/validity.d.ts.map +1 -0
  65. package/dist/curation/validity.js +191 -0
  66. package/dist/curation/validity.js.map +1 -0
  67. package/dist/fence/detect.d.ts +10 -0
  68. package/dist/fence/detect.d.ts.map +1 -0
  69. package/dist/fence/detect.js +161 -0
  70. package/dist/fence/detect.js.map +1 -0
  71. package/dist/fence/index.d.ts +22 -0
  72. package/dist/fence/index.d.ts.map +1 -0
  73. package/dist/fence/index.js +117 -0
  74. package/dist/fence/index.js.map +1 -0
  75. package/dist/frontmatter/schema.d.ts.map +1 -1
  76. package/dist/frontmatter/schema.js +26 -0
  77. package/dist/frontmatter/schema.js.map +1 -1
  78. package/dist/frontmatter/types.d.ts +3 -1
  79. package/dist/frontmatter/types.d.ts.map +1 -1
  80. package/dist/frontmatter/types.js +2 -0
  81. package/dist/frontmatter/types.js.map +1 -1
  82. package/dist/holders/registry.d.ts +8 -0
  83. package/dist/holders/registry.d.ts.map +1 -0
  84. package/dist/holders/registry.js +18 -0
  85. package/dist/holders/registry.js.map +1 -0
  86. package/dist/holders/types.d.ts +10 -0
  87. package/dist/holders/types.d.ts.map +1 -0
  88. package/dist/holders/types.js +2 -0
  89. package/dist/holders/types.js.map +1 -0
  90. package/dist/index.d.ts.map +1 -1
  91. package/dist/index.js +10 -6
  92. package/dist/index.js.map +1 -1
  93. package/dist/interview/questions.d.ts.map +1 -1
  94. package/dist/interview/questions.js +41 -9
  95. package/dist/interview/questions.js.map +1 -1
  96. package/dist/resources.d.ts +27 -0
  97. package/dist/resources.d.ts.map +1 -0
  98. package/dist/resources.js +169 -0
  99. package/dist/resources.js.map +1 -0
  100. package/dist/search/current-source.d.ts +1 -0
  101. package/dist/search/current-source.d.ts.map +1 -1
  102. package/dist/search/current-source.js +3 -1
  103. package/dist/search/current-source.js.map +1 -1
  104. package/dist/search/hybrid.d.ts +5 -0
  105. package/dist/search/hybrid.d.ts.map +1 -1
  106. package/dist/search/hybrid.js +23 -4
  107. package/dist/search/hybrid.js.map +1 -1
  108. package/dist/search/reindex.d.ts.map +1 -1
  109. package/dist/search/reindex.js +48 -13
  110. package/dist/search/reindex.js.map +1 -1
  111. package/dist/search/valid-at-source.d.ts +25 -0
  112. package/dist/search/valid-at-source.d.ts.map +1 -0
  113. package/dist/search/valid-at-source.js +131 -0
  114. package/dist/search/valid-at-source.js.map +1 -0
  115. package/dist/serve/index.d.ts.map +1 -1
  116. package/dist/serve/index.js +58 -89
  117. package/dist/serve/index.js.map +1 -1
  118. package/dist/server.d.ts +3 -1
  119. package/dist/server.d.ts.map +1 -1
  120. package/dist/server.js +159 -11
  121. package/dist/server.js.map +1 -1
  122. package/dist/sleep/cycle.d.ts.map +1 -1
  123. package/dist/sleep/cycle.js +20 -4
  124. package/dist/sleep/cycle.js.map +1 -1
  125. package/dist/storage/index-db.d.ts +7 -1
  126. package/dist/storage/index-db.d.ts.map +1 -1
  127. package/dist/storage/index-db.js +133 -8
  128. package/dist/storage/index-db.js.map +1 -1
  129. package/dist/tools/canon.d.ts +3 -0
  130. package/dist/tools/canon.d.ts.map +1 -0
  131. package/dist/tools/canon.js +177 -0
  132. package/dist/tools/canon.js.map +1 -0
  133. package/dist/tools/consumes.d.ts.map +1 -1
  134. package/dist/tools/consumes.js +47 -1
  135. package/dist/tools/consumes.js.map +1 -1
  136. package/dist/tools/curation.d.ts +2 -0
  137. package/dist/tools/curation.d.ts.map +1 -1
  138. package/dist/tools/curation.js +506 -3
  139. package/dist/tools/curation.js.map +1 -1
  140. package/dist/tools/edge-staleness.d.ts.map +1 -1
  141. package/dist/tools/edge-staleness.js +115 -0
  142. package/dist/tools/edge-staleness.js.map +1 -1
  143. package/dist/tools/edges.d.ts.map +1 -1
  144. package/dist/tools/edges.js +94 -0
  145. package/dist/tools/edges.js.map +1 -1
  146. package/dist/tools/read.d.ts +14 -0
  147. package/dist/tools/read.d.ts.map +1 -1
  148. package/dist/tools/read.js +383 -4
  149. package/dist/tools/read.js.map +1 -1
  150. package/dist/tools/receipt.d.ts +1 -1
  151. package/dist/tools/receipt.d.ts.map +1 -1
  152. package/dist/tools/receipt.js +147 -2
  153. package/dist/tools/receipt.js.map +1 -1
  154. package/dist/tools/search.d.ts.map +1 -1
  155. package/dist/tools/search.js +454 -3
  156. package/dist/tools/search.js.map +1 -1
  157. package/dist/tools/staged-actions.d.ts +7 -0
  158. package/dist/tools/staged-actions.d.ts.map +1 -1
  159. package/dist/tools/staged-actions.js +106 -2
  160. package/dist/tools/staged-actions.js.map +1 -1
  161. package/dist/tools/themes.d.ts.map +1 -1
  162. package/dist/tools/themes.js +120 -0
  163. package/dist/tools/themes.js.map +1 -1
  164. package/dist/tools/tier1.d.ts.map +1 -1
  165. package/dist/tools/tier1.js +56 -0
  166. package/dist/tools/tier1.js.map +1 -1
  167. package/dist/tools/tier2.d.ts.map +1 -1
  168. package/dist/tools/tier2.js +111 -1
  169. package/dist/tools/tier2.js.map +1 -1
  170. package/dist/tools/witness.d.ts.map +1 -1
  171. package/dist/tools/witness.js +93 -0
  172. package/dist/tools/witness.js.map +1 -1
  173. package/dist/tools/write.d.ts +1 -0
  174. package/dist/tools/write.d.ts.map +1 -1
  175. package/dist/tools/write.js +329 -2
  176. package/dist/tools/write.js.map +1 -1
  177. package/dist/utils/config.d.ts +2 -0
  178. package/dist/utils/config.d.ts.map +1 -1
  179. package/dist/utils/config.js +74 -0
  180. package/dist/utils/config.js.map +1 -1
  181. package/package.json +5 -2
@@ -30,6 +30,7 @@ import { noteSelfWrite } from "../search/self-write.js";
30
30
  import { allDocumentPaths, getDocumentsByPaths } from "../storage/index-db.js";
31
31
  import { readFile, resolveVaultPath } from "../storage/local.js";
32
32
  import { loadConfig } from "../utils/config.js";
33
+ import { normalizeIsoDate } from "../utils/dates.js";
33
34
  import { commit } from "../utils/git.js";
34
35
  import { sha256Hex } from "../utils/hash.js";
35
36
  import { readRunId } from "../utils/run-id.js";
@@ -40,6 +41,62 @@ import { openIndexForAccessOrNull } from "./search.js";
40
41
  function todayISO() {
41
42
  return new Date().toISOString().slice(0, 10);
42
43
  }
44
+ // --- supersession boundary (valid time) ------------------------------------
45
+ //
46
+ // `predecessor_valid_until` is the date the successor takes over. Supplying it
47
+ // lets one call record both the supersession event and the valid-time handoff,
48
+ // since the event IS the window boundary — derived from an authored relation
49
+ // plus a caller-supplied date, never inferred from statistics.
50
+ //
51
+ // Because the window is half-open, the supplied date is written VERBATIM: the
52
+ // predecessor's window ends exactly where the successor's begins, sharing no
53
+ // day and needing no arithmetic. That is what half-open buys, and it is worth
54
+ // the slightly less natural authoring precisely here — this is the path an
55
+ // agent drives, and an off-by-one would silently open a one-day hole in, or
56
+ // double-claim a day of, the vault's account of when a fact held.
57
+ //
58
+ // It only ever writes the PREDECESSOR. vault_supersede gates RBAC on the
59
+ // predecessor's collection alone, so touching the successor would be a write
60
+ // the caller may not be authorized for, on top of a second lock, a second
61
+ // provenance entry, and a multi-file commit. The successor's valid_from is
62
+ // surfaced as a hint for a separate, deliberate call.
63
+ // Reads and validates the optional `predecessor_valid_until` argument.
64
+ // Null when absent.
65
+ function readBoundary(args, tool) {
66
+ const raw = args.predecessor_valid_until;
67
+ if (raw === undefined || raw === null)
68
+ return ok(null);
69
+ if (typeof raw !== "string") {
70
+ return err(new Error(`${tool}: 'predecessor_valid_until' must be a YYYY-MM-DD date string`));
71
+ }
72
+ const normalized = normalizeIsoDate(raw);
73
+ if (normalized === null) {
74
+ return err(new Error(`${tool}: 'predecessor_valid_until' must be a YYYY-MM-DD date, got "${raw}"`));
75
+ }
76
+ return ok(normalized);
77
+ }
78
+ // Validates the predecessor's new valid_until, or refuses. An existing
79
+ // non-null valid_until that disagrees is an authored claim, and a convenience
80
+ // argument does not get to overwrite one — the caller reconciles the two dates
81
+ // themselves. An agreeing value passes through idempotently.
82
+ function closingUntil(fm, boundary, tool, path) {
83
+ const existing = fm.valid_until ?? null;
84
+ if (existing !== null && existing !== boundary) {
85
+ return err(new Error(`${tool}: ${path} already declares valid_until ${existing}, but ` +
86
+ `predecessor_valid_until ${boundary} was supplied. Refusing to overwrite an ` +
87
+ "authored value — reconcile the two dates, or omit the argument and set " +
88
+ "valid_until directly."));
89
+ }
90
+ return ok(boundary);
91
+ }
92
+ // The successor-side follow-up the caller should make deliberately, through
93
+ // the tool that carries the successor's own RBAC gate. Under a half-open
94
+ // window the successor's valid_from is the SAME date — that is the point.
95
+ function boundaryHint(successorPath, boundary) {
96
+ return (`valid_until was set on the predecessor. The successor ${successorPath} was NOT ` +
97
+ `modified — set 'valid_from: ${boundary}' on it with vault_write if that is the ` +
98
+ "date its claim starts holding (the two windows meet exactly, sharing no day).");
99
+ }
43
100
  // Refuses writes while the index is being (re)built. The write path ends in
44
101
  // indexDocument(), which races with a concurrent reindexVault() — the reindex
45
102
  // clears the index and re-inserts every document, so a write that lands in
@@ -127,6 +184,10 @@ export function serializeDocument(fm, body, extensions = [], raw = {}) {
127
184
  sources: fm.sources,
128
185
  superseded_by: fm.superseded_by,
129
186
  ttl_days: fm.ttl_days,
187
+ // `?? null` for the same reason as tier: a hand-built Frontmatter that
188
+ // predates these fields carries undefined, which js-yaml refuses to dump.
189
+ valid_from: fm.valid_from ?? null,
190
+ valid_until: fm.valid_until ?? null,
130
191
  tags: fm.tags,
131
192
  describes: fm.describes,
132
193
  questions_answered: fm.questions_answered,
@@ -988,6 +1049,9 @@ export async function vaultDeprecate(vaultRoot, args, access) {
988
1049
  const baseVersion = readBaseVersion(args, "vault_deprecate");
989
1050
  if (!baseVersion.ok)
990
1051
  return baseVersion;
1052
+ const boundary = readBoundary(args, "vault_deprecate");
1053
+ if (!boundary.ok)
1054
+ return boundary;
991
1055
  let supersededBy = null;
992
1056
  if (args.superseded_by !== undefined && args.superseded_by !== null) {
993
1057
  if (typeof args.superseded_by !== "string") {
@@ -1002,7 +1066,16 @@ export async function vaultDeprecate(vaultRoot, args, access) {
1002
1066
  const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
1003
1067
  if (!rbac.ok)
1004
1068
  return rbac;
1005
- return performFrontmatterWrite({
1069
+ // Same predecessor-only handoff as vault_supersede: this writes exactly the
1070
+ // document being deprecated, which it already locks and commits.
1071
+ let validUntil = null;
1072
+ if (boundary.value !== null) {
1073
+ const closing = closingUntil(oldFrontmatter, boundary.value, "vault_deprecate", path.value);
1074
+ if (!closing.ok)
1075
+ return closing;
1076
+ validUntil = closing.value;
1077
+ }
1078
+ const written = await performFrontmatterWrite({
1006
1079
  vaultRoot,
1007
1080
  target: target.value,
1008
1081
  agent: agent.value,
@@ -1012,6 +1085,7 @@ export async function vaultDeprecate(vaultRoot, args, access) {
1012
1085
  ...oldFrontmatter,
1013
1086
  status: "deprecated",
1014
1087
  superseded_by: supersededBy,
1088
+ ...(validUntil !== null ? { valid_until: validUntil } : {}),
1015
1089
  updated: todayISO(),
1016
1090
  updated_by: agent.value,
1017
1091
  },
@@ -1020,6 +1094,10 @@ export async function vaultDeprecate(vaultRoot, args, access) {
1020
1094
  baseVersion: baseVersion.value,
1021
1095
  access,
1022
1096
  });
1097
+ // A deprecation without a successor has nothing to hint at.
1098
+ if (!written.ok || boundary.value === null || supersededBy === null)
1099
+ return written;
1100
+ return ok({ ...written.value, hint: boundaryHint(supersededBy, boundary.value) });
1023
1101
  }
1024
1102
  // ---------------------------------------------------------------------------
1025
1103
  // vault_set_confidence (§11.4)
@@ -1197,6 +1275,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
1197
1275
  const baseVersion = readBaseVersion(args, "vault_supersede");
1198
1276
  if (!baseVersion.ok)
1199
1277
  return baseVersion;
1278
+ const boundary = readBoundary(args, "vault_supersede");
1279
+ if (!boundary.ok)
1280
+ return boundary;
1200
1281
  let reason;
1201
1282
  if (args.reason !== undefined && args.reason !== null) {
1202
1283
  if (typeof args.reason !== "string") {
@@ -1234,7 +1315,15 @@ export async function vaultSupersede(vaultRoot, args, access) {
1234
1315
  const rbac = requireWriteAccess(access, collectionOf(oldPath.value, oldFrontmatter));
1235
1316
  if (!rbac.ok)
1236
1317
  return rbac;
1237
- return performFrontmatterWrite({
1318
+ // Valid-time handoff, opt-in. Predecessor only — see the boundary helpers.
1319
+ let validUntil = null;
1320
+ if (boundary.value !== null) {
1321
+ const closing = closingUntil(oldFrontmatter, boundary.value, "vault_supersede", oldPath.value);
1322
+ if (!closing.ok)
1323
+ return closing;
1324
+ validUntil = closing.value;
1325
+ }
1326
+ const written = await performFrontmatterWrite({
1238
1327
  vaultRoot,
1239
1328
  // Canonical relPath keys the lock/provenance/commit (#127/#128).
1240
1329
  target: {
@@ -1250,6 +1339,7 @@ export async function vaultSupersede(vaultRoot, args, access) {
1250
1339
  ...oldFrontmatter,
1251
1340
  status: "superseded",
1252
1341
  superseded_by: newPath.value,
1342
+ ...(validUntil !== null ? { valid_until: validUntil } : {}),
1253
1343
  updated: todayISO(),
1254
1344
  updated_by: agent.value,
1255
1345
  },
@@ -1258,6 +1348,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
1258
1348
  baseVersion: baseVersion.value,
1259
1349
  access,
1260
1350
  });
1351
+ if (!written.ok || boundary.value === null)
1352
+ return written;
1353
+ return ok({ ...written.value, hint: boundaryHint(newPath.value, boundary.value) });
1261
1354
  }
1262
1355
  // Combines two source documents into a target and supersedes both sources to
1263
1356
  // point at it. Mechanical, not generative: the merged body is supplied by the
@@ -1288,6 +1381,9 @@ export async function vaultMerge(vaultRoot, args, access) {
1288
1381
  const agent = requireString(args, "agent", "vault_merge");
1289
1382
  if (!agent.ok)
1290
1383
  return agent;
1384
+ const boundary = readBoundary(args, "vault_merge");
1385
+ if (!boundary.ok)
1386
+ return boundary;
1291
1387
  const body = args.body;
1292
1388
  if (typeof body !== "string" || body.trim().length === 0) {
1293
1389
  return err(new Error("vault_merge requires a non-empty string 'body' argument"));
@@ -1439,10 +1535,21 @@ export async function vaultMerge(vaultRoot, args, access) {
1439
1535
  // miss it and clobber the merged body with the superseded write (#127/#128).
1440
1536
  if (source.rel === resolvedTarget.value.relPath)
1441
1537
  continue;
1538
+ // Valid-time handoff on BOTH sources. A conflict on either one refuses the
1539
+ // whole merge: a merge is already all-or-nothing, and a partial validity
1540
+ // write would leave the vault in a state no single call could produce.
1541
+ let sourceUntil = null;
1542
+ if (boundary.value !== null) {
1543
+ const closing = closingUntil(source.parsed.frontmatter, boundary.value, "vault_merge", source.path);
1544
+ if (!closing.ok)
1545
+ return closing;
1546
+ sourceUntil = closing.value;
1547
+ }
1442
1548
  const supersededFm = {
1443
1549
  ...source.parsed.frontmatter,
1444
1550
  status: "superseded",
1445
1551
  superseded_by: targetPath.value,
1552
+ ...(sourceUntil !== null ? { valid_until: sourceUntil } : {}),
1446
1553
  updated: todayISO(),
1447
1554
  updated_by: agent.value,
1448
1555
  };
@@ -1583,6 +1690,24 @@ const baseVersionProperty = {
1583
1690
  "write is rejected as stale and nothing is changed. Omit for " +
1584
1691
  "last-write-wins behavior.",
1585
1692
  };
1693
+ // Shared by vault_supersede, vault_deprecate, and vault_merge — the three
1694
+ // tools that create a superseded_by edge. vault_write deliberately has no
1695
+ // equivalent: it is the raw authoring surface, and a write-time cross-check
1696
+ // between superseded_by and the validity fields would make an optional field
1697
+ // able to block a write. vault_lint's validityConflicts is the safety net for
1698
+ // edges created that way.
1699
+ const boundaryProperty = {
1700
+ type: "string",
1701
+ description: "Optional YYYY-MM-DD: the date the successor takes over — i.e. the first " +
1702
+ "day the PREDECESSOR's claim no longer held. Written verbatim to the " +
1703
+ "predecessor's valid_until, recording the valid-time handoff alongside " +
1704
+ "the supersession. This is about when the fact changed IN THE WORLD, not " +
1705
+ "when you are writing. Validity windows are half-open, so the successor's " +
1706
+ "valid_from is this same date — the two windows meet exactly and share no " +
1707
+ "day. The successor is NOT modified; the result carries a hint for setting " +
1708
+ "its valid_from in a separate call. Refuses rather than overwriting an " +
1709
+ "existing conflicting valid_until.",
1710
+ };
1586
1711
  const runIdProperty = {
1587
1712
  type: "string",
1588
1713
  description: "Optional trace/run identifier of the calling run. Recorded in the " +
@@ -1648,6 +1773,23 @@ const frontmatterProperty = {
1648
1773
  description: "Number of days after which this document is considered stale and " +
1649
1774
  "should be reviewed. null = no TTL.",
1650
1775
  },
1776
+ valid_from: {
1777
+ type: ["string", "null"],
1778
+ description: "First date (YYYY-MM-DD) on which this document's claim was true IN " +
1779
+ "THE WORLD. This is valid time, NOT the date the document was written " +
1780
+ "or edited — do not copy it from 'created' or 'updated', which are " +
1781
+ "transaction time. Set it only when you actually know when the fact " +
1782
+ "started holding; null means unknown, which is never the same as " +
1783
+ "'always true'. Inclusive.",
1784
+ },
1785
+ valid_until: {
1786
+ type: ["string", "null"],
1787
+ description: "Last date (YYYY-MM-DD) on which this document's claim was true IN " +
1788
+ "THE WORLD, inclusive. null with a valid_from means open-ended — still " +
1789
+ "true as far as the vault knows — NOT 'unknown end'. Distinct from " +
1790
+ "ttl_days, which is a promise to re-review, not a claim about when a " +
1791
+ "fact stopped holding.",
1792
+ },
1651
1793
  tags: {
1652
1794
  type: "array",
1653
1795
  items: { type: "string" },
@@ -1668,6 +1810,106 @@ const frontmatterProperty = {
1668
1810
  required: ["title", "domain", "collection", "status", "confidence", "created", "provenance"],
1669
1811
  additionalProperties: true,
1670
1812
  };
1813
+ // --- output schemas (spec 2026-07-26, Decision 3) ---------------------------
1814
+ //
1815
+ // Every write tool's ok-value is a WriteResult, so the schema is built once
1816
+ // and specialized per tool: `action` is a single-member enum on all but
1817
+ // vault_write (which also stages), and only vault_write / vault_append carry
1818
+ // the advisory and staging fields. `additionalProperties` is deliberately
1819
+ // left open — the result is additive by design (#169's supersede_hint and
1820
+ // #4's domain_warnings both arrived that way).
1821
+ const validationReportProperty = {
1822
+ type: "object",
1823
+ description: "Frontmatter validation report for the document as written. Advisory on " +
1824
+ "the lifecycle tools (it reports the document as it was already on disk); " +
1825
+ "on vault_write / vault_merge an invalid report fails the write instead.",
1826
+ properties: {
1827
+ valid: { type: "boolean", description: "True when no validation issues were found" },
1828
+ issues: {
1829
+ type: "array",
1830
+ description: "Every problem found, in discovery order",
1831
+ items: {
1832
+ type: "object",
1833
+ properties: {
1834
+ field: { type: "string", description: "Frontmatter field the issue concerns" },
1835
+ message: { type: "string", description: "What is wrong with it" },
1836
+ },
1837
+ required: ["field", "message"],
1838
+ },
1839
+ },
1840
+ },
1841
+ required: ["valid", "issues"],
1842
+ };
1843
+ const shadowProperty = {
1844
+ type: "boolean",
1845
+ description: "Present and true only when the vault runs shadow_mode: the write was " +
1846
+ "computed and logged to the shadow store but NOTHING was applied — no " +
1847
+ "file, no commit, no index update, no provenance entry.",
1848
+ };
1849
+ const domainWarningsProperty = {
1850
+ type: "array",
1851
+ items: { type: "string" },
1852
+ description: "#4 advisory epistemic-boundary warnings: this accumulation-domain write " +
1853
+ "references generative-domain documents the caller can read. Absent when " +
1854
+ "there is nothing to warn about. The write has already landed.",
1855
+ };
1856
+ // The shared WriteResult shape. `actions` and `statuses` are the closed
1857
+ // vocabularies the specific tool can emit; `properties` adds the tool's own
1858
+ // optional fields.
1859
+ function writeResultSchema(opts) {
1860
+ return {
1861
+ type: "object",
1862
+ description: opts.description,
1863
+ properties: {
1864
+ path: {
1865
+ type: "string",
1866
+ description: "Vault-relative path of the document the write targeted",
1867
+ },
1868
+ action: {
1869
+ type: "string",
1870
+ enum: [...opts.actions],
1871
+ description: "What the write did",
1872
+ },
1873
+ commit: {
1874
+ type: ["string", "null"],
1875
+ description: "Short git commit hash when the write was auto-committed; null when " +
1876
+ "the vault runs auto_commit: false, or when nothing was applied " +
1877
+ "(shadow mode, or a staged proposal).",
1878
+ },
1879
+ committed: {
1880
+ type: "boolean",
1881
+ description: "Whether the write was auto-committed to git",
1882
+ },
1883
+ status: {
1884
+ type: "string",
1885
+ enum: [...(opts.statuses ?? STATUSES)],
1886
+ description: "The document's lifecycle status after the write",
1887
+ },
1888
+ updated: {
1889
+ type: "string",
1890
+ description: "The stamped 'updated' date (YYYY-MM-DD)",
1891
+ },
1892
+ validation: validationReportProperty,
1893
+ indexUpdated: {
1894
+ type: "boolean",
1895
+ description: "Whether the search index was refreshed. False does not undo the " +
1896
+ "write — the index is a rebuildable cache.",
1897
+ },
1898
+ shadow: shadowProperty,
1899
+ ...(opts.properties ?? {}),
1900
+ },
1901
+ required: [
1902
+ "path",
1903
+ "action",
1904
+ "commit",
1905
+ "committed",
1906
+ "status",
1907
+ "updated",
1908
+ "validation",
1909
+ "indexUpdated",
1910
+ ],
1911
+ };
1912
+ }
1671
1913
  export const writeTools = [
1672
1914
  {
1673
1915
  name: "vault_write",
@@ -1708,6 +1950,49 @@ export const writeTools = [
1708
1950
  required: ["path", "body", "frontmatter", "agent"],
1709
1951
  additionalProperties: false,
1710
1952
  },
1953
+ outputSchema: writeResultSchema({
1954
+ description: "The applied write ('create' or 'update'), or — for a propose-only " +
1955
+ "role — the staged proposal that was recorded instead ('staged', " +
1956
+ "nothing written).",
1957
+ actions: ["create", "update", "staged"],
1958
+ // "pending" is the staged-proposal status: no document status exists yet.
1959
+ statuses: [...STATUSES, "pending"],
1960
+ properties: {
1961
+ supersede_hint: {
1962
+ type: "string",
1963
+ description: "#169 advisory nudge, present only when this write overwrote an " +
1964
+ "existing document: vault_supersede preserves the prior version " +
1965
+ "and its lineage instead. The write has already landed.",
1966
+ },
1967
+ domain_warnings: domainWarningsProperty,
1968
+ staged_id: {
1969
+ type: "string",
1970
+ description: "Staged-action id of the recorded proposal. Present only when " + "action is 'staged'.",
1971
+ },
1972
+ expires_at: {
1973
+ type: "string",
1974
+ description: "ISO timestamp after which the staged proposal expires unratified. " +
1975
+ "Present only when action is 'staged'.",
1976
+ },
1977
+ conflicts_with: {
1978
+ type: "array",
1979
+ items: { type: "string" },
1980
+ description: "Ids of other pending proposals contesting the same target. " +
1981
+ "Present only when action is 'staged'; empty when uncontested.",
1982
+ },
1983
+ tension_id: {
1984
+ type: ["string", "null"],
1985
+ description: "Id of the inter-proposal tension logged for the conflicting " +
1986
+ "proposals, or null when none was needed. Present only when " +
1987
+ "action is 'staged'.",
1988
+ },
1989
+ tension_error: {
1990
+ type: "string",
1991
+ description: "Why the conflict tension could not be written. The proposal is " +
1992
+ "still staged and conflicts_with still names the contenders.",
1993
+ },
1994
+ },
1995
+ }),
1711
1996
  handler: (vaultRoot, args, access) => vaultWrite(vaultRoot, args, access),
1712
1997
  },
1713
1998
  {
@@ -1738,6 +2023,12 @@ export const writeTools = [
1738
2023
  required: ["path", "section", "agent"],
1739
2024
  additionalProperties: false,
1740
2025
  },
2026
+ outputSchema: writeResultSchema({
2027
+ description: "The applied append. The document's status is unchanged — an append " +
2028
+ "only touches the body and the 'updated' / 'updated_by' stamps.",
2029
+ actions: ["append"],
2030
+ properties: { domain_warnings: domainWarningsProperty },
2031
+ }),
1741
2032
  handler: (vaultRoot, args, access) => vaultAppend(vaultRoot, args, access),
1742
2033
  },
1743
2034
  {
@@ -1761,6 +2052,11 @@ export const writeTools = [
1761
2052
  required: ["path", "agent"],
1762
2053
  additionalProperties: false,
1763
2054
  },
2055
+ outputSchema: writeResultSchema({
2056
+ description: "The applied promotion. Status is always 'canonical' on success.",
2057
+ actions: ["promote"],
2058
+ statuses: ["canonical"],
2059
+ }),
1764
2060
  handler: (vaultRoot, args, access) => vaultPromote(vaultRoot, args, access),
1765
2061
  },
1766
2062
  {
@@ -1785,12 +2081,18 @@ export const writeTools = [
1785
2081
  type: "string",
1786
2082
  description: "Optional vault-relative path of the document that replaces this one",
1787
2083
  },
2084
+ predecessor_valid_until: boundaryProperty,
1788
2085
  agent: agentProperty,
1789
2086
  base_version: baseVersionProperty,
1790
2087
  },
1791
2088
  required: ["path", "reason", "agent"],
1792
2089
  additionalProperties: false,
1793
2090
  },
2091
+ outputSchema: writeResultSchema({
2092
+ description: "The applied deprecation. Status is always 'deprecated' on success.",
2093
+ actions: ["deprecate"],
2094
+ statuses: ["deprecated"],
2095
+ }),
1794
2096
  handler: (vaultRoot, args, access) => vaultDeprecate(vaultRoot, args, access),
1795
2097
  },
1796
2098
  {
@@ -1823,6 +2125,11 @@ export const writeTools = [
1823
2125
  required: ["path", "confidence", "reason", "agent"],
1824
2126
  additionalProperties: false,
1825
2127
  },
2128
+ outputSchema: writeResultSchema({
2129
+ description: "The applied confidence change. Status is unchanged — only the " +
2130
+ "document's confidence and the 'updated' / 'updated_by' stamps moved.",
2131
+ actions: ["confidence-set"],
2132
+ }),
1826
2133
  handler: (vaultRoot, args, access) => vaultSetConfidence(vaultRoot, args, access),
1827
2134
  },
1828
2135
  {
@@ -1860,6 +2167,11 @@ export const writeTools = [
1860
2167
  required: ["path", "tier", "reason", "agent"],
1861
2168
  additionalProperties: false,
1862
2169
  },
2170
+ outputSchema: writeResultSchema({
2171
+ description: "The applied tier change. Status is unchanged — only the document's " +
2172
+ "write-protection tier and the 'updated' / 'updated_by' stamps moved.",
2173
+ actions: ["tier-set"],
2174
+ }),
1863
2175
  handler: (vaultRoot, args, access) => vaultSetTier(vaultRoot, args, access),
1864
2176
  },
1865
2177
  {
@@ -1886,12 +2198,19 @@ export const writeTools = [
1886
2198
  type: "string",
1887
2199
  description: "Optional reason recorded in the commit message",
1888
2200
  },
2201
+ predecessor_valid_until: boundaryProperty,
1889
2202
  agent: agentProperty,
1890
2203
  base_version: baseVersionProperty,
1891
2204
  },
1892
2205
  required: ["old_path", "new_path", "agent"],
1893
2206
  additionalProperties: false,
1894
2207
  },
2208
+ outputSchema: writeResultSchema({
2209
+ description: "The applied supersession, reported for the OLD document (path is " +
2210
+ "old_path). Status is always 'superseded' on success.",
2211
+ actions: ["supersede"],
2212
+ statuses: ["superseded"],
2213
+ }),
1895
2214
  handler: (vaultRoot, args, access) => vaultSupersede(vaultRoot, args, access),
1896
2215
  },
1897
2216
  {
@@ -1929,11 +2248,19 @@ export const writeTools = [
1929
2248
  "frontmatter with provenance set to 'synthesized'.",
1930
2249
  additionalProperties: true,
1931
2250
  },
2251
+ predecessor_valid_until: boundaryProperty,
1932
2252
  agent: agentProperty,
1933
2253
  },
1934
2254
  required: ["path_a", "path_b", "target_path", "body", "agent"],
1935
2255
  additionalProperties: false,
1936
2256
  },
2257
+ outputSchema: writeResultSchema({
2258
+ description: "The applied merge, reported for the TARGET document (path is " +
2259
+ "target_path); the superseded sources are written under the same " +
2260
+ "commit and are not enumerated here. 'commit' covers all three files, " +
2261
+ "and 'indexUpdated' is true only when every written file reindexed.",
2262
+ actions: ["merge"],
2263
+ }),
1937
2264
  handler: (vaultRoot, args, access) => vaultMerge(vaultRoot, args, access),
1938
2265
  },
1939
2266
  ];