daftari 3.6.0 → 3.7.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/dist/attest/bundle.d.ts +53 -0
- package/dist/attest/bundle.d.ts.map +1 -0
- package/dist/attest/bundle.js +141 -0
- package/dist/attest/bundle.js.map +1 -0
- package/dist/attest/index.d.ts +2 -0
- package/dist/attest/index.d.ts.map +1 -0
- package/dist/attest/index.js +139 -0
- package/dist/attest/index.js.map +1 -0
- package/dist/attest/sign.d.ts +16 -0
- package/dist/attest/sign.d.ts.map +1 -0
- package/dist/attest/sign.js +75 -0
- package/dist/attest/sign.js.map +1 -0
- package/dist/attest/verify.d.ts +21 -0
- package/dist/attest/verify.d.ts.map +1 -0
- package/dist/attest/verify.js +148 -0
- package/dist/attest/verify.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/curation/staged-actions.d.ts +2 -0
- package/dist/curation/staged-actions.d.ts.map +1 -1
- package/dist/curation/staged-actions.js +5 -0
- package/dist/curation/staged-actions.js.map +1 -1
- package/dist/distill/adapters/claude-session.d.ts +6 -0
- package/dist/distill/adapters/claude-session.d.ts.map +1 -0
- package/dist/distill/adapters/claude-session.js +71 -0
- package/dist/distill/adapters/claude-session.js.map +1 -0
- package/dist/distill/cli.d.ts.map +1 -1
- package/dist/distill/cli.js +113 -9
- package/dist/distill/cli.js.map +1 -1
- package/dist/distill/index.d.ts +1 -0
- package/dist/distill/index.d.ts.map +1 -1
- package/dist/distill/index.js +3 -0
- package/dist/distill/index.js.map +1 -1
- package/dist/distill/propose.d.ts +23 -5
- package/dist/distill/propose.d.ts.map +1 -1
- package/dist/distill/propose.js +58 -30
- package/dist/distill/propose.js.map +1 -1
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +13 -0
- package/dist/serve/index.js.map +1 -1
- package/dist/storage/index-db.d.ts +1 -0
- package/dist/storage/index-db.d.ts.map +1 -1
- package/dist/storage/index-db.js.map +1 -1
- package/dist/tools/positions.d.ts.map +1 -1
- package/dist/tools/positions.js +6 -0
- package/dist/tools/positions.js.map +1 -1
- package/dist/tools/receipt.d.ts +6 -0
- package/dist/tools/receipt.d.ts.map +1 -1
- package/dist/tools/receipt.js +47 -1
- package/dist/tools/receipt.js.map +1 -1
- package/dist/tools/staged-actions.d.ts.map +1 -1
- package/dist/tools/staged-actions.js +26 -2
- package/dist/tools/staged-actions.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 +303 -225
- package/dist/tools/write.js.map +1 -1
- package/dist/utils/config.d.ts +8 -0
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +16 -1
- package/dist/utils/config.js.map +1 -1
- package/dist/utils/git.d.ts +18 -2
- package/dist/utils/git.d.ts.map +1 -1
- package/dist/utils/git.js +116 -13
- package/dist/utils/git.js.map +1 -1
- package/package.json +1 -1
package/dist/tools/write.js
CHANGED
|
@@ -473,6 +473,27 @@ export async function retryOnStale(attempt) {
|
|
|
473
473
|
return first;
|
|
474
474
|
return attempt();
|
|
475
475
|
}
|
|
476
|
+
// The dispatcher for the other frontmatter-only lifecycle tools (promote,
|
|
477
|
+
// deprecate, set_confidence, set_tier, append): each accepts an OPTIONAL
|
|
478
|
+
// caller-supplied base_version, unlike assert/consolidate above which never
|
|
479
|
+
// expose one. The two cases behave differently on purpose:
|
|
480
|
+
//
|
|
481
|
+
// - explicit base_version: this is the CALLER's optimistic-concurrency
|
|
482
|
+
// token, composed against content the caller itself read. A stale
|
|
483
|
+
// rejection here is the caller's own mistake — it must fail loudly
|
|
484
|
+
// WITHOUT a hidden retry, so the caller re-reads and resubmits against
|
|
485
|
+
// the winner's content (retrying transparently would silently discard
|
|
486
|
+
// work the caller may have composed by hand).
|
|
487
|
+
// - omitted base_version: `attempt` fills it in internally from the
|
|
488
|
+
// load-time contentHash (TargetDocument.contentHash), and because these
|
|
489
|
+
// tools' new frontmatter is a pure function of that load, one transparent
|
|
490
|
+
// retry via retryOnStale is sound — the same guarantee assert/consolidate
|
|
491
|
+
// rely on above.
|
|
492
|
+
export async function retryOnStaleIfDefaulted(explicitBaseVersion, attempt) {
|
|
493
|
+
if (explicitBaseVersion !== undefined)
|
|
494
|
+
return attempt();
|
|
495
|
+
return retryOnStale(attempt);
|
|
496
|
+
}
|
|
476
497
|
export async function loadTargetDocument(vaultRoot, rawPath, tool) {
|
|
477
498
|
const resolved = resolveVaultPath(vaultRoot, rawPath);
|
|
478
499
|
if (!resolved.ok)
|
|
@@ -726,6 +747,13 @@ export async function vaultWrite(vaultRoot, args, access) {
|
|
|
726
747
|
? args.reason.trim()
|
|
727
748
|
: `propose-only role '${access.roleName}': write staged for ratification`,
|
|
728
749
|
proposedDiff: { frontmatter: rawFrontmatter, body },
|
|
750
|
+
// LD-13 ratify staleness guard (same one-line capture as vault_assert's
|
|
751
|
+
// propose-only branch): anchor to the bytes `onDisk` was read from above,
|
|
752
|
+
// so a ratify replay against a document that changed since staging fails
|
|
753
|
+
// loudly as a stale write instead of silently overwriting the change.
|
|
754
|
+
// Undefined for a create (onDisk not ok — no prior version to anchor to;
|
|
755
|
+
// create-vs-create races are out of scope here, same as today).
|
|
756
|
+
...(onDisk.ok ? { baseVersion: sha256Hex(onDisk.value) } : {}),
|
|
729
757
|
...(runId.value !== undefined ? { runId: runId.value } : {}),
|
|
730
758
|
});
|
|
731
759
|
if (!staged.ok)
|
|
@@ -1010,91 +1038,90 @@ export async function vaultAppend(vaultRoot, args, access) {
|
|
|
1010
1038
|
const proposeGate = denyIfProposeOnly(access, "vault_append");
|
|
1011
1039
|
if (!proposeGate.ok)
|
|
1012
1040
|
return proposeGate;
|
|
1013
|
-
const
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1041
|
+
const attemptAppend = async () => {
|
|
1042
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_append");
|
|
1043
|
+
if (!target.ok)
|
|
1044
|
+
return target;
|
|
1045
|
+
const extensions = target.value.config.schemaExtensions;
|
|
1046
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1047
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1048
|
+
if (!rbac.ok)
|
|
1049
|
+
return rbac;
|
|
1050
|
+
const newFrontmatter = {
|
|
1051
|
+
...oldFrontmatter,
|
|
1052
|
+
updated: todayISO(),
|
|
1053
|
+
updated_by: agent.value,
|
|
1054
|
+
};
|
|
1055
|
+
const newBody = `${target.value.parsed.content.replace(/\s+$/, "")}\n\n${section.value.trim()}\n`;
|
|
1056
|
+
// Pre-write transform hooks run before the pre_write validators; their
|
|
1057
|
+
// Partial<Frontmatter> patch is merged Object.assign-style into the
|
|
1058
|
+
// post-stamp frontmatter so the validators below see the transformed
|
|
1059
|
+
// values. A transform throw or non-object return blocks the append.
|
|
1060
|
+
const loadedTransformHooks = await loadPreWriteTransformHooks(vaultRoot, target.value.config.hooks.preWriteTransform);
|
|
1061
|
+
if (!loadedTransformHooks.ok)
|
|
1062
|
+
return loadedTransformHooks;
|
|
1063
|
+
const transformResult = runPreWriteTransformHooks(loadedTransformHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
1064
|
+
Object.assign(newFrontmatter, transformResult.merged);
|
|
1065
|
+
// Pre-write hooks see the post-stamp, post-transform frontmatter (the
|
|
1066
|
+
// same shape a subsequent vault_read would return). Issues block the
|
|
1067
|
+
// append, same as for vault_write.
|
|
1068
|
+
const loadedHooks = await loadHooks(vaultRoot, target.value.config.hooks.preWrite);
|
|
1069
|
+
if (!loadedHooks.ok)
|
|
1070
|
+
return loadedHooks;
|
|
1071
|
+
const hookIssues = runPreWriteHooks(loadedHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
1072
|
+
const appendIssues = [...transformResult.issues, ...hookIssues];
|
|
1073
|
+
if (appendIssues.length > 0) {
|
|
1074
|
+
const summary = appendIssues.map((i) => `${i.field}: ${i.message}`).join("; ");
|
|
1075
|
+
return err(new Error(`invalid frontmatter: ${summary}`));
|
|
1076
|
+
}
|
|
1077
|
+
const written = await performWrite({
|
|
1078
|
+
vaultRoot,
|
|
1079
|
+
// Lock key, provenance, and commit path are all keyed on the CANONICAL
|
|
1080
|
+
// relPath, never the raw caller string: aliased spellings of one file
|
|
1081
|
+
// must contend on one lock (#127/#128).
|
|
1082
|
+
relPath: target.value.relPath,
|
|
1083
|
+
absPath: target.value.absPath,
|
|
1084
|
+
agent: agent.value,
|
|
1085
|
+
tool: "vault_append",
|
|
1086
|
+
action: "append",
|
|
1087
|
+
fileText: serializeDocument(newFrontmatter, newBody, extensions, target.value.parsed.raw),
|
|
1088
|
+
newFrontmatter,
|
|
1089
|
+
oldFrontmatter,
|
|
1090
|
+
validation: target.value.parsed.validation,
|
|
1091
|
+
commitMessage: `vault_append: ${path.value} by ${agent.value}`,
|
|
1092
|
+
autoCommit: target.value.config.autoCommit,
|
|
1093
|
+
gitDir: target.value.config.gitDir,
|
|
1094
|
+
baseVersion: baseVersion.value ?? target.value.contentHash,
|
|
1095
|
+
shadowMode: target.value.config.shadowMode,
|
|
1096
|
+
principal: access?.user,
|
|
1097
|
+
...(runId.value !== undefined ? { runId: runId.value } : {}),
|
|
1098
|
+
bodyChanged: true,
|
|
1099
|
+
});
|
|
1100
|
+
if (!written.ok)
|
|
1101
|
+
return written;
|
|
1102
|
+
return ok({ written: written.value, domain: newFrontmatter.domain });
|
|
1035
1103
|
};
|
|
1036
|
-
const
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
// values. A transform throw or non-object return blocks the append.
|
|
1041
|
-
const loadedTransformHooks = await loadPreWriteTransformHooks(vaultRoot, config.value.hooks.preWriteTransform);
|
|
1042
|
-
if (!loadedTransformHooks.ok)
|
|
1043
|
-
return loadedTransformHooks;
|
|
1044
|
-
const transformResult = runPreWriteTransformHooks(loadedTransformHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
1045
|
-
Object.assign(newFrontmatter, transformResult.merged);
|
|
1046
|
-
// Pre-write hooks see the post-stamp, post-transform frontmatter (the same
|
|
1047
|
-
// shape a subsequent vault_read would return). Issues block the append,
|
|
1048
|
-
// same as for vault_write.
|
|
1049
|
-
const loadedHooks = await loadHooks(vaultRoot, config.value.hooks.preWrite);
|
|
1050
|
-
if (!loadedHooks.ok)
|
|
1051
|
-
return loadedHooks;
|
|
1052
|
-
const hookIssues = runPreWriteHooks(loadedHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
1053
|
-
const appendIssues = [...transformResult.issues, ...hookIssues];
|
|
1054
|
-
if (appendIssues.length > 0) {
|
|
1055
|
-
const summary = appendIssues.map((i) => `${i.field}: ${i.message}`).join("; ");
|
|
1056
|
-
return err(new Error(`invalid frontmatter: ${summary}`));
|
|
1057
|
-
}
|
|
1058
|
-
const appended = await performWrite({
|
|
1059
|
-
vaultRoot,
|
|
1060
|
-
// Lock key, provenance, and commit path are all keyed on the CANONICAL
|
|
1061
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
1062
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
1063
|
-
relPath: resolved.value.relPath,
|
|
1064
|
-
absPath: resolved.value.absPath,
|
|
1065
|
-
agent: agent.value,
|
|
1066
|
-
tool: "vault_append",
|
|
1067
|
-
action: "append",
|
|
1068
|
-
fileText: serializeDocument(newFrontmatter, newBody, extensions, parsed.value.raw),
|
|
1069
|
-
newFrontmatter,
|
|
1070
|
-
oldFrontmatter,
|
|
1071
|
-
validation: parsed.value.validation,
|
|
1072
|
-
commitMessage: `vault_append: ${path.value} by ${agent.value}`,
|
|
1073
|
-
autoCommit: config.value.autoCommit,
|
|
1074
|
-
gitDir: config.value.gitDir,
|
|
1075
|
-
baseVersion: baseVersion.value,
|
|
1076
|
-
shadowMode: config.value.shadowMode,
|
|
1077
|
-
principal: access?.user,
|
|
1078
|
-
...(runId.value !== undefined ? { runId: runId.value } : {}),
|
|
1079
|
-
bodyChanged: true,
|
|
1080
|
-
});
|
|
1104
|
+
const attempt = await retryOnStaleIfDefaulted(baseVersion.value, attemptAppend);
|
|
1105
|
+
if (!attempt.ok)
|
|
1106
|
+
return attempt;
|
|
1107
|
+
const { written, domain } = attempt.value;
|
|
1081
1108
|
// #4: an appended section can introduce body links into generative-domain
|
|
1082
1109
|
// docs — same advisory channel as vault_write, scoped to what THIS append
|
|
1083
1110
|
// added: only the new section is scanned (a doc that already leaned on
|
|
1084
1111
|
// generative material warned at write time; re-warning on every later,
|
|
1085
1112
|
// unrelated append would drown the signal), and sources are skipped
|
|
1086
1113
|
// entirely because an append cannot change frontmatter.
|
|
1087
|
-
if (
|
|
1088
|
-
return
|
|
1114
|
+
if (written.shadow)
|
|
1115
|
+
return ok(written);
|
|
1089
1116
|
const appendWarnings = generativeDomainRefs(vaultRoot, {
|
|
1090
|
-
domain
|
|
1117
|
+
domain,
|
|
1091
1118
|
sources: [],
|
|
1092
1119
|
body: section.value,
|
|
1093
|
-
relPath:
|
|
1120
|
+
relPath: written.path,
|
|
1094
1121
|
}, access);
|
|
1095
1122
|
if (appendWarnings === null)
|
|
1096
|
-
return
|
|
1097
|
-
return ok({ ...
|
|
1123
|
+
return ok(written);
|
|
1124
|
+
return ok({ ...written, domain_warnings: appendWarnings });
|
|
1098
1125
|
}
|
|
1099
1126
|
// ---------------------------------------------------------------------------
|
|
1100
1127
|
// vault_promote
|
|
@@ -1121,43 +1148,52 @@ export async function vaultPromote(vaultRoot, args, access) {
|
|
|
1121
1148
|
if (access && !canPromote(access.role)) {
|
|
1122
1149
|
return err(new Error(`access denied: role '${access.roleName}' cannot promote documents`));
|
|
1123
1150
|
}
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1151
|
+
// Read-modify-write over the loaded frontmatter — see
|
|
1152
|
+
// retryOnStaleIfDefaulted above. An explicit base_version passes straight
|
|
1153
|
+
// through (one attempt, loud stale rejection); an omitted one defaults to
|
|
1154
|
+
// the load-time contentHash and gets one transparent retry, so a concurrent
|
|
1155
|
+
// vault_assert's positions array is never silently erased by a clean
|
|
1156
|
+
// promote commit.
|
|
1157
|
+
const attemptPromote = async () => {
|
|
1158
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_promote");
|
|
1159
|
+
if (!target.ok)
|
|
1160
|
+
return target;
|
|
1161
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1162
|
+
if (oldFrontmatter.status !== "draft") {
|
|
1163
|
+
return err(new Error(`vault_promote: only draft documents can be promoted ` +
|
|
1164
|
+
`(${path.value} is '${oldFrontmatter.status}')`));
|
|
1165
|
+
}
|
|
1166
|
+
if (!target.value.parsed.validation.valid) {
|
|
1167
|
+
const summary = target.value.parsed.validation.issues
|
|
1168
|
+
.map((i) => `${i.field}: ${i.message}`)
|
|
1169
|
+
.join("; ");
|
|
1170
|
+
return err(new Error(`vault_promote: frontmatter is incomplete: ${summary}`));
|
|
1171
|
+
}
|
|
1172
|
+
// `confidence set` — the document must declare a confidence explicitly, not
|
|
1173
|
+
// ride on the validator's default.
|
|
1174
|
+
const rawConfidence = target.value.parsed.raw.confidence;
|
|
1175
|
+
if (typeof rawConfidence !== "string" ||
|
|
1176
|
+
!CONFIDENCES.includes(rawConfidence)) {
|
|
1177
|
+
return err(new Error("vault_promote: confidence must be set before promotion"));
|
|
1178
|
+
}
|
|
1179
|
+
return performFrontmatterWrite({
|
|
1180
|
+
vaultRoot,
|
|
1181
|
+
target: target.value,
|
|
1182
|
+
agent: agent.value,
|
|
1183
|
+
tool: "vault_promote",
|
|
1184
|
+
action: "promote",
|
|
1185
|
+
newFrontmatter: {
|
|
1186
|
+
...oldFrontmatter,
|
|
1187
|
+
status: "canonical",
|
|
1188
|
+
updated: todayISO(),
|
|
1189
|
+
updated_by: agent.value,
|
|
1190
|
+
},
|
|
1191
|
+
commitMessage: `vault_promote: ${path.value} draft→canonical by ${agent.value}`,
|
|
1192
|
+
baseVersion: baseVersion.value ?? target.value.contentHash,
|
|
1193
|
+
access,
|
|
1194
|
+
});
|
|
1195
|
+
};
|
|
1196
|
+
return retryOnStaleIfDefaulted(baseVersion.value, attemptPromote);
|
|
1161
1197
|
}
|
|
1162
1198
|
// ---------------------------------------------------------------------------
|
|
1163
1199
|
// downstream dependents advisory helper
|
|
@@ -1243,41 +1279,50 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
1243
1279
|
}
|
|
1244
1280
|
supersededBy = args.superseded_by;
|
|
1245
1281
|
}
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
const
|
|
1258
|
-
if (!
|
|
1259
|
-
return
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1282
|
+
// Read-modify-write over the loaded frontmatter — see
|
|
1283
|
+
// retryOnStaleIfDefaulted above. An explicit base_version passes straight
|
|
1284
|
+
// through (one attempt, loud stale rejection); an omitted one defaults to
|
|
1285
|
+
// the load-time contentHash and gets one transparent retry, so a concurrent
|
|
1286
|
+
// vault_assert's positions array is never silently erased by a clean
|
|
1287
|
+
// deprecate commit.
|
|
1288
|
+
const attemptDeprecate = async () => {
|
|
1289
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_deprecate");
|
|
1290
|
+
if (!target.ok)
|
|
1291
|
+
return target;
|
|
1292
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1293
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1294
|
+
if (!rbac.ok)
|
|
1295
|
+
return rbac;
|
|
1296
|
+
// Same predecessor-only handoff as vault_supersede: this writes exactly
|
|
1297
|
+
// the document being deprecated, which it already locks and commits.
|
|
1298
|
+
let validUntil = null;
|
|
1299
|
+
if (boundary.value !== null) {
|
|
1300
|
+
const closing = closingUntil(oldFrontmatter, boundary.value, "vault_deprecate", path.value);
|
|
1301
|
+
if (!closing.ok)
|
|
1302
|
+
return closing;
|
|
1303
|
+
validUntil = closing.value;
|
|
1304
|
+
}
|
|
1305
|
+
return performFrontmatterWrite({
|
|
1306
|
+
vaultRoot,
|
|
1307
|
+
target: target.value,
|
|
1308
|
+
agent: agent.value,
|
|
1309
|
+
tool: "vault_deprecate",
|
|
1310
|
+
action: "deprecate",
|
|
1311
|
+
newFrontmatter: {
|
|
1312
|
+
...oldFrontmatter,
|
|
1313
|
+
status: "deprecated",
|
|
1314
|
+
superseded_by: supersededBy,
|
|
1315
|
+
...(validUntil !== null ? { valid_until: validUntil } : {}),
|
|
1316
|
+
updated: todayISO(),
|
|
1317
|
+
updated_by: agent.value,
|
|
1318
|
+
},
|
|
1319
|
+
commitMessage: `vault_deprecate: ${path.value} by ${agent.value} — ${reason.value}` +
|
|
1320
|
+
(supersededBy ? ` (superseded by ${supersededBy})` : ""),
|
|
1321
|
+
baseVersion: baseVersion.value ?? target.value.contentHash,
|
|
1322
|
+
access,
|
|
1323
|
+
});
|
|
1324
|
+
};
|
|
1325
|
+
const written = await retryOnStaleIfDefaulted(baseVersion.value, attemptDeprecate);
|
|
1281
1326
|
if (!written.ok)
|
|
1282
1327
|
return written;
|
|
1283
1328
|
// Build the downstream dependents advisory (best-effort, never fails the write).
|
|
@@ -1320,45 +1365,55 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
|
|
|
1320
1365
|
const baseVersion = readBaseVersion(args, "vault_set_confidence");
|
|
1321
1366
|
if (!baseVersion.ok)
|
|
1322
1367
|
return baseVersion;
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1368
|
+
// Read-modify-write over the loaded frontmatter — see
|
|
1369
|
+
// retryOnStaleIfDefaulted above. An explicit base_version passes straight
|
|
1370
|
+
// through (one attempt, loud stale rejection); an omitted one defaults to
|
|
1371
|
+
// the load-time contentHash and gets one transparent retry, so a concurrent
|
|
1372
|
+
// vault_assert's positions array is never silently erased by a clean
|
|
1373
|
+
// confidence-set commit.
|
|
1374
|
+
const attemptSetConfidence = async () => {
|
|
1375
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_confidence");
|
|
1376
|
+
if (!target.ok)
|
|
1377
|
+
return target;
|
|
1378
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1379
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1380
|
+
if (!rbac.ok)
|
|
1381
|
+
return rbac;
|
|
1382
|
+
// No-op guard: a confidence already at the target would churn a commit for
|
|
1383
|
+
// no change. Surface it as an error so a redundant staged confidence-up
|
|
1384
|
+
// does not silently no-op (and a caller learns the value was already
|
|
1385
|
+
// set). Compare against the *raw* on-disk value, not the validated
|
|
1386
|
+
// frontmatter — the validator defaults a missing confidence to "low", so
|
|
1387
|
+
// comparing the validated value would wrongly reject set_confidence(…,
|
|
1388
|
+
// "low") on a doc that never declared one and never write the field (the
|
|
1389
|
+
// trap vault_promote dodges the same way, via parsed.value.raw.confidence).
|
|
1390
|
+
const rawConfidence = target.value.parsed.raw.confidence;
|
|
1391
|
+
const currentConfidence = typeof rawConfidence === "string" &&
|
|
1392
|
+
CONFIDENCES.includes(rawConfidence)
|
|
1393
|
+
? rawConfidence
|
|
1394
|
+
: undefined;
|
|
1395
|
+
if (currentConfidence === confidence.value) {
|
|
1396
|
+
return err(new Error(`vault_set_confidence: ${path.value} confidence is already '${confidence.value}'`));
|
|
1397
|
+
}
|
|
1398
|
+
return performFrontmatterWrite({
|
|
1399
|
+
vaultRoot,
|
|
1400
|
+
target: target.value,
|
|
1401
|
+
agent: agent.value,
|
|
1402
|
+
tool: "vault_set_confidence",
|
|
1403
|
+
action: "confidence-set",
|
|
1404
|
+
newFrontmatter: {
|
|
1405
|
+
...oldFrontmatter,
|
|
1406
|
+
confidence: confidence.value,
|
|
1407
|
+
updated: todayISO(),
|
|
1408
|
+
updated_by: agent.value,
|
|
1409
|
+
},
|
|
1410
|
+
commitMessage: `vault_set_confidence: ${path.value} ${oldFrontmatter.confidence}→${confidence.value} ` +
|
|
1411
|
+
`by ${agent.value} — ${reason.value}`,
|
|
1412
|
+
baseVersion: baseVersion.value ?? target.value.contentHash,
|
|
1413
|
+
access,
|
|
1414
|
+
});
|
|
1415
|
+
};
|
|
1416
|
+
return retryOnStaleIfDefaulted(baseVersion.value, attemptSetConfidence);
|
|
1362
1417
|
}
|
|
1363
1418
|
// ---------------------------------------------------------------------------
|
|
1364
1419
|
// vault_set_tier (#141)
|
|
@@ -1396,47 +1451,56 @@ export async function vaultSetTier(vaultRoot, args, access) {
|
|
|
1396
1451
|
const baseVersion = readBaseVersion(args, "vault_set_tier");
|
|
1397
1452
|
if (!baseVersion.ok)
|
|
1398
1453
|
return baseVersion;
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1404
|
-
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
|
|
1420
|
-
|
|
1421
|
-
|
|
1422
|
-
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
|
-
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1454
|
+
// Read-modify-write over the loaded frontmatter — see
|
|
1455
|
+
// retryOnStaleIfDefaulted above. An explicit base_version passes straight
|
|
1456
|
+
// through (one attempt, loud stale rejection); an omitted one defaults to
|
|
1457
|
+
// the load-time contentHash and gets one transparent retry, so a concurrent
|
|
1458
|
+
// vault_assert's positions array is never silently erased by a clean
|
|
1459
|
+
// tier-set commit.
|
|
1460
|
+
const attemptSetTier = async () => {
|
|
1461
|
+
const target = await loadTargetDocument(vaultRoot, path.value, "vault_set_tier");
|
|
1462
|
+
if (!target.ok)
|
|
1463
|
+
return target;
|
|
1464
|
+
const oldFrontmatter = target.value.parsed.frontmatter;
|
|
1465
|
+
const rbac = requireWriteAccess(access, collectionOf(path.value, oldFrontmatter));
|
|
1466
|
+
if (!rbac.ok)
|
|
1467
|
+
return rbac;
|
|
1468
|
+
// The manual consent boundary: only a human identity may lift `manual`.
|
|
1469
|
+
if (oldFrontmatter.tier === "manual" &&
|
|
1470
|
+
newTier !== "manual" &&
|
|
1471
|
+
!agent.value.startsWith("human:")) {
|
|
1472
|
+
return err(new Error(`vault_set_tier: ${path.value} is tier 'manual' — moving it away from ` +
|
|
1473
|
+
`'manual' requires a human:* identity (got '${agent.value}').`));
|
|
1474
|
+
}
|
|
1475
|
+
// No-op guard, same shape as vault_set_confidence: compare against the
|
|
1476
|
+
// raw on-disk value so an invalid raw tier (validated down to null) can
|
|
1477
|
+
// still be set to any member.
|
|
1478
|
+
const rawTier = target.value.parsed.raw.tier;
|
|
1479
|
+
const currentTier = typeof rawTier === "string" && TIERS.includes(rawTier)
|
|
1480
|
+
? rawTier
|
|
1481
|
+
: undefined;
|
|
1482
|
+
if (currentTier === newTier) {
|
|
1483
|
+
return err(new Error(`vault_set_tier: ${path.value} tier is already '${newTier}'`));
|
|
1484
|
+
}
|
|
1485
|
+
return performFrontmatterWrite({
|
|
1486
|
+
vaultRoot,
|
|
1487
|
+
target: target.value,
|
|
1488
|
+
agent: agent.value,
|
|
1489
|
+
tool: "vault_set_tier",
|
|
1490
|
+
action: "tier-set",
|
|
1491
|
+
newFrontmatter: {
|
|
1492
|
+
...oldFrontmatter,
|
|
1493
|
+
tier: newTier,
|
|
1494
|
+
updated: todayISO(),
|
|
1495
|
+
updated_by: agent.value,
|
|
1496
|
+
},
|
|
1497
|
+
commitMessage: `vault_set_tier: ${path.value} ${oldFrontmatter.tier ?? "unset"}→${newTier} ` +
|
|
1498
|
+
`by ${agent.value} — ${reason.value}`,
|
|
1499
|
+
baseVersion: baseVersion.value ?? target.value.contentHash,
|
|
1500
|
+
access,
|
|
1501
|
+
});
|
|
1502
|
+
};
|
|
1503
|
+
return retryOnStaleIfDefaulted(baseVersion.value, attemptSetTier);
|
|
1440
1504
|
}
|
|
1441
1505
|
// ---------------------------------------------------------------------------
|
|
1442
1506
|
// vault_supersede (§11.4)
|
|
@@ -1894,6 +1958,15 @@ const agentProperty = {
|
|
|
1894
1958
|
// surface a caller reads before invoking.
|
|
1895
1959
|
const shadowNote = " If the vault runs shadow_mode, the write is computed and logged to the " +
|
|
1896
1960
|
"shadow store but NOT applied; the result carries shadow: true.";
|
|
1961
|
+
// Appended to the description of every read-modify-write tool whose
|
|
1962
|
+
// base_version defaults internally (append, promote, deprecate,
|
|
1963
|
+
// set_confidence, set_tier): unlike vault_write, an omitted base_version here
|
|
1964
|
+
// is NOT last-write-wins — it defaults to the version this call itself read,
|
|
1965
|
+
// and a race is retried once before failing loudly.
|
|
1966
|
+
const staleRetryNote = " If base_version is omitted, a concurrent change is retried once " +
|
|
1967
|
+
"automatically before this fails loudly as stale; an explicitly supplied " +
|
|
1968
|
+
"base_version that is stale is rejected immediately, with no retry — " +
|
|
1969
|
+
"re-read and resubmit.";
|
|
1897
1970
|
const baseVersionProperty = {
|
|
1898
1971
|
type: "string",
|
|
1899
1972
|
description: "Optional optimistic-concurrency token: the 'version' that vault_read " +
|
|
@@ -2265,6 +2338,7 @@ export const writeTools = [
|
|
|
2265
2338
|
"Appending links to generative-domain docs onto an accumulation-domain " +
|
|
2266
2339
|
"doc returns advisory domain_warnings naming them; the append still " +
|
|
2267
2340
|
"lands." +
|
|
2341
|
+
staleRetryNote +
|
|
2268
2342
|
shadowNote,
|
|
2269
2343
|
inputSchema: {
|
|
2270
2344
|
type: "object",
|
|
@@ -2299,6 +2373,7 @@ export const writeTools = [
|
|
|
2299
2373
|
description: "Promote a draft document to canonical status. Refuses unless the " +
|
|
2300
2374
|
"document is currently a draft, its frontmatter is complete, and a " +
|
|
2301
2375
|
"confidence level has been explicitly set. Auto-commits." +
|
|
2376
|
+
staleRetryNote +
|
|
2302
2377
|
shadowNote,
|
|
2303
2378
|
inputSchema: {
|
|
2304
2379
|
type: "object",
|
|
@@ -2326,6 +2401,7 @@ export const writeTools = [
|
|
|
2326
2401
|
annotations: { destructiveHint: true },
|
|
2327
2402
|
description: "Mark a document deprecated. A reason is required; optionally record " +
|
|
2328
2403
|
"the document that supersedes it. Auto-commits." +
|
|
2404
|
+
staleRetryNote +
|
|
2329
2405
|
shadowNote,
|
|
2330
2406
|
inputSchema: {
|
|
2331
2407
|
type: "object",
|
|
@@ -2363,6 +2439,7 @@ export const writeTools = [
|
|
|
2363
2439
|
description: "Change only a document's confidence level (low | medium | high), leaving " +
|
|
2364
2440
|
"its status and body untouched. A reason is required and recorded. Rejects " +
|
|
2365
2441
|
"if the confidence is already at the target. Auto-commits." +
|
|
2442
|
+
staleRetryNote +
|
|
2366
2443
|
shadowNote,
|
|
2367
2444
|
inputSchema: {
|
|
2368
2445
|
type: "object",
|
|
@@ -2405,6 +2482,7 @@ export const writeTools = [
|
|
|
2405
2482
|
"logged for lint review), then write. Moving a doc away from 'manual' " +
|
|
2406
2483
|
"requires a human:* identity. Rejects if the tier is already at the " +
|
|
2407
2484
|
"target. Auto-commits." +
|
|
2485
|
+
staleRetryNote +
|
|
2408
2486
|
shadowNote,
|
|
2409
2487
|
inputSchema: {
|
|
2410
2488
|
type: "object",
|