zigmini 1.0.0-beta.3 → 1.1.0-beta.1

package/src/attachments/store.ts

@@ -0,0 +1,698 @@
+import type { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import type { SecurityReceipt } from "../security-allow.ts";
+import type { StoredEvent } from "../store.ts";
+import {
+	AttachmentStoreError, type AttachmentAccepted, type AttachmentAdmission, type AttachmentCAS, type AttachmentCurrent,
+	type AttachmentEncoding, type AttachmentFormat, type AttachmentGate, type AttachmentJob, type AttachmentManifest,
+	type AttachmentMetadata, type AttachmentPreparation, type AttachmentScope, type AttachmentSelection,
+	type AttachmentState, type SelectedAttachmentExport,
+} from "./types.ts";
+
+const MAX_BYTES = 10 * 1024 * 1024;
+const SHA = /^[a-f0-9]{64}$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+const positive = (n: number) => Number.isSafeInteger(n) && n > 0;
+function fail(code: ConstructorParameters<typeof AttachmentStoreError>[0], status = 409): never { throw new AttachmentStoreError(code, status); }
+const object = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+function canonical(value: unknown): string {
+	if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (object(value) && Object.getPrototypeOf(value) === Object.prototype) {
+		return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+	}
+	return fail("invalid_attachment_input", 400);
+}
+const digest = (value: unknown): string => createHash("sha256").update(canonical(value)).digest("hex");
+export function attachmentRequestDigest(admission: Omit<AttachmentAdmission, "requestDigest">, data: Readonly<Record<string, unknown>>): string {
+	return digest({ admission, data });
+}
+function validateScope(s: AttachmentScope): void {
+	if (!s || typeof s.ownerPrincipal !== "string" || !s.ownerPrincipal || !UUID.test(s.draftId) ||
+		typeof s.convId !== "string" || !s.convId || !positive(s.convEpoch) || !s.recipient ||
+		!["main", "agent"].includes(s.recipient.kind) || typeof s.recipient.id !== "string" || !s.recipient.id ||
+		!positive(s.recipient.epoch)) fail("invalid_attachment_input", 400);
+}
+interface Row {
+	readonly id: string; readonly owner_principal: string; readonly draft_id: string; readonly conv_id: string;
+	readonly conv_epoch: number; readonly recipient_kind: "main" | "agent"; readonly recipient_id: string; readonly recipient_epoch: number;
+	readonly original_name: string; readonly format: AttachmentFormat; readonly bytes: number; readonly sha256: string | null;
+	readonly state: AttachmentState; readonly revision: number; readonly job_generation: string;
+	readonly preparation_revision: number; readonly prepared_manifest_json: string | null; readonly error_code: string | null;
+	readonly preparation_encoding: AttachmentEncoding | null;
+}
+interface Grant {
+	readonly id: string; readonly attachment_id: string; readonly conv_id: string; readonly recipient_id: string;
+	readonly message_seq: number; readonly revision: number; readonly revoked_at: string | null;
+	readonly conv_epoch: number; readonly recipient_epoch: number; readonly recipient_authority_epoch: number | null;
+}
+const rowScope = (r: Row): AttachmentScope => ({ ownerPrincipal: r.owner_principal, draftId: r.draft_id,
+	convId: r.conv_id, convEpoch: r.conv_epoch, recipient: { kind: r.recipient_kind, id: r.recipient_id, epoch: r.recipient_epoch } });
+const job = (r: Row): AttachmentJob => ({ attachmentId: r.id, state: r.state, revision: r.revision,
+	jobGeneration: r.job_generation, preparationRevision: r.preparation_revision });
+const preparation = (r: Row): AttachmentPreparation => {
+	if (!r.prepared_manifest_json) return fail("attachment_not_ready");
+	return JSON.parse(r.prepared_manifest_json);
+};
+
+/** Owns no connection. The parent Store installs this additive schema and supplies its existing acceptance. */
+export class AttachmentStore {
+	constructor(private readonly db: Database, private readonly accept: (conv: string, data: unknown, receipt?: (ref: SecurityReceipt) => void) => StoredEvent) {}
+
+	migrate(): void {
+		this.db.transaction(() => this.db.exec(`
+			CREATE TABLE IF NOT EXISTS attachments (
+				id TEXT PRIMARY KEY, owner_principal TEXT NOT NULL, draft_id TEXT NOT NULL,
+				conv_id TEXT NOT NULL REFERENCES conversations(id), recipient_kind TEXT NOT NULL CHECK(recipient_kind IN ('main','agent')),
+				recipient_id TEXT NOT NULL, conv_epoch INTEGER NOT NULL CHECK(conv_epoch>0), recipient_epoch INTEGER NOT NULL CHECK(recipient_epoch>0),
+				original_name TEXT NOT NULL, format TEXT NOT NULL CHECK(format IN ('html','md','txt','pdf')),
+				bytes INTEGER NOT NULL CHECK(bytes>0 AND bytes<=10485760), sha256 TEXT,
+				state TEXT NOT NULL CHECK(state IN ('snapshotting','sealed','preparing','ready','bound','discarded','error','revoked')),
+				revision INTEGER NOT NULL CHECK(revision>0), source_identity_json TEXT NOT NULL, created_at TEXT NOT NULL,
+				sealed_at TEXT, error_code TEXT, preparation_revision INTEGER NOT NULL DEFAULT 0,
+				prepared_manifest_json TEXT, job_generation TEXT NOT NULL,
+				preparation_encoding TEXT CHECK(preparation_encoding IN ('utf-8','utf-16le','utf-16be','euc-kr','cp949')),
+				CHECK(sha256 IS NULL OR (length(sha256)=64 AND sha256 NOT GLOB '*[^a-f0-9]*'))
+			);
+			CREATE INDEX IF NOT EXISTS attachment_staging ON attachments(owner_principal,state);
+			CREATE TABLE IF NOT EXISTS attachment_selectors (hash TEXT PRIMARY KEY);
+			CREATE TABLE IF NOT EXISTS attachment_operations (
+				principal TEXT NOT NULL, draft_id TEXT NOT NULL, operation_id TEXT NOT NULL, request_digest TEXT NOT NULL,
+				attachment_id TEXT NOT NULL REFERENCES attachments(id), receipt_json TEXT NOT NULL,
+				PRIMARY KEY(principal,draft_id,operation_id)
+			);
+			CREATE TABLE IF NOT EXISTS attachment_grants (
+				id TEXT PRIMARY KEY, attachment_id TEXT NOT NULL REFERENCES attachments(id), conv_id TEXT NOT NULL,
+				recipient_id TEXT NOT NULL, message_seq INTEGER NOT NULL REFERENCES events(seq), revision INTEGER NOT NULL CHECK(revision>0),
+				revoked_at TEXT, conv_epoch INTEGER NOT NULL, recipient_epoch INTEGER NOT NULL, recipient_authority_epoch INTEGER,
+				UNIQUE(attachment_id,message_seq)
+			);
+			CREATE TABLE IF NOT EXISTS attachment_submissions (
+				conv_id TEXT NOT NULL, submission_id TEXT NOT NULL, request_digest TEXT NOT NULL,
+				message_seq INTEGER NOT NULL REFERENCES events(seq), receipt_json TEXT NOT NULL,
+				PRIMARY KEY(conv_id,submission_id)
+			);
+			CREATE TABLE IF NOT EXISTS attachment_tombstones (
+				id TEXT PRIMARY KEY REFERENCES attachments(id), digest TEXT, submission_keys_json TEXT NOT NULL,
+				reason TEXT NOT NULL, created_at TEXT NOT NULL
+			);
+			CREATE TABLE IF NOT EXISTS attachment_recipient_epochs (recipient_id TEXT PRIMARY KEY, epoch INTEGER NOT NULL CHECK(epoch>1));
+			CREATE TABLE IF NOT EXISTS attachment_read_leases (
+				id TEXT PRIMARY KEY, attachment_id TEXT NOT NULL REFERENCES attachments(id), receipt_json TEXT NOT NULL
+			);
+			CREATE TRIGGER IF NOT EXISTS attachment_immutable_original
+			BEFORE UPDATE ON attachments WHEN OLD.sha256 IS NOT NULL AND (
+				NEW.sha256 IS NOT OLD.sha256 OR NEW.bytes != OLD.bytes OR NEW.original_name != OLD.original_name OR
+				NEW.format != OLD.format OR NEW.source_identity_json != OLD.source_identity_json)
+			BEGIN SELECT RAISE(ABORT,'attachment_immutable_original'); END;
+			CREATE TRIGGER IF NOT EXISTS attachment_immutable_scope
+			BEFORE UPDATE ON attachments WHEN NEW.owner_principal != OLD.owner_principal OR NEW.draft_id != OLD.draft_id OR
+				NEW.conv_id != OLD.conv_id OR NEW.conv_epoch != OLD.conv_epoch OR NEW.recipient_kind != OLD.recipient_kind OR
+				NEW.recipient_id != OLD.recipient_id OR NEW.recipient_epoch != OLD.recipient_epoch
+			BEGIN SELECT RAISE(ABORT,'attachment_immutable_scope'); END;
+			CREATE TRIGGER IF NOT EXISTS attachment_immutable_preparation
+			BEFORE UPDATE ON attachments WHEN EXISTS (SELECT 1 FROM attachment_grants WHERE attachment_id=OLD.id) AND
+				(NEW.preparation_revision != OLD.preparation_revision OR NEW.prepared_manifest_json IS NOT OLD.prepared_manifest_json OR
+					NEW.preparation_encoding IS NOT OLD.preparation_encoding)
+			BEGIN SELECT RAISE(ABORT,'attachment_immutable_preparation'); END;
+		`)).immediate();
+		const columns = this.db.query<{ name: string }, []>("PRAGMA table_info(attachment_tombstones)").all().map(column => column.name);
+		if (!columns.includes("trashed_at")) this.db.exec("ALTER TABLE attachment_tombstones ADD COLUMN trashed_at TEXT");
+	}
+
+	private row(id: string): Row {
+		if (!UUID.test(id)) return fail("invalid_attachment_input", 400);
+		const row = this.db.query<Row, [string]>(`SELECT id,owner_principal,draft_id,conv_id,conv_epoch,recipient_kind,recipient_id,
+			recipient_epoch,original_name,format,bytes,sha256,state,revision,job_generation,preparation_revision,
+			prepared_manifest_json,error_code,preparation_encoding FROM attachments WHERE id=?`).get(id);
+		if (!row) return fail("attachment_not_found", 404);
+		return row;
+	}
+	private live(id: string): void {
+		if (this.db.query("SELECT id FROM attachment_tombstones WHERE id=?").get(id)) fail("attachment_tombstoned", 410);
+	}
+	private current(scope: AttachmentScope, gate: AttachmentGate, owner = true): AttachmentCurrent {
+		validateScope(scope);
+		const conv = this.db.query<{ agent_id: string | null }, [string]>("SELECT agent_id FROM conversations WHERE id=?").get(scope.convId);
+		if (!conv || (scope.recipient.kind === "agent" ? conv.agent_id !== scope.recipient.id : conv.agent_id !== null)) return fail("attachment_scope_mismatch");
+		const current = gate.current(this.db, scope);
+		if (!current || !positive(current.convEpoch) || !current.recipient || !positive(current.recipient.epoch) ||
+			typeof current.ownerActive !== "boolean") return fail("attachment_provider_invalid", 503);
+		if (owner && !current.ownerActive) fail("attachment_owner_inactive", 403);
+		if (current.convEpoch !== scope.convEpoch || current.recipient.id !== scope.recipient.id ||
+			current.recipient.kind !== scope.recipient.kind || current.recipient.epoch !== scope.recipient.epoch) fail("attachment_scope_mismatch");
+		return current;
+	}
+	private modelAccess(current: AttachmentCurrent, epoch?: number | null): void {
+		if (current.authority) {
+			if (!positive(current.authority.epoch) || !positive(current.authority.policyRevision) ||
+				!["open", "blocked"].includes(current.authority.accessState)) fail("attachment_provider_invalid", 503);
+			if (current.authority.accessState === "blocked") fail("agent_access_blocked", 403);
+		}
+		if (epoch !== undefined && epoch !== (current.authority?.epoch ?? null)) fail("authority_epoch_mismatch");
+	}
+	private owns(r: Row, scope: AttachmentScope, draft = true): void {
+		if (r.owner_principal !== scope.ownerPrincipal || (draft && r.draft_id !== scope.draftId) ||
+			r.conv_id !== scope.convId || r.conv_epoch !== scope.convEpoch || r.recipient_kind !== scope.recipient.kind ||
+			r.recipient_id !== scope.recipient.id || r.recipient_epoch !== scope.recipient.epoch) fail("attachment_scope_mismatch");
+	}
+	private original(r: Row, gate: AttachmentGate): void {
+		const original = gate.original(this.db, r.id);
+		if (!original || original.bytes !== r.bytes || original.sha256 !== r.sha256) fail("attachment_original_unavailable", 410);
+	}
+	private cas(r: Row, cas: AttachmentCAS, states: readonly AttachmentState[]): void {
+		if (!positive(cas.expectedRevision) || !UUID.test(cas.jobGeneration)) fail("invalid_attachment_input", 400);
+		this.live(r.id);
+		if (r.revision !== cas.expectedRevision || r.job_generation !== cas.jobGeneration || !states.includes(r.state)) fail("attachment_cas_conflict");
+	}
+	private operation(scope: AttachmentScope, operationId: string, requestDigest: string): AttachmentJob | null {
+		const old = this.db.query<{ request_digest: string; receipt_json: string }, [string, string, string]>(
+			"SELECT request_digest,receipt_json FROM attachment_operations WHERE principal=? AND draft_id=? AND operation_id=?")
+			.get(scope.ownerPrincipal, scope.draftId, operationId);
+		if (!old) return null;
+		if (old.request_digest !== requestDigest) return fail("operation_conflict");
+		return JSON.parse(old.receipt_json);
+	}
+	private saveOperation(scope: AttachmentScope, operationId: string, requestDigest: string, result: AttachmentJob): AttachmentJob {
+		this.db.query("INSERT INTO attachment_operations VALUES (?,?,?,?,?,?)").run(scope.ownerPrincipal, scope.draftId,
+			operationId, requestDigest, result.attachmentId, JSON.stringify(result));
+		return result;
+	}
+	select(input: AttachmentSelection, gate: AttachmentGate): AttachmentJob {
+		validateScope(input.scope);
+		if (!UUID.test(input.operationId) || !UUID.test(input.jobGeneration) || typeof input.name !== "string" || !input.name ||
+			!["html", "md", "txt", "pdf"].includes(input.format) || !positive(input.bytes) || input.bytes > MAX_BYTES ||
+			!object(input.entryIdentity) || !object(input.sourceIdentity)) fail("invalid_attachment_input", 400);
+		const requestDigest = digest({ kind: "select", scope: input.scope, entryIdentity: input.entryIdentity,
+			sourceIdentity: input.sourceIdentity, name: input.name, format: input.format, bytes: input.bytes });
+		return this.db.transaction(() => {
+			this.current(input.scope, gate);
+			const old = this.operation(input.scope, input.operationId, requestDigest);
+			if (old) return old;
+			const quota = this.db.query<{ count: number; bytes: number }, [string]>(
+				"SELECT count(*) count,coalesce(sum(bytes),0) bytes FROM attachments WHERE owner_principal=? AND state NOT IN ('bound','revoked','discarded') AND id NOT IN (SELECT id FROM attachment_tombstones WHERE trashed_at IS NOT NULL)")
+				.get(input.scope.ownerPrincipal);
+			if (!quota || quota.count >= 16 || quota.bytes + input.bytes > 64 * 1024 * 1024) fail("staging_quota_exceeded", 429);
+			const id = crypto.randomUUID(), s = input.scope;
+			this.db.query(`INSERT INTO attachments (id,owner_principal,draft_id,conv_id,recipient_kind,recipient_id,conv_epoch,recipient_epoch,
+				original_name,format,bytes,state,revision,source_identity_json,created_at,job_generation) VALUES (?,?,?,?,?,?,?,?,?,?,?,'snapshotting',1,?,?,?)`)
+				.run(id, s.ownerPrincipal, s.draftId, s.convId, s.recipient.kind, s.recipient.id, s.convEpoch, s.recipient.epoch,
+					input.name, input.format, input.bytes, canonical(input.sourceIdentity), new Date().toISOString(), input.jobGeneration);
+			return this.saveOperation(s, input.operationId, requestDigest, job(this.row(id)));
+		}).immediate();
+	}
+	seal(id: string, cas: AttachmentCAS, original: { readonly bytes: number; readonly sha256: string }, gate: AttachmentGate): AttachmentJob {
+		if (!SHA.test(original.sha256) || !positive(original.bytes) || original.bytes > MAX_BYTES) fail("invalid_attachment_input", 400);
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.cas(r, cas, ["snapshotting"]);
+			if (r.bytes !== original.bytes) fail("attachment_manifest_conflict");
+			this.original({ ...r, sha256: original.sha256 }, gate);
+			this.db.query("UPDATE attachments SET sha256=?,state='sealed',revision=revision+1,sealed_at=? WHERE id=?")
+				.run(original.sha256, new Date().toISOString(), id);
+			return job(this.row(id));
+		}).immediate();
+	}
+	prepare(scope: AttachmentScope, id: string,
+		input: { readonly expectedRevision: number; readonly operationId: string; readonly jobGeneration: string; readonly encoding?: AttachmentEncoding },
+		gate: AttachmentGate): AttachmentJob {
+		if (!UUID.test(input.operationId) || !UUID.test(input.jobGeneration) || !positive(input.expectedRevision) ||
+			(input.encoding !== undefined && !["utf-8", "utf-16le", "utf-16be", "euc-kr", "cp949"].includes(input.encoding))) fail("invalid_attachment_input", 400);
+		const requestDigest = digest({ kind: "prepare", id, scope, expectedRevision: input.expectedRevision, encoding: input.encoding ?? null });
+		return this.db.transaction(() => {
+			this.current(scope, gate);
+			const r = this.row(id);
+			this.owns(r, scope);
+			const old = this.operation(scope, input.operationId, requestDigest);
+			if (old) return old;
+			this.live(id);
+			if (this.db.query("SELECT id FROM attachment_grants WHERE attachment_id=?").get(id)) fail("attachment_already_bound");
+			if (r.revision !== input.expectedRevision || !["sealed", "preparing", "ready", "error"].includes(r.state) || !r.sha256) fail("attachment_cas_conflict");
+			this.original(r, gate);
+			this.db.query(`UPDATE attachments SET state='preparing',revision=revision+1,preparation_revision=preparation_revision+1,
+				prepared_manifest_json=NULL,error_code=NULL,job_generation=?,preparation_encoding=? WHERE id=?`)
+				.run(input.jobGeneration, input.encoding ?? null, id);
+			return this.saveOperation(scope, input.operationId, requestDigest, job(this.row(id)));
+		}).immediate();
+	}
+	/** A private worker descriptor, not owner status or model metadata. Recovery keeps the selected decoding option. */
+	preparationWork(id: string, cas: AttachmentCAS) {
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.cas(r, cas, ["sealed", "preparing"]);
+			if (!r.sha256) fail("attachment_not_ready");
+			return { ...job(r), originalSha256: r.sha256, format: r.format, bytes: r.bytes, encoding: r.preparation_encoding };
+		}).immediate();
+	}
+	publish(id: string, cas: AttachmentCAS, manifest: AttachmentPreparation): AttachmentJob {
+		if (!SHA.test(manifest.originalSha256) || !SHA.test(manifest.representationSha256) || !SHA.test(manifest.inspectedTextSha256) ||
+			!positive(manifest.preparationRevision) || !["text", "native-document", "pages", "ocr"].includes(manifest.readMode) ||
+			(manifest.pageCount !== undefined && (!positive(manifest.pageCount) || manifest.pageCount > 300))) fail("invalid_attachment_input", 400);
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.cas(r, cas, ["preparing"]);
+			if (r.preparation_revision !== manifest.preparationRevision || r.sha256 !== manifest.originalSha256) fail("attachment_manifest_conflict");
+			this.db.query("UPDATE attachments SET state='ready',revision=revision+1,prepared_manifest_json=?,error_code=NULL WHERE id=?")
+				.run(canonical(manifest), id);
+			return job(this.row(id));
+		}).immediate();
+	}
+	failJob(id: string, cas: AttachmentCAS, errorCode: string): AttachmentJob {
+		if (!/^[a-z][a-z0-9_]{0,79}$/.test(errorCode)) fail("invalid_attachment_input", 400);
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.cas(r, cas, ["snapshotting", "sealed", "preparing"]);
+			this.db.query("UPDATE attachments SET state='error',revision=revision+1,error_code=? WHERE id=?").run(errorCode, id);
+			return job(this.row(id));
+		}).immediate();
+	}
+	discard(scope: AttachmentScope, id: string, expectedRevision: number, gate: AttachmentGate): AttachmentJob {
+		return this.db.transaction(() => {
+			this.current(scope, gate);
+			const r = this.row(id);
+			this.owns(r, scope);
+			this.live(id);
+			if (this.db.query("SELECT id FROM attachment_grants WHERE attachment_id=?").get(id)) fail("attachment_already_bound");
+			if (r.revision !== expectedRevision || r.state === "discarded") fail("attachment_cas_conflict");
+			this.db.query("UPDATE attachments SET state='discarded',revision=revision+1,job_generation=? WHERE id=?").run(crypto.randomUUID(), id);
+			return job(this.row(id));
+		}).immediate();
+	}
+	status(scope: AttachmentScope, id: string, gate: AttachmentGate) {
+		return this.db.transaction(() => {
+			this.current(scope, gate);
+			const r = this.row(id);
+			this.owns(r, scope, !["bound", "revoked"].includes(r.state));
+			const manifest = r.prepared_manifest_json ? preparation(r) : null;
+			return { id: r.id, name: r.original_name, format: r.format, bytes: r.bytes, sha256: r.sha256, state: r.state, revision: r.revision,
+				preparation: { revision: r.preparation_revision, state: manifest ? "ready" : r.error_code === "encoding_required" ? "encoding_required" : r.state === "error" ? "error" : "pending" },
+				readMode: manifest?.readMode ?? null, ...(r.error_code ? { error: r.error_code } : {}) };
+		}).immediate();
+	}
+	private grant(id: string): Grant {
+		const grant = this.db.query<Grant, [string]>("SELECT * FROM attachment_grants WHERE id=?").get(id);
+		if (!grant) return fail("attachment_reference_unavailable", 410);
+		return grant;
+	}
+	/** A grant with no row is treated as revoked, so a client never shows it as active. */
+	private grantRevoked(grantId: string): boolean {
+		const row = this.db.query<{ revoked_at: string | null }, [string]>("SELECT revoked_at FROM attachment_grants WHERE id=?").get(grantId);
+		return !row || row.revoked_at !== null;
+	}
+	/** A copy of a stored message for clients, with each attachment's own grant state. The stored message is not changed. */
+	withGrantState(data: unknown): unknown {
+		if (!object(data)) return data;
+		const mark = (items: unknown) => Array.isArray(items)
+			? items.map(item => object(item) && typeof item.grantId === "string" ? { ...item, grantRevoked: this.grantRevoked(item.grantId) } : item) : items;
+		return { ...data,
+			...("attachments" in data ? { attachments: mark(data.attachments) } : {}),
+			...(Array.isArray(data.references) ? { references: data.references.map(reference => object(reference) && "attachments" in reference ? { ...reference, attachments: mark(reference.attachments) } : reference) } : {}) };
+	}
+	revokedGrantIds(attachmentId: string): string[] {
+		return this.db.query<{ id: string }, [string]>("SELECT id FROM attachment_grants WHERE attachment_id=? AND revoked_at IS NOT NULL ORDER BY message_seq").all(attachmentId).map(row => row.id);
+	}
+	private metadata(r: Row, grantId: string): AttachmentMetadata {
+		const p = preparation(r);
+		if (!r.sha256) return fail("attachment_not_ready");
+		return { id: r.id, grantId, name: r.original_name, format: r.format, bytes: r.bytes, sha256: r.sha256, readMode: p.readMode,
+			...(p.pageCount !== undefined ? { pageCount: p.pageCount } : {}) };
+	}
+	private references(scope: AttachmentScope, data: Readonly<Record<string, unknown>>, gate: AttachmentGate): Set<string> {
+		const ids = new Set<string>();
+		if (data.references === undefined) return ids;
+		if (!Array.isArray(data.references) || data.references.length > 4) return fail("invalid_attachment_input", 400);
+		for (const reference of data.references) {
+			if (!object(reference) || typeof reference.seq !== "number" || !positive(reference.seq)) fail("invalid_attachment_input", 400);
+			const event = this.db.query<{ conv: string; type: string; data: string }, [number]>("SELECT conv,type,data FROM events WHERE seq=?").get(reference.seq);
+			if (!event || event.conv !== scope.convId || !["message.user", "message.final"].includes(event.type)) fail("attachment_reference_unavailable", 410);
+			const source: unknown = JSON.parse(event.data);
+			if (!object(source)) fail("attachment_reference_unavailable", 410);
+			if (source.attachments === undefined) continue;
+			if (!Array.isArray(source.attachments)) fail("attachment_reference_unavailable", 410);
+			for (const item of source.attachments) {
+				if (!object(item) || typeof item.id !== "string" || typeof item.grantId !== "string") fail("attachment_reference_unavailable", 410);
+				const grant = this.grant(item.grantId), row = this.row(item.id);
+				if (grant.message_seq !== reference.seq || grant.attachment_id !== row.id || grant.revoked_at !== null ||
+					grant.conv_id !== scope.convId) fail("attachment_reference_unavailable", 410);
+				this.owns(row, scope, false);
+				this.modelAccess(this.current(scope, gate), grant.recipient_authority_epoch);
+				this.live(row.id);
+				this.original(row, gate);
+				ids.add(row.id);
+			}
+		}
+		return ids;
+	}
+	selectorKnown(hash: string): boolean { return this.db.query("SELECT hash FROM attachment_selectors WHERE hash=?").get(hash) !== null; }
+	/** Keeps the newest browser contexts only, so an endless stream of new sockets cannot grow the table. */
+	registerSelector(hash: string): void {
+		this.db.transaction(() => {
+			this.db.query("INSERT OR IGNORE INTO attachment_selectors (hash) VALUES (?)").run(hash);
+			this.db.query("DELETE FROM attachment_selectors WHERE rowid NOT IN (SELECT rowid FROM attachment_selectors ORDER BY rowid DESC LIMIT 256)").run();
+		}).immediate();
+	}
+	/** Ledger digest of the OCR text that passed inspection; the derived file alone proves nothing. */
+	lateOcrDigest(id: string, revision: number): string | null {
+		return this.db.query<{ request_digest: string }, [string]>("SELECT request_digest FROM attachment_operations WHERE principal='late-ocr' AND draft_id='late-ocr' AND operation_id=?").get(`${id}:${revision}`)?.request_digest ?? null;
+	}
+	recordLateOcr(id: string, revision: number, digest: string): void {
+		this.db.query("INSERT OR REPLACE INTO attachment_operations VALUES ('late-ocr','late-ocr',?,?,?,'{}')").run(`${id}:${revision}`, digest, id);
+	}
+	/** Owner lookup that hides another principal's attachment behind the same not-found answer. */
+	ownedScope(id: string, principal: string): AttachmentScope {
+		const r = this.db.query<Row, [string]>("SELECT * FROM attachments WHERE id=?").get(id);
+		if (!r || r.owner_principal !== principal) return fail("attachment_not_found", 404);
+		return rowScope(r);
+	}
+	/** Exact current manifest of one owned attachment, for the admission planner. */
+	manifest(id: string, principal: string): { readonly scope: AttachmentScope; readonly manifest: AttachmentManifest; readonly preparation: AttachmentPreparation; readonly name: string } {
+		const scope = this.ownedScope(id, principal), r = this.row(id);
+		if (r.state === "revoked") fail("attachment_revoked", 410);
+		if ((r.state !== "ready" && r.state !== "bound") || !r.sha256) fail("attachment_not_ready");
+		const p = preparation(r);
+		return { scope, preparation: p, name: r.original_name, manifest: { attachmentId: id, expectedRevision: r.revision,
+			preparationRevision: r.preparation_revision, originalSha256: r.sha256, representationSha256: p.representationSha256 } };
+	}
+	preparationOf(id: string): AttachmentPreparation { return preparation(this.row(id)); }
+	info(id: string): { readonly format: AttachmentFormat; readonly name: string; readonly state: AttachmentState; readonly sha256: string | null; readonly bytes: number; readonly draftId: string } {
+		const r = this.row(id);
+		return { format: r.format, name: r.original_name, state: r.state, sha256: r.sha256, bytes: r.bytes, draftId: r.draft_id };
+	}
+	/** A selection or sealed record whose worker died with the previous gateway process. */
+	unsettled(): readonly { readonly id: string; readonly revision: number }[] {
+		return this.db.query<{ id: string; revision: number }, []>("SELECT id,revision FROM attachments WHERE state IN ('snapshotting','sealed','preparing')").all();
+	}
+	/** The stable retry digest covers client intent, not row revisions that binding itself advances. */
+	retryReceipt(convId: string, submissionId: string, stableDigest: string): AttachmentAccepted | null {
+		const old = this.db.query<{ request_digest: string }, [string, string]>(
+			"SELECT request_digest FROM attachment_operations WHERE principal=? AND draft_id='submission' AND operation_id=?")
+			.get(`submission:${convId}`, submissionId);
+		if (!old) return null;
+		if (old.request_digest !== stableDigest) return fail("submission_conflict");
+		const row = this.db.query<{ receipt_json: string }, [string, string]>(
+			"SELECT receipt_json FROM attachment_submissions WHERE conv_id=? AND submission_id=?").get(convId, submissionId);
+		if (!row) return fail("submission_conflict");
+		return JSON.parse(row.receipt_json);
+	}
+	/** Message, grants, submission digest, pending dispatch and retry digest commit together or not at all. */
+	admitOnce(admission: AttachmentAdmission, data: Readonly<Record<string, unknown>>, gate: AttachmentGate, stableDigest: string,
+		receipt?: (ref: SecurityReceipt) => void): AttachmentAccepted {
+		return this.db.transaction(() => {
+			const accepted = this.admit(admission, data, gate, receipt);
+			this.db.query("INSERT INTO attachment_operations VALUES (?,?,?,?,?,?)").run(`submission:${admission.convId}`, "submission",
+				admission.submissionId, stableDigest, admission.attachments[0]?.attachmentId ?? "", "{}");
+			return accepted;
+		}).immediate();
+	}
+	/** The newest active grant held by exactly this conversation and recipient. */
+	activeGrant(attachmentId: string, convId: string, recipient: { readonly kind: "main" | "agent"; readonly id: string }, gate: AttachmentGate): SelectedAttachmentExport {
+		return this.db.transaction(() => {
+			const r = this.db.query<Row, [string]>("SELECT * FROM attachments WHERE id=?").get(attachmentId);
+			if (!r) return fail("attachment_revoked", 410);
+			const grant = this.db.query<Grant, [string, string, string]>(
+				"SELECT * FROM attachment_grants WHERE attachment_id=? AND conv_id=? AND recipient_id=? AND revoked_at IS NULL ORDER BY message_seq DESC LIMIT 1")
+				.get(attachmentId, convId, recipient.id);
+			if (!grant || !r.sha256 || r.recipient_kind !== recipient.kind) return fail("attachment_revoked", 410);
+			const receipt: SelectedAttachmentExport = { attachmentId, sourceGrantId: grant.id, sourceGrantRevision: grant.revision, originMessageSeq: grant.message_seq,
+				sourceConvId: r.conv_id, sourceRecipientId: r.recipient_id, sourceConvEpoch: r.conv_epoch, sourceRecipientEpoch: r.recipient_epoch,
+				originalSha256: r.sha256, bytes: r.bytes, format: r.format, name: r.original_name };
+			this.assertSelectedExportEligible(this.db, receipt, gate);
+			return receipt;
+		}).immediate();
+	}
+	/** The exact grant a stored reference names; a newer grant on the same file never stands in for it. */
+	grantReceipt(grantId: string, attachmentId: string, convId: string, recipient: { readonly kind: "main" | "agent"; readonly id: string }, gate: AttachmentGate): SelectedAttachmentExport {
+		return this.db.transaction(() => {
+			const grant = this.grant(grantId), r = this.row(attachmentId);
+			if (grant.attachment_id !== attachmentId || grant.conv_id !== convId || grant.recipient_id !== recipient.id || r.recipient_kind !== recipient.kind || !r.sha256) return fail("attachment_reference_unavailable", 410);
+			if (grant.revoked_at !== null) return fail("attachment_revoked", 410);
+			const receipt: SelectedAttachmentExport = { attachmentId, sourceGrantId: grant.id, sourceGrantRevision: grant.revision, originMessageSeq: grant.message_seq,
+				sourceConvId: r.conv_id, sourceRecipientId: r.recipient_id, sourceConvEpoch: r.conv_epoch, sourceRecipientEpoch: r.recipient_epoch,
+				originalSha256: r.sha256, bytes: r.bytes, format: r.format, name: r.original_name };
+			this.assertSelectedExportEligible(this.db, receipt, gate);
+			return receipt;
+		}).immediate();
+	}
+	/** Idempotent 292-facing export ledger: same key and same canonical request keep one receipt. */
+	recordExport(key: string, requestDigest: string, attachmentId: string, receipt: SelectedAttachmentExport): SelectedAttachmentExport {
+		return this.db.transaction(() => {
+			const old = this.db.query<{ request_digest: string; receipt_json: string }, [string]>(
+				"SELECT request_digest,receipt_json FROM attachment_operations WHERE principal='export' AND draft_id='export' AND operation_id=?").get(key);
+			if (old) {
+				if (old.request_digest !== requestDigest) return fail("operation_conflict");
+				return JSON.parse(old.receipt_json);
+			}
+			this.db.query("INSERT INTO attachment_operations VALUES ('export','export',?,?,?,?)").run(key, requestDigest, attachmentId, JSON.stringify(receipt));
+			return receipt;
+		}).immediate();
+	}
+	admit(admission: AttachmentAdmission, data: Readonly<Record<string, unknown>>, gate: AttachmentGate, receipt?: (ref: SecurityReceipt) => void): AttachmentAccepted {
+		validateScope(admission);
+		if (!UUID.test(admission.submissionId) || !SHA.test(admission.requestDigest) || !SHA.test(admission.inspectedTextSha256) ||
+			typeof admission.text !== "string" || !object(data) || data.text !== admission.text || !Array.isArray(admission.attachments) ||
+			admission.attachments.length === 0) fail("invalid_attachment_input", 400);
+		if (Object.keys(admission).some(key => !["convId", "draftId", "ownerPrincipal", "convEpoch", "recipient", "submissionId",
+			"requestDigest", "inspectedTextSha256", "text", "attachments"].includes(key)) ||
+			Object.keys(admission.recipient).some(key => !["kind", "id", "epoch"].includes(key))) fail("invalid_attachment_input", 400);
+		if (admission.attachments.length > 4) fail("too_many_attachments");
+		const { requestDigest, ...body } = admission;
+		if (attachmentRequestDigest(body, data) !== requestDigest) fail("request_digest_mismatch");
+		for (const m of admission.attachments) {
+			if (!m || !UUID.test(m.attachmentId) || !positive(m.expectedRevision) || !positive(m.preparationRevision) ||
+				!SHA.test(m.originalSha256) || !SHA.test(m.representationSha256)) fail("invalid_attachment_input", 400);
+			if (Object.keys(m).some(key => !["attachmentId", "expectedRevision", "preparationRevision", "originalSha256",
+				"representationSha256"].includes(key))) fail("invalid_attachment_input", 400);
+		}
+		if (new Set(admission.attachments.map(a => a.attachmentId)).size !== admission.attachments.length) fail("invalid_attachment_input", 400);
+		const direct = new Set<string>();
+		if (data.attachments !== undefined) {
+			if (!Array.isArray(data.attachments)) fail("invalid_attachment_input", 400);
+			for (const id of data.attachments) {
+				if (typeof id !== "string" || !UUID.test(id) || direct.has(id)) fail("invalid_attachment_input", 400);
+				if (!admission.attachments.some(m => m.attachmentId === id)) fail("attachment_manifest_conflict");
+				direct.add(id);
+			}
+		}
+		return this.db.transaction(() => {
+			const current = this.current(admission, gate);
+			const old = this.db.query<{ request_digest: string; receipt_json: string }, [string, string]>(
+				"SELECT request_digest,receipt_json FROM attachment_submissions WHERE conv_id=? AND submission_id=?").get(admission.convId, admission.submissionId);
+			if (old) {
+				if (old.request_digest !== requestDigest) fail("submission_conflict");
+				return JSON.parse(old.receipt_json);
+			}
+			this.modelAccess(current);
+			const referenced = this.references(admission, data, gate);
+			for (const id of referenced) if (!admission.attachments.some(m => m.attachmentId === id)) fail("attachment_reference_unavailable", 410);
+			const rows = admission.attachments.map(m => {
+				const r = this.row(m.attachmentId);
+				this.live(r.id);
+				this.owns(r, admission, r.state !== "bound");
+				if (r.state === "bound" && !referenced.has(r.id)) {
+					if (!direct.has(r.id)) fail("attachment_reference_unavailable", 410);
+					// A direct re-selection is explicit, but must still have a current active grant in this conversation.
+					this.exportEvidence(admission, r.id, gate);
+				}
+				if (r.state !== "ready" && r.state !== "bound") fail(r.state === "revoked" ? "attachment_revoked" : "attachment_not_ready");
+				const p = preparation(r);
+				if (r.revision !== m.expectedRevision || r.preparation_revision !== m.preparationRevision || r.sha256 !== m.originalSha256 ||
+					p.representationSha256 !== m.representationSha256) fail("attachment_manifest_conflict");
+				this.original(r, gate);
+				return r;
+			});
+			if (gate.inspect(this.db, admission, rows.map(preparation)) !== undefined) fail("attachment_provider_invalid", 503);
+			const metadata = rows.map(r => this.metadata(r, crypto.randomUUID()));
+			const message = this.accept(admission.convId, { ...data, origin: "owner-attachment", attachments: metadata }, receipt);
+			const pending = this.db.query<{ seq: number }, [string, number]>(
+				"SELECT seq FROM events WHERE conv=? AND type='main.user.pending' AND json_extract(data,'$.message_seq')=?")
+				.get(admission.convId, message.seq);
+			if (!pending) fail("attachment_provider_invalid", 503);
+			for (const meta of metadata) {
+				this.db.query(`INSERT INTO attachment_grants VALUES (?,?,?,?,?,1,NULL,?,?,?)`).run(meta.grantId, meta.id, admission.convId,
+					admission.recipient.id, message.seq, admission.convEpoch, admission.recipient.epoch, current.authority?.epoch ?? null);
+				this.db.query("UPDATE attachments SET state='bound',revision=revision+1 WHERE id=? AND state='ready'").run(meta.id);
+			}
+			const accepted: AttachmentAccepted = { convId: admission.convId, submissionId: admission.submissionId,
+				messageSeq: message.seq, pendingDispatchSeq: pending.seq, attachments: metadata };
+			this.db.query("INSERT INTO attachment_submissions VALUES (?,?,?,?,?)")
+				.run(admission.convId, admission.submissionId, requestDigest, message.seq, JSON.stringify(accepted));
+			return accepted;
+		}).immediate();
+	}
+	exportEvidence(scope: AttachmentScope, id: string, gate: AttachmentGate): SelectedAttachmentExport {
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.owns(r, scope, false);
+			const grant = this.db.query<Grant, [string, string]>(
+				"SELECT * FROM attachment_grants WHERE attachment_id=? AND conv_id=? AND revoked_at IS NULL ORDER BY message_seq DESC LIMIT 1").get(id, scope.convId);
+			if (!grant || !r.sha256) return fail("attachment_revoked", 410);
+			const receipt = { attachmentId: id, sourceGrantId: grant.id, sourceGrantRevision: grant.revision, originMessageSeq: grant.message_seq,
+				sourceConvId: r.conv_id, sourceRecipientId: r.recipient_id, sourceConvEpoch: r.conv_epoch, sourceRecipientEpoch: r.recipient_epoch,
+				originalSha256: r.sha256, bytes: r.bytes, format: r.format, name: r.original_name };
+			this.assertSelectedExportEligible(this.db, receipt, gate);
+			return receipt;
+		}).immediate();
+	}
+	/** Fits confirmed 292's synchronous gate: bind gate in the trusted composition root. No bytes or recipient grant is minted here. */
+	assertSelectedExportEligible(tx: Database, receipt: SelectedAttachmentExport, gate: AttachmentGate): undefined {
+		if (tx !== this.db || !tx.inTransaction) return fail("attachment_transaction_required");
+		const r = this.row(receipt.attachmentId), grant = this.grant(receipt.sourceGrantId);
+		this.live(r.id);
+		if (grant.revoked_at !== null || r.state !== "bound") fail("attachment_revoked", 410);
+		if (grant.attachment_id !== r.id || grant.revision !== receipt.sourceGrantRevision || grant.message_seq !== receipt.originMessageSeq ||
+			r.conv_id !== receipt.sourceConvId || r.recipient_id !== receipt.sourceRecipientId || r.conv_epoch !== receipt.sourceConvEpoch ||
+			r.recipient_epoch !== receipt.sourceRecipientEpoch || r.sha256 !== receipt.originalSha256 || r.bytes !== receipt.bytes ||
+			r.format !== receipt.format || r.original_name !== receipt.name || grant.conv_epoch !== r.conv_epoch ||
+			grant.recipient_epoch !== r.recipient_epoch || grant.conv_id !== r.conv_id || grant.recipient_id !== r.recipient_id) fail("attachment_scope_mismatch");
+		this.modelAccess(this.current(rowScope(r), gate, false), grant.recipient_authority_epoch);
+		this.original(r, gate);
+		return undefined;
+	}
+	revoke(scope: AttachmentScope, grantId: string, expectedRevision: number, gate: AttachmentGate) {
+		return this.db.transaction(() => {
+			this.current(scope, gate);
+			const grant = this.grant(grantId), r = this.row(grant.attachment_id);
+			this.owns(r, scope, false);
+			if (grant.revision !== expectedRevision || grant.revoked_at !== null) fail("attachment_cas_conflict");
+			return { grantId, revision: grant.revision + 1, pendingDelivery: this.retireGrant(grant) };
+		}).immediate();
+	}
+	/** Serialized on this exact grant: a consumed or unknown delivery is reported and no other activation is touched. */
+	private retireGrant(grant: Grant): "consumed" | "uncertain" | "already_dispatched" | "cancelled" {
+		this.db.query("UPDATE attachment_grants SET revoked_at=?,revision=revision+1 WHERE id=?").run(new Date().toISOString(), grant.id);
+		if (!this.db.query("SELECT id FROM attachment_grants WHERE attachment_id=? AND revoked_at IS NULL").get(grant.attachment_id)) {
+			this.db.query("UPDATE attachments SET state='revoked',revision=revision+1 WHERE id=?").run(grant.attachment_id);
+		}
+		const attempted = this.db.query<{ seq: number }, [string, number]>("SELECT seq FROM events WHERE conv=? AND type='main.input' AND json_extract(data,'$.input_ref.message_seq')=?")
+			.get(grant.conv_id, grant.message_seq);
+		const dispatched = this.db.query("SELECT seq FROM events WHERE conv=? AND type='main.user.dispatched' AND json_extract(data,'$.message_seq')=?")
+			.get(grant.conv_id, grant.message_seq);
+		if (!attempted && !dispatched) this.db.query("INSERT INTO events(conv,type,data,ts) VALUES (?,'main.user.dispatched',?,?)")
+			.run(grant.conv_id, JSON.stringify({ message_seq: grant.message_seq, reason: "attachment_revoked" }), new Date().toISOString());
+		if (!attempted) return dispatched ? "already_dispatched" : "cancelled";
+		const consumed = this.db.query("SELECT seq FROM events WHERE conv=? AND type='main.input.consumed' AND json_extract(data,'$.input_seq')=?").get(grant.conv_id, attempted.seq);
+		return consumed ? "consumed" : "uncertain";
+	}
+	recipientEpoch(recipientId: string): number {
+		return this.db.query<{ epoch: number }, [string]>("SELECT epoch FROM attachment_recipient_epochs WHERE recipient_id=?").get(recipientId)?.epoch ?? 1;
+	}
+	/** Called only once the exact session is closed. Visibility, grants, unbound records and the new epoch change together. */
+	retireRecipient(convId: string, recipientId: string, hide: () => void): readonly string[] {
+		return this.db.transaction(() => {
+			hide();
+			for (const grant of this.db.query<Grant, [string, string]>("SELECT * FROM attachment_grants WHERE conv_id=? AND recipient_id=? AND revoked_at IS NULL").all(convId, recipientId)) this.retireGrant(grant);
+			const unbound = this.db.query<{ id: string }, [string, string]>(`SELECT id FROM attachments WHERE conv_id=? AND recipient_id=?
+				AND state NOT IN ('bound','revoked','discarded') AND id NOT IN (SELECT id FROM attachment_tombstones)`).all(convId, recipientId).map(row => row.id);
+			for (const id of unbound) this.db.query("UPDATE attachments SET state='discarded',revision=revision+1,job_generation=? WHERE id=?").run(crypto.randomUUID(), id);
+			this.db.query("INSERT INTO attachment_recipient_epochs VALUES (?,2) ON CONFLICT(recipient_id) DO UPDATE SET epoch=epoch+1").run(recipientId);
+			return unbound;
+		}).immediate();
+	}
+	/** Readers belong to one process; after a restart no lease can still be delivering. */
+	clearReadLeases(): void { this.db.query("DELETE FROM attachment_read_leases").run(); }
+	resumePreparation(id: string, jobGeneration: string): AttachmentJob & { readonly principal: string; readonly convId: string; readonly encoding: AttachmentEncoding | null } {
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.live(id);
+			if (r.state !== "sealed" || !r.sha256) fail("attachment_cas_conflict");
+			this.db.query("UPDATE attachments SET state='preparing',revision=revision+1,preparation_revision=preparation_revision+1,prepared_manifest_json=NULL,error_code=NULL,job_generation=? WHERE id=?").run(jobGeneration, id);
+			return { ...job(this.row(id)), principal: r.owner_principal, convId: r.conv_id, encoding: r.preparation_encoding };
+		}).immediate();
+	}
+	/** Sealed records that claim to be usable; startup compares each with its bytes. */
+	integrityRows(): readonly { readonly id: string; readonly bytes: number; readonly sha256: string }[] {
+		return this.db.query<{ id: string; bytes: number; sha256: string }, []>(`SELECT id,bytes,sha256 FROM attachments WHERE state IN ('ready','bound') AND sha256 IS NOT NULL
+			AND error_code IS NULL AND id NOT IN (SELECT id FROM attachment_tombstones)`).all();
+	}
+	/** Bound records keep their state so the owner can still revoke the grants. */
+	markUnavailable(id: string): void {
+		this.db.query("UPDATE attachments SET state=CASE state WHEN 'ready' THEN 'error' ELSE state END,revision=revision+1,error_code='attachment_original_unavailable' WHERE id=?").run(id);
+	}
+	private busy(id: string): { readonly grants: number; readonly readers: number; readonly uncertain: number } {
+		const n = (sql: string) => this.db.query<{ n: number }, [string]>(sql).get(id)?.n ?? 0;
+		return { grants: n("SELECT count(*) n FROM attachment_grants WHERE attachment_id=? AND revoked_at IS NULL"),
+			readers: n("SELECT count(*) n FROM attachment_read_leases WHERE attachment_id=?"),
+			uncertain: n(`SELECT count(*) n FROM events e JOIN attachment_grants g ON json_extract(e.data,'$.input_ref.message_seq')=g.message_seq
+				AND e.conv=g.conv_id WHERE g.attachment_id=? AND e.type='main.input'
+				AND NOT EXISTS (SELECT 1 FROM events settled WHERE settled.conv=e.conv AND settled.type IN ('main.input.ack','main.input.handled')
+					AND json_extract(settled.data,'$.input_seq')=e.seq)`) };
+	}
+	/** Terminal records not yet in the Trash, including a tombstone whose earlier move failed. */
+	cleanupRows() {
+		return this.db.query<{ id: string; state: string; bytes: number }, []>(`SELECT a.id,a.state,a.bytes FROM attachments a LEFT JOIN attachment_tombstones t ON t.id=a.id
+			WHERE t.trashed_at IS NULL AND (t.id IS NOT NULL OR a.state IN ('discarded','revoked','error')) ORDER BY a.rowid`).all().map(row => ({ ...row, busy: this.busy(row.id) }));
+	}
+	tombstoneOf(id: string): { readonly digest: string | null; readonly submissionKeys: readonly string[]; readonly reason: string; readonly createdAt: string; readonly trashed: boolean; readonly trashedAt: string | null } | null {
+		const row = this.db.query<{ digest: string | null; submission_keys_json: string; reason: string; created_at: string; trashed_at: string | null }, [string]>("SELECT * FROM attachment_tombstones WHERE id=?").get(id);
+		return row && { digest: row.digest, submissionKeys: JSON.parse(row.submission_keys_json), reason: row.reason, createdAt: row.created_at, trashed: row.trashed_at !== null, trashedAt: row.trashed_at };
+	}
+	markTrashed(id: string): void { this.db.query("UPDATE attachment_tombstones SET trashed_at=? WHERE id=? AND trashed_at IS NULL").run(new Date().toISOString(), id); }
+	/** Startup supplies a fresh worker generation. No source path is returned or reopened. */
+	recover(id: string, expectedRevision: number, generation: string, gate: AttachmentGate): AttachmentJob {
+		if (!UUID.test(generation)) fail("invalid_attachment_input", 400);
+		return this.db.transaction(() => {
+			const r = this.row(id);
+			this.live(id);
+			if (r.revision !== expectedRevision) fail("attachment_cas_conflict");
+			if (r.state === "discarded" || r.state === "revoked") return job(r);
+			if (!r.sha256) {
+				this.db.query("UPDATE attachments SET state='error',revision=revision+1,error_code='snapshot_incomplete',job_generation=? WHERE id=?").run(generation, id);
+			} else {
+				const original = gate.original(this.db, id);
+				if (!original || original.sha256 !== r.sha256 || original.bytes !== r.bytes) {
+					this.db.query("UPDATE attachments SET state='error',revision=revision+1,error_code='attachment_original_unavailable',job_generation=? WHERE id=?")
+						.run(generation, id);
+				} else if (r.state === "sealed" || r.state === "preparing") {
+					this.db.query("UPDATE attachments SET state='sealed',revision=revision+1,prepared_manifest_json=NULL,job_generation=? WHERE id=?")
+						.run(generation, id);
+				}
+			}
+			return job(this.row(id));
+		}).immediate();
+	}
+	acquireRead(receipt: SelectedAttachmentExport, gate: AttachmentGate): string {
+		return this.db.transaction(() => {
+			this.assertSelectedExportEligible(this.db, receipt, gate);
+			const id = crypto.randomUUID();
+			this.db.query("INSERT INTO attachment_read_leases VALUES (?,?,?)").run(id, receipt.attachmentId, JSON.stringify(receipt));
+			return id;
+		}).immediate();
+	}
+	/** Linearizes content release against revoke; caller publishes only if this succeeds. */
+	releaseRead(id: string, gate: AttachmentGate): SelectedAttachmentExport {
+		return this.db.transaction(() => {
+			const lease = this.db.query<{ receipt_json: string }, [string]>("SELECT receipt_json FROM attachment_read_leases WHERE id=?").get(id);
+			if (!lease) return fail("attachment_cas_conflict");
+			const receipt: SelectedAttachmentExport = JSON.parse(lease.receipt_json);
+			this.assertSelectedExportEligible(this.db, receipt, gate);
+			this.db.query("DELETE FROM attachment_read_leases WHERE id=?").run(id);
+			return receipt;
+		}).immediate();
+	}
+	abandonRead(id: string): void { this.db.query("DELETE FROM attachment_read_leases WHERE id=?").run(id); }
+	/** T9 performs the explicit physical Trash action only after this reservation; receipts and operation keys remain. */
+	tombstone(scope: AttachmentScope, id: string, expectedRevision: number, reason: string, gate: AttachmentGate): void {
+		if (!/^[a-z][a-z0-9_]{0,79}$/.test(reason)) fail("invalid_attachment_input", 400);
+		this.db.transaction(() => {
+			this.current(scope, gate);
+			const r = this.row(id);
+			this.owns(r, scope, false);
+			if (r.revision !== expectedRevision) fail("attachment_cas_conflict");
+			this.reserveTombstone(r, reason);
+		}).immediate();
+	}
+	/** The authenticated operator route: it also reaches records whose owner or agent scope no longer exists. */
+	operatorTombstone(id: string, reason: string): void {
+		this.db.transaction(() => this.reserveTombstone(this.row(id), reason)).immediate();
+	}
+	private reserveTombstone(r: Row, reason: string): void {
+		this.live(r.id);
+		const busy = this.busy(r.id);
+		if (!["discarded", "revoked", "error"].includes(r.state) || busy.grants > 0 || busy.readers > 0 || busy.uncertain > 0) fail("attachment_busy");
+		const keys = this.db.query<{ submission_id: string }, [string]>(`SELECT s.submission_id FROM attachment_submissions s
+			JOIN attachment_grants g ON s.message_seq=g.message_seq WHERE g.attachment_id=?`).all(r.id).map(row => row.submission_id);
+		this.db.query("INSERT INTO attachment_tombstones (id,digest,submission_keys_json,reason,created_at) VALUES (?,?,?,?,?)")
+			.run(r.id, r.sha256, JSON.stringify(keys), reason, new Date().toISOString());
+	}
+}