hikoutei 0.10.17-dev → 0.10.19-dev

package/README.md

@@ -2,6 +2,8 @@
 
 <div align="center">
 
+<img src="assets/hikoutei-icon.png" alt="Hikoutei" width="220" />
+
 # Hikoutei
 
 **Keep your app fast with SQLite. Keep your workflow visible in Google Sheets.**
@@ -34,46 +36,6 @@ collaboration.
 > and it does not treat Google Sheets as the authoritative application
 > database. SQLite is the source of truth; Sheets is the human-facing view.
 
-## Quick start
-
-Define a scalar entity and use the local SQLite authority through a
-request-local manager.
-
-```ts
-import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
-
-const User = defineTypedSheetsEntity({
-  name: "User",
-  tableName: "users",
-  properties: {
-    id: { type: "string", primary: true },
-    name: { type: "string" },
-    age: { type: "number" },
-    active: { type: "boolean" },
-  },
-});
-
-const hikoutei = await createTypedSheets({
-  dbName: "./hikoutei.sqlite",
-  entities: [User],
-});
-
-const em = hikoutei.em.fork();
-const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
-em.persist(user);
-await em.flush();
-
-user.name = "Ada Lovelace";
-await em.flush();
-```
-
-**What happens to the Sheet?** The write commits to local SQLite immediately —
-the application request never waits on Google. When the sync service is
-enabled, Hikoutei later projects the entity to the registered Google Sheet in
-the background. Human edits made in the sheet are observed, validated, and
-either accepted back into SQLite or recorded as conflicts, never silently
-overwritten.
-
 ## Why Hikoutei?
 
 - Define typed entities instead of manually converting Sheet rows.
@@ -82,29 +44,6 @@ overwritten.
 - Detect unexpected column changes and duplicate headers.
 - Avoid overwriting newer Sheet edits during conflicting updates.
 
-## When to use Hikoutei
-
-Hikoutei is a good fit for:
-
-- MVPs and prototypes where a spreadsheet is part of the product workflow.
-- Internal tools and low-traffic administrative applications.
-- Teams that want typed application data while keeping Sheets easy for people
-  to inspect.
-- Services that can use SQLite locally and accept asynchronous Sheet updates.
-
-## When to choose something else
-
-Use a conventional database and direct Google APIs when you need:
-
-- Strong transactions across many rows or services.
-- High write throughput or many concurrent writers.
-- Complex queries, joins, or reporting workloads.
-- Multi-server or multi-region coordination.
-- Immediate read-after-write consistency in Google Sheets.
-- Google Sheets to be the primary database for the application.
-
-## Is Hikoutei the right abstraction for you?
-
 Hikoutei does not replace `google-spreadsheet` or `@googleapis/sheets` — it
 sits one level above them. If you only need raw spreadsheet access, use the API
 client directly.
@@ -119,289 +58,83 @@ client directly.
 | Direct row and cell manipulation | Limited | ✅ | ✅ |
 | Full Google Sheets API access | Provider only | Partial | ✅ |
 
-## Google Sheets setup
-
-Google Sheets synchronization is a service-side concern. Applications do not
-import a provider client, pass Sheet routes to `createTypedSheets()`, or choose
-an operation for each write — `CreateTypedSheetsOptions` fields (`dbName`,
-`entities`, `providerOptions`) are all optional. The sync runtime uses one
-internal Google Sheets API provider with a service account — no Apps Script
-deployment. Sync auto-start is selected by `HIKOUTEI_SYNC_SPREADSHEET_URL`
-plus `GOOGLE_APPLICATION_CREDENTIALS`. Optional `providerOptions` tunes the
-sync-path provider (telemetry/timeouts; inert when local-only), and
-`createTypedSheetsWithSync()` exposes the same options with a richer result
-for existing-sheet adoption.
-
-**Fastest path:** install the gcloud CLI, then run `npx hikoutei setup` from your
-project directory. On an interactive terminal it offers (press Enter) to
-start `gcloud auth login --enable-gdrive-access --force` for you when the
-active account is missing or lacks Drive access — you only complete the
-browser approval yourself. (In `--yes`, CI, or non-TTY sessions, run that
-login command yourself first.) Setup then creates the project, service
-account, and key, creates a spreadsheet owned by your account, shares it
-with the service account as an Editor, verifies service-account access, and
-writes `GOOGLE_APPLICATION_CREDENTIALS` plus `HIKOUTEI_SYNC_SPREADSHEET_URL`
-into your `.env`. The human access token is used in memory only and never
-stored. Automatic setup runs on macOS and Linux; on Windows a non-dry-run
-is refused before any mutation and manual setup is available. Interrupted runs resume from a local checkpoint
-(`.hikoutei-setup-state.json`); a spreadsheet create whose outcome is
-unknown is reconciled by its creation marker on the next run and setup
-never creates a second spreadsheet (inspect Drive and rerun if setup
-reports `sheet_create_uncertain`, and a create rejected up front with
-HTTP 400/403 plus a confirmed-zero marker lookup rolls back to `key_ready`
-so a corrected rerun starts a fresh marker). Sharing is write-ahead too:
-`spreadsheet_share_started` is persisted before the idempotent SA writer
-permission ensure and `spreadsheet_shared` after it, so a crash between
-the remote permission mutation and the checkpoint write resumes the
-ensure on the next run and never creates a second spreadsheet. The
-service-account key is
-created under a write-ahead contract too: the user-managed key list is
-recorded as a baseline before the single gcloud key create, and
-`key_create_started`/`key_ready` checkpoints let a crashed run recover a
-staged or installed key instead of creating a second one. Only the
-invocation that just persisted `key_create_started` may issue the one key
-create; resumed runs are reconcile-only and, when no credential and no
-post-baseline key are visible, poll the key list plus staged/final
-evidence for up to two minutes (2, 4, 8, 16, 30, 30, 30 s) before failing
-with `key_create_uncertain` — the create is never retried automatically.
-An unmatched user-managed key with no local credential is never deleted
-automatically — setup fails with `key_create_uncertain` and you inspect
-the key list in the Google Cloud console before rerunning (a
-verified-absent state requires removing the setup state file to reset the
-key checkpoint); reused keys are enforced to owner-only mode 600. An exclusive lock directory
-(`.hikoutei-setup-state.json.lock`) prevents concurrent runs and is never
-removed automatically: a crash leaves an empty lock directory behind, and
-removing it manually is required only when you are certain no setup is
-running. Starting fresh requires removing or moving both the checkpoint and
-the key file, or passing `--project` to recover an existing key —
-checkpointed or identity-matched cloud resources are reused, and setup
-never deletes cloud resources. The manual steps below remain available for
-advanced setups.
-
-**Setup progress.** `hikoutei setup` reports step-by-step progress to
-**stderr** across the ten setup phases (cloud auth, Drive access, project,
-APIs, service account, service-account key, spreadsheet, share,
-service-account access, output): an **overall bar** advances only when a
-phase actually completes — it is never an ETA and never guesses a
-percentage — and a **detail line** shows the bounded propagation checks
-(how many of the eight key/access checks have run) and the known 2, 4, 8,
-16, 30, 30, 30 s waits, with a fixed `working…` label for unknown-duration
-steps. On an interactive terminal the four-line block redraws in place;
-in CI, non-TTY, or `NO_COLOR` sessions one static line is printed per
-phase/retry event with no control sequences. Progress pauses and the
-block is cleared during the interactive `gcloud auth login` handoff and
-resumes with the retry. Progress never prints credentials, tokens, keys,
-project ids, emails, paths, or raw command output, and it can never
-change the setup result or exit code; `--dry-run` prints the command
-plan only.
-
-**Keep setup artifacts out of Git.** `hikoutei setup` writes its defaults
-into the current directory: the service-account key
-(`hikoutei-service-account.json`, owner-only mode 600 — a secret), the
-resume checkpoint (`.hikoutei-setup-state.json` and its `.tmp`/unique-temp
-and `.lock` siblings), private key staging/cleanup directories
-(`.hikoutei-key-stage-*`, `.hikoutei-key-cleanup-*`), and
-`.hikoutei-env-*` temporary env writes. The repository's `.gitignore`
-already ignores these defaults, so a plain `git add .` does not pick them
-up. A `.gitignore` is **not a security boundary**, though: it only keeps
-untracked files out of `git add`, and it does not protect files that are
-already tracked (remove a mistakenly tracked key from history and rotate
-it — delete the user-managed key in the Cloud console and rerun setup).
-When you use a custom `--output` or keep the key or checkpoint at custom
-paths, add those exact paths to your application's ignore rules and never
-commit them.
-
-### Env-driven sync auto-start
-
-Set the spreadsheet URL in the environment and `createTypedSheets()` starts
-the Sheets sync internally — `flush()` then flows to Google Sheets through
-the outbox worker with no per-call setup:
+## Installation
 
 ```sh
-HIKOUTEI_SYNC_SPREADSHEET_URL=https://docs.google.com/spreadsheets/d/<ID>/edit
-GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
-```
-
-```ts
-const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities: [User] });
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
 ```
 
-Without `HIKOUTEI_SYNC_SPREADSHEET_URL`, `createTypedSheets()` stays
-local-only (SQLite). Startup failures are diagnosed with clear messages:
-invalid URL, missing/invalid credentials file, or a service account not
-shared on the spreadsheet (the error tells you which email to share).
-
-### Manual service-account setup
-
-1. **Create a service account.** Enable the Google Sheets API in a Cloud
-   project, create a service account with the
-   `https://www.googleapis.com/auth/spreadsheets` scope, and share the target
-   spreadsheet with its email as an **Editor**. The provider creates tabs,
-   writes effect rows and receipt records, and manages row anchors, so Viewer
-   access is not enough.
-2. **Keep the key server-side.** Put the service-account key path in
-   `GOOGLE_APPLICATION_CREDENTIALS` on the server and the spreadsheet ID in an
-   untracked secret store. Never put the key in browser code or Git: add the
-   key path (and any custom `.env`/checkpoint paths) to the application's
-   `.gitignore` — the defaults created by `hikoutei setup` are already
-   ignored, but a `.gitignore` is not a security boundary and does not
-   protect already-tracked files.
-3. **Run the application normally.** Start the app with
-   `GOOGLE_APPLICATION_CREDENTIALS` and `HIKOUTEI_SYNC_SPREADSHEET_URL` set;
-   `createTypedSheets()` detects them and starts the internal sync bootstrap —
-   it creates and verifies headers on the registered tabs, then starts outbox
-   delivery and User_Input polling. Pass `providerOptions` only when sync-path
-   tuning is needed; there is no internal bootstrap to start by hand.
-
-> **Legacy spreadsheet note.** Spreadsheets provisioned by the old Apps Script
-> provider with developer-metadata row anchors are not migrated: `User_Input`
-> tabs now require the `__hikoutei_row_id` system column, so legacy tabs must
-> be re-provisioned. Current provisioning also adds one internal formula
-> column, `__hikoutei_row_check`, directly after each `User_Input` tab's
-> registered range: Hikoutei writes a change-detection formula per row, and
-> polling reads only that column to spot human edits (rows without it fall
-> back to full reads). Do not edit, sort, or delete the column or its
-> formulas.
-
-Hikoutei uses a durable local outbox, idempotent delivery, and conflict-aware
-updates so temporary API failures do not lose committed application writes. The
-provider never logs credentials, spreadsheet IDs, URLs, or payloads, and it
-spaces request starts to stay inside Google's quota windows. See the
-[internal consistency model](website/guide/internal-consistency.md) for the
-detailed state machine and recovery rules.
-
-Live Google calls are opt-in; fake providers and SQLite fixtures are the normal
-verification path. The detailed setup and troubleshooting steps are in the
-[Quick start](website/guide/quick-start.md) and [Google Sheets setup](website/guide/setup.md) —
-including the credential pool (`--sa-count`) and API quota guidance when
-polling-heavy workloads hit HTTP 429.
+Installing the library does not touch Google Cloud — it runs local-only
+(SQLite) by default. Run the setup command below only when you want Sheet
+sync.
 
-## Installation
+## Setup (Google Sheets sync)
 
-The project and npm package are both called `hikoutei`. This repo uses pnpm
-(packageManager `pnpm@11.1.2`):
+One-time, interactive. Install the gcloud CLI, then:
 
 ```sh
-pnpm install --frozen-lockfile
+npx hikoutei setup
 ```
 
-`@mikro-orm/core` and `@mikro-orm/sql` are optional peers (`optional: true`),
-lazy-loaded only when a runtime opens. `npm install` still works for consumers.
-
-## Documentation
-
-- [Quick start](website/guide/quick-start.md) — installation, ORM lifecycle,
-  and service-side sync setup.
-- [Architecture](website/guide/architecture.md) — how the local store and
-  Sheet views fit together.
-- [Write and synchronization flow](website/guide/sync-flow.md) —
-  asynchronous delivery and recovery behavior.
-- [Internal consistency model](website/guide/internal-consistency.md) —
-  durable outbox, idempotent delivery, and conflict-aware updates.
-- [Contributing](website/guide/contributing.md) — local development and test
-  commands.
-- [Soak testing](website/guide/soak-testing.md) — the long-duration soak
-  runner: source build, six scalar tables, 6h preflight and 24h direct-live
-  runs, log envs, redaction contract, resume/cleanup, and acceptance
-  criteria.
-- [Benchmark notes](website/guide/benchmarks.md) — dated measurements and
-  their limitations.
-
-## Limitations
-
-- Google Sheets has quota, latency, and API rate limits. The outbound sync
-  worker batches effects to the spreadsheet scope, so remote request volume
-  does not grow with the number of tabs a dispatch touches.
-- Sheet updates are asynchronous; the application should read its local state.
-- SQLite is local to the service and is not a distributed coordination layer.
-- Schema changes, manual edits, and conflicting updates still need an
-  operational policy from the application.
-- The EntityManager is an ORM-style facade over scalar entities, not a full
-  ORM: entity definitions are scalar-only (`string`, `number`, `boolean`,
-  `date`), and v1 permits uniqueness only on the primary/business key.
-- Relations, joins, `populate()`, migrations, cascades, bulk/ORM query
-  builders, and raw SQL are unsupported in this milestone. Sheets is an async
-  projection and human input surface, never a live query database.
-
-## Local queries
-
-Reads use Hikoutei-owned typed operators and always execute against SQLite:
+This creates the Cloud project, service account, key, and spreadsheet, and
+writes `.env` for you. Without `HIKOUTEI_SYNC_SPREADSHEET_URL`,
+`createTypedSheets()` stays local-only (SQLite). Details, credential pools,
+quota guidance, and manual setup: [Google Sheets setup](website/guide/setup.md).
+
+## Usage
+
+Define a scalar entity and use the local SQLite authority through a
+request-local manager.
 
 ```ts
-const [users, total] = await em.findAndCount(
-  User,
-  {
-    name: { like: "Ada%" },
-    age: { gte: 18, lt: 65 },
-    active: { in: [true] },
-  },
-  {
-    orderBy: { age: "desc", name: "asc" },
-    limit: 20,
-    offset: 0,
+import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
+
+const User = defineTypedSheetsEntity({
+  name: "User",
+  tableName: "users",
+  properties: {
+    id: { type: "string", primary: true },
+    name: { type: "string" },
+    age: { type: "number" },
+    active: { type: "boolean" },
   },
-);
+});
+
+const hikoutei = await createTypedSheets({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+});
+
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
+em.persist(user);
+await em.flush();
+
+user.name = "Ada Lovelace";
+await em.flush();
+
+const loaded = await em.findOne(User, { id: "u1" });
+if (loaded !== null) {
+  em.remove(loaded);
+  await em.flush();
+}
 ```
 
-`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, and `nin` are available where
-valid for the declared scalar type; `like` is string-only. Equality shorthand
-such as `{ active: true }` remains supported. `count()` returns the unpaged
-filter total, and `findAndCount()` returns the filtered page plus a total
-that ignores `limit`/`offset` — both read from one SQLite snapshot. When an
-explicit `orderBy` omits the primary key, Hikoutei appends it in ascending
-order as the final tie-breaker; when the primary key is explicitly ordered,
-its supplied position and direction are preserved. Pagination without
-`orderBy` uses primary-key ascending order.
-
-An `offset` alone (no `limit`) is a valid offset-only read, and an explicit
-`limit: 0` returns an empty page rather than being treated as "no limit".
-`findOne()` returns one entity or `null` and accepts ordering but no paging
-options. Malformed filters, operators, ordering, and paging options fail with
-a stable `HikouteiError`; branch on `error.code` through the exported
-`HIKOUTEI_ERROR_CODES` constants (`HIKOUTEI_ERROR_CODES.INVALID_QUERY` and
-`HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE`, which resolve to the lowercase
-runtime codes `invalid_query` and `invalid_scalar_value`) instead of guessing
-strings or parsing messages.
-
-## Project status
-
-Hikoutei is in active development. The current EntityManager supports scalar
-entity lifecycle operations, typed local filters and ordering, `limit` /
-`offset` pagination, `count()`, snapshot-consistent `findAndCount()`, and
-callback-style `transactional()` work. Normal reads always come from SQLite,
-never Google Sheets. Sheet edit ingestion and conflict presentation are still
-evolving. Review release notes before upgrading minor versions.
-
-## Roadmap
-
-The first EntityManager milestone, rich local reads, is complete. Remaining
-milestones follow the implementation order below; no milestone is tied to a
-date or release number.
-
-1. **Lifecycle-safe writes**
-   - Add `upsert` and direct/bulk mutation capabilities only through a
-     Hikoutei-owned contract that preserves one SQLite transaction across the
-     entity table, canonical state, and durable Sheet effect outbox.
-   - Do not promise raw `nativeInsert`, `nativeUpdate`, `nativeDelete`, or SQL
-     pass-through APIs that could bypass that atomic lifecycle.
-2. **Relationships and loading**
-   - Add many-to-one, one-to-many, and `populate()` capabilities.
-   - Design SQLite relationship mapping, Sheets projection representation,
-     schema behavior, and conflict semantics together before public release.
-3. **Schema operations**
-   - Add migration and schema drift management.
-   - Integrate validation and operational workflows with the existing setup
-     tooling.
-
-### Synchronization and operations
-
-The following work continues in parallel with the EntityManager milestones:
-
-- Complete ingestion of intentional user edits from Google Sheets.
-- Improve update/delete conflict handling and presentation.
-
-See the [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
-for current work.
+More reads, transactions, and operators: [Quick start](website/guide/quick-start.md).
+
+Writes commit to local SQLite immediately — the request never waits on Google.
+Human edits in the Sheet flow back through polling — accepted into SQLite or
+recorded as conflicts, never silently overwritten. The full pipeline (outbox,
+delivery, conflict handling) is covered in
+[Write and synchronization flow](website/guide/sync-flow.md).
+
+## Learn more
+
+- [Quick start](website/guide/quick-start.md) — installation, ORM lifecycle, sync setup.
+- [Architecture](website/guide/architecture.md) — local store and Sheet views.
+- [Write and synchronization flow](website/guide/sync-flow.md) — delivery and recovery.
+- [Limitations](website/guide/limitations.md) — when to choose something else.
+- [Project status and roadmap](website/guide/status.md) — what is done and next.
 
 ## License
 

package/dist/contracts/api/entity.d.ts

@@ -100,11 +100,16 @@ export declare function clearRegisteredEntityTokens(): void;
  * Validates a scalar entity descriptor and returns a stable entity token.
  *
  * Throws a typed `HikouteiError` for an empty name or table name, an invalid
- * table identifier, a missing or duplicate primary key, a non-string primary
- * key, a non-scalar property type, or any unsupported relation/provider option.
- * The returned token is safe to pass to `createTypedSheets({ entities })`, and
- * is also registered so a later `createTypedSheets()` call that omits
- * `entities` can use it as the default entity set.
+ * table identifier, a missing or duplicate primary key, a non-string/number
+ * primary key, a non-scalar property type, or any unsupported
+ * relation/provider option. The returned token is safe to pass to
+ * `createTypedSheets({ entities })`, and is also registered so a later
+ * `createTypedSheets()` call that omits `entities` can use it as the default
+ * entity set.
+ *
+ * A `string` primary key stays a TEXT column with application-assigned IDs.
+ * A `number` primary key becomes an INTEGER AUTOINCREMENT column so SQLite
+ * assigns the numeric ID when the app omits it at insert.
  */
 export declare function defineTypedSheetsEntity<Name extends string, Properties extends HikouteiPropertyDescriptorMap>(input: HikouteiEntityDescriptorInput<Name, Properties>): HikouteiEntity<HikouteiEntityInstance<Properties>, Name>;
 /**

package/dist/contracts/api/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/api/entity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/api/entity.ts"],"names":[],"mappings":"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"}

package/dist/contracts/api/entity.js

@@ -81,11 +81,16 @@ const ALLOWED_PROPERTY_OPTION_KEYS = new Set([
  * Validates a scalar entity descriptor and returns a stable entity token.
  *
  * Throws a typed `HikouteiError` for an empty name or table name, an invalid
- * table identifier, a missing or duplicate primary key, a non-string primary
- * key, a non-scalar property type, or any unsupported relation/provider option.
- * The returned token is safe to pass to `createTypedSheets({ entities })`, and
- * is also registered so a later `createTypedSheets()` call that omits
- * `entities` can use it as the default entity set.
+ * table identifier, a missing or duplicate primary key, a non-string/number
+ * primary key, a non-scalar property type, or any unsupported
+ * relation/provider option. The returned token is safe to pass to
+ * `createTypedSheets({ entities })`, and is also registered so a later
+ * `createTypedSheets()` call that omits `entities` can use it as the default
+ * entity set.
+ *
+ * A `string` primary key stays a TEXT column with application-assigned IDs.
+ * A `number` primary key becomes an INTEGER AUTOINCREMENT column so SQLite
+ * assigns the numeric ID when the app omits it at insert.
  */
 export function defineTypedSheetsEntity(input) {
     const entity = new HikouteiEntity(resolveEntityDescriptor(input));
@@ -131,8 +136,9 @@ export function resolveEntityDescriptor(input) {
         throwInvalid(`entity "${name}" must declare exactly one primary key.`);
     }
     const primaryProperty = findProperty(properties, primaryKey);
-    if (primaryProperty.type !== HIKOUTEI_SCALAR_TYPES.STRING) {
-        throwInvalid(`entity "${name}" primary key "${primaryKey}" must be a string scalar in v1.`);
+    if (primaryProperty.type !== HIKOUTEI_SCALAR_TYPES.STRING &&
+        primaryProperty.type !== HIKOUTEI_SCALAR_TYPES.NUMBER) {
+        throwInvalid(`entity "${name}" primary key "${primaryKey}" must be a string or number scalar in v1.`);
     }
     return { name, tableName, primaryKey, properties };
 }
@@ -176,18 +182,20 @@ function resolveProperty(propertyName, options) {
     return {
         name: propertyName,
         type,
-        storageType: toStorageType(type),
+        storageType: toStorageType(type, primary),
         primary,
         nullable,
         unique,
     };
 }
-function toStorageType(type) {
+function toStorageType(type, primary) {
     switch (type) {
         case HIKOUTEI_SCALAR_TYPES.STRING:
             return "TEXT";
         case HIKOUTEI_SCALAR_TYPES.NUMBER:
-            return "REAL";
+            // A numeric primary key is the SQLite-generated identity (INTEGER
+            // PRIMARY KEY AUTOINCREMENT); non-primary numbers stay REAL floats.
+            return primary ? "INTEGER" : "REAL";
         case HIKOUTEI_SCALAR_TYPES.BOOLEAN:
             return "INTEGER";
         case HIKOUTEI_SCALAR_TYPES.DATE:

package/dist/contracts/api/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/api/entity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/api/entity.ts"],"names":[],"mappings":"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"}

package/dist/contracts/sync-orm/mapping/identity.d.ts

@@ -6,13 +6,18 @@
  */
 import type { TypedSheetsEntityMapping } from "./contracts.js";
 /** Derives the stable row-binding ID shared by an entity's physical projections. */
-export declare function typedSheetsEntityRowBindingId(mapping: TypedSheetsEntityMapping, entityId: string): string;
+export declare function typedSheetsEntityRowBindingId(mapping: TypedSheetsEntityMapping, entityId: string | number): string;
 /** Derives and validates the projection anchor for one canonical entity. */
-export declare function typedSheetsEntityAnchor(mapping: TypedSheetsEntityMapping, entityId: string): string;
-/** Reads the mapping's string primary key from a pending entity change. */
+export declare function typedSheetsEntityAnchor(mapping: TypedSheetsEntityMapping, entityId: string | number): string;
+/** Reads the mapping's primary key from a pending entity change.
+ *
+ * Accepts a non-empty string or a safe-integer number and normalizes both to
+ * the single canonical string form (`String(id)`) so Sheets, canonical
+ * state, and observation agree on `42` vs `"42"`.
+ */
 export declare function typedSheetsEntityId(mapping: TypedSheetsEntityMapping, entity: object): string;
 /** Converts a visible entity ID into the canonical ID used by sync state. */
-export declare function typedSheetsCanonicalEntityId(mapping: TypedSheetsEntityMapping, entityId: string): string;
+export declare function typedSheetsCanonicalEntityId(mapping: TypedSheetsEntityMapping, entityId: string | number): string;
 /** Converts a canonical sync identity back to the entity-table primary key. */
-export declare function typedSheetsEntityIdFromCanonical(mapping: TypedSheetsEntityMapping, entityId: string): string;
+export declare function typedSheetsEntityIdFromCanonical(mapping: TypedSheetsEntityMapping, entityId: string | number): string;
 //# sourceMappingURL=identity.d.ts.map

package/dist/contracts/sync-orm/mapping/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/sync-orm/mapping/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GACf,MAAM,CAMR;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CASR;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED,+EAA+E;AAC/E,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/sync-orm/mapping/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,CAMR;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CAGR;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,CAKR;AAED,+EAA+E;AAC/E,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,CAKR"}