@atomicmemory/core 1.0.0

package/dist/schemas/memories.d.ts

@@ -0,0 +1,378 @@
+/**
+ * @file Zod schemas for every /v1/memories/* route.
+ *
+ * Each request body schema authors fields in **snake_case** (the wire
+ * format) and `.transform()`s to a camelCase output consumed by
+ * handlers. The output shape of each schema was chosen to drop-in
+ * replace the value previously returned by `parseIngestBody` /
+ * `parseSearchBody` etc. so handler bodies don't change.
+ *
+ * ⚠️ Behavior-preservation invariants worth noting:
+ *   - `requireBodyString` rejects empty string AND non-string with
+ *     the same 400 message. `requiredStringBody(label)` below emits
+ *     the exact "${label} (string) is required" text for every
+ *     failure mode (missing, null, wrong type, empty).
+ *   - `parseOptionalWorkspaceContext` / `parseOptionalAgentScope`
+ *     NEVER 400 on invalid shapes — they silently drop to undefined.
+ *     Composition here uses the `.catch(undefined)` primitives from
+ *     `./common`.
+ *   - `parseOptionalIsoTimestamp` treats `''` and `null` as absent,
+ *     rejects other invalid strings. `IsoTimestamp` in `./common`
+ *     preserves that with a preprocess step.
+ *   - `retrieval_mode` absence is silent (undefined), invalid values
+ *     throw the exact message from memories.ts:553-555.
+ *   - `token_budget` must be a finite number in [100, 50000], floored
+ *     on success. Matches memories.ts:560-568.
+ *   - `limit` on POST /search / /search/fast bodies: non-number yields
+ *     undefined (not an error); number is clamped to
+ *     [1, MAX_SEARCH_LIMIT=100] and floored. Matches memories.ts:629-632.
+ *   - `conversation` max length = 100_000 chars. Over the limit
+ *     throws 'conversation exceeds max length of 100000 characters'.
+ *
+ * Source: `src/routes/memories.ts:515-647` (the inline parsers this
+ * file replaces).
+ */
+import { z } from './zod-setup.js';
+/**
+ * Per-request overlay on the startup RuntimeConfig. Applied as a shallow
+ * merge (`{ ...startup, ...override }`) onto the effective request-scope
+ * config.
+ *
+ * **Shape is permissive by design.** The schema accepts any object whose
+ * values are primitives (boolean, number, string, null) — no
+ * enumerated field list. This is deliberate: enumerating fields would
+ * couple every new overlay-eligible RuntimeConfig field to a core
+ * release, which defeats the purpose of a per-request config mechanism.
+ *
+ * **Unknown-key handling is soft**, not a 400:
+ * - If an override key doesn't match a `RuntimeConfig` field at
+ *   request-handling time, the merge is still performed (the key rides
+ *   along on the effective config object), but the route handler emits
+ *   a `X-Atomicmem-Unknown-Override-Keys` response header listing the
+ *   unmatched keys and logs a warning. This catches typos without
+ *   rejecting a request that would otherwise be valid once the field
+ *   lands in a future release.
+ * - If you want a typed, IDE-autocompleted experience, import
+ *   `RuntimeConfig` from `src/config.ts` and type your override as
+ *   `Partial<RuntimeConfig>` on the caller side.
+ *
+ * **`config_override` absent →** zero-cost path, no headers emitted,
+ * startup config used as-is.
+ */
+export declare const ConfigOverrideSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>>;
+/**
+ * Runtime type of the validated override object. For IDE-assisted
+ * editing, prefer `Partial<RuntimeConfig>` from `src/config.ts`.
+ */
+export type ConfigOverride = z.infer<typeof ConfigOverrideSchema>;
+export declare const IngestBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    conversation: 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>>;
+    source_url: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    workspace_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    agent_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    visibility: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"agent_only" | "restricted" | "workspace" | undefined, unknown>>;
+    skip_extraction: z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>;
+    config_override: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    conversation: string;
+    sourceSite: string;
+    sourceUrl: string;
+    workspace: {
+        workspaceId: string;
+        agentId: string;
+        visibility?: "agent_only" | "restricted" | "workspace" | undefined;
+    } | undefined;
+    skipExtraction: boolean;
+    configOverride: Record<string, string | number | boolean | null> | undefined;
+    metadata: Record<string, unknown> | undefined;
+}, {
+    user_id: string;
+    conversation: string;
+    source_site: string;
+    source_url: string | undefined;
+    workspace_id: string | undefined;
+    agent_id: string | undefined;
+    visibility: "agent_only" | "restricted" | "workspace" | undefined;
+    skip_extraction: boolean | undefined;
+    config_override?: Record<string, string | number | boolean | null> | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>>;
+export type IngestBody = z.infer<typeof IngestBodySchema>;
+export declare const SearchBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    query: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    source_site: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    limit: z.ZodPipe<z.ZodPipe<z.ZodTransform<number | undefined, unknown>, z.ZodOptional<z.ZodNumber>>, z.ZodTransform<number | undefined, number | undefined>>;
+    as_of: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    retrieval_mode: z.ZodPipe<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodUnknown>>, z.ZodTransform<"flat" | "tiered" | "abstract-aware" | undefined, unknown>>;
+    token_budget: z.ZodPipe<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodUnknown>> & z.ZodType<number | undefined, unknown, z.core.$ZodTypeInternals<number | undefined, unknown>>, z.ZodTransform<number | undefined, number | undefined>>;
+    threshold: z.ZodPipe<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodUnknown>> & z.ZodType<number | undefined, unknown, z.core.$ZodTypeInternals<number | undefined, unknown>>, z.ZodTransform<number | undefined, number | undefined>>;
+    namespace_scope: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    skip_repair: z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>;
+    workspace_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    agent_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    visibility: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"agent_only" | "restricted" | "workspace" | undefined, unknown>>;
+    agent_scope: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | string[] | undefined, unknown>>;
+    config_override: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    query: string;
+    sourceSite: string | undefined;
+    limit: number | undefined;
+    asOf: string | undefined;
+    retrievalMode: "flat" | "tiered" | "abstract-aware" | undefined;
+    tokenBudget: number | undefined;
+    relevanceThreshold: number | undefined;
+    namespaceScope: string | undefined;
+    skipRepair: boolean;
+    workspace: {
+        workspaceId: string;
+        agentId: string;
+        visibility?: "agent_only" | "restricted" | "workspace" | undefined;
+    } | undefined;
+    agentScope: string | string[] | undefined;
+    configOverride: Record<string, string | number | boolean | null> | undefined;
+}, {
+    user_id: string;
+    query: string;
+    source_site: string | undefined;
+    limit: number | undefined;
+    as_of: string | undefined;
+    retrieval_mode: "flat" | "tiered" | "abstract-aware" | undefined;
+    token_budget: number | undefined;
+    threshold: number | undefined;
+    namespace_scope: string | undefined;
+    skip_repair: boolean | undefined;
+    workspace_id: string | undefined;
+    agent_id: string | undefined;
+    visibility: "agent_only" | "restricted" | "workspace" | undefined;
+    agent_scope: string | string[] | undefined;
+    config_override?: Record<string, string | number | boolean | null> | undefined;
+}>>;
+export type SearchBody = z.infer<typeof SearchBodySchema>;
+export declare const ExpandBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    memory_ids: z.ZodPipe<z.ZodUnknown & z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>, z.ZodTransform<string[], string[]>>;
+    workspace_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    agent_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    visibility: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"agent_only" | "restricted" | "workspace" | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    memoryIds: string[];
+    workspace: {
+        workspaceId: string;
+        agentId: string;
+        visibility?: "agent_only" | "restricted" | "workspace" | undefined;
+    } | undefined;
+}, {
+    user_id: string;
+    memory_ids: string[];
+    workspace_id: string | undefined;
+    agent_id: string | undefined;
+    visibility: "agent_only" | "restricted" | "workspace" | undefined;
+}>>;
+export type ExpandBody = z.infer<typeof ExpandBodySchema>;
+export declare const VerifyBodySchema: z.ZodPipe<z.ZodObject<{
+    question: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    context: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    candidate_answer: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+}, z.core.$strip>, z.ZodTransform<{
+    question: string;
+    context: string;
+    candidateAnswer: string;
+}, {
+    question: string;
+    context: string;
+    candidate_answer: string;
+}>>;
+export type VerifyBody = z.infer<typeof VerifyBodySchema>;
+export declare const ConsolidateBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    execute: z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    execute: boolean;
+}, {
+    user_id: string;
+    execute: boolean | undefined;
+}>>;
+export type ConsolidateBody = z.infer<typeof ConsolidateBodySchema>;
+export declare const DecayBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    dry_run: z.ZodPipe<z.ZodUnknown, z.ZodTransform<boolean | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    dryRun: boolean;
+}, {
+    user_id: string;
+    dry_run: boolean | undefined;
+}>>;
+export type DecayBody = z.infer<typeof DecayBodySchema>;
+export declare const ReconcileBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string | undefined;
+}, {
+    user_id: string | undefined;
+}>>;
+export type ReconcileBody = z.infer<typeof ReconcileBodySchema>;
+export declare const ResetSourceBodySchema: 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>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    sourceSite: string;
+}, {
+    user_id: string;
+    source_site: string;
+}>>;
+export type ResetSourceBody = z.infer<typeof ResetSourceBodySchema>;
+export declare const LessonReportBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    pattern: z.ZodPipe<z.ZodUnknown & z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>, z.ZodTransform<string, string>>;
+    source_memory_ids: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string[], unknown>>;
+    severity: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    pattern: string;
+    sourceMemoryIds: string[];
+    severity: unknown;
+}, {
+    user_id: string;
+    pattern: string;
+    source_memory_ids: string[];
+    severity?: unknown;
+}>>;
+export type LessonReportBody = z.infer<typeof LessonReportBodySchema>;
+export declare const UserIdQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+}, {
+    user_id: string;
+}>>;
+export type UserIdQuery = z.infer<typeof UserIdQuerySchema>;
+/** Auto-converts limit to number with default; matches parseUserIdAndLimit. */
+export declare const UserIdLimitQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    limit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    limit: number;
+}, {
+    user_id: string;
+    limit?: string | undefined;
+}>>;
+export type UserIdLimitQuery = z.infer<typeof UserIdLimitQuerySchema>;
+export declare const ListQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    limit: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodString>;
+    workspace_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    agent_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    source_site: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    episode_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    limit: number;
+    offset: number;
+    workspaceId: string | undefined;
+    agentId: string | undefined;
+    sourceSite: string | undefined;
+    episodeId: string | undefined;
+}, {
+    user_id: string;
+    workspace_id: string | undefined;
+    agent_id: string | undefined;
+    source_site: string | undefined;
+    episode_id: string | undefined;
+    limit?: string | undefined;
+    offset?: string | undefined;
+}>>;
+export type ListQuery = z.infer<typeof ListQuerySchema>;
+/** Used by GET /:id and DELETE /:id. Same workspace-requires-agent rule. */
+export declare const MemoryByIdQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    workspace_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+    agent_id: z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    workspaceId: string | undefined;
+    agentId: string | undefined;
+}, {
+    user_id: string;
+    workspace_id: string | undefined;
+    agent_id: string | undefined;
+}>>;
+export type MemoryByIdQuery = z.infer<typeof MemoryByIdQuerySchema>;
+/**
+ * Query for `GET /v1/memories/event-chains`. Accepts a comma-separated list
+ * of entity UUIDs and returns the per-entity ordered event chain.
+ * `entity_ids` is parsed as comma-separated, trimmed, deduplicated; empty
+ * tokens skipped. At least one valid UUID required, capped at
+ * MAX_ENTITY_IDS_PER_REQUEST entries.
+ */
+export declare const EventChainsQuerySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    entity_ids: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    entityIds: string[];
+}, {
+    user_id: string;
+    entity_ids: string;
+}>>;
+export type EventChainsQuery = z.infer<typeof EventChainsQuerySchema>;
+/**
+ * Body for `POST /v1/memories/first-mentions/extract`. Accepts the full
+ * conversation transcript plus a turn-id-to-memory-id mapping (the harness
+ * provides this — the in-core ingest pipeline does not retain turn
+ * structure). The service runs a single LLM call to identify chronological
+ * topic-introduction events and persists them.
+ */
+export declare const FirstMentionsExtractBodySchema: z.ZodPipe<z.ZodObject<{
+    user_id: z.ZodString;
+    conversation_text: z.ZodString;
+    source_site: z.ZodString;
+    memory_ids_by_turn_id: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    userId: string;
+    conversationText: string;
+    sourceSite: string;
+    memoryIdsByTurnId: Map<number, string>;
+}, {
+    user_id: string;
+    conversation_text: string;
+    source_site: string;
+    memory_ids_by_turn_id: Record<string, string>;
+}>>;
+export type FirstMentionsExtractBody = z.infer<typeof FirstMentionsExtractBodySchema>;
+export declare const UuidIdParamSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    id: string;
+}, {
+    id: string;
+}>>;
+export type UuidIdParam = z.infer<typeof UuidIdParamSchema>;
+/** Non-UUID :id used by DELETE /lessons/:id (lessonId is a free string). */
+export declare const FreeIdParamSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodTransform<{
+    id: string;
+}, {
+    id: string;
+}>>;
+export type FreeIdParam = z.infer<typeof FreeIdParamSchema>;
+/**
+ * PUT /config body is intentionally loose: the handler enforces the
+ * startup-only-fields + 410 checks. We expose the body as an open
+ * object so the 410-first-check-then-reject-then-apply flow stays in
+ * the handler where it belongs.
+ */
+export declare const ConfigBodySchema: z.ZodObject<{}, z.core.$loose>;
+export type ConfigBody = z.infer<typeof ConfigBodySchema>;