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

package/dist/versioned-scope.d.cts

@@ -0,0 +1,57 @@
+//#region src/versioned-scope.d.ts
+/**
+ * Versioned scope keys — Layer 1 generic contract (versioned package-content
+ * materialization, design §1.6/§0.4).
+ *
+ * A versioned content index materializes immutable, per-version package
+ * content (one "kind" of content per consumer) into a shared store keyed by:
+ *
+ *     <kind>:<packageId>:<versionToken>
+ *
+ * The ingest / stale-check / cleanup machinery is KIND-AGNOSTIC — a new
+ * consumer picks a kind (e.g. `schema`, `locale`, `aup`, `seo`) and supplies
+ * a source-path mapping; the machinery never interprets the kind.
+ *
+ * Key contract (anti-collision + hot-path exactness):
+ *   - The hot path looks rows up by EXACT scope key — no LIKE, no prefix scan,
+ *     no injection surface. Therefore key construction MUST be unambiguous:
+ *     components are percent-escaped (`%`, `:`, `/`) before joining.
+ *   - `versionToken` = the package manifest's `version` when present;
+ *     otherwise the content digest (`seedDigest`). NEVER an empty string or
+ *     a stringified `undefined` (that would collide all unversioned packages).
+ *   - `seedDigest` is NOT part of the key — it lives in an independent
+ *     metadata column on the scope row, consulted only by dev-mode stale
+ *     detection. Prod never computes digests on the read path.
+ *   - Package identity is `{ id: manifest.id, version?: manifest.version }`
+ *     (NOT `manifest.did` — that is a reserved field the runtime does not
+ *     consume).
+ */
+/** Package identity for versioned-content scoping. */
+interface VersionedPackageIdentity {
+  /** `manifest.id` — e.g. `"nimbus-demo"`. */
+  id: string;
+  /** `manifest.version` when the package declares one. */
+  version?: string;
+}
+/**
+ * Build the canonical `<kind>:<packageId>:<versionToken>` scope key.
+ * Components are escaped so a separator INSIDE a component can never collide
+ * with the separator BETWEEN components. Throws on empty/non-string input.
+ */
+declare function versionedScope(kind: string, packageId: string, versionToken: string): string;
+/**
+ * Build the group key for a (kind, packageId) pair — the same escaped prefix
+ * a {@link versionedScope} key starts with, WITHOUT the version token. Used
+ * as the opaque cleanup unit: building a new version's scope supersedes every
+ * sibling scope sharing this group.
+ */
+declare function versionedScopeGroup(kind: string, packageId: string): string;
+/**
+ * Resolve the version token for a package: `manifest.version` when present,
+ * else the content digest. Throws when neither exists — an empty or
+ * `"undefined"` token would collide every unversioned package into one scope.
+ */
+declare function resolveVersionToken(identity: VersionedPackageIdentity, seedDigest: string | undefined): string;
+//#endregion
+export { VersionedPackageIdentity, resolveVersionToken, versionedScope, versionedScopeGroup };
+//# sourceMappingURL=versioned-scope.d.cts.map

package/dist/versioned-scope.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-scope.d.cts","names":[],"sources":["../src/versioned-scope.ts"],"mappings":";;AA6BA;;;;;AAoBA;;;;;;;;;AAUA;;;;;AASA;;;;;;;;UAvCiB,wBAAA;;EAEf,EAAA;;EAEA,OAAA;AAAA;;;;;;iBAgBc,cAAA,CAAe,IAAA,UAAc,SAAA,UAAmB,YAAA;;;;;;;iBAUhD,mBAAA,CAAoB,IAAA,UAAc,SAAA;;;;;;iBASlC,mBAAA,CACd,QAAA,EAAU,wBAAA,EACV,UAAA"}

package/dist/versioned-scope.d.mts

@@ -0,0 +1,57 @@
+//#region src/versioned-scope.d.ts
+/**
+ * Versioned scope keys — Layer 1 generic contract (versioned package-content
+ * materialization, design §1.6/§0.4).
+ *
+ * A versioned content index materializes immutable, per-version package
+ * content (one "kind" of content per consumer) into a shared store keyed by:
+ *
+ *     <kind>:<packageId>:<versionToken>
+ *
+ * The ingest / stale-check / cleanup machinery is KIND-AGNOSTIC — a new
+ * consumer picks a kind (e.g. `schema`, `locale`, `aup`, `seo`) and supplies
+ * a source-path mapping; the machinery never interprets the kind.
+ *
+ * Key contract (anti-collision + hot-path exactness):
+ *   - The hot path looks rows up by EXACT scope key — no LIKE, no prefix scan,
+ *     no injection surface. Therefore key construction MUST be unambiguous:
+ *     components are percent-escaped (`%`, `:`, `/`) before joining.
+ *   - `versionToken` = the package manifest's `version` when present;
+ *     otherwise the content digest (`seedDigest`). NEVER an empty string or
+ *     a stringified `undefined` (that would collide all unversioned packages).
+ *   - `seedDigest` is NOT part of the key — it lives in an independent
+ *     metadata column on the scope row, consulted only by dev-mode stale
+ *     detection. Prod never computes digests on the read path.
+ *   - Package identity is `{ id: manifest.id, version?: manifest.version }`
+ *     (NOT `manifest.did` — that is a reserved field the runtime does not
+ *     consume).
+ */
+/** Package identity for versioned-content scoping. */
+interface VersionedPackageIdentity {
+  /** `manifest.id` — e.g. `"nimbus-demo"`. */
+  id: string;
+  /** `manifest.version` when the package declares one. */
+  version?: string;
+}
+/**
+ * Build the canonical `<kind>:<packageId>:<versionToken>` scope key.
+ * Components are escaped so a separator INSIDE a component can never collide
+ * with the separator BETWEEN components. Throws on empty/non-string input.
+ */
+declare function versionedScope(kind: string, packageId: string, versionToken: string): string;
+/**
+ * Build the group key for a (kind, packageId) pair — the same escaped prefix
+ * a {@link versionedScope} key starts with, WITHOUT the version token. Used
+ * as the opaque cleanup unit: building a new version's scope supersedes every
+ * sibling scope sharing this group.
+ */
+declare function versionedScopeGroup(kind: string, packageId: string): string;
+/**
+ * Resolve the version token for a package: `manifest.version` when present,
+ * else the content digest. Throws when neither exists — an empty or
+ * `"undefined"` token would collide every unversioned package into one scope.
+ */
+declare function resolveVersionToken(identity: VersionedPackageIdentity, seedDigest: string | undefined): string;
+//#endregion
+export { VersionedPackageIdentity, resolveVersionToken, versionedScope, versionedScopeGroup };
+//# sourceMappingURL=versioned-scope.d.mts.map

package/dist/versioned-scope.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-scope.d.mts","names":[],"sources":["../src/versioned-scope.ts"],"mappings":";;AA6BA;;;;;AAoBA;;;;;;;;;AAUA;;;;;AASA;;;;;;;;UAvCiB,wBAAA;;EAEf,EAAA;;EAEA,OAAA;AAAA;;;;;;iBAgBc,cAAA,CAAe,IAAA,UAAc,SAAA,UAAmB,YAAA;;;;;;;iBAUhD,mBAAA,CAAoB,IAAA,UAAc,SAAA;;;;;;iBASlC,mBAAA,CACd,QAAA,EAAU,wBAAA,EACV,UAAA"}

package/dist/versioned-scope.mjs

@@ -0,0 +1,37 @@
+//#region src/versioned-scope.ts
+/** Separator-escape: `%` → `%25`, `:` → `%3A`, `/` → `%2F`. */
+function escapeComponent(raw, name) {
+	if (typeof raw !== "string" || raw.length === 0) throw new Error(`versionedScope: ${name} must be a non-empty string`);
+	return raw.replaceAll("%", "%25").replaceAll(":", "%3A").replaceAll("/", "%2F");
+}
+/**
+* Build the canonical `<kind>:<packageId>:<versionToken>` scope key.
+* Components are escaped so a separator INSIDE a component can never collide
+* with the separator BETWEEN components. Throws on empty/non-string input.
+*/
+function versionedScope(kind, packageId, versionToken) {
+	return `${escapeComponent(kind, "kind")}:${escapeComponent(packageId, "packageId")}:${escapeComponent(versionToken, "versionToken")}`;
+}
+/**
+* Build the group key for a (kind, packageId) pair — the same escaped prefix
+* a {@link versionedScope} key starts with, WITHOUT the version token. Used
+* as the opaque cleanup unit: building a new version's scope supersedes every
+* sibling scope sharing this group.
+*/
+function versionedScopeGroup(kind, packageId) {
+	return `${escapeComponent(kind, "kind")}:${escapeComponent(packageId, "packageId")}`;
+}
+/**
+* Resolve the version token for a package: `manifest.version` when present,
+* else the content digest. Throws when neither exists — an empty or
+* `"undefined"` token would collide every unversioned package into one scope.
+*/
+function resolveVersionToken(identity, seedDigest) {
+	if (identity.version) return identity.version;
+	if (seedDigest) return seedDigest;
+	throw new Error(`versionedScope: package "${identity.id}" has neither manifest.version nor a content digest — refusing to build an ambiguous scope key`);
+}
+
+//#endregion
+export { resolveVersionToken, versionedScope, versionedScopeGroup };
+//# sourceMappingURL=versioned-scope.mjs.map

package/dist/versioned-scope.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-scope.mjs","names":[],"sources":["../src/versioned-scope.ts"],"sourcesContent":["/**\n * Versioned scope keys — Layer 1 generic contract (versioned package-content\n * materialization, design §1.6/§0.4).\n *\n * A versioned content index materializes immutable, per-version package\n * content (one \"kind\" of content per consumer) into a shared store keyed by:\n *\n *     <kind>:<packageId>:<versionToken>\n *\n * The ingest / stale-check / cleanup machinery is KIND-AGNOSTIC — a new\n * consumer picks a kind (e.g. `schema`, `locale`, `aup`, `seo`) and supplies\n * a source-path mapping; the machinery never interprets the kind.\n *\n * Key contract (anti-collision + hot-path exactness):\n *   - The hot path looks rows up by EXACT scope key — no LIKE, no prefix scan,\n *     no injection surface. Therefore key construction MUST be unambiguous:\n *     components are percent-escaped (`%`, `:`, `/`) before joining.\n *   - `versionToken` = the package manifest's `version` when present;\n *     otherwise the content digest (`seedDigest`). NEVER an empty string or\n *     a stringified `undefined` (that would collide all unversioned packages).\n *   - `seedDigest` is NOT part of the key — it lives in an independent\n *     metadata column on the scope row, consulted only by dev-mode stale\n *     detection. Prod never computes digests on the read path.\n *   - Package identity is `{ id: manifest.id, version?: manifest.version }`\n *     (NOT `manifest.did` — that is a reserved field the runtime does not\n *     consume).\n */\n\n/** Package identity for versioned-content scoping. */\nexport interface VersionedPackageIdentity {\n  /** `manifest.id` — e.g. `\"nimbus-demo\"`. */\n  id: string;\n  /** `manifest.version` when the package declares one. */\n  version?: string;\n}\n\n/** Separator-escape: `%` → `%25`, `:` → `%3A`, `/` → `%2F`. */\nfunction escapeComponent(raw: string, name: string): string {\n  if (typeof raw !== \"string\" || raw.length === 0) {\n    throw new Error(`versionedScope: ${name} must be a non-empty string`);\n  }\n  return raw.replaceAll(\"%\", \"%25\").replaceAll(\":\", \"%3A\").replaceAll(\"/\", \"%2F\");\n}\n\n/**\n * Build the canonical `<kind>:<packageId>:<versionToken>` scope key.\n * Components are escaped so a separator INSIDE a component can never collide\n * with the separator BETWEEN components. Throws on empty/non-string input.\n */\nexport function versionedScope(kind: string, packageId: string, versionToken: string): string {\n  return `${escapeComponent(kind, \"kind\")}:${escapeComponent(packageId, \"packageId\")}:${escapeComponent(versionToken, \"versionToken\")}`;\n}\n\n/**\n * Build the group key for a (kind, packageId) pair — the same escaped prefix\n * a {@link versionedScope} key starts with, WITHOUT the version token. Used\n * as the opaque cleanup unit: building a new version's scope supersedes every\n * sibling scope sharing this group.\n */\nexport function versionedScopeGroup(kind: string, packageId: string): string {\n  return `${escapeComponent(kind, \"kind\")}:${escapeComponent(packageId, \"packageId\")}`;\n}\n\n/**\n * Resolve the version token for a package: `manifest.version` when present,\n * else the content digest. Throws when neither exists — an empty or\n * `\"undefined\"` token would collide every unversioned package into one scope.\n */\nexport function resolveVersionToken(\n  identity: VersionedPackageIdentity,\n  seedDigest: string | undefined,\n): string {\n  if (identity.version) return identity.version;\n  if (seedDigest) return seedDigest;\n  throw new Error(\n    `versionedScope: package \"${identity.id}\" has neither manifest.version nor a content digest — refusing to build an ambiguous scope key`,\n  );\n}\n"],"mappings":";;AAqCA,SAAS,gBAAgB,KAAa,MAAsB;AAC1D,KAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,EAC5C,OAAM,IAAI,MAAM,mBAAmB,KAAK,6BAA6B;AAEvE,QAAO,IAAI,WAAW,KAAK,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,WAAW,KAAK,MAAM;;;;;;;AAQjF,SAAgB,eAAe,MAAc,WAAmB,cAA8B;AAC5F,QAAO,GAAG,gBAAgB,MAAM,OAAO,CAAC,GAAG,gBAAgB,WAAW,YAAY,CAAC,GAAG,gBAAgB,cAAc,eAAe;;;;;;;;AASrI,SAAgB,oBAAoB,MAAc,WAA2B;AAC3E,QAAO,GAAG,gBAAgB,MAAM,OAAO,CAAC,GAAG,gBAAgB,WAAW,YAAY;;;;;;;AAQpF,SAAgB,oBACd,UACA,YACQ;AACR,KAAI,SAAS,QAAS,QAAO,SAAS;AACtC,KAAI,WAAY,QAAO;AACvB,OAAM,IAAI,MACR,4BAA4B,SAAS,GAAG,gGACzC"}

package/migrations/0001_tree_entries.sql

@@ -0,0 +1,17 @@
+-- Migration: tree_entries table + indexes
+-- Source: D1TreeIndex.ensureTable() in d1-tree-index.ts
+
+CREATE TABLE IF NOT EXISTS tree_entries (
+  scope TEXT NOT NULL,
+  path TEXT NOT NULL,
+  cid TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  mtime INTEGER NOT NULL,
+  ctime INTEGER NOT NULL,
+  mime_type TEXT,
+  PRIMARY KEY (scope, path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tree_mtime ON tree_entries(scope, mtime);
+CREATE INDEX IF NOT EXISTS idx_tree_size ON tree_entries(scope, size);
+CREATE INDEX IF NOT EXISTS idx_tree_mime ON tree_entries(scope, mime_type);

package/migrations/0002_resolve_entries.sql

@@ -0,0 +1,7 @@
+-- Migration: resolve_entries table
+-- Source: D1ResolveStore.ensureTable() in d1-resolve-store.ts
+
+CREATE TABLE IF NOT EXISTS resolve_entries (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);

package/migrations/0003_entries_v2.sql

@@ -0,0 +1,38 @@
+-- Migration: entries table (v2) — replaces tree_entries
+-- WITHOUT ROWID for direct PK lookup (no rowid indirection)
+-- Adds parent/name/kind columns for efficient directory operations
+
+CREATE TABLE IF NOT EXISTS entries (
+  scope       TEXT    NOT NULL,
+  path        TEXT    NOT NULL,
+  parent      TEXT    NOT NULL,
+  name        TEXT    NOT NULL,
+  kind        TEXT    NOT NULL DEFAULT 'file',
+  cid         TEXT,
+  size        INTEGER NOT NULL DEFAULT 0,
+  mime_type   TEXT,
+  ctime       INTEGER NOT NULL,
+  mtime       INTEGER NOT NULL,
+  PRIMARY KEY (scope, path),
+
+  CHECK (LENGTH(path) <= 4096),
+  CHECK (LENGTH(name) <= 255),
+  CHECK (kind IN ('file', 'dir')),
+  CHECK (LENGTH(scope) <= 128)
+) WITHOUT ROWID;
+
+-- Directory listing: direct children by parent (most critical index)
+CREATE INDEX IF NOT EXISTS idx_entries_children
+  ON entries(scope, parent, name);
+
+-- CID reference queries (dedup, GC)
+CREATE INDEX IF NOT EXISTS idx_entries_cid
+  ON entries(cid) WHERE cid IS NOT NULL;
+
+-- Time-sorted queries (recent modifications, incremental sync)
+CREATE INDEX IF NOT EXISTS idx_entries_mtime
+  ON entries(scope, mtime DESC);
+
+-- Type-based statistics
+CREATE INDEX IF NOT EXISTS idx_entries_kind
+  ON entries(scope, kind);

package/migrations/0004_gc_queue.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS ds_gc_queue (
+  cid       TEXT    NOT NULL,
+  queued_at INTEGER NOT NULL,  -- Unix ms, used for grace period filtering
+  PRIMARY KEY (cid)             -- natural dedup: same CID not enqueued twice
+);

package/migrations/0006_resolve_enhance.sql

@@ -0,0 +1,14 @@
+-- Migration: resolve_entries schema enhancement
+-- Adds indexed columns to support efficient queries by owner and kind.
+-- updated_at is set by the application layer (Date.now()) on every put().
+
+ALTER TABLE resolve_entries ADD COLUMN owner TEXT;
+ALTER TABLE resolve_entries ADD COLUMN kind TEXT;
+ALTER TABLE resolve_entries ADD COLUMN updated_at INTEGER;
+
+-- Index on owner for fast per-owner lookups
+CREATE INDEX IF NOT EXISTS idx_resolve_owner ON resolve_entries(owner);
+-- Index on kind for fast filtering by entry type
+CREATE INDEX IF NOT EXISTS idx_resolve_kind ON resolve_entries(kind);
+-- Index on updated_at for time-based queries and cache invalidation
+CREATE INDEX IF NOT EXISTS idx_resolve_updated ON resolve_entries(updated_at);

package/migrations/0007_resolve_created_at.sql

@@ -0,0 +1,10 @@
+-- Phase 7: add created_at to resolve_entries (immutable, set once at insert time).
+-- For existing rows, seed created_at from updated_at (best available approximation).
+
+ALTER TABLE resolve_entries ADD COLUMN created_at INTEGER;
+
+UPDATE resolve_entries
+   SET created_at = COALESCE(updated_at, CAST(strftime('%s', 'now') AS INTEGER) * 1000)
+ WHERE created_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_resolve_created ON resolve_entries(created_at);

package/migrations/0008_changelog.sql

@@ -0,0 +1,34 @@
+-- Phase 2 Task 2.1: changelog table — event log for DID Space sync.
+--
+-- Each row records one content change (put or delete) to a DID Space scope.
+-- Consumers:
+--   - Cloudflare Worker (D1)                  — source of truth for cross-device sync
+--   - desktop SQLite (libsql, metadata-db.ts) — local mirror for offline changelog
+--   - mobile Swift SQLiteTreeIndex            — local mirror
+--   - mobile Kotlin SQLiteTreeIndex           — local mirror
+--
+-- ALL FOUR RUNTIMES MUST CREATE BYTE-IDENTICAL DDL (after whitespace+case
+-- normalisation). The CI parity check in
+-- `scripts/check-changelog-ddl-parity.ts` enforces this. See
+-- `src/changelog-schema.ts` for the shared TypeScript constants used by
+-- d1-tree-index.ts and metadata-db.ts.
+--
+-- Schema-only migration. Task 2.1 does NOT add any put/delete hooks yet —
+-- the table stays empty until Task 2.4 wires up the producer side.
+
+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 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;

package/migrations/0009_device_sync_state.sql

@@ -0,0 +1,29 @@
+-- Phase 2 Task 2.2: device_sync_state table — per-device sync progress (D1 only).
+--
+-- Each row records the highest changelog.seq a given device has acknowledged
+-- within a given DID Space scope, plus heartbeat timestamps. Used by:
+--   - Task 3.1 push subscriber     — advance last_seq on successful delivery
+--   - Task 3.7 device registration — track last_seen_at for GC strategy 1
+--   - G16 GC Strategy 1            — retention window based on last_seen_at
+--
+-- UNLIKE changelog, this table lives ONLY in D1 (Cloudflare Worker).
+-- Mobile runtimes (Swift / Kotlin / desktop) do NOT mirror it — they post
+-- heartbeats via HTTP and read their own last_seq from their local
+-- MetadataDB's changelog mirror.
+--
+-- The composite PRIMARY KEY (scope, device_id) makes this a regular rowid
+-- table (no WITHOUT ROWID), so single-row updates stay cheap. An auxiliary
+-- index on (scope, last_seen_at) supports GC scans that want to find the
+-- oldest-seen device per scope.
+
+CREATE TABLE IF NOT EXISTS 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 IF NOT EXISTS idx_device_sync_state_scope_last_seen
+  ON device_sync_state(scope, last_seen_at);

package/migrations/0010_scope_meta.sql

@@ -0,0 +1,33 @@
+-- Phase 2 Task 2.3: scope_meta table — per-scope compaction metadata (D1 only).
+--
+-- One row per DID Space scope. Tracks compaction watermark and running
+-- counters used by the sync endpoint + background GC:
+--   - G5.a sync handler         — reads compacted_below_seq; incoming pulls
+--                                 with `since < compacted_below_seq` get a
+--                                 409 requireFullResync response
+--   - G16 emergency compaction  — advances compacted_below_seq + records
+--                                 last_compaction_at when a scope exceeds
+--                                 the changelog-row ceiling
+--   - Observability/telemetry   — total_changelog_writes counts rows ever
+--                                 written (not current size — deletes don't
+--                                 decrement it)
+--
+-- UNLIKE changelog, this table lives ONLY in D1 (Cloudflare Worker).
+-- Mobile runtimes do not mirror it; they learn about compaction by
+-- receiving a 409 from the sync endpoint and falling back to a full
+-- manifest fetch.
+--
+-- Scopes are lazy-initialised: the row is NOT created on first changelog
+-- write. It's only materialised when compaction first runs for the scope.
+-- Until then, `getCompactedBelowSeq` returns 0 — the semantically correct
+-- "nothing compacted yet" sentinel.
+--
+-- PRIMARY KEY on `scope` makes this a regular rowid table; lookups are
+-- always by PK so no secondary indices are needed.
+
+CREATE TABLE IF NOT EXISTS 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
+);

package/migrations/0011_shares.sql

@@ -0,0 +1,25 @@
+-- DID Space Share index: materialised view of .share declaration files.
+-- Source of truth is R2 .share files; this table can be fully rebuilt via D1ShareReconciler.
+-- Owner-scoped identity key: UNIQUE(owner_did, decl_path). The same relative
+-- decl_path is legitimately reusable across owners that share one D1 / one
+-- daemon-global _shares.db; slug stays globally UNIQUE (public URL identifier).
+-- This file MUST stay byte-equal (after DDL normalisation) to SHARES_TABLE_SQL +
+-- SHARES_INDEX_SQL in src/d1-schema.ts — asserted by share-migration.test.ts.
+CREATE TABLE IF NOT EXISTS ds_shares (
+  id          TEXT PRIMARY KEY,             -- nanoid(21) generated at reconcile time
+  owner_did   TEXT NOT NULL,                -- from write ctx (this.did in DIDSpaceProvider)
+  source_path TEXT NOT NULL,                -- derived from .share file location
+  decl_path   TEXT NOT NULL,                -- .share file path (owner-scoped upsert key)
+  slug        TEXT NOT NULL UNIQUE,         -- public URL identifier (globally unique)
+  kind        TEXT NOT NULL DEFAULT 'raw',  -- 'raw' | 'web'
+  status      TEXT NOT NULL DEFAULT 'active', -- 'active' | 'revoked'
+  decl_cid    TEXT,                         -- CID of .share file for reconcile diff
+  config_json TEXT NOT NULL DEFAULT '{}',   -- full parsed ShareDeclaration as JSON
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL,
+  UNIQUE(owner_did, decl_path)              -- owner-scoped identity key
+);
+
+CREATE INDEX IF NOT EXISTS idx_shares_owner_did ON ds_shares(owner_did);
+CREATE INDEX IF NOT EXISTS idx_shares_owner_source ON ds_shares(owner_did, source_path);
+CREATE INDEX IF NOT EXISTS idx_shares_slug ON ds_shares(slug);

package/migrations/0012_scope_meta_file_count.sql

@@ -0,0 +1,41 @@
+-- 0012: scope_meta.file_count — O(1) capacity guard (replaces the O(N²) scan).
+--
+-- D1TreeIndex.put() used to enforce the per-scope file cap with
+-- `SELECT COUNT(*) FROM entries WHERE scope = ?` on EVERY new-file write. That
+-- scans the whole scope each time, so a bulk sync of N files reads ~N²/2 D1
+-- rows and blew past the free-tier 5M rows_read/day ceiling (503 "exceeded
+-- limit"). We replace the scan with a single `scope_meta.file_count` read.
+--
+-- INCREMENT is a trigger (covers put + putBatch for free). DECREMENT is NOT a
+-- trigger: Cloudflare D1 counts a statement's trigger side-effects in
+-- `meta.changes`, and `deleteByPrefix` returns that value, so an AFTER-DELETE
+-- trigger would inflate the documented count. `delete`/`deleteByPrefix`
+-- instead decrement file_count with their own batch statement (see
+-- d1-tree-index.ts). This file therefore creates only the INSERT trigger.
+--
+-- Provider lineage: 0010 already created scope_meta (4 columns), so this ADDS
+-- the column. The Cloudflare runtime never ran 0010 (its 0100 schema omitted
+-- scope_meta entirely) — its generated 0104_scope_meta_file_count.sql CREATEs
+-- the table with this column instead. Both end at the same shape; the SQL is
+-- sourced from the same @aigne/afs-did-space constants.
+--
+-- D1-only (mobile runtimes don't mirror scope_meta). NOT parity-checked.
+
+ALTER TABLE scope_meta ADD COLUMN file_count INTEGER NOT NULL DEFAULT 0;
+
+-- +1 on every new file row (upsert lazily creates the scope_meta row). Dir
+-- rows and INSERT-OR-IGNORE no-ops never fire; an overwrite is an UPDATE on
+-- entries, not an INSERT, so it correctly leaves the count alone.
+CREATE TRIGGER IF NOT EXISTS trg_entries_file_count_insert
+AFTER INSERT ON entries WHEN NEW.kind = 'file'
+BEGIN
+  INSERT INTO scope_meta (scope, file_count) VALUES (NEW.scope, 1)
+  ON CONFLICT(scope) DO UPDATE SET file_count = file_count + 1;
+END;
+
+-- One-time backfill for scopes that already have files. Absolute (not +=) so
+-- it is self-correcting against any write that fired the trigger between
+-- trigger creation and this statement.
+INSERT INTO scope_meta (scope, file_count)
+  SELECT scope, COUNT(*) FROM entries WHERE kind = 'file' GROUP BY scope
+  ON CONFLICT(scope) DO UPDATE SET file_count = excluded.file_count;

package/migrations/0013_scope_meta_total_bytes.sql

@@ -0,0 +1,47 @@
+-- 0013: scope_meta.total_bytes — O(1) per-scope BYTE quota running total
+-- (upload-limits Phase 5, byte-quota D3).
+--
+-- Mirrors 0012's file_count so the byte quota (maxBytesPerScope, default OFF)
+-- reads a single `scope_meta.total_bytes` row instead of a
+-- `SELECT SUM(size) FROM entries WHERE scope = ?` full-scope scan on every
+-- write — the same O(N) rows_read anti-pattern that blew the D1 free tier (the
+-- 503 0012 fixed for file_count).
+--
+-- INCREMENT/UPDATE are triggers (cover put + putBatch + overwrite for free);
+-- DECREMENT is NOT a trigger: D1 counts a statement's trigger side-effects in
+-- `meta.changes`, and `deleteByPrefix` returns that value, so an AFTER-DELETE
+-- trigger would inflate the documented count. `delete`/`deleteByPrefix` instead
+-- decrement total_bytes with their own batch statement (see d1-tree-index.ts) —
+-- exactly like file_count.
+--
+-- Provider lineage: 0010 created scope_meta, 0012 added file_count; this ADDS
+-- total_bytes. The Cloudflare runtime CREATEs scope_meta with this column via
+-- its generated schema instead; both end at the same shape, sourced from the
+-- same @aigne/afs-did-space constants. The runtime also self-heals an older
+-- scope_meta via a probe-then-ALTER in D1TreeIndex.ensureTable.
+--
+-- D1-only (mobile runtimes don't mirror scope_meta). NOT parity-checked.
+
+ALTER TABLE scope_meta ADD COLUMN total_bytes INTEGER NOT NULL DEFAULT 0;
+
+-- += NEW.size on every new file row (upsert lazily creates the scope_meta row).
+CREATE TRIGGER IF NOT EXISTS trg_entries_total_bytes_insert
+AFTER INSERT ON entries WHEN NEW.kind = 'file'
+BEGIN
+  INSERT INTO scope_meta (scope, total_bytes) VALUES (NEW.scope, NEW.size)
+  ON CONFLICT(scope) DO UPDATE SET total_bytes = total_bytes + NEW.size;
+END;
+
+-- Overwrite (same path, new content/size) → += NEW.size - OLD.size. Floored at 0.
+CREATE TRIGGER IF NOT EXISTS trg_entries_total_bytes_update
+AFTER UPDATE ON entries WHEN NEW.kind = 'file' AND OLD.kind = 'file'
+BEGIN
+  UPDATE scope_meta SET total_bytes = MAX(0, total_bytes + NEW.size - OLD.size)
+  WHERE scope = NEW.scope;
+END;
+
+-- One-time backfill for scopes that already have files. Absolute (not +=) so it
+-- self-corrects against any write that fired the trigger mid-migration.
+INSERT INTO scope_meta (scope, total_bytes)
+  SELECT scope, COALESCE(SUM(size), 0) FROM entries WHERE kind = 'file' GROUP BY scope
+  ON CONFLICT(scope) DO UPDATE SET total_bytes = excluded.total_bytes;

package/migrations/0014_rename_tables.sql

@@ -0,0 +1,62 @@
+-- 0014: Rename all DID Space Node SQLite tables to use module-prefix naming.
+--
+-- Convention:
+--   ds_  = DID Space tables (entries, changelog, gc_queue, shares, …)
+--
+-- SQLite ALTER TABLE RENAME automatically updates trigger `ON tablename` clauses
+-- but NOT trigger BODY SQL. The file_count and total_bytes triggers reference
+-- `scope_meta` in their bodies — drop them before renaming scope_meta and
+-- recreate with ds_* table names.
+--
+-- Provider lineage: 0001–0013 created all tables with unprefixed names.
+-- This migration renames them all atomically for Node daemon databases.
+
+-- ── Step 1: Drop triggers that reference scope_meta in their bodies ───────────
+
+DROP TRIGGER IF EXISTS trg_entries_file_count_insert;
+DROP TRIGGER IF EXISTS trg_entries_total_bytes_insert;
+DROP TRIGGER IF EXISTS trg_entries_total_bytes_update;
+
+-- ── Step 2: Rename DID Space tables ──────────────────────────────────────────
+
+ALTER TABLE entries          RENAME TO ds_entries;
+ALTER TABLE resolve_entries  RENAME TO ds_resolve_entries;
+ALTER TABLE gc_queue         RENAME TO ds_gc_queue;
+ALTER TABLE shares           RENAME TO ds_shares;
+ALTER TABLE versioned_scopes RENAME TO ds_versioned_scopes;
+ALTER TABLE changelog        RENAME TO ds_changelog;
+ALTER TABLE scope_meta       RENAME TO ds_scope_meta;
+ALTER TABLE prefix_watermark RENAME TO ds_prefix_watermark;
+ALTER TABLE sync_state       RENAME TO ds_sync_state;
+
+-- device_sync_state: D1-only per the changelog-schema.ts comment — present in
+-- some Node databases (migration 0009 applied it before it was marked D1-only).
+-- Rename if it exists; callers use PRAGMA to check for its presence.
+ALTER TABLE device_sync_state RENAME TO ds_device_sync_state;
+
+-- ── Step 3: Recreate file_count trigger with new table names ─────────────────
+-- Mirrors SCOPE_META_FILE_COUNT_TRIGGER_SQL but with ds_entries / ds_scope_meta.
+
+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;
+
+-- ── Step 4: Recreate total_bytes triggers with new table names ────────────────
+-- Mirrors SCOPE_META_TOTAL_BYTES_TRIGGER_SQL but with ds_entries / ds_scope_meta.
+
+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;

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@aigne/afs-did-space",
+  "version": "1.12.0-beta.5",
+  "description": "AIGNE AFS provider for DID-scoped persistent storage with CID-based content deduplication",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/arcblock",
+  "homepage": "https://github.com/arcblock/arc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcblock/arc"
+  },
+  "bugs": {
+    "url": "https://github.com/arcblock/arc/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./cloudflare": {
+      "require": "./dist/cloudflare.cjs",
+      "import": "./dist/cloudflare.mjs"
+    },
+    "./ctime-backfill": {
+      "require": "./dist/ctime-backfill.cjs",
+      "import": "./dist/ctime-backfill.mjs"
+    },
+    "./data-backend": {
+      "require": "./dist/data-backend.cjs",
+      "import": "./dist/data-backend.mjs"
+    },
+    "./dedup-backfill": {
+      "require": "./dist/dedup-backfill.cjs",
+      "import": "./dist/dedup-backfill.mjs"
+    },
+    "./inline-content-migration": {
+      "require": "./dist/inline-content-migration.cjs",
+      "import": "./dist/inline-content-migration.mjs"
+    },
+    "./local": {
+      "require": "./dist/local.cjs",
+      "import": "./dist/local.mjs"
+    },
+    "./space-resolver": {
+      "require": "./dist/space-resolver.cjs",
+      "import": "./dist/space-resolver.mjs"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@arcblock/did": "^1.30.24",
+    "@libsql/client": "^0.15.15",
+    "@noble/hashes": "^2.2.0",
+    "js-yaml": "^4.1.1",
+    "multiformats": "^13.3.1",
+    "ufo": "^1.6.3",
+    "zod": "^4.0.0",
+    "@aigne/afs": "^1.12.0-beta.5",
+    "@aigne/afs-fs": "^1.12.0-beta.5",
+    "@aigne/afs-http-mount": "^1.11.0-beta.13",
+    "@aigne/afs-kv": "^1.12.0-beta.5",
+    "@aigne/afs-provider-utils": "^1.12.0-beta.5",
+    "@aigne/afs-sqlite": "^1.12.0-beta.5",
+    "@aigne/afs-timing": "^1.12.0-beta.5"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260301.1",
+    "@types/bun": "^1.3.6",
+    "@types/js-yaml": "^4.0.9",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.1.2",
+    "tsdown": "0.20.0-beta.3",
+    "typescript": "5.9.2",
+    "@aigne/afs-r2": "1.12.0-beta.5",
+    "@aigne/afs-session": "1.12.0-beta.5",
+    "@aigne/afs-testing": "1.12.0-beta.5",
+    "@aigne/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "clean": "rimraf dist coverage",
+    "generate:fixtures": "bun run scripts/generate-cid-fixtures.ts",
+    "pretest": "bun run generate:fixtures",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text"
+  }
+}