feat(db,contracts): trash_item migration and file manager contract refinements

- 0024_trash: trash_item table + unique idempotency index on artifact(files_idem)
- files.ts: TrashItemRow, delete planId/planExpiresAt, organize group warnings,
  scrape returns refreshMetadata taskId
- registry tests list the new table/row schema

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/db/migrations/0024_trash.ts

@@ -0,0 +1,41 @@
+import type { Kysely } from "kysely";
+import { dropTables, entityTable, execDdl } from "../src/migration-helpers.ts";
+
+// W5-A 文件管理(docs/plan/06-file-manager-spec.md §2.3.3):
+// - trash_item:删除进回收站的记录(原根/原相对路径/回收站内路径/到期时间/关联资产快照);
+//   还原或清除后删行(历史留在 audit_event)。root_id 为文件管理的根 id(lib:<uuid> / dl:<uuid>:<n>)。
+// - artifact_files_idem_key:文件管理写操作的幂等键(artifact title='files_idem',content.key)唯一。
+
+// biome-ignore lint/suspicious/noExplicitAny: 迁移不依赖应用表类型
+export async function up(db: Kysely<any>): Promise<void> {
+  await execDdl(
+    db,
+    `
+${entityTable(
+  "trash_item",
+  `
+  root_id text not null,
+  library_root_id uuid references library_root (id) on delete set null,
+  root_host_path text not null,
+  original_path text not null,
+  trash_path text not null,
+  is_dir boolean not null default false,
+  size_bytes bigint not null default 0,
+  actor text,
+  deleted_at timestamptz not null default now(),
+  expires_at timestamptz not null,
+  asset_snapshot jsonb,
+  constraint trash_item_trash_path_key unique (trash_path)`,
+)}
+create index trash_item_expires_idx on trash_item (expires_at);
+create index trash_item_root_idx on trash_item (root_id, deleted_at desc);
+
+create unique index artifact_files_idem_key on artifact ((content->>'key')) where title = 'files_idem';
+`,
+  );
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: 同上
+export async function down(db: Kysely<any>): Promise<void> {
+  await execDdl(db, `drop index if exists artifact_files_idem_key;\n${dropTables(["trash_item"])}`);
+}

packages/db/src/types.ts

@@ -1276,6 +1276,23 @@ export interface TitleAliasTable {
   updated_at: GeneratedTimestamptz;
 }
 
+export interface TrashItemTable {
+  id: Generated<string>;
+  root_id: string;
+  library_root_id: string | null;
+  root_host_path: string;
+  original_path: string;
+  trash_path: string;
+  is_dir: Generated<boolean>;
+  size_bytes: Generated<number>;
+  actor: string | null;
+  deleted_at: GeneratedTimestamptz;
+  expires_at: Timestamptz;
+  asset_snapshot: Json | null;
+  created_at: GeneratedTimestamptz;
+  updated_at: GeneratedTimestamptz;
+}
+
 export interface DB {
   acquisition_plan: AcquisitionPlanTable;
   acquisition_slot: AcquisitionSlotTable;
@@ -1338,6 +1355,7 @@ export interface DB {
   tasks_op_ledger: TasksOpLedgerTable;
   tasks_run_meta: TasksRunMetaTable;
   title_alias: TitleAliasTable;
+  trash_item: TrashItemTable;
 }
 
 export type AcquisitionPlanRow = Selectable<AcquisitionPlanTable>;
@@ -1523,3 +1541,6 @@ export type TasksRunMetaUpdate = Updateable<TasksRunMetaTable>;
 export type TitleAliasRow = Selectable<TitleAliasTable>;
 export type NewTitleAlias = Insertable<TitleAliasTable>;
 export type TitleAliasUpdate = Updateable<TitleAliasTable>;
+export type TrashItemRow = Selectable<TrashItemTable>;
+export type NewTrashItem = Insertable<TrashItemTable>;
+export type TrashItemUpdate = Updateable<TrashItemTable>;

packages/db/test/schema.test.ts

@@ -88,6 +88,8 @@ const EXPECTED_TABLES = [
   "browser_session",
   "browser_tab",
   "browser_control_lease",
+  // W5-A 文件管理回收站(0024)
+  "trash_item",
 ].sort();
 
 /** 不走 entityTable() 的表:追加型/引擎自有表,没有 uuid id + created_at/updated_at 三件套 */