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

package/dist/sync-state.mjs

@@ -0,0 +1,297 @@
+import { SYNC_STATE_INDEX_SQL, SYNC_STATE_TABLE_SQL } from "./changelog-schema.mjs";
+
+//#region src/sync-state.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.
+*/
+/** Default `AppState` returned by load() when nothing is persisted yet. */
+function defaultAppState() {
+	return {
+		deviceId: "",
+		cloudSeq: 0,
+		localSeq: 0,
+		lastSyncAt: 0,
+		syncStatus: { kind: "idle" }
+	};
+}
+/**
+* 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.
+*/
+const SYNC_STATE_KEYS = {
+	deviceId: {
+		name: "device_id",
+		scoped: false
+	},
+	localSeq: {
+		name: "local_seq",
+		scoped: true
+	},
+	cloudSeq: {
+		name: "cloud_seq",
+		scoped: true
+	},
+	lastSyncAt: {
+		name: "last_sync_at",
+		scoped: true
+	},
+	syncStatus: {
+		name: "sync_status",
+		scoped: true
+	}
+};
+/**
+* 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.
+*/
+function serializeSyncStatus(status) {
+	switch (status.kind) {
+		case "idle": return "idle";
+		case "syncing": return "syncing";
+		case "active": return "active";
+		case "error": return `error:${status.message}`;
+	}
+}
+/**
+* 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.
+*/
+function parseSyncStatus(raw) {
+	if (raw === "idle") return { kind: "idle" };
+	if (raw === "syncing") return { kind: "syncing" };
+	if (raw === "active") return { kind: "active" };
+	if (raw.startsWith("error:")) return {
+		kind: "error",
+		message: raw.slice(6)
+	};
+	throw new Error(`SyncStateStore: corrupt sync_status value: ${raw}`);
+}
+/**
+* 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.
+*/
+const DEVICE_ID_FORMAT_RE = /^(aside|desktop|server):[a-z0-9-]+:[a-z0-9-]+$/;
+/** Validate a device_id string. Returns true on match. */
+function isValidDeviceId(deviceId) {
+	return DEVICE_ID_FORMAT_RE.test(deviceId);
+}
+/**
+* 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.
+*/
+function generateDesktopDeviceId(uuid) {
+	return `desktop:ts:${uuid ?? crypto.randomUUID()}`;
+}
+var SyncStateStore = class {
+	client;
+	scope;
+	constructor(opts) {
+		if (typeof opts.scope !== "string" || opts.scope.length === 0) throw new Error("SyncStateStore: scope must be a non-empty string");
+		this.client = opts.client;
+		this.scope = opts.scope;
+	}
+	/**
+	* 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 async ensureTable(client) {
+		await client.execute(SYNC_STATE_TABLE_SQL);
+		for (const sql of SYNC_STATE_INDEX_SQL) await client.execute(sql);
+	}
+	/**
+	* 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.
+	*/
+	keyFor(field) {
+		const meta = SYNC_STATE_KEYS[field];
+		return meta.scoped ? `${this.scope}:${meta.name}` : meta.name;
+	}
+	/**
+	* 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.
+	*/
+	async load() {
+		const state = defaultAppState();
+		const result = await this.client.execute({
+			sql: `SELECT key, value FROM ds_sync_state WHERE key IN (?, ?, ?, ?, ?)`,
+			args: [
+				this.keyFor("deviceId"),
+				this.keyFor("cloudSeq"),
+				this.keyFor("localSeq"),
+				this.keyFor("lastSyncAt"),
+				this.keyFor("syncStatus")
+			]
+		});
+		const rows = /* @__PURE__ */ new Map();
+		for (const row of result.rows) {
+			const k = row[0];
+			const v = row[1];
+			if (typeof k === "string" && (typeof v === "string" || typeof v === "number")) rows.set(k, String(v));
+		}
+		const rawDeviceId = rows.get(this.keyFor("deviceId"));
+		if (rawDeviceId !== void 0) {
+			if (!isValidDeviceId(rawDeviceId)) throw new Error(`SyncStateStore: corrupt device_id value: ${rawDeviceId}`);
+			state.deviceId = rawDeviceId;
+		} else {
+			const fresh = generateDesktopDeviceId();
+			await this.writeKey(this.keyFor("deviceId"), fresh);
+			state.deviceId = fresh;
+		}
+		state.cloudSeq = parseSeqValue(rows.get(this.keyFor("cloudSeq")), "cloud_seq");
+		state.localSeq = parseSeqValue(rows.get(this.keyFor("localSeq")), "local_seq");
+		state.lastSyncAt = parseSeqValue(rows.get(this.keyFor("lastSyncAt")), "last_sync_at");
+		const rawStatus = rows.get(this.keyFor("syncStatus"));
+		if (rawStatus !== void 0) state.syncStatus = parseSyncStatus(rawStatus);
+		return state;
+	}
+	/**
+	* 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)`.
+	*/
+	async save(update) {
+		if (update.deviceId !== void 0) {
+			if (!isValidDeviceId(update.deviceId)) throw new Error(`SyncStateStore: refusing to save invalid device_id: ${update.deviceId}`);
+			await this.writeKey(this.keyFor("deviceId"), update.deviceId);
+		}
+		if (update.cloudSeq !== void 0) await this.writeKeyMonotonic(this.keyFor("cloudSeq"), update.cloudSeq);
+		if (update.localSeq !== void 0) await this.writeKeyMonotonic(this.keyFor("localSeq"), update.localSeq);
+		if (update.lastSyncAt !== void 0) {
+			const safe = Math.max(0, Math.floor(Number.isFinite(update.lastSyncAt) ? update.lastSyncAt : 0));
+			await this.writeKey(this.keyFor("lastSyncAt"), String(safe));
+		}
+		if (update.syncStatus !== void 0) await this.writeKey(this.keyFor("syncStatus"), serializeSyncStatus(update.syncStatus));
+	}
+	/** Plain INSERT OR REPLACE for non-monotonic keys. */
+	async writeKey(key, value) {
+		await this.client.execute({
+			sql: `INSERT INTO ds_sync_state (key, value) VALUES (?, ?)
+            ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+			args: [key, value]
+		});
+	}
+	/**
+	* 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.
+	*/
+	async writeKeyMonotonic(key, seq) {
+		const safe = Math.max(0, Math.floor(Number.isFinite(seq) ? seq : 0));
+		await this.client.execute({
+			sql: `INSERT INTO ds_sync_state (key, value) VALUES (?, ?)
+            ON CONFLICT(key) DO UPDATE SET
+              value = CASE
+                WHEN CAST(excluded.value AS INTEGER) > CAST(ds_sync_state.value AS INTEGER)
+                THEN excluded.value
+                ELSE ds_sync_state.value
+              END`,
+			args: [key, String(safe)]
+		});
+	}
+};
+/**
+* Parse a stored numeric value (cloud_seq / local_seq / last_sync_at).
+*
+* Missing → 0 (the "nothing recorded yet" sentinel, matches LocalChangelog).
+* Non-integer / non-numeric → throws to surface corruption to the caller.
+*/
+function parseSeqValue(raw, label) {
+	if (raw === void 0) return 0;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) throw new Error(`SyncStateStore: corrupt ${label} value: ${raw}`);
+	return parsed;
+}
+
+//#endregion
+export { DEVICE_ID_FORMAT_RE, SYNC_STATE_KEYS, SyncStateStore, defaultAppState, generateDesktopDeviceId, isValidDeviceId, parseSyncStatus, serializeSyncStatus };
+//# sourceMappingURL=sync-state.mjs.map

package/dist/sync-state.mjs.map

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

package/dist/timestamp.cjs

@@ -0,0 +1,92 @@
+
+//#region src/timestamp.ts
+/**
+* Timestamp normalization for the createdAt → ctime feed-sort fix
+* (planning/did-integration/feed-sort-createdat, design §4).
+*
+* The `entries.ctime` / `entries.mtime` columns are INTEGER unix-ms; the
+* application `createdAt` / `updatedAt` are ISO-8601 strings produced by
+* `generate.timeiso` (`YYYY-MM-DDTHH:MM:SS.sssZ`, data-contract §2). These
+* pure helpers bridge the two so a write/backfill can stamp `ctime` from the
+* application timestamp.
+*
+* STRICT INVARIANTS (design §4, tri-runtime contract — TS `Date.parse`,
+* Swift `ISO8601DateFormatter`, Kotlin `Instant.parse` MUST agree on the
+* canonical format AND on the fallback behavior for malformed input):
+* - The functions are PURE: no clock read (except the explicit `fallbackMs`
+*   argument), no env, no I/O, no SQL — they never throw and never log the
+*   input.
+* - `normalizeTs` returns a finite epoch-ms `number > 0`, or `null`. It NEVER
+*   returns `NaN`, `0`, a negative, or a non-finite value, so a caller that
+*   does `normalizeTs(x) ?? fallback` can never persist `NaN`/`NULL` into a
+*   ctime/mtime column.
+* - `resolveCtime` consumes ONLY explicit `metadata` — it does not touch
+*   bytes/path and does not call `readApplicationMetadata` (design §5 intro).
+*/
+/**
+* Parse an application timestamp value into epoch-ms.
+*
+* @param v - candidate value (typically `metadata.createdAt`, an ISO string;
+*   a raw epoch-ms number is also accepted for forward-compat).
+* @returns finite epoch-ms `> 0`, or `null` when the input is missing, the
+*   wrong type, unparseable, or non-positive (`≤ 0`, which includes the 1970
+*   epoch and pre-epoch dates — those fall back rather than sink to ctime 0).
+*
+* Contract (design §4 / tasks 0-1):
+* - string  → `Date.parse(v)`; keep only when finite and `> 0`.
+* - number  → keep only when finite and `> 0` (already epoch-ms).
+* - other   → `null`.
+*/
+function normalizeTs(v) {
+	let ms;
+	if (typeof v === "number") ms = v;
+	else if (typeof v === "string") ms = Date.parse(v);
+	else return null;
+	return Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+/**
+* Resolve the `ctime` to stamp for a write, from explicit application
+* metadata, falling back to a caller-supplied epoch-ms.
+*
+* `= normalizeTs(metadata?.createdAt) ?? fallbackMs`. Because `fallbackMs` is
+* a `number` (not `number | null`) and `normalizeTs` never returns `0`, the
+* result is ALWAYS a finite `number` — callers can stamp it into a ctime
+* column without a NaN/NULL guard.
+*
+* Only `metadata.createdAt` is read; bytes/path are never touched (design
+* §5 intro). The caller is responsible for having already lifted the
+* application metadata into `metadata` (cloud: `payload.meta`; local-apply:
+* `SyncEngine` via `readAppMeta(bytes)`).
+*/
+function resolveCtime(metadata, fallbackMs) {
+	return normalizeTs(metadata?.createdAt) ?? fallbackMs;
+}
+/**
+* Resolve the direct-parent DIR row stamp for Rule R2 (design §3 / §5.2).
+*
+* @returns `{ ctime, mtime }` to UPSERT onto the written entry's DIRECT parent
+*   directory row, or `null` when the metadata carries no usable `createdAt`
+*   (the caller then keeps `INSERT OR IGNORE` — the dir row is NOT disturbed).
+*
+* - `ctime = normalizeTs(createdAt)` (the gate: null `createdAt` → whole stamp
+*   is `null`, so a write without an application createdAt never overwrites a
+*   previously stamped DIR ctime).
+* - `mtime = normalizeTs(updatedAt) ?? ctime` (updatedAt falls back to
+*   createdAt). DIR rows never enter the changelog (design §1 fact 3) so this
+*   mtime carries NO LWW meaning — unlike file-row mtime, which is the LWW
+*   arbiter and is NEVER touched by Rule R.
+*
+* Only the direct parent is stamped; ancestors are never propagated to.
+*/
+function resolveParentDirStamp(metadata) {
+	const ctime = normalizeTs(metadata?.createdAt);
+	if (ctime === null) return null;
+	return {
+		ctime,
+		mtime: normalizeTs(metadata?.updatedAt) ?? ctime
+	};
+}
+
+//#endregion
+exports.resolveCtime = resolveCtime;
+exports.resolveParentDirStamp = resolveParentDirStamp;

package/dist/timestamp.mjs

@@ -0,0 +1,91 @@
+//#region src/timestamp.ts
+/**
+* Timestamp normalization for the createdAt → ctime feed-sort fix
+* (planning/did-integration/feed-sort-createdat, design §4).
+*
+* The `entries.ctime` / `entries.mtime` columns are INTEGER unix-ms; the
+* application `createdAt` / `updatedAt` are ISO-8601 strings produced by
+* `generate.timeiso` (`YYYY-MM-DDTHH:MM:SS.sssZ`, data-contract §2). These
+* pure helpers bridge the two so a write/backfill can stamp `ctime` from the
+* application timestamp.
+*
+* STRICT INVARIANTS (design §4, tri-runtime contract — TS `Date.parse`,
+* Swift `ISO8601DateFormatter`, Kotlin `Instant.parse` MUST agree on the
+* canonical format AND on the fallback behavior for malformed input):
+* - The functions are PURE: no clock read (except the explicit `fallbackMs`
+*   argument), no env, no I/O, no SQL — they never throw and never log the
+*   input.
+* - `normalizeTs` returns a finite epoch-ms `number > 0`, or `null`. It NEVER
+*   returns `NaN`, `0`, a negative, or a non-finite value, so a caller that
+*   does `normalizeTs(x) ?? fallback` can never persist `NaN`/`NULL` into a
+*   ctime/mtime column.
+* - `resolveCtime` consumes ONLY explicit `metadata` — it does not touch
+*   bytes/path and does not call `readApplicationMetadata` (design §5 intro).
+*/
+/**
+* Parse an application timestamp value into epoch-ms.
+*
+* @param v - candidate value (typically `metadata.createdAt`, an ISO string;
+*   a raw epoch-ms number is also accepted for forward-compat).
+* @returns finite epoch-ms `> 0`, or `null` when the input is missing, the
+*   wrong type, unparseable, or non-positive (`≤ 0`, which includes the 1970
+*   epoch and pre-epoch dates — those fall back rather than sink to ctime 0).
+*
+* Contract (design §4 / tasks 0-1):
+* - string  → `Date.parse(v)`; keep only when finite and `> 0`.
+* - number  → keep only when finite and `> 0` (already epoch-ms).
+* - other   → `null`.
+*/
+function normalizeTs(v) {
+	let ms;
+	if (typeof v === "number") ms = v;
+	else if (typeof v === "string") ms = Date.parse(v);
+	else return null;
+	return Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+/**
+* Resolve the `ctime` to stamp for a write, from explicit application
+* metadata, falling back to a caller-supplied epoch-ms.
+*
+* `= normalizeTs(metadata?.createdAt) ?? fallbackMs`. Because `fallbackMs` is
+* a `number` (not `number | null`) and `normalizeTs` never returns `0`, the
+* result is ALWAYS a finite `number` — callers can stamp it into a ctime
+* column without a NaN/NULL guard.
+*
+* Only `metadata.createdAt` is read; bytes/path are never touched (design
+* §5 intro). The caller is responsible for having already lifted the
+* application metadata into `metadata` (cloud: `payload.meta`; local-apply:
+* `SyncEngine` via `readAppMeta(bytes)`).
+*/
+function resolveCtime(metadata, fallbackMs) {
+	return normalizeTs(metadata?.createdAt) ?? fallbackMs;
+}
+/**
+* Resolve the direct-parent DIR row stamp for Rule R2 (design §3 / §5.2).
+*
+* @returns `{ ctime, mtime }` to UPSERT onto the written entry's DIRECT parent
+*   directory row, or `null` when the metadata carries no usable `createdAt`
+*   (the caller then keeps `INSERT OR IGNORE` — the dir row is NOT disturbed).
+*
+* - `ctime = normalizeTs(createdAt)` (the gate: null `createdAt` → whole stamp
+*   is `null`, so a write without an application createdAt never overwrites a
+*   previously stamped DIR ctime).
+* - `mtime = normalizeTs(updatedAt) ?? ctime` (updatedAt falls back to
+*   createdAt). DIR rows never enter the changelog (design §1 fact 3) so this
+*   mtime carries NO LWW meaning — unlike file-row mtime, which is the LWW
+*   arbiter and is NEVER touched by Rule R.
+*
+* Only the direct parent is stamped; ancestors are never propagated to.
+*/
+function resolveParentDirStamp(metadata) {
+	const ctime = normalizeTs(metadata?.createdAt);
+	if (ctime === null) return null;
+	return {
+		ctime,
+		mtime: normalizeTs(metadata?.updatedAt) ?? ctime
+	};
+}
+
+//#endregion
+export { resolveCtime, resolveParentDirStamp };
+//# sourceMappingURL=timestamp.mjs.map

package/dist/timestamp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.mjs","names":[],"sources":["../src/timestamp.ts"],"sourcesContent":["/**\n * Timestamp normalization for the createdAt → ctime feed-sort fix\n * (planning/did-integration/feed-sort-createdat, design §4).\n *\n * The `entries.ctime` / `entries.mtime` columns are INTEGER unix-ms; the\n * application `createdAt` / `updatedAt` are ISO-8601 strings produced by\n * `generate.timeiso` (`YYYY-MM-DDTHH:MM:SS.sssZ`, data-contract §2). These\n * pure helpers bridge the two so a write/backfill can stamp `ctime` from the\n * application timestamp.\n *\n * STRICT INVARIANTS (design §4, tri-runtime contract — TS `Date.parse`,\n * Swift `ISO8601DateFormatter`, Kotlin `Instant.parse` MUST agree on the\n * canonical format AND on the fallback behavior for malformed input):\n * - The functions are PURE: no clock read (except the explicit `fallbackMs`\n *   argument), no env, no I/O, no SQL — they never throw and never log the\n *   input.\n * - `normalizeTs` returns a finite epoch-ms `number > 0`, or `null`. It NEVER\n *   returns `NaN`, `0`, a negative, or a non-finite value, so a caller that\n *   does `normalizeTs(x) ?? fallback` can never persist `NaN`/`NULL` into a\n *   ctime/mtime column.\n * - `resolveCtime` consumes ONLY explicit `metadata` — it does not touch\n *   bytes/path and does not call `readApplicationMetadata` (design §5 intro).\n */\n\n/**\n * Parse an application timestamp value into epoch-ms.\n *\n * @param v - candidate value (typically `metadata.createdAt`, an ISO string;\n *   a raw epoch-ms number is also accepted for forward-compat).\n * @returns finite epoch-ms `> 0`, or `null` when the input is missing, the\n *   wrong type, unparseable, or non-positive (`≤ 0`, which includes the 1970\n *   epoch and pre-epoch dates — those fall back rather than sink to ctime 0).\n *\n * Contract (design §4 / tasks 0-1):\n * - string  → `Date.parse(v)`; keep only when finite and `> 0`.\n * - number  → keep only when finite and `> 0` (already epoch-ms).\n * - other   → `null`.\n */\nexport function normalizeTs(v: unknown): number | null {\n  let ms: number;\n  if (typeof v === \"number\") {\n    ms = v;\n  } else if (typeof v === \"string\") {\n    // Date.parse returns NaN for unparseable input (empty string, garbage,\n    // injection payloads) — Number.isFinite then rejects it below.\n    ms = Date.parse(v);\n  } else {\n    return null;\n  }\n  return Number.isFinite(ms) && ms > 0 ? ms : null;\n}\n\n/**\n * Resolve the `ctime` to stamp for a write, from explicit application\n * metadata, falling back to a caller-supplied epoch-ms.\n *\n * `= normalizeTs(metadata?.createdAt) ?? fallbackMs`. Because `fallbackMs` is\n * a `number` (not `number | null`) and `normalizeTs` never returns `0`, the\n * result is ALWAYS a finite `number` — callers can stamp it into a ctime\n * column without a NaN/NULL guard.\n *\n * Only `metadata.createdAt` is read; bytes/path are never touched (design\n * §5 intro). The caller is responsible for having already lifted the\n * application metadata into `metadata` (cloud: `payload.meta`; local-apply:\n * `SyncEngine` via `readAppMeta(bytes)`).\n */\nexport function resolveCtime(\n  metadata: Record<string, unknown> | null | undefined,\n  fallbackMs: number,\n): number {\n  return normalizeTs(metadata?.createdAt) ?? fallbackMs;\n}\n\n/**\n * Resolve the direct-parent DIR row stamp for Rule R2 (design §3 / §5.2).\n *\n * @returns `{ ctime, mtime }` to UPSERT onto the written entry's DIRECT parent\n *   directory row, or `null` when the metadata carries no usable `createdAt`\n *   (the caller then keeps `INSERT OR IGNORE` — the dir row is NOT disturbed).\n *\n * - `ctime = normalizeTs(createdAt)` (the gate: null `createdAt` → whole stamp\n *   is `null`, so a write without an application createdAt never overwrites a\n *   previously stamped DIR ctime).\n * - `mtime = normalizeTs(updatedAt) ?? ctime` (updatedAt falls back to\n *   createdAt). DIR rows never enter the changelog (design §1 fact 3) so this\n *   mtime carries NO LWW meaning — unlike file-row mtime, which is the LWW\n *   arbiter and is NEVER touched by Rule R.\n *\n * Only the direct parent is stamped; ancestors are never propagated to.\n */\nexport function resolveParentDirStamp(\n  metadata: Record<string, unknown> | null | undefined,\n): { ctime: number; mtime: number } | null {\n  const ctime = normalizeTs(metadata?.createdAt);\n  if (ctime === null) return null;\n  const mtime = normalizeTs(metadata?.updatedAt) ?? ctime;\n  return { ctime, mtime };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,YAAY,GAA2B;CACrD,IAAI;AACJ,KAAI,OAAO,MAAM,SACf,MAAK;UACI,OAAO,MAAM,SAGtB,MAAK,KAAK,MAAM,EAAE;KAElB,QAAO;AAET,QAAO,OAAO,SAAS,GAAG,IAAI,KAAK,IAAI,KAAK;;;;;;;;;;;;;;;;AAiB9C,SAAgB,aACd,UACA,YACQ;AACR,QAAO,YAAY,UAAU,UAAU,IAAI;;;;;;;;;;;;;;;;;;;AAoB7C,SAAgB,sBACd,UACyC;CACzC,MAAM,QAAQ,YAAY,UAAU,UAAU;AAC9C,KAAI,UAAU,KAAM,QAAO;AAE3B,QAAO;EAAE;EAAO,OADF,YAAY,UAAU,UAAU,IAAI;EAC3B"}

package/dist/transports/http.cjs

@@ -0,0 +1,54 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_remote_afs = require('../remote-afs.cjs');
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/transports/http.ts
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+function assertUrlScheme(rawUrl) {
+	let parsed;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		throw new Error(`HttpTransport: invalid URL: ${rawUrl}`);
+	}
+	if (!ALLOWED_SCHEMES.has(parsed.protocol)) throw new Error(`HttpTransport: only http(s) is supported, got ${parsed.protocol} (URL: ${rawUrl})`);
+	return parsed;
+}
+var HttpTransport = class {
+	kind = "http";
+	remote;
+	constructor(options) {
+		assertUrlScheme(options.url);
+		this.remote = new require_remote_afs.RemoteUserSpaceAFS({
+			baseUrl: options.url,
+			token: options.token
+		});
+	}
+	list(path, options) {
+		return this.remote.list(path, options);
+	}
+	read(path, _options) {
+		return this.remote.read(path);
+	}
+	write(path, payload, _options) {
+		return this.remote.write(path, payload);
+	}
+	delete(path, options) {
+		return this.remote.delete(path, options);
+	}
+	async stat(_path, _options) {
+		throw new _aigne_afs.AFSUnsupportedError("stat", "HttpTransport does not expose stat (REST has no /op=stat); use the WS transport for stat.");
+	}
+	async search(_path, _query, _options) {
+		throw new _aigne_afs.AFSUnsupportedError("search", "HttpTransport does not expose search (REST has no /op=search); use the WS transport for search.");
+	}
+	async exec(_path, _args, _options) {
+		throw new _aigne_afs.AFSUnsupportedError("exec", "HttpTransport does not expose exec; use the WS transport for action execution.");
+	}
+	async explain(_path, _options) {
+		throw new _aigne_afs.AFSUnsupportedError("explain", "HttpTransport does not expose explain; use the WS transport for explain.");
+	}
+};
+
+//#endregion
+exports.HttpTransport = HttpTransport;

package/dist/transports/http.d.cts

@@ -0,0 +1,26 @@
+import { Transport } from "./types.cjs";
+import { AFSDeleteOptions, AFSDeleteResult, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSExplainResult, AFSListOptions, AFSListResult, AFSReadOptions, AFSReadResult, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
+
+//#region src/transports/http.d.ts
+interface HttpTransportOptions {
+  /** Base URL of the DID Space REST server, e.g. `https://computer.afsd.dev`. */
+  url: string;
+  /** Bearer token for authentication. */
+  token: string;
+}
+declare class HttpTransport implements Transport {
+  readonly kind: "http";
+  private readonly remote;
+  constructor(options: HttpTransportOptions);
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+  write(path: string, payload: AFSWriteEntryPayload, _options?: AFSWriteOptions): Promise<AFSWriteResult>;
+  delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  stat(_path: string, _options?: AFSStatOptions): Promise<AFSStatResult>;
+  search(_path: string, _query: string, _options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  exec(_path: string, _args: Record<string, unknown>, _options?: AFSExecOptions): Promise<AFSExecResult>;
+  explain(_path: string, _options?: AFSExplainOptions): Promise<AFSExplainResult>;
+}
+//#endregion
+export { HttpTransport, HttpTransportOptions };
+//# sourceMappingURL=http.d.cts.map

package/dist/transports/http.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.cts","names":[],"sources":["../../src/transports/http.ts"],"mappings":";;;;UA4CiB,oBAAA;EAmDgB;EAjD/B,GAAA;EAiDkD;EA/ClD,KAAA;AAAA;AAAA,cAoBW,aAAA,YAAyB,SAAA;EAAA,SAC3B,IAAA;EAAA,iBACQ,MAAA;cAEL,OAAA,EAAS,oBAAA;EAOrB,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAItD,IAAA,CAAK,IAAA,UAAc,QAAA,GAAW,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAIvD,KAAA,CACE,IAAA,UACA,OAAA,EAAS,oBAAA,EACT,QAAA,GAAW,eAAA,GACV,OAAA,CAAQ,cAAA;EAIX,MAAA,CAAO,IAAA,UAAc,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EAIpD,IAAA,CAAK,KAAA,UAAe,QAAA,GAAW,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAOxD,MAAA,CACJ,KAAA,UACA,MAAA,UACA,QAAA,GAAW,gBAAA,GACV,OAAA,CAAQ,eAAA;EAOL,IAAA,CACJ,KAAA,UACA,KAAA,EAAO,MAAA,mBACP,QAAA,GAAW,cAAA,GACV,OAAA,CAAQ,aAAA;EAOL,OAAA,CAAQ,KAAA,UAAe,QAAA,GAAW,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;AAAA"}

package/dist/transports/http.d.mts

@@ -0,0 +1,26 @@
+import { Transport } from "./types.mjs";
+import { AFSDeleteOptions, AFSDeleteResult, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSExplainResult, AFSListOptions, AFSListResult, AFSReadOptions, AFSReadResult, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
+
+//#region src/transports/http.d.ts
+interface HttpTransportOptions {
+  /** Base URL of the DID Space REST server, e.g. `https://computer.afsd.dev`. */
+  url: string;
+  /** Bearer token for authentication. */
+  token: string;
+}
+declare class HttpTransport implements Transport {
+  readonly kind: "http";
+  private readonly remote;
+  constructor(options: HttpTransportOptions);
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+  write(path: string, payload: AFSWriteEntryPayload, _options?: AFSWriteOptions): Promise<AFSWriteResult>;
+  delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  stat(_path: string, _options?: AFSStatOptions): Promise<AFSStatResult>;
+  search(_path: string, _query: string, _options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  exec(_path: string, _args: Record<string, unknown>, _options?: AFSExecOptions): Promise<AFSExecResult>;
+  explain(_path: string, _options?: AFSExplainOptions): Promise<AFSExplainResult>;
+}
+//#endregion
+export { HttpTransport, HttpTransportOptions };
+//# sourceMappingURL=http.d.mts.map

package/dist/transports/http.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.mts","names":[],"sources":["../../src/transports/http.ts"],"mappings":";;;;UA4CiB,oBAAA;EAmDgB;EAjD/B,GAAA;EAiDkD;EA/ClD,KAAA;AAAA;AAAA,cAoBW,aAAA,YAAyB,SAAA;EAAA,SAC3B,IAAA;EAAA,iBACQ,MAAA;cAEL,OAAA,EAAS,oBAAA;EAOrB,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAItD,IAAA,CAAK,IAAA,UAAc,QAAA,GAAW,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAIvD,KAAA,CACE,IAAA,UACA,OAAA,EAAS,oBAAA,EACT,QAAA,GAAW,eAAA,GACV,OAAA,CAAQ,cAAA;EAIX,MAAA,CAAO,IAAA,UAAc,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EAIpD,IAAA,CAAK,KAAA,UAAe,QAAA,GAAW,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAOxD,MAAA,CACJ,KAAA,UACA,MAAA,UACA,QAAA,GAAW,gBAAA,GACV,OAAA,CAAQ,eAAA;EAOL,IAAA,CACJ,KAAA,UACA,KAAA,EAAO,MAAA,mBACP,QAAA,GAAW,cAAA,GACV,OAAA,CAAQ,aAAA;EAOL,OAAA,CAAQ,KAAA,UAAe,QAAA,GAAW,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;AAAA"}