canopycms 0.0.67-int.90 → 0.0.67

package/dist/utils/content-serialize.js

@@ -1,23 +1,18 @@
 /**
  * Comment-preserving serialisation for YAML content files and md/mdx frontmatter.
  *
- * ContentStore used to write a content file by stringifying a fresh plain object
- * (`yamlStringify(data)` / `matter.stringify(body, data)`). Comments live in neither the object
- * nor that round trip, so **every editor save silently deleted every comment in the file** —
- * invisible to a dev team (`canopycms sync` copies files byte-for-byte) and certain for an
- * editorial team. See `.claude/future-tasks/resolved/content-comment-loss-on-editor-save.md`.
+ * Stringifying a fresh plain object (`yamlStringify(data)` / `matter.stringify(body, data)`)
+ * deletes every comment in the file, because comments live in neither the object nor that round
+ * trip. So these functions re-serialise onto the file's OWN parsed document: a node whose value
+ * did not change is left untouched, and an untouched node keeps its attached comments and its
+ * original quoting/block style. Only what actually changed is rewritten.
  *
- * The fix re-serialises onto the file's OWN parsed document instead of a fresh one: nodes whose
- * value did not change are left untouched, and an untouched node keeps its attached comments
- * (and its original quoting/block style). Only what actually changed is rewritten.
- *
- * What this module does NOT do is give the file any authority over its own content. The
- * reconciler makes the document's key set match `data` exactly — a key the caller dropped
- * disappears, a key the caller kept survives whether or not the schema still knows about it.
- * Data authority stays with the payload; comments are the only thing inherited from disk. That
- * separation is deliberate: whether a surviving key SHOULD still be there is a schema question,
- * answered one layer up by `findUnknownKeys` (validation/entry-validator.ts) at the API
- * boundary, not by a serialiser that has no schema.
+ * The file gets no authority over its own content. The reconciler makes the document's key set
+ * match `data` exactly — a key the caller dropped disappears, a key the caller kept survives
+ * whether or not the schema still knows about it. Data authority stays with the payload;
+ * comments are the only thing inherited from disk. Whether a surviving key SHOULD still be there
+ * is a schema question, answered one layer up by `findUnknownKeys`
+ * (validation/entry-validator.ts) at the API boundary, not by a schema-blind serialiser.
  */
 import matter from 'gray-matter';
 import { isCollection, isMap, isNode, isScalar, isSeq, parseDocument, stringify as yamlStringify, } from 'yaml';
@@ -25,20 +20,18 @@ import { isBlockStructuralKey } from '../validation/block-structural-keys.js';
 /**
  * True only for a PLAIN object — one that should be reconciled key-by-key against a YAML map.
  *
- * The prototype check is load-bearing, not defensive tidiness. A looser "object and not an array"
- * test classifies a class instance as a record, and the reconciler then walks its (empty) own
- * enumerable keys and emits `{}` — silently replacing the value. A `Date` is the case that
- * actually occurs: HTTP payloads carry none, but `ContentStore.write` is also reachable from
- * server-side callers (build scripts via `createBuildCanopy`, migrations), and `d: 2024-01-15`
- * became `d: {}` on save. Anything non-plain falls through to `doc.createNode`, which serialises
- * it exactly as the pre-fix `yaml.stringify` did.
+ * The prototype check is load-bearing. A looser "object and not an array" test classifies a class
+ * instance as a record, and the reconciler then walks its (empty) own enumerable keys and emits
+ * `{}`, silently replacing the value. `Date` is the case that occurs: HTTP payloads carry none,
+ * but `ContentStore.write` is also reachable server-side (build scripts via `createBuildCanopy`,
+ * migrations), where a date field came back as `{}`. Anything non-plain falls through to
+ * `doc.createNode`, which serialises it exactly as a plain `yaml.stringify` would.
  *
- * Known residual, and the reason this is a prototype check rather than a `toJSON` check: a PLAIN
- * object carrying its own `toJSON` is still walked as a record here, while `createNode` (the
- * create path, and the scalar-slot path) would call `toJSON` instead — so the same payload can
- * serialise differently depending on what is currently on disk, and a `toJSON` function value
- * makes `createNode` throw. Unreachable over HTTP, since JSON payloads carry no functions; a loud
- * failure rather than corruption if a server-side caller ever hits it.
+ * Residual, and the reason this is a prototype rather than a `toJSON` check: a PLAIN object
+ * carrying its own `toJSON` is walked as a record here while `createNode` would call `toJSON`,
+ * so the same payload can serialise differently depending on what is on disk, and a `toJSON`
+ * function value makes `createNode` throw. Unreachable over HTTP (JSON payloads carry no
+ * functions), and a loud failure rather than corruption if a server-side caller hits it.
  */
 function isPlainRecord(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
@@ -51,8 +44,7 @@ function isPlainRecord(value) {
  *
  * `String(...)` mirrors how parsing into a plain object projects non-string scalar keys
  * (`1: x` reads back as `{ '1': x }`). A non-scalar (complex) key — `? [a, b] : v` — has no
- * record counterpart at all; those pairs are dropped, which is what the old
- * stringify-a-fresh-object write did to them too.
+ * record counterpart at all; those pairs are dropped.
  */
 function recordKeyOf(keyNode) {
     if (!isScalar(keyNode))
@@ -65,8 +57,8 @@ function recordKeyOf(keyNode) {
     return String(value);
 }
 /**
- * Copy the comment metadata attached to a node being REPLACED onto its replacement, so a changed
- * value keeps the comments written about it.
+ * Copy a REPLACED node's comment metadata onto its replacement, so a changed value keeps the
+ * comments written about it.
  */
 function carryComments(from, to) {
     if (!isNode(from) || !isNode(to))
@@ -81,11 +73,10 @@ function carryComments(from, to) {
         target.spaceBefore = source.spaceBefore;
 }
 /**
- * Identity key for sequence alignment: the JSON form of a value.
- *
- * Returns undefined when the value cannot be keyed — a cyclic structure (reachable through YAML
- * anchors) makes `JSON.stringify` throw, and a save must never fail because of it. An unkeyable
- * item simply matches nothing and falls through to positional reconciliation.
+ * Identity key for sequence alignment: the JSON form of a value. Undefined when the value cannot
+ * be keyed — a cyclic structure (reachable through YAML anchors) makes `JSON.stringify` throw,
+ * and a save must never fail because of it. An unkeyable item matches nothing and falls through
+ * to positional reconciliation.
  */
 function identityKey(value) {
     try {
@@ -112,47 +103,33 @@ function nodeIdentityKey(node) {
 /**
  * How far {@link sharesFieldEvidence} descends into nested records before giving up.
  *
- * Termination does not actually depend on this — it is defence in depth, deliberately kept
- * because the alternative is depending on two other layers behaving as expected, which is the
- * shape of assumption that produced the bug {@link looksLikeSameItem} documents. Spelling out
- * what the cap is and is not doing, since the obvious guess is wrong in both directions:
- *
- * - A cyclic PAYLOAD is genuinely reachable (`ContentStore.write` is callable server-side with
- *   arbitrary objects, which is why `identityKey` guards `JSON.stringify` at all). It cannot run
- *   away here on its own, because the descent below only happens when BOTH sides are records.
- * - The on-disk side cannot supply the matching cycle: `existing` comes from `yaml`'s `toJSON()`,
- *   and a self-referential anchor (`- &b {self: *b}`) does not round-trip into a cyclic JS
- *   object — `toJSON` degrades the unresolvable alias to a plain `{ source }` marker (verified
- *   against the `yaml` version pinned here; the cycle case `identityKey`'s comment describes is
- *   the `JSON.stringify` hazard, not this one).
- *
- * So the real bound today is the finite depth of the parsed document — a guarantee owned by
- * `yaml`, not by this module. The cap makes it local and explicit, and incidentally bounds cost
- * on pathologically nested content. Real content bottoms out far shallower: a block is item ->
- * `value` -> fields, and an object field inside one adds a level. Exceeding the cap simply means
- * "no evidence found", which drops a comment rather than risking a move — the safe direction.
+ * Termination does not depend on it — the cap is defence in depth. A cyclic PAYLOAD is reachable
+ * server-side (which is why `identityKey` guards `JSON.stringify`) but cannot run away here: the
+ * descent happens only when BOTH sides are records, and the on-disk side comes from `yaml`'s
+ * `toJSON()`, which degrades an unresolvable self-referential anchor to a plain `{ source }`
+ * marker rather than a cyclic object. The real bound is the parsed document's finite depth, a
+ * guarantee owned by `yaml`; the cap makes it local and bounds cost on pathologically nested
+ * content. Exceeding it means "no evidence found", which drops a comment rather than risking a
+ * move — the safe direction.
  */
 const EVIDENCE_MAX_DEPTH = 6;
 /**
  * Does `value` share at least one non-structural leaf with `existing` — i.e. is there any field
  * whose value an edit left alone?
  *
- * Two things this looks past, both learned the hard way:
+ * Two things it looks past, and both halves are required together:
  *
  * - **Block discriminators are not evidence.** `template` (and the inline shape's `_type`) names
- *   a block's TEMPLATE, so every `hero` on the page carries the same one. Counting it made the
- *   check below true for any two blocks of the same kind. See `../validation/block-structural-keys`.
+ *   a block's TEMPLATE, so every `hero` on the page carries the same one; counting it makes the
+ *   check true for any two blocks of the same kind. See `../validation/block-structural-keys`.
  * - **A block's real fields are one level down.** The canonical shape is
- *   `{ template, value: { ...fields } }`, so comparing top-level values compares `value` whole —
- *   which differs the moment ANY field in it changes. Together with the point above that left a
- *   block with no reachable evidence at all, i.e. "drop every block comment on every edit". So
- *   nested records are descended into.
+ *   `{ template, value: { ...fields } }`, so comparing top-level values compares `value` whole,
+ *   which differs the moment ANY field in it changes — with the point above, that leaves a block
+ *   no reachable evidence at all, i.e. drops every block comment on every edit. So nested
+ *   records are descended into.
  *
- * Arrays are compared whole rather than element-wise, deliberately. A list has no item identity
- * — that is the premise `reconcileSeq` is built on — so pairing elements by index to harvest
- * evidence would be the same positional guess this module exists to refuse, just one level down.
- * The cost is that a record whose only field is a list loses its comment when that list changes,
- * which is the single-field residual documented on {@link looksLikeSameItem}, not a new class.
+ * Arrays are compared whole rather than element-wise: pairing elements by index to harvest
+ * evidence would be the same positional guess {@link reconcileSeq} refuses, one level down.
  */
 function sharesFieldEvidence(existing, value, depth) {
     for (const key of Object.keys(value)) {
@@ -162,9 +139,8 @@ function sharesFieldEvidence(existing, value, depth) {
             continue;
         const before = existing[key];
         const after = value[key];
-        // Descending is only ever an EXTRA chance to find evidence: the whole-value comparison below
-        // still runs, so a pair of structurally-empty records ({} vs {}) still matches on identity
-        // even though there is no leaf inside them to match on.
+        // Descending is only an EXTRA chance to find evidence: the whole-value comparison below still
+        // runs, so a pair of structurally-empty records ({} vs {}) still matches on identity.
         if (depth < EVIDENCE_MAX_DEPTH &&
             isPlainRecord(before) &&
             isPlainRecord(after) &&
@@ -179,41 +155,26 @@ function sharesFieldEvidence(existing, value, depth) {
 }
 /**
  * Is `value` plausibly an EDITED version of the item currently at this index, rather than a
- * different item that merely landed on the same index?
- *
- * Position alone is not evidence. A save that replaces one list item wholesale — delete this
- * block, add that one — leaves the new item sitting exactly where the old one was, and pairing
- * them purely by index moved the old item's comments onto content they do not describe. For the
- * comments this change exists to protect ("do not delete this block") that is worse than losing
- * them, because a lost comment reads as a deletion in review while a moved one reads as intact.
+ * different item that merely landed on the same index? Position alone is not evidence: a save
+ * that replaces one list item wholesale leaves the new item exactly where the old one was, and
+ * {@link reconcileSeq} explains why pairing them anyway is the worse failure.
  *
  * Records carry usable evidence: an edit changes some fields and leaves others alone, so one
- * surviving field value means "same item, edited". The evidence has to be a real FIELD, though.
- * An earlier version of this rule accepted any shared key/value pair on the reasoning that "a
- * wholesale replacement shares nothing" — true of arbitrary records, false of this CMS's block
- * shape, where `template: <name>` is a category label every block of that kind carries. A save
- * that deleted one `hero` and edited the next shifted the survivor onto the deleted item's
- * index, and the discriminator alone was enough to pair them: the deleted block's "keep this
- * verbatim" comment silently migrated onto unrelated content. So the module was failing in the
- * exact direction it declared unacceptable, through the case it assumed could not arise.
- * {@link sharesFieldEvidence} is therefore discriminator-blind and record-deep.
+ * surviving field value means "same item, edited". The evidence has to be a real FIELD, which is
+ * why {@link sharesFieldEvidence} is discriminator-blind and record-deep — `template: <name>` is
+ * a category label every block of that kind carries, so counting it pairs a block deleted from an
+ * index with the unrelated survivor that shifted onto it, migrating a "keep this verbatim"
+ * comment onto other content. One shared field is the bar, not two: raising it would take a
+ * two-field block — the common size — from "keeps its comment when one field is edited" to
+ * "never keeps it".
  *
- * Scalars carry no evidence at all, so they keep the plain same-index rule — an edited string in
- * a list is overwhelmingly the common case there, and a short annotation on a scalar is far less
- * load-bearing than a block comment. That residual is unchanged by the above and is pinned as
- * accepted rather than fixed: giving scalars the same treatment would drop the comment on every
- * ordinary one-line edit, which is a large, certain loss traded against a small, speculative one.
+ * Scalars carry no evidence and keep the plain same-index rule: an edited string in a list is the
+ * common case, a short scalar annotation is far less load-bearing than a block comment, and
+ * treating scalars the same way would drop the comment on every ordinary one-line edit.
  *
- * One shared field is still the bar, not two. Raising it would take a two-field block — the
- * common size — from "keeps its comment when one field is edited" to "never keeps it", which
- * empties the rule out for the shape it was just repaired for; the discriminator was the thing
- * making one pair meaningless, and it is now excluded.
- *
- * The residuals, deliberately accepted: a record whose every field changed shares nothing, so
- * its comment is dropped rather than risked (this now includes a block edited in ALL its fields,
- * which previously kept its comment via the discriminator — a deliberate move toward the losing
- * side of the trade-off); and a genuine schema field NAMED `template` or `_type` is not counted
- * as evidence, which can only ever drop a comment, never move one.
+ * Residuals, deliberately accepted: a record whose every field changed shares nothing, so its
+ * comment is dropped rather than risked; and a genuine schema field NAMED `template` or `_type`
+ * is not counted as evidence, which can only drop a comment, never move one.
  */
 function looksLikeSameItem(node, value) {
     const existing = nodePlainValue(node);
@@ -223,9 +184,8 @@ function looksLikeSameItem(node, value) {
     return sharesFieldEvidence(existing, value, 0);
 }
 /**
- * Reconcile one slot of the document against the value that must occupy it, returning the node
- * to put there. `existing` is the node currently in that slot (or null/undefined for a slot that
- * did not exist).
+ * Reconcile one slot of the document against the value that must occupy it, returning the node to
+ * put there. `existing` is the node in that slot, or null/undefined for a slot that did not exist.
  */
 function reconcileNode(doc, existing, value) {
     if (isMap(existing) && isPlainRecord(value)) {
@@ -236,38 +196,34 @@ function reconcileNode(doc, existing, value) {
         reconcileSeq(doc, existing, value);
         return existing;
     }
-    // Unchanged scalar: return the node itself, untouched. This is the case that preserves
-    // comments in practice, and it also keeps the author's original quoting and block style.
+    // Unchanged scalar: return the node itself, untouched. This is the case that preserves comments
+    // in practice, and it keeps the author's original quoting and block style.
     if (isScalar(existing) && Object.is(existing.value, value))
         return existing;
-    // Changed, or a shape change (scalar <-> collection). Build a fresh node rather than mutating
-    // `scalar.value` in place: an in-place type change would keep the old node's representation,
-    // emitting `'42'` where the number 42 was meant.
+    // Changed, or a shape change (scalar <-> collection). A fresh node rather than mutating
+    // `scalar.value` in place, which would keep the old node's representation and emit `'42'` where
+    // the number 42 was meant.
     const fresh = doc.createNode(value);
     // Comments move with a changed VALUE, but not off a replaced STRUCTURE. `yaml` attaches a
-    // comment written above a collection's first entry to the collection node itself (the same
-    // rule that makes a leading list comment a list-head comment), so that node's comments are
-    // about its innards. Carrying them onto whatever replaces the collection put "# FLAG: explains
-    // the heading below" above a bare string that has no heading -- a comment over content it does
-    // not describe, which this module treats as worse than losing it. A comment written above the
-    // KEY is unaffected either way: it lives on the pair's key node, which is never replaced here.
+    // comment written above a collection's first entry to the collection node itself, so that
+    // node's comments are about its innards; carrying them onto whatever replaces the collection
+    // puts a comment over content it does not describe, which this module treats as worse than
+    // losing it. A comment written above the KEY is unaffected: it lives on the pair's key node,
+    // which is never replaced here.
     if (!isCollection(existing))
         carryComments(existing, fresh);
     return fresh;
 }
 /**
- * Make a map's key set match `value` exactly.
- *
- * Retained pairs are reconciled in place, so their key order and the comments attached to their
- * keys survive; keys new to `value` are appended in `value` order, which keeps the diff of a
- * save down to the lines that actually changed.
+ * Make a map's key set match `value` exactly. Retained pairs are reconciled in place, so their key
+ * order and the comments attached to their keys survive; keys new to `value` are appended in
+ * `value` order, keeping a save's diff down to the lines that actually changed.
  */
 function reconcileMap(doc, map, value) {
-    // An explicitly-undefined key is NOT a key. `Object.keys` reports it, but both `JSON.stringify`
-    // and `yaml.stringify` omit it — so without this filter a key present on disk and set to
-    // `undefined` in the payload would be rewritten as `key: null` here while the create path
-    // dropped it entirely. Same rule on both paths, so "the key set matches the payload" holds
-    // exactly rather than approximately.
+    // An explicitly-undefined key is NOT a key: `Object.keys` reports it but `JSON.stringify` and
+    // `yaml.stringify` omit it, so without this filter a key present on disk and set to `undefined`
+    // in the payload is rewritten as `key: null` here while the create path drops it. Same rule on
+    // both paths, so "the key set matches the payload" holds exactly rather than approximately.
     const wanted = new Set(Object.keys(value).filter((key) => value[key] !== undefined));
     const seen = new Set();
     const retained = [];
@@ -291,23 +247,19 @@ function reconcileMap(doc, map, value) {
 /**
  * Make a sequence's items match `value` exactly, aligning by VALUE first and position second.
  *
- * A list has no item identity — nothing in the payload says "this is the item that used to be
- * third" — so any alignment is a guess, and the two failure modes are not equally bad. Losing a
- * comment shows up in review as a deletion; silently MOVING a comment onto content it does not
- * describe does not, and the comments this fix exists to protect are exactly the load-bearing
- * kind ("do not delete this block") that must never end up over the wrong thing. The rules are
- * therefore ordered from most evidence to least, and stop rather than guessing:
+ * A list has no item identity, so any alignment is a guess and the failure modes are not equally
+ * bad: losing a comment shows up in review as a deletion, silently MOVING one onto content it does
+ * not describe does not, and the comments this protects are the load-bearing kind ("do not delete
+ * this block"). The rules run from most evidence to least, and stop rather than guessing:
  *
- * 1. **Exact value match** — reuse that old node whole, comments and all. This is what carries a
- *    comment through a pure reorder, instead of stranding it on whatever moved into its index.
+ * 1. **Exact value match** — reuse that old node whole, comments and all. This carries a comment
+ *    through a pure reorder instead of stranding it on whatever moved into its index.
  * 2. **Same index, still unclaimed, and recognisably the same item** (`looksLikeSameItem`) —
- *    reconcile against it. This is the edit-in-place case.
+ *    reconcile against it: the edit-in-place case. Same-index rather than "next unclaimed old
+ *    node in order", which pairs a newly-inserted item with an unrelated deleted one whenever one
+ *    save both removes and adds; and evidence as well as position, because a wholesale
+ *    replacement lands on the index it replaced.
  * 3. **Otherwise a fresh node, with no comments.**
- *
- * Rule 2 is deliberately same-index rather than "next unclaimed old node in order": the looser
- * form paired a newly-inserted item with an unrelated deleted one whenever one save both removed
- * and added an item. Position alone is still not enough, though — a wholesale replacement lands
- * on the index it replaced — which is why rule 2 also demands evidence of identity.
  */
 function reconcileSeq(doc, seq, value) {
     const oldItems = seq.items;
@@ -342,9 +294,8 @@ function reconcileSeq(doc, seq, value) {
         const matched = matches[index];
         if (matched !== undefined)
             return oldItems[matched];
-        // `consumed` holds OLD indices claimed by rule 1, so this asks "is the node that sits at my
-        // index still unclaimed?". Each iteration owns a distinct index, so no bookkeeping is needed
-        // here — a candidate cannot be taken twice.
+        // `consumed` holds OLD indices claimed by rule 1, so this asks "is the node at my index still
+        // unclaimed?". Each iteration owns a distinct index, so a candidate cannot be taken twice.
         const candidate = index < oldItems.length && !consumed.has(index) ? oldItems[index] : undefined;
         const sameItem = candidate !== undefined && looksLikeSameItem(candidate, item) ? candidate : undefined;
         return reconcileNode(doc, sameItem, item);
@@ -357,9 +308,9 @@ function applyDataToDocument(doc, data) {
 /**
  * Serialise entry data as a YAML file, carrying the comments of `existingRaw` through.
  *
- * Falls back to a plain stringify — byte-identical to the pre-fix behaviour — when there is
- * nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk do not
- * parse). A save must not fail because the previous content was malformed.
+ * Falls back to a plain stringify — byte-identical to serialising without preservation — when
+ * there is nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk
+ * do not parse). A save must not fail because the previous content was malformed.
  */
 export function serializeYaml(data, existingRaw) {
     if (existingRaw === undefined)
@@ -371,16 +322,15 @@ export function serializeYaml(data, existingRaw) {
     return doc.toString();
 }
 /**
- * Split a file into its raw frontmatter string, or undefined when there is nothing usable.
- *
- * Two gray-matter hazards are handled here, both of which cost a real bug when discovered:
+ * Split a file into its raw frontmatter string, or undefined when there is nothing usable. Two
+ * gray-matter hazards:
  *
  * 1. **The options argument is load-bearing.** `matter(str)` with no options reads and writes a
- *    process-global content-keyed cache, and the object it hands back on a HIT has lost
- *    `.matter` — so the second save of the same file would silently see no frontmatter and drop
- *    every comment. Passing an options object skips the cache on both sides (see the `if
- *    (!options)` guard in gray-matter's index.js), which also keeps the write path from
- *    polluting that cache for everyone else — the same class of problem as `42aede48`.
+ *    process-global content-keyed cache whose HIT returns an object that has lost `.matter`, so
+ *    the second save of the same file silently sees no frontmatter and drops every comment.
+ *    Passing an options object skips the cache on both sides (the `if (!options)` guard in
+ *    gray-matter's index.js), which also keeps this write path from polluting that cache for
+ *    everyone else.
  * 2. **It throws on malformed frontmatter.** js-yaml raises rather than returning an error list,
  *    so a file whose bytes do not parse must not be allowed to fail the save.
  *
@@ -401,11 +351,10 @@ function extractRawFrontmatter(raw) {
     return frontmatter;
 }
 /**
- * Serialise an md/mdx entry, carrying the comments of `existingRaw`'s frontmatter through.
- *
- * The reconciled YAML goes back through `matter.stringify` via a custom stringify engine rather
- * than being spliced between hand-written `---` lines, so the delimiters, blank lines and
- * trailing newline stay exactly what gray-matter would have produced.
+ * Serialise an md/mdx entry, carrying the comments of `existingRaw`'s frontmatter through. The
+ * reconciled YAML goes back through `matter.stringify` via a custom stringify engine rather than
+ * being spliced between hand-written `---` lines, so delimiters, blank lines and the trailing
+ * newline stay exactly what gray-matter would have produced.
  */
 export function serializeFrontmatter(body, data, existingRaw) {
     if (existingRaw === undefined)

package/dist/utils/content-write-lock.d.ts

@@ -1,124 +1,69 @@
 /**
- * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and
- * content writes against the same branch working tree.
- *
- * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
- * `ContentStore`'s write/delete/rename critical sections were guarded only by
- * the in-process mutex (`utils/async-mutex`), which does not cross that
- * boundary, while the worker's rebase loop (`rebaseOneBranch` in
- * worker/rebase.ts) rewrites the very same
- * working tree. A write landing after `git rebase` started is destroyed two
- * ways -- `git checkout --theirs <file>` overwrites it with the branch's
- * committed version (and the rebase then SUCCEEDS, logging nothing), and
- * `git rebase --abort` hard-resets the tree. Either way the editor already got
- * its 200. This lock is what serializes the two.
- *
- * **Asymmetric by design.** The worker retries every branch on its next sync
- * cycle (~5 minutes) while the editor is a person waiting on a save, so the
- * worker yields and the writer waits:
- *
- * - Worker: {@link tryAcquireContentWriteLock} -- zero retries. On contention
- *   it skips that branch this cycle (an extension of the existing
- *   skip-dirty-branches behavior) and picks it up next cycle.
- * - Writers: {@link withContentWriteLock} -- a short bounded wait, then a
- *   retriable failure the API surfaces as a 409.
- *
- * **Reads never take this lock.** An extra EFS round-trip on every read is not
- * an acceptable price, and a read racing a rebase gets a consistent-enough
- * older or newer file, never a destroyed one.
- *
- * ## Why the lock marker lives under `{branchRoot}/.canopy-meta`
- *
- * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
- * release function) by the **target path** passed to `lock()`, NOT by
- * `lockfilePath`. `provisioning-lock.ts` now anchors every lock on its own
- * marker path, so the registry key equals the on-disk lock identity and two
- * live locks can no longer share a key -- aliasing is structurally impossible
- * rather than merely avoided by convention. Keeping the content lock under
- * `{branchRoot}/.canopy-meta` still buys:
- *
- * - a per-branch marker, so one branch's content lock is independent of every
- *   other branch's and of that branch's provisioning lock; and
- * - no deadlock potential: the two locks are never both required, and the only
- *   possible acquisition order (provision, then write) is consistent.
- *
- * `.canopy-meta/` is git-excluded in every branch clone (`ensureGitExclude`),
- * so the lock directory can never dirty the working tree or be swept into
- * `git add .` at publish time.
- *
- * ## Honest caveat (do not oversell this)
- *
- * `proper-lockfile` decides a holder is dead by reading the lock directory's
- * mtime with `fs.stat`, which on EFS is served through the NFS attribute
- * cache. A live holder refreshes every `stale/2`, but a waiter can read a
- * cached mtime and conclude the lock is stale when it is not, taking it over.
- * The failure mode of a bad takeover is exactly today's behavior (two
- * unsynchronized writers), so this is a strict improvement -- not a proof of
- * mutual exclusion. See docs/concurrency.md.
+ * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and content writes
+ * against the same branch working tree. docs/concurrency.md has the layering.
+ *
+ * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem, so `ContentStore`'s
+ * in-process mutex (`utils/async-mutex`) does not cover the worker's rebase (`rebaseOneBranch` in
+ * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started is
+ * destroyed either way -- `git checkout --theirs` overwrites it and the rebase then SUCCEEDS
+ * silently, or `git rebase --abort` hard-resets the tree -- and the editor already got its 200.
+ *
+ * **Asymmetric by design.** The worker retries every branch on its next sync cycle (~5 minutes)
+ * while the editor is a person waiting on a save, so the worker yields and the writer waits:
+ *
+ * - Worker: {@link tryAcquireContentWriteLock} -- zero retries, skips the branch this cycle.
+ * - Writers: {@link withContentWriteLock} -- a short bounded wait, then
+ *   {@link ContentWriteLockBusyError}, which `ContentStore` maps to `BranchSyncingError` and the
+ *   API to a 409.
+ *
+ * **Reads never take this lock.** An extra EFS round-trip on every read is not an acceptable
+ * price, and a read racing a rebase gets an older or newer file, never a destroyed one.
+ *
+ * The marker lives under `{branchRoot}/.canopy-meta` and the lock anchors on that marker path like
+ * every other lock (see provisioning-lock.ts), so it can never alias the branch's provisioning
+ * lock; the two are never both required and the only possible order (provision, then write) is
+ * consistent, so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
+ * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be swept into `git add .`.
+ *
+ * Mutual exclusion is not proven: on EFS a stale cached mtime lets a waiter take over a live lock,
+ * leaving two unsynchronized writers -- the unlocked behaviour, so still a strict improvement.
  */
 import { type OnLockCompromised } from './provisioning-lock.js';
-/** On-disk name of the lock marker (a directory, created by mkdir). */
-export declare const CONTENT_WRITE_LOCK_NAME = "content-write.lock";
 /**
  * Default bounded wait for a content write.
  *
- * Deliberately short. A rebase holds this lock for a fetch plus a replay plus
- * N conflict rounds of git subprocesses on EFS -- far longer than any wait an
- * interactive save can absorb, and longer than the API's own latency budget.
- * So the wait is not sized to outlast a rebase (nothing reasonable could); it
- * is sized to absorb lock handoff and the short holds of other writers, and to
- * turn everything longer into a fast, explicit "retry" the editor can act on
- * rather than a request that hangs toward the Lambda timeout. The worker
- * revisits the branch next cycle, so the blocked state is transient.
- *
- * This is ALSO the writer-vs-writer budget, not only the rebase one. The lock
- * is per-branch-root, so every write to one branch now serializes behind it
- * where in-process serialization used to be per-entry -- bounded on Lambda
- * (one invocation per container), but real under `next dev` and build-time
- * provisioning across worker processes. The case to watch is a write whose
- * in-lock path triggers a full `idIndex()` rescan of a large tree over EFS:
- * that can plausibly exceed this budget and start 409ing unrelated saves.
- * Making it configurable for prod tuning is tracked in
+ * Deliberately short. A rebase holds this lock for a fetch, a replay and N conflict rounds of git
+ * subprocesses on EFS -- longer than an interactive save can absorb -- so the wait is not sized to
+ * outlast one. It absorbs lock handoff and other writers' short holds, and turns everything longer
+ * into a fast, explicit "retry" rather than a request hanging toward the Lambda timeout; the
+ * worker revisits the branch next cycle, so the blocked state is transient.
+ *
+ * It is ALSO the writer-vs-writer budget: the lock is per-branch-root, so every write to one
+ * branch serializes behind it -- bounded on Lambda (one invocation per container), but real under
+ * `next dev` and build-time provisioning across worker processes. The case to watch is a write
+ * whose in-lock path triggers a full `idIndex()` rescan of a large tree over EFS, which can exceed
+ * this budget and start 409ing unrelated saves. Making it configurable is tracked in
  * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
  */
 export declare const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
 /**
- * Thrown when the bounded wait expires with the branch's content lock still
- * held. Retriable -- callers translate this into a 409 with a message that
- * says so.
- *
- * The message says "syncing OR another save" because BOTH produce it. The
- * lock is taken by `write`/`delete`/`renameEntry` and by the admin
- * repair-content-duplicates action as well as by the worker's rebase, so a
- * message naming only the rebase was a confident claim about something that
- * may not be happening. `api/content.ts` routes this error ahead of the
- * generic conflict specifically so the editor sees this wording, which makes
- * the wording load-bearing rather than cosmetic.
+ * Thrown when the bounded wait expires with the branch's content lock still held. Retriable --
+ * callers translate it into a 409 with a message that says so.
+ *
+ * The message says "syncing OR another save" because BOTH produce it: the lock is taken by
+ * `write`/`delete`/`renameEntry` and the admin repair-content-duplicates action as well as by the
+ * worker's rebase, so naming only the rebase would claim more than is known. `api/content.ts`
+ * routes this error ahead of the generic conflict so the editor sees this wording, making it
+ * load-bearing rather than cosmetic.
  */
 export declare class ContentWriteLockBusyError extends Error {
     constructor(message?: string);
 }
 /**
- * Acquire the branch's content-write lock WITHOUT waiting.
- *
- * Throws an error with `code === 'ELOCKED'` when a live holder has it. Used by
- * the worker's rebase loop (which skips the branch and retries next cycle) and
- * by tests standing in for a writer.
+ * Acquire the branch's content-write lock WITHOUT waiting, for the worker's rebase loop, which
+ * skips the branch and retries next cycle. Throws with `code === 'ELOCKED'` on a live holder.
  */
 export declare function tryAcquireContentWriteLock(branchRoot: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
-/**
- * Acquire the branch's content-write lock with a short bounded wait.
- *
- * Retries ONLY on genuine contention (`ELOCKED`), the same discipline
- * `withOccFileLock` uses: proper-lockfile's own retry loop retries blindly on
- * any error, which would burn the whole budget re-hitting e.g. ENOENT after
- * the branch directory was deleted out from under the caller.
- *
- * @throws ContentWriteLockBusyError when the budget expires under contention.
- */
-export declare function acquireContentWriteLock(branchRoot: string, waitMs?: number, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
-/**
- * Run `fn` holding the branch's content-write lock, releasing it in a
- * `finally` so a throw can never strand it.
- */
+/** Run `fn` holding the branch's content-write lock, releasing in a `finally` so a throw cannot
+ * strand it. */
 export declare function withContentWriteLock<T>(branchRoot: string, fn: () => Promise<T>, waitMs?: number): Promise<T>;