@atomicmemory/core 1.0.0

package/dist/schemas/document-response-schemas.js

@@ -0,0 +1,264 @@
+/**
+ * @file Document-route response schemas.
+ *
+ * Extracted from `schemas/responses.ts` (which was at 435 non-comment
+ * LOC after Slice 3, over the workspace's 400 rule). The shapes are
+ * unchanged — this is a pure relocation. `responses.ts` re-exports
+ * each symbol so existing imports through `import * as R from
+ * './responses'` keep working.
+ *
+ * Field naming follows the wire contract (snake_case). Per-layer
+ * per-layer status enums + `last_error` envelope come from the
+ * shared `document-status-envelope` module so the same definitions
+ * back both `RawDocumentResponseSchema` (full row) and the
+ * passport-feed grouped-row schema.
+ */
+import { z } from './zod-setup.js';
+import { ExtractionStatusEnumSchema, LastErrorEnvelopeSchema, RawStorageStatusEnumSchema, SemanticIndexStatusEnumSchema, } from './document-status-envelope.js';
+/**
+ * Wire shape for `raw_storage_metadata`. Strict allowlist:
+ *   - `codec`: `{ name, version }` only. AES-GCM internals
+ *     (`nonce`/`tag`/`key_id`/`encoded_*`) NEVER reach the wire.
+ *   - `filecoin`: public projection
+ *     `{ ipfs_cid?, piece_cid?, copy_count, provider_ids,
+ *     copy_statuses }` (Phase 4 renamed the legacy ambiguous
+ *     `cid` slot to `ipfs_cid`). The structured internal
+ *     `copies: [{provider_id, status}]` blob is flattened by
+ *     `projectFilecoinPublicMetadata` at the formatter; legacy
+ *     onramp fields (`onramp`, `gateway_url`, `deal_ids`,
+ *     `onramp_status`, `deal_status`, `retrieval_verified_at`,
+ *     `last_verified_at`) and the legacy `cid` slot are NOT
+ *     emitted — the strict schema rejects them at the wire.
+ *   - `upload_result` (internal upload sidecar) is NOT declared,
+ *     so any leak fails the response-shape validator.
+ *
+ * The formatter (`formatPublicRawStorageMetadata`) is the single
+ * source of redaction; this schema is the deny-by-default lock at
+ * the route boundary. Every nested object is `.strict()` so a
+ * formatter regression that lets ANY unknown key through fails the
+ * `validateResponse` middleware instead of silently shipping.
+ */
+export const PublicRawStorageMetadataSchema = z.object({
+    codec: z.object({
+        name: z.enum(['none', 'aes_gcm']),
+        version: z.number(),
+    }).strict().optional(),
+    filecoin: z.object({
+        ipfs_cid: z.string().optional(),
+        piece_cid: z.string().optional(),
+        copy_count: z.number().int().nonnegative().optional(),
+        provider_ids: z.array(z.string()).optional(),
+        copy_statuses: z.array(z.string()).optional(),
+    }).strict().optional(),
+}).strict().openapi({
+    description: 'Public-facing raw_storage_metadata. STRICTLY allowlisted: codec ' +
+        'emits only name+version (AES-GCM internals never reach the wire); ' +
+        'filecoin emits public fields ' +
+        '(ipfs_cid, piece_cid, copy_count, provider_ids, copy_statuses) — ' +
+        '`ipfs_cid` is an optional CIDv1 IPFS / CAR-root identity hint ' +
+        'populated by drivers that derive one alongside the PieceCID; the ' +
+        'canonical storage URI stays `filecoin://piece/<piece_cid>` ' +
+        'regardless. The internal structured copies[{provider_id,status}] ' +
+        'shape is flattened at the formatter; upload_result and other ' +
+        'internal sidecars are NEVER emitted. The schema is deny-by-default ' +
+        '(`.strict()`) at every level — a formatter regression that lets ' +
+        'unknown keys through fails response-shape validation.',
+});
+/** Wire enum for per-row delete semantics. */
+export const DeleteSemanticsEnumSchema = z.enum(['delete', 'unpin', 'tombstone']).nullable()
+    .openapi({
+    description: "What AtomicMemory's DELETE call does at the provider boundary " +
+        "for this row's storage_provider. `'delete'` = adapter issues the " +
+        "provider's removal operation; `'unpin'` = removes AtomicMemory's " +
+        "pin but the provider's other peers may continue to serve; " +
+        "`'tombstone'` = AtomicMemory stops managing the bytes but the " +
+        "decentralized network may still serve. `null` for pointer-only " +
+        "rows or providers not registered for cleanup.",
+});
+/**
+ * Wire-format shape of a document record. Mirrors `RawDocumentRow`
+ * with snake_case keys. `storage_uri` and `storage_provider` are
+ * always null until managed-blob storage is configured.
+ */
+export const RawDocumentResponseSchema = z.object({
+    id: z.string(),
+    user_id: z.string(),
+    raw_source_id: z.string(),
+    external_id: z.string(),
+    external_uri: z.string().nullable(),
+    display_name: z.string().nullable(),
+    mime_type: z.string().nullable(),
+    size_bytes: z.number().nullable(),
+    content_hash: z.string().nullable(),
+    provider_version: z.string().nullable(),
+    source_modified_at: z.string().nullable(),
+    storage_mode: z.enum(['pointer_only', 'managed_blob', 'inline_small_text']),
+    storage_uri: z.string().nullable(),
+    storage_provider: z.string().nullable(),
+    registration_status: z.enum(['registered', 'registration_failed']),
+    raw_storage_status: RawStorageStatusEnumSchema,
+    // Public allowlist: `PublicRawStorageMetadata` projects
+    // through `formatPublicRawStorageMetadata` so AES-GCM internals,
+    // `upload_result`, and any unknown filecoin fields can never reach
+    // the wire. Internal structured `copies: [{ provider_id, status }]`
+    // flattens to `copy_count` / `provider_ids` / `copy_statuses` via
+    // the shared `projectFilecoinPublicMetadata` helper.
+    raw_storage_metadata: PublicRawStorageMetadataSchema,
+    // Per-row delete-semantics capability. NULL
+    // for pointer-only rows and providers the deployment doesn't have
+    // registered for cleanup.
+    delete_semantics: DeleteSemanticsEnumSchema,
+    metadata: z.record(z.string(), z.unknown()),
+    created_at: z.string(),
+    updated_at: z.string(),
+    indexed_content_hash: z.string().nullable(),
+    indexed_at: z.string().nullable(),
+    // Per-layer status envelope. Sub-schemas in
+    // `document-status-envelope.ts`. `'running'` is internal in the
+    // synchronous indexer: readers under READ COMMITTED do
+    // not observe it because the write lives inside the
+    // BEGIN..COMMIT transaction.
+    extraction_status: ExtractionStatusEnumSchema,
+    semantic_index_status: SemanticIndexStatusEnumSchema,
+    last_error: LastErrorEnvelopeSchema,
+    // Additive link to the paired `storage_artifacts` row. NULL for
+    // pointer-only stubs without `external_uri` and older rows.
+    storage_artifact_id: z.string().uuid().nullable(),
+}).openapi({ description: 'Document registry record. snake_case wire format.' });
+export const RegisterDocumentResponseSchema = z.object({
+    document: RawDocumentResponseSchema,
+    created: z.boolean(),
+}).openapi({
+    description: 'Document registration result. `created: true` when a new row was inserted; ' +
+        '`false` when an active row with the same (user, source, external_id, version) ' +
+        'already existed.',
+});
+export const ListDocumentsResponseSchema = z.object({
+    documents: z.array(RawDocumentResponseSchema),
+    count: z.number(),
+}).openapi({ description: 'Paginated document list.' });
+/**
+ * Cursor-paginated user-scoped document list. Distinct from
+ * `ListDocumentsResponseSchema` (the legacy `/list` shape) because it
+ * carries an opaque cursor instead of `count`, matching the
+ * "fetch-next-page" UX the document-detail / recovery surfaces
+ * need. `next_cursor: null` means the stream is exhausted.
+ */
+export const DocumentListRootResponseSchema = z.object({
+    documents: z.array(RawDocumentResponseSchema),
+    next_cursor: z.string().nullable(),
+}).openapi({ description: 'Cursor-paginated document list.' });
+export const DeleteDocumentResponseSchema = z.object({
+    success: z.literal(true),
+    already_deleted: z.boolean(),
+}).openapi({
+    description: 'Document soft-delete acknowledgement. `already_deleted: true` when the row was ' +
+        'missing or previously tombstoned (idempotent on repeat calls).',
+});
+export const UploadRawDocumentResponseSchema = z.object({
+    document_id: z.string(),
+    storage_provider: z.string(),
+    storage_uri: z.string(),
+    // PLAINTEXT content hash — the bytes the caller passed in, not
+    // the encoded bytes the adapter stored.
+    content_hash: z.string(),
+    size_bytes: z.number(),
+    // Filecoin uses `'blob_available'` once gateway retrieval is
+    // confirmed, immediate providers use `'blob_stored'`, and pending
+    // provider acceptances use `'blob_pending'` for the reconciler to
+    // promote. `'blob_archival_failed'` is written by the reconciler,
+    // never returned from this endpoint.
+    raw_storage_status: z.enum(['blob_stored', 'blob_pending', 'blob_available']),
+    storage_mode: z.literal('managed_blob'),
+    // Public allowlist (same as `RawDocumentResponseSchema`).
+    // Internal `upload_result` sidecar + AES-GCM internals NEVER reach
+    // the wire; internal `copies: [{ provider_id, status }]` flattens
+    // to public scalar `copy_count` / `provider_ids` / `copy_statuses`.
+    raw_storage_metadata: PublicRawStorageMetadataSchema,
+    // Per-row delete_semantics — resolved from the just-uploaded row's
+    // `storage_provider` via the registry.
+    delete_semantics: DeleteSemanticsEnumSchema,
+    idempotent_skip: z.boolean(),
+}).openapi({
+    description: 'Managed-blob upload result. The document row is now ' +
+        "`storage_mode='managed_blob'` with `raw_storage_status` set to " +
+        "`'blob_stored'` (immediate providers — local_fs, s3), " +
+        "`'blob_pending'` (eventual providers awaiting the " +
+        "reconciler), or `'blob_available'` (gateway-confirmed " +
+        "retrievable on Filecoin). `content_hash` is the SHA-256 of the " +
+        'PLAINTEXT bytes (distinct from `indexed_content_hash` and from ' +
+        'the encoded-byte hash the codec writes under ' +
+        '`raw_storage_metadata.codec`, which is internal). ' +
+        '`raw_storage_metadata` is the public allowlist ' +
+        '(codec name+version + Synapse filecoin allowlist with ' +
+        'flattened copy_count/provider_ids/copy_statuses — internal ' +
+        'sidecars stripped). `delete_semantics` advertises what ' +
+        "AtomicMemory's DELETE call will do at the provider boundary for " +
+        'this row. `idempotent_skip: true` when the same bytes were ' +
+        'already attached to this document.',
+});
+export const IndexDocumentResponseSchema = z.object({
+    document_id: z.string(),
+    indexed_content_hash: z.string(),
+    chunks_created: z.number(),
+    memories_created: z.number(),
+    idempotent_skip: z.boolean(),
+    chunker_version: z.string(),
+    parser_version: z.string(),
+}).openapi({
+    description: 'Text indexing result. `indexed_content_hash` is the SHA-256 ' +
+        'of the indexed text and is stored on the document as ' +
+        '`indexed_content_hash` (distinct from the upstream/provider ' +
+        '`content_hash`). `idempotent_skip: true` when the input matched the ' +
+        'prior indexed text under the current chunker_version (no fresh ' +
+        'chunks or memories created); otherwise the prior generation was ' +
+        'soft-deleted and the counts reflect the new generation.',
+});
+export const DocumentLimitsResponseSchema = z.object({
+    raw_upload_max_bytes: z.number().int().positive(),
+    index_max_text_bytes: z.number().int().positive(),
+    raw_storage: z.object({
+        enabled: z.boolean(),
+        mode: z.enum(['pointer_only', 'managed_blob']),
+        reason: z.string().optional(),
+        // Filecoin lifecycle refactor (Slice 4): when `mode = 'managed_blob'`
+        // and an adapter is configured, the active store's
+        // `capabilities` surface here. snake_case on the wire; the route
+        // formatter is the only camelCase→snake_case mapper. All five
+        // capability fields are optional so a `pointer_only` deployment
+        // (no store) still validates.
+        provider: z.string().optional(),
+        addressing: z.enum(['location', 'content']).optional(),
+        retrieval_consistency: z.enum(['immediate', 'eventual']).optional(),
+        delete_semantics: z.enum(['delete', 'unpin', 'tombstone']).optional(),
+        supports_head: z.boolean().optional(),
+        supports_get: z.boolean().optional(),
+    }),
+}).openapi({
+    description: 'Document upload/index limits and raw-storage capability. Public ' +
+        'preflight surface — clients read this to size requests and decide ' +
+        'whether to attempt a managed-blob upload. When a managed-blob ' +
+        'adapter is configured, `raw_storage` additionally advertises the ' +
+        "active store's `provider` + capability triple " +
+        '(`addressing`, `retrieval_consistency`, `delete_semantics`) so ' +
+        'clients can render honest copy for eventual-provider flows. ' +
+        'No PII, no per-user state.',
+});
+/**
+ * failure-transition - response shape for `POST /v1/documents/:id/extraction-failure`
+ * and `POST /v1/documents/:id/index-failure`. Both endpoints return the
+ * row in its post-transition state so the caller can read back the
+ * `extraction_status` / `semantic_index_status` / `last_error` they
+ * just persisted without a round-trip to `GET /:id`. `idempotent` is
+ * `true` when the call hit the already-failed-row idempotent retry
+ * branch (no state change beyond `last_error.occurred_at`/`message`).
+ */
+export const DocumentFailureMarkerResponseSchema = z.object({
+    document: RawDocumentResponseSchema,
+    idempotent: z.boolean(),
+}).openapi({
+    description: 'Constrained-transition acknowledgement. The persisted row is ' +
+        'echoed so callers can read back the durable status they just ' +
+        'wrote. `idempotent: true` when the row was already in the ' +
+        'failed state and the call only refreshed `last_error`.',
+});

package/dist/schemas/document-status-envelope.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file Shared Phase B status-envelope sub-schemas.
+ *
+ * The same enum + last_error tuple appears in
+ * `RawDocumentResponseSchema` (full document row) AND in
+ * `PassportFeedDocumentGroupedRowSchema` (the passport-feed grouped
+ * row's per-layer status snapshot). Inlining the literals in both
+ * places caused fallow's clone detector to flag a 31-line duplicate;
+ * centralising them here keeps the wire contract in one place.
+ */
+import { z } from './zod-setup.js';
+export declare const RawStorageStatusEnumSchema: z.ZodEnum<{
+    blob_deleted: "blob_deleted";
+    blob_tombstoned: "blob_tombstoned";
+    blob_stored: "blob_stored";
+    blob_pending: "blob_pending";
+    blob_available: "blob_available";
+    pointer_recorded: "pointer_recorded";
+    inline_text_stored: "inline_text_stored";
+    raw_storage_failed: "raw_storage_failed";
+    blob_archival_failed: "blob_archival_failed";
+}>;
+export declare const ExtractionStatusEnumSchema: z.ZodEnum<{
+    pending: "pending";
+    not_required: "not_required";
+    running: "running";
+    complete: "complete";
+    unsupported: "unsupported";
+    failed: "failed";
+}>;
+export declare const SemanticIndexStatusEnumSchema: z.ZodEnum<{
+    pending: "pending";
+    not_required: "not_required";
+    running: "running";
+    complete: "complete";
+    failed: "failed";
+    stale: "stale";
+}>;
+export declare const LastErrorEnvelopeSchema: z.ZodNullable<z.ZodObject<{
+    layer: z.ZodEnum<{
+        raw_storage: "raw_storage";
+        extraction: "extraction";
+        semantic_index: "semantic_index";
+    }>;
+    code: z.ZodString;
+    message: z.ZodString;
+    occurred_at: z.ZodString;
+}, z.core.$strip>>;

package/dist/schemas/document-status-envelope.js

@@ -0,0 +1,54 @@
+/**
+ * @file Shared Phase B status-envelope sub-schemas.
+ *
+ * The same enum + last_error tuple appears in
+ * `RawDocumentResponseSchema` (full document row) AND in
+ * `PassportFeedDocumentGroupedRowSchema` (the passport-feed grouped
+ * row's per-layer status snapshot). Inlining the literals in both
+ * places caused fallow's clone detector to flag a 31-line duplicate;
+ * centralising them here keeps the wire contract in one place.
+ */
+import { z } from './zod-setup.js';
+// Filecoin lifecycle refactor (Slice 2): the wire enum tracks the DB
+// CHECK constraint + the `RawStorageStatus` TypeScript union — all
+// three must agree. The Zod response validator (`middleware/
+// validate-response.ts`) reads this schema for every document
+// response, so a row in a Phase-1-reserved state (`blob_pending`)
+// must be acceptable on the wire even before its dedicated UI /
+// recovery flows ship. Slice 4 layers the camelCase→snake_case
+// capability map on top of this schema family on the limits route.
+export const RawStorageStatusEnumSchema = z.enum([
+    'pointer_recorded',
+    'blob_stored',
+    'inline_text_stored',
+    'raw_storage_failed',
+    'blob_deleted',
+    'blob_pending',
+    'blob_available',
+    'blob_archival_failed',
+    'blob_tombstoned',
+]);
+export const ExtractionStatusEnumSchema = z.enum([
+    'not_required',
+    'pending',
+    'running',
+    'complete',
+    'unsupported',
+    'failed',
+]);
+export const SemanticIndexStatusEnumSchema = z.enum([
+    'not_required',
+    'pending',
+    'running',
+    'complete',
+    'failed',
+    'stale',
+]);
+export const LastErrorEnvelopeSchema = z
+    .object({
+    layer: z.enum(['raw_storage', 'extraction', 'semantic_index']),
+    code: z.string(),
+    message: z.string(),
+    occurred_at: z.string(),
+})
+    .nullable();

package/dist/schemas/documents.d.ts

@@ -0,0 +1,292 @@
+/**
+ * @file Zod schemas for /v1/documents/*.
+ *
+ * Wire format is snake_case (matching /v1/memories/*); each schema
+ * `.transform()`s to camelCase for handlers. Covers register
+ * (pointer-only at the wire layer), index, raw upload, the
+ * constrained-transition bodies, the query schemas in
+ * `document-list-schemas.ts`, and the runtime preflight + path-param
+ * helpers shared across the routes.
+ *
+ * Wire-layer mode invariant: `POST /v1/documents` (register) still
+ * only accepts `storage_mode='pointer_only'`. The `managed_blob`
+ * mode is populated server-side by the post-upload row-promotion in
+ * `raw-document-blob-repository.ts:updateRawDocumentBlobStorageWithClient`
+ * `inline_small_text` is reserved for a future inline-
+ * text path and is rejected with a "not yet supported" message even
+ * though the SQL CHECK accepts it.
+ */
+import { z } from './zod-setup.js';
+export declare const RegisterDocumentBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    source_site: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    provider: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    external_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    account_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    external_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mime_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    size_bytes: z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | undefined, unknown>>;
+    content_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source_modified_at: z.ZodPipe<z.ZodUnknown, z.ZodTransform<Date | undefined, unknown>>;
+    storage_mode: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"pointer_only", unknown>>;
+    retention_policy: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    consent_policy: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    extraction_status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        not_required: "not_required";
+        unsupported: "unsupported";
+    }>>;
+    semantic_index_status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        not_required: "not_required";
+    }>>;
+}, z.core.$strict>, z.ZodTransform<{
+    extractionStatus: "pending" | "not_required" | "unsupported" | undefined;
+    semanticIndexStatus: "pending" | "not_required" | undefined;
+    storageMode: "pointer_only";
+    retentionPolicy: Record<string, unknown>;
+    consentPolicy: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    externalUri: string | null;
+    displayName: string | null;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    contentHash: string | null;
+    providerVersion: string | null;
+    sourceModifiedAt: Date | null;
+    userId: string;
+    sourceSite: string;
+    provider: string;
+    externalId: string;
+    accountId: string | null;
+}, {
+    user_id: string;
+    source_site: string;
+    provider: string;
+    external_id: string;
+    size_bytes: number | undefined;
+    source_modified_at: Date | undefined;
+    storage_mode: "pointer_only";
+    account_id?: string | null | undefined;
+    external_uri?: string | null | undefined;
+    display_name?: string | null | undefined;
+    mime_type?: string | null | undefined;
+    content_hash?: string | null | undefined;
+    provider_version?: string | null | undefined;
+    retention_policy?: Record<string, unknown> | undefined;
+    consent_policy?: Record<string, unknown> | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    extraction_status?: "pending" | "not_required" | "unsupported" | undefined;
+    semantic_index_status?: "pending" | "not_required" | undefined;
+}>>;
+export type RegisterDocumentBody = z.infer<typeof RegisterDocumentBodySchema>;
+export declare const DocumentIdParamSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    id: string;
+}, {
+    id: string;
+}>>;
+export type DocumentIdParam = z.infer<typeof DocumentIdParamSchema>;
+/**
+ * Exported (private-by-convention) so the cursor-list query-schema module
+ * (`document-list-schemas.ts`) can reuse the same wire contract for
+ * the cursor-paginated routes without re-defining the helper.
+ */
+export declare const RequiredQueryString: z.ZodString;
+export declare const DocumentByIdQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+}, {
+    user_id: string;
+}>>;
+export type DocumentByIdQuery = z.infer<typeof DocumentByIdQuerySchema>;
+export declare const ListDocumentsQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    source_site: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    sourceSite: string | undefined;
+    limit: number;
+    offset: number;
+}, {
+    user_id: string;
+    source_site?: string | undefined;
+    limit?: string | undefined;
+    offset?: string | undefined;
+}>>;
+export type ListDocumentsQuery = z.infer<typeof ListDocumentsQuerySchema>;
+/**
+ * Hard ceiling on the indexed-text body. Deterministic (no env knob)
+ * so the wire contract stays predictable: clients can size their
+ * extracted-text payloads against a known fixed value.
+ *
+ * 25 MiB accommodates the webapp manual-upload pipeline, which allows
+ * 50 MiB input files and feeds the *extracted* text (typically a
+ * fraction of the source size — e.g. a 50 MiB PDF extracts to ≈ 5 MiB
+ * of text).
+ *
+ * status-layer durable-failure contract: the indexer's `semanticValidate`
+ * (in `services/document-indexer.ts`) is the authoritative gate for
+ * whitespace-only and oversized-text inputs. Both checks fire AFTER
+ * the document is loaded and the running CAS lands, so the row is
+ * durably marked `semantic_index_status='failed'` + `last_error`
+ * before the route returns 413/400. The route's body-parser limit
+ * (`INDEX_BODY_PARSER_LIMIT` below) is a defense-in-depth bound that
+ * lets a body containing exactly `MAX_INDEX_TEXT_BYTES` of text reach
+ * the handler with reasonable JSON-wrapper headroom while still
+ * rejecting truly multi-GB request bodies.
+ *
+ * `IndexDocumentBodySchema` deliberately does NOT refine on whitespace
+ * or byte length — those are durable-failure checks owned by the
+ * indexer. The schema only enforces structural shape (string fields
+ * are present and typed correctly) so callers that send a malformed
+ * body (no `user_id`, missing `text`, wrong type) still get a clean
+ * pre-document-known 400 with no row touched.
+ */
+export declare const MAX_INDEX_TEXT_BYTES: number;
+/**
+ * Per-route HTTP body-parser limit for `POST /v1/documents/:id/index`.
+ * Adds a 64 KiB headroom on top of `MAX_INDEX_TEXT_BYTES` so a body
+ * containing the cap-sized text plus the JSON wrapper
+ * (`{"user_id":"<uuid>","text":"…"}`) and modest amounts of escape
+ * encoding still fits. Truly huge request bodies (multi-GB scrape
+ * dumps, malformed clients, attack payloads) still get rejected by
+ * Express's body parser with 413 BEFORE the handler runs.
+ *
+ * Pathological JSON-escape encodings that double the encoded text
+ * size will exceed this cap and surface as 413 from the body-parser
+ * — that is the right behavior; the runtime semantic-validation
+ * limit is on the parsed UTF-8 string, not the wire-encoded bytes,
+ * and a caller can re-encode to fit.
+ */
+export declare const INDEX_BODY_PARSER_LIMIT: number;
+export declare const IndexDocumentBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    text: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    text: string;
+}, {
+    user_id: string;
+    text: string;
+}>>;
+export type IndexDocumentBody = z.infer<typeof IndexDocumentBodySchema>;
+/**
+ * failure-transition - bounded enum of extraction-layer failure codes accepted on
+ * `POST /v1/documents/:id/extraction-failure`. The set deliberately
+ * mirrors the audit's "things a parser does when it gives up" list;
+ * adding a new code requires updating this enum AND the route's
+ * `ExtractionErrorCode` SDK type so the wire stays in lockstep.
+ */
+declare const ExtractionErrorCodeSchema: z.ZodEnum<{
+    unknown: "unknown";
+    parser_threw: "parser_threw";
+    parser_timeout: "parser_timeout";
+    parser_oom: "parser_oom";
+    unsupported_encoding: "unsupported_encoding";
+    corrupt_input: "corrupt_input";
+}>;
+export type ExtractionErrorCode = z.infer<typeof ExtractionErrorCodeSchema>;
+/**
+ * failure-transition - request body for the constrained extraction-failure
+ * transition. The route service-truncates / sanitises `error_message`
+ * before persisting (see `sanitizeLastErrorMessage` +
+ * `MAX_LAST_ERROR_MESSAGE_CHARS` in
+ * `src/db/raw-document-status-repository.ts`); the schema enforces
+ * upper-bound shape only. Service-owned status fields are NOT
+ * accepted - clients can declare *that* extraction failed and *what
+ * category*, but cannot put a document into arbitrary status
+ * combinations.
+ */
+export declare const ExtractionFailureBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    error_code: z.ZodEnum<{
+        unknown: "unknown";
+        parser_threw: "parser_threw";
+        parser_timeout: "parser_timeout";
+        parser_oom: "parser_oom";
+        unsupported_encoding: "unsupported_encoding";
+        corrupt_input: "corrupt_input";
+    }>;
+    error_message: z.ZodString;
+}, z.core.$strict>, z.ZodTransform<{
+    userId: string;
+    errorCode: "unknown" | "parser_threw" | "parser_timeout" | "parser_oom" | "unsupported_encoding" | "corrupt_input";
+    errorMessage: string;
+}, {
+    user_id: string;
+    error_code: "unknown" | "parser_threw" | "parser_timeout" | "parser_oom" | "unsupported_encoding" | "corrupt_input";
+    error_message: string;
+}>>;
+export type ExtractionFailureBody = z.infer<typeof ExtractionFailureBodySchema>;
+/**
+ * failure-transition - bounded enum of semantic-index-layer failure codes
+ * accepted on `POST /v1/documents/:id/index-failure`. The
+ * `index_text_too_large` code is special: when paired with a row in
+ * `extraction_status='pending'`, the route atomically advances
+ * extraction to `'complete'` (text-in-hand implies extraction
+ * succeeded) AND marks semantic_index `'failed'` so the durable row
+ * reflects the upload pipeline's actual sequence.
+ */
+declare const IndexErrorCodeSchema: z.ZodEnum<{
+    unknown: "unknown";
+    index_text_too_large: "index_text_too_large";
+    extraction_empty: "extraction_empty";
+}>;
+export type IndexErrorCode = z.infer<typeof IndexErrorCodeSchema>;
+/**
+ * failure-transition - request body for the constrained index-failure
+ * transition. Service ownership rules match
+ * `ExtractionFailureBodySchema`: the message is sanitised + truncated
+ * server-side; status fields cannot be smuggled in.
+ */
+export declare const IndexFailureBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    error_code: z.ZodEnum<{
+        unknown: "unknown";
+        index_text_too_large: "index_text_too_large";
+        extraction_empty: "extraction_empty";
+    }>;
+    error_message: z.ZodString;
+}, z.core.$strict>, z.ZodTransform<{
+    userId: string;
+    errorCode: "unknown" | "index_text_too_large" | "extraction_empty";
+    errorMessage: string;
+}, {
+    user_id: string;
+    error_code: "unknown" | "index_text_too_large" | "extraction_empty";
+    error_message: string;
+}>>;
+export type IndexFailureBody = z.infer<typeof IndexFailureBodySchema>;
+/**
+ * Query schema for the raw-upload route. The body is the file bytes
+ * themselves (Content-Type: application/octet-stream); identifying
+ * fields ride on the query string so we don't have to multipart-parse.
+ */
+export declare const UploadRawDocumentQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    content_type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    contentType: string | undefined;
+}, {
+    user_id: string;
+    content_type?: string | undefined;
+}>>;
+export type UploadRawDocumentQuery = z.infer<typeof UploadRawDocumentQuerySchema>;
+/**
+ * Exported for the cursor-list query-schema module
+ * (`document-list-schemas.ts`) so the cursor-paginated routes share
+ * the same parse-and-clamp semantics for `limit`. Returns
+ * `defaultVal` for missing / non-numeric input; clamps to
+ * `[min, max]` otherwise.
+ */
+export declare function clampInt(raw: string | undefined, defaultVal: number, min: number, max: number): number;
+export {};