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.
- package/CHANGELOG.md +179 -1
- package/README.md +89 -9
- package/dist/access/rbac.d.ts +1 -0
- package/dist/access/rbac.d.ts.map +1 -1
- package/dist/access/rbac.js +16 -0
- package/dist/access/rbac.js.map +1 -1
- package/dist/asof/index.d.ts.map +1 -1
- package/dist/asof/index.js +23 -2
- package/dist/asof/index.js.map +1 -1
- package/dist/asof/report.d.ts.map +1 -1
- package/dist/asof/report.js +24 -0
- package/dist/asof/report.js.map +1 -1
- package/dist/asof/snapshot.d.ts +7 -1
- package/dist/asof/snapshot.d.ts.map +1 -1
- package/dist/asof/snapshot.js +28 -1
- package/dist/asof/snapshot.js.map +1 -1
- package/dist/backfill/derive.d.ts.map +1 -1
- package/dist/backfill/derive.js +7 -0
- package/dist/backfill/derive.js.map +1 -1
- package/dist/canary/fixtures.d.ts +12 -0
- package/dist/canary/fixtures.d.ts.map +1 -0
- package/dist/canary/fixtures.js +132 -0
- package/dist/canary/fixtures.js.map +1 -0
- package/dist/canary/index.d.ts +16 -0
- package/dist/canary/index.d.ts.map +1 -0
- package/dist/canary/index.js +105 -0
- package/dist/canary/index.js.map +1 -0
- package/dist/canary/run.d.ts +39 -0
- package/dist/canary/run.d.ts.map +1 -0
- package/dist/canary/run.js +266 -0
- package/dist/canary/run.js.map +1 -0
- package/dist/canary/stats.d.ts +36 -0
- package/dist/canary/stats.d.ts.map +1 -0
- package/dist/canary/stats.js +143 -0
- package/dist/canary/stats.js.map +1 -0
- package/dist/canon/index.d.ts +15 -0
- package/dist/canon/index.d.ts.map +1 -0
- package/dist/canon/index.js +167 -0
- package/dist/canon/index.js.map +1 -0
- package/dist/canon/resolve.d.ts +12 -0
- package/dist/canon/resolve.d.ts.map +1 -0
- package/dist/canon/resolve.js +67 -0
- package/dist/canon/resolve.js.map +1 -0
- package/dist/canon/topic.d.ts +20 -0
- package/dist/canon/topic.d.ts.map +1 -0
- package/dist/canon/topic.js +81 -0
- package/dist/canon/topic.js.map +1 -0
- package/dist/canon/types.d.ts +37 -0
- package/dist/canon/types.d.ts.map +1 -0
- package/dist/canon/types.js +9 -0
- package/dist/canon/types.js.map +1 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +12 -0
- package/dist/cli.js.map +1 -1
- package/dist/consolidate/index.d.ts.map +1 -1
- package/dist/consolidate/index.js +10 -12
- package/dist/consolidate/index.js.map +1 -1
- package/dist/curation/edges.d.ts.map +1 -1
- package/dist/curation/edges.js +36 -17
- package/dist/curation/edges.js.map +1 -1
- package/dist/curation/lint-voice.d.ts +3 -0
- package/dist/curation/lint-voice.d.ts.map +1 -0
- package/dist/curation/lint-voice.js +87 -0
- package/dist/curation/lint-voice.js.map +1 -0
- package/dist/curation/lint.d.ts +7 -1
- package/dist/curation/lint.d.ts.map +1 -1
- package/dist/curation/lint.js +62 -18
- package/dist/curation/lint.js.map +1 -1
- package/dist/curation/shadow.d.ts +1 -0
- package/dist/curation/shadow.d.ts.map +1 -1
- package/dist/curation/shadow.js +17 -11
- package/dist/curation/shadow.js.map +1 -1
- package/dist/curation/staged-actions.d.ts +1 -0
- package/dist/curation/staged-actions.d.ts.map +1 -1
- package/dist/curation/staged-actions.js +21 -24
- package/dist/curation/staged-actions.js.map +1 -1
- package/dist/curation/validity.d.ts +20 -0
- package/dist/curation/validity.d.ts.map +1 -0
- package/dist/curation/validity.js +191 -0
- package/dist/curation/validity.js.map +1 -0
- package/dist/eval/generate.d.ts.map +1 -1
- package/dist/eval/generate.js +16 -0
- package/dist/eval/generate.js.map +1 -1
- package/dist/eval/index.d.ts +1 -0
- package/dist/eval/index.d.ts.map +1 -1
- package/dist/eval/index.js +79 -28
- package/dist/eval/index.js.map +1 -1
- package/dist/eval/llm-openrouter.d.ts.map +1 -1
- package/dist/eval/llm-openrouter.js +158 -65
- package/dist/eval/llm-openrouter.js.map +1 -1
- package/dist/fence/detect.d.ts +10 -0
- package/dist/fence/detect.d.ts.map +1 -0
- package/dist/fence/detect.js +161 -0
- package/dist/fence/detect.js.map +1 -0
- package/dist/fence/index.d.ts +22 -0
- package/dist/fence/index.d.ts.map +1 -0
- package/dist/fence/index.js +117 -0
- package/dist/fence/index.js.map +1 -0
- package/dist/frontmatter/schema.d.ts.map +1 -1
- package/dist/frontmatter/schema.js +26 -0
- package/dist/frontmatter/schema.js.map +1 -1
- package/dist/frontmatter/types.d.ts +3 -1
- package/dist/frontmatter/types.d.ts.map +1 -1
- package/dist/frontmatter/types.js +2 -0
- package/dist/frontmatter/types.js.map +1 -1
- package/dist/holders/registry.d.ts +8 -0
- package/dist/holders/registry.d.ts.map +1 -0
- package/dist/holders/registry.js +18 -0
- package/dist/holders/registry.js.map +1 -0
- package/dist/holders/types.d.ts +10 -0
- package/dist/holders/types.d.ts.map +1 -0
- package/dist/holders/types.js +2 -0
- package/dist/holders/types.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -6
- package/dist/index.js.map +1 -1
- package/dist/interview/index.d.ts +7 -0
- package/dist/interview/index.d.ts.map +1 -0
- package/dist/interview/index.js +219 -0
- package/dist/interview/index.js.map +1 -0
- package/dist/interview/questions.d.ts +18 -0
- package/dist/interview/questions.d.ts.map +1 -0
- package/dist/interview/questions.js +201 -0
- package/dist/interview/questions.js.map +1 -0
- package/dist/interview/transcript.d.ts +23 -0
- package/dist/interview/transcript.d.ts.map +1 -0
- package/dist/interview/transcript.js +155 -0
- package/dist/interview/transcript.js.map +1 -0
- package/dist/okf/export.d.ts.map +1 -1
- package/dist/okf/export.js +4 -2
- package/dist/okf/export.js.map +1 -1
- package/dist/okf/import.d.ts.map +1 -1
- package/dist/okf/import.js +11 -3
- package/dist/okf/import.js.map +1 -1
- package/dist/okf/index.d.ts.map +1 -1
- package/dist/okf/index.js +13 -1
- package/dist/okf/index.js.map +1 -1
- package/dist/okf/map.d.ts +11 -0
- package/dist/okf/map.d.ts.map +1 -1
- package/dist/okf/map.js +191 -13
- package/dist/okf/map.js.map +1 -1
- package/dist/okf/types.d.ts +6 -2
- package/dist/okf/types.d.ts.map +1 -1
- package/dist/okf/types.js +39 -5
- package/dist/okf/types.js.map +1 -1
- package/dist/resources.d.ts +27 -0
- package/dist/resources.d.ts.map +1 -0
- package/dist/resources.js +169 -0
- package/dist/resources.js.map +1 -0
- package/dist/search/current-source.d.ts +1 -0
- package/dist/search/current-source.d.ts.map +1 -1
- package/dist/search/current-source.js +3 -1
- package/dist/search/current-source.js.map +1 -1
- package/dist/search/hybrid.d.ts +5 -0
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/hybrid.js +25 -9
- package/dist/search/hybrid.js.map +1 -1
- package/dist/search/reindex.d.ts +3 -0
- package/dist/search/reindex.d.ts.map +1 -1
- package/dist/search/reindex.js +78 -23
- package/dist/search/reindex.js.map +1 -1
- package/dist/search/valid-at-source.d.ts +25 -0
- package/dist/search/valid-at-source.d.ts.map +1 -0
- package/dist/search/valid-at-source.js +131 -0
- package/dist/search/valid-at-source.js.map +1 -0
- package/dist/search/watcher.d.ts.map +1 -1
- package/dist/search/watcher.js +8 -17
- package/dist/search/watcher.js.map +1 -1
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +58 -89
- package/dist/serve/index.js.map +1 -1
- package/dist/server.d.ts +3 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +159 -11
- package/dist/server.js.map +1 -1
- package/dist/sleep/cycle.d.ts.map +1 -1
- package/dist/sleep/cycle.js +20 -4
- package/dist/sleep/cycle.js.map +1 -1
- package/dist/storage/index-db.d.ts +7 -1
- package/dist/storage/index-db.d.ts.map +1 -1
- package/dist/storage/index-db.js +134 -8
- package/dist/storage/index-db.js.map +1 -1
- package/dist/tools/canon.d.ts +3 -0
- package/dist/tools/canon.d.ts.map +1 -0
- package/dist/tools/canon.js +177 -0
- package/dist/tools/canon.js.map +1 -0
- package/dist/tools/consumes.d.ts.map +1 -1
- package/dist/tools/consumes.js +47 -1
- package/dist/tools/consumes.js.map +1 -1
- package/dist/tools/curation.d.ts +2 -0
- package/dist/tools/curation.d.ts.map +1 -1
- package/dist/tools/curation.js +506 -3
- package/dist/tools/curation.js.map +1 -1
- package/dist/tools/edge-staleness.d.ts.map +1 -1
- package/dist/tools/edge-staleness.js +115 -0
- package/dist/tools/edge-staleness.js.map +1 -1
- package/dist/tools/edges.d.ts.map +1 -1
- package/dist/tools/edges.js +94 -0
- package/dist/tools/edges.js.map +1 -1
- package/dist/tools/read.d.ts +14 -0
- package/dist/tools/read.d.ts.map +1 -1
- package/dist/tools/read.js +452 -51
- package/dist/tools/read.js.map +1 -1
- package/dist/tools/receipt.d.ts +1 -1
- package/dist/tools/receipt.d.ts.map +1 -1
- package/dist/tools/receipt.js +147 -2
- package/dist/tools/receipt.js.map +1 -1
- package/dist/tools/search.d.ts.map +1 -1
- package/dist/tools/search.js +454 -3
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/staged-actions.d.ts +7 -0
- package/dist/tools/staged-actions.d.ts.map +1 -1
- package/dist/tools/staged-actions.js +138 -36
- package/dist/tools/staged-actions.js.map +1 -1
- package/dist/tools/themes.d.ts.map +1 -1
- package/dist/tools/themes.js +120 -0
- package/dist/tools/themes.js.map +1 -1
- package/dist/tools/tier1.d.ts.map +1 -1
- package/dist/tools/tier1.js +56 -0
- package/dist/tools/tier1.js.map +1 -1
- package/dist/tools/tier2.d.ts.map +1 -1
- package/dist/tools/tier2.js +111 -1
- package/dist/tools/tier2.js.map +1 -1
- package/dist/tools/witness.d.ts.map +1 -1
- package/dist/tools/witness.js +93 -0
- package/dist/tools/witness.js.map +1 -1
- package/dist/tools/write.d.ts +1 -0
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +479 -216
- package/dist/tools/write.js.map +1 -1
- package/dist/utils/config.d.ts +2 -0
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +160 -86
- package/dist/utils/config.js.map +1 -1
- package/dist/utils/dates.d.ts +1 -0
- package/dist/utils/dates.d.ts.map +1 -1
- package/dist/utils/dates.js +5 -0
- package/dist/utils/dates.js.map +1 -1
- package/package.json +5 -2
package/dist/tools/read.js
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
-
|
|
159
|
+
async function scanVaultDocs(vaultRoot) {
|
|
151
160
|
const list = await listFiles(vaultRoot);
|
|
152
161
|
if (!list.ok)
|
|
153
162
|
return list;
|
|
154
|
-
const
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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
|
|
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
|
|
216
|
-
//
|
|
217
|
-
//
|
|
218
|
-
const
|
|
219
|
-
const
|
|
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
|
-
|
|
229
|
-
|
|
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
|
-
|
|
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:
|
|
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),
|
|
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
|
];
|