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

package/dist/sync-state.d.cts

@@ -0,0 +1,224 @@
+import * as _libsql_client1 from "@libsql/client";
+
+//#region src/sync-state.d.ts
+/**
+ * SyncStateStore — Phase 3 Task 3.5 (G7)
+ *
+ * Typed key-value façade over the `sync_state` table introduced by
+ * Task 3.4. Where {@link LocalChangelog} owns the bare minimum of the
+ * `{scope}:local_seq` and `{scope}:cloud_seq` keys for changelog GC,
+ * SyncStateStore exposes the FULL set of progress fields the local
+ * SyncEngine needs:
+ *
+ *   - device_id        (per-user, NOT scope-prefixed)
+ *   - {scope}:local_seq
+ *   - {scope}:cloud_seq
+ *   - {scope}:last_sync_at
+ *   - {scope}:sync_status
+ *
+ * The class is intentionally a sibling of LocalChangelog rather than a
+ * refactor of it. Both operate on the same SQLite `sync_state` table and
+ * share monotonic semantics for `local_seq` / `cloud_seq`; cross-class
+ * parity is asserted by tests so the SyncEngine can mix the two without
+ * surprises. Refactoring LocalChangelog into a thin wrapper around
+ * SyncStateStore is a future optimisation that Task 3.6 (SyncEngine) can
+ * decide to make if it becomes ergonomic.
+ *
+ * Platform notes:
+ *   - TypeScript / desktop: device_id is stored ONLY in this SQLite table.
+ *     There is no Keychain equivalent on desktop, so the file IS the SoT.
+ *   - Swift / iOS:    Keychain is the SoT; this SQLite cache is rebuilt
+ *                     on startup.
+ *   - Kotlin / Android: AndroidKeystore + EncryptedSharedPreferences is
+ *                       the SoT; SQLite is again the cache.
+ *
+ * The two mobile runtimes implement their own SyncStateStore + DeviceIDStore
+ * pair under `swift/Sources/AFSDIDSpace/` and
+ * `kotlin/afs-didspace/.../io/aigne/afs/didspace/`. The TypeScript class
+ * here matches their public surface as closely as the language allows.
+ */
+/** Discriminated union shape of `sync_status`. */
+type SyncStatus = {
+  kind: "idle";
+} | {
+  kind: "syncing";
+} | {
+  kind: "active";
+} | {
+  kind: "error";
+  message: string;
+};
+/**
+ * Full snapshot of the per-scope sync state. Returned by {@link SyncStateStore.load}.
+ *
+ * `deviceId` is per-USER-DID (stable across all scopes for the same install)
+ * and is therefore stored under the bare key `device_id` — NOT scope-prefixed.
+ * Every other field is scope-prefixed internally so multiple scopes sharing
+ * the same SQLite file stay isolated.
+ */
+interface AppState {
+  /** Stable device identifier. Generated on first load() if missing. */
+  deviceId: string;
+  /** Highest changelog.seq pulled+applied from other devices. */
+  cloudSeq: number;
+  /** Highest changelog.seq this device has pushed to cloud. */
+  localSeq: number;
+  /** Unix millis of the last successful sync round (any leg). */
+  lastSyncAt: number;
+  /** Current sync state machine value. */
+  syncStatus: SyncStatus;
+}
+/** Default `AppState` returned by load() when nothing is persisted yet. */
+declare function defaultAppState(): AppState;
+/**
+ * Registry of the raw `sync_state` keys this class manages. Exported so
+ * tests and the eventual SyncEngine can introspect the wire format without
+ * hard-coding strings.
+ *
+ * Keys marked `scoped` are written as `{scope}:{name}`. The `device_id`
+ * key is unique among the registry — it is per-user and intentionally NOT
+ * scope-prefixed so a single device sharing two DID Space scopes still
+ * presents the same identity to both.
+ */
+declare const SYNC_STATE_KEYS: {
+  readonly deviceId: {
+    readonly name: "device_id";
+    readonly scoped: false;
+  };
+  readonly localSeq: {
+    readonly name: "local_seq";
+    readonly scoped: true;
+  };
+  readonly cloudSeq: {
+    readonly name: "cloud_seq";
+    readonly scoped: true;
+  };
+  readonly lastSyncAt: {
+    readonly name: "last_sync_at";
+    readonly scoped: true;
+  };
+  readonly syncStatus: {
+    readonly name: "sync_status";
+    readonly scoped: true;
+  };
+};
+interface SyncStateStoreOptions {
+  /**
+   * Already-opened libsql client sharing the same DB file as the TreeIndex.
+   * SyncStateStore does NOT own the client lifecycle — callers (typically
+   * `DIDSpaceProvider` construction) remain responsible for close().
+   */
+  client: _libsql_client1.Client;
+  /** Scope string used to prefix per-scope keys. Must be non-empty. */
+  scope: string;
+}
+/**
+ * Serialise a {@link SyncStatus} to its on-disk string form.
+ *
+ * Format (matches the spec acceptance criteria):
+ *   - `idle`              → `"idle"`
+ *   - `syncing`           → `"syncing"`
+ *   - `active`            → `"active"`
+ *   - `error:{message}`   → `"error:{message}"`
+ *
+ * The `error` branch preserves the full message verbatim. Newlines and
+ * colons inside the message are tolerated; parsing is greedy on the prefix
+ * `error:` so the remainder of the string is the message regardless of
+ * what punctuation it contains.
+ */
+declare function serializeSyncStatus(status: SyncStatus): string;
+/**
+ * Parse a `sync_status` string back into a {@link SyncStatus}. Throws on
+ * unrecognised forms — this matches LocalChangelog's "corrupt value =
+ * surface the bug" stance from Task 3.4.
+ */
+declare function parseSyncStatus(raw: string): SyncStatus;
+/**
+ * Strict device_id format regex. Must match the server-side validator in
+ * `services/arc-computer/src/handlers/validate-headers.ts` so locally
+ * generated identifiers round-trip through the cloud sync endpoints
+ * unchanged. Format: `<class>:<platform>:<suffix>`.
+ *
+ * Duplicated locally so this module has zero cross-package imports — the
+ * source of truth lives in `validate-headers.ts` and any change there must
+ * be mirrored here AND in the Swift/Kotlin equivalents.
+ */
+declare const DEVICE_ID_FORMAT_RE: RegExp;
+/** Validate a device_id string. Returns true on match. */
+declare function isValidDeviceId(deviceId: string): boolean;
+/**
+ * Generate a fresh device_id for the current TypeScript desktop runtime.
+ * Format: `desktop:ts:<uuid v4>`. Tests can pass an injected UUID to
+ * keep generation deterministic.
+ */
+declare function generateDesktopDeviceId(uuid?: string): string;
+declare class SyncStateStore {
+  private readonly client;
+  private readonly scope;
+  constructor(opts: SyncStateStoreOptions);
+  /**
+   * Idempotently create the `sync_state` table. MetadataDB.open() and the
+   * Swift/Kotlin SQLiteTreeIndex.migrate() already create it; this static
+   * helper exists for test fixtures that build a SyncStateStore on a raw
+   * libsql client. Reuses the canonical DDL from `changelog-schema.ts` so
+   * three-runtime parity is preserved.
+   */
+  static ensureTable(client: _libsql_client1.Client): Promise<void>;
+  /**
+   * Build the on-disk key for a given AppState field. Per-scope fields
+   * are prefixed with `{scope}:`; the per-user `device_id` field is the
+   * raw bare name. Exposed as a private helper (rather than inlined) so
+   * the parity tests can introspect the rule via SYNC_STATE_KEYS.
+   */
+  private keyFor;
+  /**
+   * Read the full {@link AppState} for this scope. Missing fields fall
+   * back to the defaults from {@link defaultAppState}.
+   *
+   * If `device_id` is absent, this method generates a fresh one using
+   * {@link generateDesktopDeviceId} and persists it back to the same
+   * SQLite cache before returning. Subsequent loads will see the same
+   * value (this is the "TS desktop has no Keychain — file IS the SoT"
+   * branch from the spec).
+   *
+   * Corrupt values throw — corrupt `cloud_seq` / `local_seq` / `last_sync_at`
+   * non-numeric, corrupt `sync_status` not in the recognised set, corrupt
+   * `device_id` failing the strict regex.
+   */
+  load(): Promise<AppState>;
+  /**
+   * Persist a partial update to the {@link AppState}. Each field is
+   * written via INSERT OR REPLACE on its individual key; concurrent
+   * save() calls touching disjoint fields cannot lose data.
+   *
+   * Monotonic fields:
+   *   - `cloudSeq` and `localSeq` use the same CASE expression as
+   *     {@link LocalChangelog.markPushed}, so a save() with a lower value
+   *     than the current watermark is silently ignored. This keeps a
+   *     SyncEngine + LocalChangelog mixed-write path safe.
+   *
+   * Non-monotonic fields:
+   *   - `lastSyncAt`, `syncStatus`, `deviceId` are written as-is. The
+   *     state machine (`idle → syncing → active → idle` etc.) and the
+   *     `last_sync_at` clock have valid backwards transitions in some
+   *     edge cases (test reset, manual rollback) and we must not block
+   *     them.
+   *
+   * Unknown fields are caught at compile time by `Partial<AppState>`.
+   * Defense-in-depth: at runtime we iterate the explicit list of fields
+   * we know how to serialise rather than `Object.keys(update)`.
+   */
+  save(update: Partial<AppState>): Promise<void>;
+  /** Plain INSERT OR REPLACE for non-monotonic keys. */
+  private writeKey;
+  /**
+   * Monotonic INSERT OR REPLACE for integer keys. Mirror of the helper in
+   * {@link LocalChangelog.writeSeqKeyMonotonic} so the two classes converge
+   * on the same on-disk representation regardless of which one performs
+   * the write.
+   */
+  private writeKeyMonotonic;
+}
+//#endregion
+export { AppState, DEVICE_ID_FORMAT_RE, SYNC_STATE_KEYS, SyncStateStore, SyncStateStoreOptions, SyncStatus, defaultAppState, generateDesktopDeviceId, isValidDeviceId, parseSyncStatus, serializeSyncStatus };
+//# sourceMappingURL=sync-state.d.cts.map

package/dist/sync-state.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state.d.cts","names":[],"sources":["../src/sync-state.ts"],"mappings":";;;;;;AAwCA;;;;;;;;;;;AAcA;;;;;;;;;;;;AAcA;;;;;AAoBA;;;;;;KAhDY,UAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAe,OAAA;AAAA;;;;;;AAoDrB;;;UA1CiB,QAAA;EAgDf;EA9CA,QAAA;EAgDA;EA9CA,QAAA;EA8CK;EA5CL,QAAA;EA6DiC;EA3DjC,UAAA;EA2D0C;EAzD1C,UAAA,EAAY,UAAA;AAAA;;iBAIE,eAAA,CAAA,GAAmB,QAAA;;;AA2FnC;;;;;AAGA;;;cA1Ea,eAAA;EAAA;;;;;;;;;;;;;;;;;;;;;UAQI,qBAAA;EAoFG;;;;;EA9ElB,MAAA,EANoC,eAAA,CAMH,MAAA;EA4GzB;EA1GR,KAAA;AAAA;;;;;;;;;;;;;;;iBAiBc,mBAAA,CAAoB,MAAA,EAAQ,UAAA;;;;;;iBAkB5B,eAAA,CAAgB,GAAA,WAAc,UAAA;;;;;;;;;;;cAoBjC,mBAAA,EAAmB,MAAA;;iBAGhB,eAAA,CAAgB,QAAA;;;;;;iBAShB,uBAAA,CAAwB,IAAA;AAAA,cAK3B,cAAA;EAAA,iBACM,MAAA;EAAA,iBACA,KAAA;cAEL,IAAA,EAAM,qBAAA;;;;;;;;SAeL,WAAA,CAAY,MAAA,EAfc,eAAA,CAemB,MAAA,GAAS,OAAA;;;;;;;UAe3D,MAAA;;;;;;;;;;;;;;;EAqBF,IAAA,CAAA,GAAQ,OAAA,CAAQ,QAAA;;;;;;;;;;;;;;;;;;;;;;;EA2EhB,IAAA,CAAK,MAAA,EAAQ,OAAA,CAAQ,QAAA,IAAY,OAAA;;UA4BzB,QAAA;;;;;;;UAcA,iBAAA;AAAA"}

package/dist/sync-state.d.mts

@@ -0,0 +1,224 @@
+import * as _libsql_client2 from "@libsql/client";
+
+//#region src/sync-state.d.ts
+/**
+ * SyncStateStore — Phase 3 Task 3.5 (G7)
+ *
+ * Typed key-value façade over the `sync_state` table introduced by
+ * Task 3.4. Where {@link LocalChangelog} owns the bare minimum of the
+ * `{scope}:local_seq` and `{scope}:cloud_seq` keys for changelog GC,
+ * SyncStateStore exposes the FULL set of progress fields the local
+ * SyncEngine needs:
+ *
+ *   - device_id        (per-user, NOT scope-prefixed)
+ *   - {scope}:local_seq
+ *   - {scope}:cloud_seq
+ *   - {scope}:last_sync_at
+ *   - {scope}:sync_status
+ *
+ * The class is intentionally a sibling of LocalChangelog rather than a
+ * refactor of it. Both operate on the same SQLite `sync_state` table and
+ * share monotonic semantics for `local_seq` / `cloud_seq`; cross-class
+ * parity is asserted by tests so the SyncEngine can mix the two without
+ * surprises. Refactoring LocalChangelog into a thin wrapper around
+ * SyncStateStore is a future optimisation that Task 3.6 (SyncEngine) can
+ * decide to make if it becomes ergonomic.
+ *
+ * Platform notes:
+ *   - TypeScript / desktop: device_id is stored ONLY in this SQLite table.
+ *     There is no Keychain equivalent on desktop, so the file IS the SoT.
+ *   - Swift / iOS:    Keychain is the SoT; this SQLite cache is rebuilt
+ *                     on startup.
+ *   - Kotlin / Android: AndroidKeystore + EncryptedSharedPreferences is
+ *                       the SoT; SQLite is again the cache.
+ *
+ * The two mobile runtimes implement their own SyncStateStore + DeviceIDStore
+ * pair under `swift/Sources/AFSDIDSpace/` and
+ * `kotlin/afs-didspace/.../io/aigne/afs/didspace/`. The TypeScript class
+ * here matches their public surface as closely as the language allows.
+ */
+/** Discriminated union shape of `sync_status`. */
+type SyncStatus = {
+  kind: "idle";
+} | {
+  kind: "syncing";
+} | {
+  kind: "active";
+} | {
+  kind: "error";
+  message: string;
+};
+/**
+ * Full snapshot of the per-scope sync state. Returned by {@link SyncStateStore.load}.
+ *
+ * `deviceId` is per-USER-DID (stable across all scopes for the same install)
+ * and is therefore stored under the bare key `device_id` — NOT scope-prefixed.
+ * Every other field is scope-prefixed internally so multiple scopes sharing
+ * the same SQLite file stay isolated.
+ */
+interface AppState {
+  /** Stable device identifier. Generated on first load() if missing. */
+  deviceId: string;
+  /** Highest changelog.seq pulled+applied from other devices. */
+  cloudSeq: number;
+  /** Highest changelog.seq this device has pushed to cloud. */
+  localSeq: number;
+  /** Unix millis of the last successful sync round (any leg). */
+  lastSyncAt: number;
+  /** Current sync state machine value. */
+  syncStatus: SyncStatus;
+}
+/** Default `AppState` returned by load() when nothing is persisted yet. */
+declare function defaultAppState(): AppState;
+/**
+ * Registry of the raw `sync_state` keys this class manages. Exported so
+ * tests and the eventual SyncEngine can introspect the wire format without
+ * hard-coding strings.
+ *
+ * Keys marked `scoped` are written as `{scope}:{name}`. The `device_id`
+ * key is unique among the registry — it is per-user and intentionally NOT
+ * scope-prefixed so a single device sharing two DID Space scopes still
+ * presents the same identity to both.
+ */
+declare const SYNC_STATE_KEYS: {
+  readonly deviceId: {
+    readonly name: "device_id";
+    readonly scoped: false;
+  };
+  readonly localSeq: {
+    readonly name: "local_seq";
+    readonly scoped: true;
+  };
+  readonly cloudSeq: {
+    readonly name: "cloud_seq";
+    readonly scoped: true;
+  };
+  readonly lastSyncAt: {
+    readonly name: "last_sync_at";
+    readonly scoped: true;
+  };
+  readonly syncStatus: {
+    readonly name: "sync_status";
+    readonly scoped: true;
+  };
+};
+interface SyncStateStoreOptions {
+  /**
+   * Already-opened libsql client sharing the same DB file as the TreeIndex.
+   * SyncStateStore does NOT own the client lifecycle — callers (typically
+   * `DIDSpaceProvider` construction) remain responsible for close().
+   */
+  client: _libsql_client2.Client;
+  /** Scope string used to prefix per-scope keys. Must be non-empty. */
+  scope: string;
+}
+/**
+ * Serialise a {@link SyncStatus} to its on-disk string form.
+ *
+ * Format (matches the spec acceptance criteria):
+ *   - `idle`              → `"idle"`
+ *   - `syncing`           → `"syncing"`
+ *   - `active`            → `"active"`
+ *   - `error:{message}`   → `"error:{message}"`
+ *
+ * The `error` branch preserves the full message verbatim. Newlines and
+ * colons inside the message are tolerated; parsing is greedy on the prefix
+ * `error:` so the remainder of the string is the message regardless of
+ * what punctuation it contains.
+ */
+declare function serializeSyncStatus(status: SyncStatus): string;
+/**
+ * Parse a `sync_status` string back into a {@link SyncStatus}. Throws on
+ * unrecognised forms — this matches LocalChangelog's "corrupt value =
+ * surface the bug" stance from Task 3.4.
+ */
+declare function parseSyncStatus(raw: string): SyncStatus;
+/**
+ * Strict device_id format regex. Must match the server-side validator in
+ * `services/arc-computer/src/handlers/validate-headers.ts` so locally
+ * generated identifiers round-trip through the cloud sync endpoints
+ * unchanged. Format: `<class>:<platform>:<suffix>`.
+ *
+ * Duplicated locally so this module has zero cross-package imports — the
+ * source of truth lives in `validate-headers.ts` and any change there must
+ * be mirrored here AND in the Swift/Kotlin equivalents.
+ */
+declare const DEVICE_ID_FORMAT_RE: RegExp;
+/** Validate a device_id string. Returns true on match. */
+declare function isValidDeviceId(deviceId: string): boolean;
+/**
+ * Generate a fresh device_id for the current TypeScript desktop runtime.
+ * Format: `desktop:ts:<uuid v4>`. Tests can pass an injected UUID to
+ * keep generation deterministic.
+ */
+declare function generateDesktopDeviceId(uuid?: string): string;
+declare class SyncStateStore {
+  private readonly client;
+  private readonly scope;
+  constructor(opts: SyncStateStoreOptions);
+  /**
+   * Idempotently create the `sync_state` table. MetadataDB.open() and the
+   * Swift/Kotlin SQLiteTreeIndex.migrate() already create it; this static
+   * helper exists for test fixtures that build a SyncStateStore on a raw
+   * libsql client. Reuses the canonical DDL from `changelog-schema.ts` so
+   * three-runtime parity is preserved.
+   */
+  static ensureTable(client: _libsql_client2.Client): Promise<void>;
+  /**
+   * Build the on-disk key for a given AppState field. Per-scope fields
+   * are prefixed with `{scope}:`; the per-user `device_id` field is the
+   * raw bare name. Exposed as a private helper (rather than inlined) so
+   * the parity tests can introspect the rule via SYNC_STATE_KEYS.
+   */
+  private keyFor;
+  /**
+   * Read the full {@link AppState} for this scope. Missing fields fall
+   * back to the defaults from {@link defaultAppState}.
+   *
+   * If `device_id` is absent, this method generates a fresh one using
+   * {@link generateDesktopDeviceId} and persists it back to the same
+   * SQLite cache before returning. Subsequent loads will see the same
+   * value (this is the "TS desktop has no Keychain — file IS the SoT"
+   * branch from the spec).
+   *
+   * Corrupt values throw — corrupt `cloud_seq` / `local_seq` / `last_sync_at`
+   * non-numeric, corrupt `sync_status` not in the recognised set, corrupt
+   * `device_id` failing the strict regex.
+   */
+  load(): Promise<AppState>;
+  /**
+   * Persist a partial update to the {@link AppState}. Each field is
+   * written via INSERT OR REPLACE on its individual key; concurrent
+   * save() calls touching disjoint fields cannot lose data.
+   *
+   * Monotonic fields:
+   *   - `cloudSeq` and `localSeq` use the same CASE expression as
+   *     {@link LocalChangelog.markPushed}, so a save() with a lower value
+   *     than the current watermark is silently ignored. This keeps a
+   *     SyncEngine + LocalChangelog mixed-write path safe.
+   *
+   * Non-monotonic fields:
+   *   - `lastSyncAt`, `syncStatus`, `deviceId` are written as-is. The
+   *     state machine (`idle → syncing → active → idle` etc.) and the
+   *     `last_sync_at` clock have valid backwards transitions in some
+   *     edge cases (test reset, manual rollback) and we must not block
+   *     them.
+   *
+   * Unknown fields are caught at compile time by `Partial<AppState>`.
+   * Defense-in-depth: at runtime we iterate the explicit list of fields
+   * we know how to serialise rather than `Object.keys(update)`.
+   */
+  save(update: Partial<AppState>): Promise<void>;
+  /** Plain INSERT OR REPLACE for non-monotonic keys. */
+  private writeKey;
+  /**
+   * Monotonic INSERT OR REPLACE for integer keys. Mirror of the helper in
+   * {@link LocalChangelog.writeSeqKeyMonotonic} so the two classes converge
+   * on the same on-disk representation regardless of which one performs
+   * the write.
+   */
+  private writeKeyMonotonic;
+}
+//#endregion
+export { AppState, DEVICE_ID_FORMAT_RE, SYNC_STATE_KEYS, SyncStateStore, SyncStateStoreOptions, SyncStatus, defaultAppState, generateDesktopDeviceId, isValidDeviceId, parseSyncStatus, serializeSyncStatus };
+//# sourceMappingURL=sync-state.d.mts.map

package/dist/sync-state.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state.d.mts","names":[],"sources":["../src/sync-state.ts"],"mappings":";;;;;;AAwCA;;;;;;;;;;;AAcA;;;;;;;;;;;;AAcA;;;;;AAoBA;;;;;;KAhDY,UAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAe,OAAA;AAAA;;;;;;AAoDrB;;;UA1CiB,QAAA;EAgDf;EA9CA,QAAA;EAgDA;EA9CA,QAAA;EA8CK;EA5CL,QAAA;EA6DiC;EA3DjC,UAAA;EA2D0C;EAzD1C,UAAA,EAAY,UAAA;AAAA;;iBAIE,eAAA,CAAA,GAAmB,QAAA;;;AA2FnC;;;;;AAGA;;;cA1Ea,eAAA;EAAA;;;;;;;;;;;;;;;;;;;;;UAQI,qBAAA;EAoFG;;;;;EA9ElB,MAAA,EANoC,eAAA,CAMH,MAAA;EA4GzB;EA1GR,KAAA;AAAA;;;;;;;;;;;;;;;iBAiBc,mBAAA,CAAoB,MAAA,EAAQ,UAAA;;;;;;iBAkB5B,eAAA,CAAgB,GAAA,WAAc,UAAA;;;;;;;;;;;cAoBjC,mBAAA,EAAmB,MAAA;;iBAGhB,eAAA,CAAgB,QAAA;;;;;;iBAShB,uBAAA,CAAwB,IAAA;AAAA,cAK3B,cAAA;EAAA,iBACM,MAAA;EAAA,iBACA,KAAA;cAEL,IAAA,EAAM,qBAAA;;;;;;;;SAeL,WAAA,CAAY,MAAA,EAfc,eAAA,CAemB,MAAA,GAAS,OAAA;;;;;;;UAe3D,MAAA;;;;;;;;;;;;;;;EAqBF,IAAA,CAAA,GAAQ,OAAA,CAAQ,QAAA;;;;;;;;;;;;;;;;;;;;;;;EA2EhB,IAAA,CAAK,MAAA,EAAQ,OAAA,CAAQ,QAAA,IAAY,OAAA;;UA4BzB,QAAA;;;;;;;UAcA,iBAAA;AAAA"}