@objectstack/metadata-fs 17.0.0-rc.5 → 17.0.0

package/CHANGELOG.md

@@ -1,5 +1,328 @@
 # @objectstack/metadata-fs
 
+## 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
+
+- 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()`.
+
+- 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 [121852d]
+- Updated dependencies [5e247fd]
+- Updated dependencies [1a53a02]
+- Updated dependencies [a954634]
+- Updated dependencies [3d4c545]
+- Updated dependencies [bb7cb41]
+  - @objectstack/metadata-core@17.0.0-rc.6
+
 ## 17.0.0-rc.5
 
 ### Patch Changes

package/README.md

@@ -35,7 +35,7 @@ const repo = new FileSystemRepository({
   root: './metadata',
   org: 'system',
 });
-await repo.start();          // scan + open watcher
+await repo.start();          // scan + open watcher — creates nothing on disk
 
 const view = await repo.get({
   org: 'system',
@@ -47,4 +47,19 @@ for await (const evt of repo.watch({})) {
 }
 ```
 
+## Root creation is a write, not an attach
+
+`start()` never creates `<root>`. Attaching a repository whose root does not
+exist is legal: reads answer as if the repository were empty, and the root —
+together with `<root>/.objectstack/.log/` — appears on the **first write**
+(`put` / `delete`). This is what keeps a read-only boot, such as the dry run
+`os migrate plan` performs on a project that has never been started, from
+leaving a directory skeleton behind (#7000, the filesystem half of #6743).
+
+One consequence worth knowing: 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 exist yet. A root brought into existence by a third
+party while the process runs, without this repository ever writing, is
+therefore not picked up until the next `start()`.
+
 See ADR-0008 (incl. §0 amendment) and the `metadata-branch-removal` changeset.

package/dist/index.cjs

@@ -243,8 +243,6 @@ 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;
     this.org = opts.org;
@@ -255,15 +253,42 @@ var FileSystemRepository = class {
     this.log = new JsonlLog(logFile(this.layout));
   }
   // ── Lifecycle ───────────────────────────────────────────────────────
+  /**
+   * Attach the repository. **Creates nothing on disk** (#7000).
+   *
+   * Attaching is not a write. `start()` used to `mkdir` both the root and
+   * `<root>/.objectstack/.log` unconditionally, which meant every read-only
+   * boot that merely attaches a repository left a skeleton behind — most
+   * visibly `os migrate plan`, a declared dry run, on a project that has
+   * never been started. That is the same property #6743 ruled on for
+   * `.objectstack/data/`: a dry run leaves nothing behind, and the existence
+   * of `.objectstack/` has to stay a usable "this project has been started"
+   * signal.
+   *
+   * Every read path below already treats a missing root as an empty
+   * repository (`scanHeads` swallows ENOENT, `JsonlLog` guards on
+   * `existsSync`, `get` guards on `existsSync`), so the root is materialized
+   * by `ensureRoot()` on the first write instead.
+   */
   async start() {
     if (this.started) return;
     this.started = true;
-    await import_promises2.default.mkdir(this.layout.root, { recursive: true });
-    await import_promises2.default.mkdir(logDir(this.layout), { recursive: true });
     await this.scanHeads();
     const highest = await this.log.highestSeq();
     this.nextSeq = highest + 1;
-    if (!this.disableWatch) this.startWatcher();
+    if (!this.disableWatch && (0, import_node_fs2.existsSync)(this.layout.root)) this.startWatcher();
+  }
+  /**
+   * Bring the repository root into existence. Called by every write path
+   * immediately before it touches the disk — `start()` deliberately does not
+   * create it (#7000), so this is the single seam where the root appears.
+   *
+   * It is also where a watcher that `start()` could not arm (missing root)
+   * gets armed, so "external edits are detected" survives the change.
+   */
+  async ensureRoot() {
+    await import_promises2.default.mkdir(this.layout.root, { recursive: true });
+    if (this.started && !this.disableWatch && !this.watcher) this.startWatcher();
   }
   async close() {
     if (this.watcher) {
@@ -381,13 +406,10 @@ var FileSystemRepository = class {
       const seq = this.nextSeq++;
       const ts = this.now().toISOString();
       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 = {
         seq,
@@ -427,13 +449,14 @@ var FileSystemRepository = class {
         throw new import_metadata_core.ConflictError(ref, opts.parentVersion, currentHead);
       }
       const file = itemPath(this.layout, ref.type, ref.name);
-      this.selfWrites.add(file);
+      await this.ensureRoot();
+      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 = {
@@ -502,10 +525,58 @@ var FileSystemRepository = class {
     }
     return last;
   }
+  /**
+   * Register a path this repository just wrote with the watcher (#7282).
+   *
+   * chokidar's initial scan is asynchronous, and every write path here can be
+   * running **while it is still walking the tree** — `start()` arms the watcher
+   * and the caller may `put()` on the next tick, and `ensureRoot()` arms it in
+   * the middle of the very first write. With `usePolling` that combination has
+   * a permanently-blinding interleaving, measured on chokidar 5 with this
+   * repository's own options:
+   *
+   *   1. chokidar reads `<root>/<type>/` and finds it EMPTY — the atomic
+   *      `rename` in `writeJsonAtomic` has not landed yet.
+   *   2. the rename lands; the directory's mtime changes.
+   *   3. chokidar calls `watchFile()` on that directory, and libuv takes its
+   *      polling baseline stat — which already reflects step 2.
+   *
+   * From then on the directory's stat never changes again, so no poll ever
+   * fires for it, `_handleRead` never re-runs, the item file is never added to
+   * the watched set, and no per-file watcher is ever created. chokidar emits
+   * neither `add` nor `change` for that path **for the life of the process** —
+   * `getWatched()` reports the type directory as `[]` forever while the file
+   * sits in it. That is the whole of #7282: the four merge-queue ejections all
+   * waited out their deadlines (20s, then 25541ms against 25s) on an event that
+   * was never going to be delivered, which is why widening the deadline and
+   * widening the pre-edit sleep both changed nothing, and why lowering
+   * `interval` would change nothing either — a shorter poll re-compares against
+   * the same unchanged directory stat.
+   *
+   * The window is exactly "files that exist at baseline time but were absent
+   * from the snapshot read a moment earlier", and the only writer that can be
+   * inside it is us. So we close it at the source: tell the watcher explicitly
+   * about every path we create, instead of hoping its scan happened to see it.
+   *
+   * `add()` is idempotent here — `_handleFile` returns early when the parent
+   * directory already tracks the basename — and it emits nothing, because
+   * chokidar treats an explicit `add()` as an initial add and `ignoreInitial`
+   * is set. Its effect is the one we need: `_watchWithNodeFs` registers the
+   * basename with the parent directory (without which chokidar drops `change`
+   * events for the file) and starts the per-file poll.
+   */
+  trackWrittenPath(file) {
+    const w = this.watcher;
+    if (!w || w.closed) return;
+    w.add(file);
+  }
   startWatcher() {
-    const w = import_chokidar.default.watch(this.layout.root, {
-      ignored: [/(^|[\\/])\../],
-      // skip dotfiles incl. .objectstack
+    const root = this.layout.root;
+    const w = import_chokidar.default.watch(root, {
+      // Skip dotfiles under the root — including the repository's own
+      // `.objectstack/` bookkeeping subtree — matched on the path RELATIVE
+      // to the watch root (#7150). See `isIgnoredWatchPath`.
+      ignored: (p) => isIgnoredWatchPath(root, p),
       ignoreInitial: true,
       depth: 2,
       awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 20 },
@@ -521,8 +592,55 @@ var FileSystemRepository = class {
     w.on("unlink", (p) => void this.handleFsChange(p, "unlink"));
     this.watcher = w;
   }
+  /**
+   * 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 = {
@@ -573,6 +691,11 @@ var FileSystemRepository = class {
     });
   }
 };
+function isIgnoredWatchPath(root, absPath) {
+  const rel = import_node_path3.default.relative(root, absPath);
+  if (rel === "" || rel.startsWith("..")) return false;
+  return rel.split(/[\\/]/).some((segment) => segment.startsWith("."));
+}
 async function readJson(file) {
   try {
     const text = await import_promises2.default.readFile(file, "utf8");