Name the script for what it does, now that it serves two providers

`link-polyfill.ts` handled one provider. It now handles two through a registry, one of which is not a polyfill, so both the filename and the `link:` verb said something false — and a name that is short but wrong misleads more than an opaque one would. It becomes `overlay-local-checkout.ts`, which is the operation: it copy-overlays a local package checkout into node_modules for development. "link" also implied a symlink, which is precisely what the script exists NOT to do — its own header spends a paragraph on why. No behaviour changed: same registry, same copy, same `--once`, same watch loop, same assertion. Both providers exercised afterwards, each reporting the singletons it must preserve — one package for the data layer, two for the indexing package, whose own checkout carries `file:` links and would otherwise smuggle in a second verifier. Seven references repaired by rewriting the sentence that carried them rather than swapping a path, across the script, `package.json`, `.env.example` and four doctrine leaves. No compatibility alias left behind: an old name kept "just in case" would restore exactly the ambiguity being removed.
The indexing package installs, and there is still one verifier
2026-08-17 12:35:28 +02:00 · 2026-08-17 12:30:25 +02:00 · 2026-08-17 12:26:21 +02:00
11 changed files with 195 additions and 125 deletions
@@ -45,6 +45,6 @@ NODE_ENV=

 # ── Outillage dev (facultatif) ─────────────────────────────────────────────
 # Override du chemin local du polyfill @ng-eventually/sdk pour `pnpm run
-# link:polyfill` (lien local réactif). Défaut = ../nextgraph/ng-eventually-js/packages/sdk.
+# overlay:polyfill` (overlay local réactif). Défaut = ../nextgraph/ng-eventually-js/packages/sdk.
 NG_EVENTUALLY_LOCAL=

@@ -2,7 +2,7 @@
 type: contract
 summary: The API @ng-helpers/indexing exposes to an application — creating an index, depositing references into it, curating it, and reading it back
 pulled_from: https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git/.project/concepts/indexing/indexing-layer/contract_indexing-layer.md
-pulled_version: aeb8c7d157178baf7a87d0b1fafaefb3382e7345
+pulled_version: 2ce21131575f66af09f28ee109ad712aa41173ae
 pulled_at: 2026-08-17
 ---

@@ -22,10 +22,13 @@ An application using this package must:

 - have a NextGraph session already open under the identity it wants to act as, and build the port from it — `polyfillPort({ sessionId })`, where `sessionId` is what `@ng-eventually/polyfill`'s own `init(…)` hands its callback;
 - reach a broker, since every operation here is a document read, a document write, or an inbox deposit;
+- **supply `@ng-eventually/polyfill` itself.** This package declares it a *peer*, not a dependency: the application names it among its own dependencies and decides which copy it gets. That copy must be the very one the application's own code calls, because everything this package does passes through it — and that package requires exactly one instance of itself in an application, for reasons its own contract states.
 - **hardcode the index's NURI in its own source.** Nothing marks a document as an index; the reference is what makes it one, and it is the only way anyone reaches it.

 One handle is one identity: the port carries a session and no call takes an identifier. Two users mean two handles.

+**Obtaining it.** This package is not published to npm, nor to any other package host, and it is not distributed as built output: its published entry point is TypeScript source, so whatever builds the application is what compiles it, and a toolchain that accepts only JavaScript cannot consume it as it stands. `@ng-eventually/polyfill` is distributed the same way. By which channel the source reaches a given application is agreed with that application rather than fixed here; what this contract fixes is the version you pin and what you must provide alongside it.
+
 ## Surface

 Full typed shape: the package's `types` entry, `@ng-helpers/indexing`. The load-bearing signatures:
@@ -144,6 +147,12 @@ What each level means here, in this package's own terms:

 **A tag says where it comes from.** A release cut on `main` carries a **full version** (`1.0.0`), and the three rules above govern what changes between two full versions. Work still on a branch carries a **pre-release** of the version it is heading for (`1.0.0-dev.3`), which sorts *below* that version by construction — so you can pin what exists today while the tag itself tells you the surface has not been released and may still move before it is. Between two pre-releases of the same version nothing is promised: re-pull and read this leaf again. When the branch lands, the full version appears alongside; the pre-release keeps resolving, so no reference you pinned is ever withdrawn from under you.

-`1.0.0` is a baseline, not a claim of maturity: it is the number that makes your pin mean something. Nothing was released before it. This engagement is cut on `main`, so `1.0.0` is what you pin, and your `usage_` leaf anchors `against:` on that exact string — `against: @ng-helpers/indexing@1.0.0`. Had you pinned a pre-release, `against:` would carry that string, pre-release suffix included.
+**The tag is bare — `v1.0.1` — because this repository publishes exactly one engagement**, so there is nothing for a prefix to disambiguate. Should a second one ever ship here, tags take the package name from that point on (`indexing/v…`), because a bare tag stops saying which surface it froze the day two versions move independently. Bare tags already laid stay valid as history.
+
+`1.0.0` was a baseline, not a claim of maturity: it was the number that made your pin mean something. Nothing was released before it. **It could not be installed, however**, and `1.0.1` supersedes it. `1.0.0` declared `@ng-eventually/polyfill` as a dependency resolved through a path that existed only in one working copy, so every attempt to install it from anywhere else failed outright — not on some operations but at the install itself, which is why no application ever ran it. `1.0.1` declares that package a peer, which the application supplies. Nothing exported moved, which is what makes this a patch and not a major: the only thing that changed for a caller is a requirement it could never have satisfied before, so there is no working arrangement for it to break.
+
+**`1.0.0` is superseded, not withdrawn.** The tag stays where it is and keeps resolving, because no pinned reference is ever taken away from under you — this contract's policy holds even for a version that never worked. Nothing forces an upgrade; it is simply that an installation pinned there cannot have succeeded, so there is nothing to migrate.
+
+This engagement is cut on `main`, so `1.0.1` is what you pin, and your `usage_` leaf anchors `against:` on that exact string — `against: @ng-helpers/indexing@1.0.1`. Had you pinned a pre-release, `against:` would carry that string, pre-release suffix included.

 There is no changelog file and no deprecation window: **the sections above are the release note.** A removal or a narrowing lands in `## Surface` and `## Guarantees` in the same version that ships it. Diff this leaf between two pulls — `## Guarantees` and `## Non-guarantees` before `## Surface`, because that is where a narrowing shows up first.
@@ -6,7 +6,7 @@ last_checked: 2026-08-16

 # Pitfall: refreshing the data-layer package never reaches a running dev server, not even across a rebuild

-`pnpm run link:polyfill` overlays the local package into `node_modules/@ng-eventually/polyfill/` as real files, and keeps them current. **That is all it does.** A `bun run dev` already running goes on serving the package it loaded at startup, however many times the overlay is rewritten underneath it, and however many rebuilds happen in between.
+`pnpm run overlay:polyfill` (or `overlay:indexing`, for the other provider) overlays the local checkout into `node_modules/<package>/` as real files, and keeps them current. **That is all it does.** A `bun run dev` already running goes on serving the package it loaded at startup, however many times the overlay is rewritten underneath it, and however many rebuilds happen in between.

 **VERIFIED, controlled sandbox test with this project's own bun.** A dependency resolving to copy A, overlaid with copy B: the running server still serves A at +3 s and +13 s after the overlay. An edit to **application source** then triggers a genuine rebuild — a new bundle hash confirms it — and the rebuilt bundle **still serves A**. Only a restart serves B. So the mechanism is not "the watcher never fires because `node_modules` is excluded" — a rebuild the watcher DOES trigger still carries the stale dependency forward; the server's resolution of that import is pinned at process start, and a rebuild does not re-resolve it.

@@ -18,7 +18,7 @@ VERIFIED 2026-08-16, and it cost about an hour. A defect had been fixed on the p

 The dev server had been running for **six days**. It predated the package rename and the whole migration, and it was serving code from before the fix. The browser was running a different application from the one under test.

-Two things made it hard to see. The failure mode is **silence** — nothing warns that the served code is old. And `scripts/link-polyfill.ts` explicitly promised the opposite, that `bun --hot` would reload the copied file live; that claim is now corrected in the script, but a reader who trusted it would rule out the true cause first, which is exactly what happened.
+Two things made it hard to see. The failure mode is **silence** — nothing warns that the served code is old. And `scripts/overlay-local-checkout.ts` explicitly promised the opposite, that `bun --hot` would reload the copied file live; that claim is now corrected in the script, but a reader who trusted it would rule out the true cause first, which is exactly what happened.

 ## The reflex to build

@@ -58,4 +58,4 @@ A `Dockerfile` exists (multi-stage Bun Alpine). **Installation goes through pnpm

 `bun run dev` = **`portless festipod bun --hot src/index.ts`** — it goes through the **`portless`** wrapper (an external port-management tool), not a bare `bun --hot`. HMR is active outside production.

-**Reactive local link to the SDK**: in production the `@ng-eventually/polyfill` dependency comes from Gitea (git+https, pinned by `pnpm-lock.yaml`). When the provider's package has to be exercised from a local checkout, `pnpm run link:polyfill` (script `scripts/link-polyfill.ts`) replaces `node_modules/@ng-eventually/polyfill` with a **real copy** of that checkout (location overridable with `NG_EVENTUALLY_LOCAL`) — **without** its own `node_modules/@ng-org` — and resyncs on every edit. Copying rather than symlinking is what keeps **a single `@ng-org/*` instance** installed: a symlink would drag in a second one and the SDK would stop working. To go back to the committed state: `pnpm install`.
+**Reactive local overlay for the SDK**: in production the `@ng-eventually/polyfill` dependency comes from Gitea (git+https, pinned by `pnpm-lock.yaml`), and `@ng-helpers/indexing` likewise. When a provider's package has to be exercised from a local checkout, `pnpm run overlay:polyfill` or `pnpm run overlay:indexing` (script `scripts/overlay-local-checkout.ts`, one provider per run) replaces `node_modules/<package>` with a **real copy** of that checkout (location overridable with `NG_EVENTUALLY_LOCAL` / `NG_HELPERS_LOCAL`) — **without** its own `node_modules/*` — and resyncs on every edit. Copying rather than symlinking is what keeps a **single instance** of every package the provider shares with Festipod installed (`@ng-org/*`, and for `indexing`, `@ng-eventually/polyfill` itself): a symlink would drag in a second one and the SDK would stop working. To go back to the committed state: `pnpm install`.
@@ -1,6 +1,6 @@
 ---
 type: knowledge
-summary: Stack components (Bun runtime/build/test, install through pnpm, React, NextGraph, Storybook, Cucumber, Tailwind-inside-the-build) and the real list of package.json scripts, quirks included (cucumber through node+tsx, link:polyfill for the reactive local link)
+summary: Stack components (Bun runtime/build/test, install through pnpm, React, NextGraph, Storybook, Cucumber, Tailwind-inside-the-build) and the real list of package.json scripts, quirks included (cucumber through node+tsx, overlay:polyfill/overlay:indexing for the reactive local overlay)
 ---

 # Stack & commands
@@ -33,7 +33,7 @@ summary: Stack components (Bun runtime/build/test, install through pnpm, React,
 | `steps:extract` | `bun scripts/extract-step-definitions.ts` |
 | `build:orm` | `rdf-orm build --input ./src/shared/shapes/shex --output ./src/shared/shapes/orm` |
 | `build:ng` | `bash scripts/build-ng-packages.sh` — (re)builds the NextGraph packages from a local source (optional tool) |
-| `link:polyfill` | `bun scripts/link-polyfill.ts` — **reactive** local link to `@ng-eventually/polyfill` (copy-overlay + watcher). Details in [[knowledge_deployment]]. |
+| `overlay:polyfill` / `overlay:indexing` | `bun scripts/overlay-local-checkout.ts <provider>` — **reactive** local overlay of a provider's checkout (`@ng-eventually/polyfill` or `@ng-helpers/indexing`; copy-overlay + watcher, `--once` for a single pass). Details in [[knowledge_deployment]]. |
 | `storybook` / `build-storybook` | Storybook dev (6006) / static build |

 ## Pitfalls
@@ -30,7 +30,7 @@ API details: [[knowledge_bun-apis]].

 **Dependencies are installed with `pnpm install`, not `bun install`.** Everything else stays on Bun: **runtime, build, test, scripts** (`bun run dev`, `bun build`, `bun test`, `bunx`). Only the installation step changes package manager.

-**Why.** The data SDK is installed from a Gitea repository as a **subdirectory** git dependency: `git+https://…/ng-eventually.git#main&path:/packages/polyfill`. pnpm (≥ 10.26) resolves that `#<ref>&path:/…` format and guarantees a **single** instance of `@ng-org/*`; `bun install` does not handle this workflow cleanly. The reference lockfile is therefore `pnpm-lock.yaml`, and the reactive local link goes through `pnpm run link:polyfill` (see [[knowledge_deployment]]).
+**Why.** The data SDK is installed from a Gitea repository as a **subdirectory** git dependency: `git+https://…/ng-eventually.git#main&path:/packages/polyfill`. pnpm (≥ 10.26) resolves that `#<ref>&path:/…` format and guarantees a **single** instance of `@ng-org/*`; `bun install` does not handle this workflow cleanly. The reference lockfile is therefore `pnpm-lock.yaml`, and the reactive local overlay goes through `pnpm run overlay:polyfill` (`overlay:indexing` for the other provider; see [[knowledge_deployment]]).

 **Practical consequence.** npm scripts that relied on `node_modules/.bin/*` may break (pnpm puts shell shims there, not JS entries) — call the package's actual JS entry (e.g. `node_modules/@cucumber/cucumber/bin/cucumber.js`) rather than the `.bin/` shim.

@@ -42,4 +42,4 @@ consume:
    pullFrom: https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git/.project/concepts/indexing/indexing-layer/contract_indexing-layer.md
    # Pinned on the TAG, never on a branch: a branch moves under us and the pin would stop
    # naming a state anyone can go back to. Re-pin to the next tag at each upgrade.
-    ref: v1.0.0
+    ref: v1.0.1
@@ -17,12 +17,14 @@
    "build:orm": "rdf-orm build --input ./src/shared/shapes/shex --output ./src/shared/shapes/orm",
    "validate": "bun scripts/validate.ts",
    "build:ng": "bash scripts/build-ng-packages.sh",
-    "link:polyfill": "bun scripts/link-polyfill.ts",
+    "overlay:polyfill": "bun scripts/overlay-local-checkout.ts polyfill",
+    "overlay:indexing": "bun scripts/overlay-local-checkout.ts indexing",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "dependencies": {
    "@ng-eventually/polyfill": "git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill",
+    "@ng-helpers/indexing": "git+https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git#v1.0.1",
    "@ng-org/alien-deepsignals": "0.1.2-alpha.11",
    "@ng-org/orm": "0.1.2-alpha.18",
    "@ng-org/shex-orm": "0.1.2-alpha.8",
@@ -11,6 +11,9 @@ importers:
      '@ng-eventually/polyfill':
        specifier: git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill
        version: git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill(@ng-org/alien-deepsignals@0.1.2-alpha.11(react@19.2.7))(@ng-org/orm@0.1.2-alpha.18(react@19.2.7))(@ng-org/shex-orm@0.1.2-alpha.8(typescript@6.0.3))(@ng-org/web@0.1.2-alpha.13)
+      '@ng-helpers/indexing':
+        specifier: git+https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git#v1.0.1
+        version: git+https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git#d615a72775cc9110de64b9b7fcc1d0d6c6d127ea(@ng-eventually/polyfill@git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill(@ng-org/alien-deepsignals@0.1.2-alpha.11(react@19.2.7))(@ng-org/orm@0.1.2-alpha.18(react@19.2.7))(@ng-org/shex-orm@0.1.2-alpha.8(typescript@6.0.3))(@ng-org/web@0.1.2-alpha.13))
      '@ng-org/alien-deepsignals':
        specifier: 0.1.2-alpha.11
        version: 0.1.2-alpha.11(react@19.2.7)
@@ -506,6 +509,12 @@ packages:
      '@ng-org/web':
        optional: true

+  '@ng-helpers/indexing@git+https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git#d615a72775cc9110de64b9b7fcc1d0d6c6d127ea':
+    resolution: {commit: d615a72775cc9110de64b9b7fcc1d0d6c6d127ea, repo: https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git, type: git}
+    version: 1.0.1
+    peerDependencies:
+      '@ng-eventually/polyfill': '*'
+
  '@ng-org/alien-deepsignals@0.1.2-alpha.11':
    resolution: {integrity: sha512-nPgqOrheAda/pW5FHgSb45SrSZWuyMyEVqO683ijEsVPpD105bngfh92PPfcRoRnFzGSoKXa3CfuqUHi2+qVIQ==}
    peerDependencies:
@@ -3734,6 +3743,10 @@ snapshots:
      '@ng-org/shex-orm': 0.1.2-alpha.8(typescript@6.0.3)
      '@ng-org/web': 0.1.2-alpha.13

+  '@ng-helpers/indexing@git+https://gitea.reconnexion.apps.gueraud.net/Sylvain/ng-helpers.git#d615a72775cc9110de64b9b7fcc1d0d6c6d127ea(@ng-eventually/polyfill@git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill(@ng-org/alien-deepsignals@0.1.2-alpha.11(react@19.2.7))(@ng-org/orm@0.1.2-alpha.18(react@19.2.7))(@ng-org/shex-orm@0.1.2-alpha.8(typescript@6.0.3))(@ng-org/web@0.1.2-alpha.13))':
+    dependencies:
+      '@ng-eventually/polyfill': git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill(@ng-org/alien-deepsignals@0.1.2-alpha.11(react@19.2.7))(@ng-org/orm@0.1.2-alpha.18(react@19.2.7))(@ng-org/shex-orm@0.1.2-alpha.8(typescript@6.0.3))(@ng-org/web@0.1.2-alpha.13)
+
  '@ng-org/alien-deepsignals@0.1.2-alpha.11(react@19.2.7)':
    dependencies:
      alien-signals: 2.0.8
@@ -1,114 +0,0 @@
-#!/usr/bin/env bun
-/**
- * link-polyfill.ts — Reactive local link for the @ng-eventually/polyfill polyfill.
- *
- * WHY a copy-overlay and not a symlink:
- *   The committed prod dependency installs @ng-eventually/polyfill from Gitea (git+https)
- *   into pnpm's store WITHOUT its own node_modules/@ng-org → @ng-org/web resolves up to
- *   Festipod → ONE @ng-org instance (one verifier). The local polyfill CHECKOUT, however,
- *   carries its own node_modules/@ng-org/* (symlinks into the ng-eventually-js monorepo
- *   store). Symlinking node_modules/@ng-eventually/polyfill to that checkout puts the
- *   checkout's @ng-org in the resolution path → a SECOND @ng-org instance → broken SDK
- *   (two verifiers). So we overlay a real directory that contains ONLY the polyfill's
- *   source (no node_modules) and keep it in sync by copying — @ng-org still resolves to
- *   Festipod, single instance preserved.
- *
- * WHAT IT DOES:
- *   1. Replaces node_modules/@ng-eventually/polyfill (the pnpm store symlink) with a real
- *      directory holding the local polyfill's package.json + src (NO node_modules).
- *   2. Asserts the single-instance invariant (same @ng-org/web realpath from Festipod and
- *      from the overlay) — aborts if it would break.
- *   3. Watches the local polyfill src and copies each change into the overlay.
- *
- * ⚠️ RESTART `bun run dev` AFTER THIS SCRIPT WRITES. The overlay lives inside
- * node_modules, which file watchers exclude by convention — so a running dev
- * server keeps serving the polyfill it loaded at startup, however many times
- * this script rewrites the files underneath it. VERIFIED the hard way: a dev
- * server six days old served pre-fix code while the overlay on disk was current,
- * and an hour went into hunting a defect that had already been fixed. Watching
- * copies the files; it does not make anything reload them.
- *
- * USAGE (reactive dev):
- *   Terminal 1:  pnpm run link:polyfill      # overlays local source, then watches
- *   Terminal 2:  bun run dev                 # portless festipod bun --hot src/index.ts
- *   Edit files under packages/polyfill/src → they land in node_modules → RESTART dev to pick them up.
- *
- *   pnpm run link:polyfill --once            # overlay + verify, no watch (CI / one-shot)
- *   Return to the committed git-installed dependency:  pnpm install
- *
- * Override the local checkout path with NG_EVENTUALLY_LOCAL=/path/to/packages/polyfill.
- */
-import { existsSync, lstatSync, mkdirSync, rmSync, cpSync, copyFileSync, realpathSync } from "node:fs";
-import { watch } from "node:fs";
-import { join, dirname } from "node:path";
-
-const FESTIPOD = realpathSync(join(import.meta.dir, ".."));
-const LOCAL =
-  process.env.NG_EVENTUALLY_LOCAL ??
-  "/home/sylvain/projects/nextgraph/ng-eventually-js/packages/polyfill";
-const TARGET = join(FESTIPOD, "node_modules", "@ng-eventually", "polyfill");
-const SRC_LOCAL = join(LOCAL, "src");
-const SRC_TARGET = join(TARGET, "src");
-const ONCE = process.argv.includes("--once");
-
-function fail(msg: string): never {
-  console.error(`✖ link:polyfill — ${msg}`);
-  process.exit(1);
-}
-
-if (!existsSync(join(LOCAL, "package.json"))) {
-  fail(`local polyfill not found at ${LOCAL} (set NG_EVENTUALLY_LOCAL to override)`);
-}
-
-// 1. Replace the pnpm store symlink with a real overlay dir (metadata + src, NO node_modules).
-console.log(`→ overlaying local polyfill: ${LOCAL}`);
-if (existsSync(TARGET) || lstatSync(TARGET, { throwIfNoEntry: false })) {
-  rmSync(TARGET, { recursive: true, force: true });
-}
-mkdirSync(TARGET, { recursive: true });
-for (const meta of ["package.json", "tsconfig.json", "README.md"]) {
-  const from = join(LOCAL, meta);
-  if (existsSync(from)) copyFileSync(from, join(TARGET, meta));
-}
-// Copy src fresh (NEVER a node_modules dir — that is what guarantees single @ng-org instance).
-cpSync(SRC_LOCAL, SRC_TARGET, { recursive: true });
-
-// 2. Assert the single-instance invariant.
-const fromFestipod = realpathSync(Bun.resolveSync("@ng-org/web", FESTIPOD));
-const overlayReal = realpathSync(TARGET);
-const fromPolyfill = realpathSync(Bun.resolveSync("@ng-org/web", overlayReal));
-console.log(`  @ng-org/web (Festipod): ${fromFestipod}`);
-console.log(`  @ng-org/web (overlay) : ${fromPolyfill}`);
-if (fromFestipod !== fromPolyfill) {
-  fail(
-    "single-instance invariant BROKEN — @ng-org/web resolves to two different realpaths.\n" +
-      "  The overlay must not contain its own node_modules/@ng-org. Aborting.",
-  );
-}
-console.log("✓ single @ng-org/web instance preserved");
-
-if (ONCE) {
-  console.log("✓ overlay ready (--once, not watching)");
-  process.exit(0);
-}
-
-// 3. Watch and copy on change. This keeps the overlay CURRENT; it does not make a
-// running dev server notice (node_modules is outside the watcher) — restart it.
-console.log(`👀 watching ${SRC_LOCAL} → ${SRC_TARGET} (Ctrl-C to stop)`);
-watch(SRC_LOCAL, { recursive: true }, (_event, filename) => {
-  if (!filename) return;
-  const from = join(SRC_LOCAL, filename);
-  const to = join(SRC_TARGET, filename);
-  try {
-    if (existsSync(from)) {
-      mkdirSync(dirname(to), { recursive: true });
-      copyFileSync(from, to);
-      console.log(`  ↻ ${filename}`);
-    } else if (existsSync(to)) {
-      rmSync(to, { force: true });
-      console.log(`  ✗ ${filename} (removed)`);
-    }
-  } catch (err) {
-    console.error(`  ! failed to sync ${filename}:`, err);
-  }
-});
@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+/**
+ * overlay-local-checkout.ts — Reactive local overlay of a data-layer PROVIDER's checkout
+ * into node_modules. One script, one provider per run; only the paths differ between them.
+ *
+ * PROVIDERS (first non-flag argument; defaults to `polyfill`):
+ *   polyfill  → node_modules/@ng-eventually/polyfill   override: NG_EVENTUALLY_LOCAL
+ *   indexing  → node_modules/@ng-helpers/indexing      override: NG_HELPERS_LOCAL
+ *
+ * WHY a copy-overlay and not a symlink (identical for every provider):
+ *   A committed prod dependency installs from Gitea (git+https) into pnpm's store WITHOUT
+ *   its own node_modules/@ng-org, so @ng-org/web resolves UP to Festipod → ONE @ng-org
+ *   instance (one verifier). A local CHECKOUT, however, carries its own node_modules/*
+ *   (links into that provider's own dev tree). Symlinking node_modules/<pkg> to the
+ *   checkout would put the checkout's copies in the resolution path → a SECOND @ng-org
+ *   (and, for `indexing`, a second @ng-eventually/polyfill) → broken SDK, two verifiers.
+ *   So we overlay a real directory containing ONLY the provider's source (no node_modules):
+ *   shared packages still resolve up to Festipod, single instance preserved.
+ *
+ * WHAT IT DOES:
+ *   1. Replaces node_modules/<package> (the pnpm store symlink) with a real directory
+ *      holding the local checkout's package.json + src (NO node_modules).
+ *   2. Asserts the single-instance invariant — every package this provider SHARES with
+ *      Festipod must resolve to the same realpath from Festipod and from the overlay —
+ *      and aborts if it would break.
+ *   3. Watches the local checkout's src and copies each change into the overlay.
+ *
+ * ⚠️ RESTART `bun run dev` AFTER THIS SCRIPT WRITES — a rebuild is NOT a substitute.
+ * A running dev server NEVER picks up a package refreshed inside node_modules, not even
+ * across a genuine rebuild: VERIFIED in a controlled test, an application-source edit
+ * produced a new bundle hash and the rebuilt bundle STILL carried the stale dependency.
+ * The server's resolution of that import is pinned at process start and a rebuild does not
+ * re-resolve it. Only restarting serves the fresh copy, and nothing warns you — a stale
+ * server looks exactly like a current one. See
+ * .project/concepts/tech-stack/caveat_polyfill-overlay-needs-a-dev-restart.md, which cost
+ * an hour to learn. Watching copies the files; it does not make anything reload them.
+ *
+ * USAGE (reactive dev):
+ *   Terminal 1:  pnpm run overlay:polyfill    # or: pnpm run overlay:indexing
+ *   Terminal 2:  bun run dev                  # portless festipod bun --hot src/index.ts
+ *   Edit the checkout's src → it lands in node_modules → RESTART dev to pick it up.
+ *
+ *   pnpm run overlay:indexing --once          # overlay + verify, no watch (CI / one-shot)
+ *   Return to the committed git-installed dependencies:  pnpm install
+ */
+import { existsSync, lstatSync, mkdirSync, rmSync, cpSync, copyFileSync, realpathSync } from "node:fs";
+import { watch } from "node:fs";
+import { join, dirname } from "node:path";
+
+interface Provider {
+  /** Package as installed, e.g. "@ng-eventually/polyfill" — also its node_modules path. */
+  readonly packageName: string;
+  /** Local checkout used when the env override is unset. */
+  readonly defaultLocal: string;
+  /** Env var overriding the local checkout path. */
+  readonly envOverride: string;
+  /**
+   * Packages this provider SHARES with Festipod and that must stay single-instance.
+   * Each is resolved from Festipod and from the overlay; the realpaths must match.
+   */
+  readonly singletons: readonly string[];
+}
+
+const PROVIDERS: Record<string, Provider> = {
+  polyfill: {
+    packageName: "@ng-eventually/polyfill",
+    defaultLocal: "/home/sylvain/projects/nextgraph/ng-eventually-js/packages/polyfill",
+    envOverride: "NG_EVENTUALLY_LOCAL",
+    singletons: ["@ng-org/web"],
+  },
+  indexing: {
+    packageName: "@ng-helpers/indexing",
+    defaultLocal: "/home/sylvain/projects/nextgraph/ng-helpers",
+    envOverride: "NG_HELPERS_LOCAL",
+    // Consumes the polyfill, so BOTH it and the verifier underneath must stay single.
+    singletons: ["@ng-eventually/polyfill", "@ng-org/web"],
+  },
+};
+
+const FESTIPOD = realpathSync(join(import.meta.dir, ".."));
+const args = process.argv.slice(2);
+const ONCE = args.includes("--once");
+const KEY = args.find((a) => !a.startsWith("-")) ?? "polyfill";
+
+function fail(msg: string): never {
+  console.error(`✖ overlay:${KEY} — ${msg}`);
+  process.exit(1);
+}
+
+const provider = PROVIDERS[KEY];
+if (!provider) {
+  fail(`unknown provider "${KEY}" — expected one of: ${Object.keys(PROVIDERS).join(", ")}`);
+}
+
+const LOCAL = process.env[provider.envOverride] ?? provider.defaultLocal;
+const TARGET = join(FESTIPOD, "node_modules", ...provider.packageName.split("/"));
+const SRC_LOCAL = join(LOCAL, "src");
+const SRC_TARGET = join(TARGET, "src");
+
+if (!existsSync(join(LOCAL, "package.json"))) {
+  fail(`local checkout not found at ${LOCAL} (set ${provider.envOverride} to override)`);
+}
+if (!existsSync(SRC_LOCAL)) {
+  fail(`local checkout has no src/ at ${SRC_LOCAL}`);
+}
+
+// 1. Replace the pnpm store symlink with a real overlay dir (metadata + src, NO node_modules).
+console.log(`→ overlaying local ${provider.packageName}: ${LOCAL}`);
+if (existsSync(TARGET) || lstatSync(TARGET, { throwIfNoEntry: false })) {
+  rmSync(TARGET, { recursive: true, force: true });
+}
+mkdirSync(TARGET, { recursive: true });
+for (const meta of ["package.json", "tsconfig.json", "README.md"]) {
+  const from = join(LOCAL, meta);
+  if (existsSync(from)) copyFileSync(from, join(TARGET, meta));
+}
+// Copy src fresh (NEVER a node_modules dir — that is what guarantees single instances).
+cpSync(SRC_LOCAL, SRC_TARGET, { recursive: true });
+
+// 2. Assert the single-instance invariant for every package shared with Festipod.
+const overlayReal = realpathSync(TARGET);
+for (const spec of provider.singletons) {
+  const fromFestipod = realpathSync(Bun.resolveSync(spec, FESTIPOD));
+  const fromOverlay = realpathSync(Bun.resolveSync(spec, overlayReal));
+  console.log(`  ${spec} (Festipod): ${fromFestipod}`);
+  console.log(`  ${spec} (overlay) : ${fromOverlay}`);
+  if (fromFestipod !== fromOverlay) {
+    fail(
+      `single-instance invariant BROKEN — ${spec} resolves to two different realpaths.\n` +
+        "  The overlay must not contain its own node_modules. Aborting.",
+    );
+  }
+}
+console.log(`✓ single instance preserved for: ${provider.singletons.join(", ")}`);
+
+if (ONCE) {
+  console.log("✓ overlay ready (--once, not watching)");
+  process.exit(0);
+}
+
+// 3. Watch and copy on change. This keeps the overlay CURRENT; it does NOT make a running
+// dev server notice — not even across a rebuild (see the header). Restart it.
+console.log(`👀 watching ${SRC_LOCAL} → ${SRC_TARGET} (Ctrl-C to stop)`);
+watch(SRC_LOCAL, { recursive: true }, (_event, filename) => {
+  if (!filename) return;
+  const from = join(SRC_LOCAL, filename);
+  const to = join(SRC_TARGET, filename);
+  try {
+    if (existsSync(from)) {
+      mkdirSync(dirname(to), { recursive: true });
+      copyFileSync(from, to);
+      console.log(`  ↻ ${filename}`);
+    } else if (existsSync(to)) {
+      rmSync(to, { force: true });
+      console.log(`  ✗ ${filename} (removed)`);
+    }
+  } catch (err) {
+    console.error(`  ! failed to sync ${filename}:`, err);
+  }
+});