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/write.js
CHANGED
|
@@ -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,
|
|
@@ -338,6 +399,64 @@ function denyIfProposeOnly(access, tool) {
|
|
|
338
399
|
}
|
|
339
400
|
return ok(undefined);
|
|
340
401
|
}
|
|
402
|
+
// The uniform RBAC write gate. One helper because the denial string is part
|
|
403
|
+
// of the tool contract — every write tool emits the identical message shape,
|
|
404
|
+
// and it must never leak more than the collection name.
|
|
405
|
+
function requireWriteAccess(access, collection) {
|
|
406
|
+
if (access && !canWrite(access.role, collection)) {
|
|
407
|
+
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` + `collection '${collection}'`));
|
|
408
|
+
}
|
|
409
|
+
return ok(undefined);
|
|
410
|
+
}
|
|
411
|
+
async function loadTargetDocument(vaultRoot, rawPath, tool) {
|
|
412
|
+
const resolved = resolveVaultPath(vaultRoot, rawPath);
|
|
413
|
+
if (!resolved.ok)
|
|
414
|
+
return resolved;
|
|
415
|
+
const existing = await readFile(resolved.value.absPath);
|
|
416
|
+
if (!existing.ok) {
|
|
417
|
+
return err(new Error(`${tool}: document not found: ${rawPath}`));
|
|
418
|
+
}
|
|
419
|
+
const parsed = parseDocument(existing.value);
|
|
420
|
+
if (!parsed.ok)
|
|
421
|
+
return parsed;
|
|
422
|
+
const config = loadConfig(vaultRoot);
|
|
423
|
+
if (!config.ok)
|
|
424
|
+
return config;
|
|
425
|
+
return ok({
|
|
426
|
+
// Lock key, provenance, and commit path are all keyed on the CANONICAL
|
|
427
|
+
// relPath, never the raw caller string: aliased spellings of one file
|
|
428
|
+
// must contend on one lock (#127/#128).
|
|
429
|
+
relPath: resolved.value.relPath,
|
|
430
|
+
absPath: resolved.value.absPath,
|
|
431
|
+
parsed: parsed.value,
|
|
432
|
+
config: config.value,
|
|
433
|
+
});
|
|
434
|
+
}
|
|
435
|
+
// The shared performWrite tail for frontmatter-only mutations: body preserved
|
|
436
|
+
// verbatim (bodyChanged false), file text re-serialized from the new
|
|
437
|
+
// frontmatter over the existing content.
|
|
438
|
+
function performFrontmatterWrite(opts) {
|
|
439
|
+
const { target } = opts;
|
|
440
|
+
return performWrite({
|
|
441
|
+
vaultRoot: opts.vaultRoot,
|
|
442
|
+
relPath: target.relPath,
|
|
443
|
+
absPath: target.absPath,
|
|
444
|
+
agent: opts.agent,
|
|
445
|
+
tool: opts.tool,
|
|
446
|
+
action: opts.action,
|
|
447
|
+
fileText: serializeDocument(opts.newFrontmatter, target.parsed.content, target.config.schemaExtensions, target.parsed.raw),
|
|
448
|
+
newFrontmatter: opts.newFrontmatter,
|
|
449
|
+
oldFrontmatter: target.parsed.frontmatter,
|
|
450
|
+
validation: target.parsed.validation,
|
|
451
|
+
commitMessage: opts.commitMessage,
|
|
452
|
+
autoCommit: target.config.autoCommit,
|
|
453
|
+
gitDir: target.config.gitDir,
|
|
454
|
+
baseVersion: opts.baseVersion,
|
|
455
|
+
shadowMode: target.config.shadowMode,
|
|
456
|
+
principal: opts.access?.user,
|
|
457
|
+
bodyChanged: false,
|
|
458
|
+
});
|
|
459
|
+
}
|
|
341
460
|
// ---------------------------------------------------------------------------
|
|
342
461
|
// vault_write
|
|
343
462
|
// ---------------------------------------------------------------------------
|
|
@@ -470,13 +589,9 @@ export async function vaultWrite(vaultRoot, args, access) {
|
|
|
470
589
|
// collection is allowed to differ from the physical dir (e.g. a draft staged
|
|
471
590
|
// in _drafts/ that declares its destination collection); it just never widens
|
|
472
591
|
// access.
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
|
|
477
|
-
`collection '${collection}'`));
|
|
478
|
-
}
|
|
479
|
-
}
|
|
592
|
+
const writeGate = requireWriteAccess(access, targetCollection(vaultRoot, path.value));
|
|
593
|
+
if (!writeGate.ok)
|
|
594
|
+
return writeGate;
|
|
480
595
|
const resolved = resolveVaultPath(vaultRoot, path.value);
|
|
481
596
|
if (!resolved.ok)
|
|
482
597
|
return resolved;
|
|
@@ -775,13 +890,9 @@ export async function vaultAppend(vaultRoot, args, access) {
|
|
|
775
890
|
return config;
|
|
776
891
|
const extensions = config.value.schemaExtensions;
|
|
777
892
|
const oldFrontmatter = parsed.value.frontmatter;
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
|
|
782
|
-
`collection '${collection}'`));
|
|
783
|
-
}
|
|
784
|
-
}
|
|
893
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
894
|
+
if (!rbac.ok)
|
|
895
|
+
return rbac;
|
|
785
896
|
const newFrontmatter = {
|
|
786
897
|
...oldFrontmatter,
|
|
787
898
|
updated: todayISO(),
|
|
@@ -875,65 +986,42 @@ export async function vaultPromote(vaultRoot, args, access) {
|
|
|
875
986
|
if (access && !canPromote(access.role)) {
|
|
876
987
|
return err(new Error(`access denied: role '${access.roleName}' cannot promote documents`));
|
|
877
988
|
}
|
|
878
|
-
const
|
|
879
|
-
if (!
|
|
880
|
-
return
|
|
881
|
-
const
|
|
882
|
-
if (!existing.ok) {
|
|
883
|
-
return err(new Error(`vault_promote: document not found: ${path.value}`));
|
|
884
|
-
}
|
|
885
|
-
const parsed = parseDocument(existing.value);
|
|
886
|
-
if (!parsed.ok)
|
|
887
|
-
return parsed;
|
|
888
|
-
const config = loadConfig(vaultRoot);
|
|
889
|
-
if (!config.ok)
|
|
890
|
-
return config;
|
|
891
|
-
const extensions = config.value.schemaExtensions;
|
|
892
|
-
const oldFrontmatter = parsed.value.frontmatter;
|
|
989
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_promote");
|
|
990
|
+
if (!target.ok)
|
|
991
|
+
return target;
|
|
992
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
893
993
|
if (oldFrontmatter.status !== "draft") {
|
|
894
994
|
return err(new Error(`vault_promote: only draft documents can be promoted ` +
|
|
895
995
|
`(${path.value} is '${oldFrontmatter.status}')`));
|
|
896
996
|
}
|
|
897
|
-
if (!
|
|
898
|
-
const summary =
|
|
997
|
+
if (!target.value.parsed.validation.valid) {
|
|
998
|
+
const summary = target.value.parsed.validation.issues
|
|
899
999
|
.map((i) => `${i.field}: ${i.message}`)
|
|
900
1000
|
.join("; ");
|
|
901
1001
|
return err(new Error(`vault_promote: frontmatter is incomplete: ${summary}`));
|
|
902
1002
|
}
|
|
903
1003
|
// `confidence set` — the document must declare a confidence explicitly, not
|
|
904
1004
|
// ride on the validator's default.
|
|
905
|
-
const rawConfidence =
|
|
1005
|
+
const rawConfidence = target.value.parsed.raw.confidence;
|
|
906
1006
|
if (typeof rawConfidence !== "string" ||
|
|
907
1007
|
!CONFIDENCES.includes(rawConfidence)) {
|
|
908
1008
|
return err(new Error("vault_promote: confidence must be set before promotion"));
|
|
909
1009
|
}
|
|
910
|
-
|
|
911
|
-
...oldFrontmatter,
|
|
912
|
-
status: "canonical",
|
|
913
|
-
updated: todayISO(),
|
|
914
|
-
updated_by: agent.value,
|
|
915
|
-
};
|
|
916
|
-
return performWrite({
|
|
1010
|
+
return performFrontmatterWrite({
|
|
917
1011
|
vaultRoot,
|
|
918
|
-
|
|
919
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
920
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
921
|
-
relPath: resolved.value.relPath,
|
|
922
|
-
absPath: resolved.value.absPath,
|
|
1012
|
+
target: target.value,
|
|
923
1013
|
agent: agent.value,
|
|
924
1014
|
tool: "vault_promote",
|
|
925
1015
|
action: "promote",
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
1016
|
+
newFrontmatter: {
|
|
1017
|
+
...oldFrontmatter,
|
|
1018
|
+
status: "canonical",
|
|
1019
|
+
updated: todayISO(),
|
|
1020
|
+
updated_by: agent.value,
|
|
1021
|
+
},
|
|
930
1022
|
commitMessage: `vault_promote: ${path.value} draft→canonical by ${agent.value}`,
|
|
931
|
-
autoCommit: config.value.autoCommit,
|
|
932
|
-
gitDir: config.value.gitDir,
|
|
933
1023
|
baseVersion: baseVersion.value,
|
|
934
|
-
|
|
935
|
-
principal: access?.user,
|
|
936
|
-
bodyChanged: false,
|
|
1024
|
+
access,
|
|
937
1025
|
});
|
|
938
1026
|
}
|
|
939
1027
|
// ---------------------------------------------------------------------------
|
|
@@ -961,6 +1049,9 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
961
1049
|
const baseVersion = readBaseVersion(args, "vault_deprecate");
|
|
962
1050
|
if (!baseVersion.ok)
|
|
963
1051
|
return baseVersion;
|
|
1052
|
+
const boundary = readBoundary(args, "vault_deprecate");
|
|
1053
|
+
if (!boundary.ok)
|
|
1054
|
+
return boundary;
|
|
964
1055
|
let supersededBy = null;
|
|
965
1056
|
if (args.superseded_by !== undefined && args.superseded_by !== null) {
|
|
966
1057
|
if (typeof args.superseded_by !== "string") {
|
|
@@ -968,58 +1059,45 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
968
1059
|
}
|
|
969
1060
|
supersededBy = args.superseded_by;
|
|
970
1061
|
}
|
|
971
|
-
const
|
|
972
|
-
if (!
|
|
973
|
-
return
|
|
974
|
-
const
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
if (!canWrite(access.role, collection)) {
|
|
989
|
-
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
|
|
990
|
-
`collection '${collection}'`));
|
|
991
|
-
}
|
|
992
|
-
}
|
|
993
|
-
const newFrontmatter = {
|
|
994
|
-
...oldFrontmatter,
|
|
995
|
-
status: "deprecated",
|
|
996
|
-
superseded_by: supersededBy,
|
|
997
|
-
updated: todayISO(),
|
|
998
|
-
updated_by: agent.value,
|
|
999
|
-
};
|
|
1000
|
-
return performWrite({
|
|
1062
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_deprecate");
|
|
1063
|
+
if (!target.ok)
|
|
1064
|
+
return target;
|
|
1065
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1066
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1067
|
+
if (!rbac.ok)
|
|
1068
|
+
return rbac;
|
|
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({
|
|
1001
1079
|
vaultRoot,
|
|
1002
|
-
|
|
1003
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
1004
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
1005
|
-
relPath: resolved.value.relPath,
|
|
1006
|
-
absPath: resolved.value.absPath,
|
|
1080
|
+
target: target.value,
|
|
1007
1081
|
agent: agent.value,
|
|
1008
1082
|
tool: "vault_deprecate",
|
|
1009
1083
|
action: "deprecate",
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1084
|
+
newFrontmatter: {
|
|
1085
|
+
...oldFrontmatter,
|
|
1086
|
+
status: "deprecated",
|
|
1087
|
+
superseded_by: supersededBy,
|
|
1088
|
+
...(validUntil !== null ? { valid_until: validUntil } : {}),
|
|
1089
|
+
updated: todayISO(),
|
|
1090
|
+
updated_by: agent.value,
|
|
1091
|
+
},
|
|
1014
1092
|
commitMessage: `vault_deprecate: ${path.value} by ${agent.value} — ${reason.value}` +
|
|
1015
1093
|
(supersededBy ? ` (superseded by ${supersededBy})` : ""),
|
|
1016
|
-
autoCommit: config.value.autoCommit,
|
|
1017
|
-
gitDir: config.value.gitDir,
|
|
1018
1094
|
baseVersion: baseVersion.value,
|
|
1019
|
-
|
|
1020
|
-
principal: access?.user,
|
|
1021
|
-
bodyChanged: false,
|
|
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)
|
|
@@ -1053,28 +1131,13 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
|
|
|
1053
1131
|
const baseVersion = readBaseVersion(args, "vault_set_confidence");
|
|
1054
1132
|
if (!baseVersion.ok)
|
|
1055
1133
|
return baseVersion;
|
|
1056
|
-
const
|
|
1057
|
-
if (!
|
|
1058
|
-
return
|
|
1059
|
-
const
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
const parsed = parseDocument(existing.value);
|
|
1064
|
-
if (!parsed.ok)
|
|
1065
|
-
return parsed;
|
|
1066
|
-
const config = loadConfig(vaultRoot);
|
|
1067
|
-
if (!config.ok)
|
|
1068
|
-
return config;
|
|
1069
|
-
const extensions = config.value.schemaExtensions;
|
|
1070
|
-
const oldFrontmatter = parsed.value.frontmatter;
|
|
1071
|
-
if (access) {
|
|
1072
|
-
const collection = collectionOf(path.value, oldFrontmatter);
|
|
1073
|
-
if (!canWrite(access.role, collection)) {
|
|
1074
|
-
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
|
|
1075
|
-
`collection '${collection}'`));
|
|
1076
|
-
}
|
|
1077
|
-
}
|
|
1134
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_confidence");
|
|
1135
|
+
if (!target.ok)
|
|
1136
|
+
return target;
|
|
1137
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1138
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1139
|
+
if (!rbac.ok)
|
|
1140
|
+
return rbac;
|
|
1078
1141
|
// No-op guard: a confidence already at the target would churn a commit for no
|
|
1079
1142
|
// change. Surface it as an error so a redundant staged confidence-up does not
|
|
1080
1143
|
// silently no-op (and a caller learns the value was already set). Compare
|
|
@@ -1083,41 +1146,29 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
|
|
|
1083
1146
|
// validated value would wrongly reject set_confidence(…, "low") on a doc that
|
|
1084
1147
|
// never declared one and never write the field (the trap vault_promote dodges
|
|
1085
1148
|
// the same way, via parsed.value.raw.confidence).
|
|
1086
|
-
const rawConfidence =
|
|
1149
|
+
const rawConfidence = target.value.parsed.raw.confidence;
|
|
1087
1150
|
const currentConfidence = typeof rawConfidence === "string" && CONFIDENCES.includes(rawConfidence)
|
|
1088
1151
|
? rawConfidence
|
|
1089
1152
|
: undefined;
|
|
1090
1153
|
if (currentConfidence === confidence.value) {
|
|
1091
1154
|
return err(new Error(`vault_set_confidence: ${path.value} confidence is already '${confidence.value}'`));
|
|
1092
1155
|
}
|
|
1093
|
-
|
|
1094
|
-
...oldFrontmatter,
|
|
1095
|
-
confidence: confidence.value,
|
|
1096
|
-
updated: todayISO(),
|
|
1097
|
-
updated_by: agent.value,
|
|
1098
|
-
};
|
|
1099
|
-
return performWrite({
|
|
1156
|
+
return performFrontmatterWrite({
|
|
1100
1157
|
vaultRoot,
|
|
1101
|
-
|
|
1102
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
1103
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
1104
|
-
relPath: resolved.value.relPath,
|
|
1105
|
-
absPath: resolved.value.absPath,
|
|
1158
|
+
target: target.value,
|
|
1106
1159
|
agent: agent.value,
|
|
1107
1160
|
tool: "vault_set_confidence",
|
|
1108
1161
|
action: "confidence-set",
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1162
|
+
newFrontmatter: {
|
|
1163
|
+
...oldFrontmatter,
|
|
1164
|
+
confidence: confidence.value,
|
|
1165
|
+
updated: todayISO(),
|
|
1166
|
+
updated_by: agent.value,
|
|
1167
|
+
},
|
|
1113
1168
|
commitMessage: `vault_set_confidence: ${path.value} ${oldFrontmatter.confidence}→${confidence.value} ` +
|
|
1114
1169
|
`by ${agent.value} — ${reason.value}`,
|
|
1115
|
-
autoCommit: config.value.autoCommit,
|
|
1116
|
-
gitDir: config.value.gitDir,
|
|
1117
1170
|
baseVersion: baseVersion.value,
|
|
1118
|
-
|
|
1119
|
-
principal: access?.user,
|
|
1120
|
-
bodyChanged: false,
|
|
1171
|
+
access,
|
|
1121
1172
|
});
|
|
1122
1173
|
}
|
|
1123
1174
|
// ---------------------------------------------------------------------------
|
|
@@ -1156,28 +1207,13 @@ export async function vaultSetTier(vaultRoot, args, access) {
|
|
|
1156
1207
|
const baseVersion = readBaseVersion(args, "vault_set_tier");
|
|
1157
1208
|
if (!baseVersion.ok)
|
|
1158
1209
|
return baseVersion;
|
|
1159
|
-
const
|
|
1160
|
-
if (!
|
|
1161
|
-
return
|
|
1162
|
-
const
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
const parsed = parseDocument(existing.value);
|
|
1167
|
-
if (!parsed.ok)
|
|
1168
|
-
return parsed;
|
|
1169
|
-
const config = loadConfig(vaultRoot);
|
|
1170
|
-
if (!config.ok)
|
|
1171
|
-
return config;
|
|
1172
|
-
const extensions = config.value.schemaExtensions;
|
|
1173
|
-
const oldFrontmatter = parsed.value.frontmatter;
|
|
1174
|
-
if (access) {
|
|
1175
|
-
const collection = collectionOf(path.value, oldFrontmatter);
|
|
1176
|
-
if (!canWrite(access.role, collection)) {
|
|
1177
|
-
return err(new Error(`access denied: role '${access.roleName}' cannot write to ` +
|
|
1178
|
-
`collection '${collection}'`));
|
|
1179
|
-
}
|
|
1180
|
-
}
|
|
1210
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_tier");
|
|
1211
|
+
if (!target.ok)
|
|
1212
|
+
return target;
|
|
1213
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1214
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1215
|
+
if (!rbac.ok)
|
|
1216
|
+
return rbac;
|
|
1181
1217
|
// The manual consent boundary: only a human identity may lift `manual`.
|
|
1182
1218
|
if (oldFrontmatter.tier === "manual" &&
|
|
1183
1219
|
newTier !== "manual" &&
|
|
@@ -1188,41 +1224,29 @@ export async function vaultSetTier(vaultRoot, args, access) {
|
|
|
1188
1224
|
// No-op guard, same shape as vault_set_confidence: compare against the raw
|
|
1189
1225
|
// on-disk value so an invalid raw tier (validated down to null) can still be
|
|
1190
1226
|
// set to any member.
|
|
1191
|
-
const rawTier =
|
|
1227
|
+
const rawTier = target.value.parsed.raw.tier;
|
|
1192
1228
|
const currentTier = typeof rawTier === "string" && TIERS.includes(rawTier)
|
|
1193
1229
|
? rawTier
|
|
1194
1230
|
: undefined;
|
|
1195
1231
|
if (currentTier === newTier) {
|
|
1196
1232
|
return err(new Error(`vault_set_tier: ${path.value} tier is already '${newTier}'`));
|
|
1197
1233
|
}
|
|
1198
|
-
|
|
1199
|
-
...oldFrontmatter,
|
|
1200
|
-
tier: newTier,
|
|
1201
|
-
updated: todayISO(),
|
|
1202
|
-
updated_by: agent.value,
|
|
1203
|
-
};
|
|
1204
|
-
return performWrite({
|
|
1234
|
+
return performFrontmatterWrite({
|
|
1205
1235
|
vaultRoot,
|
|
1206
|
-
|
|
1207
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
1208
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
1209
|
-
relPath: resolved.value.relPath,
|
|
1210
|
-
absPath: resolved.value.absPath,
|
|
1236
|
+
target: target.value,
|
|
1211
1237
|
agent: agent.value,
|
|
1212
1238
|
tool: "vault_set_tier",
|
|
1213
1239
|
action: "tier-set",
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1240
|
+
newFrontmatter: {
|
|
1241
|
+
...oldFrontmatter,
|
|
1242
|
+
tier: newTier,
|
|
1243
|
+
updated: todayISO(),
|
|
1244
|
+
updated_by: agent.value,
|
|
1245
|
+
},
|
|
1218
1246
|
commitMessage: `vault_set_tier: ${path.value} ${oldFrontmatter.tier ?? "unset"}→${newTier} ` +
|
|
1219
1247
|
`by ${agent.value} — ${reason.value}`,
|
|
1220
|
-
autoCommit: config.value.autoCommit,
|
|
1221
|
-
gitDir: config.value.gitDir,
|
|
1222
1248
|
baseVersion: baseVersion.value,
|
|
1223
|
-
|
|
1224
|
-
principal: access?.user,
|
|
1225
|
-
bodyChanged: false,
|
|
1249
|
+
access,
|
|
1226
1250
|
});
|
|
1227
1251
|
}
|
|
1228
1252
|
// ---------------------------------------------------------------------------
|
|
@@ -1251,6 +1275,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1251
1275
|
const baseVersion = readBaseVersion(args, "vault_supersede");
|
|
1252
1276
|
if (!baseVersion.ok)
|
|
1253
1277
|
return baseVersion;
|
|
1278
|
+
const boundary = readBoundary(args, "vault_supersede");
|
|
1279
|
+
if (!boundary.ok)
|
|
1280
|
+
return boundary;
|
|
1254
1281
|
let reason;
|
|
1255
1282
|
if (args.reason !== undefined && args.reason !== null) {
|
|
1256
1283
|
if (typeof args.reason !== "string") {
|
|
@@ -1284,43 +1311,46 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1284
1311
|
const config = loadConfig(vaultRoot);
|
|
1285
1312
|
if (!config.ok)
|
|
1286
1313
|
return config;
|
|
1287
|
-
const extensions = config.value.schemaExtensions;
|
|
1288
1314
|
const oldFrontmatter = parsed.value.frontmatter;
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
updated_by: agent.value,
|
|
1302
|
-
};
|
|
1303
|
-
return performWrite({
|
|
1315
|
+
const rbac = requireWriteAccess(access, collectionOf(oldPath.value, oldFrontmatter));
|
|
1316
|
+
if (!rbac.ok)
|
|
1317
|
+
return rbac;
|
|
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({
|
|
1304
1327
|
vaultRoot,
|
|
1305
1328
|
// Canonical relPath keys the lock/provenance/commit (#127/#128).
|
|
1306
|
-
|
|
1307
|
-
|
|
1329
|
+
target: {
|
|
1330
|
+
relPath: resolvedOld.value.relPath,
|
|
1331
|
+
absPath: resolvedOld.value.absPath,
|
|
1332
|
+
parsed: parsed.value,
|
|
1333
|
+
config: config.value,
|
|
1334
|
+
},
|
|
1308
1335
|
agent: agent.value,
|
|
1309
1336
|
tool: "vault_supersede",
|
|
1310
1337
|
action: "supersede",
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1338
|
+
newFrontmatter: {
|
|
1339
|
+
...oldFrontmatter,
|
|
1340
|
+
status: "superseded",
|
|
1341
|
+
superseded_by: newPath.value,
|
|
1342
|
+
...(validUntil !== null ? { valid_until: validUntil } : {}),
|
|
1343
|
+
updated: todayISO(),
|
|
1344
|
+
updated_by: agent.value,
|
|
1345
|
+
},
|
|
1315
1346
|
commitMessage: `vault_supersede: ${oldPath.value} superseded by ${newPath.value} ` +
|
|
1316
1347
|
`by ${agent.value}${reason ? ` — ${reason}` : ""}`,
|
|
1317
|
-
autoCommit: config.value.autoCommit,
|
|
1318
|
-
gitDir: config.value.gitDir,
|
|
1319
1348
|
baseVersion: baseVersion.value,
|
|
1320
|
-
|
|
1321
|
-
principal: access?.user,
|
|
1322
|
-
bodyChanged: false,
|
|
1349
|
+
access,
|
|
1323
1350
|
});
|
|
1351
|
+
if (!written.ok || boundary.value === null)
|
|
1352
|
+
return written;
|
|
1353
|
+
return ok({ ...written.value, hint: boundaryHint(newPath.value, boundary.value) });
|
|
1324
1354
|
}
|
|
1325
1355
|
// Combines two source documents into a target and supersedes both sources to
|
|
1326
1356
|
// point at it. Mechanical, not generative: the merged body is supplied by the
|
|
@@ -1351,6 +1381,9 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1351
1381
|
const agent = requireString(args, "agent", "vault_merge");
|
|
1352
1382
|
if (!agent.ok)
|
|
1353
1383
|
return agent;
|
|
1384
|
+
const boundary = readBoundary(args, "vault_merge");
|
|
1385
|
+
if (!boundary.ok)
|
|
1386
|
+
return boundary;
|
|
1354
1387
|
const body = args.body;
|
|
1355
1388
|
if (typeof body !== "string" || body.trim().length === 0) {
|
|
1356
1389
|
return err(new Error("vault_merge requires a non-empty string 'body' argument"));
|
|
@@ -1413,10 +1446,9 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1413
1446
|
targetCollection(vaultRoot, targetPath.value),
|
|
1414
1447
|
];
|
|
1415
1448
|
for (const collection of collections) {
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
}
|
|
1449
|
+
const gate = requireWriteAccess(access, collection);
|
|
1450
|
+
if (!gate.ok)
|
|
1451
|
+
return gate;
|
|
1420
1452
|
}
|
|
1421
1453
|
}
|
|
1422
1454
|
// Target frontmatter: inherit path_a's raw frontmatter, apply caller
|
|
@@ -1503,10 +1535,21 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1503
1535
|
// miss it and clobber the merged body with the superseded write (#127/#128).
|
|
1504
1536
|
if (source.rel === resolvedTarget.value.relPath)
|
|
1505
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
|
+
}
|
|
1506
1548
|
const supersededFm = {
|
|
1507
1549
|
...source.parsed.frontmatter,
|
|
1508
1550
|
status: "superseded",
|
|
1509
1551
|
superseded_by: targetPath.value,
|
|
1552
|
+
...(sourceUntil !== null ? { valid_until: sourceUntil } : {}),
|
|
1510
1553
|
updated: todayISO(),
|
|
1511
1554
|
updated_by: agent.value,
|
|
1512
1555
|
};
|
|
@@ -1647,6 +1690,24 @@ const baseVersionProperty = {
|
|
|
1647
1690
|
"write is rejected as stale and nothing is changed. Omit for " +
|
|
1648
1691
|
"last-write-wins behavior.",
|
|
1649
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
|
+
};
|
|
1650
1711
|
const runIdProperty = {
|
|
1651
1712
|
type: "string",
|
|
1652
1713
|
description: "Optional trace/run identifier of the calling run. Recorded in the " +
|
|
@@ -1712,6 +1773,23 @@ const frontmatterProperty = {
|
|
|
1712
1773
|
description: "Number of days after which this document is considered stale and " +
|
|
1713
1774
|
"should be reviewed. null = no TTL.",
|
|
1714
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
|
+
},
|
|
1715
1793
|
tags: {
|
|
1716
1794
|
type: "array",
|
|
1717
1795
|
items: { type: "string" },
|
|
@@ -1732,6 +1810,106 @@ const frontmatterProperty = {
|
|
|
1732
1810
|
required: ["title", "domain", "collection", "status", "confidence", "created", "provenance"],
|
|
1733
1811
|
additionalProperties: true,
|
|
1734
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
|
+
}
|
|
1735
1913
|
export const writeTools = [
|
|
1736
1914
|
{
|
|
1737
1915
|
name: "vault_write",
|
|
@@ -1772,6 +1950,49 @@ export const writeTools = [
|
|
|
1772
1950
|
required: ["path", "body", "frontmatter", "agent"],
|
|
1773
1951
|
additionalProperties: false,
|
|
1774
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
|
+
}),
|
|
1775
1996
|
handler: (vaultRoot, args, access) => vaultWrite(vaultRoot, args, access),
|
|
1776
1997
|
},
|
|
1777
1998
|
{
|
|
@@ -1802,6 +2023,12 @@ export const writeTools = [
|
|
|
1802
2023
|
required: ["path", "section", "agent"],
|
|
1803
2024
|
additionalProperties: false,
|
|
1804
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
|
+
}),
|
|
1805
2032
|
handler: (vaultRoot, args, access) => vaultAppend(vaultRoot, args, access),
|
|
1806
2033
|
},
|
|
1807
2034
|
{
|
|
@@ -1825,6 +2052,11 @@ export const writeTools = [
|
|
|
1825
2052
|
required: ["path", "agent"],
|
|
1826
2053
|
additionalProperties: false,
|
|
1827
2054
|
},
|
|
2055
|
+
outputSchema: writeResultSchema({
|
|
2056
|
+
description: "The applied promotion. Status is always 'canonical' on success.",
|
|
2057
|
+
actions: ["promote"],
|
|
2058
|
+
statuses: ["canonical"],
|
|
2059
|
+
}),
|
|
1828
2060
|
handler: (vaultRoot, args, access) => vaultPromote(vaultRoot, args, access),
|
|
1829
2061
|
},
|
|
1830
2062
|
{
|
|
@@ -1849,12 +2081,18 @@ export const writeTools = [
|
|
|
1849
2081
|
type: "string",
|
|
1850
2082
|
description: "Optional vault-relative path of the document that replaces this one",
|
|
1851
2083
|
},
|
|
2084
|
+
predecessor_valid_until: boundaryProperty,
|
|
1852
2085
|
agent: agentProperty,
|
|
1853
2086
|
base_version: baseVersionProperty,
|
|
1854
2087
|
},
|
|
1855
2088
|
required: ["path", "reason", "agent"],
|
|
1856
2089
|
additionalProperties: false,
|
|
1857
2090
|
},
|
|
2091
|
+
outputSchema: writeResultSchema({
|
|
2092
|
+
description: "The applied deprecation. Status is always 'deprecated' on success.",
|
|
2093
|
+
actions: ["deprecate"],
|
|
2094
|
+
statuses: ["deprecated"],
|
|
2095
|
+
}),
|
|
1858
2096
|
handler: (vaultRoot, args, access) => vaultDeprecate(vaultRoot, args, access),
|
|
1859
2097
|
},
|
|
1860
2098
|
{
|
|
@@ -1887,6 +2125,11 @@ export const writeTools = [
|
|
|
1887
2125
|
required: ["path", "confidence", "reason", "agent"],
|
|
1888
2126
|
additionalProperties: false,
|
|
1889
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
|
+
}),
|
|
1890
2133
|
handler: (vaultRoot, args, access) => vaultSetConfidence(vaultRoot, args, access),
|
|
1891
2134
|
},
|
|
1892
2135
|
{
|
|
@@ -1924,6 +2167,11 @@ export const writeTools = [
|
|
|
1924
2167
|
required: ["path", "tier", "reason", "agent"],
|
|
1925
2168
|
additionalProperties: false,
|
|
1926
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
|
+
}),
|
|
1927
2175
|
handler: (vaultRoot, args, access) => vaultSetTier(vaultRoot, args, access),
|
|
1928
2176
|
},
|
|
1929
2177
|
{
|
|
@@ -1950,12 +2198,19 @@ export const writeTools = [
|
|
|
1950
2198
|
type: "string",
|
|
1951
2199
|
description: "Optional reason recorded in the commit message",
|
|
1952
2200
|
},
|
|
2201
|
+
predecessor_valid_until: boundaryProperty,
|
|
1953
2202
|
agent: agentProperty,
|
|
1954
2203
|
base_version: baseVersionProperty,
|
|
1955
2204
|
},
|
|
1956
2205
|
required: ["old_path", "new_path", "agent"],
|
|
1957
2206
|
additionalProperties: false,
|
|
1958
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
|
+
}),
|
|
1959
2214
|
handler: (vaultRoot, args, access) => vaultSupersede(vaultRoot, args, access),
|
|
1960
2215
|
},
|
|
1961
2216
|
{
|
|
@@ -1993,11 +2248,19 @@ export const writeTools = [
|
|
|
1993
2248
|
"frontmatter with provenance set to 'synthesized'.",
|
|
1994
2249
|
additionalProperties: true,
|
|
1995
2250
|
},
|
|
2251
|
+
predecessor_valid_until: boundaryProperty,
|
|
1996
2252
|
agent: agentProperty,
|
|
1997
2253
|
},
|
|
1998
2254
|
required: ["path_a", "path_b", "target_path", "body", "agent"],
|
|
1999
2255
|
additionalProperties: false,
|
|
2000
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
|
+
}),
|
|
2001
2264
|
handler: (vaultRoot, args, access) => vaultMerge(vaultRoot, args, access),
|
|
2002
2265
|
},
|
|
2003
2266
|
];
|