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

package/dist/upload-session-store.d.cts

@@ -0,0 +1,99 @@
+import { Client } from "@libsql/client";
+
+//#region src/upload-session-store.d.ts
+/**
+ * Prepared-session TTL (design §9 / §15). Hours-scale and DELIBERATELY far
+ * shorter than `DEFAULT_GC_GRACE_MS` (7 days): in-flight protection cannot lean
+ * on the GC grace window (prepared TTL ≪ grace), so the prepared-session UNION
+ * in reference-check.ts is the real protection. 2h is ample for a large
+ * first-sync batch's uploads to land + commit.
+ */
+declare const UPLOAD_SESSION_TTL_MS: number;
+type UploadSessionStatus = "prepared" | "committed" | "aborted" | "expired";
+type UploadSessionEntryStatus = "needs_upload" | "already_present" | "committed" | "failed";
+interface UploadSessionEntryInput {
+  path: string;
+  cid: string;
+  objectKey: string;
+  checksumSha256: string;
+  size: number;
+  mimeType?: string | null;
+  ifMatch?: string | null;
+  deviceId?: string | null;
+  mtime?: number | null;
+  status: UploadSessionEntryStatus;
+}
+interface NewUploadSession {
+  id: string;
+  scope: string;
+  caller?: string | null;
+  /** Absolute expiry (ms epoch). Caller computes from UPLOAD_SESSION_TTL_MS. */
+  expiresAt: number;
+  /** Defaults to Date.now() when omitted. */
+  createdAt?: number;
+  entries: UploadSessionEntryInput[];
+}
+interface UploadSessionEntry extends UploadSessionEntryInput {
+  mimeType: string | null;
+  ifMatch: string | null;
+  deviceId: string | null;
+  mtime: number | null;
+}
+interface UploadSession {
+  id: string;
+  scope: string;
+  caller: string | null;
+  expiresAt: number;
+  status: UploadSessionStatus;
+  createdAt: number;
+  entries: UploadSessionEntry[];
+}
+interface UploadSessionStore {
+  ensureTable(): Promise<void>;
+  /** Persist a new `prepared` session + its entries. Throws on empty entries. */
+  createSession(input: NewUploadSession): Promise<void>;
+  /** Read a session + its entries, or null if unknown. */
+  getSession(id: string): Promise<UploadSession | null>;
+  /** Update per-entry statuses by path. Unknown paths are silently ignored. */
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  /** Flip the session to `committed`. */
+  markCommitted(id: string): Promise<void>;
+  /** Flip the session to `aborted`. */
+  markAborted(id: string): Promise<void>;
+  /** Delete sessions (and their entries) past their expires_at, regardless of status. Returns count. */
+  sweepExpired(now: number): Promise<number>;
+}
+declare class D1UploadSessionStore implements UploadSessionStore {
+  private readonly db;
+  constructor(db: D1Database);
+  ensureTable(): Promise<void>;
+  createSession(input: NewUploadSession): Promise<void>;
+  getSession(id: string): Promise<UploadSession | null>;
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  markCommitted(id: string): Promise<void>;
+  markAborted(id: string): Promise<void>;
+  sweepExpired(now: number): Promise<number>;
+}
+declare class SqliteUploadSessionStore implements UploadSessionStore {
+  private readonly client;
+  constructor(client: Client);
+  ensureTable(): Promise<void>;
+  createSession(input: NewUploadSession): Promise<void>;
+  getSession(id: string): Promise<UploadSession | null>;
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  markCommitted(id: string): Promise<void>;
+  markAborted(id: string): Promise<void>;
+  sweepExpired(now: number): Promise<number>;
+}
+//#endregion
+export { D1UploadSessionStore, NewUploadSession, SqliteUploadSessionStore, UPLOAD_SESSION_TTL_MS, UploadSession, UploadSessionEntry, UploadSessionEntryInput, UploadSessionEntryStatus, UploadSessionStatus, UploadSessionStore };
+//# sourceMappingURL=upload-session-store.d.cts.map

package/dist/upload-session-store.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-session-store.d.cts","names":[],"sources":["../src/upload-session-store.ts"],"mappings":";;;;;;;;;;cAkCa,qBAAA;AAAA,KAED,mBAAA;AAAA,KACA,wBAAA;AAAA,UAEK,uBAAA;EACf,IAAA;EACA,GAAA;EACA,SAAA;EACA,cAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA;EACA,MAAA,EAAQ,wBAAA;AAAA;AAAA,UAGO,gBAAA;EACf,EAAA;EACA,KAAA;EACA,MAAA;EAKgC;EAHhC,SAAA;EAMe;EAJf,SAAA;EACA,OAAA,EAAS,uBAAA;AAAA;AAAA,UAGM,kBAAA,SAA2B,uBAAA;EAC1C,QAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA;AAAA;AAAA,UAGe,aAAA;EACf,EAAA;EACA,KAAA;EACA,MAAA;EACA,SAAA;EACA,MAAA,EAAQ,mBAAA;EACR,SAAA;EACA,OAAA,EAAS,kBAAA;AAAA;AAAA,UAGM,kBAAA;EACf,WAAA,IAAe,OAAA;EALf;EAOA,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAN/B;EAQT,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EARL;EAU3B,WAAA,CACE,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAPkB;EASrB,aAAA,CAAc,EAAA,WAAa,OAAA;EAPK;EAShC,WAAA,CAAY,EAAA,WAAa,OAAA;EALgB;EAOzC,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA;AAAA,cAiDhB,oBAAA,YAAgC,kBAAA;EAAA,iBACd,EAAA;cAAA,EAAA,EAAI,UAAA;EAE3B,WAAA,CAAA,GAAe,OAAA;EASf,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAYxC,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EAUhC,WAAA,CACJ,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAQG,aAAA,CAAc,EAAA,WAAa,OAAA;EAI3B,WAAA,CAAY,EAAA,WAAa,OAAA;EAIzB,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA;AAAA,cAUtB,wBAAA,YAAoC,kBAAA;EAAA,iBAClB,MAAA;cAAA,MAAA,EAAQ,MAAA;EAE/B,WAAA,CAAA,GAAe,OAAA;EAMf,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAsBxC,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EAUhC,WAAA,CACJ,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAWG,aAAA,CAAc,EAAA,WAAa,OAAA;EAI3B,WAAA,CAAY,EAAA,WAAa,OAAA;EAIzB,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA"}

package/dist/upload-session-store.d.mts

@@ -0,0 +1,99 @@
+import { Client } from "@libsql/client";
+
+//#region src/upload-session-store.d.ts
+/**
+ * Prepared-session TTL (design §9 / §15). Hours-scale and DELIBERATELY far
+ * shorter than `DEFAULT_GC_GRACE_MS` (7 days): in-flight protection cannot lean
+ * on the GC grace window (prepared TTL ≪ grace), so the prepared-session UNION
+ * in reference-check.ts is the real protection. 2h is ample for a large
+ * first-sync batch's uploads to land + commit.
+ */
+declare const UPLOAD_SESSION_TTL_MS: number;
+type UploadSessionStatus = "prepared" | "committed" | "aborted" | "expired";
+type UploadSessionEntryStatus = "needs_upload" | "already_present" | "committed" | "failed";
+interface UploadSessionEntryInput {
+  path: string;
+  cid: string;
+  objectKey: string;
+  checksumSha256: string;
+  size: number;
+  mimeType?: string | null;
+  ifMatch?: string | null;
+  deviceId?: string | null;
+  mtime?: number | null;
+  status: UploadSessionEntryStatus;
+}
+interface NewUploadSession {
+  id: string;
+  scope: string;
+  caller?: string | null;
+  /** Absolute expiry (ms epoch). Caller computes from UPLOAD_SESSION_TTL_MS. */
+  expiresAt: number;
+  /** Defaults to Date.now() when omitted. */
+  createdAt?: number;
+  entries: UploadSessionEntryInput[];
+}
+interface UploadSessionEntry extends UploadSessionEntryInput {
+  mimeType: string | null;
+  ifMatch: string | null;
+  deviceId: string | null;
+  mtime: number | null;
+}
+interface UploadSession {
+  id: string;
+  scope: string;
+  caller: string | null;
+  expiresAt: number;
+  status: UploadSessionStatus;
+  createdAt: number;
+  entries: UploadSessionEntry[];
+}
+interface UploadSessionStore {
+  ensureTable(): Promise<void>;
+  /** Persist a new `prepared` session + its entries. Throws on empty entries. */
+  createSession(input: NewUploadSession): Promise<void>;
+  /** Read a session + its entries, or null if unknown. */
+  getSession(id: string): Promise<UploadSession | null>;
+  /** Update per-entry statuses by path. Unknown paths are silently ignored. */
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  /** Flip the session to `committed`. */
+  markCommitted(id: string): Promise<void>;
+  /** Flip the session to `aborted`. */
+  markAborted(id: string): Promise<void>;
+  /** Delete sessions (and their entries) past their expires_at, regardless of status. Returns count. */
+  sweepExpired(now: number): Promise<number>;
+}
+declare class D1UploadSessionStore implements UploadSessionStore {
+  private readonly db;
+  constructor(db: D1Database);
+  ensureTable(): Promise<void>;
+  createSession(input: NewUploadSession): Promise<void>;
+  getSession(id: string): Promise<UploadSession | null>;
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  markCommitted(id: string): Promise<void>;
+  markAborted(id: string): Promise<void>;
+  sweepExpired(now: number): Promise<number>;
+}
+declare class SqliteUploadSessionStore implements UploadSessionStore {
+  private readonly client;
+  constructor(client: Client);
+  ensureTable(): Promise<void>;
+  createSession(input: NewUploadSession): Promise<void>;
+  getSession(id: string): Promise<UploadSession | null>;
+  markEntries(id: string, updates: Array<{
+    path: string;
+    status: UploadSessionEntryStatus;
+  }>): Promise<void>;
+  markCommitted(id: string): Promise<void>;
+  markAborted(id: string): Promise<void>;
+  sweepExpired(now: number): Promise<number>;
+}
+//#endregion
+export { D1UploadSessionStore, NewUploadSession, SqliteUploadSessionStore, UPLOAD_SESSION_TTL_MS, UploadSession, UploadSessionEntry, UploadSessionEntryInput, UploadSessionEntryStatus, UploadSessionStatus, UploadSessionStore };
+//# sourceMappingURL=upload-session-store.d.mts.map

package/dist/upload-session-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-session-store.d.mts","names":[],"sources":["../src/upload-session-store.ts"],"mappings":";;;;;;;;;;cAkCa,qBAAA;AAAA,KAED,mBAAA;AAAA,KACA,wBAAA;AAAA,UAEK,uBAAA;EACf,IAAA;EACA,GAAA;EACA,SAAA;EACA,cAAA;EACA,IAAA;EACA,QAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA;EACA,MAAA,EAAQ,wBAAA;AAAA;AAAA,UAGO,gBAAA;EACf,EAAA;EACA,KAAA;EACA,MAAA;EAKgC;EAHhC,SAAA;EAMe;EAJf,SAAA;EACA,OAAA,EAAS,uBAAA;AAAA;AAAA,UAGM,kBAAA,SAA2B,uBAAA;EAC1C,QAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA;AAAA;AAAA,UAGe,aAAA;EACf,EAAA;EACA,KAAA;EACA,MAAA;EACA,SAAA;EACA,MAAA,EAAQ,mBAAA;EACR,SAAA;EACA,OAAA,EAAS,kBAAA;AAAA;AAAA,UAGM,kBAAA;EACf,WAAA,IAAe,OAAA;EALf;EAOA,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAN/B;EAQT,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EARL;EAU3B,WAAA,CACE,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAPkB;EASrB,aAAA,CAAc,EAAA,WAAa,OAAA;EAPK;EAShC,WAAA,CAAY,EAAA,WAAa,OAAA;EALgB;EAOzC,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA;AAAA,cAiDhB,oBAAA,YAAgC,kBAAA;EAAA,iBACd,EAAA;cAAA,EAAA,EAAI,UAAA;EAE3B,WAAA,CAAA,GAAe,OAAA;EASf,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAYxC,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EAUhC,WAAA,CACJ,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAQG,aAAA,CAAc,EAAA,WAAa,OAAA;EAI3B,WAAA,CAAY,EAAA,WAAa,OAAA;EAIzB,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA;AAAA,cAUtB,wBAAA,YAAoC,kBAAA;EAAA,iBAClB,MAAA;cAAA,MAAA,EAAQ,MAAA;EAE/B,WAAA,CAAA,GAAe,OAAA;EAMf,aAAA,CAAc,KAAA,EAAO,gBAAA,GAAmB,OAAA;EAsBxC,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,aAAA;EAUhC,WAAA,CACJ,EAAA,UACA,OAAA,EAAS,KAAA;IAAQ,IAAA;IAAc,MAAA,EAAQ,wBAAA;EAAA,KACtC,OAAA;EAWG,aAAA,CAAc,EAAA,WAAa,OAAA;EAI3B,WAAA,CAAY,EAAA,WAAa,OAAA;EAIzB,YAAA,CAAa,GAAA,WAAc,OAAA;AAAA"}

package/dist/upload-session-store.mjs

@@ -0,0 +1,184 @@
+import { UPLOAD_SESSIONS_INDEX_SQL, UPLOAD_SESSIONS_TABLE_SQL, UPLOAD_SESSION_ENTRIES_TABLE_SQL } from "./d1-schema.mjs";
+
+//#region src/upload-session-store.ts
+/**
+* Prepared-session TTL (design §9 / §15). Hours-scale and DELIBERATELY far
+* shorter than `DEFAULT_GC_GRACE_MS` (7 days): in-flight protection cannot lean
+* on the GC grace window (prepared TTL ≪ grace), so the prepared-session UNION
+* in reference-check.ts is the real protection. 2h is ample for a large
+* first-sync batch's uploads to land + commit.
+*/
+const UPLOAD_SESSION_TTL_MS = 7200 * 1e3;
+function assertNonEmpty(input) {
+	if (!input.entries || input.entries.length === 0) throw new Error("createSession: entries must be non-empty");
+}
+/**
+* Statement strings shared by BOTH backends (D1 binds positionally, libsql via
+* `args`) — hoisted so the two impls can never drift on column lists / WHERE
+* clauses. Mirrors reference-check.ts's hoisted-SQL style.
+*/
+const SQL = {
+	insertSession: "INSERT INTO ds_upload_sessions (id, scope, caller, expires_at, status, created_at) VALUES (?, ?, ?, ?, 'prepared', ?)",
+	insertEntry: "INSERT INTO ds_upload_session_entries (session_id, path, cid, object_key, checksum_sha256, size, mime_type, if_match, device_id, mtime, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+	selectSession: "SELECT * FROM ds_upload_sessions WHERE id = ?",
+	selectEntries: "SELECT * FROM ds_upload_session_entries WHERE session_id = ?",
+	updateEntryStatus: "UPDATE ds_upload_session_entries SET status = ? WHERE session_id = ? AND path = ?",
+	markCommitted: "UPDATE ds_upload_sessions SET status = 'committed' WHERE id = ?",
+	markAborted: "UPDATE ds_upload_sessions SET status = 'aborted' WHERE id = ?",
+	sweepEntries: "DELETE FROM ds_upload_session_entries WHERE session_id IN (SELECT id FROM ds_upload_sessions WHERE expires_at < ?)",
+	sweepSessions: "DELETE FROM ds_upload_sessions WHERE expires_at < ?"
+};
+/** Positional bind args for `insertEntry` (shared by both backends). */
+function entryArgs(sessionId, e) {
+	return [
+		sessionId,
+		e.path,
+		e.cid,
+		e.objectKey,
+		e.checksumSha256,
+		e.size,
+		e.mimeType ?? null,
+		e.ifMatch ?? null,
+		e.deviceId ?? null,
+		e.mtime ?? null,
+		e.status
+	];
+}
+var D1UploadSessionStore = class {
+	constructor(db) {
+		this.db = db;
+	}
+	async ensureTable() {
+		const stmts = [
+			this.db.prepare(UPLOAD_SESSIONS_TABLE_SQL),
+			this.db.prepare(UPLOAD_SESSION_ENTRIES_TABLE_SQL),
+			...UPLOAD_SESSIONS_INDEX_SQL.map((sql) => this.db.prepare(sql))
+		];
+		await this.db.batch(stmts);
+	}
+	async createSession(input) {
+		assertNonEmpty(input);
+		const createdAt = input.createdAt ?? Date.now();
+		const stmts = [this.db.prepare(SQL.insertSession).bind(input.id, input.scope, input.caller ?? null, input.expiresAt, createdAt), ...input.entries.map((e) => this.db.prepare(SQL.insertEntry).bind(...entryArgs(input.id, e)))];
+		await this.db.batch(stmts);
+	}
+	async getSession(id) {
+		const row = await this.db.prepare(SQL.selectSession).bind(id).first();
+		if (!row) return null;
+		return rowToSession(row, (await this.db.prepare(SQL.selectEntries).bind(id).all()).results);
+	}
+	async markEntries(id, updates) {
+		if (updates.length === 0) return;
+		const stmts = updates.map((u) => this.db.prepare(SQL.updateEntryStatus).bind(u.status, id, u.path));
+		await this.db.batch(stmts);
+	}
+	async markCommitted(id) {
+		await this.db.prepare(SQL.markCommitted).bind(id).run();
+	}
+	async markAborted(id) {
+		await this.db.prepare(SQL.markAborted).bind(id).run();
+	}
+	async sweepExpired(now) {
+		await this.db.prepare(SQL.sweepEntries).bind(now).run();
+		return (await this.db.prepare(SQL.sweepSessions).bind(now).run()).meta?.changes ?? 0;
+	}
+};
+var SqliteUploadSessionStore = class {
+	constructor(client) {
+		this.client = client;
+	}
+	async ensureTable() {
+		await this.client.execute(UPLOAD_SESSIONS_TABLE_SQL);
+		await this.client.execute(UPLOAD_SESSION_ENTRIES_TABLE_SQL);
+		for (const sql of UPLOAD_SESSIONS_INDEX_SQL) await this.client.execute(sql);
+	}
+	async createSession(input) {
+		assertNonEmpty(input);
+		const createdAt = input.createdAt ?? Date.now();
+		const stmts = [{
+			sql: SQL.insertSession,
+			args: [
+				input.id,
+				input.scope,
+				input.caller ?? null,
+				input.expiresAt,
+				createdAt
+			]
+		}, ...input.entries.map((e) => ({
+			sql: SQL.insertEntry,
+			args: entryArgs(input.id, e)
+		}))];
+		await this.client.batch(stmts, "write");
+	}
+	async getSession(id) {
+		const sessionRes = await this.client.execute({
+			sql: SQL.selectSession,
+			args: [id]
+		});
+		if (sessionRes.rows.length === 0) return null;
+		const entriesRes = await this.client.execute({
+			sql: SQL.selectEntries,
+			args: [id]
+		});
+		return rowToSession(sessionRes.rows[0], entriesRes.rows);
+	}
+	async markEntries(id, updates) {
+		if (updates.length === 0) return;
+		await this.client.batch(updates.map((u) => ({
+			sql: SQL.updateEntryStatus,
+			args: [
+				u.status,
+				id,
+				u.path
+			]
+		})), "write");
+	}
+	async markCommitted(id) {
+		await this.client.execute({
+			sql: SQL.markCommitted,
+			args: [id]
+		});
+	}
+	async markAborted(id) {
+		await this.client.execute({
+			sql: SQL.markAborted,
+			args: [id]
+		});
+	}
+	async sweepExpired(now) {
+		await this.client.execute({
+			sql: SQL.sweepEntries,
+			args: [now]
+		});
+		return (await this.client.execute({
+			sql: SQL.sweepSessions,
+			args: [now]
+		})).rowsAffected ?? 0;
+	}
+};
+function rowToSession(s, entryRows) {
+	return {
+		id: String(s.id),
+		scope: String(s.scope),
+		caller: s.caller == null ? null : String(s.caller),
+		expiresAt: Number(s.expires_at),
+		status: String(s.status),
+		createdAt: Number(s.created_at),
+		entries: entryRows.map((e) => ({
+			path: String(e.path),
+			cid: String(e.cid),
+			objectKey: String(e.object_key),
+			checksumSha256: String(e.checksum_sha256),
+			size: Number(e.size),
+			mimeType: e.mime_type == null ? null : String(e.mime_type),
+			ifMatch: e.if_match == null ? null : String(e.if_match),
+			deviceId: e.device_id == null ? null : String(e.device_id),
+			mtime: e.mtime == null ? null : Number(e.mtime),
+			status: String(e.status)
+		}))
+	};
+}
+
+//#endregion
+export { D1UploadSessionStore, SqliteUploadSessionStore, UPLOAD_SESSION_TTL_MS };
+//# sourceMappingURL=upload-session-store.mjs.map

package/dist/upload-session-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-session-store.mjs","names":[],"sources":["../src/upload-session-store.ts"],"sourcesContent":["/**\n * upload-session-store.ts — recoverable upload-session registry (design §9).\n *\n * Two backends behind ONE interface (same split as `GcQueue`):\n *   - `D1UploadSessionStore`     — Cloudflare D1\n *   - `SqliteUploadSessionStore` — Node `_metadata.db` (libsql)\n * External behavior is identical (§9 \"Node/local … external behavior 必须一致\").\n *\n * The store persists the prepared → committed/aborted/expired lifecycle so:\n *   1. `commit-upload` (P2) re-validates the client's entries against the\n *      prepared contract recorded here (never trusts client-claimed proof);\n *   2. GC protects objects referenced by a non-expired `prepared` session\n *      (in-flight protection — see reference-check.ts).\n *\n * scope discipline (§9): `scope` is ALWAYS `this._scope` (the de-identified\n * storage scope), and `caller` may hold ONLY a blocklet bareInstanceId, never a\n * user DID. Enforcement of those values is the writer's job (the prepare-upload\n * handler) + the table CHECKs; this store just persists what it is given.\n */\n\nimport type { InValue, Client as LibsqlClient } from \"@libsql/client\";\nimport {\n  UPLOAD_SESSION_ENTRIES_TABLE_SQL,\n  UPLOAD_SESSIONS_INDEX_SQL,\n  UPLOAD_SESSIONS_TABLE_SQL,\n} from \"./d1-schema.js\";\n\n/**\n * Prepared-session TTL (design §9 / §15). Hours-scale and DELIBERATELY far\n * shorter than `DEFAULT_GC_GRACE_MS` (7 days): in-flight protection cannot lean\n * on the GC grace window (prepared TTL ≪ grace), so the prepared-session UNION\n * in reference-check.ts is the real protection. 2h is ample for a large\n * first-sync batch's uploads to land + commit.\n */\nexport const UPLOAD_SESSION_TTL_MS = 2 * 60 * 60 * 1000;\n\nexport type UploadSessionStatus = \"prepared\" | \"committed\" | \"aborted\" | \"expired\";\nexport type UploadSessionEntryStatus = \"needs_upload\" | \"already_present\" | \"committed\" | \"failed\";\n\nexport interface UploadSessionEntryInput {\n  path: string;\n  cid: string;\n  objectKey: string;\n  checksumSha256: string;\n  size: number;\n  mimeType?: string | null;\n  ifMatch?: string | null;\n  deviceId?: string | null;\n  mtime?: number | null;\n  status: UploadSessionEntryStatus;\n}\n\nexport interface NewUploadSession {\n  id: string;\n  scope: string;\n  caller?: string | null;\n  /** Absolute expiry (ms epoch). Caller computes from UPLOAD_SESSION_TTL_MS. */\n  expiresAt: number;\n  /** Defaults to Date.now() when omitted. */\n  createdAt?: number;\n  entries: UploadSessionEntryInput[];\n}\n\nexport interface UploadSessionEntry extends UploadSessionEntryInput {\n  mimeType: string | null;\n  ifMatch: string | null;\n  deviceId: string | null;\n  mtime: number | null;\n}\n\nexport interface UploadSession {\n  id: string;\n  scope: string;\n  caller: string | null;\n  expiresAt: number;\n  status: UploadSessionStatus;\n  createdAt: number;\n  entries: UploadSessionEntry[];\n}\n\nexport interface UploadSessionStore {\n  ensureTable(): Promise<void>;\n  /** Persist a new `prepared` session + its entries. Throws on empty entries. */\n  createSession(input: NewUploadSession): Promise<void>;\n  /** Read a session + its entries, or null if unknown. */\n  getSession(id: string): Promise<UploadSession | null>;\n  /** Update per-entry statuses by path. Unknown paths are silently ignored. */\n  markEntries(\n    id: string,\n    updates: Array<{ path: string; status: UploadSessionEntryStatus }>,\n  ): Promise<void>;\n  /** Flip the session to `committed`. */\n  markCommitted(id: string): Promise<void>;\n  /** Flip the session to `aborted`. */\n  markAborted(id: string): Promise<void>;\n  /** Delete sessions (and their entries) past their expires_at, regardless of status. Returns count. */\n  sweepExpired(now: number): Promise<number>;\n}\n\nfunction assertNonEmpty(input: NewUploadSession): void {\n  if (!input.entries || input.entries.length === 0) {\n    throw new Error(\"createSession: entries must be non-empty\");\n  }\n}\n\n/**\n * Statement strings shared by BOTH backends (D1 binds positionally, libsql via\n * `args`) — hoisted so the two impls can never drift on column lists / WHERE\n * clauses. Mirrors reference-check.ts's hoisted-SQL style.\n */\nconst SQL = {\n  insertSession:\n    \"INSERT INTO ds_upload_sessions (id, scope, caller, expires_at, status, created_at) VALUES (?, ?, ?, ?, 'prepared', ?)\",\n  insertEntry:\n    \"INSERT INTO ds_upload_session_entries (session_id, path, cid, object_key, checksum_sha256, size, mime_type, if_match, device_id, mtime, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\",\n  selectSession: \"SELECT * FROM ds_upload_sessions WHERE id = ?\",\n  selectEntries: \"SELECT * FROM ds_upload_session_entries WHERE session_id = ?\",\n  updateEntryStatus:\n    \"UPDATE ds_upload_session_entries SET status = ? WHERE session_id = ? AND path = ?\",\n  markCommitted: \"UPDATE ds_upload_sessions SET status = 'committed' WHERE id = ?\",\n  markAborted: \"UPDATE ds_upload_sessions SET status = 'aborted' WHERE id = ?\",\n  sweepEntries:\n    \"DELETE FROM ds_upload_session_entries WHERE session_id IN (SELECT id FROM ds_upload_sessions WHERE expires_at < ?)\",\n  sweepSessions: \"DELETE FROM ds_upload_sessions WHERE expires_at < ?\",\n} as const;\n\n/** Positional bind args for `insertEntry` (shared by both backends). */\nfunction entryArgs(sessionId: string, e: UploadSessionEntryInput): unknown[] {\n  return [\n    sessionId,\n    e.path,\n    e.cid,\n    e.objectKey,\n    e.checksumSha256,\n    e.size,\n    e.mimeType ?? null,\n    e.ifMatch ?? null,\n    e.deviceId ?? null,\n    e.mtime ?? null,\n    e.status,\n  ];\n}\n\n// ─── D1 (Cloudflare) ────────────────────────────────────────────────────────\n\nexport class D1UploadSessionStore implements UploadSessionStore {\n  constructor(private readonly db: D1Database) {}\n\n  async ensureTable(): Promise<void> {\n    const stmts = [\n      this.db.prepare(UPLOAD_SESSIONS_TABLE_SQL),\n      this.db.prepare(UPLOAD_SESSION_ENTRIES_TABLE_SQL),\n      ...UPLOAD_SESSIONS_INDEX_SQL.map((sql) => this.db.prepare(sql)),\n    ];\n    await this.db.batch(stmts);\n  }\n\n  async createSession(input: NewUploadSession): Promise<void> {\n    assertNonEmpty(input);\n    const createdAt = input.createdAt ?? Date.now();\n    const stmts = [\n      this.db\n        .prepare(SQL.insertSession)\n        .bind(input.id, input.scope, input.caller ?? null, input.expiresAt, createdAt),\n      ...input.entries.map((e) => this.db.prepare(SQL.insertEntry).bind(...entryArgs(input.id, e))),\n    ];\n    await this.db.batch(stmts);\n  }\n\n  async getSession(id: string): Promise<UploadSession | null> {\n    const row = await this.db.prepare(SQL.selectSession).bind(id).first();\n    if (!row) return null;\n    const entries = await this.db.prepare(SQL.selectEntries).bind(id).all();\n    return rowToSession(\n      row as Record<string, unknown>,\n      entries.results as Array<Record<string, unknown>>,\n    );\n  }\n\n  async markEntries(\n    id: string,\n    updates: Array<{ path: string; status: UploadSessionEntryStatus }>,\n  ): Promise<void> {\n    if (updates.length === 0) return;\n    const stmts = updates.map((u) =>\n      this.db.prepare(SQL.updateEntryStatus).bind(u.status, id, u.path),\n    );\n    await this.db.batch(stmts);\n  }\n\n  async markCommitted(id: string): Promise<void> {\n    await this.db.prepare(SQL.markCommitted).bind(id).run();\n  }\n\n  async markAborted(id: string): Promise<void> {\n    await this.db.prepare(SQL.markAborted).bind(id).run();\n  }\n\n  async sweepExpired(now: number): Promise<number> {\n    // Delete entries first (no cascade in SQLite without PRAGMA), then sessions.\n    await this.db.prepare(SQL.sweepEntries).bind(now).run();\n    const res = await this.db.prepare(SQL.sweepSessions).bind(now).run();\n    return res.meta?.changes ?? 0;\n  }\n}\n\n// ─── libsql (Node) ──────────────────────────────────────────────────────────\n\nexport class SqliteUploadSessionStore implements UploadSessionStore {\n  constructor(private readonly client: LibsqlClient) {}\n\n  async ensureTable(): Promise<void> {\n    await this.client.execute(UPLOAD_SESSIONS_TABLE_SQL);\n    await this.client.execute(UPLOAD_SESSION_ENTRIES_TABLE_SQL);\n    for (const sql of UPLOAD_SESSIONS_INDEX_SQL) await this.client.execute(sql);\n  }\n\n  async createSession(input: NewUploadSession): Promise<void> {\n    assertNonEmpty(input);\n    const createdAt = input.createdAt ?? Date.now();\n    const stmts = [\n      {\n        sql: SQL.insertSession,\n        args: [\n          input.id,\n          input.scope,\n          input.caller ?? null,\n          input.expiresAt,\n          createdAt,\n        ] as InValue[],\n      },\n      ...input.entries.map((e) => ({\n        sql: SQL.insertEntry,\n        args: entryArgs(input.id, e) as InValue[],\n      })),\n    ];\n    await this.client.batch(stmts, \"write\");\n  }\n\n  async getSession(id: string): Promise<UploadSession | null> {\n    const sessionRes = await this.client.execute({ sql: SQL.selectSession, args: [id] });\n    if (sessionRes.rows.length === 0) return null;\n    const entriesRes = await this.client.execute({ sql: SQL.selectEntries, args: [id] });\n    return rowToSession(\n      sessionRes.rows[0] as unknown as Record<string, unknown>,\n      entriesRes.rows as unknown as Array<Record<string, unknown>>,\n    );\n  }\n\n  async markEntries(\n    id: string,\n    updates: Array<{ path: string; status: UploadSessionEntryStatus }>,\n  ): Promise<void> {\n    if (updates.length === 0) return;\n    await this.client.batch(\n      updates.map((u) => ({\n        sql: SQL.updateEntryStatus,\n        args: [u.status, id, u.path] as InValue[],\n      })),\n      \"write\",\n    );\n  }\n\n  async markCommitted(id: string): Promise<void> {\n    await this.client.execute({ sql: SQL.markCommitted, args: [id] });\n  }\n\n  async markAborted(id: string): Promise<void> {\n    await this.client.execute({ sql: SQL.markAborted, args: [id] });\n  }\n\n  async sweepExpired(now: number): Promise<number> {\n    await this.client.execute({ sql: SQL.sweepEntries, args: [now] });\n    const res = await this.client.execute({ sql: SQL.sweepSessions, args: [now] });\n    return res.rowsAffected ?? 0;\n  }\n}\n\n// ─── shared row mapping ───────────────────────────────────────────────────────\n\nfunction rowToSession(\n  s: Record<string, unknown>,\n  entryRows: Array<Record<string, unknown>>,\n): UploadSession {\n  return {\n    id: String(s.id),\n    scope: String(s.scope),\n    caller: s.caller == null ? null : String(s.caller),\n    expiresAt: Number(s.expires_at),\n    status: String(s.status) as UploadSessionStatus,\n    createdAt: Number(s.created_at),\n    entries: entryRows.map((e) => ({\n      path: String(e.path),\n      cid: String(e.cid),\n      objectKey: String(e.object_key),\n      checksumSha256: String(e.checksum_sha256),\n      size: Number(e.size),\n      mimeType: e.mime_type == null ? null : String(e.mime_type),\n      ifMatch: e.if_match == null ? null : String(e.if_match),\n      deviceId: e.device_id == null ? null : String(e.device_id),\n      mtime: e.mtime == null ? null : Number(e.mtime),\n      status: String(e.status) as UploadSessionEntryStatus,\n    })),\n  };\n}\n"],"mappings":"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"}

package/dist/url-normalize.cjs

@@ -0,0 +1,61 @@
+
+//#region src/url-normalize.ts
+/**
+* URL normalization for item dedup (#492).
+*
+* Produces a stable identity key for a saved URL so the same bookmark saved
+* from different surfaces (clean link, shared-with-tracking, different param
+* order, different anchor) collapses to one entry. Normalization is
+* intentionally CONSERVATIVE — it only removes parts that are never part of a
+* page's identity, so two genuinely different pages are never merged:
+*
+* - scheme + host are lower-cased and default ports dropped (the `URL`
+*   constructor does this per RFC 3986);
+* - the fragment (`#...`) is dropped — an anchor is a client-side scroll
+*   target, never server identity;
+* - the well-known `utm_*` family and unambiguous click IDs (fbclid, gclid, …)
+*   are stripped;
+* - remaining params are sorted so order doesn't create phantom duplicates.
+*
+* Ambiguous params like `ref` / `source` / `campaign` / `id` are deliberately
+* NOT stripped: they are load-bearing on many sites, and dropping them would
+* collapse distinct pages into one — a silent data loss on the merge step.
+* Only the `utm_` prefix and the explicit click-ID list below are removed.
+*
+* This is the shared normalization contract: every writer (web / native / AI)
+* that dedups by URL should key off this function so behavior is identical
+* across surfaces.
+*
+* Returns the original string unchanged if it is not a parseable absolute URL.
+*/
+/** Unambiguous click / tracking params (non-`utm_`) safe to strip everywhere. */
+const STRIP_PARAMS = new Set([
+	"fbclid",
+	"gclid",
+	"gbraid",
+	"wbraid",
+	"dclid",
+	"msclkid",
+	"yclid",
+	"mc_eid",
+	"igshid",
+	"twclid",
+	"ttclid"
+]);
+function normalizeItemUrl(raw) {
+	let u;
+	try {
+		u = new URL(raw);
+	} catch {
+		return raw;
+	}
+	u.hash = "";
+	const kept = new URLSearchParams();
+	for (const [k, v] of u.searchParams) if (!k.startsWith("utm_") && !STRIP_PARAMS.has(k)) kept.append(k, v);
+	u.search = kept.toString();
+	u.searchParams.sort();
+	return u.toString();
+}
+
+//#endregion
+exports.normalizeItemUrl = normalizeItemUrl;

package/dist/url-normalize.d.cts

@@ -0,0 +1,33 @@
+//#region src/url-normalize.d.ts
+/**
+ * URL normalization for item dedup (#492).
+ *
+ * Produces a stable identity key for a saved URL so the same bookmark saved
+ * from different surfaces (clean link, shared-with-tracking, different param
+ * order, different anchor) collapses to one entry. Normalization is
+ * intentionally CONSERVATIVE — it only removes parts that are never part of a
+ * page's identity, so two genuinely different pages are never merged:
+ *
+ * - scheme + host are lower-cased and default ports dropped (the `URL`
+ *   constructor does this per RFC 3986);
+ * - the fragment (`#...`) is dropped — an anchor is a client-side scroll
+ *   target, never server identity;
+ * - the well-known `utm_*` family and unambiguous click IDs (fbclid, gclid, …)
+ *   are stripped;
+ * - remaining params are sorted so order doesn't create phantom duplicates.
+ *
+ * Ambiguous params like `ref` / `source` / `campaign` / `id` are deliberately
+ * NOT stripped: they are load-bearing on many sites, and dropping them would
+ * collapse distinct pages into one — a silent data loss on the merge step.
+ * Only the `utm_` prefix and the explicit click-ID list below are removed.
+ *
+ * This is the shared normalization contract: every writer (web / native / AI)
+ * that dedups by URL should key off this function so behavior is identical
+ * across surfaces.
+ *
+ * Returns the original string unchanged if it is not a parseable absolute URL.
+ */
+declare function normalizeItemUrl(raw: string): string;
+//#endregion
+export { normalizeItemUrl };
+//# sourceMappingURL=url-normalize.d.cts.map

package/dist/url-normalize.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-normalize.d.cts","names":[],"sources":["../src/url-normalize.ts"],"mappings":";;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,gBAAA,CAAiB,GAAA"}

package/dist/url-normalize.d.mts

@@ -0,0 +1,33 @@
+//#region src/url-normalize.d.ts
+/**
+ * URL normalization for item dedup (#492).
+ *
+ * Produces a stable identity key for a saved URL so the same bookmark saved
+ * from different surfaces (clean link, shared-with-tracking, different param
+ * order, different anchor) collapses to one entry. Normalization is
+ * intentionally CONSERVATIVE — it only removes parts that are never part of a
+ * page's identity, so two genuinely different pages are never merged:
+ *
+ * - scheme + host are lower-cased and default ports dropped (the `URL`
+ *   constructor does this per RFC 3986);
+ * - the fragment (`#...`) is dropped — an anchor is a client-side scroll
+ *   target, never server identity;
+ * - the well-known `utm_*` family and unambiguous click IDs (fbclid, gclid, …)
+ *   are stripped;
+ * - remaining params are sorted so order doesn't create phantom duplicates.
+ *
+ * Ambiguous params like `ref` / `source` / `campaign` / `id` are deliberately
+ * NOT stripped: they are load-bearing on many sites, and dropping them would
+ * collapse distinct pages into one — a silent data loss on the merge step.
+ * Only the `utm_` prefix and the explicit click-ID list below are removed.
+ *
+ * This is the shared normalization contract: every writer (web / native / AI)
+ * that dedups by URL should key off this function so behavior is identical
+ * across surfaces.
+ *
+ * Returns the original string unchanged if it is not a parseable absolute URL.
+ */
+declare function normalizeItemUrl(raw: string): string;
+//#endregion
+export { normalizeItemUrl };
+//# sourceMappingURL=url-normalize.d.mts.map

package/dist/url-normalize.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-normalize.d.mts","names":[],"sources":["../src/url-normalize.ts"],"mappings":";;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,gBAAA,CAAiB,GAAA"}

package/dist/url-normalize.mjs

@@ -0,0 +1,61 @@
+//#region src/url-normalize.ts
+/**
+* URL normalization for item dedup (#492).
+*
+* Produces a stable identity key for a saved URL so the same bookmark saved
+* from different surfaces (clean link, shared-with-tracking, different param
+* order, different anchor) collapses to one entry. Normalization is
+* intentionally CONSERVATIVE — it only removes parts that are never part of a
+* page's identity, so two genuinely different pages are never merged:
+*
+* - scheme + host are lower-cased and default ports dropped (the `URL`
+*   constructor does this per RFC 3986);
+* - the fragment (`#...`) is dropped — an anchor is a client-side scroll
+*   target, never server identity;
+* - the well-known `utm_*` family and unambiguous click IDs (fbclid, gclid, …)
+*   are stripped;
+* - remaining params are sorted so order doesn't create phantom duplicates.
+*
+* Ambiguous params like `ref` / `source` / `campaign` / `id` are deliberately
+* NOT stripped: they are load-bearing on many sites, and dropping them would
+* collapse distinct pages into one — a silent data loss on the merge step.
+* Only the `utm_` prefix and the explicit click-ID list below are removed.
+*
+* This is the shared normalization contract: every writer (web / native / AI)
+* that dedups by URL should key off this function so behavior is identical
+* across surfaces.
+*
+* Returns the original string unchanged if it is not a parseable absolute URL.
+*/
+/** Unambiguous click / tracking params (non-`utm_`) safe to strip everywhere. */
+const STRIP_PARAMS = new Set([
+	"fbclid",
+	"gclid",
+	"gbraid",
+	"wbraid",
+	"dclid",
+	"msclkid",
+	"yclid",
+	"mc_eid",
+	"igshid",
+	"twclid",
+	"ttclid"
+]);
+function normalizeItemUrl(raw) {
+	let u;
+	try {
+		u = new URL(raw);
+	} catch {
+		return raw;
+	}
+	u.hash = "";
+	const kept = new URLSearchParams();
+	for (const [k, v] of u.searchParams) if (!k.startsWith("utm_") && !STRIP_PARAMS.has(k)) kept.append(k, v);
+	u.search = kept.toString();
+	u.searchParams.sort();
+	return u.toString();
+}
+
+//#endregion
+export { normalizeItemUrl };
+//# sourceMappingURL=url-normalize.mjs.map

package/dist/url-normalize.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-normalize.mjs","names":[],"sources":["../src/url-normalize.ts"],"sourcesContent":["/**\n * URL normalization for item dedup (#492).\n *\n * Produces a stable identity key for a saved URL so the same bookmark saved\n * from different surfaces (clean link, shared-with-tracking, different param\n * order, different anchor) collapses to one entry. Normalization is\n * intentionally CONSERVATIVE — it only removes parts that are never part of a\n * page's identity, so two genuinely different pages are never merged:\n *\n * - scheme + host are lower-cased and default ports dropped (the `URL`\n *   constructor does this per RFC 3986);\n * - the fragment (`#...`) is dropped — an anchor is a client-side scroll\n *   target, never server identity;\n * - the well-known `utm_*` family and unambiguous click IDs (fbclid, gclid, …)\n *   are stripped;\n * - remaining params are sorted so order doesn't create phantom duplicates.\n *\n * Ambiguous params like `ref` / `source` / `campaign` / `id` are deliberately\n * NOT stripped: they are load-bearing on many sites, and dropping them would\n * collapse distinct pages into one — a silent data loss on the merge step.\n * Only the `utm_` prefix and the explicit click-ID list below are removed.\n *\n * This is the shared normalization contract: every writer (web / native / AI)\n * that dedups by URL should key off this function so behavior is identical\n * across surfaces.\n *\n * Returns the original string unchanged if it is not a parseable absolute URL.\n */\n\n/** Unambiguous click / tracking params (non-`utm_`) safe to strip everywhere. */\nconst STRIP_PARAMS = new Set([\n  \"fbclid\", // Facebook\n  \"gclid\", // Google Ads\n  \"gbraid\", // Google Ads (iOS)\n  \"wbraid\", // Google Ads (web→app)\n  \"dclid\", // Google DoubleClick\n  \"msclkid\", // Microsoft Ads\n  \"yclid\", // Yandex\n  \"mc_eid\", // Mailchimp\n  \"igshid\", // Instagram\n  \"twclid\", // Twitter / X\n  \"ttclid\", // TikTok\n]);\n\nexport function normalizeItemUrl(raw: string): string {\n  let u: URL;\n  try {\n    u = new URL(raw);\n  } catch {\n    return raw;\n  }\n  // Drop the fragment — an anchor is never part of a bookmark's identity.\n  u.hash = \"\";\n  const kept = new URLSearchParams();\n  for (const [k, v] of u.searchParams) {\n    if (!k.startsWith(\"utm_\") && !STRIP_PARAMS.has(k)) {\n      // append (not set) so legitimately repeated keys survive intact.\n      kept.append(k, v);\n    }\n  }\n  u.search = kept.toString();\n  // Sort remaining params so param order doesn't create phantom duplicates.\n  u.searchParams.sort();\n  return u.toString();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAM,eAAe,IAAI,IAAI;CAC3B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAgB,iBAAiB,KAAqB;CACpD,IAAI;AACJ,KAAI;AACF,MAAI,IAAI,IAAI,IAAI;SACV;AACN,SAAO;;AAGT,GAAE,OAAO;CACT,MAAM,OAAO,IAAI,iBAAiB;AAClC,MAAK,MAAM,CAAC,GAAG,MAAM,EAAE,aACrB,KAAI,CAAC,EAAE,WAAW,OAAO,IAAI,CAAC,aAAa,IAAI,EAAE,CAE/C,MAAK,OAAO,GAAG,EAAE;AAGrB,GAAE,SAAS,KAAK,UAAU;AAE1B,GAAE,aAAa,MAAM;AACrB,QAAO,EAAE,UAAU"}