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

package/dist/scope-migration-node.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration-node.d.cts","names":[],"sources":["../src/scope-migration-node.ts"],"mappings":";;;UAiCiB,yBAAA;;EAEf,MAAA;AAAA;AAAA,UAGe,wBAAA;EAHf;EAKA,OAAA;EAFe;EAIf,IAAA;;EAEA,OAAA;EAJA;EAMA,MAAA;IAAU,QAAA;IAAkB,OAAA;EAAA;AAAA;;;AAwB9B;;;;;;;;;iBAAsB,qBAAA,CACpB,MAAA,EAAQ,MAAA,EACR,CAAA,UACA,GAAA,EAAK,UAAA,GACJ,OAAA;;;;;iBA+EmB,iBAAA,CAAkB,IAAA;EACtC,QAAA;EACA,GAAA,EAAK,UAAA;EACL,MAAA;AAAA,IACE,OAAA,CAAQ,wBAAA"}

package/dist/scope-migration-node.d.mts

@@ -0,0 +1,44 @@
+import { Client } from "@libsql/client";
+
+//#region src/scope-migration-node.d.ts
+interface NodeScopeMigrationOptions {
+  /** Classify only — list migrate/skip, rewrite + rename nothing. */
+  dryRun?: boolean;
+}
+interface NodeScopeMigrationReport {
+  /** Plaintext DID directory names that WILL be / WERE migrated (sorted). */
+  migrate: string[];
+  /** Non-DID directory names skipped: already-derived hash / versioned / junk (sorted). */
+  skip: string[];
+  /** Count of directories actually renamed (0 when dryRun). */
+  renamed: number;
+  /** `_shares.db` owner_did migration outcome. */
+  shares: {
+    migrated: number;
+    skipped: number;
+  };
+}
+/**
+ * Rewrite a single per-user `_metadata.db` for the DID scope `s` → derived.
+ * Atomic (one write batch). The caller MUST close the client before renaming
+ * the directory.
+ *
+ * Probes table existence first: older `_metadata.db` files predate
+ * `prefix_watermark` / `sync_state` / `cid_cache` (added by later phases), so
+ * each statement is included ONLY when its table exists — otherwise libsql
+ * throws "no such table" and the whole batch aborts. `entries` / `changelog`
+ * are the core tables (always present in a real space db).
+ */
+declare function migrateNodeMetadataDb(client: Client, s: string, key: Uint8Array): Promise<void>;
+/**
+ * Migrate (or, with `dryRun`, classify) every plaintext-DID space under
+ * `rootPath`, plus the daemon-global `_shares.db`.
+ */
+declare function migrateNodeSpaces(opts: {
+  rootPath: string;
+  key: Uint8Array;
+  dryRun?: boolean;
+}): Promise<NodeScopeMigrationReport>;
+//#endregion
+export { NodeScopeMigrationOptions, NodeScopeMigrationReport, migrateNodeMetadataDb, migrateNodeSpaces };
+//# sourceMappingURL=scope-migration-node.d.mts.map

package/dist/scope-migration-node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration-node.d.mts","names":[],"sources":["../src/scope-migration-node.ts"],"mappings":";;;UAiCiB,yBAAA;;EAEf,MAAA;AAAA;AAAA,UAGe,wBAAA;EAHf;EAKA,OAAA;EAFe;EAIf,IAAA;;EAEA,OAAA;EAJA;EAMA,MAAA;IAAU,QAAA;IAAkB,OAAA;EAAA;AAAA;;;AAwB9B;;;;;;;;;iBAAsB,qBAAA,CACpB,MAAA,EAAQ,MAAA,EACR,CAAA,UACA,GAAA,EAAK,UAAA,GACJ,OAAA;;;;;iBA+EmB,iBAAA,CAAkB,IAAA;EACtC,QAAA;EACA,GAAA,EAAK,UAAA;EACL,MAAA;AAAA,IACE,OAAA,CAAQ,wBAAA"}

package/dist/scope-migration-node.mjs

@@ -0,0 +1,171 @@
+import { deriveScope, isPlainDidScope } from "./scope-id.mjs";
+import { existsSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { createClient } from "@libsql/client";
+
+//#region src/scope-migration-node.ts
+/**
+* scope-migration-node — offline Node scope de-identification migration (README §5.4).
+*
+* Migrates the existing PLAINTEXT DID-scoped per-user spaces on a local disk to
+* derived HMAC scopes. Unlike the CF migration (one shared D1), Node stores each
+* user under `{rootPath}/{scope}/_metadata.db` + a daemon-global
+* `{rootPath}/_shares.db`, so this is a per-DIRECTORY rename plus a per-db
+* rewrite. OFFLINE tool: the daemon MUST be stopped first (README §5.4).
+*
+* Per directory `{rootPath}/{s}` whose basename `s` is a plaintext DID:
+*   1. Rewrite `_metadata.db` scope columns (entries / changelog /
+*      prefix_watermark) where `scope = s` → `deriveScope(s)`, rewrite the
+*      `sync_state` `{s}:` key prefix (INSERT+DELETE — can't UPDATE a PK; the
+*      bare `device_id` key has no `{s}:` prefix so it is preserved), and clear
+*      `cid_cache` (no scope column, rebuildable). `sync_checkpoint` (transient)
+*      and `gc_queue` (cid-keyed) are untouched. ALL in one atomic batch.
+*   2. `fs.rename` the directory to `{rootPath}/{deriveScope(s)}` — done LAST so
+*      the directory name is the idempotency marker: an interrupted run leaves a
+*      plaintext dir (re-run completes it), and a finished dir is a hash
+*      (`isPlainDidScope` false → skipped). The per-db batch is itself
+*      idempotent (keyed on the old plaintext `s`, a no-op once moved).
+*
+* Then the daemon-global `_shares.db.owner_did` is migrated once (same DID
+* classification). Strict: only true DIDs migrate; versioned / already-derived /
+* junk are skipped + reported, never silently HMAC'd.
+*/
+/** Which of `names` exist as tables in this db. */
+async function existingTables(client, names) {
+	const placeholders = names.map(() => "?").join(", ");
+	const res = await client.execute({
+		sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`,
+		args: names
+	});
+	return new Set((res.rows ?? []).map((r) => r.name));
+}
+/**
+* Rewrite a single per-user `_metadata.db` for the DID scope `s` → derived.
+* Atomic (one write batch). The caller MUST close the client before renaming
+* the directory.
+*
+* Probes table existence first: older `_metadata.db` files predate
+* `prefix_watermark` / `sync_state` / `cid_cache` (added by later phases), so
+* each statement is included ONLY when its table exists — otherwise libsql
+* throws "no such table" and the whole batch aborts. `entries` / `changelog`
+* are the core tables (always present in a real space db).
+*/
+async function migrateNodeMetadataDb(client, s, key) {
+	const h = deriveScope(s, key);
+	const scopedPrefix = `${s}:`;
+	const derivedPrefix = `${h}:`;
+	const likeOld = `${s}:%`;
+	const present = await existingTables(client, [
+		"ds_entries",
+		"ds_changelog",
+		"ds_prefix_watermark",
+		"ds_dirty_path",
+		"ds_sync_state",
+		"cid_cache"
+	]);
+	const stmts = [];
+	if (present.has("ds_entries")) stmts.push({
+		sql: "UPDATE ds_entries SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_changelog")) stmts.push({
+		sql: "UPDATE ds_changelog SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_prefix_watermark")) stmts.push({
+		sql: "UPDATE ds_prefix_watermark SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_dirty_path")) stmts.push({
+		sql: "UPDATE ds_dirty_path SET scope = ? WHERE scope = ?",
+		args: [h, s]
+	});
+	if (present.has("ds_sync_state")) {
+		stmts.push({
+			sql: "INSERT OR IGNORE INTO ds_sync_state(key, value) SELECT replace(key, ?, ?), value FROM ds_sync_state WHERE key LIKE ?",
+			args: [
+				scopedPrefix,
+				derivedPrefix,
+				likeOld
+			]
+		});
+		stmts.push({
+			sql: "DELETE FROM ds_sync_state WHERE key LIKE ?",
+			args: [likeOld]
+		});
+	}
+	if (present.has("cid_cache")) stmts.push({
+		sql: "DELETE FROM cid_cache",
+		args: []
+	});
+	if (stmts.length > 0) await client.batch(stmts, "write");
+}
+/** Migrate `_shares.db.owner_did` for every plaintext-DID owner (one batch). */
+async function migrateNodeShares(sharesPath, key, dryRun) {
+	const client = createClient({ url: `file:${sharesPath}` });
+	try {
+		const owners = ((await client.execute("SELECT DISTINCT owner_did AS v FROM ds_shares")).rows ?? []).map((r) => r.v).filter((v) => v != null);
+		const migrate = owners.filter((o) => isPlainDidScope(o));
+		const skipped = owners.length - migrate.length;
+		if (dryRun || migrate.length === 0) return {
+			migrated: 0,
+			skipped
+		};
+		await client.batch(migrate.map((o) => ({
+			sql: "UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?",
+			args: [deriveScope(o, key), o]
+		})), "write");
+		return {
+			migrated: migrate.length,
+			skipped
+		};
+	} finally {
+		client.close();
+	}
+}
+/**
+* Migrate (or, with `dryRun`, classify) every plaintext-DID space under
+* `rootPath`, plus the daemon-global `_shares.db`.
+*/
+async function migrateNodeSpaces(opts) {
+	const { rootPath, key, dryRun = false } = opts;
+	const migrate = [];
+	const skip = [];
+	const entries = existsSync(rootPath) ? readdirSync(rootPath, { withFileTypes: true }) : [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		(isPlainDidScope(entry.name) ? migrate : skip).push(entry.name);
+	}
+	migrate.sort();
+	skip.sort();
+	let renamed = 0;
+	if (!dryRun) for (const s of migrate) {
+		const dir = join(rootPath, s);
+		const dbPath = join(dir, "_metadata.db");
+		if (existsSync(dbPath)) {
+			const client = createClient({ url: `file:${dbPath}` });
+			try {
+				await migrateNodeMetadataDb(client, s, key);
+			} finally {
+				client.close();
+			}
+		}
+		renameSync(dir, join(rootPath, deriveScope(s, key)));
+		renamed++;
+	}
+	const sharesPath = join(rootPath, "_shares.db");
+	const shares = existsSync(sharesPath) ? await migrateNodeShares(sharesPath, key, dryRun) : {
+		migrated: 0,
+		skipped: 0
+	};
+	return {
+		migrate,
+		skip,
+		renamed,
+		shares
+	};
+}
+
+//#endregion
+export { migrateNodeMetadataDb, migrateNodeSpaces };
+//# sourceMappingURL=scope-migration-node.mjs.map

package/dist/scope-migration-node.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration-node.mjs","names":[],"sources":["../src/scope-migration-node.ts"],"sourcesContent":["/**\n * scope-migration-node — offline Node scope de-identification migration (README §5.4).\n *\n * Migrates the existing PLAINTEXT DID-scoped per-user spaces on a local disk to\n * derived HMAC scopes. Unlike the CF migration (one shared D1), Node stores each\n * user under `{rootPath}/{scope}/_metadata.db` + a daemon-global\n * `{rootPath}/_shares.db`, so this is a per-DIRECTORY rename plus a per-db\n * rewrite. OFFLINE tool: the daemon MUST be stopped first (README §5.4).\n *\n * Per directory `{rootPath}/{s}` whose basename `s` is a plaintext DID:\n *   1. Rewrite `_metadata.db` scope columns (entries / changelog /\n *      prefix_watermark) where `scope = s` → `deriveScope(s)`, rewrite the\n *      `sync_state` `{s}:` key prefix (INSERT+DELETE — can't UPDATE a PK; the\n *      bare `device_id` key has no `{s}:` prefix so it is preserved), and clear\n *      `cid_cache` (no scope column, rebuildable). `sync_checkpoint` (transient)\n *      and `gc_queue` (cid-keyed) are untouched. ALL in one atomic batch.\n *   2. `fs.rename` the directory to `{rootPath}/{deriveScope(s)}` — done LAST so\n *      the directory name is the idempotency marker: an interrupted run leaves a\n *      plaintext dir (re-run completes it), and a finished dir is a hash\n *      (`isPlainDidScope` false → skipped). The per-db batch is itself\n *      idempotent (keyed on the old plaintext `s`, a no-op once moved).\n *\n * Then the daemon-global `_shares.db.owner_did` is migrated once (same DID\n * classification). Strict: only true DIDs migrate; versioned / already-derived /\n * junk are skipped + reported, never silently HMAC'd.\n */\n// biome-ignore lint/style/noRestrictedImports: offline migration manages physical DID-space directories\nimport { existsSync, readdirSync, renameSync } from \"node:fs\";\n// biome-ignore lint/style/noRestrictedImports: filesystem path joins for the on-disk directory layout\nimport { join } from \"node:path\";\nimport { type Client, createClient } from \"@libsql/client\";\nimport { deriveScope, isPlainDidScope } from \"./scope-id.js\";\n\nexport interface NodeScopeMigrationOptions {\n  /** Classify only — list migrate/skip, rewrite + rename nothing. */\n  dryRun?: boolean;\n}\n\nexport interface NodeScopeMigrationReport {\n  /** Plaintext DID directory names that WILL be / WERE migrated (sorted). */\n  migrate: string[];\n  /** Non-DID directory names skipped: already-derived hash / versioned / junk (sorted). */\n  skip: string[];\n  /** Count of directories actually renamed (0 when dryRun). */\n  renamed: number;\n  /** `_shares.db` owner_did migration outcome. */\n  shares: { migrated: number; skipped: number };\n}\n\n/** Which of `names` exist as tables in this db. */\nasync function existingTables(client: Client, names: string[]): Promise<Set<string>> {\n  const placeholders = names.map(() => \"?\").join(\", \");\n  const res = await client.execute({\n    sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`,\n    args: names,\n  });\n  return new Set((res.rows ?? []).map((r) => r.name as string));\n}\n\n/**\n * Rewrite a single per-user `_metadata.db` for the DID scope `s` → derived.\n * Atomic (one write batch). The caller MUST close the client before renaming\n * the directory.\n *\n * Probes table existence first: older `_metadata.db` files predate\n * `prefix_watermark` / `sync_state` / `cid_cache` (added by later phases), so\n * each statement is included ONLY when its table exists — otherwise libsql\n * throws \"no such table\" and the whole batch aborts. `entries` / `changelog`\n * are the core tables (always present in a real space db).\n */\nexport async function migrateNodeMetadataDb(\n  client: Client,\n  s: string,\n  key: Uint8Array,\n): Promise<void> {\n  const h = deriveScope(s, key);\n  const scopedPrefix = `${s}:`;\n  const derivedPrefix = `${h}:`;\n  const likeOld = `${s}:%`;\n  const present = await existingTables(client, [\n    \"ds_entries\",\n    \"ds_changelog\",\n    \"ds_prefix_watermark\",\n    \"ds_dirty_path\",\n    \"ds_sync_state\",\n    \"cid_cache\",\n  ]);\n\n  const stmts: Parameters<Client[\"batch\"]>[0] = [];\n  if (present.has(\"ds_entries\")) {\n    stmts.push({ sql: \"UPDATE ds_entries SET scope = ? WHERE scope = ?\", args: [h, s] });\n  }\n  if (present.has(\"ds_changelog\")) {\n    stmts.push({ sql: \"UPDATE ds_changelog SET scope = ? WHERE scope = ?\", args: [h, s] });\n  }\n  if (present.has(\"ds_prefix_watermark\")) {\n    stmts.push({ sql: \"UPDATE ds_prefix_watermark SET scope = ? WHERE scope = ?\", args: [h, s] });\n  }\n  if (present.has(\"ds_dirty_path\")) {\n    // index-follower-dirty-path §10.2: move the dirty backlog to the HMAC scope\n    // so the migrated user's follower keeps finding its pending rows.\n    stmts.push({ sql: \"UPDATE ds_dirty_path SET scope = ? WHERE scope = ?\", args: [h, s] });\n  }\n  if (present.has(\"ds_sync_state\")) {\n    // Rewrite the `{s}:` key prefix. INSERT the derived-prefixed rows first, then\n    // DELETE the plaintext-prefixed ones — the bare `device_id` key (no `{s}:`\n    // prefix) is never matched, so it survives.\n    stmts.push({\n      sql: \"INSERT OR IGNORE INTO ds_sync_state(key, value) SELECT replace(key, ?, ?), value FROM ds_sync_state WHERE key LIKE ?\",\n      args: [scopedPrefix, derivedPrefix, likeOld],\n    });\n    stmts.push({ sql: \"DELETE FROM ds_sync_state WHERE key LIKE ?\", args: [likeOld] });\n  }\n  if (present.has(\"cid_cache\")) {\n    // Clear (no scope column; path→cid cache is rebuildable and the dir rename\n    // invalidates absolute paths anyway). sync_checkpoint (transient session\n    // state) + gc_queue (cid-keyed) are intentionally left untouched.\n    stmts.push({ sql: \"DELETE FROM cid_cache\", args: [] });\n  }\n\n  if (stmts.length > 0) await client.batch(stmts, \"write\");\n}\n\n/** Migrate `_shares.db.owner_did` for every plaintext-DID owner (one batch). */\nasync function migrateNodeShares(\n  sharesPath: string,\n  key: Uint8Array,\n  dryRun: boolean,\n): Promise<{ migrated: number; skipped: number }> {\n  const client = createClient({ url: `file:${sharesPath}` });\n  try {\n    const res = await client.execute(\"SELECT DISTINCT owner_did AS v FROM ds_shares\");\n    const owners = (res.rows ?? []).map((r) => r.v as string).filter((v): v is string => v != null);\n    const migrate = owners.filter((o) => isPlainDidScope(o));\n    const skipped = owners.length - migrate.length;\n    if (dryRun || migrate.length === 0) return { migrated: 0, skipped };\n    await client.batch(\n      migrate.map((o) => ({\n        sql: \"UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?\",\n        args: [deriveScope(o, key), o],\n      })),\n      \"write\",\n    );\n    return { migrated: migrate.length, skipped };\n  } finally {\n    client.close();\n  }\n}\n\n/**\n * Migrate (or, with `dryRun`, classify) every plaintext-DID space under\n * `rootPath`, plus the daemon-global `_shares.db`.\n */\nexport async function migrateNodeSpaces(opts: {\n  rootPath: string;\n  key: Uint8Array;\n  dryRun?: boolean;\n}): Promise<NodeScopeMigrationReport> {\n  const { rootPath, key, dryRun = false } = opts;\n  const migrate: string[] = [];\n  const skip: string[] = [];\n\n  const entries = existsSync(rootPath) ? readdirSync(rootPath, { withFileTypes: true }) : [];\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    (isPlainDidScope(entry.name) ? migrate : skip).push(entry.name);\n  }\n  migrate.sort();\n  skip.sort();\n\n  let renamed = 0;\n  if (!dryRun) {\n    for (const s of migrate) {\n      const dir = join(rootPath, s);\n      const dbPath = join(dir, \"_metadata.db\");\n      if (existsSync(dbPath)) {\n        const client = createClient({ url: `file:${dbPath}` });\n        try {\n          await migrateNodeMetadataDb(client, s, key);\n        } finally {\n          // MUST close before renaming the directory (the file handle is held).\n          client.close();\n        }\n      }\n      // Rename LAST — the directory name is the idempotency marker.\n      renameSync(dir, join(rootPath, deriveScope(s, key)));\n      renamed++;\n    }\n  }\n\n  const sharesPath = join(rootPath, \"_shares.db\");\n  const shares = existsSync(sharesPath)\n    ? await migrateNodeShares(sharesPath, key, dryRun)\n    : { migrated: 0, skipped: 0 };\n\n  return { migrate, skip, renamed, shares };\n}\n"],"mappings":"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"}

package/dist/scope-migration.cjs

@@ -0,0 +1,155 @@
+const require_changelog_schema = require('./changelog-schema.cjs');
+const require_scope_id = require('./scope-id.cjs');
+
+//#region src/scope-migration.ts
+/**
+* scope-migration — offline D1 scope de-identification migration (README §4.5).
+*
+* Migrates the existing PLAINTEXT DID scopes in a CF D1 database to derived
+* HMAC scopes, in place. This is an OFFLINE ops tool (not a DDL migration, not
+* on the request path): a local Node process holds the deployment secret,
+* derives scopes with the SAME `deriveScope` the runtime uses, and rewrites the
+* scope columns.
+*
+* Strict / fail-closed classification: only scopes for which
+* `isPlainDidScope` (= `@arcblock/did#isValid`) is true are migrated. Versioned
+* content scopes (`schema:pkg:1.2.3`), already-derived base32 hashes, bare names
+* (`persona`) and junk are SKIPPED and logged — never silently HMAC'd. Because
+* an already-derived hash is not a valid DID, a re-run sees it as non-DID and
+* skips it: the migration is idempotent with no external "done" set.
+*
+* The thin CLI wrapper (runtimes/cloudflare/scripts/migrate-scope.mjs) handles
+* argv + the D1 connection + the STOP GATE print; this module holds the
+* testable logic so `test/migration.test.ts` can drive it against a mock D1.
+*/
+/**
+* Tables with a `scope` column that hold per-user DID-scoped data. `scope_meta`
+* is intentionally absent — it is a derived count and is REBUILT after the
+* scope columns move (UPDATE does not fire the file_count triggers, so a stale
+* plaintext row would remain). `versioned_scopes` / `resolve_entries` /
+* `gc_queue` are exempt by design (README §4.5 matrix).
+*/
+const SCOPE_TABLES = [
+	"ds_entries",
+	"ds_changelog",
+	"ds_prefix_watermark",
+	"ds_device_sync_state",
+	"ds_dirty_path"
+];
+async function tableExists(db, name) {
+	return await db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").bind(name).first() != null;
+}
+async function distinctColumn(db, table, column) {
+	return ((await db.prepare(`SELECT DISTINCT ${column} AS v FROM ${table}`).all()).results ?? []).map((r) => r.v).filter((v) => v != null);
+}
+/**
+* Migrate (or, with `dryRun`, classify) all plaintext DID scopes in `db`.
+*
+* @param db   the D1 database (or a compatible mock) — the bound runtime D1
+* @param key  the deployment HMAC secret bytes (from `decodeScopeHmacSecret`)
+* @param opts `{ dryRun }` to classify without writing
+*/
+async function migrateD1Scopes(db, key, opts = {}) {
+	const tablesPresent = [];
+	for (const t of SCOPE_TABLES) if (await tableExists(db, t)) tablesPresent.push(t);
+	const hasShares = await tableExists(db, "ds_shares");
+	const hasScopeMeta = await tableExists(db, "ds_scope_meta");
+	const candidateSet = /* @__PURE__ */ new Set();
+	for (const t of tablesPresent) for (const s of await distinctColumn(db, t, "scope")) candidateSet.add(s);
+	if (hasShares) for (const s of await distinctColumn(db, "ds_shares", "owner_did")) candidateSet.add(s);
+	const migrate = [];
+	const skip = [];
+	for (const s of candidateSet) (require_scope_id.isPlainDidScope(s) ? migrate : skip).push(s);
+	migrate.sort();
+	skip.sort();
+	const base = {
+		tablesPresent,
+		hasShares,
+		hasScopeMeta,
+		candidates: candidateSet.size,
+		migrate,
+		skip,
+		migrated: 0,
+		scopeMetaRebuilt: false
+	};
+	if (opts.dryRun) return base;
+	for (const s of migrate) {
+		const h = require_scope_id.deriveScope(s, key);
+		const stmts = tablesPresent.map((t) => db.prepare(`UPDATE ${t} SET scope = ? WHERE scope = ?`).bind(h, s));
+		if (hasShares) stmts.push(db.prepare("UPDATE ds_shares SET owner_did = ? WHERE owner_did = ?").bind(h, s));
+		await db.batch(stmts);
+	}
+	let scopeMetaRebuilt = false;
+	if (hasScopeMeta && migrate.length > 0) {
+		const placeholders = migrate.map(() => "?").join(", ");
+		await db.prepare(`DELETE FROM ds_scope_meta WHERE scope IN (${placeholders})`).bind(...migrate).run();
+		await db.prepare(require_changelog_schema.SCOPE_META_FILE_COUNT_BACKFILL_SQL).run();
+		scopeMetaRebuilt = true;
+	}
+	return {
+		...base,
+		migrated: migrate.length,
+		scopeMetaRebuilt
+	};
+}
+/** Classify distinct scope strings into migrate (plaintext DID) vs skip. */
+function classifyScopes(scopes) {
+	const migrate = [];
+	const skip = [];
+	for (const s of [...new Set(scopes)]) (require_scope_id.isPlainDidScope(s) ? migrate : skip).push(s);
+	migrate.sort();
+	skip.sort();
+	return {
+		migrate,
+		skip
+	};
+}
+const SQL_SCOPE_COLUMN_TABLES = [
+	"ds_entries",
+	"ds_changelog",
+	"ds_prefix_watermark",
+	"ds_dirty_path"
+];
+/**
+* Generate the migration `.sql` for a REMOTE CF D1 (README §4.5 离线脚本形态).
+*
+* The HMAC is computed HERE (D1 SQL can't); the operator dumps the distinct
+* scopes with `wrangler d1 execute --remote --json` and applies the emitted file
+* with `wrangler d1 execute --remote --file`. Only plaintext DID scopes are
+* rewritten — versioned `schema:…` / already-derived / junk are left out, so a
+* re-apply is idempotent (their `WHERE scope = '<old DID>'` matches nothing).
+*
+* Statement order matters: all scope UPDATEs first, then the scope_meta rebuild
+* (DELETE stale plaintext rows + BACKFILL derived counts from the now-moved
+* entries). `entries` / `changelog` / `prefix_watermark` are CF's standard
+* scope-bearing tables (migrations 0100–0107); `device_sync_state` is absent.
+*/
+function buildD1MigrationSql(scopes, key, opts = {}) {
+	const { includeShares = true, includeScopeMeta = true } = opts;
+	const { migrate, skip } = classifyScopes(scopes);
+	const q = (v) => `'${v.replace(/'/g, "''")}'`;
+	const lines = [
+		"-- DID Space scope de-identification migration (generated).",
+		"-- Apply with: wrangler d1 execute <DB> --remote --file <this-file>",
+		`-- migrate ${migrate.length} DID scope(s); skip ${skip.length} non-DID scope(s).`
+	];
+	for (const s of migrate) {
+		const h = require_scope_id.deriveScope(s, key);
+		for (const t of SQL_SCOPE_COLUMN_TABLES) lines.push(`UPDATE ${t} SET scope = ${q(h)} WHERE scope = ${q(s)};`);
+		if (includeShares) lines.push(`UPDATE ds_shares SET owner_did = ${q(h)} WHERE owner_did = ${q(s)};`);
+	}
+	if (includeScopeMeta && migrate.length > 0) {
+		lines.push(`DELETE FROM ds_scope_meta WHERE scope IN (${migrate.map(q).join(", ")});`);
+		lines.push(`${require_changelog_schema.SCOPE_META_FILE_COUNT_BACKFILL_SQL};`);
+	}
+	return {
+		sql: `${lines.join("\n")}\n`,
+		migrate,
+		skip
+	};
+}
+
+//#endregion
+exports.buildD1MigrationSql = buildD1MigrationSql;
+exports.classifyScopes = classifyScopes;
+exports.migrateD1Scopes = migrateD1Scopes;

package/dist/scope-migration.d.cts

@@ -0,0 +1,65 @@
+//#region src/scope-migration.d.ts
+interface ScopeMigrationOptions {
+  /** Classify only — collect + classify candidates, write nothing (STOP GATE). */
+  dryRun?: boolean;
+}
+interface ScopeMigrationReport {
+  /** Which `SCOPE_TABLES` actually exist in this DB (CF lacks device_sync_state). */
+  tablesPresent: string[];
+  /** Whether the `shares` / `scope_meta` tables exist. */
+  hasShares: boolean;
+  hasScopeMeta: boolean;
+  /** Distinct candidate scopes seen across all sources. */
+  candidates: number;
+  /** Plaintext DID scopes that WILL be / WERE migrated (sorted). */
+  migrate: string[];
+  /** Non-DID scopes skipped: versioned / already-derived hash / bare / junk (sorted). */
+  skip: string[];
+  /** Count actually migrated (0 when dryRun). */
+  migrated: number;
+  /** Whether scope_meta was rebuilt (only when something migrated + table present). */
+  scopeMetaRebuilt: boolean;
+}
+/**
+ * Migrate (or, with `dryRun`, classify) all plaintext DID scopes in `db`.
+ *
+ * @param db   the D1 database (or a compatible mock) — the bound runtime D1
+ * @param key  the deployment HMAC secret bytes (from `decodeScopeHmacSecret`)
+ * @param opts `{ dryRun }` to classify without writing
+ */
+declare function migrateD1Scopes(db: D1Database, key: Uint8Array, opts?: ScopeMigrationOptions): Promise<ScopeMigrationReport>;
+/** Classify distinct scope strings into migrate (plaintext DID) vs skip. */
+declare function classifyScopes(scopes: string[]): {
+  migrate: string[];
+  skip: string[];
+};
+interface BuildD1MigrationSqlOptions {
+  /** Emit `UPDATE shares SET owner_did = …` (CF has a shares table). Default true. */
+  includeShares?: boolean;
+  /** Emit the scope_meta DELETE-stale + BACKFILL rebuild. Default true. */
+  includeScopeMeta?: boolean;
+}
+interface D1MigrationSql {
+  /** The `.sql` text to apply via `wrangler d1 execute --remote --file`. */
+  sql: string;
+  migrate: string[];
+  skip: string[];
+}
+/**
+ * Generate the migration `.sql` for a REMOTE CF D1 (README §4.5 离线脚本形态).
+ *
+ * The HMAC is computed HERE (D1 SQL can't); the operator dumps the distinct
+ * scopes with `wrangler d1 execute --remote --json` and applies the emitted file
+ * with `wrangler d1 execute --remote --file`. Only plaintext DID scopes are
+ * rewritten — versioned `schema:…` / already-derived / junk are left out, so a
+ * re-apply is idempotent (their `WHERE scope = '<old DID>'` matches nothing).
+ *
+ * Statement order matters: all scope UPDATEs first, then the scope_meta rebuild
+ * (DELETE stale plaintext rows + BACKFILL derived counts from the now-moved
+ * entries). `entries` / `changelog` / `prefix_watermark` are CF's standard
+ * scope-bearing tables (migrations 0100–0107); `device_sync_state` is absent.
+ */
+declare function buildD1MigrationSql(scopes: string[], key: Uint8Array, opts?: BuildD1MigrationSqlOptions): D1MigrationSql;
+//#endregion
+export { BuildD1MigrationSqlOptions, D1MigrationSql, ScopeMigrationOptions, ScopeMigrationReport, buildD1MigrationSql, classifyScopes, migrateD1Scopes };
+//# sourceMappingURL=scope-migration.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration.d.cts","names":[],"sources":["../src/scope-migration.ts"],"mappings":";UA2CiB,qBAAA;EAAA;EAEf,MAAA;AAAA;AAAA,UAGe,oBAAA;EAHT;EAKN,aAAA;EAFmC;EAInC,SAAA;EACA,YAAA;EAHA;EAKA,UAAA;EAFA;EAIA,OAAA;EAAA;EAEA,IAAA;EAEA;EAAA,QAAA;EAEgB;EAAhB,gBAAA;AAAA;;;;;;;;iBAuBoB,eAAA,CACpB,EAAA,EAAI,UAAA,EACJ,GAAA,EAAK,UAAA,EACL,IAAA,GAAM,qBAAA,GACL,OAAA,CAAQ,oBAAA;;iBAwEK,cAAA,CAAe,MAAA;EAAqB,OAAA;EAAmB,IAAA;AAAA;AAAA,UAStD,0BAAA;EAlFf;EAoFA,aAAA;EAnFS;EAqFT,gBAAA;AAAA;AAAA,UAGe,cAAA;EAhBa;EAkB5B,GAAA;EACA,OAAA;EACA,IAAA;AAAA;;;;AAXF;;;;;AAOA;;;;;;iBA6BgB,mBAAA,CACd,MAAA,YACA,GAAA,EAAK,UAAA,EACL,IAAA,GAAM,0BAAA,GACL,cAAA"}

package/dist/scope-migration.d.mts

@@ -0,0 +1,65 @@
+//#region src/scope-migration.d.ts
+interface ScopeMigrationOptions {
+  /** Classify only — collect + classify candidates, write nothing (STOP GATE). */
+  dryRun?: boolean;
+}
+interface ScopeMigrationReport {
+  /** Which `SCOPE_TABLES` actually exist in this DB (CF lacks device_sync_state). */
+  tablesPresent: string[];
+  /** Whether the `shares` / `scope_meta` tables exist. */
+  hasShares: boolean;
+  hasScopeMeta: boolean;
+  /** Distinct candidate scopes seen across all sources. */
+  candidates: number;
+  /** Plaintext DID scopes that WILL be / WERE migrated (sorted). */
+  migrate: string[];
+  /** Non-DID scopes skipped: versioned / already-derived hash / bare / junk (sorted). */
+  skip: string[];
+  /** Count actually migrated (0 when dryRun). */
+  migrated: number;
+  /** Whether scope_meta was rebuilt (only when something migrated + table present). */
+  scopeMetaRebuilt: boolean;
+}
+/**
+ * Migrate (or, with `dryRun`, classify) all plaintext DID scopes in `db`.
+ *
+ * @param db   the D1 database (or a compatible mock) — the bound runtime D1
+ * @param key  the deployment HMAC secret bytes (from `decodeScopeHmacSecret`)
+ * @param opts `{ dryRun }` to classify without writing
+ */
+declare function migrateD1Scopes(db: D1Database, key: Uint8Array, opts?: ScopeMigrationOptions): Promise<ScopeMigrationReport>;
+/** Classify distinct scope strings into migrate (plaintext DID) vs skip. */
+declare function classifyScopes(scopes: string[]): {
+  migrate: string[];
+  skip: string[];
+};
+interface BuildD1MigrationSqlOptions {
+  /** Emit `UPDATE shares SET owner_did = …` (CF has a shares table). Default true. */
+  includeShares?: boolean;
+  /** Emit the scope_meta DELETE-stale + BACKFILL rebuild. Default true. */
+  includeScopeMeta?: boolean;
+}
+interface D1MigrationSql {
+  /** The `.sql` text to apply via `wrangler d1 execute --remote --file`. */
+  sql: string;
+  migrate: string[];
+  skip: string[];
+}
+/**
+ * Generate the migration `.sql` for a REMOTE CF D1 (README §4.5 离线脚本形态).
+ *
+ * The HMAC is computed HERE (D1 SQL can't); the operator dumps the distinct
+ * scopes with `wrangler d1 execute --remote --json` and applies the emitted file
+ * with `wrangler d1 execute --remote --file`. Only plaintext DID scopes are
+ * rewritten — versioned `schema:…` / already-derived / junk are left out, so a
+ * re-apply is idempotent (their `WHERE scope = '<old DID>'` matches nothing).
+ *
+ * Statement order matters: all scope UPDATEs first, then the scope_meta rebuild
+ * (DELETE stale plaintext rows + BACKFILL derived counts from the now-moved
+ * entries). `entries` / `changelog` / `prefix_watermark` are CF's standard
+ * scope-bearing tables (migrations 0100–0107); `device_sync_state` is absent.
+ */
+declare function buildD1MigrationSql(scopes: string[], key: Uint8Array, opts?: BuildD1MigrationSqlOptions): D1MigrationSql;
+//#endregion
+export { BuildD1MigrationSqlOptions, D1MigrationSql, ScopeMigrationOptions, ScopeMigrationReport, buildD1MigrationSql, classifyScopes, migrateD1Scopes };
+//# sourceMappingURL=scope-migration.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope-migration.d.mts","names":[],"sources":["../src/scope-migration.ts"],"mappings":";UA2CiB,qBAAA;EAAA;EAEf,MAAA;AAAA;AAAA,UAGe,oBAAA;EAHT;EAKN,aAAA;EAFmC;EAInC,SAAA;EACA,YAAA;EAHA;EAKA,UAAA;EAFA;EAIA,OAAA;EAAA;EAEA,IAAA;EAEA;EAAA,QAAA;EAEgB;EAAhB,gBAAA;AAAA;;;;;;;;iBAuBoB,eAAA,CACpB,EAAA,EAAI,UAAA,EACJ,GAAA,EAAK,UAAA,EACL,IAAA,GAAM,qBAAA,GACL,OAAA,CAAQ,oBAAA;;iBAwEK,cAAA,CAAe,MAAA;EAAqB,OAAA;EAAmB,IAAA;AAAA;AAAA,UAStD,0BAAA;EAlFf;EAoFA,aAAA;EAnFS;EAqFT,gBAAA;AAAA;AAAA,UAGe,cAAA;EAhBa;EAkB5B,GAAA;EACA,OAAA;EACA,IAAA;AAAA;;;;AAXF;;;;;AAOA;;;;;;iBA6BgB,mBAAA,CACd,MAAA,YACA,GAAA,EAAK,UAAA,EACL,IAAA,GAAM,0BAAA,GACL,cAAA"}