hikoutei 0.3.0 → 0.3.1

package/docs/ci.md

@@ -1,18 +1,29 @@
 # CI scenarios
 
-Hikoutei's CI includes an **internal sync/gateway end-to-end scenario**. It is
-not a public API smoke test. The scenario drives the internal typed-sheets sync
-pipeline — projection registration, gateway provisioning, the bounded effect
-worker, polling, and the MikroORM-backed storage/CAS/hash machinery — and
-loads implementation modules directly from the packed `dist/` tree. The
+Hikoutei's CI runs two installed-consumer scenarios against the packed
+package. Each is built as an installed consumer: after `npm pack` it imports
+from the packed tarball rather than from `src/**` or the source-only test
+fake, and neither is allowed to import those.
+
+1. **Internal sync/gateway E2E** (`scripts/ci/run-api-scenario.mjs`) drives the
+   internal typed-sheets sync pipeline — projection registration, gateway
+   provisioning, the bounded effect worker, polling, and the MikroORM-backed
+   storage/CAS/hash machinery — and loads implementation modules directly from
+   the packed `dist/` tree.
+2. **Installed root API smoke** (`scripts/ci/run-root-api-scenario.mjs`)
+   imports ONLY the installed package root entrypoint `hikoutei` (no internal
+   package subpaths and no source imports) and exercises the public
+   entity-lifecycle contract an application is meant to use.
+
+The public contract is the high-level `hikoutei` root API: a SQLite-backed
+entity lifecycle. Sheet configuration, registration, and synchronization remain
+internal service concerns. The
 `hikoutei/orm` and `hikoutei/mikro-orm` package subpaths are intentionally not
-published.
-
-The public contract is the high-level `hikoutei` root API: Sheet
-configuration/registration and a MikroORM-style entity lifecycle. Root API
-coverage lives in the unit/provider tests; this installed-consumer scenario
-intentionally remains focused on the internal sync/gateway pipeline and should
-not be read as public API CRUD coverage.
+published; the root smoke performs those dynamic imports only as negative
+boundary assertions (they must be rejected with `ERR_PACKAGE_PATH_NOT_EXPORTED`)
+while the lifecycle itself imports only the root `hikoutei` entrypoint. This
+guards the boundary directly in an installed consumer in addition to the
+source-level tests.
 
 ## Internal sync/gateway E2E
 
@@ -29,13 +40,63 @@ the same lifecycle:
 5. edit a User_Input value and verify that polling reports the changed row;
 6. restore the value, delete the entity, and verify the final projection state.
 
+## Installed root API smoke
+
+The root smoke imports only the installed `hikoutei` root entrypoint and drives
+the stable public lifecycle end to end against an in-memory SQLite authority
+(`dbName: ":memory:"`):
+
+1. define a scalar entity with `defineTypedSheetsEntity()`;
+2. open the runtime with `createTypedSheets()` and only `dbName` plus entity tokens;
+3. obtain a request-local manager with `em.fork()`;
+4. `create()` / `persist()` / `flush()` one entity and `findOne()`-verify it;
+5. mutate the loaded entity, `flush()`, and re-read it through a fresh fork to
+   confirm the mutation committed locally;
+6. `remove()` / `flush()` and verify the entity is gone through a fresh fork;
+7. close the runtime.
+
+It uses assertions and writes a JSON report plus a clear pass summary. It never
+contacts Google Sheets, never needs credentials, and never provisions remote
+tabs, so it runs as a packed consumer only in the normal CI, develop, and stable
+verify jobs and has no live counterpart. It is local-only — an in-memory SQLite
+authority with no backend concept — not a fake-backend scenario like the
+internal sync/gateway E2E. Its entity lifecycle imports only the
+root `hikoutei` package; the `hikoutei/orm` and `hikoutei/mikro-orm` dynamic
+imports it performs are negative boundary assertions that must be rejected,
+not part of the lifecycle.
+
 ## Backends and triggers
 
-The fake backend runs when a pull request targets `main` or `develop`, and when
-those branches receive a push. The live workflow runs for pull requests
-targeting `main` or `develop`. Live is skipped for forked pull requests because
-GitHub does not expose repository secrets to them; using `pull_request_target`
-would expose the secret to untrusted PR code. It uses a dedicated test
+The normal CI, develop, and stable verification jobs run **both** installed-consumer
+scenarios — the internal sync/gateway E2E and the installed root API smoke. The
+internal E2E uses the **fake** backend (no Google Sheets contact, no
+credentials); the root API smoke is local-only, an in-memory SQLite authority
+(`:memory:`) with no backend concept. The workflows are:
+
+- `.github/workflows/ci.yml` runs on pull requests and pushes to `main` and
+  `develop`.
+- `.github/workflows/develop-version.yml` creates the next patch version and
+  `develop-vX.Y.Z` tag after a `develop` push.
+- `.github/workflows/develop-publish.yml` verifies and publishes that tag with
+  the `develop` dist-tag.
+- `.github/workflows/main-version.yml` creates the next minor version and
+  `vX.Y.Z` tag after a `main` push.
+- `.github/workflows/stable-publish.yml` verifies and publishes that tag with
+  the `latest` dist-tag.
+
+Only the internal sync/gateway E2E has a live variant, in the separate
+`.github/workflows/live-integration.yml` workflow. It is opt-in via
+`workflow_dispatch` — a maintainer with write access dispatches it explicitly;
+it never runs automatically on pull requests or pushes — and exercises
+that single scenario against real Google Sheets with `--backend=live`. The installed root API smoke has no live
+counterpart: it is a local-only lifecycle smoke against an in-memory SQLite
+authority, so it never runs there.
+
+Because live is opt-in via `workflow_dispatch`, it is triggered manually by a
+maintainer with write access rather than automatically on pull requests, so
+there is no forked-PR secret-exposure path. The three gateway secrets are
+scoped to the live execution and cleanup steps only, not the whole job, so
+checkout/setup/install/build never see them. The live run uses a dedicated test
 spreadsheet and the following GitHub Actions secrets:
 
 - `TYPED_SHEETS_GATEWAY_URL`
@@ -51,62 +112,124 @@ not leave the fixture behind. The Apps Script receipt tab is also removed by
 the cleanup operation. Do not point the live secrets at a production
 spreadsheet; cleanup is intentionally scoped to the dedicated CI spreadsheet.
 
-## Beta publication
+## Develop publication
 
-A push to `develop` runs `.github/workflows/beta-publish.yml`. It repeats the
-unit/type/build/package checks and the installed-package fake sync/gateway E2E
-before publishing to npm with the `beta` dist-tag. Pull requests do not publish
-beta packages; the workflow runs after the commit reaches `develop`.
+A push to `develop` runs `.github/workflows/develop-version.yml`. It verifies
+the merged package, increments only the patch component, updates
+`package.json` and `package-lock.json`, commits the release version, and creates
+an annotated tag such as `develop-v0.3.1`. The generated commit is guarded from
+being processed as another release.
 
-The workflow requires the GitHub repository `NPM_TOKEN` secret and uses npm
-provenance. The token must never be committed to the repository. The publish
-job also checks that `develop` still points at the workflow commit so an older
-run cannot publish after a newer commit has landed.
+The tag triggers `.github/workflows/develop-publish.yml`. It repeats the
+unit/type/build/package checks, the installed-package internal sync/gateway
+E2E, and the installed root API smoke before publishing the numeric package
+version with the npm `develop` dist-tag. The version has no `-beta` suffix, but
+normal `npm install hikoutei` still resolves `latest` rather than this channel.
+Install the develop channel explicitly:
 
-The workflow does not commit a generated version back to `develop`. It
-publishes an ephemeral prerelease on the current numeric `package.json` version
-line with the GitHub run ID and attempt. For example, `0.3.0` produces
-`0.3.0-beta.b30560831639.1`, and starting the next development cycle at
-`0.3.1` produces `0.3.1-beta...`. The stable `package.json` version is
-therefore unchanged by CI. A full workflow rerun receives a new version;
-rerunning only the publish job intentionally reuses its verified artifact.
-An already published beta version is not deleted; after a corrected run, the
-`beta` dist-tag points to the new package on the current version line.
+```sh
+npm install hikoutei@develop
+```
 
-Install the newest beta package explicitly:
+The version calculation is isolated in `scripts/ci/release-version.mjs` and is
+covered by `test/release-version.test.ts`. For example:
 
-```sh
-npm install hikoutei@beta
+```text
+0.3.0 + patch → 0.3.1
+0.3.1 + patch → 0.3.2
 ```
 
+The workflow requires a repository `RELEASE_TOKEN` secret with contents write
+permission. A token other than the default `GITHUB_TOKEN` is used because a
+push made by `GITHUB_TOKEN` does not trigger another workflow; the release tag
+must trigger `develop-publish.yml`. The publish job separately requires
+`NPM_TOKEN` plus npm provenance. The branch SHA is checked immediately before
+pushing, and the commit plus tag use one atomic Git push, so a concurrent
+develop merge fails without leaving a stale release tag. The version commit and
+npm publication are not atomic; a failed publish can be retried from the
+existing `develop-vX.Y.Z` tag after verifying that the version has not already
+been published.
+
 ## Stable publication
 
-Stable releases use `.github/workflows/stable-publish.yml` and a numeric Git
-tag such as `v0.2.1`. The tag version must exactly match the versions in
-`package.json` and both version fields in `package-lock.json`; the workflow does
-not bump versions automatically.
+A push to `main` runs `.github/workflows/main-version.yml`. It verifies the
+merged package, increments the minor component, updates the package manifests,
+commits the release version, and creates an annotated tag such as `v0.4.0`:
 
-Release procedure:
+```text
+0.3.1 + minor → 0.4.0
+```
 
-1. Choose the next SemVer version and update `package.json` and
-   `package-lock.json` in a reviewed release commit.
-2. Use a compatibility-preserving patch version for bug fixes (for example
-   `0.2.1`) or a new minor version for a new public API/feature (for example
-   `0.3.0`). Document intentional pre-1.0 compatibility breaks.
-3. Create and push the matching `vX.Y.Z` tag.
-4. The tag workflow reruns the checks and installed-consumer fake E2E, then
-   publishes the verified package with the `latest` dist-tag. A `develop` push
-   does not change `latest`; for example, the `0.3.0` stable package is
-   published only after the `v0.3.0` tag is pushed.
+The tag triggers `.github/workflows/stable-publish.yml`. That workflow only
+validates the numeric tag and matching package manifest versions, reruns the
+full checks and installed-consumer scenarios, and publishes to npm with the
+`latest` dist-tag. A `develop-v0.3.1` tag cannot trigger this numeric `vX.Y.Z`
+workflow.
+
+The main version workflow uses the same `RELEASE_TOKEN` requirement so its
+`vX.Y.Z` tag triggers `stable-publish.yml`. The stable publish job also
+requires the repository `NPM_TOKEN` secret and npm provenance before publishing
+`latest`. After a stable main release, merge
+`main` back into `develop` so the next patch release starts from the new stable
+baseline. Stable package versions are
+immutable on npm, so reusing a published version fails instead of replacing
+it. Normal users install the stable channel with:
 
-A stable package is immutable on npm, so reusing a published version fails
-instead of replacing the existing package. Normal users can install the
-`latest` release with `npm install hikoutei`.
+```sh
+npm install hikoutei
+```
 
 ## Artifacts
 
-The internal sync/gateway CI workflows emit a JSON artifact and, for live
-runs, a step summary. The beta and stable publication workflows upload their
-fake E2E reports and verified package artifacts when available. Setup time and
-steady-state time are reported separately so spreadsheet creation and header
-provisioning do not distort the internal sync/gateway measurements.
+The CI, develop, and stable jobs each emit a JSON report for **both**
+scenarios (internal sync/gateway E2E and installed root API smoke). The live
+job emits a JSON report only for the internal sync/gateway E2E, the single
+scenario it runs. Both runner scripts (`run-api-scenario.mjs` and
+`run-root-api-scenario.mjs`) default their `--summary` option to
+`GITHUB_STEP_SUMMARY`, so in GitHub Actions every CI/develop/stable invocation
+writes a step summary even though none passes `--summary` explicitly. The live
+internal E2E run is the only invocation that passes `--summary` explicitly
+(`--summary="$GITHUB_STEP_SUMMARY"`), which resolves to the same default but
+documents the intent. The develop and stable verify jobs upload their two
+installed-consumer scenario reports as a dedicated reports artifact
+(`if: always()`), separate from the package artifact (`if: success()`) that the
+publish job consumes. Setup time and steady-state time are reported separately
+for the internal E2E so spreadsheet creation and header provisioning do not
+distort the internal sync/gateway measurements.
+
+The develop and stable package artifacts are each a single directory that
+holds the npm tarball and its `sha256` checksum together under
+`$RUNNER_TEMP/hikoutei-{develop,stable}-package`. Their GitHub artifact names
+are `hikoutei-develop-package` and `hikoutei-stable-package`; the installed
+consumer report artifacts are `hikoutei-develop-fake-installed-consumer` and
+`hikoutei-stable-fake-installed-consumer`. The normal CI report artifact is
+`hikoutei-fake-installed-consumer`. The publish job downloads the corresponding
+package directory, asserts it contains exactly one `hikoutei-*.tgz` and the
+checksum file, verifies the checksum line names that exact tarball (not merely
+any file present in the directory), and only then runs `sha256sum --check`
+before publishing. Name/version validation, npm provenance, the
+`develop`/`latest` dist-tags, and the stale branch SHA checks are enforced by
+the corresponding workflows.
+
+## Action versions
+
+Every workflow pins `actions/checkout`, `actions/setup-node`,
+`actions/upload-artifact`, and `actions/download-artifact` to the current
+Node 24-compatible major (`v5`) so the JavaScript actions run on the runner's
+Node 24 runtime:
+
+| Action | Major | Runtime |
+| --- | --- | --- |
+| `actions/checkout` | `v5` | Node 24 |
+| `actions/setup-node` | `v5` | Node 24 |
+| `actions/upload-artifact` | `v5` | Node 24 |
+| `actions/download-artifact` | `v5` | Node 24 |
+
+All four are on the same major, so there is no exception to record. The pin
+preserves behavior: artifacts are downloaded by name (not by artifact ID);
+`upload-artifact` still zips by default; `setup-node` `cache: npm` is set
+explicitly (the package has no `packageManager` field, so the auto-cache
+shortcut never applies); and the publish steps set `NODE_AUTH_TOKEN` in their
+own `env`, so npm provenance and the `id-token: write` permission are
+unchanged. This major is the action's own runtime version; the build and
+test job still uses `node-version: 22`.

package/docs/mikro-orm-adapter-spike.md

@@ -1,248 +1,89 @@
 # MikroORM SQLite Adapter and Entity Facade Spike
 
-## Purpose
-
-This spike tests the proposed Sheets-side persistence shape without making
-MikroORM the typed-sheets public API:
+This spike records the current provider boundary. MikroORM is the replaceable
+SQLite execution engine behind Hikoutei's root EntityManager; it is not part of
+the application-facing contract.
 
 ```text
-application server
-├─ primary entities → application MikroORM → primary database (for example MySQL)
-└─ Sheets entities  → typed-sheets EntityManager → MikroORM SQLite executor → SQLite → Google Sheets outbox
+application code
+  └─ hikoutei root EntityManager
+       └─ provider-neutral scalar persistence contract
+            └─ MikroORM + SQLite
+                 └─ [internal sync service]
+                      └─ canonical state and Sheet effect outbox
 ```
 
-The two MikroORM instances are intentionally separate. A Sheets entity uses a
-dedicated SQLite database and cannot accidentally write through the
-application's MySQL entity manager. `TypedSheetsOrm` and
-`TypedSheetsEntityManager` are ours; MikroORM is only the first replaceable
-SQLite execution engine behind them.
-
-## Public entity lifecycle
+## Root entity lifecycle
 
-The application-facing lifecycle follows the familiar entity-manager shape,
-without returning a raw MikroORM manager:
+Applications use only the root package:
 
 ```ts
-import {
-  defineTypedSheetsEntityMapping,
-} from "typed-sheets/orm";
-import {
-  initializeMappedTypedSheetsOrm,
-} from "typed-sheets/mikro-orm";
-import { provisionRegisteredSyncSheets } from "typed-sheets";
-
-const orderMapping = defineTypedSheetsEntityMapping({
-  entity: Order,
-  logicalSheetId: "orders",
-  primaryKey: "id",
-  businessKey: "orderNumber",
-  schemaVersion: 1,
-  fields: [
-    {
-      property: "orderNumber",
-      cellKind: "string",
-      ownership: "user",
-      required: true,
-      unique: true,
-    },
-    {
-      property: "status",
-      cellKind: "string",
-      ownership: "user",
-      required: true,
-    },
-    {
-      property: "approvedAt",
-      cellKind: "date",
-      ownership: "system",
-    },
-  ],
-  projections: [
-    {
-      physicalSheetId: "orders-input",
-      spreadsheetId: process.env.GOOGLE_SHEET_ID!,
-      tabName: "User_Input",
-      registeredRange: "A:B",
-      projection: "user_input",
-    },
-    {
-      physicalSheetId: "orders-system",
-      spreadsheetId: process.env.GOOGLE_SHEET_ID!,
-      tabName: "System_State",
-      registeredRange: "A:D",
-      projection: "system_state",
-    },
-  ],
+import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
+
+const Order = defineTypedSheetsEntity({
+  name: "Order",
+  tableName: "orders",
+  properties: {
+    id: { type: "string", primary: true },
+    status: { type: "string" },
+  },
 });
 
-const typedSheetsOrm = await initializeMappedTypedSheetsOrm({
+const hikoutei = await createTypedSheets({
   dbName: "./typed-sheets.sqlite",
   entities: [Order],
-  mappings: [orderMapping],
-  writer: { writerId: "orders-service" },
-  onRegisteredProjections: (definitions) =>
-    provisionRegisteredSyncSheets(appsScriptGateway, definitions),
 });
 
-const em = typedSheetsOrm.em.fork();
-
+const em = hikoutei.em.fork();
 const order = em.create(Order, { id: "o-1", status: "pending" });
 em.persist(order);
 await em.flush();
-
-const loaded = await em.findOne(Order, { id: "o-1" });
-if (loaded !== null) {
-  loaded.status = "paid";
-  await em.flush();
-}
 ```
 
-The initial facade exposes `fork`, `create`, `find`, `findOne`, `persist`,
-`remove`, `flush`, `transactional`, and `clear`. Reads use the local SQLite
-state only; they do not wait for a Google Sheets API call. The initial filter
-contract is an equality filter with optional `limit` and `offset`, rather than
-the entire MikroORM query language.
-
-`flush()` collects create, update, and delete changes, then the built-in mapping
-planner writes the entity row, canonical state, row binding, business-key
-index, and ordered Sheets outbox effects in one SQLite transaction. It does
-not synchronously call Google Sheets. If planning throws, all of those local
-writes roll back together.
-
-The mapping requires exactly one `System_State` route and may additionally
-declare one `User_Input` route. `System_State` receives the complete canonical
-view plus a system tombstone marker. A direct create or a direct change to a
-user-owned field also emits a candidate-preserving `User_Input` reconcile
-effect; it does not overwrite an unresolved Sheet candidate. A direct remove
-also creates a guarded `user_input_delete` effect when a `User_Input` route
-exists. Its payload contains the complete expected input row, so the gateway
-deletes only an anchored row whose visible revision and full row hash still
-match. The worker blocks that effect rather than deleting when an unresolved
-candidate owns any user-owned field.
-
-The production-shaped sync gateway source at
-`apps-script/gateway/Code.gs` is the thin operation data plane. Deploy the
-current source before connecting a service; older deployments may not
-understand the current signed operation protocol.
-
-The low-level `flushCoordinator` seam remains available for an adapter author
-or an advanced custom planner, but ordinary entity configuration no longer
-needs it.
-
-`onRegisteredProjections` is optional. When supplied, it receives the exact
-registry routes and generated headers after the local SQLite registration has
-succeeded; the example uses it to provision the reviewed Apps Script
-allowlist. Omitting it keeps remote spreadsheet provisioning separate from
-process startup.
-
-## Package boundary
-
-The typed-sheets entity lifecycle contracts are available from
-`typed-sheets/orm`. The MikroORM-specific initializer and SQLite adapter are
-available only from `typed-sheets/mikro-orm`. The root `typed-sheets` import
-does not load MikroORM.
-
-MikroORM is an optional peer dependency. This keeps the core/storage contract
-replaceable by another persistence integration later.
+The facade exposes `fork`, `create`, `find`, `findOne`, `persist`, `remove`,
+`flush`, and `transactional`. Reads use SQLite only. The root runtime creates
+entity tables and does not require Sheet routes, gateway credentials, or sync
+provisioning.
 
-```ts
-import {
-  initializeMikroOrmSqliteAdapter,
-  migrateMikroOrmSqliteStorageSchema,
-} from "typed-sheets/mikro-orm";
+## Internal mapped service
 
-const storage = await initializeMikroOrmSqliteAdapter({
-  dbName: "./typed-sheets.sqlite",
-  entities: [Order],
-});
-
-// Explicit on purpose: startup does not mutate a production schema unless the
-// application opts in.
-await migrateMikroOrmSqliteStorageSchema(storage);
-```
+The sync service uses the same adapter contracts but adds private mapping
+configuration for routes and field ownership. Its bootstrap performs local
+schema migration and projection registration, provisions the Apps Script
+allowlist, and starts the effect/polling supervisors. Those modules are under
+`src/application/sync/service/` and are not exported from `src/index.ts`.
 
-`migrateMikroOrmSqliteStorageSchema()` first applies MikroORM's safe,
-non-destructive entity-schema update, then applies typed-sheets' versioned sync
-schema. The sync schema keeps its existing `PRAGMA user_version` migration
-contract while both schemas share the same SQLite connection.
+In internal service mode, `flush()` plans and commits the entity row, canonical
+state, row binding, business-key index, and ordered Sheet outbox effects in one
+SQLite transaction. It still returns before the remote write completes.
 
-## Proven transaction boundary
+The service uses the existing guarded operation model:
 
-`MikroOrmSqliteAdapter.transactional()` provides the active MikroORM entity
-manager and an adapter-neutral SQL executor together:
+- `System_State` receives canonical materialization and tombstones.
+- `User_Input` is updated only through guarded projection effects.
+- response loss is recovered through durable receipts and postcondition reads.
+- user edits are polled, evaluated with ownership and field-level CAS, and
+  accepted changes are applied to SQLite without a duplicate User_Input loop.
+- stale, conflicting, and invalid input remains in SQLite evidence tables.
 
-```ts
-import { persistObservedRowWithSql } from "typed-sheets";
+The production-shaped gateway source is
+`apps-script/gateway/Code.gs`. Its signed transport and operation types are
+internal adapter details; application code does not construct them.
 
-await storage.transactional(async ({ entityManager, sql }) => {
-  const order = entityManager.create(Order, { id: "o-1", status: "pending" });
-  entityManager.persist(order);
-  await entityManager.flush();
+## Provider boundary
 
-  // The observation receipt, event ledger, canonical state, and Sheets outbox
-  // all use this same transaction-bound SQL executor. A later failure rolls
-  // the Order row back too.
-  await persistObservedRowWithSql(sql, fence, observedRow);
-});
-```
+`ScalarEntityPersistenceProvider` is the engine-neutral contract used by the
+public EntityManager. The current `MikroOrmScalarPersistenceProvider` maps it
+to one MikroORM SQLite connection. The mapped sync runtime exposes the same
+connection to storage SQL, entity writes, and outbox planning so a transaction
+cannot commit an entity mutation without its local sync work.
 
-Focused tests prove these operations commit or roll back together:
-
-- MikroORM entity row
-- typed-sheets canonical state
-- pending Google Sheets effect
-- writer lease and fencing (stale writer rejection)
-- registered Sheet projection/allowlist
-
-## Current boundary
-
-The durable SQLite paths now have adapter-backed counterparts:
-
-- writer lease, registry, canonical commit, and effect-outbox operations;
-- `persistObservedRowWithSql()` / `persistObservedRowWithAdapter()` for
-  observation receipt, event ledger, canonical state, conflict, quarantine,
-  and effects;
-- `persistResolutionCommandWithSql()` /
-  `persistResolutionCommandWithAdapter()` for trusted conflict commands;
-- `runSyncEffectWorkerWithAdapter()` from `typed-sheets/mikro-orm` for Sheets
-  effect claiming, application, and recovery.
-
-The legacy synchronous `node:sqlite` APIs remain available for existing
-runtimes. The `WithSql` variants require a caller-owned transaction, while the
-`WithAdapter` variants open one through the adapter. This distinction makes it
-explicit at the call site whether a user-entity mutation must share the same
-commit boundary.
-
-The public mapping layer now derives canonical commits and projection effects
-from entity lifecycle changes. It also supplies
-`persistMappedObservedRowWithMikroOrm()` for the reverse half of the durable
-boundary: an already-normalized, already-evaluated accepted observation is
-stored and applied to the mapped MikroORM entity in one SQLite transaction.
-It uses native MikroORM writes internally so it does not trigger a second
-outbound `flush()` loop.
-
-The raw Sheet snapshot → normalized observation → pure evaluator bridge is
-still explicit. In particular, physical row-anchor discovery and projection
-row-location persistence must be supplied by the existing gateway/ingestion
-flow before an observation reaches `persistMappedObservedRowWithMikroOrm()`.
-This prevents the mapping layer from guessing row identity from a row number or
-business key.
-
-`em.remove()` creates a canonical tombstone, a `System_State` tombstone
-projection, and a guarded physical `User_Input` deletion when that route is
-configured. A gateway response loss is resolved only through the deletion
-effect's own receipt; an absent row by itself is never treated as proof that a
-manual or unrelated deletion was ours. If the gateway or local conflict ledger
-detects an active candidate, the input row is retained and the deletion effect
-is marked `blocked_candidate` for explicit conflict handling.
-
-The mapping/planner depends only on the adapter-neutral storage and entity
-engine contracts. A future SQLite execution engine can replace MikroORM
-without changing the `typedSheetsOrm.em.fork()` workflow or mapping
-declarations.
+A future provider can implement the scalar persistence contract without
+changing entity lifecycle calls. A future worker process can reuse the internal
+sync engine without changing the root API.
 
 ## Runtime requirement
 
 The current adapter uses MikroORM 7's Node SQLite dialect, which requires Node
 22.17 or later. Node's built-in SQLite API is still marked experimental; that
-warning is expected in the focused adapter tests.
+warning is expected in focused adapter tests.