@atomicmemory/core 1.0.0

package/dist/routes/memory-response-formatters.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Wire-format response shapers for the memory API.
+ *
+ * Internal service types use camelCase; HTTP wire convention is snake_case.
+ * These formatters translate at the route boundary so internal types and
+ * the public contract can evolve independently.
+ *
+ * Database rows (MemoryRow, LessonRow, ClaimVersionRow) already use
+ * snake_case column names and pass through unchanged.
+ */
+import type { IngestResult, MemoryScope, RetrievalObservability } from '../services/memory-service-types.js';
+import type { ConsolidationResult, ConsolidationExecutionResult } from '../services/consolidation-service.js';
+import type { DecayResult, CapCheckResult } from '../services/memory-lifecycle.js';
+import type { ReconciliationResult } from '../services/deferred-audn.js';
+import type { MutationSummary, AuditTrailEntry } from '../db/repository-types.js';
+export declare function formatIngestResponse(result: IngestResult): {
+    ingest_trace_id?: string | undefined;
+    episode_id: string;
+    facts_extracted: number;
+    memories_stored: number;
+    memories_updated: number;
+    memories_deleted: number;
+    memories_skipped: number;
+    stored_memory_ids: string[];
+    updated_memory_ids: string[];
+    links_created: number;
+    composites_created: number;
+};
+export declare function formatScope(scope: MemoryScope): {
+    kind: "user";
+    user_id: string;
+} | {
+    agent_scope?: import("../db/repository-types.js").AgentScope | undefined;
+    kind: "workspace";
+    user_id: string;
+    workspace_id: string;
+    agent_id: string;
+};
+export declare function formatStatsResponse(stats: {
+    count: number;
+    avgImportance: number;
+    sourceDistribution: Record<string, number>;
+}): {
+    count: number;
+    avg_importance: number;
+    source_distribution: Record<string, number>;
+};
+export declare function formatConsolidateResponse(result: ConsolidationResult): {
+    memories_scanned: number;
+    clusters_found: number;
+    memories_in_clusters: number;
+    clusters: {
+        member_ids: string[];
+        member_contents: string[];
+        avg_affinity: number;
+        member_count: number;
+    }[];
+};
+export declare function formatConsolidateExecuteResponse(result: ConsolidationExecutionResult): {
+    clusters_consolidated: number;
+    memories_archived: number;
+    memories_created: number;
+    consolidated_memory_ids: string[];
+};
+export declare function formatDecayResponse(result: DecayResult, archived: number): {
+    memories_evaluated: number;
+    candidates_for_archival: {
+        id: string;
+        content: string;
+        retention_score: number;
+        importance: number;
+        days_since_access: number;
+        access_count: number;
+    }[];
+    retention_threshold: number;
+    avg_retention_score: number;
+    archived: number;
+};
+export declare function formatCapResponse(result: CapCheckResult): {
+    active_memories: number;
+    max_memories: number;
+    status: import("../services/memory-lifecycle.js").CapStatus;
+    usage_ratio: number;
+    recommendation: import("../services/memory-lifecycle.js").CapRecommendation;
+};
+export declare function formatLessonStatsResponse(stats: {
+    totalActive: number;
+    byType: Record<string, number>;
+}): {
+    total_active: number;
+    by_type: Record<string, number>;
+};
+export declare function formatReconciliationResponse(result: ReconciliationResult): {
+    processed: number;
+    resolved: number;
+    noops: number;
+    updates: number;
+    supersedes: number;
+    deletes: number;
+    adds: number;
+    errors: number;
+    duration_ms: number;
+};
+export declare function formatResetSourceResponse(result: {
+    deletedMemories: number;
+    deletedEpisodes: number;
+    deletedDocuments: number;
+}): {
+    success: boolean;
+    deleted_memories: number;
+    deleted_episodes: number;
+    deleted_documents: number;
+};
+export declare function formatMutationSummaryResponse(summary: MutationSummary): {
+    total_versions: number;
+    active_versions: number;
+    superseded_versions: number;
+    total_claims: number;
+    by_mutation_type: Record<string, number>;
+};
+export declare function formatObservability(observability: RetrievalObservability): {
+    assembly?: {
+        final_ids: string[];
+        final_token_cost: number;
+        token_budget: number | null;
+        primary_evidence_position: number | null;
+        blocks: string[];
+    } | undefined;
+    packaging?: {
+        package_type: import("../services/retrieval-trace.js").PackagingType;
+        included_ids: string[];
+        dropped_ids: string[];
+        evidence_roles: Record<string, import("../services/retrieval-trace.js").PackagingEvidenceRole>;
+        episode_count: number;
+        date_count: number;
+        has_current_marker: boolean;
+        has_conflict_block: boolean;
+        token_cost: number;
+    } | undefined;
+    retrieval?: {
+        stage_names?: string[] | undefined;
+        stage_count?: number | undefined;
+        trace_id?: string | undefined;
+        filter_decisions?: {
+            id: string;
+            source_site: string;
+            source_kind: "local" | "integration";
+            namespace: string | null;
+            semantic_similarity: number;
+            ranking_score: number;
+            relevance: number;
+            threshold: number | null;
+            decision: "filtered" | "kept";
+            reason: string;
+        }[] | undefined;
+        filtered_candidate_ids?: string[] | undefined;
+        relevance_filter_reason?: string | undefined;
+        relevance_filter_source?: string | undefined;
+        relevance_threshold?: number | null | undefined;
+        candidate_ids: string[];
+        candidate_count: number;
+        query_text: string;
+        skip_repair: boolean;
+    } | undefined;
+};
+export declare function formatAuditTrailEntry(entry: AuditTrailEntry): {
+    version_id: string;
+    claim_id: string;
+    content: string;
+    mutation_type: import("../db/repository-types.js").MutationType | null;
+    mutation_reason: string | null;
+    actor_model: string | null;
+    contradiction_confidence: number | null;
+    previous_version_id: string | null;
+    superseded_by_version_id: string | null;
+    valid_from: Date;
+    valid_to: Date | null;
+    memory_id: string | null;
+};

package/dist/routes/memory-response-formatters.js

@@ -0,0 +1,210 @@
+/**
+ * Wire-format response shapers for the memory API.
+ *
+ * Internal service types use camelCase; HTTP wire convention is snake_case.
+ * These formatters translate at the route boundary so internal types and
+ * the public contract can evolve independently.
+ *
+ * Database rows (MemoryRow, LessonRow, ClaimVersionRow) already use
+ * snake_case column names and pass through unchanged.
+ */
+export function formatIngestResponse(result) {
+    return {
+        episode_id: result.episodeId,
+        facts_extracted: result.factsExtracted,
+        memories_stored: result.memoriesStored,
+        memories_updated: result.memoriesUpdated,
+        memories_deleted: result.memoriesDeleted,
+        memories_skipped: result.memoriesSkipped,
+        stored_memory_ids: result.storedMemoryIds,
+        updated_memory_ids: result.updatedMemoryIds,
+        links_created: result.linksCreated,
+        composites_created: result.compositesCreated,
+        ...(result.ingestTraceId ? { ingest_trace_id: result.ingestTraceId } : {}),
+    };
+}
+export function formatScope(scope) {
+    if (scope.kind === 'user') {
+        return { kind: 'user', user_id: scope.userId };
+    }
+    return {
+        kind: 'workspace',
+        user_id: scope.userId,
+        workspace_id: scope.workspaceId,
+        agent_id: scope.agentId,
+        ...(scope.agentScope !== undefined ? { agent_scope: scope.agentScope } : {}),
+    };
+}
+export function formatStatsResponse(stats) {
+    return {
+        count: stats.count,
+        avg_importance: stats.avgImportance,
+        source_distribution: stats.sourceDistribution,
+    };
+}
+function formatClusterCandidate(cluster) {
+    return {
+        member_ids: cluster.memberIds,
+        member_contents: cluster.memberContents,
+        avg_affinity: cluster.avgAffinity,
+        member_count: cluster.memberCount,
+    };
+}
+export function formatConsolidateResponse(result) {
+    return {
+        memories_scanned: result.memoriesScanned,
+        clusters_found: result.clustersFound,
+        memories_in_clusters: result.memoriesInClusters,
+        clusters: result.clusters.map(formatClusterCandidate),
+    };
+}
+export function formatConsolidateExecuteResponse(result) {
+    return {
+        clusters_consolidated: result.clustersConsolidated,
+        memories_archived: result.memoriesArchived,
+        memories_created: result.memoriesCreated,
+        consolidated_memory_ids: result.consolidatedMemoryIds,
+    };
+}
+function formatDecayCandidate(candidate) {
+    return {
+        id: candidate.id,
+        content: candidate.content,
+        retention_score: candidate.retentionScore,
+        importance: candidate.importance,
+        days_since_access: candidate.daysSinceAccess,
+        access_count: candidate.accessCount,
+    };
+}
+export function formatDecayResponse(result, archived) {
+    return {
+        memories_evaluated: result.memoriesEvaluated,
+        candidates_for_archival: result.candidatesForArchival.map(formatDecayCandidate),
+        retention_threshold: result.retentionThreshold,
+        avg_retention_score: result.avgRetentionScore,
+        archived,
+    };
+}
+export function formatCapResponse(result) {
+    return {
+        active_memories: result.activeMemories,
+        max_memories: result.maxMemories,
+        status: result.status,
+        usage_ratio: result.usageRatio,
+        recommendation: result.recommendation,
+    };
+}
+export function formatLessonStatsResponse(stats) {
+    return {
+        total_active: stats.totalActive,
+        by_type: stats.byType,
+    };
+}
+export function formatReconciliationResponse(result) {
+    return {
+        processed: result.processed,
+        resolved: result.resolved,
+        noops: result.noops,
+        updates: result.updates,
+        supersedes: result.supersedes,
+        deletes: result.deletes,
+        adds: result.adds,
+        errors: result.errors,
+        duration_ms: result.durationMs,
+    };
+}
+export function formatResetSourceResponse(result) {
+    return {
+        success: true,
+        deleted_memories: result.deletedMemories,
+        deleted_episodes: result.deletedEpisodes,
+        deleted_documents: result.deletedDocuments,
+    };
+}
+export function formatMutationSummaryResponse(summary) {
+    return {
+        total_versions: summary.totalVersions,
+        active_versions: summary.activeVersions,
+        superseded_versions: summary.supersededVersions,
+        total_claims: summary.totalClaims,
+        by_mutation_type: summary.byMutationType,
+    };
+}
+function formatRetrievalTrace(summary) {
+    return {
+        candidate_ids: summary.candidateIds,
+        candidate_count: summary.candidateCount,
+        query_text: summary.queryText,
+        skip_repair: summary.skipRepair,
+        ...(summary.relevanceThreshold !== undefined ? { relevance_threshold: summary.relevanceThreshold } : {}),
+        ...(summary.relevanceFilterSource ? { relevance_filter_source: summary.relevanceFilterSource } : {}),
+        ...(summary.relevanceFilterReason ? { relevance_filter_reason: summary.relevanceFilterReason } : {}),
+        ...(summary.filteredCandidateIds ? { filtered_candidate_ids: summary.filteredCandidateIds } : {}),
+        ...(summary.filterDecisions ? {
+            filter_decisions: summary.filterDecisions.map(formatFilterDecision),
+        } : {}),
+        ...(summary.traceId ? { trace_id: summary.traceId } : {}),
+        ...(summary.stageCount !== undefined ? { stage_count: summary.stageCount } : {}),
+        ...(summary.stageNames ? { stage_names: summary.stageNames } : {}),
+    };
+}
+function formatFilterDecision(decision) {
+    return {
+        id: decision.id,
+        source_site: decision.sourceSite,
+        source_kind: decision.sourceKind,
+        namespace: decision.namespace,
+        semantic_similarity: decision.semanticSimilarity,
+        ranking_score: decision.rankingScore,
+        relevance: decision.relevance,
+        threshold: decision.threshold,
+        decision: decision.decision,
+        reason: decision.reason,
+    };
+}
+function formatPackagingTrace(summary) {
+    return {
+        package_type: summary.packageType,
+        included_ids: summary.includedIds,
+        dropped_ids: summary.droppedIds,
+        // evidenceRoles keys are memory IDs (opaque); values are role enum strings.
+        evidence_roles: summary.evidenceRoles,
+        episode_count: summary.episodeCount,
+        date_count: summary.dateCount,
+        has_current_marker: summary.hasCurrentMarker,
+        has_conflict_block: summary.hasConflictBlock,
+        token_cost: summary.tokenCost,
+    };
+}
+function formatAssemblyTrace(summary) {
+    return {
+        final_ids: summary.finalIds,
+        final_token_cost: summary.finalTokenCost,
+        token_budget: summary.tokenBudget,
+        primary_evidence_position: summary.primaryEvidencePosition,
+        blocks: summary.blocks,
+    };
+}
+export function formatObservability(observability) {
+    return {
+        ...(observability.retrieval ? { retrieval: formatRetrievalTrace(observability.retrieval) } : {}),
+        ...(observability.packaging ? { packaging: formatPackagingTrace(observability.packaging) } : {}),
+        ...(observability.assembly ? { assembly: formatAssemblyTrace(observability.assembly) } : {}),
+    };
+}
+export function formatAuditTrailEntry(entry) {
+    return {
+        version_id: entry.versionId,
+        claim_id: entry.claimId,
+        content: entry.content,
+        mutation_type: entry.mutationType,
+        mutation_reason: entry.mutationReason,
+        actor_model: entry.actorModel,
+        contradiction_confidence: entry.contradictionConfidence,
+        previous_version_id: entry.previousVersionId,
+        superseded_by_version_id: entry.supersededByVersionId,
+        valid_from: entry.validFrom,
+        valid_to: entry.validTo,
+        memory_id: entry.memoryId,
+    };
+}

package/dist/routes/public-raw-storage-metadata.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Public projection of `raw_documents.raw_storage_metadata`.
+ *
+ * The upload and reconciler pipeline writes an internal
+ * shape `{ codec, filecoin?, upload_result? }` into the JSONB
+ * column. This module is the SINGLE wire-side redaction seam:
+ * internal sidecars (`upload_result`, AES-GCM `nonce`/`tag`/`key_id`
+ * /`encoded_content_hash`/`encoded_size_bytes`) NEVER appear on the
+ * wire; the Filecoin sidecar is projected through the shared
+ * storage/public metadata module
+ * (`src/storage/filecoin-public-metadata.ts`) so document and
+ * storage_artifact paths emit one consistent shape without
+ * importing `providers/filecoin/*` from the route layer.
+ *
+ * The Filecoin public shape is `{ ipfs_cid, piece_cid,
+ * copy_count, provider_ids, copy_statuses }` (Phase 4 renamed
+ * the previous ambiguous `cid` slot to `ipfs_cid`). Legacy
+ * onramp keys (`onramp`, `gateway_url`, `deal_ids`,
+ * `onramp_status`, `deal_status`, `retrieval_verified_at`,
+ * `last_verified_at`) and the legacy `cid` slot are NOT emitted
+ * by this projector — adversarial / pre-migration values are
+ * silently dropped at the shape gate (and rejected at the
+ * deny-by-default Zod schema if they somehow reach the response
+ * validator).
+ */
+import { type FilecoinPublicMetadata } from '../storage/filecoin-public-metadata.js';
+/** Public-facing codec shape — `name` + `version` only. */
+export interface PublicCodecMetadata {
+    name: string;
+    version: number;
+}
+/**
+ * Re-export of the Synapse-shaped public filecoin shape produced
+ * by `src/storage/filecoin-public-metadata.ts`. Routes consume
+ * the projected fields directly (e.g. `metadata.filecoin?.ipfs_cid`,
+ * `metadata.filecoin?.piece_cid`) — see that module for the
+ * canonical key list.
+ */
+export type PublicFilecoinMetadata = FilecoinPublicMetadata;
+export interface PublicRawStorageMetadata {
+    codec?: PublicCodecMetadata;
+    filecoin?: PublicFilecoinMetadata;
+}
+/**
+ * Strip internal-only sidecars from a `raw_storage_metadata` JSONB
+ * blob. Pure projection — idempotent and side-effect free.
+ *
+ *   - `codec` keeps only `{ name, version }`.
+ *   - `filecoin` is projected via `projectFilecoinPublicMetadata`
+ *     so the wire shape matches the storage-side allowlist.
+ *   - `upload_result` and any other top-level
+ *     keys are dropped.
+ */
+export declare function formatPublicRawStorageMetadata(internal: Record<string, unknown>): PublicRawStorageMetadata;

package/dist/routes/public-raw-storage-metadata.js

@@ -0,0 +1,56 @@
+/**
+ * @file Public projection of `raw_documents.raw_storage_metadata`.
+ *
+ * The upload and reconciler pipeline writes an internal
+ * shape `{ codec, filecoin?, upload_result? }` into the JSONB
+ * column. This module is the SINGLE wire-side redaction seam:
+ * internal sidecars (`upload_result`, AES-GCM `nonce`/`tag`/`key_id`
+ * /`encoded_content_hash`/`encoded_size_bytes`) NEVER appear on the
+ * wire; the Filecoin sidecar is projected through the shared
+ * storage/public metadata module
+ * (`src/storage/filecoin-public-metadata.ts`) so document and
+ * storage_artifact paths emit one consistent shape without
+ * importing `providers/filecoin/*` from the route layer.
+ *
+ * The Filecoin public shape is `{ ipfs_cid, piece_cid,
+ * copy_count, provider_ids, copy_statuses }` (Phase 4 renamed
+ * the previous ambiguous `cid` slot to `ipfs_cid`). Legacy
+ * onramp keys (`onramp`, `gateway_url`, `deal_ids`,
+ * `onramp_status`, `deal_status`, `retrieval_verified_at`,
+ * `last_verified_at`) and the legacy `cid` slot are NOT emitted
+ * by this projector — adversarial / pre-migration values are
+ * silently dropped at the shape gate (and rejected at the
+ * deny-by-default Zod schema if they somehow reach the response
+ * validator).
+ */
+import { projectFilecoinPublicMetadata, } from '../storage/filecoin-public-metadata.js';
+/**
+ * Strip internal-only sidecars from a `raw_storage_metadata` JSONB
+ * blob. Pure projection — idempotent and side-effect free.
+ *
+ *   - `codec` keeps only `{ name, version }`.
+ *   - `filecoin` is projected via `projectFilecoinPublicMetadata`
+ *     so the wire shape matches the storage-side allowlist.
+ *   - `upload_result` and any other top-level
+ *     keys are dropped.
+ */
+export function formatPublicRawStorageMetadata(internal) {
+    const out = {};
+    const codec = projectCodec(internal['codec']);
+    if (codec)
+        out.codec = codec;
+    const filecoin = projectFilecoinPublicMetadata(internal['filecoin']);
+    if (Object.keys(filecoin).length > 0)
+        out.filecoin = filecoin;
+    return out;
+}
+function projectCodec(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    const name = record['name'];
+    const version = record['version'];
+    if (typeof name !== 'string' || typeof version !== 'number')
+        return null;
+    return { name, version };
+}

package/dist/routes/reflect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Synchronous reflect-flush endpoint for benchmark / eval mode.
+ *
+ * POST /v1/reflect/flush — drains all pending reflection_jobs serially and
+ * returns the count of jobs processed. Returns 503 if Reflect is disabled.
+ *
+ * This endpoint is intentionally synchronous (it blocks until the queue is
+ * empty or the 1 000-job safety cap is hit) so benchmarking harnesses can
+ * call it once after ingest and be guaranteed all reflections are written
+ * before issuing queries.
+ */
+import type { Request, Response } from 'express';
+import type { JobsWorkerDeps } from '../services/reflect-jobs.js';
+export declare function makeReflectFlushHandler(deps: JobsWorkerDeps, enabled: boolean): (req: Request, res: Response) => Promise<void>;

package/dist/routes/reflect.js

@@ -0,0 +1,19 @@
+import { processOnePendingJob } from '../services/reflect-jobs.js';
+const FLUSH_JOB_CAP = 1000;
+export function makeReflectFlushHandler(deps, enabled) {
+    return async (_req, res) => {
+        if (!enabled) {
+            res.status(503).json({ error: 'reflect_disabled' });
+            return;
+        }
+        let processed = 0;
+        let remaining = FLUSH_JOB_CAP;
+        while (remaining-- > 0) {
+            const did = await processOnePendingJob(deps);
+            if (!did)
+                break;
+            processed++;
+        }
+        res.json({ processed });
+    };
+}

package/dist/routes/response-schema-map.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Route→schema maps consumed by `validate-response` middleware.
+ *
+ * Keyed by Express's router-relative `${method} ${route.path}` format
+ * (method lowercase, path matches what Express stores in `req.route.path`).
+ * When a new route is added, add a corresponding entry here; the
+ * validator is a no-op for routes not in the map (so new routes
+ * ship without a hard dependency on a schema existing yet).
+ */
+import type { ResponseSchemaMap } from '../middleware/validate-response.js';
+export declare const MEMORY_RESPONSE_SCHEMAS: ResponseSchemaMap;
+export declare const AGENT_RESPONSE_SCHEMAS: ResponseSchemaMap;
+export declare const DOCUMENT_RESPONSE_SCHEMAS: ResponseSchemaMap;
+export declare const STORAGE_RESPONSE_SCHEMAS: ResponseSchemaMap;

package/dist/routes/response-schema-map.js

@@ -0,0 +1,69 @@
+/**
+ * @file Route→schema maps consumed by `validate-response` middleware.
+ *
+ * Keyed by Express's router-relative `${method} ${route.path}` format
+ * (method lowercase, path matches what Express stores in `req.route.path`).
+ * When a new route is added, add a corresponding entry here; the
+ * validator is a no-op for routes not in the map (so new routes
+ * ship without a hard dependency on a schema existing yet).
+ */
+import * as R from '../schemas/responses.js';
+import { PassportFeedResponseSchema } from '../schemas/document-list-responses.js';
+import { DeleteArtifactResultSchema, StorageCapabilitiesResponseSchema, StoredArtifactResponseSchema, VerifyArtifactResultSchema, } from '../schemas/storage-schemas.js';
+export const MEMORY_RESPONSE_SCHEMAS = {
+    'post /ingest': R.IngestResponseSchema,
+    'post /ingest/quick': R.IngestResponseSchema,
+    'post /search': R.SearchResponseSchema,
+    'post /search/fast': R.SearchResponseSchema,
+    'post /expand': R.ExpandResponseSchema,
+    'post /verify': R.VerifyResponseSchema,
+    'get /list': R.ListResponseSchema,
+    'get /stats': R.StatsResponseSchema,
+    'get /health': R.HealthResponseSchema,
+    'put /config': R.ConfigUpdateResponseSchema,
+    'get /event-chains': R.EventChainsResponseSchema,
+    'post /first-mentions/extract': R.FirstMentionsExtractResponseSchema,
+    'post /consolidate': R.ConsolidateResponseSchema,
+    'post /decay': R.DecayResponseSchema,
+    'get /cap': R.CapResponseSchema,
+    'get /lessons': R.LessonsListResponseSchema,
+    'get /lessons/stats': R.LessonStatsResponseSchema,
+    'post /lessons/report': R.LessonReportResponseSchema,
+    'delete /lessons/:id': R.SuccessResponseSchema,
+    'post /reconcile': R.ReconciliationResponseSchema,
+    'get /reconcile/status': R.ReconcileStatusResponseSchema,
+    'post /reset-source': R.ResetSourceResponseSchema,
+    'get /:id': R.GetMemoryResponseSchema,
+    'delete /:id': R.SuccessResponseSchema,
+    'get /audit/summary': R.MutationSummaryResponseSchema,
+    'get /audit/recent': R.AuditRecentResponseSchema,
+    'get /:id/audit': R.AuditTrailResponseSchema,
+};
+export const AGENT_RESPONSE_SCHEMAS = {
+    'put /trust': R.TrustResponseSchema,
+    'get /trust': R.TrustResponseSchema,
+    'get /conflicts': R.ConflictsListResponseSchema,
+    'put /conflicts/:id/resolve': R.ResolveConflictResponseSchema,
+    'post /conflicts/auto-resolve': R.AutoResolveConflictsResponseSchema,
+};
+export const DOCUMENT_RESPONSE_SCHEMAS = {
+    'post /': R.RegisterDocumentResponseSchema,
+    'get /': R.DocumentListRootResponseSchema,
+    'get /limits': R.DocumentLimitsResponseSchema,
+    'get /list': R.ListDocumentsResponseSchema,
+    'get /without-memories': R.DocumentListRootResponseSchema,
+    'get /passport-feed': PassportFeedResponseSchema,
+    'post /:id/index': R.IndexDocumentResponseSchema,
+    'post /:id/extraction-failure': R.DocumentFailureMarkerResponseSchema,
+    'post /:id/index-failure': R.DocumentFailureMarkerResponseSchema,
+    'put /:id/raw': R.UploadRawDocumentResponseSchema,
+    'get /:id': R.RawDocumentResponseSchema,
+    'delete /:id': R.DeleteDocumentResponseSchema,
+};
+export const STORAGE_RESPONSE_SCHEMAS = {
+    'get /capabilities': StorageCapabilitiesResponseSchema,
+    'post /artifacts': StoredArtifactResponseSchema,
+    'get /artifacts/:id': StoredArtifactResponseSchema,
+    'delete /artifacts/:id': DeleteArtifactResultSchema,
+    'post /artifacts/:id/verify': VerifyArtifactResultSchema,
+};

package/dist/routes/route-errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared error handling utilities for Express route handlers.
+ *
+ * Request-input validation is performed by the Zod-based
+ * `validateBody` / `validateQuery` / `validateParams` middleware in
+ * `src/middleware/validate.ts`, which emits 400 responses directly.
+ * Most uncaught service-layer failures stay 500. Upstream AI provider
+ * failures get a sanitized operator-facing envelope.
+ */
+import type { Response } from 'express';
+/** Log the error and send the public JSON error response. */
+export declare function handleRouteError(res: Response, context: string, err: unknown): void;

package/dist/routes/route-errors.js

@@ -0,0 +1,30 @@
+/**
+ * Shared error handling utilities for Express route handlers.
+ *
+ * Request-input validation is performed by the Zod-based
+ * `validateBody` / `validateQuery` / `validateParams` middleware in
+ * `src/middleware/validate.ts`, which emits 400 responses directly.
+ * Most uncaught service-layer failures stay 500. Upstream AI provider
+ * failures get a sanitized operator-facing envelope.
+ */
+import { classifyUpstreamProviderFailure, routeErrorMessage, } from './upstream-provider-errors.js';
+/** Log the error and send the public JSON error response. */
+export function handleRouteError(res, context, err) {
+    const internalMessage = routeErrorMessage(err);
+    const stack = err instanceof Error ? err.stack : undefined;
+    const upstream = classifyUpstreamProviderFailure(err);
+    if (upstream) {
+        console.error(`${context} error: [${upstream.status}] upstream provider ${upstream.providerStatus}: ${internalMessage}${stack ? `\n${stack}` : ''}`);
+        res.status(upstream.status).json({
+            error_code: upstream.errorCode,
+            error: upstream.error,
+            message: upstream.message,
+            provider_status: upstream.providerStatus,
+            retryable: upstream.retryable,
+            details: upstream.details,
+        });
+        return;
+    }
+    console.error(`${context} error: [500] ${internalMessage}${stack ? `\n${stack}` : ''}`);
+    res.status(500).json({ error: 'Internal server error' });
+}