daftari 1.32.0 → 3.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 +123 -1
- package/README.md +472 -342
- 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 +8 -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 +6 -0
- package/dist/cli.js.map +1 -1
- package/dist/court/index.d.ts.map +1 -1
- package/dist/court/index.js +48 -0
- package/dist/court/index.js.map +1 -1
- package/dist/court/triage.d.ts +5 -0
- package/dist/court/triage.d.ts.map +1 -0
- package/dist/court/triage.js +71 -0
- package/dist/court/triage.js.map +1 -0
- 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 +5 -1
- package/dist/curation/lint.d.ts.map +1 -1
- package/dist/curation/lint.js +41 -5
- package/dist/curation/lint.js.map +1 -1
- package/dist/curation/read-heat.d.ts +16 -0
- package/dist/curation/read-heat.d.ts.map +1 -0
- package/dist/curation/read-heat.js +52 -0
- package/dist/curation/read-heat.js.map +1 -0
- package/dist/curation/structural.d.ts +1 -1
- package/dist/curation/structural.d.ts.map +1 -1
- package/dist/curation/structural.js +8 -7
- package/dist/curation/structural.js.map +1 -1
- package/dist/curation/tension-triage.d.ts +57 -0
- package/dist/curation/tension-triage.d.ts.map +1 -0
- package/dist/curation/tension-triage.js +155 -0
- package/dist/curation/tension-triage.js.map +1 -0
- 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/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 +28 -1
- package/dist/frontmatter/schema.js.map +1 -1
- package/dist/frontmatter/types.d.ts +6 -1
- package/dist/frontmatter/types.d.ts.map +1 -1
- package/dist/frontmatter/types.js +8 -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/questions.d.ts.map +1 -1
- package/dist/interview/questions.js +41 -9
- package/dist/interview/questions.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 +6 -1
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/hybrid.js +23 -4
- package/dist/search/hybrid.js.map +1 -1
- package/dist/search/reindex.d.ts.map +1 -1
- package/dist/search/reindex.js +48 -13
- 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/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 +38 -6
- 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 +133 -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 +4 -0
- package/dist/tools/curation.d.ts.map +1 -1
- package/dist/tools/curation.js +647 -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 +385 -6
- 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 +456 -5
- 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 +106 -2
- 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 +8 -0
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +391 -3
- 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 +74 -0
- package/dist/utils/config.js.map +1 -1
- package/package.json +5 -2
package/dist/tools/write.js
CHANGED
|
@@ -17,8 +17,9 @@ import { frontmatterDiff, recordProvenance } from "../curation/provenance.js";
|
|
|
17
17
|
import { recordShadowAction } from "../curation/shadow.js";
|
|
18
18
|
import { stageActionWithConflictCheck } from "../curation/staged-actions.js";
|
|
19
19
|
import { sourceReadable } from "../curation/tension-access.js";
|
|
20
|
+
import { bucketHiddenDownstream, buildReverseLinkMap, buildReverseSourceMap, computeBlast, } from "../curation/tension-blast.js";
|
|
20
21
|
import { EXTERNAL_REF } from "../curation/tier0.js";
|
|
21
|
-
import { buildPathIndexes, extractLinks, outgoingLinkTargets, resolveLink, } from "../curation/vault-docs.js";
|
|
22
|
+
import { buildPathIndexes, extractLinks, loadDocuments, outgoingLinkTargets, resolveLink, } from "../curation/vault-docs.js";
|
|
22
23
|
import { parseDocument } from "../frontmatter/parser.js";
|
|
23
24
|
import { validateFrontmatter } from "../frontmatter/schema.js";
|
|
24
25
|
import { CONFIDENCES, DOMAINS, err, ok, PROVENANCES, STATUSES, TIERS, } from "../frontmatter/types.js";
|
|
@@ -30,6 +31,7 @@ import { noteSelfWrite } from "../search/self-write.js";
|
|
|
30
31
|
import { allDocumentPaths, getDocumentsByPaths } from "../storage/index-db.js";
|
|
31
32
|
import { readFile, resolveVaultPath } from "../storage/local.js";
|
|
32
33
|
import { loadConfig } from "../utils/config.js";
|
|
34
|
+
import { normalizeIsoDate } from "../utils/dates.js";
|
|
33
35
|
import { commit } from "../utils/git.js";
|
|
34
36
|
import { sha256Hex } from "../utils/hash.js";
|
|
35
37
|
import { readRunId } from "../utils/run-id.js";
|
|
@@ -40,6 +42,62 @@ import { openIndexForAccessOrNull } from "./search.js";
|
|
|
40
42
|
function todayISO() {
|
|
41
43
|
return new Date().toISOString().slice(0, 10);
|
|
42
44
|
}
|
|
45
|
+
// --- supersession boundary (valid time) ------------------------------------
|
|
46
|
+
//
|
|
47
|
+
// `predecessor_valid_until` is the date the successor takes over. Supplying it
|
|
48
|
+
// lets one call record both the supersession event and the valid-time handoff,
|
|
49
|
+
// since the event IS the window boundary — derived from an authored relation
|
|
50
|
+
// plus a caller-supplied date, never inferred from statistics.
|
|
51
|
+
//
|
|
52
|
+
// Because the window is half-open, the supplied date is written VERBATIM: the
|
|
53
|
+
// predecessor's window ends exactly where the successor's begins, sharing no
|
|
54
|
+
// day and needing no arithmetic. That is what half-open buys, and it is worth
|
|
55
|
+
// the slightly less natural authoring precisely here — this is the path an
|
|
56
|
+
// agent drives, and an off-by-one would silently open a one-day hole in, or
|
|
57
|
+
// double-claim a day of, the vault's account of when a fact held.
|
|
58
|
+
//
|
|
59
|
+
// It only ever writes the PREDECESSOR. vault_supersede gates RBAC on the
|
|
60
|
+
// predecessor's collection alone, so touching the successor would be a write
|
|
61
|
+
// the caller may not be authorized for, on top of a second lock, a second
|
|
62
|
+
// provenance entry, and a multi-file commit. The successor's valid_from is
|
|
63
|
+
// surfaced as a hint for a separate, deliberate call.
|
|
64
|
+
// Reads and validates the optional `predecessor_valid_until` argument.
|
|
65
|
+
// Null when absent.
|
|
66
|
+
function readBoundary(args, tool) {
|
|
67
|
+
const raw = args.predecessor_valid_until;
|
|
68
|
+
if (raw === undefined || raw === null)
|
|
69
|
+
return ok(null);
|
|
70
|
+
if (typeof raw !== "string") {
|
|
71
|
+
return err(new Error(`${tool}: 'predecessor_valid_until' must be a YYYY-MM-DD date string`));
|
|
72
|
+
}
|
|
73
|
+
const normalized = normalizeIsoDate(raw);
|
|
74
|
+
if (normalized === null) {
|
|
75
|
+
return err(new Error(`${tool}: 'predecessor_valid_until' must be a YYYY-MM-DD date, got "${raw}"`));
|
|
76
|
+
}
|
|
77
|
+
return ok(normalized);
|
|
78
|
+
}
|
|
79
|
+
// Validates the predecessor's new valid_until, or refuses. An existing
|
|
80
|
+
// non-null valid_until that disagrees is an authored claim, and a convenience
|
|
81
|
+
// argument does not get to overwrite one — the caller reconciles the two dates
|
|
82
|
+
// themselves. An agreeing value passes through idempotently.
|
|
83
|
+
function closingUntil(fm, boundary, tool, path) {
|
|
84
|
+
const existing = fm.valid_until ?? null;
|
|
85
|
+
if (existing !== null && existing !== boundary) {
|
|
86
|
+
return err(new Error(`${tool}: ${path} already declares valid_until ${existing}, but ` +
|
|
87
|
+
`predecessor_valid_until ${boundary} was supplied. Refusing to overwrite an ` +
|
|
88
|
+
"authored value — reconcile the two dates, or omit the argument and set " +
|
|
89
|
+
"valid_until directly."));
|
|
90
|
+
}
|
|
91
|
+
return ok(boundary);
|
|
92
|
+
}
|
|
93
|
+
// The successor-side follow-up the caller should make deliberately, through
|
|
94
|
+
// the tool that carries the successor's own RBAC gate. Under a half-open
|
|
95
|
+
// window the successor's valid_from is the SAME date — that is the point.
|
|
96
|
+
function boundaryHint(successorPath, boundary) {
|
|
97
|
+
return (`valid_until was set on the predecessor. The successor ${successorPath} was NOT ` +
|
|
98
|
+
`modified — set 'valid_from: ${boundary}' on it with vault_write if that is the ` +
|
|
99
|
+
"date its claim starts holding (the two windows meet exactly, sharing no day).");
|
|
100
|
+
}
|
|
43
101
|
// Refuses writes while the index is being (re)built. The write path ends in
|
|
44
102
|
// indexDocument(), which races with a concurrent reindexVault() — the reindex
|
|
45
103
|
// clears the index and re-inserts every document, so a write that lands in
|
|
@@ -124,9 +182,14 @@ export function serializeDocument(fm, body, extensions = [], raw = {}) {
|
|
|
124
182
|
// undefined here, which js-yaml refuses to dump (null it serializes fine,
|
|
125
183
|
// matching the superseded_by convention).
|
|
126
184
|
tier: fm.tier ?? null,
|
|
185
|
+
criticality: fm.criticality ?? null,
|
|
127
186
|
sources: fm.sources,
|
|
128
187
|
superseded_by: fm.superseded_by,
|
|
129
188
|
ttl_days: fm.ttl_days,
|
|
189
|
+
// `?? null` for the same reason as tier: a hand-built Frontmatter that
|
|
190
|
+
// predates these fields carries undefined, which js-yaml refuses to dump.
|
|
191
|
+
valid_from: fm.valid_from ?? null,
|
|
192
|
+
valid_until: fm.valid_until ?? null,
|
|
130
193
|
tags: fm.tags,
|
|
131
194
|
describes: fm.describes,
|
|
132
195
|
questions_answered: fm.questions_answered,
|
|
@@ -964,6 +1027,55 @@ export async function vaultPromote(vaultRoot, args, access) {
|
|
|
964
1027
|
});
|
|
965
1028
|
}
|
|
966
1029
|
// ---------------------------------------------------------------------------
|
|
1030
|
+
// downstream dependents advisory helper
|
|
1031
|
+
// ---------------------------------------------------------------------------
|
|
1032
|
+
// Builds the downstream dependents advisory for a retracted doc (deprecated
|
|
1033
|
+
// or superseded). Best-effort: returns null when docs can't be loaded so the
|
|
1034
|
+
// caller can omit `dependents` without failing the write.
|
|
1035
|
+
//
|
|
1036
|
+
// When `access` is provided, filters the downstream set to docs the role can
|
|
1037
|
+
// read and coarsens the hidden remainder via bucketHiddenDownstream. Without
|
|
1038
|
+
// access, all downstream docs are returned and hidden_downstream is "none".
|
|
1039
|
+
async function buildDependentsAdvisory(vaultRoot, retractedPath, access) {
|
|
1040
|
+
const docsResult = await loadDocuments(vaultRoot);
|
|
1041
|
+
if (!docsResult.ok)
|
|
1042
|
+
return undefined;
|
|
1043
|
+
const docs = docsResult.value;
|
|
1044
|
+
const reverseSource = buildReverseSourceMap(docs);
|
|
1045
|
+
const reverseLink = buildReverseLinkMap(docs);
|
|
1046
|
+
const blast = computeBlast({ seeds: [retractedPath], reverseSource, reverseLink });
|
|
1047
|
+
if (access) {
|
|
1048
|
+
const db = openIndexForAccessOrNull(vaultRoot);
|
|
1049
|
+
try {
|
|
1050
|
+
const kept = blast.downstream.filter((e) => sourceReadable(db, access, e.path));
|
|
1051
|
+
const hidden = blast.downstream.length - kept.length;
|
|
1052
|
+
let primary_blast = 0;
|
|
1053
|
+
let advisory_blast = 0;
|
|
1054
|
+
for (const e of kept) {
|
|
1055
|
+
if (e.dependency_type === "source")
|
|
1056
|
+
primary_blast += 1;
|
|
1057
|
+
else
|
|
1058
|
+
advisory_blast += 1;
|
|
1059
|
+
}
|
|
1060
|
+
return {
|
|
1061
|
+
downstream: kept,
|
|
1062
|
+
primary_blast,
|
|
1063
|
+
advisory_blast,
|
|
1064
|
+
hidden_downstream: bucketHiddenDownstream(hidden),
|
|
1065
|
+
};
|
|
1066
|
+
}
|
|
1067
|
+
finally {
|
|
1068
|
+
db?.close();
|
|
1069
|
+
}
|
|
1070
|
+
}
|
|
1071
|
+
return {
|
|
1072
|
+
downstream: blast.downstream,
|
|
1073
|
+
primary_blast: blast.primary_blast,
|
|
1074
|
+
advisory_blast: blast.advisory_blast,
|
|
1075
|
+
hidden_downstream: "none",
|
|
1076
|
+
};
|
|
1077
|
+
}
|
|
1078
|
+
// ---------------------------------------------------------------------------
|
|
967
1079
|
// vault_deprecate
|
|
968
1080
|
// ---------------------------------------------------------------------------
|
|
969
1081
|
// Marks a document deprecated. A reason is mandatory and is recorded in the
|
|
@@ -988,6 +1100,9 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
988
1100
|
const baseVersion = readBaseVersion(args, "vault_deprecate");
|
|
989
1101
|
if (!baseVersion.ok)
|
|
990
1102
|
return baseVersion;
|
|
1103
|
+
const boundary = readBoundary(args, "vault_deprecate");
|
|
1104
|
+
if (!boundary.ok)
|
|
1105
|
+
return boundary;
|
|
991
1106
|
let supersededBy = null;
|
|
992
1107
|
if (args.superseded_by !== undefined && args.superseded_by !== null) {
|
|
993
1108
|
if (typeof args.superseded_by !== "string") {
|
|
@@ -1002,7 +1117,16 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
1002
1117
|
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1003
1118
|
if (!rbac.ok)
|
|
1004
1119
|
return rbac;
|
|
1005
|
-
|
|
1120
|
+
// Same predecessor-only handoff as vault_supersede: this writes exactly the
|
|
1121
|
+
// document being deprecated, which it already locks and commits.
|
|
1122
|
+
let validUntil = null;
|
|
1123
|
+
if (boundary.value !== null) {
|
|
1124
|
+
const closing = closingUntil(oldFrontmatter, boundary.value, "vault_deprecate", path.value);
|
|
1125
|
+
if (!closing.ok)
|
|
1126
|
+
return closing;
|
|
1127
|
+
validUntil = closing.value;
|
|
1128
|
+
}
|
|
1129
|
+
const written = await performFrontmatterWrite({
|
|
1006
1130
|
vaultRoot,
|
|
1007
1131
|
target: target.value,
|
|
1008
1132
|
agent: agent.value,
|
|
@@ -1012,6 +1136,7 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
1012
1136
|
...oldFrontmatter,
|
|
1013
1137
|
status: "deprecated",
|
|
1014
1138
|
superseded_by: supersededBy,
|
|
1139
|
+
...(validUntil !== null ? { valid_until: validUntil } : {}),
|
|
1015
1140
|
updated: todayISO(),
|
|
1016
1141
|
updated_by: agent.value,
|
|
1017
1142
|
},
|
|
@@ -1020,6 +1145,15 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
1020
1145
|
baseVersion: baseVersion.value,
|
|
1021
1146
|
access,
|
|
1022
1147
|
});
|
|
1148
|
+
if (!written.ok)
|
|
1149
|
+
return written;
|
|
1150
|
+
// Build the downstream dependents advisory (best-effort, never fails the write).
|
|
1151
|
+
const dependents = await buildDependentsAdvisory(vaultRoot, path.value, access);
|
|
1152
|
+
// A deprecation without a successor has nothing to hint at.
|
|
1153
|
+
if (boundary.value === null || supersededBy === null) {
|
|
1154
|
+
return ok({ ...written.value, dependents });
|
|
1155
|
+
}
|
|
1156
|
+
return ok({ ...written.value, hint: boundaryHint(supersededBy, boundary.value), dependents });
|
|
1023
1157
|
}
|
|
1024
1158
|
// ---------------------------------------------------------------------------
|
|
1025
1159
|
// vault_set_confidence (§11.4)
|
|
@@ -1197,6 +1331,9 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1197
1331
|
const baseVersion = readBaseVersion(args, "vault_supersede");
|
|
1198
1332
|
if (!baseVersion.ok)
|
|
1199
1333
|
return baseVersion;
|
|
1334
|
+
const boundary = readBoundary(args, "vault_supersede");
|
|
1335
|
+
if (!boundary.ok)
|
|
1336
|
+
return boundary;
|
|
1200
1337
|
let reason;
|
|
1201
1338
|
if (args.reason !== undefined && args.reason !== null) {
|
|
1202
1339
|
if (typeof args.reason !== "string") {
|
|
@@ -1234,7 +1371,15 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1234
1371
|
const rbac = requireWriteAccess(access, collectionOf(oldPath.value, oldFrontmatter));
|
|
1235
1372
|
if (!rbac.ok)
|
|
1236
1373
|
return rbac;
|
|
1237
|
-
|
|
1374
|
+
// Valid-time handoff, opt-in. Predecessor only — see the boundary helpers.
|
|
1375
|
+
let validUntil = null;
|
|
1376
|
+
if (boundary.value !== null) {
|
|
1377
|
+
const closing = closingUntil(oldFrontmatter, boundary.value, "vault_supersede", oldPath.value);
|
|
1378
|
+
if (!closing.ok)
|
|
1379
|
+
return closing;
|
|
1380
|
+
validUntil = closing.value;
|
|
1381
|
+
}
|
|
1382
|
+
const written = await performFrontmatterWrite({
|
|
1238
1383
|
vaultRoot,
|
|
1239
1384
|
// Canonical relPath keys the lock/provenance/commit (#127/#128).
|
|
1240
1385
|
target: {
|
|
@@ -1250,6 +1395,7 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1250
1395
|
...oldFrontmatter,
|
|
1251
1396
|
status: "superseded",
|
|
1252
1397
|
superseded_by: newPath.value,
|
|
1398
|
+
...(validUntil !== null ? { valid_until: validUntil } : {}),
|
|
1253
1399
|
updated: todayISO(),
|
|
1254
1400
|
updated_by: agent.value,
|
|
1255
1401
|
},
|
|
@@ -1258,6 +1404,14 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1258
1404
|
baseVersion: baseVersion.value,
|
|
1259
1405
|
access,
|
|
1260
1406
|
});
|
|
1407
|
+
if (!written.ok)
|
|
1408
|
+
return written;
|
|
1409
|
+
// Build the downstream dependents advisory (best-effort, never fails the write).
|
|
1410
|
+
const dependents = await buildDependentsAdvisory(vaultRoot, oldPath.value, access);
|
|
1411
|
+
if (boundary.value === null) {
|
|
1412
|
+
return ok({ ...written.value, dependents });
|
|
1413
|
+
}
|
|
1414
|
+
return ok({ ...written.value, hint: boundaryHint(newPath.value, boundary.value), dependents });
|
|
1261
1415
|
}
|
|
1262
1416
|
// Combines two source documents into a target and supersedes both sources to
|
|
1263
1417
|
// point at it. Mechanical, not generative: the merged body is supplied by the
|
|
@@ -1288,6 +1442,9 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1288
1442
|
const agent = requireString(args, "agent", "vault_merge");
|
|
1289
1443
|
if (!agent.ok)
|
|
1290
1444
|
return agent;
|
|
1445
|
+
const boundary = readBoundary(args, "vault_merge");
|
|
1446
|
+
if (!boundary.ok)
|
|
1447
|
+
return boundary;
|
|
1291
1448
|
const body = args.body;
|
|
1292
1449
|
if (typeof body !== "string" || body.trim().length === 0) {
|
|
1293
1450
|
return err(new Error("vault_merge requires a non-empty string 'body' argument"));
|
|
@@ -1439,10 +1596,21 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1439
1596
|
// miss it and clobber the merged body with the superseded write (#127/#128).
|
|
1440
1597
|
if (source.rel === resolvedTarget.value.relPath)
|
|
1441
1598
|
continue;
|
|
1599
|
+
// Valid-time handoff on BOTH sources. A conflict on either one refuses the
|
|
1600
|
+
// whole merge: a merge is already all-or-nothing, and a partial validity
|
|
1601
|
+
// write would leave the vault in a state no single call could produce.
|
|
1602
|
+
let sourceUntil = null;
|
|
1603
|
+
if (boundary.value !== null) {
|
|
1604
|
+
const closing = closingUntil(source.parsed.frontmatter, boundary.value, "vault_merge", source.path);
|
|
1605
|
+
if (!closing.ok)
|
|
1606
|
+
return closing;
|
|
1607
|
+
sourceUntil = closing.value;
|
|
1608
|
+
}
|
|
1442
1609
|
const supersededFm = {
|
|
1443
1610
|
...source.parsed.frontmatter,
|
|
1444
1611
|
status: "superseded",
|
|
1445
1612
|
superseded_by: targetPath.value,
|
|
1613
|
+
...(sourceUntil !== null ? { valid_until: sourceUntil } : {}),
|
|
1446
1614
|
updated: todayISO(),
|
|
1447
1615
|
updated_by: agent.value,
|
|
1448
1616
|
};
|
|
@@ -1583,6 +1751,24 @@ const baseVersionProperty = {
|
|
|
1583
1751
|
"write is rejected as stale and nothing is changed. Omit for " +
|
|
1584
1752
|
"last-write-wins behavior.",
|
|
1585
1753
|
};
|
|
1754
|
+
// Shared by vault_supersede, vault_deprecate, and vault_merge — the three
|
|
1755
|
+
// tools that create a superseded_by edge. vault_write deliberately has no
|
|
1756
|
+
// equivalent: it is the raw authoring surface, and a write-time cross-check
|
|
1757
|
+
// between superseded_by and the validity fields would make an optional field
|
|
1758
|
+
// able to block a write. vault_lint's validityConflicts is the safety net for
|
|
1759
|
+
// edges created that way.
|
|
1760
|
+
const boundaryProperty = {
|
|
1761
|
+
type: "string",
|
|
1762
|
+
description: "Optional YYYY-MM-DD: the date the successor takes over — i.e. the first " +
|
|
1763
|
+
"day the PREDECESSOR's claim no longer held. Written verbatim to the " +
|
|
1764
|
+
"predecessor's valid_until, recording the valid-time handoff alongside " +
|
|
1765
|
+
"the supersession. This is about when the fact changed IN THE WORLD, not " +
|
|
1766
|
+
"when you are writing. Validity windows are half-open, so the successor's " +
|
|
1767
|
+
"valid_from is this same date — the two windows meet exactly and share no " +
|
|
1768
|
+
"day. The successor is NOT modified; the result carries a hint for setting " +
|
|
1769
|
+
"its valid_from in a separate call. Refuses rather than overwriting an " +
|
|
1770
|
+
"existing conflicting valid_until.",
|
|
1771
|
+
};
|
|
1586
1772
|
const runIdProperty = {
|
|
1587
1773
|
type: "string",
|
|
1588
1774
|
description: "Optional trace/run identifier of the calling run. Recorded in the " +
|
|
@@ -1648,6 +1834,23 @@ const frontmatterProperty = {
|
|
|
1648
1834
|
description: "Number of days after which this document is considered stale and " +
|
|
1649
1835
|
"should be reviewed. null = no TTL.",
|
|
1650
1836
|
},
|
|
1837
|
+
valid_from: {
|
|
1838
|
+
type: ["string", "null"],
|
|
1839
|
+
description: "First date (YYYY-MM-DD) on which this document's claim was true IN " +
|
|
1840
|
+
"THE WORLD. This is valid time, NOT the date the document was written " +
|
|
1841
|
+
"or edited — do not copy it from 'created' or 'updated', which are " +
|
|
1842
|
+
"transaction time. Set it only when you actually know when the fact " +
|
|
1843
|
+
"started holding; null means unknown, which is never the same as " +
|
|
1844
|
+
"'always true'. Inclusive.",
|
|
1845
|
+
},
|
|
1846
|
+
valid_until: {
|
|
1847
|
+
type: ["string", "null"],
|
|
1848
|
+
description: "Last date (YYYY-MM-DD) on which this document's claim was true IN " +
|
|
1849
|
+
"THE WORLD, inclusive. null with a valid_from means open-ended — still " +
|
|
1850
|
+
"true as far as the vault knows — NOT 'unknown end'. Distinct from " +
|
|
1851
|
+
"ttl_days, which is a promise to re-review, not a claim about when a " +
|
|
1852
|
+
"fact stopped holding.",
|
|
1853
|
+
},
|
|
1651
1854
|
tags: {
|
|
1652
1855
|
type: "array",
|
|
1653
1856
|
items: { type: "string" },
|
|
@@ -1668,6 +1871,106 @@ const frontmatterProperty = {
|
|
|
1668
1871
|
required: ["title", "domain", "collection", "status", "confidence", "created", "provenance"],
|
|
1669
1872
|
additionalProperties: true,
|
|
1670
1873
|
};
|
|
1874
|
+
// --- output schemas (spec 2026-07-26, Decision 3) ---------------------------
|
|
1875
|
+
//
|
|
1876
|
+
// Every write tool's ok-value is a WriteResult, so the schema is built once
|
|
1877
|
+
// and specialized per tool: `action` is a single-member enum on all but
|
|
1878
|
+
// vault_write (which also stages), and only vault_write / vault_append carry
|
|
1879
|
+
// the advisory and staging fields. `additionalProperties` is deliberately
|
|
1880
|
+
// left open — the result is additive by design (#169's supersede_hint and
|
|
1881
|
+
// #4's domain_warnings both arrived that way).
|
|
1882
|
+
const validationReportProperty = {
|
|
1883
|
+
type: "object",
|
|
1884
|
+
description: "Frontmatter validation report for the document as written. Advisory on " +
|
|
1885
|
+
"the lifecycle tools (it reports the document as it was already on disk); " +
|
|
1886
|
+
"on vault_write / vault_merge an invalid report fails the write instead.",
|
|
1887
|
+
properties: {
|
|
1888
|
+
valid: { type: "boolean", description: "True when no validation issues were found" },
|
|
1889
|
+
issues: {
|
|
1890
|
+
type: "array",
|
|
1891
|
+
description: "Every problem found, in discovery order",
|
|
1892
|
+
items: {
|
|
1893
|
+
type: "object",
|
|
1894
|
+
properties: {
|
|
1895
|
+
field: { type: "string", description: "Frontmatter field the issue concerns" },
|
|
1896
|
+
message: { type: "string", description: "What is wrong with it" },
|
|
1897
|
+
},
|
|
1898
|
+
required: ["field", "message"],
|
|
1899
|
+
},
|
|
1900
|
+
},
|
|
1901
|
+
},
|
|
1902
|
+
required: ["valid", "issues"],
|
|
1903
|
+
};
|
|
1904
|
+
const shadowProperty = {
|
|
1905
|
+
type: "boolean",
|
|
1906
|
+
description: "Present and true only when the vault runs shadow_mode: the write was " +
|
|
1907
|
+
"computed and logged to the shadow store but NOTHING was applied — no " +
|
|
1908
|
+
"file, no commit, no index update, no provenance entry.",
|
|
1909
|
+
};
|
|
1910
|
+
const domainWarningsProperty = {
|
|
1911
|
+
type: "array",
|
|
1912
|
+
items: { type: "string" },
|
|
1913
|
+
description: "#4 advisory epistemic-boundary warnings: this accumulation-domain write " +
|
|
1914
|
+
"references generative-domain documents the caller can read. Absent when " +
|
|
1915
|
+
"there is nothing to warn about. The write has already landed.",
|
|
1916
|
+
};
|
|
1917
|
+
// The shared WriteResult shape. `actions` and `statuses` are the closed
|
|
1918
|
+
// vocabularies the specific tool can emit; `properties` adds the tool's own
|
|
1919
|
+
// optional fields.
|
|
1920
|
+
function writeResultSchema(opts) {
|
|
1921
|
+
return {
|
|
1922
|
+
type: "object",
|
|
1923
|
+
description: opts.description,
|
|
1924
|
+
properties: {
|
|
1925
|
+
path: {
|
|
1926
|
+
type: "string",
|
|
1927
|
+
description: "Vault-relative path of the document the write targeted",
|
|
1928
|
+
},
|
|
1929
|
+
action: {
|
|
1930
|
+
type: "string",
|
|
1931
|
+
enum: [...opts.actions],
|
|
1932
|
+
description: "What the write did",
|
|
1933
|
+
},
|
|
1934
|
+
commit: {
|
|
1935
|
+
type: ["string", "null"],
|
|
1936
|
+
description: "Short git commit hash when the write was auto-committed; null when " +
|
|
1937
|
+
"the vault runs auto_commit: false, or when nothing was applied " +
|
|
1938
|
+
"(shadow mode, or a staged proposal).",
|
|
1939
|
+
},
|
|
1940
|
+
committed: {
|
|
1941
|
+
type: "boolean",
|
|
1942
|
+
description: "Whether the write was auto-committed to git",
|
|
1943
|
+
},
|
|
1944
|
+
status: {
|
|
1945
|
+
type: "string",
|
|
1946
|
+
enum: [...(opts.statuses ?? STATUSES)],
|
|
1947
|
+
description: "The document's lifecycle status after the write",
|
|
1948
|
+
},
|
|
1949
|
+
updated: {
|
|
1950
|
+
type: "string",
|
|
1951
|
+
description: "The stamped 'updated' date (YYYY-MM-DD)",
|
|
1952
|
+
},
|
|
1953
|
+
validation: validationReportProperty,
|
|
1954
|
+
indexUpdated: {
|
|
1955
|
+
type: "boolean",
|
|
1956
|
+
description: "Whether the search index was refreshed. False does not undo the " +
|
|
1957
|
+
"write — the index is a rebuildable cache.",
|
|
1958
|
+
},
|
|
1959
|
+
shadow: shadowProperty,
|
|
1960
|
+
...(opts.properties ?? {}),
|
|
1961
|
+
},
|
|
1962
|
+
required: [
|
|
1963
|
+
"path",
|
|
1964
|
+
"action",
|
|
1965
|
+
"commit",
|
|
1966
|
+
"committed",
|
|
1967
|
+
"status",
|
|
1968
|
+
"updated",
|
|
1969
|
+
"validation",
|
|
1970
|
+
"indexUpdated",
|
|
1971
|
+
],
|
|
1972
|
+
};
|
|
1973
|
+
}
|
|
1671
1974
|
export const writeTools = [
|
|
1672
1975
|
{
|
|
1673
1976
|
name: "vault_write",
|
|
@@ -1708,6 +2011,49 @@ export const writeTools = [
|
|
|
1708
2011
|
required: ["path", "body", "frontmatter", "agent"],
|
|
1709
2012
|
additionalProperties: false,
|
|
1710
2013
|
},
|
|
2014
|
+
outputSchema: writeResultSchema({
|
|
2015
|
+
description: "The applied write ('create' or 'update'), or — for a propose-only " +
|
|
2016
|
+
"role — the staged proposal that was recorded instead ('staged', " +
|
|
2017
|
+
"nothing written).",
|
|
2018
|
+
actions: ["create", "update", "staged"],
|
|
2019
|
+
// "pending" is the staged-proposal status: no document status exists yet.
|
|
2020
|
+
statuses: [...STATUSES, "pending"],
|
|
2021
|
+
properties: {
|
|
2022
|
+
supersede_hint: {
|
|
2023
|
+
type: "string",
|
|
2024
|
+
description: "#169 advisory nudge, present only when this write overwrote an " +
|
|
2025
|
+
"existing document: vault_supersede preserves the prior version " +
|
|
2026
|
+
"and its lineage instead. The write has already landed.",
|
|
2027
|
+
},
|
|
2028
|
+
domain_warnings: domainWarningsProperty,
|
|
2029
|
+
staged_id: {
|
|
2030
|
+
type: "string",
|
|
2031
|
+
description: "Staged-action id of the recorded proposal. Present only when " + "action is 'staged'.",
|
|
2032
|
+
},
|
|
2033
|
+
expires_at: {
|
|
2034
|
+
type: "string",
|
|
2035
|
+
description: "ISO timestamp after which the staged proposal expires unratified. " +
|
|
2036
|
+
"Present only when action is 'staged'.",
|
|
2037
|
+
},
|
|
2038
|
+
conflicts_with: {
|
|
2039
|
+
type: "array",
|
|
2040
|
+
items: { type: "string" },
|
|
2041
|
+
description: "Ids of other pending proposals contesting the same target. " +
|
|
2042
|
+
"Present only when action is 'staged'; empty when uncontested.",
|
|
2043
|
+
},
|
|
2044
|
+
tension_id: {
|
|
2045
|
+
type: ["string", "null"],
|
|
2046
|
+
description: "Id of the inter-proposal tension logged for the conflicting " +
|
|
2047
|
+
"proposals, or null when none was needed. Present only when " +
|
|
2048
|
+
"action is 'staged'.",
|
|
2049
|
+
},
|
|
2050
|
+
tension_error: {
|
|
2051
|
+
type: "string",
|
|
2052
|
+
description: "Why the conflict tension could not be written. The proposal is " +
|
|
2053
|
+
"still staged and conflicts_with still names the contenders.",
|
|
2054
|
+
},
|
|
2055
|
+
},
|
|
2056
|
+
}),
|
|
1711
2057
|
handler: (vaultRoot, args, access) => vaultWrite(vaultRoot, args, access),
|
|
1712
2058
|
},
|
|
1713
2059
|
{
|
|
@@ -1738,6 +2084,12 @@ export const writeTools = [
|
|
|
1738
2084
|
required: ["path", "section", "agent"],
|
|
1739
2085
|
additionalProperties: false,
|
|
1740
2086
|
},
|
|
2087
|
+
outputSchema: writeResultSchema({
|
|
2088
|
+
description: "The applied append. The document's status is unchanged — an append " +
|
|
2089
|
+
"only touches the body and the 'updated' / 'updated_by' stamps.",
|
|
2090
|
+
actions: ["append"],
|
|
2091
|
+
properties: { domain_warnings: domainWarningsProperty },
|
|
2092
|
+
}),
|
|
1741
2093
|
handler: (vaultRoot, args, access) => vaultAppend(vaultRoot, args, access),
|
|
1742
2094
|
},
|
|
1743
2095
|
{
|
|
@@ -1761,6 +2113,11 @@ export const writeTools = [
|
|
|
1761
2113
|
required: ["path", "agent"],
|
|
1762
2114
|
additionalProperties: false,
|
|
1763
2115
|
},
|
|
2116
|
+
outputSchema: writeResultSchema({
|
|
2117
|
+
description: "The applied promotion. Status is always 'canonical' on success.",
|
|
2118
|
+
actions: ["promote"],
|
|
2119
|
+
statuses: ["canonical"],
|
|
2120
|
+
}),
|
|
1764
2121
|
handler: (vaultRoot, args, access) => vaultPromote(vaultRoot, args, access),
|
|
1765
2122
|
},
|
|
1766
2123
|
{
|
|
@@ -1785,12 +2142,18 @@ export const writeTools = [
|
|
|
1785
2142
|
type: "string",
|
|
1786
2143
|
description: "Optional vault-relative path of the document that replaces this one",
|
|
1787
2144
|
},
|
|
2145
|
+
predecessor_valid_until: boundaryProperty,
|
|
1788
2146
|
agent: agentProperty,
|
|
1789
2147
|
base_version: baseVersionProperty,
|
|
1790
2148
|
},
|
|
1791
2149
|
required: ["path", "reason", "agent"],
|
|
1792
2150
|
additionalProperties: false,
|
|
1793
2151
|
},
|
|
2152
|
+
outputSchema: writeResultSchema({
|
|
2153
|
+
description: "The applied deprecation. Status is always 'deprecated' on success.",
|
|
2154
|
+
actions: ["deprecate"],
|
|
2155
|
+
statuses: ["deprecated"],
|
|
2156
|
+
}),
|
|
1794
2157
|
handler: (vaultRoot, args, access) => vaultDeprecate(vaultRoot, args, access),
|
|
1795
2158
|
},
|
|
1796
2159
|
{
|
|
@@ -1823,6 +2186,11 @@ export const writeTools = [
|
|
|
1823
2186
|
required: ["path", "confidence", "reason", "agent"],
|
|
1824
2187
|
additionalProperties: false,
|
|
1825
2188
|
},
|
|
2189
|
+
outputSchema: writeResultSchema({
|
|
2190
|
+
description: "The applied confidence change. Status is unchanged — only the " +
|
|
2191
|
+
"document's confidence and the 'updated' / 'updated_by' stamps moved.",
|
|
2192
|
+
actions: ["confidence-set"],
|
|
2193
|
+
}),
|
|
1826
2194
|
handler: (vaultRoot, args, access) => vaultSetConfidence(vaultRoot, args, access),
|
|
1827
2195
|
},
|
|
1828
2196
|
{
|
|
@@ -1860,6 +2228,11 @@ export const writeTools = [
|
|
|
1860
2228
|
required: ["path", "tier", "reason", "agent"],
|
|
1861
2229
|
additionalProperties: false,
|
|
1862
2230
|
},
|
|
2231
|
+
outputSchema: writeResultSchema({
|
|
2232
|
+
description: "The applied tier change. Status is unchanged — only the document's " +
|
|
2233
|
+
"write-protection tier and the 'updated' / 'updated_by' stamps moved.",
|
|
2234
|
+
actions: ["tier-set"],
|
|
2235
|
+
}),
|
|
1863
2236
|
handler: (vaultRoot, args, access) => vaultSetTier(vaultRoot, args, access),
|
|
1864
2237
|
},
|
|
1865
2238
|
{
|
|
@@ -1886,12 +2259,19 @@ export const writeTools = [
|
|
|
1886
2259
|
type: "string",
|
|
1887
2260
|
description: "Optional reason recorded in the commit message",
|
|
1888
2261
|
},
|
|
2262
|
+
predecessor_valid_until: boundaryProperty,
|
|
1889
2263
|
agent: agentProperty,
|
|
1890
2264
|
base_version: baseVersionProperty,
|
|
1891
2265
|
},
|
|
1892
2266
|
required: ["old_path", "new_path", "agent"],
|
|
1893
2267
|
additionalProperties: false,
|
|
1894
2268
|
},
|
|
2269
|
+
outputSchema: writeResultSchema({
|
|
2270
|
+
description: "The applied supersession, reported for the OLD document (path is " +
|
|
2271
|
+
"old_path). Status is always 'superseded' on success.",
|
|
2272
|
+
actions: ["supersede"],
|
|
2273
|
+
statuses: ["superseded"],
|
|
2274
|
+
}),
|
|
1895
2275
|
handler: (vaultRoot, args, access) => vaultSupersede(vaultRoot, args, access),
|
|
1896
2276
|
},
|
|
1897
2277
|
{
|
|
@@ -1929,11 +2309,19 @@ export const writeTools = [
|
|
|
1929
2309
|
"frontmatter with provenance set to 'synthesized'.",
|
|
1930
2310
|
additionalProperties: true,
|
|
1931
2311
|
},
|
|
2312
|
+
predecessor_valid_until: boundaryProperty,
|
|
1932
2313
|
agent: agentProperty,
|
|
1933
2314
|
},
|
|
1934
2315
|
required: ["path_a", "path_b", "target_path", "body", "agent"],
|
|
1935
2316
|
additionalProperties: false,
|
|
1936
2317
|
},
|
|
2318
|
+
outputSchema: writeResultSchema({
|
|
2319
|
+
description: "The applied merge, reported for the TARGET document (path is " +
|
|
2320
|
+
"target_path); the superseded sources are written under the same " +
|
|
2321
|
+
"commit and are not enumerated here. 'commit' covers all three files, " +
|
|
2322
|
+
"and 'indexUpdated' is true only when every written file reindexed.",
|
|
2323
|
+
actions: ["merge"],
|
|
2324
|
+
}),
|
|
1937
2325
|
handler: (vaultRoot, args, access) => vaultMerge(vaultRoot, args, access),
|
|
1938
2326
|
},
|
|
1939
2327
|
];
|