daftari 3.5.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/CHANGELOG.md +12 -0
- package/README.md +39 -1
- 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/consolidate/decorrelation.js +1 -1
- package/dist/consolidate/decorrelation.js.map +1 -1
- package/dist/consolidate/index.js +1 -1
- package/dist/court/index.d.ts.map +1 -1
- package/dist/court/index.js +5 -3
- package/dist/court/index.js.map +1 -1
- package/dist/curation/lint.d.ts.map +1 -1
- package/dist/curation/lint.js +68 -1
- package/dist/curation/lint.js.map +1 -1
- package/dist/curation/positions.d.ts +14 -0
- package/dist/curation/positions.d.ts.map +1 -1
- package/dist/curation/positions.js +74 -0
- package/dist/curation/positions.js.map +1 -1
- package/dist/curation/provenance.d.ts.map +1 -1
- package/dist/curation/provenance.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/curation/tension.d.ts +9 -1
- package/dist/curation/tension.d.ts.map +1 -1
- package/dist/curation/tension.js +34 -1
- package/dist/curation/tension.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/federation/classification.d.ts +9 -0
- package/dist/federation/classification.d.ts.map +1 -0
- package/dist/federation/classification.js +122 -0
- package/dist/federation/classification.js.map +1 -0
- package/dist/federation/index-location.d.ts +4 -0
- package/dist/federation/index-location.d.ts.map +1 -0
- package/dist/federation/index-location.js +30 -0
- package/dist/federation/index-location.js.map +1 -0
- package/dist/federation/mount-index.d.ts +8 -0
- package/dist/federation/mount-index.d.ts.map +1 -0
- package/dist/federation/mount-index.js +63 -0
- package/dist/federation/mount-index.js.map +1 -0
- package/dist/federation/mounts.d.ts +29 -0
- package/dist/federation/mounts.d.ts.map +1 -0
- package/dist/federation/mounts.js +215 -0
- package/dist/federation/mounts.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +27 -0
- package/dist/index.js.map +1 -1
- package/dist/search/hybrid.d.ts +10 -0
- package/dist/search/hybrid.d.ts.map +1 -1
- package/dist/search/hybrid.js +28 -15
- package/dist/search/hybrid.js.map +1 -1
- package/dist/search/reindex.d.ts +2 -0
- package/dist/search/reindex.d.ts.map +1 -1
- package/dist/search/reindex.js +17 -9
- package/dist/search/reindex.js.map +1 -1
- package/dist/serve/auth-log.d.ts +16 -0
- package/dist/serve/auth-log.d.ts.map +1 -0
- package/dist/serve/auth-log.js +53 -0
- package/dist/serve/auth-log.js.map +1 -0
- package/dist/serve/index.d.ts +2 -0
- package/dist/serve/index.d.ts.map +1 -1
- package/dist/serve/index.js +141 -10
- package/dist/serve/index.js.map +1 -1
- package/dist/serve/limits.d.ts +37 -0
- package/dist/serve/limits.d.ts.map +1 -0
- package/dist/serve/limits.js +79 -0
- package/dist/serve/limits.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +20 -0
- package/dist/server.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 +9 -3
- package/dist/storage/index-db.js.map +1 -1
- package/dist/tools/curation.d.ts.map +1 -1
- package/dist/tools/curation.js +6 -5
- package/dist/tools/curation.js.map +1 -1
- package/dist/tools/positions.d.ts +8 -2
- package/dist/tools/positions.d.ts.map +1 -1
- package/dist/tools/positions.js +317 -173
- package/dist/tools/positions.js.map +1 -1
- package/dist/tools/read.d.ts +11 -0
- package/dist/tools/read.d.ts.map +1 -1
- package/dist/tools/read.js +188 -10
- package/dist/tools/read.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/search.d.ts +1 -1
- package/dist/tools/search.d.ts.map +1 -1
- package/dist/tools/search.js +455 -38
- package/dist/tools/search.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/witness.d.ts.map +1 -1
- package/dist/tools/witness.js +78 -7
- package/dist/tools/witness.js.map +1 -1
- package/dist/tools/write.d.ts +9 -0
- package/dist/tools/write.d.ts.map +1 -1
- package/dist/tools/write.js +374 -234
- package/dist/tools/write.js.map +1 -1
- package/dist/utils/config.d.ts +34 -0
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +168 -6
- 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 +176 -34
- package/dist/utils/git.js.map +1 -1
- package/dist/utils/vault-gitignore.d.ts +1 -1
- package/dist/utils/vault-gitignore.d.ts.map +1 -1
- package/dist/utils/vault-gitignore.js +1 -0
- package/dist/utils/vault-gitignore.js.map +1 -1
- package/dist/witness/track-record.d.ts +23 -0
- package/dist/witness/track-record.d.ts.map +1 -1
- package/dist/witness/track-record.js +0 -0
- package/dist/witness/track-record.js.map +1 -1
- package/package.json +1 -1
package/dist/tools/write.js
CHANGED
|
@@ -319,7 +319,7 @@ async function performWrite(params) {
|
|
|
319
319
|
reason: `stale: base_version ${shortHash(params.baseVersion)} != ` +
|
|
320
320
|
`current ${currentHash ? shortHash(currentHash) : "<absent>"}`,
|
|
321
321
|
});
|
|
322
|
-
return err(new Error(
|
|
322
|
+
return err(new Error(`${STALE_WRITE_PREFIX} ${params.relPath} changed since base_version`));
|
|
323
323
|
}
|
|
324
324
|
}
|
|
325
325
|
await mkdir(dirname(params.absPath), { recursive: true });
|
|
@@ -334,11 +334,19 @@ async function performWrite(params) {
|
|
|
334
334
|
// wins, like every other path here.
|
|
335
335
|
noteSelfWrite(params.absPath);
|
|
336
336
|
let commitHash = null;
|
|
337
|
+
let commitError = null;
|
|
337
338
|
if (params.autoCommit) {
|
|
338
|
-
const
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
339
|
+
const identity = commitIdentity(params.agent, params.principal);
|
|
340
|
+
const committed = await commit(params.vaultRoot, [params.relPath], params.commitMessage + identity.trailer, identity.author, { gitDir: params.gitDir });
|
|
341
|
+
if (committed.ok)
|
|
342
|
+
commitHash = committed.value.hash;
|
|
343
|
+
// A commit failure does NOT short-circuit: the file is on disk and
|
|
344
|
+
// indexed, so the durable write still gets its provenance entry
|
|
345
|
+
// (flagged uncommitted via `reason`) and its consumes edges — a
|
|
346
|
+
// hole in the ledger where a real mutation happened is worse than a
|
|
347
|
+
// dirty-uncommitted window. The error is returned after.
|
|
348
|
+
else
|
|
349
|
+
commitError = committed.error;
|
|
342
350
|
}
|
|
343
351
|
await recordProvenance(params.vaultRoot, {
|
|
344
352
|
tool: params.tool,
|
|
@@ -349,6 +357,7 @@ async function performWrite(params) {
|
|
|
349
357
|
...(params.bodyChanged !== undefined ? { body_changed: params.bodyChanged } : {}),
|
|
350
358
|
action: params.action,
|
|
351
359
|
frontmatter_diff: frontmatterDiff(params.oldFrontmatter, params.newFrontmatter),
|
|
360
|
+
...(commitError ? { reason: `commit failed: ${commitError.message}` } : {}),
|
|
352
361
|
});
|
|
353
362
|
// #233: a run-correlated write compiles its input set — every path the
|
|
354
363
|
// run read beforehand becomes a consumes edge. Best-effort like the
|
|
@@ -360,6 +369,10 @@ async function performWrite(params) {
|
|
|
360
369
|
runId: params.runId,
|
|
361
370
|
});
|
|
362
371
|
}
|
|
372
|
+
if (commitError) {
|
|
373
|
+
return err(new Error(`${params.relPath} was written and indexed but the git commit failed: ` +
|
|
374
|
+
commitError.message));
|
|
375
|
+
}
|
|
363
376
|
return ok({
|
|
364
377
|
path: params.relPath,
|
|
365
378
|
action: params.action,
|
|
@@ -425,6 +438,62 @@ export function requireWriteAccess(access, collection) {
|
|
|
425
438
|
}
|
|
426
439
|
return ok(undefined);
|
|
427
440
|
}
|
|
441
|
+
// Git history is the attribution layer, and the caller-supplied `agent`
|
|
442
|
+
// string is advisory — any authenticated principal could claim any agent.
|
|
443
|
+
// When an AccessContext exists the commit author is the AUTHENTICATED
|
|
444
|
+
// principal (matching the provenance log's ground-truth `principal` field);
|
|
445
|
+
// the claimed agent survives as a Daftari-Agent trailer so the advisory
|
|
446
|
+
// identity stays in-history. With no access context (operator/stdio), the
|
|
447
|
+
// agent is the only identity there is and authors the commit as before.
|
|
448
|
+
export function commitIdentity(agent, principal) {
|
|
449
|
+
if (!principal || principal === agent)
|
|
450
|
+
return { author: agent, trailer: "" };
|
|
451
|
+
return { author: principal, trailer: `\n\nDaftari-Agent: ${agent}` };
|
|
452
|
+
}
|
|
453
|
+
// The one place the stale-rejection message prefix is defined: the producer
|
|
454
|
+
// (performWrite's base_version check) and the classifier below must agree,
|
|
455
|
+
// or retryOnStale silently stops retrying and the lost-update race returns.
|
|
456
|
+
export const STALE_WRITE_PREFIX = "stale write:";
|
|
457
|
+
// A stale-write rejection from performWrite (base_version mismatch, above).
|
|
458
|
+
// The ONE retryable failure: the rejection proves nothing was written,
|
|
459
|
+
// committed, or indexed, so reload-and-recompute is always safe.
|
|
460
|
+
export function isStaleWriteError(e) {
|
|
461
|
+
return e.message.startsWith(STALE_WRITE_PREFIX);
|
|
462
|
+
}
|
|
463
|
+
// Runs `attempt` and, when it fails with a stale-write rejection, runs it
|
|
464
|
+
// again (once). Each attempt must load its target fresh and recompute the
|
|
465
|
+
// mutation from the reloaded document — sound only for tools whose new
|
|
466
|
+
// frontmatter is a pure function of the load (assert/consolidate), never for
|
|
467
|
+
// callers carrying externally-composed content, whose base_version conflicts
|
|
468
|
+
// belong to the caller. Non-stale failures (lock contention stays fail-fast,
|
|
469
|
+
// slice-3 §3.5) are returned unchanged.
|
|
470
|
+
export async function retryOnStale(attempt) {
|
|
471
|
+
const first = await attempt();
|
|
472
|
+
if (first.ok || !isStaleWriteError(first.error))
|
|
473
|
+
return first;
|
|
474
|
+
return attempt();
|
|
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
|
+
}
|
|
428
497
|
export async function loadTargetDocument(vaultRoot, rawPath, tool) {
|
|
429
498
|
const resolved = resolveVaultPath(vaultRoot, rawPath);
|
|
430
499
|
if (!resolved.ok)
|
|
@@ -447,6 +516,7 @@ export async function loadTargetDocument(vaultRoot, rawPath, tool) {
|
|
|
447
516
|
absPath: resolved.value.absPath,
|
|
448
517
|
parsed: parsed.value,
|
|
449
518
|
config: config.value,
|
|
519
|
+
contentHash: sha256Hex(existing.value),
|
|
450
520
|
});
|
|
451
521
|
}
|
|
452
522
|
// The shared performWrite tail for frontmatter-only mutations: body preserved
|
|
@@ -677,6 +747,13 @@ export async function vaultWrite(vaultRoot, args, access) {
|
|
|
677
747
|
? args.reason.trim()
|
|
678
748
|
: `propose-only role '${access.roleName}': write staged for ratification`,
|
|
679
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) } : {}),
|
|
680
757
|
...(runId.value !== undefined ? { runId: runId.value } : {}),
|
|
681
758
|
});
|
|
682
759
|
if (!staged.ok)
|
|
@@ -961,91 +1038,90 @@ export async function vaultAppend(vaultRoot, args, access) {
|
|
|
961
1038
|
const proposeGate = denyIfProposeOnly(access, "vault_append");
|
|
962
1039
|
if (!proposeGate.ok)
|
|
963
1040
|
return proposeGate;
|
|
964
|
-
const
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
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 });
|
|
986
1103
|
};
|
|
987
|
-
const
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
// values. A transform throw or non-object return blocks the append.
|
|
992
|
-
const loadedTransformHooks = await loadPreWriteTransformHooks(vaultRoot, config.value.hooks.preWriteTransform);
|
|
993
|
-
if (!loadedTransformHooks.ok)
|
|
994
|
-
return loadedTransformHooks;
|
|
995
|
-
const transformResult = runPreWriteTransformHooks(loadedTransformHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
996
|
-
Object.assign(newFrontmatter, transformResult.merged);
|
|
997
|
-
// Pre-write hooks see the post-stamp, post-transform frontmatter (the same
|
|
998
|
-
// shape a subsequent vault_read would return). Issues block the append,
|
|
999
|
-
// same as for vault_write.
|
|
1000
|
-
const loadedHooks = await loadHooks(vaultRoot, config.value.hooks.preWrite);
|
|
1001
|
-
if (!loadedHooks.ok)
|
|
1002
|
-
return loadedHooks;
|
|
1003
|
-
const hookIssues = runPreWriteHooks(loadedHooks.value, newFrontmatter, { path: path.value, operation: "append" });
|
|
1004
|
-
const appendIssues = [...transformResult.issues, ...hookIssues];
|
|
1005
|
-
if (appendIssues.length > 0) {
|
|
1006
|
-
const summary = appendIssues.map((i) => `${i.field}: ${i.message}`).join("; ");
|
|
1007
|
-
return err(new Error(`invalid frontmatter: ${summary}`));
|
|
1008
|
-
}
|
|
1009
|
-
const appended = await performWrite({
|
|
1010
|
-
vaultRoot,
|
|
1011
|
-
// Lock key, provenance, and commit path are all keyed on the CANONICAL
|
|
1012
|
-
// relPath (resolved.value.relPath), never the raw caller string: aliased
|
|
1013
|
-
// spellings of one file must contend on one lock (#127/#128).
|
|
1014
|
-
relPath: resolved.value.relPath,
|
|
1015
|
-
absPath: resolved.value.absPath,
|
|
1016
|
-
agent: agent.value,
|
|
1017
|
-
tool: "vault_append",
|
|
1018
|
-
action: "append",
|
|
1019
|
-
fileText: serializeDocument(newFrontmatter, newBody, extensions, parsed.value.raw),
|
|
1020
|
-
newFrontmatter,
|
|
1021
|
-
oldFrontmatter,
|
|
1022
|
-
validation: parsed.value.validation,
|
|
1023
|
-
commitMessage: `vault_append: ${path.value} by ${agent.value}`,
|
|
1024
|
-
autoCommit: config.value.autoCommit,
|
|
1025
|
-
gitDir: config.value.gitDir,
|
|
1026
|
-
baseVersion: baseVersion.value,
|
|
1027
|
-
shadowMode: config.value.shadowMode,
|
|
1028
|
-
principal: access?.user,
|
|
1029
|
-
...(runId.value !== undefined ? { runId: runId.value } : {}),
|
|
1030
|
-
bodyChanged: true,
|
|
1031
|
-
});
|
|
1104
|
+
const attempt = await retryOnStaleIfDefaulted(baseVersion.value, attemptAppend);
|
|
1105
|
+
if (!attempt.ok)
|
|
1106
|
+
return attempt;
|
|
1107
|
+
const { written, domain } = attempt.value;
|
|
1032
1108
|
// #4: an appended section can introduce body links into generative-domain
|
|
1033
1109
|
// docs — same advisory channel as vault_write, scoped to what THIS append
|
|
1034
1110
|
// added: only the new section is scanned (a doc that already leaned on
|
|
1035
1111
|
// generative material warned at write time; re-warning on every later,
|
|
1036
1112
|
// unrelated append would drown the signal), and sources are skipped
|
|
1037
1113
|
// entirely because an append cannot change frontmatter.
|
|
1038
|
-
if (
|
|
1039
|
-
return
|
|
1114
|
+
if (written.shadow)
|
|
1115
|
+
return ok(written);
|
|
1040
1116
|
const appendWarnings = generativeDomainRefs(vaultRoot, {
|
|
1041
|
-
domain
|
|
1117
|
+
domain,
|
|
1042
1118
|
sources: [],
|
|
1043
1119
|
body: section.value,
|
|
1044
|
-
relPath:
|
|
1120
|
+
relPath: written.path,
|
|
1045
1121
|
}, access);
|
|
1046
1122
|
if (appendWarnings === null)
|
|
1047
|
-
return
|
|
1048
|
-
return ok({ ...
|
|
1123
|
+
return ok(written);
|
|
1124
|
+
return ok({ ...written, domain_warnings: appendWarnings });
|
|
1049
1125
|
}
|
|
1050
1126
|
// ---------------------------------------------------------------------------
|
|
1051
1127
|
// vault_promote
|
|
@@ -1072,43 +1148,52 @@ export async function vaultPromote(vaultRoot, args, access) {
|
|
|
1072
1148
|
if (access && !canPromote(access.role)) {
|
|
1073
1149
|
return err(new Error(`access denied: role '${access.roleName}' cannot promote documents`));
|
|
1074
1150
|
}
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
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);
|
|
1112
1197
|
}
|
|
1113
1198
|
// ---------------------------------------------------------------------------
|
|
1114
1199
|
// downstream dependents advisory helper
|
|
@@ -1194,41 +1279,50 @@ export async function vaultDeprecate(vaultRoot, args, access) {
|
|
|
1194
1279
|
}
|
|
1195
1280
|
supersededBy = args.superseded_by;
|
|
1196
1281
|
}
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
const
|
|
1209
|
-
if (!
|
|
1210
|
-
return
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
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);
|
|
1232
1326
|
if (!written.ok)
|
|
1233
1327
|
return written;
|
|
1234
1328
|
// Build the downstream dependents advisory (best-effort, never fails the write).
|
|
@@ -1271,45 +1365,55 @@ export async function vaultSetConfidence(vaultRoot, args, access) {
|
|
|
1271
1365
|
const baseVersion = readBaseVersion(args, "vault_set_confidence");
|
|
1272
1366
|
if (!baseVersion.ok)
|
|
1273
1367
|
return baseVersion;
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
|
|
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);
|
|
1313
1417
|
}
|
|
1314
1418
|
// ---------------------------------------------------------------------------
|
|
1315
1419
|
// vault_set_tier (#141)
|
|
@@ -1347,47 +1451,56 @@ export async function vaultSetTier(vaultRoot, args, access) {
|
|
|
1347
1451
|
const baseVersion = readBaseVersion(args, "vault_set_tier");
|
|
1348
1452
|
if (!baseVersion.ok)
|
|
1349
1453
|
return baseVersion;
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
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);
|
|
1391
1504
|
}
|
|
1392
1505
|
// ---------------------------------------------------------------------------
|
|
1393
1506
|
// vault_supersede (§11.4)
|
|
@@ -1471,6 +1584,7 @@ export async function vaultSupersede(vaultRoot, args, access) {
|
|
|
1471
1584
|
absPath: resolvedOld.value.absPath,
|
|
1472
1585
|
parsed: parsed.value,
|
|
1473
1586
|
config: config.value,
|
|
1587
|
+
contentHash: sha256Hex(existing.value),
|
|
1474
1588
|
},
|
|
1475
1589
|
agent: agent.value,
|
|
1476
1590
|
tool: "vault_supersede",
|
|
@@ -1769,11 +1883,18 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1769
1883
|
await writeFile(w.absPath, w.fileText, "utf-8");
|
|
1770
1884
|
}
|
|
1771
1885
|
let commitHash = null;
|
|
1886
|
+
let commitError = null;
|
|
1772
1887
|
if (config.value.autoCommit) {
|
|
1773
|
-
const
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
|
|
1888
|
+
const identity = commitIdentity(agent.value, access?.user);
|
|
1889
|
+
const committed = await commit(vaultRoot, writes.map((w) => w.relPath), `vault_merge: ${pathA.value} + ${pathB.value} → ${targetPath.value} by ${agent.value}` +
|
|
1890
|
+
identity.trailer, identity.author, { gitDir: config.value.gitDir });
|
|
1891
|
+
if (committed.ok)
|
|
1892
|
+
commitHash = committed.value.hash;
|
|
1893
|
+
// Same discipline as performWrite: all three files are durable on
|
|
1894
|
+
// disk, so a commit failure must not skip their index rows and
|
|
1895
|
+
// provenance entries — record them flagged uncommitted, error after.
|
|
1896
|
+
else
|
|
1897
|
+
commitError = committed.error;
|
|
1777
1898
|
}
|
|
1778
1899
|
// Index each written doc and log provenance per file. Both are best-effort
|
|
1779
1900
|
// (the index is a rebuildable cache; the log is advisory) so a failure here
|
|
@@ -1796,8 +1917,13 @@ export async function vaultMerge(vaultRoot, args, access) {
|
|
|
1796
1917
|
// frontmatter stamps.
|
|
1797
1918
|
body_changed: w.action === "merge",
|
|
1798
1919
|
frontmatter_diff: frontmatterDiff(w.oldFrontmatter, w.newFrontmatter),
|
|
1920
|
+
...(commitError ? { reason: `commit failed: ${commitError.message}` } : {}),
|
|
1799
1921
|
});
|
|
1800
1922
|
}
|
|
1923
|
+
if (commitError) {
|
|
1924
|
+
return err(new Error(`vault_merge: ${writes.length} files were written and indexed but the git commit ` +
|
|
1925
|
+
`failed: ${commitError.message}`));
|
|
1926
|
+
}
|
|
1801
1927
|
return ok({
|
|
1802
1928
|
path: targetPath.value,
|
|
1803
1929
|
action: "merge",
|
|
@@ -1832,6 +1958,15 @@ const agentProperty = {
|
|
|
1832
1958
|
// surface a caller reads before invoking.
|
|
1833
1959
|
const shadowNote = " If the vault runs shadow_mode, the write is computed and logged to the " +
|
|
1834
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.";
|
|
1835
1970
|
const baseVersionProperty = {
|
|
1836
1971
|
type: "string",
|
|
1837
1972
|
description: "Optional optimistic-concurrency token: the 'version' that vault_read " +
|
|
@@ -2203,6 +2338,7 @@ export const writeTools = [
|
|
|
2203
2338
|
"Appending links to generative-domain docs onto an accumulation-domain " +
|
|
2204
2339
|
"doc returns advisory domain_warnings naming them; the append still " +
|
|
2205
2340
|
"lands." +
|
|
2341
|
+
staleRetryNote +
|
|
2206
2342
|
shadowNote,
|
|
2207
2343
|
inputSchema: {
|
|
2208
2344
|
type: "object",
|
|
@@ -2237,6 +2373,7 @@ export const writeTools = [
|
|
|
2237
2373
|
description: "Promote a draft document to canonical status. Refuses unless the " +
|
|
2238
2374
|
"document is currently a draft, its frontmatter is complete, and a " +
|
|
2239
2375
|
"confidence level has been explicitly set. Auto-commits." +
|
|
2376
|
+
staleRetryNote +
|
|
2240
2377
|
shadowNote,
|
|
2241
2378
|
inputSchema: {
|
|
2242
2379
|
type: "object",
|
|
@@ -2264,6 +2401,7 @@ export const writeTools = [
|
|
|
2264
2401
|
annotations: { destructiveHint: true },
|
|
2265
2402
|
description: "Mark a document deprecated. A reason is required; optionally record " +
|
|
2266
2403
|
"the document that supersedes it. Auto-commits." +
|
|
2404
|
+
staleRetryNote +
|
|
2267
2405
|
shadowNote,
|
|
2268
2406
|
inputSchema: {
|
|
2269
2407
|
type: "object",
|
|
@@ -2301,6 +2439,7 @@ export const writeTools = [
|
|
|
2301
2439
|
description: "Change only a document's confidence level (low | medium | high), leaving " +
|
|
2302
2440
|
"its status and body untouched. A reason is required and recorded. Rejects " +
|
|
2303
2441
|
"if the confidence is already at the target. Auto-commits." +
|
|
2442
|
+
staleRetryNote +
|
|
2304
2443
|
shadowNote,
|
|
2305
2444
|
inputSchema: {
|
|
2306
2445
|
type: "object",
|
|
@@ -2343,6 +2482,7 @@ export const writeTools = [
|
|
|
2343
2482
|
"logged for lint review), then write. Moving a doc away from 'manual' " +
|
|
2344
2483
|
"requires a human:* identity. Rejects if the tier is already at the " +
|
|
2345
2484
|
"target. Auto-commits." +
|
|
2485
|
+
staleRetryNote +
|
|
2346
2486
|
shadowNote,
|
|
2347
2487
|
inputSchema: {
|
|
2348
2488
|
type: "object",
|