daftari 3.0.0 → 3.2.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.
Files changed (123) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +11 -5
  3. package/dist/access/locks.d.ts +1 -0
  4. package/dist/access/locks.d.ts.map +1 -1
  5. package/dist/access/locks.js +13 -0
  6. package/dist/access/locks.js.map +1 -1
  7. package/dist/access/rbac.js +3 -3
  8. package/dist/access/rbac.js.map +1 -1
  9. package/dist/asof/git-read.d.ts.map +1 -1
  10. package/dist/asof/git-read.js +4 -0
  11. package/dist/asof/git-read.js.map +1 -1
  12. package/dist/audit/describes.d.ts +7 -0
  13. package/dist/audit/describes.d.ts.map +1 -1
  14. package/dist/audit/describes.js +48 -16
  15. package/dist/audit/describes.js.map +1 -1
  16. package/dist/backfill/derive.d.ts.map +1 -1
  17. package/dist/backfill/derive.js +3 -0
  18. package/dist/backfill/derive.js.map +1 -1
  19. package/dist/curation/lint-voice.d.ts.map +1 -1
  20. package/dist/curation/lint-voice.js +2 -0
  21. package/dist/curation/lint-voice.js.map +1 -1
  22. package/dist/curation/lint.d.ts +1 -1
  23. package/dist/curation/lint.d.ts.map +1 -1
  24. package/dist/curation/lint.js +95 -0
  25. package/dist/curation/lint.js.map +1 -1
  26. package/dist/curation/positions.d.ts +29 -0
  27. package/dist/curation/positions.d.ts.map +1 -0
  28. package/dist/curation/positions.js +164 -0
  29. package/dist/curation/positions.js.map +1 -0
  30. package/dist/curation/staged-actions.d.ts +1 -1
  31. package/dist/curation/staged-actions.d.ts.map +1 -1
  32. package/dist/curation/staged-actions.js +1 -0
  33. package/dist/curation/staged-actions.js.map +1 -1
  34. package/dist/curation/staleness.d.ts +0 -7
  35. package/dist/curation/staleness.d.ts.map +1 -1
  36. package/dist/curation/staleness.js +0 -30
  37. package/dist/curation/staleness.js.map +1 -1
  38. package/dist/curation/tension.d.ts +5 -2
  39. package/dist/curation/tension.d.ts.map +1 -1
  40. package/dist/curation/tension.js +169 -103
  41. package/dist/curation/tension.js.map +1 -1
  42. package/dist/curation/vault-docs.d.ts +10 -0
  43. package/dist/curation/vault-docs.d.ts.map +1 -1
  44. package/dist/curation/vault-docs.js +101 -10
  45. package/dist/curation/vault-docs.js.map +1 -1
  46. package/dist/eval/llm-openrouter.d.ts.map +1 -1
  47. package/dist/eval/llm-openrouter.js +8 -0
  48. package/dist/eval/llm-openrouter.js.map +1 -1
  49. package/dist/frontmatter/schema.d.ts.map +1 -1
  50. package/dist/frontmatter/schema.js +118 -1
  51. package/dist/frontmatter/schema.js.map +1 -1
  52. package/dist/frontmatter/types.d.ts +26 -2
  53. package/dist/frontmatter/types.d.ts.map +1 -1
  54. package/dist/frontmatter/types.js +7 -0
  55. package/dist/frontmatter/types.js.map +1 -1
  56. package/dist/lifecycle/lock.d.ts +2 -0
  57. package/dist/lifecycle/lock.d.ts.map +1 -1
  58. package/dist/lifecycle/lock.js +98 -18
  59. package/dist/lifecycle/lock.js.map +1 -1
  60. package/dist/search/providers/openai-3-small.d.ts.map +1 -1
  61. package/dist/search/providers/openai-3-small.js +8 -0
  62. package/dist/search/providers/openai-3-small.js.map +1 -1
  63. package/dist/search/reindex.d.ts.map +1 -1
  64. package/dist/search/reindex.js +39 -13
  65. package/dist/search/reindex.js.map +1 -1
  66. package/dist/serve/index.d.ts +4 -1
  67. package/dist/serve/index.d.ts.map +1 -1
  68. package/dist/serve/index.js +28 -12
  69. package/dist/serve/index.js.map +1 -1
  70. package/dist/server.d.ts.map +1 -1
  71. package/dist/server.js +2 -0
  72. package/dist/server.js.map +1 -1
  73. package/dist/sleep/cycle.d.ts +12 -0
  74. package/dist/sleep/cycle.d.ts.map +1 -1
  75. package/dist/sleep/cycle.js +98 -2
  76. package/dist/sleep/cycle.js.map +1 -1
  77. package/dist/sleep/report.d.ts.map +1 -1
  78. package/dist/sleep/report.js +31 -0
  79. package/dist/sleep/report.js.map +1 -1
  80. package/dist/storage/index-db.d.ts +1 -0
  81. package/dist/storage/index-db.d.ts.map +1 -1
  82. package/dist/storage/index-db.js +17 -2
  83. package/dist/storage/index-db.js.map +1 -1
  84. package/dist/tools/anchors.d.ts +12 -0
  85. package/dist/tools/anchors.d.ts.map +1 -0
  86. package/dist/tools/anchors.js +64 -0
  87. package/dist/tools/anchors.js.map +1 -0
  88. package/dist/tools/pin-mint.d.ts +49 -0
  89. package/dist/tools/pin-mint.d.ts.map +1 -0
  90. package/dist/tools/pin-mint.js +157 -0
  91. package/dist/tools/pin-mint.js.map +1 -0
  92. package/dist/tools/positions.d.ts +42 -0
  93. package/dist/tools/positions.d.ts.map +1 -0
  94. package/dist/tools/positions.js +711 -0
  95. package/dist/tools/positions.js.map +1 -0
  96. package/dist/tools/read.d.ts +46 -1
  97. package/dist/tools/read.d.ts.map +1 -1
  98. package/dist/tools/read.js +302 -3
  99. package/dist/tools/read.js.map +1 -1
  100. package/dist/tools/repin.d.ts +29 -0
  101. package/dist/tools/repin.d.ts.map +1 -0
  102. package/dist/tools/repin.js +140 -0
  103. package/dist/tools/repin.js.map +1 -0
  104. package/dist/tools/staged-actions.d.ts.map +1 -1
  105. package/dist/tools/staged-actions.js +102 -6
  106. package/dist/tools/staged-actions.js.map +1 -1
  107. package/dist/tools/write.d.ts +30 -2
  108. package/dist/tools/write.d.ts.map +1 -1
  109. package/dist/tools/write.js +149 -12
  110. package/dist/tools/write.js.map +1 -1
  111. package/dist/utils/concurrency.d.ts +2 -0
  112. package/dist/utils/concurrency.d.ts.map +1 -0
  113. package/dist/utils/concurrency.js +39 -0
  114. package/dist/utils/concurrency.js.map +1 -0
  115. package/dist/utils/config.d.ts +3 -0
  116. package/dist/utils/config.d.ts.map +1 -1
  117. package/dist/utils/config.js +45 -0
  118. package/dist/utils/config.js.map +1 -1
  119. package/dist/utils/git.d.ts +3 -0
  120. package/dist/utils/git.d.ts.map +1 -1
  121. package/dist/utils/git.js +34 -1
  122. package/dist/utils/git.js.map +1 -1
  123. package/package.json +2 -2
@@ -1,13 +1,17 @@
1
1
  import { type AccessContext } from "../access/rbac.js";
2
2
  import { type BlastDownstreamEntry, type HiddenDownstream } from "../curation/tension-blast.js";
3
+ import { type ParsedDocument } from "../frontmatter/parser.js";
3
4
  import { type Frontmatter, type Result, type ValidationReport } from "../frontmatter/types.js";
4
- import { type SchemaExtension } from "../utils/config.js";
5
+ import { type DaftariConfig, type SchemaExtension } from "../utils/config.js";
6
+ import type { MintedEntry, UnresolvedEntry } from "./pin-mint.js";
5
7
  import type { ToolDefinition } from "./read.js";
8
+ export declare function requireIndexReady(): Result<void, Error>;
9
+ export declare function targetCollection(vaultRoot: string, relPath: string): string;
6
10
  export declare function applyExtensionDefaults(raw: Record<string, unknown>, extensions: SchemaExtension[]): Record<string, unknown>;
7
11
  export declare function serializeDocument(fm: Frontmatter, body: string, extensions?: SchemaExtension[], raw?: Record<string, unknown>): string;
8
12
  export interface WriteResult {
9
13
  path: string;
10
- action: "create" | "update" | "append" | "promote" | "deprecate" | "supersede" | "merge" | "confidence-set" | "tier-set" | "staged";
14
+ action: "create" | "update" | "append" | "promote" | "deprecate" | "supersede" | "merge" | "confidence-set" | "tier-set" | "assert" | "consolidate" | "staged";
11
15
  commit: string | null;
12
16
  committed: boolean;
13
17
  status: string;
@@ -23,6 +27,10 @@ export interface WriteResult {
23
27
  conflicts_with?: string[];
24
28
  tension_id?: string | null;
25
29
  tension_error?: string;
30
+ pin_mint?: {
31
+ minted: MintedEntry[];
32
+ unresolved: UnresolvedEntry[];
33
+ };
26
34
  dependents?: {
27
35
  downstream: BlastDownstreamEntry[];
28
36
  primary_blast: number;
@@ -30,6 +38,26 @@ export interface WriteResult {
30
38
  hidden_downstream: HiddenDownstream;
31
39
  };
32
40
  }
41
+ export declare function requireWriteAccess(access: AccessContext | undefined, collection: string): Result<void, Error>;
42
+ export interface TargetDocument {
43
+ relPath: string;
44
+ absPath: string;
45
+ parsed: ParsedDocument;
46
+ config: DaftariConfig;
47
+ }
48
+ export declare function loadTargetDocument(vaultRoot: string, rawPath: string, tool: string): Promise<Result<TargetDocument, Error>>;
49
+ export declare function performFrontmatterWrite(opts: {
50
+ vaultRoot: string;
51
+ target: TargetDocument;
52
+ agent: string;
53
+ tool: string;
54
+ action: WriteResult["action"];
55
+ newFrontmatter: Frontmatter;
56
+ commitMessage: string;
57
+ baseVersion: string | undefined;
58
+ access?: AccessContext;
59
+ runId?: string;
60
+ }): Promise<Result<WriteResult, Error>>;
33
61
  export declare function vaultWrite(vaultRoot: string, args: Record<string, unknown>, access?: AccessContext): Promise<Result<WriteResult, Error>>;
34
62
  export declare function vaultAppend(vaultRoot: string, args: Record<string, unknown>, access?: AccessContext): Promise<Result<WriteResult, Error>>;
35
63
  export declare function vaultPromote(vaultRoot: string, args: Record<string, unknown>, access?: AccessContext): Promise<Result<WriteResult, Error>>;
@@ -1 +1 @@
1
- {"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,aAAa,EAAuC,MAAM,mBAAmB,CAAC;AAM5F,OAAO,EACL,KAAK,oBAAoB,EAKzB,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAWtC,OAAO,EAKL,KAAK,WAAW,EAGhB,KAAK,MAAM,EAKX,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AASjC,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAgJhD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,UAAU,EAAE,eAAe,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAMD,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,eAAe,EAAO,EAClC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAChC,MAAM,CAsDR;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EACF,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,WAAW,GACX,OAAO,GACP,gBAAgB,GAChB,UAAU,GACV,QAAQ,CAAC;IAGb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IAKtB,IAAI,CAAC,EAAE,MAAM,CAAC;IAId,MAAM,CAAC,EAAE,OAAO,CAAC;IAMjB,cAAc,CAAC,EAAE,MAAM,CAAC;IAMxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAO3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IAMvB,UAAU,CAAC,EAAE;QACX,UAAU,EAAE,oBAAoB,EAAE,CAAC;QACnC,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,gBAAgB,CAAC;KACrC,CAAC;CACH;AA4bD,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAsTrC;AAQD,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAkHrC;AASD,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CA4DrC;AA+DD,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAoErC;AAUD,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAiErC;AAaD,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAuErC;AAUD,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CA8FrC;AA2BD,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CA+TrC;AAsRD,eAAO,MAAM,UAAU,EAAE,cAAc,EAuXtC,CAAC"}
1
+ {"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"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"}
@@ -10,9 +10,10 @@
10
10
  import { mkdir, writeFile } from "node:fs/promises";
11
11
  import { dirname, relative, resolve, sep } from "node:path";
12
12
  import matter from "gray-matter";
13
- import { acquireLock, openLockDb, releaseLock } from "../access/locks.js";
13
+ import { acquireLock, mintLeaseHolder, openLockDb, releaseLock } from "../access/locks.js";
14
14
  import { canPromote, canWrite, isProposeOnly } from "../access/rbac.js";
15
15
  import { mintConsumesEdges } from "../curation/consumes.js";
16
+ import { foreignPositionViolation } from "../curation/positions.js";
16
17
  import { frontmatterDiff, recordProvenance } from "../curation/provenance.js";
17
18
  import { recordShadowAction } from "../curation/shadow.js";
18
19
  import { stageActionWithConflictCheck } from "../curation/staged-actions.js";
@@ -35,6 +36,7 @@ import { normalizeIsoDate } from "../utils/dates.js";
35
36
  import { commit } from "../utils/git.js";
36
37
  import { sha256Hex } from "../utils/hash.js";
37
38
  import { readRunId } from "../utils/run-id.js";
39
+ import { mintDescribesPins } from "./pin-mint.js";
38
40
  import { openIndexForAccessOrNull } from "./search.js";
39
41
  // ---------------------------------------------------------------------------
40
42
  // shared helpers
@@ -103,7 +105,7 @@ function boundaryHint(successorPath, boundary) {
103
105
  // clears the index and re-inserts every document, so a write that lands in
104
106
  // between can be wiped or land against a half-built index. Failing fast keeps
105
107
  // hooks, locks, and git commits from running for a write we can't index yet.
106
- function requireIndexReady() {
108
+ export function requireIndexReady() {
107
109
  const status = getIndexStatus();
108
110
  if (status.status === "indexing") {
109
111
  return err(new Error(indexingBusyMessage(status)));
@@ -131,7 +133,7 @@ function collectionOf(relPath, fm) {
131
133
  // runs before we touch the target, preserving "deny before revealing anything".
132
134
  // A path that escapes the root yields a `..`-leading segment, which no role can
133
135
  // write; `resolveVaultPath` rejects it properly downstream.
134
- function targetCollection(vaultRoot, relPath) {
136
+ export function targetCollection(vaultRoot, relPath) {
135
137
  const rel = relative(resolve(vaultRoot), resolve(vaultRoot, relPath));
136
138
  return rel.split(sep)[0] ?? "";
137
139
  }
@@ -194,6 +196,14 @@ export function serializeDocument(fm, body, extensions = [], raw = {}) {
194
196
  describes: fm.describes,
195
197
  questions_answered: fm.questions_answered,
196
198
  questions_raised: fm.questions_raised,
199
+ // Positions (Slice 1): emitted ONLY when non-null — a deliberate exception
200
+ // to the always-emit built-in convention so the thousands of legacy docs
201
+ // stay byte-stable. A null typed value with surviving raw content (e.g. a
202
+ // malformed hand-written positions block) still round-trips verbatim via
203
+ // the raw-preservation loop below (#113).
204
+ ...(fm.positions != null ? { positions: fm.positions } : {}),
205
+ ...(fm.org_position != null ? { org_position: fm.org_position } : {}),
206
+ ...(fm.contested != null ? { contested: fm.contested } : {}),
197
207
  };
198
208
  const handled = new Set(Object.keys(ordered));
199
209
  for (const ext of extensions) {
@@ -283,8 +293,12 @@ async function performWrite(params) {
283
293
  if (!lockDbResult.ok)
284
294
  return lockDbResult;
285
295
  const lockDb = lockDbResult.value;
296
+ // Minted ONCE per mutation attempt (S3-a) and reused at every acquire/
297
+ // release below — never re-mint at the release site, or the release
298
+ // silently no-ops and the path wedges for the 60s TTL.
299
+ const holder = mintLeaseHolder(params.agent);
286
300
  try {
287
- const lock = acquireLock(lockDb, params.relPath, params.agent);
301
+ const lock = acquireLock(lockDb, params.relPath, holder);
288
302
  if (!lock.ok)
289
303
  return lock;
290
304
  try {
@@ -357,7 +371,7 @@ async function performWrite(params) {
357
371
  });
358
372
  }
359
373
  finally {
360
- releaseLock(lockDb, params.relPath, params.agent);
374
+ releaseLock(lockDb, params.relPath, holder);
361
375
  }
362
376
  }
363
377
  catch (e) {
@@ -404,13 +418,13 @@ function denyIfProposeOnly(access, tool) {
404
418
  // The uniform RBAC write gate. One helper because the denial string is part
405
419
  // of the tool contract — every write tool emits the identical message shape,
406
420
  // and it must never leak more than the collection name.
407
- function requireWriteAccess(access, collection) {
421
+ export function requireWriteAccess(access, collection) {
408
422
  if (access && !canWrite(access.role, collection)) {
409
423
  return err(new Error(`access denied: role '${access.roleName}' cannot write to ` + `collection '${collection}'`));
410
424
  }
411
425
  return ok(undefined);
412
426
  }
413
- async function loadTargetDocument(vaultRoot, rawPath, tool) {
427
+ export async function loadTargetDocument(vaultRoot, rawPath, tool) {
414
428
  const resolved = resolveVaultPath(vaultRoot, rawPath);
415
429
  if (!resolved.ok)
416
430
  return resolved;
@@ -437,7 +451,7 @@ async function loadTargetDocument(vaultRoot, rawPath, tool) {
437
451
  // The shared performWrite tail for frontmatter-only mutations: body preserved
438
452
  // verbatim (bodyChanged false), file text re-serialized from the new
439
453
  // frontmatter over the existing content.
440
- function performFrontmatterWrite(opts) {
454
+ export function performFrontmatterWrite(opts) {
441
455
  const { target } = opts;
442
456
  return performWrite({
443
457
  vaultRoot: opts.vaultRoot,
@@ -457,6 +471,7 @@ function performFrontmatterWrite(opts) {
457
471
  shadowMode: target.config.shadowMode,
458
472
  principal: opts.access?.user,
459
473
  bodyChanged: false,
474
+ ...(opts.runId !== undefined ? { runId: opts.runId } : {}),
460
475
  });
461
476
  }
462
477
  // ---------------------------------------------------------------------------
@@ -619,10 +634,12 @@ export async function vaultWrite(vaultRoot, args, access) {
619
634
  if (!proposeConfig.ok)
620
635
  return proposeConfig;
621
636
  let previewRaw = { ...rawFrontmatter };
637
+ let existingPositions = null;
622
638
  const onDisk = await readFile(resolved.value.absPath);
623
639
  if (onDisk.ok) {
624
640
  const parsedExisting = parseDocument(onDisk.value);
625
641
  if (parsedExisting.ok) {
642
+ existingPositions = parsedExisting.value.frontmatter.positions;
626
643
  const merged = { ...parsedExisting.value.raw };
627
644
  for (const [key, value] of Object.entries(rawFrontmatter)) {
628
645
  if (value === null)
@@ -640,6 +657,17 @@ export async function vaultWrite(vaultRoot, args, access) {
640
657
  previewRaw.updated_by = agent.value;
641
658
  }
642
659
  const preview = validateFrontmatter(previewRaw, proposeConfig.value.schemaExtensions);
660
+ // R-12/LD-13: die at stage time — cheaper than waiting for a poisoned
661
+ // proposal to fail at ratify dispatch (which re-checks authoritatively
662
+ // through the direct path above).
663
+ if (existingPositions != null) {
664
+ const previewViolation = foreignPositionViolation(existingPositions, preview.frontmatter.positions, access.user);
665
+ if (previewViolation) {
666
+ return err(new Error(`vault_write (stage preview): ${previewViolation} — another principal's ` +
667
+ `position entries can only be superseded by their own new position ` +
668
+ `(vault_assert) or edited by their holder`));
669
+ }
670
+ }
643
671
  const staged = await stageActionWithConflictCheck(vaultRoot, {
644
672
  actionType: "write",
645
673
  targetPath: resolved.value.relPath,
@@ -772,6 +800,37 @@ export async function vaultWrite(vaultRoot, args, access) {
772
800
  if (rawFrontmatter.updated_by === undefined || rawFrontmatter.updated_by === null) {
773
801
  rawFrontmatter.updated_by = agent.value;
774
802
  }
803
+ // JIT anchor-pin minting (U2, R1/R2/R3): enrich shaless `describes` entries
804
+ // with working-tree blob shas BEFORE validateFrontmatter/serialization so
805
+ // both see the pinned values and the enriched array lands in the .md (R3).
806
+ // Best-effort: a throw from mintDescribesPins must never fail the write (R2).
807
+ // Propose-only path: NO minting here — the raw payload is staged verbatim;
808
+ // minting happens when vault_ratify dispatches back through vaultWrite with
809
+ // the ratifier's access (the isProposeOnly branch above returns early).
810
+ let pinMintOutcome;
811
+ if (Array.isArray(rawFrontmatter.describes) && rawFrontmatter.describes.length > 0) {
812
+ // Type-safety: describes is schema-typed string[], but the raw payload is
813
+ // unknown[]. Non-string elements would be rejected by validateFrontmatter
814
+ // anyway; skip minting entirely if any entry is not a string so that the
815
+ // minted result array stays correctly parallel to the input (no reordering
816
+ // or dropping needed).
817
+ const allStrings = rawFrontmatter.describes.every((e) => typeof e === "string");
818
+ if (allStrings) {
819
+ try {
820
+ const mintResult = await mintDescribesPins(vaultRoot, rawFrontmatter.describes);
821
+ // Write the enriched array back so validation + serialization see it (R3).
822
+ rawFrontmatter.describes = mintResult.entries;
823
+ // Surface the outcome only when at least one entry was mintable
824
+ // (null-when-silent, matching supersede_hint/domain_warnings precedent).
825
+ if (mintResult.minted.length > 0 || mintResult.unresolved.length > 0) {
826
+ pinMintOutcome = { minted: mintResult.minted, unresolved: mintResult.unresolved };
827
+ }
828
+ }
829
+ catch {
830
+ // Best-effort: mint failure is silent; write proceeds with entries as-is.
831
+ }
832
+ }
833
+ }
775
834
  const { frontmatter, report } = validateFrontmatter(rawFrontmatter, extensions);
776
835
  // Pre-write hooks run after built-in schema validation has filled
777
836
  // defaults. Their issues merge into the report and are treated the same
@@ -797,6 +856,27 @@ export async function vaultWrite(vaultRoot, args, access) {
797
856
  const summary = mergedReport.issues.map((i) => `${i.field}: ${i.message}`).join("; ");
798
857
  return err(new Error(`invalid frontmatter: ${summary}`));
799
858
  }
859
+ // R-12/LD-13: no principal rewrites another's positions through the
860
+ // generic write path. Checked after validation so both sides are typed
861
+ // Position[] (raw YAML dates already normalized). Operator servers
862
+ // (no access) bypass, matching the tier/ratify gate conventions.
863
+ if (access && isUpdate && oldFrontmatter && oldFrontmatter.positions != null) {
864
+ const violation = foreignPositionViolation(oldFrontmatter.positions, frontmatter.positions, access.user);
865
+ if (violation) {
866
+ await recordProvenance(vaultRoot, {
867
+ tool: "vault_write",
868
+ file: resolved.value.relPath,
869
+ agent: agent.value,
870
+ principal: access.user,
871
+ ...(runId.value !== undefined ? { run_id: runId.value } : {}),
872
+ action: "rejected_foreign_position",
873
+ reason: violation,
874
+ });
875
+ return err(new Error(`vault_write: ${violation} — another principal's position entries can ` +
876
+ `only be superseded by their own new position (vault_assert) or ` +
877
+ `edited by their holder`));
878
+ }
879
+ }
800
880
  const stamped = {
801
881
  ...frontmatter,
802
882
  created: isUpdate ? oldFrontmatter.created : frontmatter.created,
@@ -833,7 +913,9 @@ export async function vaultWrite(vaultRoot, args, access) {
833
913
  // Attached here (not in performWrite) so vault_supersede and the other
834
914
  // lifecycle tools never nudge about themselves. A shadow-mode result is
835
915
  // excluded: nothing landed and nothing was replaced, so the hints' text
836
- // would be false. #4's domain warnings ride the same channel.
916
+ // would be false. #4's domain warnings ride the same channel. pin_mint is
917
+ // also suppressed under shadow: nothing landed on disk, so the minted sha
918
+ // would point at a write that never happened (same logic as supersede_hint).
837
919
  if (!written.ok || written.value.shadow)
838
920
  return written;
839
921
  const warnings = generativeDomainRefs(vaultRoot, {
@@ -842,12 +924,13 @@ export async function vaultWrite(vaultRoot, args, access) {
842
924
  body,
843
925
  relPath: resolved.value.relPath,
844
926
  }, access);
845
- if (!isUpdate && warnings === null)
927
+ if (!isUpdate && warnings === null && pinMintOutcome === undefined)
846
928
  return written;
847
929
  return ok({
848
930
  ...written.value,
849
931
  ...(isUpdate ? { supersede_hint: SUPERSEDE_HINT } : {}),
850
932
  ...(warnings ? { domain_warnings: warnings } : {}),
933
+ ...(pinMintOutcome !== undefined ? { pin_mint: pinMintOutcome } : {}),
851
934
  });
852
935
  }
853
936
  // ---------------------------------------------------------------------------
@@ -1660,9 +1743,14 @@ export async function vaultMerge(vaultRoot, args, access) {
1660
1743
  const lockDb = lockDbResult.value;
1661
1744
  const lockPaths = [...new Set(writes.map((w) => w.relPath))].sort();
1662
1745
  const held = [];
1746
+ // ONE minted holder for every path in this merge (S3-a): the same-holder
1747
+ // re-acquire rule means a merge whose deduped, sorted path set is
1748
+ // acquired under one holder cannot self-conflict. Never re-mint at the
1749
+ // release loop below.
1750
+ const holder = mintLeaseHolder(agent.value);
1663
1751
  try {
1664
1752
  for (const relPath of lockPaths) {
1665
- const lock = acquireLock(lockDb, relPath, agent.value);
1753
+ const lock = acquireLock(lockDb, relPath, holder);
1666
1754
  if (!lock.ok)
1667
1755
  return lock;
1668
1756
  held.push(relPath);
@@ -1726,7 +1814,7 @@ export async function vaultMerge(vaultRoot, args, access) {
1726
1814
  }
1727
1815
  finally {
1728
1816
  for (const relPath of held)
1729
- releaseLock(lockDb, relPath, agent.value);
1817
+ releaseLock(lockDb, relPath, holder);
1730
1818
  lockDb.close();
1731
1819
  }
1732
1820
  }
@@ -1867,6 +1955,16 @@ const frontmatterProperty = {
1867
1955
  description: "Open questions this document raises (mirrors ## Questions Raised). " +
1868
1956
  "Surfaced by vault_lint's `unanswered-questions` check.",
1869
1957
  },
1958
+ describes: {
1959
+ type: "array",
1960
+ items: { type: "string" },
1961
+ description: "Code bindings this document describes, in the form " +
1962
+ "`[<repo>:]<path>[::symbol][#L<start>[-<end>]][@<sha12>]`. " +
1963
+ "Shaless entries with a `#L` range are enriched with a working-tree " +
1964
+ "blob sha at write time (JIT pin minting, U2); the minting outcome is " +
1965
+ "reported in `pin_mint` on the result. The schema stays `string[]` — " +
1966
+ "no structural change; enrichment happens pre-validation.",
1967
+ },
1870
1968
  },
1871
1969
  required: ["title", "domain", "collection", "status", "confidence", "created", "provenance"],
1872
1970
  additionalProperties: true,
@@ -1914,6 +2012,44 @@ const domainWarningsProperty = {
1914
2012
  "references generative-domain documents the caller can read. Absent when " +
1915
2013
  "there is nothing to warn about. The write has already landed.",
1916
2014
  };
2015
+ const pinMintProperty = {
2016
+ type: "object",
2017
+ description: "JIT anchor-pin minting outcome (U2). Present only when at least one " +
2018
+ "`describes` entry had a shaless `#L<start>-<end>` tail that was a " +
2019
+ "candidate for minting. Absent (null-when-silent) when no entries were " +
2020
+ "mintable. The write always lands regardless of mint errors.",
2021
+ properties: {
2022
+ minted: {
2023
+ type: "array",
2024
+ items: {
2025
+ type: "object",
2026
+ properties: {
2027
+ entry: { type: "string", description: "Original (input) entry string" },
2028
+ pinned: { type: "string", description: "Rewritten entry with @sha12 pin" },
2029
+ committed: {
2030
+ type: "boolean",
2031
+ description: "True when the blob is reachable in the odb (was committed)",
2032
+ },
2033
+ },
2034
+ required: ["entry", "pinned", "committed"],
2035
+ },
2036
+ description: "Entries successfully enriched with a blob-sha pin",
2037
+ },
2038
+ unresolved: {
2039
+ type: "array",
2040
+ items: {
2041
+ type: "object",
2042
+ properties: {
2043
+ entry: { type: "string", description: "Original (input) entry string" },
2044
+ reason: { type: "string", description: "Why the entry could not be minted" },
2045
+ },
2046
+ required: ["entry", "reason"],
2047
+ },
2048
+ description: "Entries that could not be minted, with reasons",
2049
+ },
2050
+ },
2051
+ required: ["minted", "unresolved"],
2052
+ };
1917
2053
  // The shared WriteResult shape. `actions` and `statuses` are the closed
1918
2054
  // vocabularies the specific tool can emit; `properties` adds the tool's own
1919
2055
  // optional fields.
@@ -2026,6 +2162,7 @@ export const writeTools = [
2026
2162
  "and its lineage instead. The write has already landed.",
2027
2163
  },
2028
2164
  domain_warnings: domainWarningsProperty,
2165
+ pin_mint: pinMintProperty,
2029
2166
  staged_id: {
2030
2167
  type: "string",
2031
2168
  description: "Staged-action id of the recorded proposal. Present only when " + "action is 'staged'.",