daftari 1.31.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 (239) hide show
  1. package/CHANGELOG.md +179 -1
  2. package/README.md +89 -9
  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 +12 -0
  54. package/dist/cli.js.map +1 -1
  55. package/dist/consolidate/index.d.ts.map +1 -1
  56. package/dist/consolidate/index.js +10 -12
  57. package/dist/consolidate/index.js.map +1 -1
  58. package/dist/curation/edges.d.ts.map +1 -1
  59. package/dist/curation/edges.js +36 -17
  60. package/dist/curation/edges.js.map +1 -1
  61. package/dist/curation/lint-voice.d.ts +3 -0
  62. package/dist/curation/lint-voice.d.ts.map +1 -0
  63. package/dist/curation/lint-voice.js +87 -0
  64. package/dist/curation/lint-voice.js.map +1 -0
  65. package/dist/curation/lint.d.ts +7 -1
  66. package/dist/curation/lint.d.ts.map +1 -1
  67. package/dist/curation/lint.js +62 -18
  68. package/dist/curation/lint.js.map +1 -1
  69. package/dist/curation/shadow.d.ts +1 -0
  70. package/dist/curation/shadow.d.ts.map +1 -1
  71. package/dist/curation/shadow.js +17 -11
  72. package/dist/curation/shadow.js.map +1 -1
  73. package/dist/curation/staged-actions.d.ts +1 -0
  74. package/dist/curation/staged-actions.d.ts.map +1 -1
  75. package/dist/curation/staged-actions.js +21 -24
  76. package/dist/curation/staged-actions.js.map +1 -1
  77. package/dist/curation/validity.d.ts +20 -0
  78. package/dist/curation/validity.d.ts.map +1 -0
  79. package/dist/curation/validity.js +191 -0
  80. package/dist/curation/validity.js.map +1 -0
  81. package/dist/eval/generate.d.ts.map +1 -1
  82. package/dist/eval/generate.js +16 -0
  83. package/dist/eval/generate.js.map +1 -1
  84. package/dist/eval/index.d.ts +1 -0
  85. package/dist/eval/index.d.ts.map +1 -1
  86. package/dist/eval/index.js +79 -28
  87. package/dist/eval/index.js.map +1 -1
  88. package/dist/eval/llm-openrouter.d.ts.map +1 -1
  89. package/dist/eval/llm-openrouter.js +158 -65
  90. package/dist/eval/llm-openrouter.js.map +1 -1
  91. package/dist/fence/detect.d.ts +10 -0
  92. package/dist/fence/detect.d.ts.map +1 -0
  93. package/dist/fence/detect.js +161 -0
  94. package/dist/fence/detect.js.map +1 -0
  95. package/dist/fence/index.d.ts +22 -0
  96. package/dist/fence/index.d.ts.map +1 -0
  97. package/dist/fence/index.js +117 -0
  98. package/dist/fence/index.js.map +1 -0
  99. package/dist/frontmatter/schema.d.ts.map +1 -1
  100. package/dist/frontmatter/schema.js +26 -0
  101. package/dist/frontmatter/schema.js.map +1 -1
  102. package/dist/frontmatter/types.d.ts +3 -1
  103. package/dist/frontmatter/types.d.ts.map +1 -1
  104. package/dist/frontmatter/types.js +2 -0
  105. package/dist/frontmatter/types.js.map +1 -1
  106. package/dist/holders/registry.d.ts +8 -0
  107. package/dist/holders/registry.d.ts.map +1 -0
  108. package/dist/holders/registry.js +18 -0
  109. package/dist/holders/registry.js.map +1 -0
  110. package/dist/holders/types.d.ts +10 -0
  111. package/dist/holders/types.d.ts.map +1 -0
  112. package/dist/holders/types.js +2 -0
  113. package/dist/holders/types.js.map +1 -0
  114. package/dist/index.d.ts.map +1 -1
  115. package/dist/index.js +10 -6
  116. package/dist/index.js.map +1 -1
  117. package/dist/interview/index.d.ts +7 -0
  118. package/dist/interview/index.d.ts.map +1 -0
  119. package/dist/interview/index.js +219 -0
  120. package/dist/interview/index.js.map +1 -0
  121. package/dist/interview/questions.d.ts +18 -0
  122. package/dist/interview/questions.d.ts.map +1 -0
  123. package/dist/interview/questions.js +201 -0
  124. package/dist/interview/questions.js.map +1 -0
  125. package/dist/interview/transcript.d.ts +23 -0
  126. package/dist/interview/transcript.d.ts.map +1 -0
  127. package/dist/interview/transcript.js +155 -0
  128. package/dist/interview/transcript.js.map +1 -0
  129. package/dist/okf/export.d.ts.map +1 -1
  130. package/dist/okf/export.js +4 -2
  131. package/dist/okf/export.js.map +1 -1
  132. package/dist/okf/import.d.ts.map +1 -1
  133. package/dist/okf/import.js +11 -3
  134. package/dist/okf/import.js.map +1 -1
  135. package/dist/okf/index.d.ts.map +1 -1
  136. package/dist/okf/index.js +13 -1
  137. package/dist/okf/index.js.map +1 -1
  138. package/dist/okf/map.d.ts +11 -0
  139. package/dist/okf/map.d.ts.map +1 -1
  140. package/dist/okf/map.js +191 -13
  141. package/dist/okf/map.js.map +1 -1
  142. package/dist/okf/types.d.ts +6 -2
  143. package/dist/okf/types.d.ts.map +1 -1
  144. package/dist/okf/types.js +39 -5
  145. package/dist/okf/types.js.map +1 -1
  146. package/dist/resources.d.ts +27 -0
  147. package/dist/resources.d.ts.map +1 -0
  148. package/dist/resources.js +169 -0
  149. package/dist/resources.js.map +1 -0
  150. package/dist/search/current-source.d.ts +1 -0
  151. package/dist/search/current-source.d.ts.map +1 -1
  152. package/dist/search/current-source.js +3 -1
  153. package/dist/search/current-source.js.map +1 -1
  154. package/dist/search/hybrid.d.ts +5 -0
  155. package/dist/search/hybrid.d.ts.map +1 -1
  156. package/dist/search/hybrid.js +25 -9
  157. package/dist/search/hybrid.js.map +1 -1
  158. package/dist/search/reindex.d.ts +3 -0
  159. package/dist/search/reindex.d.ts.map +1 -1
  160. package/dist/search/reindex.js +78 -23
  161. package/dist/search/reindex.js.map +1 -1
  162. package/dist/search/valid-at-source.d.ts +25 -0
  163. package/dist/search/valid-at-source.d.ts.map +1 -0
  164. package/dist/search/valid-at-source.js +131 -0
  165. package/dist/search/valid-at-source.js.map +1 -0
  166. package/dist/search/watcher.d.ts.map +1 -1
  167. package/dist/search/watcher.js +8 -17
  168. package/dist/search/watcher.js.map +1 -1
  169. package/dist/serve/index.d.ts.map +1 -1
  170. package/dist/serve/index.js +58 -89
  171. package/dist/serve/index.js.map +1 -1
  172. package/dist/server.d.ts +3 -1
  173. package/dist/server.d.ts.map +1 -1
  174. package/dist/server.js +159 -11
  175. package/dist/server.js.map +1 -1
  176. package/dist/sleep/cycle.d.ts.map +1 -1
  177. package/dist/sleep/cycle.js +20 -4
  178. package/dist/sleep/cycle.js.map +1 -1
  179. package/dist/storage/index-db.d.ts +7 -1
  180. package/dist/storage/index-db.d.ts.map +1 -1
  181. package/dist/storage/index-db.js +134 -8
  182. package/dist/storage/index-db.js.map +1 -1
  183. package/dist/tools/canon.d.ts +3 -0
  184. package/dist/tools/canon.d.ts.map +1 -0
  185. package/dist/tools/canon.js +177 -0
  186. package/dist/tools/canon.js.map +1 -0
  187. package/dist/tools/consumes.d.ts.map +1 -1
  188. package/dist/tools/consumes.js +47 -1
  189. package/dist/tools/consumes.js.map +1 -1
  190. package/dist/tools/curation.d.ts +2 -0
  191. package/dist/tools/curation.d.ts.map +1 -1
  192. package/dist/tools/curation.js +506 -3
  193. package/dist/tools/curation.js.map +1 -1
  194. package/dist/tools/edge-staleness.d.ts.map +1 -1
  195. package/dist/tools/edge-staleness.js +115 -0
  196. package/dist/tools/edge-staleness.js.map +1 -1
  197. package/dist/tools/edges.d.ts.map +1 -1
  198. package/dist/tools/edges.js +94 -0
  199. package/dist/tools/edges.js.map +1 -1
  200. package/dist/tools/read.d.ts +14 -0
  201. package/dist/tools/read.d.ts.map +1 -1
  202. package/dist/tools/read.js +452 -51
  203. package/dist/tools/read.js.map +1 -1
  204. package/dist/tools/receipt.d.ts +1 -1
  205. package/dist/tools/receipt.d.ts.map +1 -1
  206. package/dist/tools/receipt.js +147 -2
  207. package/dist/tools/receipt.js.map +1 -1
  208. package/dist/tools/search.d.ts.map +1 -1
  209. package/dist/tools/search.js +454 -3
  210. package/dist/tools/search.js.map +1 -1
  211. package/dist/tools/staged-actions.d.ts +7 -0
  212. package/dist/tools/staged-actions.d.ts.map +1 -1
  213. package/dist/tools/staged-actions.js +138 -36
  214. package/dist/tools/staged-actions.js.map +1 -1
  215. package/dist/tools/themes.d.ts.map +1 -1
  216. package/dist/tools/themes.js +120 -0
  217. package/dist/tools/themes.js.map +1 -1
  218. package/dist/tools/tier1.d.ts.map +1 -1
  219. package/dist/tools/tier1.js +56 -0
  220. package/dist/tools/tier1.js.map +1 -1
  221. package/dist/tools/tier2.d.ts.map +1 -1
  222. package/dist/tools/tier2.js +111 -1
  223. package/dist/tools/tier2.js.map +1 -1
  224. package/dist/tools/witness.d.ts.map +1 -1
  225. package/dist/tools/witness.js +93 -0
  226. package/dist/tools/witness.js.map +1 -1
  227. package/dist/tools/write.d.ts +1 -0
  228. package/dist/tools/write.d.ts.map +1 -1
  229. package/dist/tools/write.js +479 -216
  230. package/dist/tools/write.js.map +1 -1
  231. package/dist/utils/config.d.ts +2 -0
  232. package/dist/utils/config.d.ts.map +1 -1
  233. package/dist/utils/config.js +160 -86
  234. package/dist/utils/config.js.map +1 -1
  235. package/dist/utils/dates.d.ts +1 -0
  236. package/dist/utils/dates.d.ts.map +1 -1
  237. package/dist/utils/dates.js +5 -0
  238. package/dist/utils/dates.js.map +1 -1
  239. package/package.json +5 -2
@@ -8,12 +8,13 @@ import { computeDecay } from "../curation/decay.js";
8
8
  import { compiledUpstreamStaleness, loadCompiledStaleContext, splitUpstreamVisibility, } from "../curation/edge-staleness.js";
9
9
  import { readProvenanceLog } from "../curation/provenance.js";
10
10
  import { recordRead } from "../curation/read-log.js";
11
- import { listStaleFiles } from "../curation/staleness.js";
11
+ import { computeStaleness } from "../curation/staleness.js";
12
12
  import { structuralDecay } from "../curation/structural.js";
13
- import { DEFAULT_TENSION_STATUS, listTensions } from "../curation/tension.js";
13
+ import { DEFAULT_TENSION_STATUS, listTensions, TENSION_KINDS } from "../curation/tension.js";
14
14
  import { sourceReadable, visibleTensions } from "../curation/tension-access.js";
15
+ import { computeValidity } from "../curation/validity.js";
15
16
  import { parseDocument } from "../frontmatter/parser.js";
16
- import { DOMAINS, err, ok, STATUSES, } from "../frontmatter/types.js";
17
+ import { CONFIDENCES, DOMAINS, err, ok, PROVENANCES, STATUSES, TIERS, } from "../frontmatter/types.js";
17
18
  import { contestedFor } from "../search/contested.js";
18
19
  import { getProvider } from "../search/vector.js";
19
20
  import { countDimMismatches, openIndexDb } from "../storage/index-db.js";
@@ -131,6 +132,10 @@ export async function vaultRead(vaultRoot, path, access, runId) {
131
132
  validation: parsed.value.validation,
132
133
  hasFrontmatter: parsed.value.hasFrontmatter,
133
134
  decay: computeDecay(parsed.value.frontmatter),
135
+ // Evaluated against today. No index access and no RBAC branch — these
136
+ // fields belong to a document the caller has already been permitted to
137
+ // read.
138
+ validity: computeValidity(parsed.value.frontmatter, new Date().toISOString().slice(0, 10)),
134
139
  upstream_staleness: upstream,
135
140
  structural,
136
141
  ...(contestedResult
@@ -141,17 +146,21 @@ export async function vaultRead(vaultRoot, path, access, runId) {
141
146
  }
142
147
  // A document's collection is its frontmatter `collection`, falling back to the
143
148
  // top-level directory of its vault-relative path.
144
- function collectionOf(relPath, fm) {
149
+ //
150
+ // Exported because the MCP resource layer (src/resources.ts) gates
151
+ // `resources/read` on the same predicate vault_read uses. One visibility rule,
152
+ // not two that can drift apart.
153
+ export function collectionOf(relPath, fm) {
145
154
  if (fm.collection)
146
155
  return fm.collection;
147
156
  const top = relPath.split("/")[0];
148
157
  return top ?? "";
149
158
  }
150
- export async function vaultIndex(vaultRoot, filters = {}, access) {
159
+ async function scanVaultDocs(vaultRoot) {
151
160
  const list = await listFiles(vaultRoot);
152
161
  if (!list.ok)
153
162
  return list;
154
- const entries = [];
163
+ const docs = [];
155
164
  for (const relPath of list.value) {
156
165
  const resolved = resolveVaultPath(vaultRoot, relPath);
157
166
  if (!resolved.ok)
@@ -162,49 +171,70 @@ export async function vaultIndex(vaultRoot, filters = {}, access) {
162
171
  const parsed = parseDocument(file.value);
163
172
  if (!parsed.ok)
164
173
  continue;
165
- const fm = parsed.value.frontmatter;
166
- const collection = collectionOf(relPath, fm);
167
- if (filters.collection && collection !== filters.collection)
168
- continue;
169
- if (filters.status && fm.status !== filters.status)
170
- continue;
171
- if (filters.domain && fm.domain !== filters.domain)
172
- continue;
173
- if (filters.tags && filters.tags.length > 0) {
174
- const hasAll = filters.tags.every((t) => fm.tags.includes(t));
175
- if (!hasAll)
176
- continue;
177
- }
178
- if (filters.hasUnanswered !== undefined) {
179
- if (fm.questions_raised.length > 0 !== filters.hasUnanswered)
180
- continue;
181
- }
182
- entries.push({
183
- path: relPath,
184
- title: fm.title,
185
- collection,
186
- domain: fm.domain,
187
- status: fm.status,
188
- confidence: fm.confidence,
189
- updated: fm.updated,
190
- tags: fm.tags,
191
- questionsAnswered: fm.questions_answered,
192
- questionsRaised: fm.questions_raised,
174
+ docs.push({
175
+ relPath,
176
+ frontmatter: parsed.value.frontmatter,
193
177
  valid: parsed.value.validation.valid,
194
178
  });
195
179
  }
180
+ return ok(docs);
181
+ }
182
+ function toIndexEntry(doc) {
183
+ const fm = doc.frontmatter;
184
+ return {
185
+ path: doc.relPath,
186
+ title: fm.title,
187
+ collection: collectionOf(doc.relPath, fm),
188
+ domain: fm.domain,
189
+ status: fm.status,
190
+ confidence: fm.confidence,
191
+ updated: fm.updated,
192
+ tags: fm.tags,
193
+ questionsAnswered: fm.questions_answered,
194
+ questionsRaised: fm.questions_raised,
195
+ valid: doc.valid,
196
+ };
197
+ }
198
+ function matchesIndexFilters(doc, filters) {
199
+ const fm = doc.frontmatter;
200
+ if (filters.collection && collectionOf(doc.relPath, fm) !== filters.collection)
201
+ return false;
202
+ if (filters.status && fm.status !== filters.status)
203
+ return false;
204
+ if (filters.domain && fm.domain !== filters.domain)
205
+ return false;
206
+ if (filters.tags && filters.tags.length > 0 && !filters.tags.every((t) => fm.tags.includes(t))) {
207
+ return false;
208
+ }
209
+ if (filters.hasUnanswered !== undefined) {
210
+ if (fm.questions_raised.length > 0 !== filters.hasUnanswered)
211
+ return false;
212
+ }
213
+ return true;
214
+ }
215
+ export async function vaultIndex(vaultRoot, filters = {}, access) {
216
+ const docs = await scanVaultDocs(vaultRoot);
217
+ if (!docs.ok)
218
+ return docs;
219
+ const entries = docs.value.filter((d) => matchesIndexFilters(d, filters)).map(toIndexEntry);
196
220
  // RBAC: drop documents in collections the role cannot read.
197
221
  const visible = access ? filterByReadPermission(access.role, entries) : entries;
198
222
  return ok({ count: visible.length, entries: visible });
199
223
  }
200
224
  export async function vaultStatus(vaultRoot, access) {
201
- // vault_status reports only over the documents the role can read.
202
- const index = await vaultIndex(vaultRoot, {}, access);
203
- if (!index.ok)
204
- return index;
225
+ // vault_status reports only over the documents the role can read. ONE
226
+ // whole-vault scan feeds both the index-shaped aggregates and the staleness
227
+ // distribution — scoring from the already-parsed frontmatter instead of a
228
+ // second read+parse sweep through listStaleFiles.
229
+ const scan = await scanVaultDocs(vaultRoot);
230
+ if (!scan.ok)
231
+ return scan;
232
+ const allEntries = scan.value.map(toIndexEntry);
233
+ const visibleEntries = access ? filterByReadPermission(access.role, allEntries) : allEntries;
234
+ const indexEntries = { count: visibleEntries.length, entries: visibleEntries };
205
235
  const byCollection = new Map();
206
236
  let invalidCount = 0;
207
- for (const entry of index.value.entries) {
237
+ for (const entry of indexEntries.entries) {
208
238
  byCollection.set(entry.collection, (byCollection.get(entry.collection) ?? 0) + 1);
209
239
  if (!entry.valid)
210
240
  invalidCount += 1;
@@ -212,24 +242,36 @@ export async function vaultStatus(vaultRoot, access) {
212
242
  const collections = [...byCollection.entries()]
213
243
  .sort((a, b) => a[0].localeCompare(b[0]))
214
244
  .map(([collection, count]) => ({ collection, count }));
215
- // Staleness: score every file, then keep only those the index already
216
- // deemed visible, so the distribution honours RBAC. Threshold 0 makes
217
- // listStaleFiles return every document with its decay score.
218
- const visiblePaths = new Set(index.value.entries.map((e) => e.path));
219
- const staleScan = await listStaleFiles(vaultRoot, 0);
220
- if (!staleScan.ok)
221
- return staleScan;
245
+ // Staleness distribution over the visible set, from the same scan. One
246
+ // shared instant scores every document (as listStaleFiles did) so two docs
247
+ // straddling a UTC day boundary mid-scan can't bucket inconsistently.
248
+ const scanNow = new Date();
249
+ const visiblePaths = new Set(indexEntries.entries.map((e) => e.path));
222
250
  const stalenessDistribution = {
223
251
  fresh: 0,
224
252
  aging: 0,
225
253
  stale: 0,
226
254
  total: 0,
227
255
  };
228
- for (const file of staleScan.value) {
229
- if (!visiblePaths.has(file.path))
256
+ // Same loop, same visible-set gate, same shared instant — the adoption
257
+ // monitor must never widen the denominator past what the caller can read,
258
+ // or the count leaks vault size.
259
+ const validityCoverage = { authored: 0, unknown: 0, total: 0 };
260
+ for (const doc of scan.value) {
261
+ if (!visiblePaths.has(doc.relPath))
230
262
  continue;
231
263
  stalenessDistribution.total += 1;
232
- const score = file.staleness.score;
264
+ validityCoverage.total += 1;
265
+ const hasInterval = (doc.frontmatter.valid_from ?? null) !== null ||
266
+ (doc.frontmatter.valid_until ?? null) !== null;
267
+ if (hasInterval)
268
+ validityCoverage.authored += 1;
269
+ else
270
+ validityCoverage.unknown += 1;
271
+ const score = computeStaleness({
272
+ updated: doc.frontmatter.updated,
273
+ ttl_days: doc.frontmatter.ttl_days,
274
+ }, scanNow).score;
233
275
  if (score >= 1)
234
276
  stalenessDistribution.stale += 1;
235
277
  else if (score >= 0.5)
@@ -282,11 +324,12 @@ export async function vaultStatus(vaultRoot, access) {
282
324
  }
283
325
  return ok({
284
326
  vault: vaultRoot,
285
- fileCount: index.value.count,
327
+ fileCount: indexEntries.count,
286
328
  collections,
287
329
  invalidCount,
288
330
  generatedAt: new Date().toISOString(),
289
331
  stalenessDistribution,
332
+ validityCoverage,
290
333
  unresolvedTensions: {
291
334
  count: tensionEntries.length,
292
335
  recent: recentTensions,
@@ -301,6 +344,170 @@ export async function vaultStatus(vaultRoot, access) {
301
344
  // ---------------------------------------------------------------------------
302
345
  // MCP tool definitions
303
346
  // ---------------------------------------------------------------------------
347
+ // Output-schema fragments (JSON Schema 2020-12). Shared shapes live here
348
+ // because several tools embed the same value: a schema that drifts between
349
+ // two tools describes the same type two different ways, which is worse than
350
+ // no schema at all.
351
+ //
352
+ // `additionalProperties: false` is used sparingly and only where a value is
353
+ // closed by construction. Frontmatter carries config-declared extension
354
+ // fields, `raw` is whatever the author's YAML said, and provenance entries
355
+ // are read back from an append-only log written by older versions — all three
356
+ // legitimately carry keys this schema does not name.
357
+ // Frontmatter as validateFrontmatter always produces it: every built-in field
358
+ // present and coerced, plus any config-declared extension fields.
359
+ export const FRONTMATTER_SCHEMA = {
360
+ type: "object",
361
+ properties: {
362
+ title: { type: "string" },
363
+ domain: { type: "string", enum: [...DOMAINS] },
364
+ collection: { type: "string" },
365
+ status: { type: "string", enum: [...STATUSES] },
366
+ confidence: { type: "string", enum: [...CONFIDENCES] },
367
+ created: { type: "string", description: "YYYY-MM-DD (verbatim as authored)" },
368
+ updated: { type: "string", description: "YYYY-MM-DD (verbatim as authored)" },
369
+ updated_by: { type: "string", description: "agent:<id> | human:<username>" },
370
+ provenance: { type: "string", enum: [...PROVENANCES] },
371
+ // null means no write-path tier enforcement — the pre-#141 default.
372
+ tier: { type: ["string", "null"], enum: [...TIERS, null] },
373
+ sources: { type: "array", items: { type: "string" } },
374
+ superseded_by: { type: ["string", "null"] },
375
+ ttl_days: { type: ["number", "null"] },
376
+ tags: { type: "array", items: { type: "string" } },
377
+ describes: { type: "array", items: { type: "string" } },
378
+ questions_answered: { type: "array", items: { type: "string" } },
379
+ questions_raised: { type: "array", items: { type: "string" } },
380
+ },
381
+ required: [
382
+ "title",
383
+ "domain",
384
+ "collection",
385
+ "status",
386
+ "confidence",
387
+ "created",
388
+ "updated",
389
+ "updated_by",
390
+ "provenance",
391
+ "tier",
392
+ "sources",
393
+ "superseded_by",
394
+ "ttl_days",
395
+ "tags",
396
+ "describes",
397
+ "questions_answered",
398
+ "questions_raised",
399
+ ],
400
+ };
401
+ const VALIDATION_SCHEMA = {
402
+ type: "object",
403
+ properties: {
404
+ valid: { type: "boolean" },
405
+ issues: {
406
+ type: "array",
407
+ items: {
408
+ type: "object",
409
+ properties: {
410
+ field: { type: "string" },
411
+ message: { type: "string" },
412
+ },
413
+ required: ["field", "message"],
414
+ },
415
+ },
416
+ },
417
+ required: ["valid", "issues"],
418
+ };
419
+ // computeDecay's return: null when healthy (the silent baseline), otherwise a
420
+ // level with reasons and a banner that is null for `aging` (scarcity rule).
421
+ // Exported: vault_receipt embeds the same value per cited source.
422
+ export const DECAY_SCHEMA = {
423
+ type: ["object", "null"],
424
+ properties: {
425
+ level: { type: "string", enum: ["deprecated", "warn", "aging"] },
426
+ reasons: { type: "array", items: { type: "string" } },
427
+ banner: { type: ["string", "null"] },
428
+ },
429
+ required: ["level", "reasons", "banner"],
430
+ };
431
+ // One classified upstream edge (#234). Only compiled edges can reach
432
+ // pending-broken; the other classes park in pending-unchecked.
433
+ const UPSTREAM_EDGE_SCHEMA = {
434
+ type: "object",
435
+ properties: {
436
+ unit: { type: "string" },
437
+ edge_class: { type: "string", enum: ["compiled", "declared", "earned"] },
438
+ staleness: {
439
+ type: "string",
440
+ enum: ["current", "pending-unchecked", "pending-compatible", "pending-broken"],
441
+ },
442
+ baseline: {
443
+ type: ["string", "null"],
444
+ description: "ISO timestamp the classification measured from; null when none is derivable",
445
+ },
446
+ changed_fields: { type: "array", items: { type: "string" } },
447
+ reason: { type: "string" },
448
+ },
449
+ required: ["unit", "edge_class", "staleness", "baseline", "changed_fields", "reason"],
450
+ };
451
+ // One index row / vault_index entry.
452
+ const INDEX_ENTRY_SCHEMA = {
453
+ type: "object",
454
+ properties: {
455
+ path: { type: "string", description: "Vault-relative path" },
456
+ title: { type: "string" },
457
+ collection: { type: "string" },
458
+ domain: { type: "string", enum: [...DOMAINS] },
459
+ status: { type: "string", enum: [...STATUSES] },
460
+ confidence: { type: "string", enum: [...CONFIDENCES] },
461
+ updated: { type: "string" },
462
+ tags: { type: "array", items: { type: "string" } },
463
+ questionsAnswered: { type: "array", items: { type: "string" } },
464
+ questionsRaised: { type: "array", items: { type: "string" } },
465
+ valid: { type: "boolean", description: "Whether the document's frontmatter validates" },
466
+ },
467
+ required: [
468
+ "path",
469
+ "title",
470
+ "collection",
471
+ "domain",
472
+ "status",
473
+ "confidence",
474
+ "updated",
475
+ "tags",
476
+ "questionsAnswered",
477
+ "questionsRaised",
478
+ "valid",
479
+ ],
480
+ };
481
+ // A curation-log line, replayed. Entries are read back from an append-only
482
+ // JSONL log — older versions wrote fewer keys, future ones may write more, so
483
+ // only the four always-present fields are required and the object stays open.
484
+ const PROVENANCE_ENTRY_SCHEMA = {
485
+ type: "object",
486
+ properties: {
487
+ timestamp: { type: "string", description: "ISO 8601" },
488
+ tool: { type: "string" },
489
+ file: { type: "string", description: "Vault-relative path" },
490
+ agent: { type: "string", description: "Caller-claimed identity, e.g. agent:claude-code" },
491
+ action: {
492
+ type: "string",
493
+ description: "create | update | append | promote | deprecate for a write that landed; " +
494
+ "rejected_stale for one refused by the base_version check",
495
+ },
496
+ principal: { type: "string", description: "Authenticated identity, when the server has one" },
497
+ run_id: { type: "string" },
498
+ body_changed: { type: "boolean" },
499
+ frontmatter_diff: {
500
+ type: "object",
501
+ description: "Per-field before/after for every frontmatter field the write changed",
502
+ additionalProperties: {
503
+ type: "object",
504
+ properties: { before: {}, after: {} },
505
+ },
506
+ },
507
+ reason: { type: "string" },
508
+ },
509
+ required: ["timestamp", "tool", "file", "agent", "action"],
510
+ };
304
511
  function asString(v) {
305
512
  return typeof v === "string" && v.length > 0 ? v : undefined;
306
513
  }
@@ -317,7 +524,12 @@ export const readTools = [
317
524
  annotations: { readOnlyHint: true },
318
525
  description: "Read a single vault document. Returns its markdown body, parsed " +
319
526
  "frontmatter, a validation report, a decay assessment (null when " +
320
- "healthy; otherwise level, reasons, and an optional banner), an " +
527
+ "healthy; otherwise level, reasons, and an optional banner), a " +
528
+ "validity report (valid time — whether the document's CLAIM was true " +
529
+ "in the world at a given date, which is not the same as whether the " +
530
+ "document is fresh: 'decay' answers freshness, 'validity' answers " +
531
+ "truth-in-the-world; null when the document authors no interval, which " +
532
+ "means unknown and never 'always true'), an " +
321
533
  "upstream_staleness report (#234 — per compiled input, whether it " +
322
534
  "changed since this document was compiled and what tier 1 says about " +
323
535
  "the pending change: current / pending-compatible / pending-broken; " +
@@ -345,6 +557,99 @@ export const readTools = [
345
557
  required: ["path"],
346
558
  additionalProperties: false,
347
559
  },
560
+ outputSchema: {
561
+ type: "object",
562
+ properties: {
563
+ path: { type: "string", description: "The path as requested by the caller" },
564
+ content: { type: "string", description: "Markdown body, frontmatter block stripped" },
565
+ frontmatter: FRONTMATTER_SCHEMA,
566
+ raw: {
567
+ type: "object",
568
+ description: "Frontmatter exactly as parsed from YAML, before coercion",
569
+ },
570
+ validation: VALIDATION_SCHEMA,
571
+ hasFrontmatter: { type: "boolean" },
572
+ decay: DECAY_SCHEMA,
573
+ // Null when there is nothing to say — byte-identical to a document
574
+ // with no compiled edges at all (no existence signal either way).
575
+ upstream_staleness: {
576
+ type: ["object", "null"],
577
+ properties: {
578
+ edges: {
579
+ type: "array",
580
+ items: UPSTREAM_EDGE_SCHEMA,
581
+ description: "Only upstream units the caller can read (omission, #217)",
582
+ },
583
+ hidden_pending: {
584
+ type: "string",
585
+ enum: ["none", "some", "many"],
586
+ description: "Coarse bucket over pending edges to units outside the caller's " +
587
+ "read scope — never an exact count",
588
+ },
589
+ pending_broken: {
590
+ type: "integer",
591
+ minimum: 0,
592
+ description: "Pending-broken count among the VISIBLE edges only",
593
+ },
594
+ banner: { type: ["string", "null"] },
595
+ },
596
+ required: ["edges", "hidden_pending", "pending_broken", "banner"],
597
+ },
598
+ // Null when healthy — same contract as `decay`.
599
+ structural: {
600
+ type: ["object", "null"],
601
+ properties: {
602
+ orphan: {
603
+ type: "boolean",
604
+ description: "No document the caller can read links here",
605
+ },
606
+ deprecated_still_linked: {
607
+ type: ["object", "null"],
608
+ properties: {
609
+ canonical_linkers: { type: "array", items: { type: "string" } },
610
+ },
611
+ required: ["canonical_linkers"],
612
+ },
613
+ banner: { type: "string" },
614
+ },
615
+ required: ["orphan", "deprecated_still_linked", "banner"],
616
+ },
617
+ // Absent (both fields) when no visible unresolved tension touches the
618
+ // document. `contested` is capped; `contestedCount` is the true total.
619
+ contested: {
620
+ type: "array",
621
+ items: {
622
+ type: "object",
623
+ properties: {
624
+ id: { type: "string", description: "Absent only for legacy entries" },
625
+ kind: { type: "string", enum: [...TENSION_KINDS] },
626
+ counterpart: {
627
+ type: "string",
628
+ description: "Canonical vault-relative path of the other side",
629
+ },
630
+ claimSelf: { type: "string" },
631
+ claimOther: { type: "string" },
632
+ loggedAt: { type: "string", description: "Entry date, YYYY-MM-DD" },
633
+ },
634
+ required: ["kind", "counterpart", "claimSelf", "claimOther", "loggedAt"],
635
+ },
636
+ },
637
+ contestedCount: { type: "integer", minimum: 0 },
638
+ version: { type: "string", description: "SHA-256 (hex) of the raw file bytes" },
639
+ },
640
+ required: [
641
+ "path",
642
+ "content",
643
+ "frontmatter",
644
+ "raw",
645
+ "validation",
646
+ "hasFrontmatter",
647
+ "decay",
648
+ "upstream_staleness",
649
+ "structural",
650
+ "version",
651
+ ],
652
+ },
348
653
  handler: (vaultRoot, args, access) => {
349
654
  const runId = readRunId(args, "vault_read");
350
655
  if (!runId.ok)
@@ -386,6 +691,18 @@ export const readTools = [
386
691
  },
387
692
  additionalProperties: false,
388
693
  },
694
+ outputSchema: {
695
+ type: "object",
696
+ properties: {
697
+ count: {
698
+ type: "integer",
699
+ minimum: 0,
700
+ description: "Number of entries returned (post-RBAC, post-filter)",
701
+ },
702
+ entries: { type: "array", items: INDEX_ENTRY_SCHEMA },
703
+ },
704
+ required: ["count", "entries"],
705
+ },
389
706
  handler: (vaultRoot, args, access) => vaultIndex(vaultRoot, {
390
707
  collection: asString(args.collection),
391
708
  status: asString(args.status),
@@ -406,6 +723,90 @@ export const readTools = [
406
723
  properties: {},
407
724
  additionalProperties: false,
408
725
  },
726
+ outputSchema: {
727
+ type: "object",
728
+ properties: {
729
+ vault: { type: "string", description: "Absolute path of the vault root" },
730
+ fileCount: {
731
+ type: "integer",
732
+ minimum: 0,
733
+ description: "Documents the caller can read",
734
+ },
735
+ collections: {
736
+ type: "array",
737
+ items: {
738
+ type: "object",
739
+ properties: {
740
+ collection: { type: "string" },
741
+ count: { type: "integer", minimum: 0 },
742
+ },
743
+ required: ["collection", "count"],
744
+ },
745
+ },
746
+ invalidCount: { type: "integer", minimum: 0 },
747
+ generatedAt: { type: "string", description: "ISO 8601" },
748
+ // fresh (< 0.5 of TTL elapsed), aging (>= 0.5, not expired), stale
749
+ // (>= 1.0). `total` equals the role's visible file count.
750
+ stalenessDistribution: {
751
+ type: "object",
752
+ properties: {
753
+ fresh: { type: "integer", minimum: 0 },
754
+ aging: { type: "integer", minimum: 0 },
755
+ stale: { type: "integer", minimum: 0 },
756
+ total: { type: "integer", minimum: 0 },
757
+ },
758
+ required: ["fresh", "aging", "stale", "total"],
759
+ },
760
+ unresolvedTensions: {
761
+ type: "object",
762
+ properties: {
763
+ count: { type: "integer", minimum: 0 },
764
+ recent: {
765
+ type: "array",
766
+ maxItems: 5,
767
+ items: {
768
+ type: "object",
769
+ properties: {
770
+ title: { type: "string" },
771
+ date: { type: "string", description: "YYYY-MM-DD" },
772
+ },
773
+ required: ["title", "date"],
774
+ },
775
+ },
776
+ },
777
+ required: ["count", "recent"],
778
+ },
779
+ recentWrites: {
780
+ type: "object",
781
+ properties: {
782
+ count: { type: "integer", minimum: 0 },
783
+ entries: {
784
+ type: "array",
785
+ maxItems: 10,
786
+ items: PROVENANCE_ENTRY_SCHEMA,
787
+ },
788
+ },
789
+ required: ["count", "entries"],
790
+ },
791
+ embeddingDimMismatches: {
792
+ type: "integer",
793
+ minimum: 0,
794
+ description: "Embedding cache rows for the active model whose stored dim does not " +
795
+ "match the provider's; non-zero means those chunks are skipped in ranking",
796
+ },
797
+ },
798
+ required: [
799
+ "vault",
800
+ "fileCount",
801
+ "collections",
802
+ "invalidCount",
803
+ "generatedAt",
804
+ "stalenessDistribution",
805
+ "unresolvedTensions",
806
+ "recentWrites",
807
+ "embeddingDimMismatches",
808
+ ],
809
+ },
409
810
  handler: (vaultRoot, _args, access) => vaultStatus(vaultRoot, access),
410
811
  },
411
812
  ];