@stacklink/sdk 0.2.0

package/dist/src/domain/memory-contract.js

@@ -0,0 +1,931 @@
+import { z } from 'zod';
+export const memorySubjectTypes = [
+    'user',
+    'agent',
+    'tenant',
+    'run',
+    'application',
+    'custom',
+];
+export const memoryRecordKinds = [
+    'fact',
+    'episode',
+    'profile_item',
+    'block',
+];
+export const memoryAutomaticRecordKinds = [
+    'fact',
+    'episode',
+];
+export const memoryTypes = [
+    'preference',
+    'decision',
+    'commitment',
+    'goal',
+    'constraint',
+    'relationship',
+    'durable_fact',
+];
+export const memorySensitivityClasses = [
+    'standard',
+    'personal',
+    'restricted',
+    'secret',
+];
+export const memoryRestrictedDataClasses = [
+    'health',
+    'biometric',
+    'government_identity',
+    'precise_location',
+    'protected_trait',
+    'minor',
+    'detailed_personal_financial',
+];
+export const memoryRecordStates = [
+    'current',
+    'conflicted',
+    'forgotten',
+];
+export const memoryRecallableRecordStates = [
+    'current',
+    'conflicted',
+];
+export const memoryRelationTypes = [
+    'derived_from',
+    'supersedes',
+    'contradicts',
+    'supports',
+    'related_to',
+];
+export const memorySourceKinds = [
+    'direct',
+    'conversation',
+    'document',
+    'provider',
+    'tool_execution',
+    'artifact',
+];
+export const memorySubjectRefSchema = z.object({
+    type: z.enum(memorySubjectTypes),
+    externalId: z.string().trim().min(1).max(220),
+}).strict();
+export const memoryConsentProofSchema = z.object({
+    status: z.literal('granted'),
+    basis: z.enum(['user_consent', 'contract', 'legitimate_interest', 'project_policy']),
+    recordedAt: z.string().datetime(),
+    reference: z.string().trim().min(1).max(500).optional(),
+}).strict();
+export const memoryConsentPolicySchema = z.object({
+    mode: z.enum(['project_policy', 'required']).default('project_policy'),
+}).passthrough();
+export const memoryTenantSelectorSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+}).superRefine((value, ctx) => {
+    const supplied = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (supplied.length !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide exactly one of tenantId, externalTenantId, or sessionId.',
+        });
+    }
+});
+const memoryTemporalFieldsShape = {
+    occurredAt: z.string().datetime().optional(),
+    validFrom: z.string().datetime().optional(),
+    validTo: z.string().datetime().optional(),
+};
+export const memoryIngestInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+    subjects: z.array(memorySubjectRefSchema).min(1).max(20).optional(),
+    mode: z.enum(['exact', 'extract']).default('exact'),
+    kind: z.enum(memoryRecordKinds).default('fact'),
+    content: z.string().trim().min(1).max(10_000_000),
+    title: z.string().trim().min(1).max(260).optional(),
+    memoryType: z.enum(memoryTypes).default('durable_fact'),
+    sensitivityClass: z.enum(memorySensitivityClasses).default('standard'),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length).default([]),
+    topicTags: z.array(z.string().trim().min(1).max(120)).max(50).default([]),
+    language: z.string().trim().min(1).max(80).optional(),
+    source: z.object({
+        kind: z.enum(memorySourceKinds).default('direct'),
+        externalId: z.string().trim().min(1).max(320).optional(),
+        providerKey: z.string().trim().min(1).max(120).optional(),
+        connectedAccountId: z.string().uuid().optional(),
+        resourceType: z.string().trim().min(1).max(120).optional(),
+        resourceId: z.string().trim().min(1).max(320).optional(),
+        toolExecutionId: z.string().uuid().optional(),
+        applicationKey: z.string().trim().min(1).max(160).optional(),
+    }).strict().default({ kind: 'direct' }),
+    idempotencyKey: z.string().trim().min(1).max(240).optional(),
+    policyKey: z.string().trim().min(1).max(120).optional(),
+    consent: memoryConsentProofSchema.optional(),
+    metadata: z.record(z.unknown()).default({}),
+    ...memoryTemporalFieldsShape,
+}).superRefine((value, ctx) => {
+    const selectors = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (selectors.length !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide exactly one of tenantId, externalTenantId, or sessionId.',
+        });
+    }
+    if (!value.sessionId && (!value.subjects || value.subjects.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['subjects'],
+            message: 'subjects are required when sessionId is not supplied.',
+        });
+    }
+    validateMemorySensitivity(value, ctx);
+    validateTemporalInterval(value, ctx);
+});
+const memoryRichInputSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('file'),
+        filename: z.string().trim().min(1).max(260),
+        mediaType: z.string().trim().min(1).max(160),
+        dataBase64: z.string().min(1).max(35_000_000),
+    }).strict(),
+    z.object({
+        type: z.literal('url'),
+        url: z.string().url().max(4_000),
+    }).strict(),
+]);
+export const memoryRichIngestInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+    subjects: z.array(memorySubjectRefSchema).min(1).max(20).optional(),
+    mode: z.enum(['exact', 'extract']).default('extract'),
+    kind: z.enum(memoryRecordKinds).default('episode'),
+    input: memoryRichInputSchema,
+    title: z.string().trim().min(1).max(260).optional(),
+    memoryType: z.enum(memoryTypes).default('durable_fact'),
+    sensitivityClass: z.enum(memorySensitivityClasses).default('standard'),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length).default([]),
+    topicTags: z.array(z.string().trim().min(1).max(120)).max(50).default([]),
+    language: z.string().trim().min(1).max(80).optional(),
+    idempotencyKey: z.string().trim().min(1).max(240).optional(),
+    policyKey: z.string().trim().min(1).max(120).optional(),
+    consent: memoryConsentProofSchema.optional(),
+    metadata: z.record(z.unknown()).default({}),
+    ...memoryTemporalFieldsShape,
+}).superRefine((value, ctx) => {
+    const selectors = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (selectors.length !== 1) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant or session selector.' });
+    }
+    if (!value.sessionId && (!value.subjects || value.subjects.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['subjects'],
+            message: 'subjects are required when sessionId is not supplied.',
+        });
+    }
+    validateMemorySensitivity(value, ctx);
+    validateTemporalInterval(value, ctx);
+});
+const memoryReadInputShape = {
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+    subjects: z.array(memorySubjectRefSchema).min(1).max(20).optional(),
+    query: z.string().trim().min(1).max(20_000),
+    kinds: z.array(z.enum(memoryRecordKinds)).max(memoryRecordKinds.length).optional(),
+    memoryTypes: z.array(z.enum(memoryTypes)).max(memoryTypes.length).optional(),
+    providerKeys: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
+    sourceFamilyKeys: z.array(z.string().trim().min(1).max(180)).max(50).optional(),
+    connectedAccountIds: z.array(z.string().uuid()).max(50).optional(),
+    resourceTypes: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
+    resourceIds: z.array(z.string().trim().min(1).max(320)).max(1000).optional(),
+    states: z.array(z.enum(memoryRecallableRecordStates))
+        .max(memoryRecallableRecordStates.length)
+        .default(['current', 'conflicted']),
+    validAt: z.string().datetime().optional(),
+    recordedAt: z.string().datetime().optional(),
+    includeGraph: z.boolean().default(true),
+    includeSourceRefs: z.boolean().default(true),
+    limit: z.number().int().min(1).max(100).default(20),
+    semanticCandidateLimit: z.number().int().min(1).max(2000).optional(),
+};
+const memorySearchBaseSchema = z.object(memoryReadInputShape);
+export const memorySearchInputSchema = memorySearchBaseSchema.superRefine(memoryReadSelectorValidation);
+export const memoryContextInputSchema = memorySearchBaseSchema.extend({
+    query: z.string().trim().min(1).max(20_000),
+    tokenBudget: z.number().int().min(128).max(32_000).optional(),
+    includeProfile: z.boolean().optional(),
+    includeBlocks: z.boolean().optional(),
+    includeRecentEpisodes: z.boolean().default(true),
+    promptFormat: z.enum(['text', 'markdown']).default('text'),
+}).superRefine(memoryReadSelectorValidation);
+const memoryRecordListSelectorShape = {
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+    subjectType: z.enum(memorySubjectTypes).optional(),
+    externalSubjectId: z.string().trim().min(1).max(220).optional(),
+    kind: z.enum(memoryRecordKinds).optional(),
+    sourceKind: z.enum(memorySourceKinds).optional(),
+    cursor: z.string().uuid().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+};
+function validateMemoryRecordListSelector(value, ctx) {
+    const selectors = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (selectors.length !== 1) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant or session selector.' });
+    }
+    if (Boolean(value.subjectType) !== Boolean(value.externalSubjectId)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'subjectType and externalSubjectId must be supplied together.',
+        });
+    }
+}
+export const memoryRecordListQuerySchema = z.object({
+    ...memoryRecordListSelectorShape,
+    state: z.enum(memoryRecallableRecordStates).optional(),
+}).superRefine(validateMemoryRecordListSelector);
+export const memoryForgottenRecordListQuerySchema = z.object(memoryRecordListSelectorShape)
+    .superRefine(validateMemoryRecordListSelector);
+export const memoryRecordUpdateInputSchema = z.object({
+    content: z.string().trim().min(1).max(1_000_000).optional(),
+    title: z.string().trim().min(1).max(260).nullable().optional(),
+    memoryType: z.enum(memoryTypes).optional(),
+    sensitivityClass: z.enum(memorySensitivityClasses).optional(),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length).optional(),
+    topicTags: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
+    language: z.string().trim().min(1).max(80).nullable().optional(),
+    validFrom: z.string().datetime().nullable().optional(),
+    validTo: z.string().datetime().nullable().optional(),
+    state: z.enum(['current', 'conflicted']).optional(),
+    reason: z.string().trim().min(1).max(500).optional(),
+    metadata: z.record(z.unknown()).optional(),
+}).superRefine((value, ctx) => {
+    if (Object.keys(value).length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'At least one record field must be supplied.' });
+    }
+    if (value.sensitivityClass !== undefined)
+        validateMemorySensitivity(value, ctx);
+});
+export const memoryForgetInputSchema = z.object({
+    reason: z.string().trim().min(1).max(500).optional(),
+});
+export const memoryBlockInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    sessionId: z.string().uuid().optional(),
+    subjects: z.array(memorySubjectRefSchema).min(1).max(20).optional(),
+    title: z.string().trim().min(1).max(260),
+    content: z.string().trim().min(1).max(200_000),
+    access: z.enum(['read_only', 'editable']).default('read_only'),
+    priority: z.number().int().min(0).max(100).default(50),
+    required: z.boolean().default(false),
+    metadata: z.record(z.unknown()).default({}),
+}).superRefine((value, ctx) => {
+    const selectors = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (selectors.length !== 1) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant or session selector.' });
+    }
+    if (!value.sessionId && (!value.subjects || value.subjects.length === 0)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['subjects'], message: 'subjects are required without sessionId.' });
+    }
+});
+export const memorySourceBindingInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    source: z.discriminatedUnion('kind', [
+        z.object({
+            kind: z.literal('conversation'),
+            applicationKey: z.string().trim().min(1).max(160),
+        }).strict(),
+        z.object({
+            kind: z.literal('artifact'),
+            artifactIds: z.array(z.string().uuid()).max(1000).default([]),
+        }).strict(),
+    ]),
+    targets: z.array(memorySubjectRefSchema).min(1).max(20),
+    policyKey: z.string().trim().min(1).max(120).default('default'),
+    consent: memoryConsentProofSchema.optional(),
+    metadata: z.record(z.unknown()).default({}),
+}).superRefine((value, ctx) => {
+    if (Boolean(value.tenantId) === Boolean(value.externalTenantId)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide exactly one of tenantId or externalTenantId.',
+        });
+    }
+});
+export const memoryConnectedSourceBackfillRangeSchema = z.enum([
+    'future_only',
+    'last_30_days',
+    'last_90_days',
+    'all',
+]);
+export const memoryConnectedSourceInputSchema = z.object({
+    idempotencyKey: z.string().trim().min(1).max(240),
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    connectedAccountId: z.string().uuid(),
+    sourceFamilyKey: z.string().trim().min(1).max(180),
+    resourceIds: z.array(z.string().trim().min(1).max(320)).max(1000).default([]),
+    selectionMode: z.enum(['selected_resources', 'recipe_default']).default('selected_resources'),
+    targets: z.array(memorySubjectRefSchema).min(1).max(20),
+    existingContent: memoryConnectedSourceBackfillRangeSchema.default('future_only'),
+    maxBackfillItems: z.number().int().positive().max(10_000).nullable().default(null),
+    deliveryMode: z.enum(['auto', 'webhook', 'polling']).default('auto'),
+    rememberInstructions: z.string().trim().max(4000).default(''),
+    excludeInstructions: z.string().trim().max(4000).default(''),
+    allowedMemoryTypes: z.array(z.enum(memoryTypes)).max(memoryTypes.length).default([...memoryTypes]),
+    learnedRetentionDays: z.number().int().min(1).max(3650).nullable().default(null),
+    sourceRetentionDays: z.number().int().min(1).max(3650).nullable().default(30),
+    consent: memoryConsentProofSchema.optional(),
+    metadata: z.record(z.unknown()).default({}),
+}).strict().superRefine((value, ctx) => {
+    if (Boolean(value.tenantId) === Boolean(value.externalTenantId)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide exactly one of tenantId or externalTenantId.',
+        });
+    }
+});
+export const memoryConnectedSourcePreviewInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    connectedAccountId: z.string().uuid(),
+    sourceFamilyKey: z.string().trim().min(1).max(180),
+    resourceIds: z.array(z.string().trim().min(1).max(320)).max(1000).default([]),
+    existingContent: memoryConnectedSourceBackfillRangeSchema.default('future_only'),
+}).strict().superRefine((value, ctx) => {
+    if (Boolean(value.tenantId) === Boolean(value.externalTenantId)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide exactly one of tenantId or externalTenantId.',
+        });
+    }
+});
+export const memoryConnectedSourceSettingsInputSchema = z.object({
+    resourceIds: z.array(z.string().trim().min(1).max(320)).max(1000),
+    targets: z.array(memorySubjectRefSchema).min(1).max(20),
+    existingContent: memoryConnectedSourceBackfillRangeSchema,
+    rememberInstructions: z.string().trim().max(4000),
+    excludeInstructions: z.string().trim().max(4000),
+    allowedMemoryTypes: z.array(z.enum(memoryTypes)).max(memoryTypes.length),
+    learnedRetentionDays: z.number().int().min(1).max(3650).nullable(),
+    sourceRetentionDays: z.number().int().min(1).max(3650).nullable(),
+}).strict();
+export const memorySourceBindingUpdateInputSchema = z.object({
+    status: z.enum(['active', 'paused']).optional(),
+    connectedSource: memoryConnectedSourceSettingsInputSchema.optional(),
+}).strict().refine((value) => value.status !== undefined || value.connectedSource !== undefined, {
+    message: 'Provide a source status or complete connected-source settings.',
+});
+export const memoryProcessSourceJobType = 'memory_process_source';
+export const memoryNormalizeRichSourceJobType = 'memory_normalize_rich_source';
+export const memoryRebuildProfileJobType = 'memory_rebuild_profile';
+export const memoryCellMoveJobType = 'memory_cell_move_execute';
+export const memoryReconcileJobType = 'memory_reconcile';
+export const memoryRetentionJobType = 'memory_retention';
+export const memoryConnectedSourceEventJobType = 'memory_connected_source_event';
+export const memoryConversationTurnInputSchema = z.object({
+    sessionId: z.string().uuid(),
+    applicationKey: z.string().trim().min(1).max(160),
+    turnId: z.string().trim().min(1).max(240),
+    content: z.string().trim().min(1).max(1_000_000),
+    title: z.string().trim().min(1).max(260).optional(),
+    occurredAt: z.string().datetime().optional(),
+    consent: memoryConsentProofSchema.optional(),
+    metadata: z.record(z.unknown()).default({}),
+}).strict();
+export const memoryGraphQueryInputSchema = memorySearchBaseSchema.extend({
+    query: z.string().trim().min(1).max(20_000).optional(),
+    seedRecordIds: z.array(z.string().uuid()).max(50).default([]),
+    predicates: z.array(z.string().trim().min(1).max(120)).max(50).optional(),
+    maxDepth: z.number().int().min(1).max(4).default(2),
+    maxClaims: z.number().int().min(1).max(200).default(50),
+}).superRefine(memoryReadSelectorValidation).refine((value) => Boolean(value.query) || value.seedRecordIds.length > 0, {
+    message: 'Provide query or seedRecordIds.',
+});
+export const memoryExportInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    subject: memorySubjectRefSchema.optional(),
+    format: z.enum(['json', 'jsonl']).default('json'),
+}).superRefine((value, ctx) => {
+    if (Boolean(value.tenantId) === Boolean(value.externalTenantId)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant selector.' });
+    }
+});
+export const memoryLegalHoldInputSchema = z.object({
+    tenantId: z.string().uuid().optional(),
+    externalTenantId: z.string().trim().min(1).max(160).optional(),
+    subject: memorySubjectRefSchema.optional(),
+    reason: z.string().trim().min(1).max(2000),
+}).strict().superRefine((value, ctx) => {
+    if (Boolean(value.tenantId) === Boolean(value.externalTenantId)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant selector.' });
+    }
+});
+export const memoryProjectPolicyInputSchema = z.object({
+    key: z.string().trim().min(1).max(120).default('default'),
+    captureMode: z.enum(['explicit', 'bound_sources']).default('explicit'),
+    extractionEnabled: z.boolean().default(true),
+    profileEnabled: z.boolean().default(true),
+    retentionDays: z.number().int().min(1).max(3650).nullable().default(null),
+    sourceRetentionDays: z.number().int().min(1).max(3650).nullable().default(30),
+    allowedMemoryTypes: z.array(z.enum(memoryTypes)).max(memoryTypes.length).default([...memoryTypes]),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length).default([]),
+    languages: z.array(z.string().trim().min(1).max(80)).max(50).default([]),
+    consent: z.record(z.unknown()).default({}),
+    extraction: z.record(z.unknown()).default({}),
+    context: z.record(z.unknown()).default({}),
+    metadata: z.record(z.unknown()).default({}),
+});
+export const memoryProjectPolicyUpdateInputSchema = memoryProjectPolicyInputSchema
+    .omit({ key: true })
+    .extend({
+    expectedVersion: z.number().int().positive(),
+})
+    .strict();
+export const memoryPolicyPreviewInputSchema = z.object({
+    idempotencyKey: z.string().trim().min(1).max(240),
+    content: z.string().trim().min(1).max(200_000),
+    title: z.string().trim().min(1).max(260).optional(),
+    sourceCategory: z.string().trim().min(1).max(120).optional(),
+    language: z.string().trim().min(1).max(80).optional(),
+    policy: memoryProjectPolicyInputSchema.omit({ key: true }).default({}),
+}).strict();
+export const stacklinkPlatformEventTypes = [
+    'provider.resource.created',
+    'provider.resource.updated',
+    'provider.resource.deleted',
+    'tool.execution.completed',
+    'conversation.turn.completed',
+    'artifact.created',
+];
+export const stacklinkPlatformEventSchema = z.object({
+    id: z.string().uuid(),
+    schemaVersion: z.literal('stacklink.event.v1'),
+    consumerAppId: z.string().uuid(),
+    tenantId: z.string().uuid(),
+    sessionId: z.string().uuid().optional(),
+    userId: z.string().uuid().optional(),
+    type: z.enum(stacklinkPlatformEventTypes),
+    source: z.object({
+        kind: z.enum(['provider', 'tool_execution', 'conversation', 'artifact']),
+        providerKey: z.string().trim().min(1).max(120).optional(),
+        connectedAccountId: z.string().uuid().optional(),
+        resourceType: z.string().trim().min(1).max(120).optional(),
+        resourceId: z.string().trim().min(1).max(320).optional(),
+        resourcePreviousScopeIds: z.array(z.string().trim().min(1).max(320)).max(1000).optional(),
+        resourceCurrentScopeIds: z.array(z.string().trim().min(1).max(320)).max(1000).optional(),
+        resourceAffectedScopeIds: z.array(z.string().trim().min(1).max(320)).max(1000).optional(),
+        toolExecutionId: z.string().uuid().optional(),
+        applicationKey: z.string().trim().min(1).max(160).optional(),
+    }).strict(),
+    occurredAt: z.string().datetime(),
+    observedAt: z.string().datetime(),
+    payloadRef: z.string().trim().min(1).max(2000).optional(),
+    data: z.record(z.unknown()),
+    metadata: z.record(z.unknown()),
+}).strict();
+export const memorySessionConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    agentExternalId: z.string().trim().min(1).max(220).optional(),
+    readableSubjects: z.array(z.enum(['session_user', 'session_agent', 'tenant_shared'])).max(3).default(['session_user']),
+    writableSubjects: z.array(z.enum(['session_user', 'session_agent', 'tenant_shared'])).max(3).default(['session_user']),
+    captureMode: z.enum(['explicit', 'bound_sources']).default('explicit'),
+    includeProfile: z.boolean().default(true),
+    includeBlocks: z.boolean().default(true),
+    contextTokenBudget: z.number().int().min(128).max(32_000).default(1600),
+    policyKey: z.string().trim().min(1).max(120).default('default'),
+}).strict().superRefine((value, ctx) => {
+    if (value.enabled && value.readableSubjects.length === 0 && value.writableSubjects.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['readableSubjects'],
+            message: 'An enabled Memory session must grant at least one readable or writable subject.',
+        });
+    }
+    const usesAgent = value.readableSubjects.includes('session_agent')
+        || value.writableSubjects.includes('session_agent');
+    if (usesAgent && !value.agentExternalId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['agentExternalId'],
+            message: 'agentExternalId is required when session_agent is readable or writable.',
+        });
+    }
+});
+export const memoryExtractedEntitySchema = z.object({
+    key: z.string().trim().min(1).max(320),
+    type: z.string().trim().min(1).max(80),
+    canonicalKey: z.string().trim().min(1).max(320),
+    displayName: z.string().trim().min(1).max(320).nullable(),
+    attributes: z.record(z.unknown()),
+}).strict();
+const memoryExtractedNullableDateTimeSchema = z.preprocess((value) => {
+    if (typeof value !== 'string')
+        return value;
+    return z.string().datetime().safeParse(value).success ? value : null;
+}, z.string().datetime().nullable());
+export const memoryExtractedClaimSchema = z.object({
+    subjectEntityKey: z.string().trim().min(1).max(320),
+    predicate: z.string().trim().min(1).max(120),
+    objectEntityKey: z.string().trim().min(1).max(320).nullable(),
+    literalValue: z.unknown().nullable(),
+    validFrom: memoryExtractedNullableDateTimeSchema,
+    validTo: memoryExtractedNullableDateTimeSchema,
+}).strict().superRefine((value, ctx) => {
+    const objectCount = Number(value.objectEntityKey !== null) + Number(value.literalValue !== null);
+    if (objectCount !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Each claim requires exactly one objectEntityKey or literalValue.',
+        });
+    }
+    validateTemporalInterval({
+        validFrom: value.validFrom ?? undefined,
+        validTo: value.validTo ?? undefined,
+    }, ctx);
+});
+export const memoryEvidenceSpanSchema = z.object({
+    sourceObjectId: z.string().trim().min(1).max(320),
+    segmentId: z.string().trim().min(1).max(80),
+    startOffset: z.number().int().min(0),
+    endOffset: z.number().int().positive(),
+    quotedText: z.string().min(1).max(20_000),
+}).strict().refine((value) => value.endOffset > value.startOffset, {
+    message: 'Evidence endOffset must be greater than startOffset.',
+});
+export const memoryExtractedRecordSchema = z.object({
+    candidateId: z.string().trim().min(1).max(120),
+    recordKind: z.enum(memoryAutomaticRecordKinds),
+    memoryType: z.enum(memoryTypes),
+    title: z.string().trim().min(1).max(260),
+    content: z.string().trim().min(1).max(200_000),
+    language: z.string().trim().min(1).max(80),
+    sensitivityClass: z.enum(memorySensitivityClasses),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length),
+    topicTags: z.array(z.string().trim().min(1).max(120)).max(50),
+    validFrom: memoryExtractedNullableDateTimeSchema,
+    validTo: memoryExtractedNullableDateTimeSchema,
+    evidence: z.array(memoryEvidenceSpanSchema).min(1).max(5),
+    entities: z.array(memoryExtractedEntitySchema).max(50),
+    claims: z.array(memoryExtractedClaimSchema).max(100),
+    attributes: z.record(z.unknown()),
+}).strict().superRefine((value, ctx) => {
+    validateTemporalInterval({
+        validFrom: value.validFrom ?? undefined,
+        validTo: value.validTo ?? undefined,
+    }, ctx);
+    const entityKeys = new Set(value.entities.map((entity) => entity.key));
+    for (const [index, claim] of value.claims.entries()) {
+        if (!entityKeys.has(claim.subjectEntityKey)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['claims', index, 'subjectEntityKey'],
+                message: 'Claim subjectEntityKey must reference an entity in the same candidate.',
+            });
+        }
+        if (claim.objectEntityKey && !entityKeys.has(claim.objectEntityKey)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['claims', index, 'objectEntityKey'],
+                message: 'Claim objectEntityKey must reference an entity in the same candidate.',
+            });
+        }
+    }
+});
+export const memoryExtractionResultSchema = z.object({
+    records: z.array(memoryExtractedRecordSchema).max(100),
+}).strict();
+export const memorySafetyDecisionSchema = z.object({
+    candidateId: z.string().trim().min(1).max(120),
+    status: z.enum(['classified', 'uncertain']),
+    sensitivityClass: z.enum(memorySensitivityClasses),
+    restrictedDataClasses: z.array(z.enum(memoryRestrictedDataClasses)).max(memoryRestrictedDataClasses.length),
+    reason: z.string().trim().min(1).max(1000),
+}).strict().superRefine((value, ctx) => {
+    if (value.sensitivityClass === 'restricted' && value.restrictedDataClasses.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['restrictedDataClasses'],
+            message: 'Restricted safety decisions must declare at least one restricted-data class.',
+        });
+    }
+    if (value.sensitivityClass !== 'restricted' && value.restrictedDataClasses.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['restrictedDataClasses'],
+            message: 'Only restricted safety decisions may declare restricted-data classes.',
+        });
+    }
+});
+export const memorySafetyResultSchema = z.object({
+    decisions: z.array(memorySafetyDecisionSchema).max(100),
+}).strict();
+const memoryConsolidationDecisionSchema = z.object({
+    candidateId: z.string().trim().min(1).max(120),
+    action: z.enum(['add', 'supersede', 'contradict', 'support', 'no_change']),
+    targetRecordId: z.string().uuid().nullable(),
+    reason: z.string().trim().min(1).max(1000),
+}).strict().superRefine((decision, ctx) => {
+    const actionRequiresTarget = decision.action === 'supersede'
+        || decision.action === 'contradict'
+        || decision.action === 'support';
+    if (actionRequiresTarget !== (decision.targetRecordId !== null)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['targetRecordId'],
+            message: actionRequiresTarget
+                ? `${decision.action} requires targetRecordId.`
+                : `${decision.action} requires targetRecordId to be null.`,
+        });
+    }
+});
+export const memoryConsolidationResultSchema = z.object({
+    decisions: z.array(memoryConsolidationDecisionSchema).max(100),
+}).strict();
+export const memoryProfileResultSchema = z.object({
+    buckets: z.array(z.object({
+        key: z.string().trim().min(1).max(120),
+        content: z.string().trim().min(1).max(100_000),
+        includedRecordVersionIds: z.array(z.string().uuid()).min(1).max(500),
+    }).strict()).max(100),
+}).strict().superRefine((value, ctx) => {
+    const keys = value.buckets.map((bucket) => bucket.key);
+    if (new Set(keys).size !== keys.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Profile bucket keys must be unique.' });
+    }
+});
+export const memoryProfileDeltaResultSchema = z.object({
+    buckets: z.array(z.object({
+        key: z.string().trim().min(1).max(120),
+        content: z.string().trim().min(1).max(100_000),
+        includedRecordVersionIds: z.array(z.string().uuid()).min(1).max(500),
+    }).strict()).max(100),
+    removeBucketKeys: z.array(z.string().trim().min(1).max(120)).max(100),
+}).strict().superRefine((value, ctx) => {
+    const keys = value.buckets.map((bucket) => bucket.key);
+    if (new Set(keys).size !== keys.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Profile delta bucket keys must be unique.' });
+    }
+    if (new Set(value.removeBucketKeys).size !== value.removeBucketKeys.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Profile delta removal keys must be unique.' });
+    }
+    for (const key of value.removeBucketKeys) {
+        if (keys.includes(key)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `Profile delta cannot update and remove bucket ${key}.` });
+        }
+    }
+});
+export const memoryExtractionJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['records'],
+    properties: {
+        records: {
+            type: 'array',
+            maxItems: 100,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: [
+                    'candidateId', 'recordKind', 'memoryType', 'title', 'content', 'language',
+                    'sensitivityClass', 'restrictedDataClasses', 'topicTags', 'validFrom', 'validTo',
+                    'evidence', 'entities', 'claims', 'attributes',
+                ],
+                properties: {
+                    candidateId: { type: 'string' },
+                    recordKind: { type: 'string', enum: [...memoryAutomaticRecordKinds] },
+                    memoryType: { type: 'string', enum: [...memoryTypes] },
+                    title: { type: 'string' },
+                    content: { type: 'string' },
+                    language: { type: 'string' },
+                    sensitivityClass: { type: 'string', enum: [...memorySensitivityClasses] },
+                    restrictedDataClasses: {
+                        type: 'array',
+                        maxItems: memoryRestrictedDataClasses.length,
+                        items: { type: 'string', enum: [...memoryRestrictedDataClasses] },
+                    },
+                    topicTags: {
+                        type: 'array',
+                        maxItems: 50,
+                        items: { type: 'string' },
+                    },
+                    validFrom: { type: ['string', 'null'], format: 'date-time' },
+                    validTo: { type: ['string', 'null'], format: 'date-time' },
+                    evidence: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: 5,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['sourceObjectId', 'segmentId', 'startOffset', 'endOffset', 'quotedText'],
+                            properties: {
+                                sourceObjectId: { type: 'string' },
+                                segmentId: { type: 'string' },
+                                startOffset: { type: 'integer', minimum: 0 },
+                                endOffset: { type: 'integer', minimum: 1 },
+                                quotedText: { type: 'string' },
+                            },
+                        },
+                    },
+                    entities: {
+                        type: 'array',
+                        description: 'Entities used by this record. Every entity key referenced by this record claims must be declared in this same array.',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['key', 'type', 'canonicalKey', 'displayName', 'attributes'],
+                            properties: {
+                                key: { type: 'string', description: 'A key unique within this record and used by this record claims.' },
+                                type: { type: 'string' },
+                                canonicalKey: { type: 'string' },
+                                displayName: { type: ['string', 'null'] },
+                                attributes: { type: 'object', additionalProperties: true },
+                            },
+                        },
+                    },
+                    claims: {
+                        type: 'array',
+                        description: 'Claims for this record. Entity references may only use keys declared in this same record entities array.',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['subjectEntityKey', 'predicate', 'objectEntityKey', 'literalValue', 'validFrom', 'validTo'],
+                            properties: {
+                                subjectEntityKey: { type: 'string', description: 'Must exactly match an entities[].key in this same record.' },
+                                predicate: { type: 'string' },
+                                objectEntityKey: { type: ['string', 'null'], description: 'When non-null, must exactly match an entities[].key in this same record.' },
+                                literalValue: {
+                                    anyOf: [
+                                        { type: 'string' },
+                                        { type: 'number' },
+                                        { type: 'boolean' },
+                                        { type: 'object' },
+                                        { type: 'array' },
+                                        { type: 'null' },
+                                    ],
+                                },
+                                validFrom: { type: ['string', 'null'], format: 'date-time' },
+                                validTo: { type: ['string', 'null'], format: 'date-time' },
+                            },
+                        },
+                    },
+                    attributes: { type: 'object', additionalProperties: true },
+                },
+            },
+        },
+    },
+};
+export const memorySafetyJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['decisions'],
+    properties: {
+        decisions: {
+            type: 'array',
+            maxItems: 100,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['candidateId', 'status', 'sensitivityClass', 'restrictedDataClasses', 'reason'],
+                properties: {
+                    candidateId: { type: 'string' },
+                    status: { type: 'string', enum: ['classified', 'uncertain'] },
+                    sensitivityClass: { type: 'string', enum: [...memorySensitivityClasses] },
+                    restrictedDataClasses: {
+                        type: 'array',
+                        maxItems: memoryRestrictedDataClasses.length,
+                        items: { type: 'string', enum: [...memoryRestrictedDataClasses] },
+                    },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+    },
+};
+export const memoryConsolidationJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['decisions'],
+    properties: {
+        decisions: {
+            type: 'array',
+            maxItems: 100,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['candidateId', 'action', 'targetRecordId', 'reason'],
+                properties: {
+                    candidateId: { type: 'string' },
+                    action: { type: 'string', enum: ['add', 'supersede', 'contradict', 'support', 'no_change'] },
+                    targetRecordId: { type: ['string', 'null'], format: 'uuid' },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+    },
+};
+export function memoryProfileJsonSchema(allowedBucketKeys) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['buckets'],
+        properties: {
+            buckets: {
+                type: 'array',
+                maxItems: allowedBucketKeys.length,
+                items: memoryProfileBucketJsonSchema(allowedBucketKeys),
+            },
+        },
+    };
+}
+export function memoryProfileDeltaJsonSchema(allowedBucketKeys) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['buckets', 'removeBucketKeys'],
+        properties: {
+            buckets: {
+                type: 'array',
+                maxItems: allowedBucketKeys.length,
+                items: memoryProfileBucketJsonSchema(allowedBucketKeys),
+            },
+            removeBucketKeys: {
+                type: 'array',
+                maxItems: allowedBucketKeys.length,
+                items: { type: 'string', enum: allowedBucketKeys },
+            },
+        },
+    };
+}
+function memoryProfileBucketJsonSchema(allowedBucketKeys) {
+    if (allowedBucketKeys.length === 0) {
+        throw new Error('Memory profile schemas require at least one allowed bucket key.');
+    }
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['key', 'content', 'includedRecordVersionIds'],
+        properties: {
+            key: { type: 'string', enum: allowedBucketKeys },
+            content: { type: 'string', minLength: 1, maxLength: 100_000 },
+            includedRecordVersionIds: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 500,
+                items: { type: 'string', format: 'uuid' },
+            },
+        },
+    };
+}
+function memoryReadSelectorValidation(value, ctx) {
+    const selectors = [value.tenantId, value.externalTenantId, value.sessionId].filter(Boolean);
+    if (selectors.length !== 1) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide exactly one tenant or session selector.' });
+    }
+    if (!value.sessionId && (!value.subjects || value.subjects.length === 0)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['subjects'], message: 'subjects are required without sessionId.' });
+    }
+}
+function validateMemorySensitivity(value, ctx) {
+    const restrictedDataClasses = value.restrictedDataClasses ?? [];
+    if (value.sensitivityClass === 'secret') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['sensitivityClass'],
+            message: 'Secret authentication or credential material cannot be stored in Memory.',
+        });
+    }
+    if (value.sensitivityClass === 'restricted' && restrictedDataClasses.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['restrictedDataClasses'],
+            message: 'Restricted Memory must declare at least one typed restricted-data class.',
+        });
+    }
+    if (value.sensitivityClass !== 'restricted' && restrictedDataClasses.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['restrictedDataClasses'],
+            message: 'Restricted-data classes are allowed only when sensitivityClass is restricted.',
+        });
+    }
+}
+function validateTemporalInterval(value, ctx) {
+    if (value.validFrom && value.validTo && Date.parse(value.validTo) <= Date.parse(value.validFrom)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['validTo'],
+            message: 'validTo must be later than validFrom.',
+        });
+    }
+}
+//# sourceMappingURL=memory-contract.js.map