@objectstack/metadata-fs 17.0.0-rc.6 → 17.1.0

package/CHANGELOG.md

@@ -1,5 +1,309 @@
 # @objectstack/metadata-fs
 
+## 17.1.0
+
+### Patch Changes
+
+- bd2fc8b: fix(metadata-fs): an external write reaches subscribers even when the watcher's single delivery attempt is lost — content-keyed reconciliation behind the poll (#9339)
+  
+  `FileSystemRepository`'s watcher gave an externally-written file **exactly one**
+  chance to be noticed, and losing it was permanent and silent. Under
+  `usePolling`, chokidar re-reads a directory only when its stat *strictly*
+  advances; an external write advances the type directory's mtime once, so poll
+  #2..#N compare an unchanged stat and can never rediscover the file. Measured on
+  #9339 with a fault-injection harness: with that single read suppressed, fifteen
+  further poll ticks never find the file — a 20s deadline and a 200s deadline buy
+  the same one attempt. That is the structural reason behind #7282's empirical
+  finding that the event is *"never delivered, not slow"*, and why widening the
+  deadline (#7208) and lowering `interval` were both spent before they were tried.
+  
+  **At least six independent one-shot gates sit on that attempt**, spanning three
+  layers — the kernel timestamp (the directory mtime does not strictly advance),
+  chokidar's readdir throttle and readdir snapshot, and chokidar's emit gates
+  (`_throttle('add')`, a stale `_pendingWrites` entry, the `awaitWriteFinish`
+  ENOENT early return). Each produces a byte-identical observable: no event, ever,
+  for that path. They are indistinguishable at the point of failure, which is why
+  #7282's close — picked from that family — covered one member and reopened.
+  
+  **The fix does not name a member.** A bounded, content-keyed reconciliation
+  sweep runs alongside the watcher and compares what is on disk against `heads`,
+  the index that already defines what the repository believes it holds, publishing
+  any divergence through the *same* handler the watcher feeds. Its only premise is
+  that the bytes on disk stopped matching the index, so it is robust across all six
+  by construction — and equally across a seventh nobody has found.
+  
+  - **Cadence** — one pass over `<root>/<type>/*.json` every 2s (twice the poll
+    interval), the same walk `start()` already performs once. Sweeps are chained
+    rather than intervalled, so they can never overlap or stack behind a slow
+    disk; the timer is `unref`ed and is retired by `close()`; and it is armed only
+    alongside the watcher, so a `disableWatch` repository pays nothing.
+  - **Exactly-once is preserved.** Suppression stays content-keyed (`#7335`): the
+    sweep republishes nothing the watcher already delivered, and recognises this
+    repository's own `put()` by content rather than by a clock.
+  - **Events are indistinguishable from the fast path** — same `op`,
+    `parentHash`, `source: 'fs'` and actor, because they are produced by the same
+    code. A subscriber cannot be made to care which path noticed.
+  - **A recovered path is re-armed** with the watcher through the seam `put()`
+    already uses, so a loss upstream of chokidar's `_handleFile` does not leave
+    the file dependent on the sweep forever.
+  - `put()`'s existing direct registration (#7336) is unchanged, as are
+    `usePolling`, `interval`, and `awaitWriteFinish`.
+  
+  ⚠️ **Bound on the claim.** The six gates are *forced fault injections*, not the
+  CI mechanism, which was never identified and may be a seventh. What is measured
+  is that the fix converts **six of six** forced one-shot gates from permanent
+  loss to delivery (3/3 runs each), where all six returned an empty event list
+  before it. That is not the same statement as "the flake is fixed".
+- Updated dependencies [b6c7690]
+- Updated dependencies [845e164]
+- Updated dependencies [1a7f907]
+- Updated dependencies [7fc01db]
+  - @objectstack/metadata-core@17.1.0
+
+## 17.0.0
+
+### Patch Changes
+
+- 2e836de: chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+  The AGENTS.md post-task checklist requires breaking changesets to carry their
+  FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+  inside the npm package and is what an upgrading agent greps after the tombstone
+  error." That delivery path was severed for 68 of the 69 publishable packages:
+  npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+  older npm versions — not `CHANGELOG.md`, and the canonical
+  `"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+  10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+  70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+  explicitly.
+
+  The tombstone-error scenario is precisely the one where the repo is out of
+  reach — the upgrading agent has `node_modules` and nothing else — so the
+  migration text has to ride in the tarball. Every publishable package now
+  declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+  `["dist", "README.md", "CHANGELOG.md"]`.
+
+  The other half is the gate: `check:published-files` gains a fifth invariant,
+  COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+  always-required lint job, so the next package cannot silently sever the path
+  again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+  into the canonical set.
+
+  Consumer-visible change: one more file per install (the package's changelog,
+  e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+  promised.
+
+- a1b66ef: `FileSystemRepository` no longer creates its root directory when it is attached — only when it first writes.
+
+  `start()` used to `mkdir` both `<root>` and `<root>/.objectstack/.log` unconditionally, so merely attaching a repository was a write. Because `MetadataPlugin` attaches one at `<project>/.objectstack/metadata` during every boot, a command that never writes metadata still brought a directory skeleton into existence. The loudest case is `os migrate plan`, a declared dry run: on a project that had never been started it left
+
+  ```
+  .objectstack/metadata/.objectstack/.log
+  ```
+
+  behind, which also destroyed the one signal — does `.objectstack/` exist? — by which the next command can tell a fresh project from a started one. This is the filesystem half of the same property the database half already covers: a dry run leaves nothing behind.
+
+  Attaching and reading a repository whose root does not exist is now explicitly supported and answers as an empty repository (`get`, `getByHash`, `list`, `history`, `watch`). The root, the type directories and the JSONL change log all appear on the first `put` / `delete`, and nothing about the boot's read-only character changes: no metadata is written that was not written before.
+
+  One behavioural note for direct users of the package: when the root is absent at `start()`, the chokidar watcher is armed by the first write instead, because chokidar cannot watch a path that does not yet exist. A root brought into existence by a third party while the process runs — with this repository never writing — is therefore not picked up until the next `start()`.
+
+- c7e7900: fix(metadata-core,metadata-fs): hash the serialized form, so `put().version` identifies the bytes actually stored (#7856)
+
+  `hashSpec` canonicalised a `Date` to `{}`, because `canonicalize` walked a
+  value's own enumerable keys and a `Date` has none. `JSON.stringify` — what every
+  repository actually writes — turns the same `Date` into an ISO string. So the
+  hash of the in-memory spec and the hash of the bytes on disk were **different
+  hashes for the same item**, and the version handed back to a caller did not
+  identify what had been stored.
+
+  Measured on `main`, one spec carrying one `Date`:
+
+  ```
+  canonicalize(in-memory) : {"createdAt":{},"label":"Home"}
+  JSON.stringify (bytes)  : {"label":"Home","createdAt":"2024-01-01T00:00:00.000Z"}
+  ```
+
+  `canonicalize` now honours `toJSON` exactly as `JSON.stringify` does —
+  consulted once per position, its result serialised as-is and never
+  re-consulted — which makes a new guarantee true by construction:
+
+  ```
+  canonicalize(x) === canonicalize(JSON.parse(JSON.stringify(x)))
+  ```
+
+  **Both repository implementations were wrong, in different places**, which is
+  why the fix is one function rather than two patches. `FileSystemRepository`
+  broke `put().version === get().hash`: it hashed the spec it was handed, wrote
+  `JSON.stringify` of it, and re-hashed the parse on the way back out.
+  `InMemoryRepository` broke the repository contract's invariant 4
+  (`item.hash === hashSpec(item.body)`): it stores `body` already serialised
+  (`clonePlain`) while hashing the in-memory spec, so the item it returns
+  disagreed with its own hash. `SysMetadataRepository` inherits the fix through
+  the same function.
+
+  Downstream, an incoherent version meant a repository could report an
+  `{op:'update', actor:'fs'}` for a file nothing outside the process had touched:
+  the head index held a hash the disk could never reproduce, so re-reading one's
+  own write looked like somebody else's edit. That surfaces without any watcher —
+  a restart rebuilds the index from disk and the version the caller was handed no
+  longer matches it.
+
+  **Ordinary specs hash exactly as before, and this is not a migration.** The new
+  path diverges only at a position carrying a callable `toJSON`; a graph without
+  one is byte-identical through `canonicalize`. Verified against this repository's
+  entire checked-in JSON corpus — 1973 files hashed under both the old and the new
+  implementation, **0 hashes changed** — and the `hashSpec({})` regression guard
+  in `metadata-core` is unmoved. Stored versions for ordinary specs keep their
+  meaning. Versions for `toJSON`-carrying specs do change, and those are exactly
+  the versions that never identified their stored bytes in the first place.
+
+  Also supported as a consequence: a class instance with a `toJSON` now hashes as
+  whatever it serialises to, rather than as its private fields. One without a
+  `toJSON` still hashes as its own enumerable keys — which is what
+  `JSON.stringify` writes for it.
+
+  The pin is table-driven and lives in the shared repository contract suite, so
+  every `MetadataRepository` implementation is held to it: `Date` at a key, `Date`
+  under an array index, a class whose `toJSON` yields a string, an object literal
+  carrying its own `toJSON`, a nested case, and a plain-JSON control row that
+  proves the fix did not simply change every hash.
+
+- a1686f9: fix(metadata-fs): stop suppressing self-writes on a wall clock, so a poll tick can no longer swallow an external edit (#7335)
+
+  `FileSystemRepository` suppressed the watcher event its own `put()`/`delete()`
+  was about to produce by adding the path to a `selfWrites` Set and clearing it on
+  a fixed `setTimeout(…, 200)`. `handleFsChange` then dropped **any** event for a
+  path in that Set, without ever reading what the watcher had observed.
+
+  Under `usePolling: true, interval: 1000` chokidar compares state once per tick,
+  so our own write and an external edit landing between two ticks are delivered as
+  a **single** event carrying the _external_ content. Dropping that on a timer
+  destroyed the only notification the external edit would ever produce — the edit
+  was silently lost, and nothing later recovered it. The realistic trigger is a
+  `git checkout` or an editor save arriving while the process writes the same item:
+  the dev-mode authoring loop.
+
+  **Measured.** The filing recorded 0/360 instrumented iterations reaching the
+  window and called it derived rather than observed. That was a sampling artefact:
+  the delivery lag of a self-write event is
+  `(interval - (writeTime mod interval)) + awaitWriteFinish`, so a _fixed_
+  pre-edit sleep phase-locks the poll and pins the lag outside the window
+  (measured: 519–585 ms across 25 runs). Randomising the sleep so the lag samples
+  `[0, interval)` uniformly, 40 runs:
+
+  | delivery lag | runs | external edit |
+  | ------------ | ---- | ------------- |
+  | < 200 ms     | 7    | **swallowed** |
+  | > 200 ms     | 33   | delivered     |
+
+  A perfect split on the wall-clock boundary — the mechanism, observed.
+
+  **The fix removes the pre-check rather than re-keying it**, because the
+  content-keyed suppression it was shadowing already existed one step further
+  down and needs no timer:
+
+  - `add`/`change` — `currentHead === hash` drops the event when the bytes on disk
+    are the bytes we last published. `put()` sets that head in the same
+    continuation as its `rename`, and `awaitWriteFinish` holds any event for a
+    further `stabilityThreshold`, so the index is never late.
+  - `unlink` — `!currentHead` drops the event when the index already agrees the
+    item is gone.
+
+  `delete()` additionally now retires the head **before** it unlinks rather than
+  after. `awaitWriteFinish` debounces only `add`/`change`, so that face gets no
+  stability cushion between the disk mutation and the event it produces; ordering
+  the index update first makes the downstream check a total suppression rather
+  than a race against the poll callback. A failed `unlink` restores the head
+  before rethrowing, so the error path is unchanged.
+
+  No API or configuration change; the repository publishes strictly more of the
+  external edits it was always meant to report.
+
+  One pre-existing limit is now documented rather than altered: identity is judged
+  on what round-trips through the file, so a spec whose in-memory form does not
+  (a `Date`, which canonicalises to `{}` in memory but to an ISO string once
+  written and re-read) is republished as an external `update`. Such a spec already
+  fails `put().version === get().hash` independently of the watcher, and the
+  200 ms window never covered it either — it expired some 360 ms before the event
+  it would have had to catch.
+
+- ab07b53: fix(metadata-fs): register every written path with the watcher, so an item created while chokidar is still scanning is not invisible forever (#7282)
+
+  `FileSystemRepository`'s watcher could go **permanently blind to a single
+  item** — external edits to that file produced no `MetadataEvent` for the whole
+  life of the process, and nothing recovered short of a restart. The window is a
+  race between chokidar's asynchronous initial scan and the repository's own
+  first write, and both `start()` (which arms the watcher, after which the caller
+  may `put()` on the next tick) and `ensureRoot()` (which arms it in the middle
+  of the very first write, #7000) can open it.
+
+  Measured on chokidar 5 with this repository's options (`usePolling`,
+  `interval: 1000`):
+
+  1. chokidar reads `<root>/<type>/` and finds it EMPTY — the atomic `rename` in
+     `writeJsonAtomic` has not landed yet;
+  2. the rename lands, changing the directory's mtime;
+  3. chokidar calls `watchFile()` on that directory and libuv takes its polling
+     baseline stat, which already reflects step 2.
+
+  The directory's stat then never changes again, so no poll ever fires for it,
+  the directory is never re-read, the item file is never added to the watched
+  set, and no per-file watcher is created. `getWatched()` reports the type
+  directory as `[]` while the file sits in it, and neither `add` nor `change` is
+  ever emitted for that path.
+
+  The fix does not widen any timer. The only writer that can be inside that
+  window is the repository itself, so `put()` now tells the watcher explicitly
+  about the path it created instead of depending on a directory scan that may
+  never notice it. Registration is idempotent and emits nothing.
+
+  User-visible effect: `MetadataManager.subscribe()` (and every consumer of
+  `repo.watch()`) now reliably sees out-of-process edits — a hand edit, or a
+  `git checkout` bringing metadata JSON in — to items written earlier in the same
+  process. This was also the cause of four merge-queue ejections across three
+  PRs; the two time-based mitigations tried before it (a 20s/25s event deadline
+  and a wider pre-edit sleep) could not have worked, because the event was never
+  delivered rather than late.
+
+- 684ab22: fix(metadata-fs): the `FileSystemRepository` watcher now sees external edits in the production layout
+
+  `MetadataPlugin` attaches the repository at `<project>/.objectstack/metadata`, and the
+  watcher's `ignored` matcher was a bare dotfile regex. chokidar applies that matcher to the
+  watched root path itself, not only to entries found underneath it, so the `.objectstack`
+  segment of the root matched and the entire watch was inert — `getWatched()` returned `{}`
+  and no event ever fired. Hand edits, a `git checkout` that brings metadata JSON in, and any
+  other out-of-process writer under `.objectstack/metadata/` were invisible until the next
+  `start()`, even though `MetadataManager.setRepository()` is wired to those events and uses
+  them to invalidate the registry and the `list()` cache.
+
+  The matcher is now evaluated against the path _relative_ to the watch root, so dot segments
+  belonging to the root itself are never considered while dotfiles under the root — including
+  the repository's own `.objectstack/` bookkeeping subtree — stay ignored as before.
+
+- Updated dependencies [f5a4ef0]
+- Updated dependencies [2e836de]
+- Updated dependencies [121852d]
+- Updated dependencies [db0d53c]
+- Updated dependencies [c7e7900]
+- Updated dependencies [72c3c86]
+- Updated dependencies [3670cf9]
+- Updated dependencies [2d8dba3]
+- Updated dependencies [7372d46]
+- Updated dependencies [5e247fd]
+- Updated dependencies [1a53a02]
+- Updated dependencies [a954634]
+- Updated dependencies [fda61e4]
+- Updated dependencies [db48ad5]
+- Updated dependencies [65f184b]
+- Updated dependencies [51a587d]
+- Updated dependencies [c073b8c]
+- Updated dependencies [946a131]
+- Updated dependencies [ce92674]
+- Updated dependencies [3d4c545]
+- Updated dependencies [bb7cb41]
+  - @objectstack/metadata-core@17.0.0
+
 ## 17.0.0-rc.6
 
 ### Patch Changes

package/dist/index.cjs

@@ -235,6 +235,8 @@ var matchRefFilter = (ref, filter) => {
   return true;
 };
 var matchEvent = (evt, filter) => matchRefFilter(evt.ref, filter);
+var RESYNC_INTERVAL_MS = 2e3;
+var isEnoent = (err) => err?.code === "ENOENT";
 var FileSystemRepository = class {
   constructor(opts) {
     this.mutex = new KeyedMutex();
@@ -243,10 +245,18 @@ var FileSystemRepository = class {
     this.heads = /* @__PURE__ */ new Map();
     /** Next seq counter, hydrated from the log on `start()`. */
     this.nextSeq = 1;
-    /** Paths we wrote ourselves; suppress the resulting chokidar event. */
-    this.selfWrites = /* @__PURE__ */ new Set();
     this.watcher = null;
     this.started = false;
+    /** Pending reconciliation sweep (#9339). Chained, never overlapping. */
+    this.resyncTimer = null;
+    /** False before the watcher is armed and from `close()` onwards. */
+    this.resyncEnabled = false;
+    /**
+     * Sweep read faults already reported, keyed `CODE @ path`, so a standing
+     * fault is announced once rather than every 2s (AGENTS.md: say it once, at
+     * the first degradation). An entry is cleared when that path reads again.
+     */
+    this.resyncFaults = /* @__PURE__ */ new Set();
     this.org = opts.org;
     this.fsActor = opts.fsActor ?? "fs";
     this.disableWatch = opts.disableWatch ?? false;
@@ -293,6 +303,7 @@ var FileSystemRepository = class {
     if (this.started && !this.disableWatch && !this.watcher) this.startWatcher();
   }
   async close() {
+    this.stopResync();
     if (this.watcher) {
       await this.watcher.close();
       this.watcher = null;
@@ -410,12 +421,7 @@ var FileSystemRepository = class {
       const file = itemPath(this.layout, ref.type, ref.name);
       await this.ensureRoot();
       await import_promises2.default.mkdir(typeDir(this.layout, ref.type), { recursive: true });
-      this.selfWrites.add(file);
-      try {
-        await writeJsonAtomic(file, spec);
-      } finally {
-        setTimeout(() => this.selfWrites.delete(file), 200);
-      }
+      await writeJsonAtomic(file, spec);
       this.trackWrittenPath(file);
       this.heads.set(key, hash);
       const evt = {
@@ -457,13 +463,13 @@ var FileSystemRepository = class {
       }
       const file = itemPath(this.layout, ref.type, ref.name);
       await this.ensureRoot();
-      this.selfWrites.add(file);
+      this.heads.delete(key);
       try {
         if ((0, import_node_fs2.existsSync)(file)) await import_promises2.default.unlink(file);
-      } finally {
-        setTimeout(() => this.selfWrites.delete(file), 200);
+      } catch (err) {
+        if (currentHead !== null) this.heads.set(key, currentHead);
+        throw err;
       }
-      this.heads.delete(key);
       const seq = this.nextSeq++;
       const ts = this.now().toISOString();
       const evt = {
@@ -598,9 +604,278 @@ var FileSystemRepository = class {
     w.on("change", (p) => void this.handleFsChange(p, "change"));
     w.on("unlink", (p) => void this.handleFsChange(p, "unlink"));
     this.watcher = w;
+    this.startResync();
+  }
+  /**
+   * Publish the `delete` face of an externally-observed removal.
+   *
+   * Extracted from `handleFsChange` unchanged so the reconciliation sweep
+   * (#9339) can reuse it **verbatim** rather than growing a second copy of the
+   * event shape. The one-line invariant: the caller already holds the per-key
+   * mutex, and `!currentHead` is the content-keyed suppression that makes our
+   * own `delete()` a no-op here.
+   */
+  async publishExternalDelete(ref, key) {
+    const currentHead = this.heads.get(key) ?? null;
+    if (!currentHead) return;
+    this.heads.delete(key);
+    const seq = this.nextSeq++;
+    const evt = {
+      seq,
+      op: "delete",
+      ref: { ...ref, version: void 0 },
+      hash: null,
+      parentHash: currentHead,
+      actor: this.fsActor,
+      ts: this.now().toISOString(),
+      source: "fs"
+    };
+    await this.log.append(evt);
+    this.broker.publish(evt);
+  }
+  startResync() {
+    this.resyncEnabled = true;
+    this.scheduleResync();
+  }
+  stopResync() {
+    this.resyncEnabled = false;
+    if (this.resyncTimer) {
+      clearTimeout(this.resyncTimer);
+      this.resyncTimer = null;
+    }
+  }
+  /**
+   * Schedule the next sweep — chained, never `setInterval` (#9339).
+   *
+   * A chained timeout cannot stack: the next sweep is armed only once the
+   * previous one has finished, so a saturated runner degrades to *fewer*
+   * sweeps instead of a growing backlog of overlapping tree walks. The timer
+   * is `unref`ed because a backstop must never be the reason a process stays
+   * alive.
+   */
+  scheduleResync() {
+    if (!this.resyncEnabled || this.resyncTimer) return;
+    const timer = setTimeout(() => {
+      this.resyncTimer = null;
+      void this.resync().finally(() => this.scheduleResync());
+    }, RESYNC_INTERVAL_MS);
+    timer.unref?.();
+    this.resyncTimer = timer;
+  }
+  /**
+   * Announce a sweep read that could not run — the non-silence half of #8895's
+   * "discriminate or propagate".
+   *
+   * ## Why `error` and not `warn`
+   *
+   * AGENTS.md decides the level with one question: *after the degradation, does
+   * the system still look "normal" from the outside while something it claims
+   * is persisted has not actually landed?* Here it does. Nothing throws, the
+   * watcher stays armed, `getWatched()` stays populated, `start()` succeeded —
+   * and the repository's index quietly stops tracking what is on disk. That is
+   * the rule's second limb verbatim ("persisted state and runtime state
+   * disagree"), not the functional-degradation limb: no capability is visibly
+   * smaller, so nobody finds out by using the missing thing.
+   *
+   * The counter-argument — *this is only a backstop, the watcher is still the
+   * fast path* — is why the level is arguable, and it does not survive the
+   * failing errno. The sharp case is fd exhaustion: EMFILE/ENFILE break this
+   * `readdir` and chokidar's `fs.watchFile` polling **at the same time and for
+   * the same reason**, so the fast path is not an independent fallback under
+   * precisely the load that produces this fault. A backstop that is silently
+   * absent whenever it is most needed is a durability-shaped degradation.
+   *
+   * ⚠️ AGENTS.md also warns against over-applying `error`, and the discipline
+   * that answers it is the ledger, not a quieter level: an `error` owes the
+   * consequence and the fix, said **once** at the first degradation rather than
+   * once per failed read. A sweep runs every 2s forever, so an unlatched
+   * `console.error` here would be the mirror-image failure the same rule names.
+   *
+   * ⛔ It deliberately does NOT throw. This runs on a background timer; taking
+   * a process down on a transient EACCES would be worse than the bug. The bar
+   * met here is non-silence, not propagation.
+   *
+   * The channel is `console.error` because this class has no logger: nothing is
+   * injected through `FileSystemRepositoryOptions`, and widening that public
+   * surface to carry one is out of scope for this fix.
+   */
+  reportResyncFault(target, err) {
+    const code = err?.code ?? "UNKNOWN";
+    const key = `${code} @ ${target}`;
+    if (this.resyncFaults.has(key)) return;
+    this.resyncFaults.add(key);
+    console.error(
+      `[FileSystemRepository] metadata reconciliation sweep could not read ${target} (${code}). CONSEQUENCE: external edits under this path are no longer reconciled, so this repository's index and its watch() subscribers can drift from what is on disk while everything keeps reporting healthy. The chokidar watcher is not an independent fallback here \u2014 fd exhaustion degrades both. FIX: restore read access to the path; the sweep recovers by itself on the first successful read. Reported once per path and error code.`
+    );
+  }
+  /** Re-arm reporting for a path that reads again, so a recurrence is heard. */
+  clearResyncFault(target) {
+    if (this.resyncFaults.size === 0) return;
+    const suffix = ` @ ${target}`;
+    for (const key of this.resyncFaults) {
+      if (key.endsWith(suffix)) this.resyncFaults.delete(key);
+    }
   }
+  /**
+   * Content-keyed reconciliation sweep — the backstop that makes external-edit
+   * detection a guarantee rather than a single chance (#9339, #7282).
+   *
+   * ## Why the watcher alone cannot be the guarantee
+   *
+   * An external write to `<root>/<type>/<name>.json` reaches a subscriber only
+   * if chokidar notices it, and under `usePolling` it gets **exactly one**
+   * opportunity to do so: the write advances the type directory's mtime once,
+   * and chokidar re-reads a directory only when its stat *strictly advances*,
+   * so every later poll compares an unchanged stat and can never rediscover
+   * the file. Measured on #9339 with a fault-injection harness: with the one
+   * read suppressed, fifteen further poll ticks never find the new file, and a
+   * 20s deadline and a 200s deadline buy the same single attempt. That is the
+   * structural reason behind #7282's empirical finding that the event is
+   * "never delivered, not slow", and why widening the deadline (#7208) and
+   * lowering `interval` were both spent before they were tried.
+   *
+   * At least six independent one-shot gates sit on that single attempt,
+   * spanning three layers — the kernel timestamp (the directory mtime does not
+   * strictly advance), chokidar's readdir throttle and readdir snapshot, and
+   * chokidar's emit gates (`_throttle('add')`, a stale `_pendingWrites` entry,
+   * the `awaitWriteFinish` ENOENT early return). Each one produces a
+   * byte-identical observable: no event, ever, for that path.
+   *
+   * ## Why this shape, and not a narrower one
+   *
+   * ⚠️ The six are indistinguishable at the point of failure, so **any fix
+   * that has to name which gate fired is a fix for one member of a family** —
+   * which is exactly how #7282 was closed and exactly why it reopened. This
+   * sweep never asks. It compares what is on disk against `heads`, the index
+   * that already defines what this repository believes it holds, and publishes
+   * the divergence through the same `handleFsChange` the watcher feeds. It is
+   * therefore robust across all six *by construction*, and equally across a
+   * seventh nobody has found: the only property it relies on is that the bytes
+   * on disk stopped matching the index.
+   *
+   * `put()` is unaffected and keeps its direct registration (`trackWrittenPath`
+   * calls `watcher.add` and bypasses the whole chain, which is why the `put()`
+   * half of this family was already closed by #7336 and the external-write half
+   * was not).
+   *
+   * ## Cost, and why it is bounded
+   *
+   * One pass over `<root>/<type>/*.json` per sweep — the same walk `start()`
+   * already performs once — with no retry loop inside it and no work at all
+   * when nothing diverged. Sweeps are chained, so they cannot overlap; the
+   * timer is `unref`ed and dies with `close()`; and it is armed only alongside
+   * the watcher, so a `disableWatch` repository pays nothing.
+   *
+   * Discovery is by content, never by stat: a stat pre-filter would reintroduce
+   * a time key of exactly the kind this replaces.
+   */
+  async resync() {
+    const root = this.layout.root;
+    let entries = [];
+    try {
+      entries = await import_promises2.default.readdir(root, { withFileTypes: true });
+      this.clearResyncFault(root);
+    } catch (err) {
+      if (!isEnoent(err)) this.reportResyncFault(root, err);
+      return;
+    }
+    const onDisk = /* @__PURE__ */ new Set();
+    const unreadableTypes = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      const dir = import_node_path3.default.join(root, entry.name);
+      let files = [];
+      try {
+        files = await import_promises2.default.readdir(dir);
+        this.clearResyncFault(dir);
+      } catch (err) {
+        if (!isEnoent(err)) {
+          this.reportResyncFault(dir, err);
+          unreadableTypes.add(entry.name);
+        }
+        continue;
+      }
+      for (const file of files) {
+        if (!file.endsWith(".json") || file.startsWith(".")) continue;
+        const abs = import_node_path3.default.join(dir, file);
+        const parsed = parseItemPath(this.layout, abs);
+        if (!parsed) continue;
+        const ref = {
+          org: this.org,
+          type: parsed.type,
+          name: parsed.name
+        };
+        const key = (0, import_metadata_core.refKey)(ref);
+        onDisk.add(key);
+        const before = this.heads.get(key);
+        await this.handleFsChange(abs, "add");
+        if (this.heads.get(key) !== before) {
+          this.trackWrittenPath(abs);
+        }
+      }
+    }
+    for (const key of [...this.heads.keys()]) {
+      if (onDisk.has(key)) continue;
+      const ref = parseRefKey(key);
+      if (!ref) continue;
+      if (unreadableTypes.has(ref.type)) continue;
+      const file = itemPath(this.layout, ref.type, ref.name);
+      await this.mutex.run(key, async () => {
+        if ((0, import_node_fs2.existsSync)(file)) return;
+        await this.publishExternalDelete(ref, key);
+      });
+    }
+  }
+  /**
+   * Translate a watcher event into a `MetadataEvent`, or drop it.
+   *
+   * ## Self-writes are suppressed by content identity, never by a clock (#7335)
+   *
+   * This used to open with `if (this.selfWrites.has(absPath)) return;` — a
+   * `Set` that `put()`/`delete()` added the path to and a `setTimeout(…, 200)`
+   * cleared. That check discarded **every** event for a recently-written path
+   * without ever looking at what the watcher had actually observed, which is
+   * the whole defect: with `usePolling`, chokidar compares state once per
+   * `interval`, so our write and an external edit landing between two ticks
+   * are delivered as **one** event carrying the *external* content. Dropping
+   * it on a wall clock destroyed the only notification that edit would ever
+   * produce.
+   *
+   * Measured on `origin/main` @ `69fde55`, 40 iterations, poll phase
+   * randomised so the delivery lag samples `[0, interval)` uniformly:
+   *
+   *   delivery lag < 200ms  →  7 runs  →  external edit SWALLOWED, every time
+   *   delivery lag > 200ms  →  33 runs →  external edit delivered, every time
+   *
+   * A perfect split on the wall-clock boundary, and the reason earlier
+   * instrumentation saw 0/360: a *fixed* pre-edit sleep phase-locks the poll,
+   * pinning the lag (measured: 519–585ms across 25 runs) safely outside the
+   * window. Nothing about the window was rare — it was unsampled.
+   *
+   * What remains is the check that was already doing the real work one step
+   * down, and it needs no timer because it compares the content the watcher
+   * **read** against the index:
+   *
+   *   - `add`/`change` — `currentHead === hash` drops the event when the bytes
+   *     on disk are the bytes we last published. `put()` sets that head in the
+   *     same continuation as its `rename`, and `awaitWriteFinish` holds the
+   *     event for a further `stabilityThreshold`, so it is never late.
+   *   - `unlink` — `!currentHead` drops the event when the index already
+   *     agrees the item is gone. `delete()` retires the head *before* it
+   *     unlinks, precisely because this face gets no `awaitWriteFinish` delay.
+   *
+   * Both faces are pinned together in `test/self-write-suppression.test.ts`.
+   *
+   * Note the deliberate limit: identity is judged on what round-trips through
+   * the file, so a spec whose in-memory form does not (a `Date`, which
+   * canonicalises to `{}` in memory but to an ISO string once written and
+   * re-read) is republished as an external `update`. That predates this change
+   * and is independent of it — such a spec already fails `put().version ===
+   * get().hash`, and the 200ms window never covered it either, expiring some
+   * 360ms before the event it would have had to catch.
+   */
   async handleFsChange(absPath, kind) {
-    if (this.selfWrites.has(absPath)) return;
     const parsed = parseItemPath(this.layout, absPath);
     if (!parsed) return;
     const ref = {
@@ -611,22 +886,7 @@ var FileSystemRepository = class {
     const key = (0, import_metadata_core.refKey)(ref);
     await this.mutex.run(key, async () => {
       if (kind === "unlink") {
-        const currentHead2 = this.heads.get(key) ?? null;
-        if (!currentHead2) return;
-        this.heads.delete(key);
-        const seq2 = this.nextSeq++;
-        const evt2 = {
-          seq: seq2,
-          op: "delete",
-          ref: { ...ref, version: void 0 },
-          hash: null,
-          parentHash: currentHead2,
-          actor: this.fsActor,
-          ts: this.now().toISOString(),
-          source: "fs"
-        };
-        await this.log.append(evt2);
-        this.broker.publish(evt2);
+        await this.publishExternalDelete(ref, key);
         return;
       }
       const body = await readJson(absPath);