@aigne/afs-did-space 1.12.0-beta.5

package/dist/changelog-schema.cjs

@@ -0,0 +1,603 @@
+
+//#region src/changelog-schema.ts
+/**
+* Changelog table schema — single source of truth for the four runtimes:
+*   - D1 (Cloudflare Worker)         : migrations/0008_changelog.sql + d1-tree-index.ts
+*   - desktop SQLite (libsql)        : metadata-db.ts ensureChangelogTable()
+*   - Swift SQLite (mobile)          : SQLiteTreeIndex.swift migrate()
+*   - Kotlin SQLite (mobile)         : SQLiteTreeIndex.kt migrate()
+*
+* The CI parity script (`scripts/check-changelog-ddl-parity.ts`) reads the
+* DDL strings out of all four locations, normalises whitespace, lower-cases
+* keywords/identifiers, and asserts byte equality.
+*
+* **Do not edit any of those four sources without updating the others.**
+*
+* Phase 2 Task 2.1 introduces the schema only — `put`/`delete` start writing
+* changelog rows in Task 2.4. Until then the table sits empty.
+*/
+/** CREATE TABLE statement. Idempotent (`IF NOT EXISTS`). */
+const CHANGELOG_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_changelog (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope TEXT NOT NULL,
+  path TEXT NOT NULL,
+  op TEXT NOT NULL,
+  cid TEXT,
+  old_cid TEXT,
+  size INTEGER,
+  mtime INTEGER NOT NULL,
+  device_id TEXT NOT NULL,
+  CHECK (op IN ('put', 'delete'))
+)`;
+/**
+* CREATE INDEX statements. Order matches migration file.
+*
+* The cid / old_cid indexes are **scope-composite** (`(scope, cid)` /
+* `(scope, old_cid)`), NOT bare `(cid)` / `(old_cid)`: the only readers are
+* `isReferenced` / `isReferencedMany`, which ALWAYS filter `scope = ?` (read-
+* auth, design §7.2). A bare-cid index forces the `cid IN (…)` seek to fan out
+* across every scope + the whole append-only history (Model B global object
+* pool) and residual-filter scope afterwards — the 7180× rows_read blow-up on
+* staging D1. Leading `scope` collapses the seek to one user's rows. No live
+* SCOPE-BLIND reader exists (GC liveness uses entries-only `referencedAnywhere`;
+* the scope-blind three-way `D1GCQueue.isReferenced` is retired), so these
+* replace the old globals rather than adding to them — index count unchanged,
+* no extra write-amplification on the hot append-only changelog.
+*/
+const CHANGELOG_INDEX_SQL = [
+	"CREATE INDEX IF NOT EXISTS idx_changelog_scope_seq ON ds_changelog(scope, seq)",
+	"CREATE INDEX IF NOT EXISTS idx_changelog_scope_cid ON ds_changelog(scope, cid) WHERE cid IS NOT NULL",
+	"CREATE INDEX IF NOT EXISTS idx_changelog_scope_old_cid ON ds_changelog(scope, old_cid) WHERE old_cid IS NOT NULL"
+];
+/**
+* Migration 0110 — swap the legacy bare-cid changelog indexes for the
+* scope-composite ones above. An explicit `DROP` is required: `CREATE INDEX
+* IF NOT EXISTS idx_changelog_scope_cid …` lands the new index on fresh DBs,
+* but an already-deployed DB carries the OLD `idx_changelog_cid` / `_old_cid`
+* names — those must be dropped or they linger as orphan indexes, still
+* maintained on every changelog insert. Fresh DBs apply the regenerated 0100
+* (new names) THEN this (DROP no-ops on the absent old names, CREATE no-ops on
+* the already-present new ones) → idempotent both ways. Sourced here so the
+* migration and `ensureTable` share one definition. D1 + Node libsql only
+* (mobile single-device runtimes have no scope selectivity to gain).
+*/
+const CHANGELOG_SCOPE_CID_MIGRATION_SQL = [
+	"DROP INDEX IF EXISTS idx_changelog_cid",
+	"DROP INDEX IF EXISTS idx_changelog_old_cid",
+	"CREATE INDEX IF NOT EXISTS idx_changelog_scope_cid ON ds_changelog(scope, cid) WHERE cid IS NOT NULL",
+	"CREATE INDEX IF NOT EXISTS idx_changelog_scope_old_cid ON ds_changelog(scope, old_cid) WHERE old_cid IS NOT NULL"
+];
+/**
+* Combined DDL block (table + indices), separated by `;\n`.
+*
+* This is the canonical form against which Swift/Kotlin literals and the
+* migration SQL file are compared. The parity script normalises whitespace
+* and case before byte-comparing, so reformatting any one location is fine
+* as long as the SQL semantics stay identical.
+*/
+const CHANGELOG_DDL = [CHANGELOG_TABLE_SQL, ...CHANGELOG_INDEX_SQL].join(";\n");
+/**
+* Phase 2 Task 2.2 — `device_sync_state` table (D1 only).
+*
+* Worker-side per-device sync progress tracker. Unlike `changelog`, this
+* table lives ONLY in Cloudflare D1; mobile runtimes do not mirror it.
+* Each row records the highest changelog.seq a device has acknowledged
+* plus heartbeat timestamps.
+*
+* Columns:
+*   - scope         : DID Space scope (matches changelog.scope semantics)
+*   - device_id     : opaque device identifier from request header
+*   - last_seq      : highest changelog.seq this device has consumed
+*   - last_sync_at  : unix millis of last successful advancement of last_seq
+*   - last_seen_at  : unix millis of most recent heartbeat / HTTP touch
+*
+* Composite PRIMARY KEY `(scope, device_id)` means the table is a regular
+* rowid table (no WITHOUT ROWID) so row updates stay cheap.
+*
+* NOT parity-checked by `scripts/check-changelog-ddl-parity.ts` — this DDL
+* is D1-only. Kept here beside `CHANGELOG_*` so the full D1 schema sits in
+* one file for future readers.
+*/
+const DEVICE_SYNC_STATE_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_device_sync_state (
+  scope TEXT NOT NULL,
+  device_id TEXT NOT NULL,
+  last_seq INTEGER NOT NULL DEFAULT 0,
+  last_sync_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  PRIMARY KEY (scope, device_id)
+)`;
+/** CREATE INDEX statements for `device_sync_state`. Order matches migration. */
+const DEVICE_SYNC_STATE_INDEX_SQL = ["CREATE INDEX IF NOT EXISTS idx_device_sync_state_scope_last_seen ON ds_device_sync_state(scope, last_seen_at)"];
+/**
+* Phase 2 Task 2.3 — `scope_meta` table (D1 only).
+*
+* Per-scope compaction metadata for the Cloudflare Worker. One row per
+* DID Space scope. Written by G16 emergency compaction; read by the
+* G5.a sync endpoint to decide whether to 409 incoming pulls whose
+* `since` sits below the compaction watermark.
+*
+* Columns:
+*   - scope                  : DID Space scope (matches changelog.scope)
+*   - compacted_below_seq    : highest seq that has been compacted away;
+*                              incoming syncs with since < this value
+*                              must receive a 409 requireFullResync.
+*                              Monotonically non-decreasing.
+*   - last_compaction_at     : unix millis of most recent compaction pass
+*   - total_changelog_writes : running counter of changelog rows ever
+*                              written to this scope (deletes do NOT
+*                              decrement); used by G16 to decide when to
+*                              trigger emergency compaction
+*   - file_count             : live count of `kind='file'` rows in `entries`
+*                              for this scope. Maintained by the two
+*                              `trg_entries_file_count_*` triggers below so
+*                              the per-write capacity guard reads ONE row
+*                              instead of a full-scope `COUNT(*)` scan (the
+*                              O(N²) rows_read blow-up that exhausted the D1
+*                              free tier during bulk sync). UNLIKE
+*                              total_changelog_writes, deletes DO decrement it
+*                              (floored at 0).
+*
+* Scopes are lazy-initialised: the row is NOT created on first changelog
+* write. It's only materialised when compaction first runs for the
+* scope. The `getCompactedBelowSeq` helper returns 0 for missing rows —
+* the correct "nothing compacted yet" sentinel.
+*
+* PRIMARY KEY on `scope` makes this a regular rowid table; no secondary
+* indices are needed since all lookups are by PK.
+*
+* NOT parity-checked by `scripts/check-changelog-ddl-parity.ts` — this
+* DDL is D1-only (mobile runtimes do not mirror it). Kept here beside
+* `CHANGELOG_*` and `DEVICE_SYNC_STATE_*` so the full D1 schema sits in
+* one file for future readers.
+*/
+const SCOPE_META_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_scope_meta (
+  scope TEXT PRIMARY KEY,
+  compacted_below_seq INTEGER NOT NULL DEFAULT 0,
+  last_compaction_at INTEGER NOT NULL DEFAULT 0,
+  total_changelog_writes INTEGER NOT NULL DEFAULT 0,
+  file_count INTEGER NOT NULL DEFAULT 0
+)`;
+/**
+* Additive ALTER for the `total_bytes` running-total (upload-limits Phase 5,
+* byte-quota D3). total_bytes is added ONLY via this ALTER — NOT in the CREATE
+* TABLE above — so the single migration that introduces it works on BOTH a
+* fresh DB and an already-deployed scope_meta (an `ADD COLUMN` in the CREATE
+* would collide with the migration's ALTER on a fresh DB; the runner is not
+* idempotent on "duplicate column"). The runtime probe-then-ALTER in
+* D1TreeIndex.ensureTable applies it to fresh test/dev DBs; production deploys
+* apply the generated migration. Defaulted + NOT NULL → safe additive ALTER.
+*/
+const SCOPE_META_TOTAL_BYTES_COLUMN_SQL = "ALTER TABLE ds_scope_meta ADD COLUMN total_bytes INTEGER NOT NULL DEFAULT 0";
+/**
+* Trigger that keeps `scope_meta.file_count` incrementing in lock-step with
+* new `kind='file'` rows in `entries`. It exists so the capacity guard in
+* `D1TreeIndex.put()` can read a single `scope_meta` row instead of issuing a
+* full-scope `SELECT COUNT(*) FROM entries` on every new-file write — that
+* scan read the WHOLE scope each time, turning a bulk sync of N files into
+* ~N²/2 D1 `rows_read` and blowing past the free-tier 5M/day ceiling.
+*
+* INCREMENT via trigger; DECREMENT in app code — asymmetric on purpose.
+* Cloudflare's D1 counts a statement's TRIGGER side-effects in `meta.changes`
+* (verified on workerd: deleting 2 files + 1 dir with an AFTER-DELETE trigger
+* reports 5, not 3). `deleteByPrefix` RETURNS `meta.changes`, so an
+* AFTER-DELETE trigger would silently inflate that documented count. Inserts
+* are safe — neither `put` nor `putBatch` reads `meta.changes` — so the
+* increment stays a trigger (covering both paths for free), while
+* `delete`/`deleteByPrefix` decrement `file_count` with their own batch
+* statement, computed atomically from the pre-delete entries state. See
+* `D1TreeIndex.delete` / `deleteByPrefix`.
+*
+* Trigger semantics:
+*   - INSERT of a `kind='file'` row → +1 (upsert creates the scope_meta row
+*     lazily on first file). Dir rows (`kind='dir'`) and `INSERT OR IGNORE`
+*     no-ops never fire. An overwrite (`ON CONFLICT DO UPDATE` on entries) is
+*     an UPDATE, not an INSERT, so it correctly leaves the count alone.
+*
+* D1-only (mobile runtimes don't mirror scope_meta). NOT parity-checked.
+*
+* NOTE: the body contains an inner `;` (required by SQLite trigger grammar).
+* Any SQL splitter that feeds this to D1 one statement at a time MUST keep
+* the `CREATE TRIGGER … BEGIN … END` block whole — see
+* `runtimes/cloudflare/scripts/apply-d1-migrations.mjs` `splitSqlStatements`.
+*/
+const SCOPE_META_FILE_COUNT_TRIGGER_SQL = [`CREATE TRIGGER IF NOT EXISTS trg_entries_file_count_insert
+   AFTER INSERT ON ds_entries WHEN NEW.kind = 'file'
+   BEGIN
+     INSERT INTO ds_scope_meta (scope, file_count) VALUES (NEW.scope, 1)
+     ON CONFLICT(scope) DO UPDATE SET file_count = file_count + 1;
+   END`];
+/**
+* Triggers that keep `scope_meta.total_bytes` (upload-limits Phase 5 byte-quota
+* D3) in lock-step with the `size` of `kind='file'` rows — mirroring the
+* file_count trigger so the byte quota reads ONE scope_meta row instead of a
+* `SELECT SUM(size)` full-scope scan (the rejected O(N) rows_read anti-pattern
+* that caused the 503, did-space-d1-filecount-fix).
+*
+*   - INSERT of a new file → `+= NEW.size` (lazy upsert of the scope_meta row).
+*   - UPDATE (overwrite, same path, new content/size) → `+= NEW.size - OLD.size`.
+*     Safe as a trigger because put/putBatch do NOT read `meta.changes` — only
+*     `deleteByPrefix` does, so DELETE decrements in app code (below), exactly
+*     like file_count. Floored at 0 against drift.
+*
+* D1-only (mobile runtimes don't mirror scope_meta). NOT parity-checked. Each
+* `CREATE TRIGGER … BEGIN … END` block has an inner `;` — keep it whole when
+* splitting SQL (see apply-d1-migrations.mjs splitSqlStatements).
+*/
+const SCOPE_META_TOTAL_BYTES_TRIGGER_SQL = [`CREATE TRIGGER IF NOT EXISTS trg_entries_total_bytes_insert
+   AFTER INSERT ON ds_entries WHEN NEW.kind = 'file'
+   BEGIN
+     INSERT INTO ds_scope_meta (scope, total_bytes) VALUES (NEW.scope, NEW.size)
+     ON CONFLICT(scope) DO UPDATE SET total_bytes = total_bytes + NEW.size;
+   END`, `CREATE TRIGGER IF NOT EXISTS trg_entries_total_bytes_update
+   AFTER UPDATE ON ds_entries WHEN NEW.kind = 'file' AND OLD.kind = 'file'
+   BEGIN
+     UPDATE ds_scope_meta SET total_bytes = MAX(0, total_bytes + NEW.size - OLD.size)
+     WHERE scope = NEW.scope;
+   END`];
+/**
+* Decrement `total_bytes` for `delete()`: subtract the file's size iff `path`
+* is currently a file. Placed BEFORE the `DELETE FROM entries` so the subquery
+* observes the pre-delete row. Floored at 0. Bind order: `(scope, path, scope)`
+* — the subquery's `(scope, path)` first, then the outer `WHERE scope`.
+*/
+const SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL = `UPDATE ds_scope_meta
+  SET total_bytes = MAX(0, total_bytes - COALESCE(
+    (SELECT size FROM ds_entries WHERE scope = ? AND path = ? AND kind = 'file'), 0
+  ))
+  WHERE scope = ?`;
+/**
+* Decrement `total_bytes` for `deleteByPrefix()`: subtract Σ size of the file
+* rows in the range. Placed BEFORE the range `DELETE` so the SUM observes the
+* pre-delete rows; scans only the deleted range. Floored at 0. Bind order:
+* `(scope, lo, hi, scope)`.
+*/
+const SCOPE_META_TOTAL_BYTES_DELETE_RANGE_SQL = `UPDATE ds_scope_meta
+  SET total_bytes = MAX(0, total_bytes - (
+    SELECT COALESCE(SUM(size), 0) FROM ds_entries INDEXED BY idx_entries_kind
+    WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'
+  ))
+  WHERE scope = ?`;
+/**
+* One-time backfill: seed `total_bytes` from the current file rows for every
+* scope. Absolute (`SET = excluded.total_bytes`) so it self-corrects against a
+* concurrent write between trigger creation and this statement. Migration-only.
+*/
+const SCOPE_META_TOTAL_BYTES_BACKFILL_SQL = `INSERT INTO ds_scope_meta (scope, total_bytes)
+  SELECT scope, COALESCE(SUM(size), 0) FROM ds_entries WHERE kind = 'file' GROUP BY scope
+  ON CONFLICT(scope) DO UPDATE SET total_bytes = excluded.total_bytes`;
+/**
+* Decrement statement for `delete()`: −1 iff `path` is currently a file.
+* Placed in the delete batch BEFORE the `DELETE FROM entries` so the EXISTS
+* subquery observes the pre-delete row. Floored at 0. Bind order:
+* `(scope, scope, path)`.
+*/
+const SCOPE_META_FILE_COUNT_DELETE_ONE_SQL = `UPDATE ds_scope_meta
+  SET file_count = MAX(0, file_count - 1)
+  WHERE scope = ? AND EXISTS (
+    SELECT 1 FROM ds_entries WHERE scope = ? AND path = ? AND kind = 'file'
+  )`;
+/**
+* Decrement statement for `deleteByPrefix()`: subtract the number of file rows
+* in the prefix range. Placed in the batch BEFORE the range `DELETE` so the
+* COUNT observes the pre-delete rows; the COUNT scans only the range being
+* deleted (never the whole scope). Floored at 0. Bind order:
+* `(scope, scope, lo, hi)`.
+*/
+const SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL = `UPDATE ds_scope_meta
+  SET file_count = MAX(0, file_count - (
+    SELECT COUNT(*) FROM ds_entries
+    WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'
+  ))
+  WHERE scope = ?`;
+/**
+* One-time backfill: seed `file_count` from the current `entries` rows for
+* every scope that already has files. Absolute (`SET = excluded.file_count`,
+* not `+=`) so it is self-correcting if a concurrent write fires a trigger
+* between trigger creation and this statement. Migration-only — fresh DBs
+* (tests / first deploy) start empty and need no backfill.
+*/
+const SCOPE_META_FILE_COUNT_BACKFILL_SQL = `INSERT INTO ds_scope_meta (scope, file_count)
+  SELECT scope, COUNT(*) FROM ds_entries WHERE kind = 'file' GROUP BY scope
+  ON CONFLICT(scope) DO UPDATE SET file_count = excluded.file_count`;
+/**
+* CREATE INDEX statements for `scope_meta`. Empty by design — lookups are
+* always by the PRIMARY KEY, so the autogenerated PK index is sufficient.
+* Exported as an empty array for symmetry with `CHANGELOG_INDEX_SQL` and
+* `DEVICE_SYNC_STATE_INDEX_SQL` so callers can loop uniformly.
+*/
+const SCOPE_META_INDEX_SQL = [];
+/**
+* Live Update Resilience Phase 0 (DEC-7 / design §11.4) — `prefix_watermark`.
+*
+* Per-`(scope, prefix)` monotonic write counter. `prefix` is the FIRST path
+* segment of a write path (the `/user` first-level collection root, e.g.
+* `items`, `tags`). Every file write/delete INSIDE a collection (`depth >= 2`)
+* bumps the matching row's `version` by 1, in the SAME D1 batch as the
+* changelog INSERT (typical +1 row write-amplification).
+*
+* Web live-update reconcile reads ONE row (`SELECT version WHERE scope=? AND
+* prefix=?`) to decide "did my list change?" — true O(1), independent of
+* changelog history size or global write activity (the append-only changelog
+* `drain` would be `O(global increment)` rows_read and hit the D1 cliff; see
+* design §11.1-11.3 for the rejected alternatives B/D).
+*
+* `version` is prefix-LOCAL: it only counts writes to THIS collection root, so
+* exposing it as the wire `liveSeq` never leaks another blocklet's timing
+* (invariant I3). It is a plain monotonic counter, so `+1` gap detection works
+* within a prefix (Phase 3 push self-check).
+*
+* NOT parity-checked by `scripts/check-changelog-ddl-parity.ts` — this table is
+* D1-only (Cloudflare) + Node sqlite. Mobile (Swift/Kotlin) does NOT mirror it:
+* mobile sync drains the changelog and never reads the watermark. Same handling
+* as `scope_meta` / `device_sync_state` above.
+*/
+const PREFIX_WATERMARK_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_prefix_watermark (
+  scope TEXT NOT NULL,
+  prefix TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (scope, prefix)
+)`;
+/**
+* Upsert that bumps a prefix's watermark by 1 (lazily creating the row at
+* version 1). Bind order: `(scope, prefix)`. Placed in the SAME batch as the
+* changelog INSERT so a write and its watermark bump commit atomically.
+*/
+const PREFIX_WATERMARK_BUMP_SQL = `INSERT INTO ds_prefix_watermark (scope, prefix, version)
+  VALUES (?, ?, 1)
+  ON CONFLICT(scope, prefix) DO UPDATE SET version = version + 1`;
+/**
+* Read the current watermark `version` for a `(scope, prefix)`. Bind order:
+* `(scope, prefix)`. Missing row ⇒ no result ⇒ caller treats as version 0
+* ("nothing written under this collection root yet").
+*/
+const PREFIX_WATERMARK_READ_SQL = `SELECT version FROM ds_prefix_watermark
+  WHERE scope = ? AND prefix = ?`;
+/**
+* Instance-space layout marker. Both `CloudflareDIDSpace.getInstanceSpace`
+* and the local backend mount blocklet fragments behind a `PrefixedTreeIndex`
+* whose prefix is `blocklets/{instanceDid}/{role}/` — so the scope-relative
+* paths this module sees for ALL instance-space traffic share the first
+* segment `blocklets`. A first-segment watermark key would therefore collapse
+* every collection of every blocklet (and every role) into ONE row per scope:
+* a cross-blocklet timing leak (invariant I3) plus a false-trigger refetch of
+* every open list on any write anywhere in the space (observed on staging CF
+* 2026-06-10: `/user/items`, `/user/tags` and `/user/collections` all reported
+* the same liveSeq). Under this layout the collection root is segment 4
+* (`blocklets/{i}/{role}/items`), not segment 1.
+*/
+const INSTANCE_LAYOUT_MARKER = "blocklets";
+/** Segments forming the fragment root: `blocklets/{instanceDid}/{role}`. */
+const INSTANCE_LAYOUT_ROOT_SEGMENTS = 3;
+/**
+* Extract the watermark prefix (the collection root) from a scope-relative
+* tree path.
+*
+* Applied SYMMETRICALLY on the write side (which collection root does this
+* write bump?) and the read side (which row does this list read?), so the two
+* always agree regardless of how deeply the path nests — `items/X/y.json`,
+* `items/X`, and `items` all map to `items`. Paths under the instance-space
+* layout (`blocklets/{i}/{role}/...`) resolve to the per-fragment collection
+* root `blocklets/{i}/{role}/<root>` — both sides of a `PrefixedTreeIndex`
+* mount see the same prefixed path, so symmetry holds there too, now at the
+* REAL collection-root granularity (prefix-local, I3).
+*
+* Returns `null` when the path has no collection root (`""`, `"foo.json"`,
+* or a bare fragment root like `blocklets/i/user`) — such lists expose no
+* `liveSeq` (consumer falls back to full re-list).
+*/
+function watermarkPrefix(treePath) {
+	const segments = treePath.split("/").filter(Boolean);
+	if (segments[0] === INSTANCE_LAYOUT_MARKER) return segments.length >= INSTANCE_LAYOUT_ROOT_SEGMENTS + 1 ? segments.slice(0, INSTANCE_LAYOUT_ROOT_SEGMENTS + 1).join("/") : null;
+	return segments[0] ?? null;
+}
+/**
+* Write-side gate: a write bumps a watermark only when it lands INSIDE a
+* collection root. Generically that means `depth >= 2` (a root-level file
+* `foo.json` is not a collection); under the instance-space layout the same
+* rule applies relative to the fragment root — `blocklets/i/user/foo.json`
+* (a file directly at the role root) is not inside a collection either.
+* Returns the prefix to bump, or `null` to skip.
+*/
+function watermarkWritePrefix(treePath) {
+	const segments = treePath.split("/").filter(Boolean);
+	if (segments[0] === INSTANCE_LAYOUT_MARKER) return segments.length >= INSTANCE_LAYOUT_ROOT_SEGMENTS + 2 ? segments.slice(0, INSTANCE_LAYOUT_ROOT_SEGMENTS + 1).join("/") : null;
+	if (segments.length < 2) return null;
+	return segments[0] ?? null;
+}
+/**
+* Phase 3 Task 3.4 — `sync_state` local key-value table.
+*
+* Per-scope progress tracker for the local SyncEngine. Lives in the SAME
+* SQLite DB as `changelog` on desktop (via MetadataDB) and mobile (via
+* SQLiteTreeIndex). Byte-identical DDL across runtimes so the three-way
+* parity script can treat it the same way as `changelog`.
+*
+* Schema (Task 3.4 minimum):
+*   key   : `{scope}:local_seq` — max seq this device has pushed to cloud
+*   key   : `{scope}:cloud_seq` — max seq pulled/applied from other devices
+*
+* Task 3.5 extends usage with more keys (device_id, last_sync_at, sync_status)
+* backed by Keychain/Keystore on mobile. The table shape is unchanged — only
+* the set of keys written to it grows.
+*
+* Values are always TEXT (SQLite's universal type). Integer keys like
+* `local_seq` are stored as decimal strings and parsed at read time. This
+* keeps the schema a single source of truth regardless of how many key types
+* Task 3.5 adds later.
+*
+* Scope-prefixed keys let multiple DID Space scopes share the same SQLite DB
+* without colliding — matching the existing scope isolation in the changelog
+* table.
+*/
+const SYNC_STATE_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_sync_state (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)`;
+/** CREATE INDEX statements for `sync_state`. Empty by design — lookups are by PK. */
+const SYNC_STATE_INDEX_SQL = [];
+/**
+* Combined DDL for the sync_state table + indices. Exported for the same
+* three-way parity reasons as `CHANGELOG_DDL` — Swift and Kotlin each embed
+* a byte-identical literal that must match this string after normalisation.
+*/
+const SYNC_STATE_DDL = [SYNC_STATE_TABLE_SQL, ...SYNC_STATE_INDEX_SQL].join(";\n");
+/**
+* Whitespace+case normaliser used by the parity script and tests.
+*
+* Strategy:
+*   1. Strip SQL line comments (`-- ...` to end of line).
+*   2. Strip C-style block comments (`/* ... *​/`) — defensive, none currently.
+*   3. Lower-case everything (SQLite keywords + identifiers are case-insensitive).
+*   4. Strip ALL `;` characters — different sources may add/omit a trailing
+*      semicolon on the last statement; semantically equivalent so we drop them.
+*   5. Collapse any whitespace run (spaces, tabs, newlines) into a single space.
+*   6. Trim leading/trailing whitespace.
+*   7. Remove spaces immediately around `(`, `)`, `,` so that
+*      `changelog(scope, seq)` and `changelog ( scope , seq )` compare equal.
+*
+* Note: this is intentionally conservative — string literals like `'put'` and
+* `'delete'` already happen to be lower-case, and SQLite treats string values
+* as case-sensitive. If a future column ever needed mixed-case literals, we
+* would have to mask string-literal regions before lower-casing.
+*/
+function normalizeDdl(input) {
+	return input.replace(/--[^\n]*/g, " ").replace(/\/\*[\s\S]*?\*\//g, " ").toLowerCase().replace(/;/g, " ").replace(/\s+/g, " ").trim().replace(/\s*([(),])\s*/g, "$1");
+}
+/** `kind` discriminator for a changelog row entry on the sync wire. */
+const CHANGELOG_ROW_KIND = "did-space:changelog-row";
+/** `kind` discriminator for a manifest file entry on the sync wire. */
+const MANIFEST_FILE_KIND = "did-space:file";
+/**
+* Field list for a changelog row's `meta.extra` (canonical sync wire).
+* Order is documentary only — consumers read by key, never by position.
+*/
+const CHANGELOG_WIRE_EXTRA_FIELDS = [
+	"seq",
+	"op",
+	"originalPath",
+	"cid",
+	"oldCid",
+	"size",
+	"mtime",
+	"deviceId"
+];
+/** Field list for a manifest entry's `meta.extra` (canonical sync wire). */
+const MANIFEST_WIRE_EXTRA_FIELDS = ["cid", "mtime"];
+/**
+* Serialize a changelog row to its canonical `meta.extra` payload. The provider
+* wraps this as `meta: { kind: CHANGELOG_ROW_KIND, extra: serializeChangelogEntry(row) }`.
+*/
+function serializeChangelogEntry(row) {
+	return {
+		seq: row.seq,
+		op: row.op,
+		originalPath: row.path,
+		cid: row.cid ?? null,
+		oldCid: row.old_cid ?? null,
+		size: row.size ?? null,
+		mtime: row.mtime,
+		deviceId: row.device_id
+	};
+}
+/**
+* Serialize a manifest file entry to its canonical `meta`. `cid` is emitted at
+* BOTH top-level and `extra.cid` (additive — see module header).
+*/
+function serializeManifestEntry(row) {
+	const meta = {
+		kind: MANIFEST_FILE_KIND,
+		cid: row.cid,
+		size: row.size,
+		extra: {
+			cid: row.cid,
+			mtime: row.mtime
+		}
+	};
+	if (row.mimeType !== void 0) meta.mimeType = row.mimeType;
+	return meta;
+}
+/** Coerce an unknown into a finite number, or `fallback` when not coercible. */
+function asNumber(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+/** Coerce an unknown into a non-empty string, or `null`. */
+function asStringOrNull(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+* Parse an untrusted changelog `meta.extra` bag into a typed {@link ChangelogWireExtra}.
+* Returns `null` when required fields (`op`, `originalPath`) are missing/invalid —
+* a malformed row is skipped, never crashes the parser. Numeric/optional fields
+* degrade to safe defaults (`seq=0`, `cid=null`, …).
+*/
+function parseChangelogEntry(extra) {
+	if (!extra || typeof extra !== "object") return null;
+	const e = extra;
+	const op = e.op;
+	if (op !== "put" && op !== "delete") return null;
+	const originalPath = typeof e.originalPath === "string" ? e.originalPath : null;
+	if (originalPath === null) return null;
+	const deviceId = typeof e.deviceId === "string" ? e.deviceId : "";
+	return {
+		seq: asNumber(e.seq, 0),
+		op,
+		originalPath,
+		cid: asStringOrNull(e.cid),
+		oldCid: asStringOrNull(e.oldCid),
+		size: typeof e.size === "number" && Number.isFinite(e.size) ? e.size : null,
+		mtime: asNumber(e.mtime, 0),
+		deviceId
+	};
+}
+/**
+* Parse an untrusted manifest entry `meta` into its canonical `{ cid, mtime }`.
+* Reads `extra.cid` FIRST (canonical, all-runtime), falling back to top-level
+* `meta.cid` (additive). Returns `null` when no cid is resolvable.
+*/
+function parseManifestEntry(meta) {
+	if (!meta || typeof meta !== "object") return null;
+	const m = meta;
+	const extra = m.extra ?? {};
+	const cid = typeof extra.cid === "string" && extra.cid.length > 0 ? extra.cid : typeof m.cid === "string" && m.cid.length > 0 ? m.cid : null;
+	if (cid === null) return null;
+	return {
+		cid,
+		mtime: asNumber(extra.mtime, 0)
+	};
+}
+
+//#endregion
+exports.CHANGELOG_DDL = CHANGELOG_DDL;
+exports.CHANGELOG_INDEX_SQL = CHANGELOG_INDEX_SQL;
+exports.CHANGELOG_ROW_KIND = CHANGELOG_ROW_KIND;
+exports.CHANGELOG_SCOPE_CID_MIGRATION_SQL = CHANGELOG_SCOPE_CID_MIGRATION_SQL;
+exports.CHANGELOG_TABLE_SQL = CHANGELOG_TABLE_SQL;
+exports.CHANGELOG_WIRE_EXTRA_FIELDS = CHANGELOG_WIRE_EXTRA_FIELDS;
+exports.DEVICE_SYNC_STATE_INDEX_SQL = DEVICE_SYNC_STATE_INDEX_SQL;
+exports.DEVICE_SYNC_STATE_TABLE_SQL = DEVICE_SYNC_STATE_TABLE_SQL;
+exports.MANIFEST_FILE_KIND = MANIFEST_FILE_KIND;
+exports.MANIFEST_WIRE_EXTRA_FIELDS = MANIFEST_WIRE_EXTRA_FIELDS;
+exports.PREFIX_WATERMARK_BUMP_SQL = PREFIX_WATERMARK_BUMP_SQL;
+exports.PREFIX_WATERMARK_READ_SQL = PREFIX_WATERMARK_READ_SQL;
+exports.PREFIX_WATERMARK_TABLE_SQL = PREFIX_WATERMARK_TABLE_SQL;
+exports.SCOPE_META_FILE_COUNT_BACKFILL_SQL = SCOPE_META_FILE_COUNT_BACKFILL_SQL;
+exports.SCOPE_META_FILE_COUNT_DELETE_ONE_SQL = SCOPE_META_FILE_COUNT_DELETE_ONE_SQL;
+exports.SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL = SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL;
+exports.SCOPE_META_FILE_COUNT_TRIGGER_SQL = SCOPE_META_FILE_COUNT_TRIGGER_SQL;
+exports.SCOPE_META_INDEX_SQL = SCOPE_META_INDEX_SQL;
+exports.SCOPE_META_TABLE_SQL = SCOPE_META_TABLE_SQL;
+exports.SCOPE_META_TOTAL_BYTES_BACKFILL_SQL = SCOPE_META_TOTAL_BYTES_BACKFILL_SQL;
+exports.SCOPE_META_TOTAL_BYTES_COLUMN_SQL = SCOPE_META_TOTAL_BYTES_COLUMN_SQL;
+exports.SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL = SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL;
+exports.SCOPE_META_TOTAL_BYTES_DELETE_RANGE_SQL = SCOPE_META_TOTAL_BYTES_DELETE_RANGE_SQL;
+exports.SCOPE_META_TOTAL_BYTES_TRIGGER_SQL = SCOPE_META_TOTAL_BYTES_TRIGGER_SQL;
+exports.SYNC_STATE_DDL = SYNC_STATE_DDL;
+exports.SYNC_STATE_INDEX_SQL = SYNC_STATE_INDEX_SQL;
+exports.SYNC_STATE_TABLE_SQL = SYNC_STATE_TABLE_SQL;
+exports.normalizeDdl = normalizeDdl;
+exports.parseChangelogEntry = parseChangelogEntry;
+exports.parseManifestEntry = parseManifestEntry;
+exports.serializeChangelogEntry = serializeChangelogEntry;
+exports.serializeManifestEntry = serializeManifestEntry;
+exports.watermarkPrefix = watermarkPrefix;
+exports.watermarkWritePrefix = watermarkWritePrefix;