Extraction & OCR

The extraction.* family (10 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Claimextraction.job.claim

AdminOnly (DEFERRED). Atomic guard: UPDATE … WHERE status=‘PENDING’. Returns { claimed } (rows_affected==1). Mirrors agenttask.claim.

Call POST /v/extraction.job.claim with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Createextraction.job.create

(DEFERRED). Dedup on (file_record_id, status IN PENDING|PROCESSING) -> return existing {idempotent

Call POST /v/extraction.job.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool extraction.job.create.

Finishextraction.job.finish

AdminOnly (DEFERRED). Terminal transition; server stamps completed_at=now(). One verb covers all four terminal sites via status. { jobId, status, resultCount?, errorMessage?, modelId?, currentStep?, stepLabel? }. State guard: an already-terminal job -> idempotent if the status matches, else Conflict.

Call POST /v/extraction.job.finish with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Progressextraction.job.progress

AdminOnly (DEFERRED). Non-terminal progress (mirrors agenttask.checkpoint). { jobId, currentStep?, stepLabel?, snapshotId? } - only-set-what-was-sent. Fence id+workspace.

Call POST /v/extraction.job.progress with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Sweepextraction.job.sweep

AdminOnly (DEFERRED). Batch stale-recovery, workspace-scoped, replicating recoverStaleJobs (extraction-queue.ts) in ONE verb tx, in the SAME order (so a just-timed-out PROCESSING job cascades to TIMED_OUT/PENDING in the same sweep, exactly as the frontend $transaction did): (1) PROCESSING past timeout_at -> FAILED + ‘Job timed out’ + completed_at (2) FAILED with attempts >= max_attempts -> TIMED_OUT (terminal) (3) FAILED with attempts < max_attempts -> PENDING (retry)

Call POST /v/extraction.job.sweep with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Deleteextraction.mapping.delete

(DEFERRED; no live caller). { rawClass }. Idempotent delete on (workspace_id, raw_class).

Call POST /v/extraction.mapping.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool extraction.mapping.delete.

Setextraction.mapping.set

(DEFERRED; no live caller). Idempotent upsert on (workspace_id, raw_class). { rawClass, canonicalClass }. created_by_id from the acting user (optional).

Call POST /v/extraction.mapping.set with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool extraction.mapping.set.

Recordextraction.quality.record

AdminOnly (DEFERRED; append-only score row). { fileRecordId, textLength, fileSize, compressionRatio, garbledCharRate, structureScore, passedThreshold }. Mints eqs_. NO updated_at.

Call POST /v/extraction.quality.record with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Createextraction.snapshot.create

AdminOnly, SENSITIVE/L2 (DEFERRED; raw document plaintext). { fileRecordId, plainText }. Server computes text_hash=sha256(plainText) + char_count. Mints esnap_. NO updated_at column.

Call POST /v/extraction.snapshot.create with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Purgeextraction.snapshot.purge

AdminOnly (DEFERRED; per-workspace retention). { olderThanDays }. Deletes extraction_snapshots created before now()-days within the caller’s workspace (the cross-workspace CRON must enumerate workspaces and dispatch this per-workspace - an architecture-gated boundary change).

Call POST /v/extraction.snapshot.purge with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.