The data layer is a real external dependency, pinned to a commit

`package.json` named `#main`, where the renamed `packages/polyfill` does not
exist, and `pnpm-lock.yaml` still named the package as it was called in July.
`pnpm install --frozen-lockfile` -- the Dockerfile's install step -- refused on
exactly that mismatch, so the image could not build at all. Both now name the
commit the branch was pushed at, and the frozen install passes.

The dependency is now genuinely external: installed from git into pnpm's store,
with no local overlay anywhere in the resolution. The invariant that justified
the overlay in the first place holds -- `@ng-org/web` resolves to the same
realpath from the application and from the installed package, so one instance
and one verifier. A git-installed package does not carry its own `@ng-org`,
where a symlink to the checkout would have.

`.project/contracts.yaml` names the same commit as the dependency, so the surface
the app is coded against and the package it installs designate one state, and a
drift between them becomes visible instead of silent. A tag will replace the
commit once the provider settles a convention; the invariant is that the two
agree, whatever the ref.

Deployment doctrine now carries what a deployer needs and did not have: the
pinning discipline, that the frozen install only verifies, the wallet arriving
through the environment with its one-directional precedence and its loud failure
on a malformed value, that neither the wallet nor its password is a secret, that
tailwindcss is a devDependency the server needs at serve time, and that a
deployed origin's embedding in the broker's iframe is covered by no test.

Nothing has been deployed in this shape yet, and the doctrine says so.

.env.example

@@ -18,10 +18,19 @@
 FESTIPOD_SHARED_WALLET_PASSWORD=
 
 # Chemin vers le fichier portefeuille partagé (.ngw), absolu ou relatif à la
-# racine. Servi en téléchargement à /shared-wallet.ngw — par le build de l'app,
-# et par le serveur du harness pendant les tests.
+# racine. Servi en téléchargement à /shared-wallet.ngw. C'est la forme du DEV
+# LOCAL et du harness de TESTS : le fichier vit sur le disque de la machine.
 FESTIPOD_SHARED_WALLET_FILE=/chemin/absolu/vers/festipod-wallet.ngw
 
+# Contenu du portefeuille partagé (.ngw), encodé en base64 — deuxième source
+# pour le même fichier. C'est la forme des DÉPLOIEMENTS (conteneur) : *.ngw est
+# gitignoré, donc `COPY . .` n'en embarque aucun et rien n'en monte un ; le
+# fichier n'étant pas un secret (l'app le sert à quiconque ouvre l'app), il
+# voyage comme une variable de config. `FESTIPOD_SHARED_WALLET_FILE` est
+# prioritaire quand les deux sont renseignées — voir le commentaire dans
+# src/index.ts. Générer la valeur avec, p.ex., `base64 -w0 festipod-wallet.ngw`.
+FESTIPOD_SHARED_WALLET_FILE_BASE64=
+
 # ── Seed automatique (opt-in) ──────────────────────────────────────────────
 # Non vide => l'app amorce des données de démo dans un wallet VIDE au 1er login.
 # OFF par défaut : laisser vide en usage normal.

.project/concepts/tech-stack/_overview.md

@@ -3,7 +3,7 @@ type: _overview
 summary: Stack and tooling — Bun-first (runtime, bundler, native APIs), build pipeline, and the project's commands
 triggers:
   keywords: [bun, bunx, build, bundler, vite, webpack, jest, npm, storybook, "bun.serve", hmr, tailwind, package.json]
-  paths: ["build.ts", "package.json", "bunfig.toml", "tsconfig.json", "src/index.ts", "src/index.html", ".storybook/**", "scripts/**"]
+  paths: ["build.ts", "package.json", "pnpm-lock.yaml", "Dockerfile", ".env.example", "bunfig.toml", "tsconfig.json", "src/index.ts", "src/index.html", ".storybook/**", "scripts/**"]
 ---
 
 # Tech stack

.project/concepts/tech-stack/knowledge_deployment.md

@@ -1,11 +1,13 @@
 ---
 type: knowledge
-summary: Deployment — multi-stage Bun Alpine Dockerfile; install through pnpm (git+node inside the image) but bun at runtime; runs `bun run start` from src/ (not dist/), EXPOSE 3000, env PORT/NODE_ENV; no CI/CD committed; dev goes through the portless wrapper
-last_checked: 2026-07-14
+summary: Deployment — multi-stage Bun Alpine Dockerfile; install through pnpm (git+node inside the image) but bun at runtime; runs `bun run start` from src/ (not dist/), EXPOSE 3000; the data-layer git dependency must be pinned to a tag/commit and match `contracts.yaml`'s ref; the shared wallet reaches the container through env vars, not a mount, because it isn't a secret; no CI/CD committed; dev goes through the portless wrapper
+last_checked: 2026-08-17
 ---
 
 # Deployment & infra
 
+Nothing has actually been deployed with this shape yet — this leaf states what a deployment needs to line up, verified against the code and manifests, not a procedure that has been run end to end.
+
 ## Dockerfile
 
 A `Dockerfile` exists (multi-stage Bun Alpine). **Installation goes through pnpm, but runtime/build/test stay on bun** (see [[knowledge_stack-and-commands]]):
@@ -14,16 +16,41 @@ A `Dockerfile` exists (multi-stage Bun Alpine). **Installation goes through pnpm
 
 **`bun` peer pitfall**: `bun-plugin-tailwind` declares `bun` as a peerDependency → pnpm materializes the npm `bun` package and **creates a `node_modules/.bin/bun` shim** that shadows the `bun` from the PATH under `bun run`/`pnpm run`. Its postinstall is ignored by default → broken shim → `bun run start` fails. Fixed by approving the build: `pnpm.onlyBuiltDependencies: ["bun"]` in `package.json` (the postinstall then downloads the real binary). Without that, the whole pnpm migration breaks startup.
 
+**`tailwindcss` is a devDependency the server needs at serve time, not only at build time.** `bunfig.toml`'s `[serve.static] plugins = ["bun-plugin-tailwind"]` applies to `Bun.serve`'s HTML-import serving — the path both `bun run dev` and `bun run start` use ([[knowledge_build-pipeline]]) — not only to `bun run build.ts`. The install stage must therefore keep installing devDependencies: no `--prod`, and `NODE_ENV` stays unset until the `release` stage, after `pnpm install --frozen-lockfile` has already run. Moving `ENV NODE_ENV=production` earlier, or adding `--prod` to the install, would drop `tailwindcss` and break every serve, dev included.
+
 **Production runs the sources, and this is the normal path, not a quirk**: `start` = `NODE_ENV=production bun src/index.ts` → the container **runs the TypeScript directly** (Bun transpiles on the fly). `bun run build` (→ `dist/`) is on **no** path at all — nothing serves that directory, in this container or anywhere else; serving it would mean changing the entrypoint. Consequence for the code: in this deployment `NODE_ENV=production` says *how* the sources run, never *that they were bundled* — [[knowledge_build-pipeline]].
 
+## The data-layer git dependency must stay pinned, and the pin must be checkable
+
+`package.json` resolves `@ng-eventually/polyfill` from `git+https://…/ng-eventually.git#<ref>&path:/packages/polyfill` — the `path:` selector is what lets a subdirectory of the provider's repo be installed as the package. Two things follow, ahead of any real deployment:
+
+- **`<ref>` must name a tag or a commit, never a branch.** A branch moves: the image was built against whatever commit the branch pointed to at build time, and the branch head can advance afterwards without the image changing — so "the same deployment" silently starts drifting from what it was actually built against. The tag-naming convention itself is the provider's call and is not settled yet; the requirement is only that the ref be immutable.
+- **The same `<ref>` should also be the `ref:` of the `polyfill-surface` entry in `.project/contracts.yaml`.** That manifest pins the version of [[contract_polyfill-surface]] the app is coded against; when it names the same ref as `package.json`'s specifier, the contract the app was written for and the package actually installed name the same state, and a difference between the two becomes visible instead of silent. Both now name the **same commit**, which is the state a deployment can ship on. A tag is expected to replace that commit once the provider settles a naming convention — a one-line change in each of the two files, with the invariant unchanged: whatever the ref is, the two must agree.
+
+**`pnpm install --frozen-lockfile` (the Dockerfile's install step) never regenerates — it only verifies.** `pnpm-lock.yaml` must already reproduce `package.json` exactly, so any change to the git specifier (ref, path, or package name) needs `pnpm install` run and the regenerated lockfile committed *before* the image can build; skipping that step fails the build outright, not silently. This has bitten once: the lockfile still named the old package and path after the dependency was renamed, so `--frozen-lockfile` refused and the image could not build until it was regenerated.
+
 ## CI/CD
 
 **No** pipeline is committed (`.github/workflows/` absent, no Coolify config in the repo). A knowingly accepted blind spot. To host the Bun app, the `coolify-hosting` skill applies.
 
+Also untested: whether a **deployed origin** can be embedded in the hosted broker's iframe at all — the SDK's identity flow runs the app inside that iframe (see [[contract_polyfill-surface]]'s `ensureIdentity()` barrier). [[caveat_firefox-lna-blocks-broker-iframe]] records the one failure mode known here, and it is a **local-dev-origin** one (`127.0.0.1` blocked by Firefox LNA); no scenario in this repo exercises a real deployed origin against the broker's embedding policy.
+
 ## Environment variables
 
 - `PORT` (default 3000), `NODE_ENV` (enables/disables HMR and the dev auto-seed — see concept `data-layer`).
-- No `.env*` is committed (`.env` is gitignored). No secret management in the repo.
+- No `.env*` is committed (`.env` is gitignored).
+
+### The shared wallet: config, not a secret, not a mount
+
+[[contract_polyfill-surface]] requires the app to serve a wallet file (`.ngw`) and pass its URL and password to `configure` as `sharedWallet: { fileUrl, password }`. `*.ngw` is gitignored and no deployment mounts one, so `src/index.ts` serves it from environment variables, read fresh on every request:
+
+- `FESTIPOD_SHARED_WALLET_PASSWORD` — the password, always read this way (dev, tests, and deployments alike).
+- `FESTIPOD_SHARED_WALLET_FILE` — a filesystem path to the `.ngw` file. The form local dev and the test harness use: the file sits on the machine's disk.
+- `FESTIPOD_SHARED_WALLET_FILE_BASE64` — the file's bytes, base64-encoded. The form a deployment uses instead, since nothing mounts a `.ngw` into the container.
+
+**Precedence is one-directional and does not fall through.** `FESTIPOD_SHARED_WALLET_FILE` wins whenever it is set, *even if the path turns out unreadable* — an unreadable path answers 404, it does **not** fall back to the base64 form. A deployment must set exactly one of the two; leaving a leftover `FESTIPOD_SHARED_WALLET_FILE` pointing nowhere in a deployment environment silently 404s instead of serving the base64 value that was actually intended. A malformed base64 value answers 500 naming the variable — never a 404, which would be indistinguishable from "not configured at all".
+
+**Neither the password nor the wallet file is a secret**, and that is deliberate, not an oversight: the contract has the app hand both to every user who opens it — that is how a first-time device without its own wallet onboards. Provisioning them as protected/mounted storage would guard something the app already gives away by design; they travel as plain configuration instead, and a new host needs only its environment variables, nothing to mount.
 
 ## Dev
 

.project/contracts.yaml

@@ -19,4 +19,4 @@ consume:
     # The contract is published from the branch that carries it while that branch is still
     # in flight; it moves to `main` once the provider lands it there. Flip this line then,
     # and re-pull — the stamp records which commit the local copy actually came from.
-    ref: caps-p1a-and-virtual-user-boundary
+    ref: a8d53010c227462cc9317e9be499c2100ca8d533

Dockerfile

@@ -3,7 +3,7 @@ FROM oven/bun:1-alpine AS base
 WORKDIR /app
 
 # Install dependencies with pnpm.
-# - git: the @ng-eventually/client polyfill is a git+https (public Gitea) dependency → no auth.
+# - git: @ng-eventually/polyfill is a git+https (public Gitea) dependency → no auth.
 # - nodejs + npm: pnpm is a Node CLI; we pin the exact pnpm version via `npm i -g`
 #   (Alpine's nodejs package does not bundle corepack).
 # The `bun` npm peer (pulled by bun-plugin-tailwind) is approved to build in package.json

package.json

@@ -22,7 +22,7 @@
     "build-storybook": "storybook build"
   },
   "dependencies": {
-    "@ng-eventually/polyfill": "git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#main&path:/packages/polyfill",
+    "@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",
     "@ng-org/orm": "0.1.2-alpha.18",
     "@ng-org/shex-orm": "0.1.2-alpha.8",

pnpm-lock.yaml

@@ -8,9 +8,9 @@ importers:
 
   .:
     dependencies:
-      '@ng-eventually/client':
-        specifier: git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#main&path:/packages/client
-        version: git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#1f0bae461e461c9fddd7215f972418acb2b4a989&path:/packages/client(@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-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-org/alien-deepsignals':
         specifier: 0.1.2-alpha.11
         version: 0.1.2-alpha.11(react@19.2.7)
@@ -488,8 +488,8 @@ packages:
       '@emnapi/core': ^1.7.1
       '@emnapi/runtime': ^1.7.1
 
-  '@ng-eventually/client@git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#1f0bae461e461c9fddd7215f972418acb2b4a989&path:/packages/client':
-    resolution: {commit: 1f0bae461e461c9fddd7215f972418acb2b4a989, path: /packages/client, repo: https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git, type: git}
+  '@ng-eventually/polyfill@git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#a8d53010c227462cc9317e9be499c2100ca8d533&path:/packages/polyfill':
+    resolution: {commit: a8d53010c227462cc9317e9be499c2100ca8d533, path: /packages/polyfill, repo: https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git, type: git}
     version: 0.0.0
     peerDependencies:
       '@ng-org/alien-deepsignals': '*'
@@ -3727,7 +3727,7 @@ snapshots:
       '@tybys/wasm-util': 0.10.3
     optional: true
 
-  '@ng-eventually/client@git+https://gitea.reconnexion.apps.gueraud.net/Reconnexion/ng-eventually.git#1f0bae461e461c9fddd7215f972418acb2b4a989&path:/packages/client(@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-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)':
     optionalDependencies:
       '@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)

src/index.ts

@@ -3,6 +3,24 @@ import index from "./index.html";
 
 const port = process.env.PORT ? parseInt(process.env.PORT) : 3000;
 
+// Strict base64 check (not a mere `Buffer.from` attempt, which silently drops invalid
+// characters instead of failing): reject anything that is not a well-formed base64 body
+// before decoding, so a typo'd env var is reported instead of served as 810 garbage bytes.
+const BASE64_SHAPE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+function decodeBase64WalletOrThrow(raw: string) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0 || trimmed.length % 4 !== 0 || !BASE64_SHAPE.test(trimmed)) {
+    throw new Error("not valid base64 (bad characters, or length not a multiple of 4)");
+  }
+  // Web `atob` (not Node's `Buffer`, whose `ArrayBufferLike` generic doesn't line up
+  // with `Response`'s `BodyInit`) — decodes to a binary string, rebuilt into bytes below.
+  const binary = atob(trimmed);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
 const server = serve({
   port,
   routes: {
@@ -54,12 +72,44 @@ const server = serve({
       }),
 
     // The shared wallet file — the `fileUrl` the app hands the SDK, when configured.
+    //
+    // Two sources, read fresh on every request (never captured at module evaluation):
+    //   - FESTIPOD_SHARED_WALLET_FILE: a filesystem path. What local dev and the test
+    //     harness set today — a file sitting at the working-copy root.
+    //   - FESTIPOD_SHARED_WALLET_FILE_BASE64: the file's bytes, base64-encoded. What a
+    //     container sets instead, since *.ngw is gitignored and nothing mounts one there.
+    //
+    // Precedence: FILE wins whenever it is set, even if the path turns out unreadable —
+    // it is NOT "whichever resolves". This keeps dev/test behaviour byte-for-byte
+    // unchanged (they set only FILE, never BASE64) and makes the rule predictable: a
+    // deployment picks exactly one variable to set, and setting both is a leftover, not
+    // an intentional fallback chain.
     "/shared-wallet.ngw": async () => {
-      const p = process.env.FESTIPOD_SHARED_WALLET_FILE;
-      if (p) {
-        const file = Bun.file(p);
+      const path = process.env.FESTIPOD_SHARED_WALLET_FILE;
+      if (path) {
+        const file = Bun.file(path);
         if (await file.exists()) return new Response(file);
+        return new Response("No shared wallet file configured.", { status: 404 });
       }
+
+      const encoded = process.env.FESTIPOD_SHARED_WALLET_FILE_BASE64;
+      if (encoded) {
+        // Malformed must fail loudly: a 404 here would look identical to "not
+        // configured", which is exactly the confusion this project is removing.
+        try {
+          const bytes = decodeBase64WalletOrThrow(encoded);
+          return new Response(bytes, {
+            headers: { "Content-Type": "application/octet-stream" },
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return new Response(
+            `FESTIPOD_SHARED_WALLET_FILE_BASE64 is set but ${message}.`,
+            { status: 500 }
+          );
+        }
+      }
+
       return new Response("No shared wallet file configured.", { status: 404 });
     },