@mfdaves/okf-mcp 0.9.1 → 0.12.0-rc.1

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 (97) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +172 -17
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/policies/authoring-safety.md +11 -1
  5. package/package.json +17 -5
  6. package/server.json +2 -2
  7. package/src/assets.js +165 -73
  8. package/src/authoring/candidates.js +391 -0
  9. package/src/authoring/git-preflight.js +225 -0
  10. package/src/authoring/git-publish.js +776 -0
  11. package/src/authoring/live.js +789 -0
  12. package/src/authoring/paths.js +112 -0
  13. package/src/authoring/policy-hook.js +221 -0
  14. package/src/authoring/proposal-policy.js +137 -0
  15. package/src/authoring/receipts.js +329 -0
  16. package/src/authoring/render.js +38 -0
  17. package/src/authoring/shared.js +75 -0
  18. package/src/authoring/staging.js +216 -0
  19. package/src/authoring.js +386 -287
  20. package/src/cache/files.js +147 -0
  21. package/src/cache/lock.js +201 -0
  22. package/src/cache/paths.js +197 -0
  23. package/src/cache/store.js +703 -0
  24. package/src/catalog-text.js +19 -0
  25. package/src/cli.js +184 -151
  26. package/src/computation.js +99 -61
  27. package/src/context/assemble.js +567 -0
  28. package/src/context/cli-options.js +88 -0
  29. package/src/context/score.js +234 -0
  30. package/src/context/sections.js +274 -0
  31. package/src/embed/interface.js +160 -0
  32. package/src/embed/openai.js +715 -0
  33. package/src/embed/prepare.js +182 -0
  34. package/src/embed/units.js +96 -0
  35. package/src/git-source.js +112 -52
  36. package/src/graph.js +95 -37
  37. package/src/http-server.js +36 -17
  38. package/src/index.js +15 -0
  39. package/src/indexer/assemble.js +566 -0
  40. package/src/indexer/build.js +290 -0
  41. package/src/indexer/cache.js +81 -0
  42. package/src/indexer/edges.js +430 -0
  43. package/src/indexer/index.js +44 -0
  44. package/src/indexer/paths.js +178 -0
  45. package/src/indexer/resolve.js +282 -0
  46. package/src/indexer/update.js +720 -0
  47. package/src/indexer.js +3 -1068
  48. package/src/live-authoring.js +4 -2329
  49. package/src/markdown.js +21 -16
  50. package/src/mcp/registry.js +328 -0
  51. package/src/mcp/resources.js +45 -0
  52. package/src/mcp/server.js +472 -0
  53. package/src/mcp/tools/catalog.js +244 -0
  54. package/src/mcp/tools/computation.js +83 -0
  55. package/src/mcp/tools/context.js +133 -0
  56. package/src/mcp/tools/graph.js +167 -0
  57. package/src/mcp/tools/live-authoring.js +316 -0
  58. package/src/mcp/tools/migration.js +86 -0
  59. package/src/mcp/tools/producers.js +79 -0
  60. package/src/mcp/tools/proposals.js +213 -0
  61. package/src/mcp/tools/provenance.js +87 -0
  62. package/src/mcp/tools/remote.js +79 -0
  63. package/src/mcp/tools/search.js +242 -0
  64. package/src/mcp-server.js +3 -1611
  65. package/src/migration.js +431 -253
  66. package/src/parser.js +245 -130
  67. package/src/plugins.js +71 -48
  68. package/src/policy/write-policy.js +713 -0
  69. package/src/producer-publisher.js +195 -77
  70. package/src/producers.js +265 -101
  71. package/src/project.js +277 -93
  72. package/src/remote.js +96 -61
  73. package/src/search/cli-options.js +107 -0
  74. package/src/search/confidence.js +61 -0
  75. package/src/search/dense.js +304 -0
  76. package/src/search/embedding-cli.js +57 -0
  77. package/src/search/embedding-config.js +217 -0
  78. package/src/search/fusion.js +249 -0
  79. package/src/search/hybrid.js +526 -0
  80. package/src/search/languages.js +200 -0
  81. package/src/search/lexical.js +695 -0
  82. package/src/search/query.js +620 -0
  83. package/src/search/stem/among.js +43 -0
  84. package/src/search/stem/base-stemmer.js +311 -0
  85. package/src/search/stem/en-regions.js +456 -0
  86. package/src/search/stem/en-suffixes.js +664 -0
  87. package/src/search/stem/en-tables.js +176 -0
  88. package/src/search/stem/en.js +238 -0
  89. package/src/search/stem/it-regions.js +459 -0
  90. package/src/search/stem/it-suffixes.js +471 -0
  91. package/src/search/stem/it-tables.js +257 -0
  92. package/src/search/stem/it.js +155 -0
  93. package/src/search-index.js +2 -81
  94. package/src/search.js +2 -252
  95. package/src/store.js +134 -81
  96. package/src/v02.js +301 -105
  97. package/src/validation.js +24 -20
@@ -0,0 +1,789 @@
1
+ "use strict";
2
+
3
+ const fs = require("node:fs");
4
+ const path = require("node:path");
5
+ const { spawnSync: nodeSpawnSync } = require("node:child_process");
6
+ const { isDeepStrictEqual } = require("node:util");
7
+
8
+ const {
9
+ deriveConceptPathSuggestion,
10
+ isConfiguredGeneratorOutput,
11
+ normalizeConceptPath,
12
+ renderConceptMarkdown,
13
+ } = require("../authoring");
14
+ const {
15
+ IndexCache,
16
+ attachProject,
17
+ buildIndex,
18
+ bundleAllowsPath,
19
+ conceptMatchSummary,
20
+ refreshIndex,
21
+ resolveConcept,
22
+ updateIndex,
23
+ validateIndex,
24
+ } = require("../indexer");
25
+ const {
26
+ MANAGED_METADATA_KEYS,
27
+ actorValue,
28
+ applyRelationPatch,
29
+ applySourcePatch,
30
+ applyTagPatch,
31
+ conceptConflictDetails,
32
+ conceptIsManaged,
33
+ nonEmptyString,
34
+ normalizeBody,
35
+ normalizeRelation,
36
+ normalizeSource,
37
+ semanticConceptKey,
38
+ staleUpdateDetails,
39
+ uniqueStrings,
40
+ validateMetadata,
41
+ validateRemovalKeys,
42
+ } = require("./candidates");
43
+ const { GitPublisher } = require("./git-publish");
44
+ const { enforceWritePolicy, resolveWritePolicy, withPolicyViolations } = require("./policy-hook");
45
+ const {
46
+ candidateSummaries,
47
+ durabilityReceipt,
48
+ policyReceipt,
49
+ policyValidation,
50
+ preconditionsReceipt,
51
+ rollbackReceipt,
52
+ snapshotReceipt,
53
+ targetReceipt,
54
+ validationReceipt,
55
+ } = require("./receipts");
56
+ const {
57
+ AuthoringOperationalError,
58
+ AuthoringPolicyError,
59
+ byteLength,
60
+ hasOwn,
61
+ isPlainObject,
62
+ revisionFor,
63
+ } = require("./shared");
64
+ const { assertRevisions, rollback, stageCandidates } = require("./staging");
65
+
66
+ const MAX_CHANGES = 100;
67
+ const MAX_COMMIT_MESSAGE_BYTES = 1024;
68
+
69
+ // The candidate as an index upsert: its rendered Markdown before it is
70
+ // written, or a read-back of the target path once it is.
71
+ function candidateUpsert(candidate, persisted) {
72
+ const upsert = { bundleId: candidate.bundle, relativePath: candidate.path };
73
+ return persisted ? upsert : Object.assign(upsert, { text: candidate.markdown });
74
+ }
75
+
76
+ class LiveAuthoringService {
77
+ constructor(store, options) {
78
+ const config = options || {};
79
+ this.store = store;
80
+ this.actor = actorValue(config.actor);
81
+ this.gitCommit = Boolean(config.gitCommit);
82
+ this.spawnSync = config.spawnSync || nodeSpawnSync;
83
+ this.now = config.now || (() => new Date());
84
+ this.git = new GitPublisher({ gitCommit: this.gitCommit, spawnSync: this.spawnSync });
85
+ this.writePolicy = resolveWritePolicy(config, store);
86
+ // One index kept between batches and refreshed before each (W-6); a host
87
+ // hands one over through adoptIndex and takes it back via takePublication.
88
+ this.indexCache = new IndexCache({ now: this.now });
89
+ this.publication = null;
90
+ }
91
+
92
+ adoptIndex(index, additionalBundles) {
93
+ this.indexCache.adopt(index, additionalBundles);
94
+ }
95
+
96
+ takePublication() {
97
+ const publication = this.publication;
98
+ this.publication = null;
99
+ return publication;
100
+ }
101
+
102
+ // Under the writer lock like the rest of a batch; the once-a-day rebuild
103
+ // for a new calendar day (updateIndex) lands here: one build's latency.
104
+ currentIndex(additionalBundles) {
105
+ return this.indexCache.current(additionalBundles, () => this.buildIndex(additionalBundles));
106
+ }
107
+
108
+ // Called when the files on disk are no longer known to match any index the
109
+ // service holds (an incomplete rollback, a diverged worktree).
110
+ forgetIndex() {
111
+ this.indexCache.forget();
112
+ }
113
+
114
+ getBundle(id) {
115
+ const bundles = this.store.getBundles();
116
+ const bundle = id
117
+ ? bundles.find((entry) => entry.id === id)
118
+ : bundles.length === 1
119
+ ? bundles[0]
120
+ : null;
121
+ if (!bundle) {
122
+ throw new Error(
123
+ id
124
+ ? `Unknown writable OKF bundle: ${id}`
125
+ : "A bundle id is required unless exactly one writable OKF root is configured.",
126
+ );
127
+ }
128
+ return bundle;
129
+ }
130
+
131
+ buildIndex(additionalBundles, documentOverrides) {
132
+ const index = buildIndex(this.store.getBundles().concat(additionalBundles || []), {
133
+ relationTypes: this.store.getRelationTypes(),
134
+ strictLinks: this.store.strictLinks,
135
+ allowCustomRelationTypes: this.store.allowCustomRelationTypes,
136
+ documentOverrides,
137
+ });
138
+ return this.store.project ? attachProject(index, this.store.project) : index;
139
+ }
140
+
141
+ assertWritableTarget(bundle, conceptPath, existing) {
142
+ const target = this.store.resolveConceptFile(bundle.id, conceptPath);
143
+ if (isConfiguredGeneratorOutput(this.store.project, target.absolutePath)) {
144
+ throw new Error(
145
+ `Concept is inside a configured generator output and must be changed through its generator: ${conceptPath}`,
146
+ );
147
+ }
148
+ if (existing && conceptIsManaged(existing, this.store.project)) {
149
+ throw new Error(`Generated concept must be changed through its generator: ${existing.uri}`);
150
+ }
151
+ return target;
152
+ }
153
+
154
+ createCandidate(change, bundle, currentIndex, generated) {
155
+ const type = nonEmptyString(change.type, "changes[].type");
156
+ if (type === "Attested Computation") {
157
+ throw new Error("Live concept authoring cannot create Attested Computation contracts.");
158
+ }
159
+ const title = nonEmptyString(change.title, "changes[].title");
160
+ const conceptPath = normalizeConceptPath(
161
+ change.path || deriveConceptPathSuggestion(currentIndex, bundle, { type, title }).path,
162
+ );
163
+ if (!bundleAllowsPath(bundle, conceptPath)) {
164
+ throw new Error(`Concept path is excluded by the bundle policy: ${conceptPath}`);
165
+ }
166
+ const target = this.assertWritableTarget(bundle, conceptPath, null);
167
+ if (fs.existsSync(target.absolutePath)) {
168
+ throw new Error(`Concept file already exists: ${conceptPath}`);
169
+ }
170
+ const metadata = validateMetadata(change.metadata, "changes[].metadata");
171
+ const frontmatter = Object.assign({ type, title }, metadata);
172
+ if (hasOwn(change, "description")) {
173
+ frontmatter.description = String(change.description);
174
+ }
175
+ const tags = uniqueStrings(change.tags, "changes[].tags");
176
+ if (change.sources !== undefined && !Array.isArray(change.sources)) {
177
+ throw new Error("changes[].sources must be an array.");
178
+ }
179
+ if (change.relations !== undefined && !Array.isArray(change.relations)) {
180
+ throw new Error("changes[].relations must be an array.");
181
+ }
182
+ const sources = (change.sources || []).map((source, index) =>
183
+ normalizeSource(source, `changes[].sources[${index}]`),
184
+ );
185
+ const relations = (change.relations || []).map((relation, index) =>
186
+ normalizeRelation(relation, `changes[].relations[${index}]`),
187
+ );
188
+ if (tags.length) frontmatter.tags = tags;
189
+ if (sources.length)
190
+ frontmatter.sources = applySourcePatch([], { add: sources }, "changes[].sources");
191
+ if (relations.length)
192
+ frontmatter.relations = applyRelationPatch([], { add: relations }, "changes[].relations");
193
+ frontmatter.generated = generated;
194
+ const body = hasOwn(change, "body") ? String(change.body || "") : `# ${title}`;
195
+ const markdown = renderConceptMarkdown({ path: conceptPath, frontmatter, body });
196
+ return {
197
+ op: "create",
198
+ bundle: bundle.id,
199
+ path: conceptPath,
200
+ uri: `okf://${bundle.id}/${conceptPath.replace(/\.md$/i, "")}`,
201
+ title,
202
+ frontmatter,
203
+ body,
204
+ markdown,
205
+ target,
206
+ baseRevision: null,
207
+ publishedRevision: revisionFor(markdown),
208
+ originalFrontmatter: {},
209
+ originalBody: "",
210
+ };
211
+ }
212
+
213
+ updateCandidate(change, bundle, currentIndex, generated) {
214
+ const uri = nonEmptyString(change.uri, "changes[].uri");
215
+ const existing = resolveConcept(currentIndex, uri);
216
+ if (!existing?.valid || existing.reserved) {
217
+ const details = staleUpdateDetails(currentIndex, uri, bundle.id, this.store.project);
218
+ throw new AuthoringPolicyError(
219
+ `Unknown valid OKF concept: ${uri}`,
220
+ details.recovery.status === "ambiguous" ? "concept_locator_ambiguous" : "concept_not_found",
221
+ details,
222
+ );
223
+ }
224
+ if (existing.bundle !== bundle.id) {
225
+ throw new Error(`All changes must target writable bundle ${bundle.id}: ${uri}`);
226
+ }
227
+ if (existing.type === "Attested Computation") {
228
+ throw new Error(
229
+ "Live concept authoring cannot modify Attested Computation contracts or code.",
230
+ );
231
+ }
232
+ const target = this.assertWritableTarget(bundle, existing.path, existing);
233
+ const originalText = fs.readFileSync(target.absolutePath, "utf8");
234
+ const originalMode = fs.statSync(target.absolutePath).mode;
235
+ const indexedRevision = revisionFor(existing.text);
236
+ const diskRevision = revisionFor(originalText);
237
+ if (indexedRevision !== diskRevision) {
238
+ // planChanges re-reads the document and plans again once; a second
239
+ // mismatch is a conflict the caller sees with the revision now on disk.
240
+ throw new AuthoringPolicyError(
241
+ `Concept changed after it was indexed; retry the update: ${existing.uri}`,
242
+ "concept_changed",
243
+ {
244
+ uri: existing.uri,
245
+ bundleId: existing.bundle,
246
+ relativePath: existing.path,
247
+ indexedRevision,
248
+ revision: diskRevision,
249
+ },
250
+ );
251
+ }
252
+ const frontmatter = Object.assign({}, existing.frontmatter);
253
+ Object.assign(frontmatter, validateMetadata(change.metadata, "changes[].metadata"));
254
+ validateRemovalKeys(change.removeMetadataKeys, "changes[].removeMetadataKeys").forEach(
255
+ (key) => {
256
+ delete frontmatter[key];
257
+ },
258
+ );
259
+ if (hasOwn(change, "title")) {
260
+ frontmatter.title = nonEmptyString(change.title, "changes[].title");
261
+ }
262
+ if (hasOwn(change, "description")) {
263
+ frontmatter.description = String(change.description);
264
+ }
265
+ if (hasOwn(change, "tags")) {
266
+ frontmatter.tags = applyTagPatch(frontmatter.tags, change.tags, "changes[].tags");
267
+ }
268
+ if (hasOwn(change, "sources")) {
269
+ frontmatter.sources = applySourcePatch(
270
+ frontmatter.sources,
271
+ change.sources,
272
+ "changes[].sources",
273
+ );
274
+ }
275
+ if (hasOwn(change, "relations")) {
276
+ frontmatter.relations = applyRelationPatch(
277
+ frontmatter.relations,
278
+ change.relations,
279
+ "changes[].relations",
280
+ );
281
+ }
282
+ const body = hasOwn(change, "body") ? String(change.body || "") : existing.body;
283
+ if (
284
+ isDeepStrictEqual(frontmatter, existing.frontmatter) &&
285
+ normalizeBody(body) === normalizeBody(existing.body)
286
+ ) {
287
+ throw new Error(`Update has no effective changes: ${existing.uri}`);
288
+ }
289
+ frontmatter.generated = Object.assign(
290
+ {},
291
+ isPlainObject(existing.frontmatter.generated) ? existing.frontmatter.generated : {},
292
+ generated,
293
+ );
294
+ const markdown = renderConceptMarkdown({ path: existing.path, frontmatter, body });
295
+ return {
296
+ op: "update",
297
+ bundle: bundle.id,
298
+ path: existing.path,
299
+ uri: existing.uri,
300
+ title: frontmatter.title || existing.title,
301
+ frontmatter,
302
+ body,
303
+ markdown,
304
+ target,
305
+ baseRevision: diskRevision,
306
+ publishedRevision: revisionFor(markdown),
307
+ originalText,
308
+ originalMode,
309
+ originalFrontmatter: Object.assign({}, existing.frontmatter),
310
+ originalBody: existing.body,
311
+ };
312
+ }
313
+
314
+ validationResult(index, candidates) {
315
+ const validation = validateIndex(index);
316
+ const candidateDiagnostics = [];
317
+ candidates.forEach((candidate) => {
318
+ const document = index.byPathUri.get(`okf://${candidate.bundle}/${candidate.path}`);
319
+ if (!document || document.reserved || !document.valid) {
320
+ candidateDiagnostics.push({
321
+ code: "candidate_not_indexed",
322
+ severity: "error",
323
+ layer: "project",
324
+ bundle: candidate.bundle,
325
+ path: candidate.path,
326
+ message: "Candidate did not become a valid concept in the future graph.",
327
+ });
328
+ return;
329
+ }
330
+ (document.warnings || [])
331
+ .filter((entry) => entry.layer === "v0.2")
332
+ .forEach((entry) => {
333
+ candidateDiagnostics.push(
334
+ Object.assign({}, entry, {
335
+ severity: "error",
336
+ bundle: candidate.bundle,
337
+ path: candidate.path,
338
+ }),
339
+ );
340
+ });
341
+ });
342
+ const diagnostics = validation.diagnostics.concat(candidateDiagnostics);
343
+ return {
344
+ valid: validation.valid && candidateDiagnostics.length === 0,
345
+ conformant: validation.conformant,
346
+ validForProject: validation.validForProject && candidateDiagnostics.length === 0,
347
+ diagnostics,
348
+ errors: validation.errors,
349
+ warnings: validation.warnings,
350
+ };
351
+ }
352
+
353
+ defaultMessage(candidates) {
354
+ if (candidates.length === 1) {
355
+ return `docs(okf): ${candidates[0].op === "create" ? "add" : "update"} ${candidates[0].title}`;
356
+ }
357
+ return `docs(okf): apply ${candidates.length} concept changes`;
358
+ }
359
+
360
+ commitMessage(input, candidates) {
361
+ if (hasOwn(input, "message") && typeof input.message !== "string") {
362
+ throw new AuthoringPolicyError("Git commit message must be a string.");
363
+ }
364
+ const supplied = hasOwn(input, "message") ? input.message.trim() : "";
365
+ const message = supplied || this.defaultMessage(candidates);
366
+ if (message.includes("\0")) {
367
+ throw new AuthoringPolicyError("Git commit message cannot contain NUL characters.");
368
+ }
369
+ if (byteLength(message) > MAX_COMMIT_MESSAGE_BYTES) {
370
+ throw new AuthoringPolicyError(
371
+ `Git commit message must not exceed ${MAX_COMMIT_MESSAGE_BYTES} UTF-8 bytes.`,
372
+ );
373
+ }
374
+ return message;
375
+ }
376
+
377
+ // The staged publication steps stay overridable methods: tests subclass the
378
+ // service and hook them to inject races between staging and publication.
379
+ stageCandidates(candidates) {
380
+ return stageCandidates(this.store, candidates);
381
+ }
382
+
383
+ assertRevisions(staged) {
384
+ return assertRevisions(staged);
385
+ }
386
+
387
+ rollback(applied, staged, createdDirectories) {
388
+ return rollback(applied, staged, createdDirectories);
389
+ }
390
+
391
+ generatedStamp() {
392
+ const timestampValue = this.now();
393
+ return {
394
+ by: this.actor,
395
+ at:
396
+ timestampValue instanceof Date
397
+ ? timestampValue.toISOString()
398
+ : new Date(timestampValue).toISOString(),
399
+ };
400
+ }
401
+
402
+ buildCandidates(changes, bundle, currentIndex, generated) {
403
+ return changes.map((change, index) => {
404
+ if (!isPlainObject(change)) {
405
+ throw new AuthoringPolicyError(`changes[${index}] must be an object.`);
406
+ }
407
+ try {
408
+ if (change.op === "create") {
409
+ return this.createCandidate(change, bundle, currentIndex, generated);
410
+ }
411
+ if (change.op === "update") {
412
+ return this.updateCandidate(change, bundle, currentIndex, generated);
413
+ }
414
+ throw new AuthoringPolicyError(`changes[${index}].op must be create or update.`);
415
+ } catch (error) {
416
+ if (error instanceof AuthoringPolicyError || error instanceof AuthoringOperationalError) {
417
+ throw error;
418
+ }
419
+ if (error?.code) throw error;
420
+ throw new AuthoringPolicyError(error?.message ? error.message : String(error));
421
+ }
422
+ });
423
+ }
424
+
425
+ planChanges(input, context) {
426
+ if (!isPlainObject(input)) {
427
+ throw new AuthoringPolicyError("okf_apply_changes requires an object argument.");
428
+ }
429
+ if (
430
+ !Array.isArray(input.changes) ||
431
+ input.changes.length < 1 ||
432
+ input.changes.length > MAX_CHANGES
433
+ ) {
434
+ throw new AuthoringPolicyError(
435
+ `changes must contain from 1 through ${MAX_CHANGES} operations.`,
436
+ );
437
+ }
438
+ let bundle;
439
+ try {
440
+ bundle = this.getBundle(input.bundle);
441
+ } catch (error) {
442
+ if (error?.code) throw error;
443
+ throw new AuthoringPolicyError(error?.message ? error.message : String(error));
444
+ }
445
+ const generated = this.generatedStamp();
446
+ const additionalBundles =
447
+ context && Array.isArray(context.additionalBundles) ? context.additionalBundles : [];
448
+ let currentIndex = this.currentIndex(additionalBundles);
449
+ let candidates = null;
450
+ for (let attempt = 0; candidates === null; attempt += 1) {
451
+ try {
452
+ candidates = this.buildCandidates(input.changes, bundle, currentIndex, generated);
453
+ } catch (error) {
454
+ if (error?.code !== "concept_changed" || attempt > 0) throw error;
455
+ // The index missed an edit the refresh cannot see (same size and
456
+ // mtime): take that document from disk and plan again, once.
457
+ const { bundleId, relativePath } = error.details;
458
+ currentIndex = this.indexCache.update(currentIndex, {
459
+ upserts: [{ bundleId, relativePath }],
460
+ });
461
+ }
462
+ }
463
+ const policy = enforceWritePolicy(this.writePolicy, {
464
+ actor: this.actor,
465
+ candidates,
466
+ index: currentIndex,
467
+ });
468
+ const targetPaths = new Set();
469
+ candidates.forEach((candidate) => {
470
+ const key = path.resolve(candidate.target.absolutePath);
471
+ if (targetPaths.has(key)) {
472
+ throw new AuthoringPolicyError(
473
+ `A batch cannot target the same concept more than once: ${candidate.path}`,
474
+ );
475
+ }
476
+ targetPaths.add(key);
477
+ });
478
+ const absoluteTargets = Array.from(targetPaths);
479
+ for (let left = 0; left < absoluteTargets.length; left += 1) {
480
+ for (let right = left + 1; right < absoluteTargets.length; right += 1) {
481
+ if (
482
+ absoluteTargets[left].startsWith(`${absoluteTargets[right]}${path.sep}`) ||
483
+ absoluteTargets[right].startsWith(`${absoluteTargets[left]}${path.sep}`)
484
+ ) {
485
+ throw new AuthoringPolicyError(
486
+ "A batch cannot place one concept path underneath another concept file path.",
487
+ );
488
+ }
489
+ }
490
+ }
491
+ const currentConcepts = currentIndex.concepts.filter((doc) => doc.bundle === bundle.id);
492
+ const replacedPaths = new Set(
493
+ candidates.filter((entry) => entry.op === "update").map((entry) => entry.path),
494
+ );
495
+ const finalConcepts = currentConcepts
496
+ .filter((doc) => !replacedPaths.has(doc.path))
497
+ .concat(candidates);
498
+ for (const candidate of candidates) {
499
+ const key = semanticConceptKey(candidate.frontmatter.type, candidate.title);
500
+ const before = currentConcepts.filter(
501
+ (doc) => semanticConceptKey(doc.type, doc.title) === key,
502
+ );
503
+ const after = finalConcepts.filter(
504
+ (doc) => semanticConceptKey(doc.type || doc.frontmatter.type, doc.title) === key,
505
+ );
506
+ if (after.length <= Math.max(1, before.length)) continue;
507
+ const existing = after.filter((doc) => !candidates.includes(doc));
508
+ const details =
509
+ candidate.op === "create" && existing.length === 1 && after.length === 2
510
+ ? conceptConflictDetails(existing, this.store.project)
511
+ : {
512
+ reason: before.length ? "same_type_title" : "same_batch_type_title",
513
+ candidates: after.slice(0, 5).map((doc) => conceptMatchSummary(doc)),
514
+ omitted: Math.max(0, after.length - 5),
515
+ recommendedOperation: "merge_batch_changes",
516
+ };
517
+ throw new AuthoringPolicyError(
518
+ `The batch would leave more than one concept with the same type and title: ${candidate.uri}`,
519
+ "concept_already_exists",
520
+ details,
521
+ );
522
+ }
523
+ const message = this.commitMessage(input, candidates);
524
+ const validation = withPolicyViolations(
525
+ this.validationResult(
526
+ updateIndex(
527
+ currentIndex,
528
+ { upserts: candidates.map((candidate) => candidateUpsert(candidate, false)) },
529
+ this.indexCache.options(),
530
+ ),
531
+ candidates,
532
+ ),
533
+ policy,
534
+ );
535
+ const gitPreflight = this.git.prepareGit(bundle, candidates);
536
+ return {
537
+ input,
538
+ bundle,
539
+ generated,
540
+ additionalBundles,
541
+ currentIndex,
542
+ candidates,
543
+ message,
544
+ validation,
545
+ policy,
546
+ gitPreflight,
547
+ target: targetReceipt(this.store, bundle, candidates, gitPreflight),
548
+ changes: candidateSummaries(candidates),
549
+ };
550
+ }
551
+
552
+ invalidValidationReceipt(error) {
553
+ const validation = policyValidation(error);
554
+ const generated = this.generatedStamp();
555
+ return {
556
+ valid: false,
557
+ readyToApply: false,
558
+ applied: false,
559
+ filesChanged: false,
560
+ status: "invalid",
561
+ snapshot: {
562
+ checkedAt: generated.at,
563
+ timeOfCheck: true,
564
+ generatedBy: generated.by,
565
+ graphValidation: "not_run",
566
+ },
567
+ preconditions: {
568
+ allSatisfied: false,
569
+ revisions: [],
570
+ git: {
571
+ enabled: this.gitCommit,
572
+ ready: false,
573
+ repositoryStatus: "not_inspected",
574
+ repositoryRoot: null,
575
+ diagnostics: [],
576
+ },
577
+ },
578
+ generated,
579
+ durability: durabilityReceipt(null, false),
580
+ changes: [],
581
+ validation,
582
+ ...(error?.code ? { code: error.code } : {}),
583
+ ...(error && error.details !== undefined ? { details: error.details } : {}),
584
+ git: {
585
+ enabled: this.gitCommit,
586
+ repository: false,
587
+ repositoryRoot: null,
588
+ repositoryStatus: "not_inspected",
589
+ commitState: "not_attempted",
590
+ persistence: "none",
591
+ },
592
+ };
593
+ }
594
+
595
+ async validateChanges(input, context) {
596
+ return this.store.withWriteLock(() => {
597
+ this.publication = null;
598
+ try {
599
+ return validationReceipt(this.planChanges(input, context));
600
+ } catch (error) {
601
+ if (!(error instanceof AuthoringPolicyError)) {
602
+ throw error;
603
+ }
604
+ return this.invalidValidationReceipt(error);
605
+ }
606
+ });
607
+ }
608
+
609
+ async applyChanges(input, context) {
610
+ return this.store.withWriteLock(() => this.applyChangesUnlocked(input, context));
611
+ }
612
+
613
+ async applyChangesUnlocked(input, context) {
614
+ this.publication = null;
615
+ const plan = this.planChanges(input, context);
616
+ if (!plan.validation.valid) {
617
+ return {
618
+ applied: false,
619
+ readyToApply: false,
620
+ filesChanged: false,
621
+ status: "rejected",
622
+ snapshot: snapshotReceipt(plan),
623
+ preconditions: preconditionsReceipt(plan),
624
+ generated: plan.generated,
625
+ target: plan.target,
626
+ durability: durabilityReceipt(null, false),
627
+ changes: plan.changes,
628
+ validation: plan.validation,
629
+ ...policyReceipt(plan),
630
+ git: {
631
+ enabled: plan.gitPreflight.enabled,
632
+ repository: Boolean(plan.gitPreflight.repository),
633
+ repositoryRoot: plan.gitPreflight.repositoryRoot,
634
+ repositoryStatus: plan.gitPreflight.repositoryStatus,
635
+ commitState: "not_attempted",
636
+ persistence: "none",
637
+ },
638
+ };
639
+ }
640
+ if (!plan.gitPreflight.ready) {
641
+ const blocker = plan.gitPreflight.diagnostics[0];
642
+ throw new AuthoringPolicyError(
643
+ blocker
644
+ ? blocker.message
645
+ : "Configured Git preconditions do not currently allow automatic apply.",
646
+ );
647
+ }
648
+ const transaction = this.stageCandidates(plan.candidates);
649
+ const staged = transaction.staged;
650
+ const applied = [];
651
+ try {
652
+ this.assertRevisions(staged);
653
+ staged.forEach((candidate) => {
654
+ if (candidate.op === "create") {
655
+ fs.linkSync(candidate.temporary, candidate.target.absolutePath);
656
+ applied.push(candidate);
657
+ fs.unlinkSync(candidate.temporary);
658
+ } else {
659
+ const currentRevision = revisionFor(fs.readFileSync(candidate.target.absolutePath));
660
+ if (currentRevision !== candidate.baseRevision) {
661
+ throw new Error(`Concept changed immediately before publication: ${candidate.path}`);
662
+ }
663
+ fs.renameSync(candidate.temporary, candidate.target.absolutePath);
664
+ applied.push(candidate);
665
+ }
666
+ });
667
+ } catch (error) {
668
+ const rollback = this.rollback(applied, staged, transaction.createdDirectories);
669
+ if (!rollback.complete) {
670
+ this.forgetIndex();
671
+ return rollbackReceipt(plan, rollback, error);
672
+ }
673
+ throw error;
674
+ }
675
+ let persistedValidation;
676
+ let persistedIndex;
677
+ try {
678
+ // Validate the bytes that landed on disk, read back from the targets,
679
+ // applied to the index the batch was planned against after a refresh,
680
+ // so a dependency that changed or vanished since planning counts too.
681
+ persistedIndex = updateIndex(
682
+ refreshIndex(plan.currentIndex, this.indexCache.options()),
683
+ { upserts: plan.candidates.map((candidate) => candidateUpsert(candidate, true)) },
684
+ this.indexCache.options(),
685
+ );
686
+ persistedValidation = this.validationResult(persistedIndex, plan.candidates);
687
+ } catch (error) {
688
+ const rollback = this.rollback(applied, staged, transaction.createdDirectories);
689
+ if (!rollback.complete) {
690
+ this.forgetIndex();
691
+ return rollbackReceipt(plan, rollback, error);
692
+ }
693
+ throw error;
694
+ }
695
+ if (!persistedValidation.valid) {
696
+ const rollback = this.rollback(applied, staged, transaction.createdDirectories);
697
+ if (!rollback.complete) {
698
+ this.forgetIndex();
699
+ }
700
+ return Object.assign(rollbackReceipt(plan, rollback, null), {
701
+ validation: persistedValidation,
702
+ });
703
+ }
704
+ let git;
705
+ try {
706
+ git = this.git.commitGit(plan.gitPreflight, plan.candidates, plan.message);
707
+ } catch (error) {
708
+ git = {
709
+ enabled: plan.gitPreflight.enabled,
710
+ repository: Boolean(plan.gitPreflight.repository),
711
+ repositoryRoot: plan.gitPreflight.repositoryRoot,
712
+ committed: null,
713
+ commitState: "unknown",
714
+ persistence: "unknown",
715
+ error: error?.message ? error.message : String(error),
716
+ };
717
+ }
718
+ if (git.targetState === "conflict") {
719
+ // The worktree diverged from what was validated; nothing the service
720
+ // holds describes the files now, so re-read everything and let the host
721
+ // rebuild its own index.
722
+ this.forgetIndex();
723
+ let currentValidation = persistedValidation;
724
+ try {
725
+ currentValidation = this.validationResult(this.buildIndex(plan.additionalBundles), []);
726
+ } catch {
727
+ // Preserve the last complete validation receipt when the conflicting state is unreadable.
728
+ }
729
+ if (git.committed !== true) {
730
+ return {
731
+ applied: false,
732
+ readyToApply: false,
733
+ filesChanged: true,
734
+ status: "post_publication_conflict",
735
+ snapshot: snapshotReceipt(plan),
736
+ preconditions: preconditionsReceipt(plan),
737
+ generated: plan.generated,
738
+ target: plan.target,
739
+ durability: durabilityReceipt(git, true, "partial_filesystem_state"),
740
+ changes: plan.changes,
741
+ validation: currentValidation,
742
+ ...policyReceipt(plan),
743
+ git,
744
+ error:
745
+ git.error || "Validated concept bytes were replaced before Git persistence completed.",
746
+ };
747
+ }
748
+ persistedValidation = currentValidation;
749
+ } else {
750
+ const shared = this.indexCache.index === plan.currentIndex;
751
+ this.indexCache.replace(plan.currentIndex, persistedIndex);
752
+ this.publication = {
753
+ index: persistedIndex,
754
+ hostOwned: Boolean(shared && this.indexCache.hostOwned),
755
+ changes: { upserts: plan.candidates.map((candidate) => candidateUpsert(candidate, true)) },
756
+ };
757
+ }
758
+ const status =
759
+ git.commitState === "unknown"
760
+ ? "applied_commit_unknown"
761
+ : git.committed === true && git.targetState === "conflict"
762
+ ? "applied_worktree_diverged"
763
+ : git.enabled && git.repository && !git.committed
764
+ ? "applied_uncommitted"
765
+ : "applied";
766
+ return {
767
+ applied: true,
768
+ readyToApply: git.targetState !== "conflict",
769
+ filesChanged: true,
770
+ status,
771
+ snapshot: snapshotReceipt(plan),
772
+ preconditions: preconditionsReceipt(plan),
773
+ generated: plan.generated,
774
+ target: plan.target,
775
+ durability: durabilityReceipt(git, true),
776
+ changes: plan.changes,
777
+ validation: persistedValidation,
778
+ ...policyReceipt(plan),
779
+ git,
780
+ };
781
+ }
782
+ }
783
+
784
+ module.exports = {
785
+ LiveAuthoringService,
786
+ MAX_CHANGES,
787
+ MAX_COMMIT_MESSAGE_BYTES,
788
+ MANAGED_METADATA_KEYS,
789
+ };