@atomicmemory/core 1.0.0

package/dist/schemas/agents.js

@@ -0,0 +1,126 @@
+/**
+ * @file Zod schemas for the 5 /v1/agents/* routes.
+ *
+ * Mirrors the inline parsers at `src/routes/agents.ts:86-109`
+ * byte-for-byte:
+ *   - `requireString` accepts either a string OR an array (takes
+ *     first element via `String(value[0])`) — this handles Express
+ *     query strings with duplicate params. Throws
+ *     `"${field} is required"` on missing/non-accepted input.
+ *   - `requireTrustLevel` distinguishes type error ("trust_level must
+ *     be a number between 0.0 and 1.0") from range error
+ *     ("trust_level must be between 0.0 and 1.0").
+ *   - `requireResolution` accepts the three enum variants; anything
+ *     else throws the full list-of-valid-values message.
+ *
+ * Every error message matches the pre-refactor text exactly so HTTP
+ * clients that regex on `{ error }` continue to match.
+ */
+import { z } from './zod-setup.js';
+/**
+ * Build a schema that produces `"${label} is required"` for every
+ * failure mode the old `requireString` threw on (missing, null,
+ * non-string non-array, empty string, empty array). Successful
+ * strings pass through; arrays yield `String(value[0])`.
+ */
+function requiredStringOrArray(label) {
+    const message = `${label} is required`;
+    return z
+        .unknown()
+        .transform(v => {
+        if (typeof v === 'string')
+            return v;
+        if (Array.isArray(v) && v.length > 0)
+            return String(v[0]);
+        return undefined;
+    })
+        .refine((v) => typeof v === 'string' && v.length > 0, {
+        message,
+    })
+        .transform(v => v)
+        .openapi({ type: 'string', minLength: 1, description: `Required. ${label}.` });
+}
+const TRUST_TYPE_MESSAGE = 'trust_level must be a number between 0.0 and 1.0';
+const TRUST_RANGE_MESSAGE = 'trust_level must be between 0.0 and 1.0';
+/** Finite number in [0.0, 1.0]. Separate messages for wrong-type vs out-of-range. */
+const TrustLevelSchema = z
+    .unknown()
+    .superRefine((v, ctx) => {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        ctx.addIssue({ code: 'custom', message: TRUST_TYPE_MESSAGE });
+        return;
+    }
+    if (v < 0.0 || v > 1.0) {
+        ctx.addIssue({ code: 'custom', message: TRUST_RANGE_MESSAGE });
+    }
+})
+    .transform(v => v)
+    .openapi({
+    type: 'number',
+    minimum: 0.0,
+    maximum: 1.0,
+    description: 'Trust score in [0.0, 1.0].',
+});
+const VALID_RESOLUTIONS = ['resolved_new', 'resolved_existing', 'resolved_both'];
+const RESOLUTION_MESSAGE = 'resolution must be "resolved_new", "resolved_existing", or "resolved_both"';
+const ResolutionSchema = z
+    .unknown()
+    .refine((v) => typeof v === 'string' && VALID_RESOLUTIONS.includes(v), { message: RESOLUTION_MESSAGE })
+    .transform(v => v)
+    .openapi({
+    type: 'string',
+    enum: [...VALID_RESOLUTIONS],
+});
+// ---------------------------------------------------------------------------
+// PUT /trust
+// ---------------------------------------------------------------------------
+export const SetTrustBodySchema = z
+    .object({
+    agent_id: requiredStringOrArray('agent_id'),
+    user_id: requiredStringOrArray('user_id'),
+    trust_level: TrustLevelSchema,
+    display_name: z
+        .unknown()
+        .transform(v => (typeof v === 'string' ? v : undefined))
+        .openapi({ type: 'string' }),
+})
+    .transform(b => ({
+    agentId: b.agent_id,
+    userId: b.user_id,
+    trustLevel: b.trust_level,
+    displayName: b.display_name,
+}))
+    .openapi({
+    description: "Set the calling user's trust level for a given agent. trust_level in [0.0, 1.0].",
+});
+// ---------------------------------------------------------------------------
+// GET /trust
+// ---------------------------------------------------------------------------
+export const GetTrustQuerySchema = z
+    .object({
+    agent_id: requiredStringOrArray('agent_id'),
+    user_id: requiredStringOrArray('user_id'),
+})
+    .transform(q => ({ agentId: q.agent_id, userId: q.user_id }))
+    .openapi({ description: 'Look up the trust level for a (user, agent) pair.' });
+// ---------------------------------------------------------------------------
+// GET /conflicts  +  POST /conflicts/auto-resolve
+// ---------------------------------------------------------------------------
+export const UserIdFromQuerySchema = z
+    .object({ user_id: requiredStringOrArray('user_id') })
+    .transform(q => ({ userId: q.user_id }))
+    .openapi({ description: 'List open agent conflicts for a user.' });
+export const UserIdFromBodySchema = z
+    .object({ user_id: requiredStringOrArray('user_id') })
+    .transform(b => ({ userId: b.user_id }))
+    .openapi({ description: 'Auto-resolve expired conflicts for a user.' });
+// ---------------------------------------------------------------------------
+// PUT /conflicts/:id/resolve
+// ---------------------------------------------------------------------------
+export const ConflictIdParamSchema = z
+    .object({ id: z.string().min(1) })
+    .transform(p => ({ id: p.id }));
+export const ResolveConflictBodySchema = z
+    .object({ resolution: ResolutionSchema })
+    .transform(b => ({ resolution: b.resolution }))
+    .openapi({ description: 'Resolve a specific conflict with one of the three enum variants.' });

package/dist/schemas/common.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @file Shared Zod schemas reused across request/response bodies.
+ *
+ * All schemas author fields in **snake_case** (the wire format). The
+ * Phase-2 request schemas layer `.transform()` on top to emit the
+ * camelCase TypeScript shapes handlers expect, matching today's
+ * `parseIngestBody` / `parseSearchBody` behavior.
+ *
+ * Source-of-truth contracts:
+ *   - WorkspaceContext / AgentScope: `src/db/repository-types.ts:186-199`
+ *   - Body parsing shape:            `src/routes/memories.ts:515-628`
+ */
+import { z } from './zod-setup.js';
+export declare const MemoryVisibilitySchema: z.ZodEnum<{
+    agent_only: "agent_only";
+    restricted: "restricted";
+    workspace: "workspace";
+}>;
+export type MemoryVisibility = z.infer<typeof MemoryVisibilitySchema>;
+export declare const WorkspaceIdField: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+export declare const AgentIdField: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+export declare const VisibilityField: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"agent_only" | "restricted" | "workspace" | undefined, unknown>>;
+/**
+ * Post-transform camelCase `WorkspaceContext` output shape consumed by
+ * services. Both fields are required here because this schema
+ * represents the "workspace is active" branch of the transform;
+ * absence is expressed at the parent level as `workspace: undefined`.
+ *
+ * Matches `WorkspaceContext` in `src/db/repository-types.ts:186`.
+ */
+export declare const WorkspaceContextOutputSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    agentId: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        agent_only: "agent_only";
+        restricted: "restricted";
+        workspace: "workspace";
+    }>>;
+}, z.core.$strip>;
+export type WorkspaceContext = z.infer<typeof WorkspaceContextOutputSchema>;
+/**
+ * Agent-scope filter for workspace searches.
+ * Accepts:
+ *   - 'all' | 'self' | 'others' — enum variants
+ *   - a concrete agent_id string — filter to that agent's memories
+ *   - string[] — filter to any of the listed agent IDs
+ *
+ * ⚠️ Behavior must match `parseOptionalAgentScope`
+ * (`src/routes/memories.ts:617`): for values that are neither a
+ * string nor a string-only array, the parser returns `undefined`
+ * silently (no 400). `.catch(undefined)` preserves that tolerance so
+ * Phase 2 composition does not regress `agent_scope: 42` /
+ * `agent_scope: {}` from "ignored" to a 400.
+ */
+export declare const AgentScopeSchema: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | string[] | undefined, unknown>>;
+export type AgentScopeInput = z.infer<typeof AgentScopeSchema>;
+/** Retrieval mode enum for POST /v1/memories/search body.retrieval_mode. */
+export declare const RetrievalModeSchema: z.ZodEnum<{
+    flat: "flat";
+    tiered: "tiered";
+    "abstract-aware": "abstract-aware";
+}>;
+export type RetrievalMode = z.infer<typeof RetrievalModeSchema>;
+/**
+ * Required string field — truthy string, no trimming. Exactly matches
+ * the contract of `requireBodyString` (`src/routes/memories.ts:571`):
+ *
+ * ```ts
+ * if (!value || typeof value !== 'string') throw new InputError(message);
+ * return value;
+ * ```
+ *
+ * Note the absence of a trim: today's handlers pass through leading /
+ * trailing whitespace, and "   " (whitespace-only) is truthy so it
+ * succeeds the current check. This schema preserves that exact
+ * behavior — do not add `.trim()` or a whitespace-only rejection here.
+ */
+export declare const NonEmptyString: z.ZodString;
+/**
+ * Matches `optionalBodyString` (memories.ts:576): `typeof v === 'string'
+ * ? v : undefined`. Preserves empty string verbatim — callers may
+ * distinguish `""` from `undefined` downstream (e.g. search filters).
+ *
+ * Shared between every Zod request schema that accepts an optional
+ * string body field; do not redefine in resource-specific schema files.
+ */
+export declare const OptionalBodyString: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+/**
+ * Build a schema that produces the exact error message
+ * `"${label} (string) is required"` for every failure mode that
+ * `requireBodyString` threw on (missing, null, wrong type, empty
+ * string). Preserves wire-contract text clients may match against.
+ *
+ * Shared between every Zod request schema that requires a non-empty
+ * string body field; do not redefine in resource-specific schema files.
+ */
+export declare function requiredStringBody(label: string): z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+/**
+ * ISO-8601 timestamp accepted as a plain string on the wire. The
+ * memories/search route parses this via `parseOptionalIsoTimestamp`
+ * (`src/routes/memories.ts:641`):
+ *   - `undefined`, `null`, or `''` → treated as absent (no 400).
+ *   - Any other non-string or unparseable string → 400.
+ *   - Parseable string → passed through unchanged.
+ *
+ * Preprocess strips the empty-string / null sentinels before the
+ * string+date check so composing `IsoTimestamp` into a route body
+ * preserves the "empty means absent" contract exactly.
+ */
+export declare const IsoTimestamp: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;

package/dist/schemas/common.js

@@ -0,0 +1,190 @@
+/**
+ * @file Shared Zod schemas reused across request/response bodies.
+ *
+ * All schemas author fields in **snake_case** (the wire format). The
+ * Phase-2 request schemas layer `.transform()` on top to emit the
+ * camelCase TypeScript shapes handlers expect, matching today's
+ * `parseIngestBody` / `parseSearchBody` behavior.
+ *
+ * Source-of-truth contracts:
+ *   - WorkspaceContext / AgentScope: `src/db/repository-types.ts:186-199`
+ *   - Body parsing shape:            `src/routes/memories.ts:515-628`
+ */
+import { z } from './zod-setup.js';
+export const MemoryVisibilitySchema = z
+    .enum(['agent_only', 'restricted', 'workspace'])
+    .openapi({
+    description: 'Write-time visibility label controlling which agents in a workspace can read the memory.',
+});
+/**
+ * Request-body-level schema for the three top-level workspace fields
+ * (`workspace_id`, `agent_id`, `visibility`).
+ *
+ * ⚠️ Behavior must match `parseOptionalWorkspaceContext`
+ * (`src/routes/memories.ts:601-615`). Current parser calls
+ * `optionalBodyString`, which returns the value unchanged when it is
+ * a string and `undefined` otherwise — it **never 400s**. Then the
+ * parser treats missing `workspace_id` / `agent_id` (including empty
+ * string, which fails the `!workspaceId` truthy check) as "no
+ * workspace context" and falls back to user scope.
+ *
+ * Both field schemas therefore silently coerce any invalid or empty
+ * value to `undefined` via `.catch(undefined)`. Phase 2's route
+ * schemas compose these as top-level body fields and run a transform
+ * that emits the internal {@link WorkspaceContext} camelCase shape
+ * only when both are non-empty strings.
+ */
+// These use `.unknown().transform(...)` rather than `.optional().catch()`
+// because zod-to-openapi's traversal fails on ZodCatch nodes. The
+// runtime semantics are identical (non-string / empty → undefined).
+const VALID_VISIBILITIES = ['agent_only', 'restricted', 'workspace'];
+export const WorkspaceIdField = z
+    .unknown()
+    .transform(v => (typeof v === 'string' && v.length > 0 ? v : undefined))
+    .openapi({
+    type: 'string',
+    description: 'Optional workspace identifier. Silently dropped if empty / non-string.',
+});
+export const AgentIdField = z
+    .unknown()
+    .transform(v => (typeof v === 'string' && v.length > 0 ? v : undefined))
+    .openapi({
+    type: 'string',
+    description: 'Optional agent identifier. Silently dropped if empty / non-string.',
+});
+export const VisibilityField = z
+    .unknown()
+    .transform(v => typeof v === 'string' && VALID_VISIBILITIES.includes(v)
+    ? v
+    : undefined)
+    .openapi({
+    type: 'string',
+    enum: VALID_VISIBILITIES,
+    description: 'Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined.',
+});
+/**
+ * Post-transform camelCase `WorkspaceContext` output shape consumed by
+ * services. Both fields are required here because this schema
+ * represents the "workspace is active" branch of the transform;
+ * absence is expressed at the parent level as `workspace: undefined`.
+ *
+ * Matches `WorkspaceContext` in `src/db/repository-types.ts:186`.
+ */
+export const WorkspaceContextOutputSchema = z
+    .object({
+    workspaceId: z.string().min(1),
+    agentId: z.string().min(1),
+    visibility: MemoryVisibilitySchema.optional(),
+})
+    .openapi({
+    description: 'Internal workspace-scope context. Emitted by request-body transforms when both workspace_id and agent_id are present on the wire.',
+});
+/**
+ * Agent-scope filter for workspace searches.
+ * Accepts:
+ *   - 'all' | 'self' | 'others' — enum variants
+ *   - a concrete agent_id string — filter to that agent's memories
+ *   - string[] — filter to any of the listed agent IDs
+ *
+ * ⚠️ Behavior must match `parseOptionalAgentScope`
+ * (`src/routes/memories.ts:617`): for values that are neither a
+ * string nor a string-only array, the parser returns `undefined`
+ * silently (no 400). `.catch(undefined)` preserves that tolerance so
+ * Phase 2 composition does not regress `agent_scope: 42` /
+ * `agent_scope: {}` from "ignored" to a 400.
+ */
+export const AgentScopeSchema = z
+    .unknown()
+    .transform(v => {
+    if (typeof v === 'string')
+        return v;
+    if (Array.isArray(v) && v.every((x) => typeof x === 'string')) {
+        return v;
+    }
+    return undefined;
+})
+    .openapi({
+    description: "Agent-scope filter for workspace searches. String literal 'all' | 'self' | 'others' or a concrete agent_id. Array of agent_ids is also accepted. Any other value is silently ignored.",
+    example: 'all',
+    oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+});
+/** Retrieval mode enum for POST /v1/memories/search body.retrieval_mode. */
+export const RetrievalModeSchema = z
+    .enum(['flat', 'tiered', 'abstract-aware'])
+    .openapi({
+    description: 'Retrieval pipeline mode. Defaults to flat when omitted.',
+});
+/**
+ * Required string field — truthy string, no trimming. Exactly matches
+ * the contract of `requireBodyString` (`src/routes/memories.ts:571`):
+ *
+ * ```ts
+ * if (!value || typeof value !== 'string') throw new InputError(message);
+ * return value;
+ * ```
+ *
+ * Note the absence of a trim: today's handlers pass through leading /
+ * trailing whitespace, and "   " (whitespace-only) is truthy so it
+ * succeeds the current check. This schema preserves that exact
+ * behavior — do not add `.trim()` or a whitespace-only rejection here.
+ */
+export const NonEmptyString = z.string().min(1, 'must be a non-empty string');
+/**
+ * Matches `optionalBodyString` (memories.ts:576): `typeof v === 'string'
+ * ? v : undefined`. Preserves empty string verbatim — callers may
+ * distinguish `""` from `undefined` downstream (e.g. search filters).
+ *
+ * Shared between every Zod request schema that accepts an optional
+ * string body field; do not redefine in resource-specific schema files.
+ */
+export const OptionalBodyString = z
+    .unknown()
+    .transform(v => (typeof v === 'string' ? v : undefined))
+    .openapi({ type: 'string' });
+/**
+ * Build a schema that produces the exact error message
+ * `"${label} (string) is required"` for every failure mode that
+ * `requireBodyString` threw on (missing, null, wrong type, empty
+ * string). Preserves wire-contract text clients may match against.
+ *
+ * Shared between every Zod request schema that requires a non-empty
+ * string body field; do not redefine in resource-specific schema files.
+ */
+export function requiredStringBody(label) {
+    const message = `${label} (string) is required`;
+    return z
+        .unknown()
+        .refine((v) => typeof v === 'string' && v.length > 0, {
+        message,
+    })
+        .transform(v => v)
+        .openapi({ type: 'string', minLength: 1, description: `Required. ${label}.` });
+}
+/**
+ * ISO-8601 timestamp accepted as a plain string on the wire. The
+ * memories/search route parses this via `parseOptionalIsoTimestamp`
+ * (`src/routes/memories.ts:641`):
+ *   - `undefined`, `null`, or `''` → treated as absent (no 400).
+ *   - Any other non-string or unparseable string → 400.
+ *   - Parseable string → passed through unchanged.
+ *
+ * Preprocess strips the empty-string / null sentinels before the
+ * string+date check so composing `IsoTimestamp` into a route body
+ * preserves the "empty means absent" contract exactly.
+ */
+export const IsoTimestamp = z
+    .unknown()
+    .superRefine((v, ctx) => {
+    if (v === undefined || v === null || v === '')
+        return;
+    if (typeof v !== 'string' || Number.isNaN(Date.parse(v))) {
+        ctx.addIssue({ code: 'custom', message: 'as_of must be a valid ISO timestamp' });
+    }
+})
+    .transform(v => v === undefined || v === null || v === '' ? undefined : v)
+    .openapi({
+    type: 'string',
+    format: 'date-time',
+    description: 'ISO-8601 timestamp accepted by temporal search (as_of). Empty string or null means absent; any other non-ISO value is rejected with 400.',
+    example: '2026-01-15T12:00:00Z',
+});

package/dist/schemas/document-list-responses.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file cursor-list — focused response schemas for the cursor-paginated
+ *       document list / recovery / passport-feed endpoints.
+ *
+ * Split out from `schemas/responses.ts` (already at 456 non-comment
+ * LOC) so adding the cursor-list Slice 3 surface doesn't push the
+ * shared response-schema file further over the workspace's 400 LOC
+ * rule. The validate-response middleware imports these by name via
+ * `routes/response-schema-map.ts`.
+ *
+ * Wire format is snake_case end-to-end. The discriminated union on
+ * `kind` is the public shape — internal columns (embeddings, audit
+ * fields, internal metadata) are deliberately absent.
+ */
+import { z } from './zod-setup.js';
+export declare const PassportFeedResponseSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"document_grouped">;
+        document_id: z.ZodString;
+        sort_at: z.ZodString;
+        sort_id: z.ZodString;
+        representative: z.ZodObject<{
+            id: z.ZodString;
+            content: z.ZodString;
+            created_at: z.ZodString;
+            source_site: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        chunk_count: z.ZodNumber;
+        raw_storage_status: 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";
+        }>;
+        extraction_status: z.ZodEnum<{
+            pending: "pending";
+            not_required: "not_required";
+            running: "running";
+            complete: "complete";
+            unsupported: "unsupported";
+            failed: "failed";
+        }>;
+        semantic_index_status: z.ZodEnum<{
+            pending: "pending";
+            not_required: "not_required";
+            running: "running";
+            complete: "complete";
+            failed: "failed";
+            stale: "stale";
+        }>;
+        last_error: 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>>;
+        display_name: z.ZodNullable<z.ZodString>;
+        mime_type: z.ZodNullable<z.ZodString>;
+        storage_provider: z.ZodNullable<z.ZodString>;
+        raw_storage_metadata: z.ZodObject<{
+            codec: z.ZodOptional<z.ZodObject<{
+                name: z.ZodEnum<{
+                    none: "none";
+                    aes_gcm: "aes_gcm";
+                }>;
+                version: z.ZodNumber;
+            }, z.core.$strict>>;
+            filecoin: z.ZodOptional<z.ZodObject<{
+                ipfs_cid: z.ZodOptional<z.ZodString>;
+                piece_cid: z.ZodOptional<z.ZodString>;
+                copy_count: z.ZodOptional<z.ZodNumber>;
+                provider_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                copy_statuses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        delete_semantics: z.ZodNullable<z.ZodEnum<{
+            delete: "delete";
+            unpin: "unpin";
+            tombstone: "tombstone";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"standalone_memory">;
+        sort_at: z.ZodString;
+        sort_id: z.ZodString;
+        memory: z.ZodObject<{
+            id: z.ZodString;
+            content: z.ZodString;
+            created_at: z.ZodString;
+            source_site: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "kind">>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;

package/dist/schemas/document-list-responses.js

@@ -0,0 +1,87 @@
+/**
+ * @file cursor-list — focused response schemas for the cursor-paginated
+ *       document list / recovery / passport-feed endpoints.
+ *
+ * Split out from `schemas/responses.ts` (already at 456 non-comment
+ * LOC) so adding the cursor-list Slice 3 surface doesn't push the
+ * shared response-schema file further over the workspace's 400 LOC
+ * rule. The validate-response middleware imports these by name via
+ * `routes/response-schema-map.ts`.
+ *
+ * Wire format is snake_case end-to-end. The discriminated union on
+ * `kind` is the public shape — internal columns (embeddings, audit
+ * fields, internal metadata) are deliberately absent.
+ */
+import { z } from './zod-setup.js';
+import { ExtractionStatusEnumSchema, LastErrorEnvelopeSchema, RawStorageStatusEnumSchema, SemanticIndexStatusEnumSchema, } from './document-status-envelope.js';
+import { DeleteSemanticsEnumSchema, PublicRawStorageMetadataSchema, } from './document-response-schemas.js';
+/**
+ * cursor-list — public passport-feed representative subset. Mirrors the
+ * fields a UI list-row card needs (id / content / created_at /
+ * source_site) without exposing embeddings, internal metadata, or
+ * soft-delete flags.
+ */
+const PassportFeedRepresentativeSchema = z.object({
+    id: z.string(),
+    content: z.string(),
+    created_at: z.string(),
+    source_site: z.string().nullable(),
+});
+/**
+ * cursor-list — `document_grouped` row: one per documentId-with-memories.
+ * Carries the chunk_count + the latest chunk as `representative` +
+ * the status-layer status envelope joined from `raw_documents`.
+ */
+const PassportFeedDocumentGroupedRowSchema = z.object({
+    kind: z.literal('document_grouped'),
+    document_id: z.string(),
+    sort_at: z.string(),
+    sort_id: z.string(),
+    representative: PassportFeedRepresentativeSchema,
+    chunk_count: z.number().int().nonnegative(),
+    raw_storage_status: RawStorageStatusEnumSchema,
+    extraction_status: ExtractionStatusEnumSchema,
+    semantic_index_status: SemanticIndexStatusEnumSchema,
+    last_error: LastErrorEnvelopeSchema,
+    display_name: z.string().nullable(),
+    mime_type: z.string().nullable(),
+    // public wire widening (public contract): grouped rows now carry
+    // `storage_provider` + the redacted `raw_storage_metadata` +
+    // per-row `delete_semantics` so the webapp can render
+    // provider-aware UI (CID chip, capability-driven delete copy)
+    // without an extra GET. Standalone-memory rows stay status-only.
+    storage_provider: z.string().nullable(),
+    raw_storage_metadata: PublicRawStorageMetadataSchema,
+    delete_semantics: DeleteSemanticsEnumSchema,
+});
+/**
+ * cursor-list — `standalone_memory` row: 1:1 the underlying memory
+ * (raw_document_id IS NULL). No status envelope (there is no
+ * document) and no `chunk_count` on the wire — the public shape
+ * exposes the memory verbatim so consumers branch on `kind`
+ * instead of trying to render the two row kinds with the same
+ * field set.
+ */
+const PassportFeedStandaloneMemoryRowSchema = z.object({
+    kind: z.literal('standalone_memory'),
+    sort_at: z.string(),
+    sort_id: z.string(),
+    memory: PassportFeedRepresentativeSchema,
+});
+const PassportFeedRowSchema = z
+    .discriminatedUnion('kind', [
+    PassportFeedDocumentGroupedRowSchema,
+    PassportFeedStandaloneMemoryRowSchema,
+])
+    .openapi({ description: 'Passport-feed row (document_grouped or standalone_memory).' });
+export const PassportFeedResponseSchema = z
+    .object({
+    rows: z.array(PassportFeedRowSchema),
+    next_cursor: z.string().nullable(),
+})
+    .openapi({
+    description: 'Passport feed: grouped memory-backed document rows + ' +
+        '1:1 standalone memory rows, unioned and ordered by ' +
+        '(sort_at DESC, sort_id DESC). `next_cursor` is the opaque ' +
+        'continuation cursor; null indicates the stream is exhausted.',
+});