@lore-co/core 0.1.17 → 0.1.19

package/dist/reliability-schemas.js

@@ -0,0 +1,750 @@
+import { z } from "zod";
+import { GuardActionSchema } from "./guard-schemas.js";
+import { redactUnknown } from "./redaction.js";
+import { AgentMessageSchema, MemoryScopeSchema, } from "./schemas.js";
+export const RELIABILITY_CONTRACT_VERSION = "reliability-v1";
+export const RELIABILITY_V1_MEDIA_TYPE = "application/vnd.lore.reliability-v1+json";
+export const CAPTURE_EXTRACT_JOB_VERSION = "capture-extract-v1";
+export const MEMORY_EMBED_JOB_VERSION = "memory-embed-v1";
+export const ReliabilityContractVersionSchema = z.literal(RELIABILITY_CONTRACT_VERSION);
+export const ReliabilityOperationSchema = z.enum([
+    "capture",
+    "retrieval",
+    "guard",
+]);
+export const ReliabilityStatusSchema = z.enum([
+    "ok",
+    "degraded",
+    "blocked",
+    "overridden",
+    "failed",
+]);
+export const ReliabilitySourceSchema = z.enum([
+    "live",
+    "cache",
+    "local_queue",
+    "none",
+]);
+export const ReliabilityFallbackModeSchema = z.enum([
+    "none",
+    "live_lexical",
+    "cached_context",
+    "cached_policy",
+    "local_queue",
+    "break_glass",
+]);
+export const ReliabilityReasonCodeSchema = z.enum([
+    "live_success",
+    "idempotent_replay",
+    "semantic_unavailable",
+    "lexical_fallback",
+    "live_unavailable",
+    "cached_context",
+    "cached_policy",
+    "no_usable_cache",
+    "capture_queued",
+    "local_persistence_failed",
+    "governed_rule",
+    "policy_unavailable",
+    "policy_expired",
+    "user_override",
+    "invalid_response",
+    "integration_unsupported",
+]);
+const KnownFreshnessFields = {
+    asOf: z.iso.datetime({ offset: true }),
+    ageMs: z.number().int().nonnegative(),
+    validUntil: z.iso.datetime({ offset: true }).nullable(),
+};
+export const ReliabilityFreshnessSchema = z.discriminatedUnion("state", [
+    z
+        .object({
+        state: z.literal("fresh"),
+        ...KnownFreshnessFields,
+    })
+        .strict(),
+    z
+        .object({
+        state: z.literal("stale"),
+        ...KnownFreshnessFields,
+    })
+        .strict(),
+    z
+        .object({
+        state: z.literal("unknown"),
+        asOf: z.null(),
+        ageMs: z.null(),
+        validUntil: z.null(),
+    })
+        .strict(),
+]);
+export const ReliabilityPolicyReferenceSchema = z
+    .discriminatedUnion("source", [
+    z
+        .object({
+        source: z.literal("live"),
+        version: z.string().trim().min(1).max(200),
+        loadedAt: z.iso.datetime({ offset: true }),
+        validUntil: z.iso.datetime({ offset: true }).nullable(),
+    })
+        .strict(),
+    z
+        .object({
+        source: z.literal("cache"),
+        version: z.string().trim().min(1).max(200),
+        loadedAt: z.iso.datetime({ offset: true }),
+        validUntil: z.iso.datetime({ offset: true }),
+    })
+        .strict(),
+    z
+        .object({
+        source: z.literal("none"),
+        version: z.null(),
+        loadedAt: z.null(),
+        validUntil: z.null(),
+    })
+        .strict(),
+])
+    .superRefine((policy, context) => {
+    if (policy.source !== "none" &&
+        policy.validUntil !== null &&
+        Date.parse(policy.validUntil) <= Date.parse(policy.loadedAt)) {
+        context.addIssue({
+            code: "custom",
+            path: ["validUntil"],
+            message: "Policy validity must end after it was loaded",
+        });
+    }
+});
+const FALLBACK_REASON = {
+    live_lexical: "lexical_fallback",
+    cached_context: "cached_context",
+    cached_policy: "cached_policy",
+    local_queue: "capture_queued",
+    break_glass: "user_override",
+};
+export const ReliabilityMetadataSchema = z
+    .object({
+    contractVersion: ReliabilityContractVersionSchema,
+    operation: ReliabilityOperationSchema,
+    status: ReliabilityStatusSchema,
+    source: ReliabilitySourceSchema,
+    freshness: ReliabilityFreshnessSchema,
+    fallback: ReliabilityFallbackModeSchema,
+    policy: ReliabilityPolicyReferenceSchema,
+    reasons: z.array(ReliabilityReasonCodeSchema).min(1).max(8),
+    requestId: z.string().trim().min(1).max(128).nullable(),
+})
+    .strict()
+    .superRefine((result, context) => {
+    if (new Set(result.reasons).size !== result.reasons.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["reasons"],
+            message: "Reliability reason codes must be unique",
+        });
+    }
+    const expectedFallbackReason = FALLBACK_REASON[result.fallback];
+    if (expectedFallbackReason !== undefined &&
+        !result.reasons.includes(expectedFallbackReason)) {
+        context.addIssue({
+            code: "custom",
+            path: ["reasons"],
+            message: `Fallback ${result.fallback} requires reason ${expectedFallbackReason}`,
+        });
+    }
+    if (result.source === "none" && result.freshness.state !== "unknown") {
+        context.addIssue({
+            code: "custom",
+            path: ["freshness"],
+            message: "A result with no source must have unknown freshness",
+        });
+    }
+    if (result.source === "live" && result.freshness.state !== "fresh") {
+        context.addIssue({
+            code: "custom",
+            path: ["freshness"],
+            message: "A live result must be fresh",
+        });
+    }
+    if (result.source === "cache" &&
+        result.freshness.state === "unknown") {
+        context.addIssue({
+            code: "custom",
+            path: ["freshness"],
+            message: "A cached result must report when it was captured",
+        });
+    }
+    if (result.source === "local_queue" &&
+        result.freshness.state !== "fresh") {
+        context.addIssue({
+            code: "custom",
+            path: ["freshness"],
+            message: "A newly queued local capture must be fresh",
+        });
+    }
+    if (result.status === "ok" && result.source === "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["source"],
+            message: "A successful result must identify a usable source",
+        });
+    }
+    if (result.status === "ok" && result.fallback !== "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["fallback"],
+            message: "A non-degraded result cannot use a fallback",
+        });
+    }
+    if (result.status === "degraded" && result.fallback === "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["fallback"],
+            message: "A degraded result must identify its fallback",
+        });
+    }
+    if (result.status === "overridden" &&
+        result.fallback !== "break_glass") {
+        context.addIssue({
+            code: "custom",
+            path: ["fallback"],
+            message: "An overridden result must use the break-glass fallback",
+        });
+    }
+    if (result.status === "failed" &&
+        (result.source !== "none" || result.fallback !== "none")) {
+        context.addIssue({
+            code: "custom",
+            path: ["status"],
+            message: "A failed result cannot claim a usable source or fallback",
+        });
+    }
+    if (result.fallback === "live_lexical" &&
+        result.source !== "live") {
+        context.addIssue({
+            code: "custom",
+            path: ["source"],
+            message: "A lexical fallback is still a live source",
+        });
+    }
+    if ((result.fallback === "cached_context" ||
+        result.fallback === "cached_policy") &&
+        result.source !== "cache") {
+        context.addIssue({
+            code: "custom",
+            path: ["source"],
+            message: "A cached fallback must identify cache as its source",
+        });
+    }
+    if (result.fallback === "local_queue" &&
+        result.source !== "local_queue") {
+        context.addIssue({
+            code: "custom",
+            path: ["source"],
+            message: "A local-queue fallback must identify the local queue",
+        });
+    }
+});
+const CaptureAcknowledgementFields = {
+    contractVersion: ReliabilityContractVersionSchema,
+    captureId: z.uuid(),
+    idempotencyKey: z.string().trim().min(1).max(500),
+    acknowledgedAt: z.iso.datetime({ offset: true }),
+};
+export const CaptureAcknowledgementSchema = z
+    .discriminatedUnion("state", [
+    z
+        .object({
+        ...CaptureAcknowledgementFields,
+        state: z.literal("queued_local"),
+        durability: z.literal("local_machine"),
+        replayPending: z.literal(true),
+        replayed: z.literal(false),
+        processing: z.literal("pending_upload"),
+    })
+        .strict(),
+    z
+        .object({
+        ...CaptureAcknowledgementFields,
+        state: z.literal("committed_server"),
+        durability: z.literal("workspace_database"),
+        replayPending: z.literal(false),
+        replayed: z.boolean(),
+        processing: z.enum(["pending_extraction", "completed"]),
+        eventId: z.uuid(),
+        memoryIds: z.array(z.uuid()),
+    })
+        .strict(),
+])
+    .superRefine((acknowledgement, context) => {
+    if (acknowledgement.state === "committed_server" &&
+        acknowledgement.processing === "pending_extraction" &&
+        acknowledgement.memoryIds.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["memoryIds"],
+            message: "Pending extraction cannot acknowledge extracted memories",
+        });
+    }
+});
+export const CaptureProcessingResultSchema = z
+    .object({
+    created: z.number().int().nonnegative(),
+    duplicates: z.number().int().nonnegative(),
+    reconciled: z.number().int().nonnegative(),
+    superseded: z.number().int().nonnegative(),
+})
+    .strict();
+const CaptureExtractMemoryIdsSchema = z.array(z.uuid()).max(10_000);
+const CaptureExtractResultFields = {
+    memoryIds: CaptureExtractMemoryIdsSchema,
+    result: CaptureProcessingResultSchema,
+};
+const CaptureExtractMessageSchema = AgentMessageSchema.extend({
+    content: z.string().max(100_000),
+    id: z.string().trim().min(1).max(500).optional(),
+}).strict();
+const CaptureExtractScopeSchema = MemoryScopeSchema.extend({
+    organization: z.string().trim().min(1).max(200),
+    project: z.string().trim().min(1).max(500).optional(),
+    repo: z.string().trim().min(1).max(1_000).optional(),
+    path: z.string().trim().min(1).max(2_000).optional(),
+    component: z.string().trim().min(1).max(500).optional(),
+}).strict();
+const CaptureExtractInteractionSchema = z
+    .object({
+    agent: z.string().trim().min(1).max(100),
+    workspaceId: z.uuid(),
+    eventId: z.uuid(),
+    userId: z.uuid().optional(),
+    scope: CaptureExtractScopeSchema,
+    sessionId: z.string().trim().min(1).max(500),
+    messages: z.array(CaptureExtractMessageSchema).min(1).max(500),
+})
+    .strict();
+const CaptureRedactionFindingSchema = z
+    .object({
+    kind: z.enum([
+        "circular",
+        "pre_redacted",
+        "private_key",
+        "authorization",
+        "connection_url",
+        "jwt",
+        "provider_token",
+        "credential",
+    ]),
+    count: z.number().int().positive().max(10_000),
+})
+    .strict();
+const CaptureExtractProvenanceFields = {
+    connector: z.string().trim().min(1).max(100),
+    externalEventId: z.string().trim().min(1).max(500),
+    redacted: z.boolean(),
+    redactionFindings: z.array(CaptureRedactionFindingSchema).max(8),
+};
+export const CaptureExtractJobPayloadSchema = z
+    .discriminatedUnion("kind", [
+    z
+        .object({
+        jobVersion: z.literal(CAPTURE_EXTRACT_JOB_VERSION),
+        kind: z.literal("observation"),
+        captureId: z.uuid(),
+        eventId: z.uuid(),
+        idempotencyKey: z.string().trim().min(1).max(500),
+        requestHash: z.string().regex(/^[a-f0-9]{64}$/u),
+        interaction: CaptureExtractInteractionSchema,
+        provenance: z
+            .object({
+            ...CaptureExtractProvenanceFields,
+            task: z.string().max(100_000).nullable(),
+        })
+            .strict(),
+    })
+        .strict(),
+    z
+        .object({
+        jobVersion: z.literal(CAPTURE_EXTRACT_JOB_VERSION),
+        kind: z.literal("paired_turn"),
+        captureId: z.uuid(),
+        eventId: z.uuid(),
+        idempotencyKey: z.string().trim().min(1).max(500),
+        requestHash: z.string().regex(/^[a-f0-9]{64}$/u),
+        interaction: CaptureExtractInteractionSchema,
+        provenance: z
+            .object({
+            ...CaptureExtractProvenanceFields,
+            previousAssistantMessageId: z
+                .string()
+                .trim()
+                .min(1)
+                .max(500)
+                .nullable(),
+        })
+            .strict(),
+    })
+        .strict(),
+])
+    .superRefine((payload, context) => {
+    if (payload.interaction.eventId !== payload.eventId) {
+        context.addIssue({
+            code: "custom",
+            path: ["interaction", "eventId"],
+            message: "Capture interaction must bind the persisted event",
+        });
+    }
+    const redacted = redactUnknown(payload).value;
+    if (JSON.stringify(redacted) !== JSON.stringify(payload)) {
+        context.addIssue({
+            code: "custom",
+            path: ["interaction"],
+            message: "Capture extraction payload must be redacted before persistence",
+        });
+    }
+});
+export const CaptureExtractJobResultSchema = z
+    .object({
+    jobVersion: z.literal(CAPTURE_EXTRACT_JOB_VERSION),
+    captureId: z.uuid(),
+    eventId: z.uuid(),
+    ...CaptureExtractResultFields,
+})
+    .strict();
+const Sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+export const MemoryEmbedJobPayloadV1Schema = z
+    .object({
+    jobVersion: z.literal(MEMORY_EMBED_JOB_VERSION),
+    workspaceId: z.uuid(),
+    memoryId: z.uuid(),
+    updatedAt: z.iso.datetime({ offset: true }),
+    fingerprint: Sha256Schema,
+    contentSha256: Sha256Schema,
+    provider: z.string().trim().min(1).max(100),
+    model: z.string().trim().min(1).max(500),
+    embeddingSpaceId: Sha256Schema,
+    dimensions: z.number().int().min(1).max(16_384),
+})
+    .strict();
+export const MemoryEmbedJobResultV1Schema = z
+    .object({
+    jobVersion: z.literal(MEMORY_EMBED_JOB_VERSION),
+    memoryId: z.uuid(),
+    embeddingSpaceId: Sha256Schema,
+    outcome: z.enum(["stored", "stale"]),
+})
+    .strict();
+const CaptureStatusFields = {
+    contractVersion: ReliabilityContractVersionSchema,
+    captureId: z.uuid(),
+    eventId: z.uuid(),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+};
+export const CaptureStatusResponseSchema = z
+    .discriminatedUnion("processing", [
+    z
+        .object({
+        ...CaptureStatusFields,
+        processing: z.literal("pending_extraction"),
+        attempts: z.number().int().min(0).max(100),
+    })
+        .strict(),
+    z
+        .object({
+        ...CaptureStatusFields,
+        processing: z.literal("completed"),
+        attempts: z.number().int().min(1).max(100),
+        completedAt: z.iso.datetime({ offset: true }),
+        ...CaptureExtractResultFields,
+    })
+        .strict(),
+    z
+        .object({
+        ...CaptureStatusFields,
+        processing: z.literal("dead"),
+        attempts: z.number().int().min(1).max(100),
+        deadAt: z.iso.datetime({ offset: true }),
+        failure: z
+            .object({
+            code: z
+                .string()
+                .trim()
+                .min(1)
+                .max(100)
+                .regex(/^[a-z0-9][a-z0-9._-]*$/iu),
+            message: z.string().trim().min(1).max(500),
+        })
+            .strict(),
+    })
+        .strict(),
+])
+    .superRefine((status, context) => {
+    if (Date.parse(status.updatedAt) < Date.parse(status.createdAt)) {
+        context.addIssue({
+            code: "custom",
+            path: ["updatedAt"],
+            message: "Capture status cannot be updated before the job was created",
+        });
+    }
+    const terminalAt = status.processing === "completed"
+        ? status.completedAt
+        : status.processing === "dead"
+            ? status.deadAt
+            : null;
+    if (terminalAt !== null &&
+        Date.parse(terminalAt) < Date.parse(status.createdAt)) {
+        context.addIssue({
+            code: "custom",
+            path: [
+                status.processing === "completed" ? "completedAt" : "deadAt",
+            ],
+            message: "Capture job cannot terminate before it was created",
+        });
+    }
+    if (terminalAt !== null &&
+        Date.parse(terminalAt) > Date.parse(status.updatedAt)) {
+        context.addIssue({
+            code: "custom",
+            path: [
+                status.processing === "completed" ? "completedAt" : "deadAt",
+            ],
+            message: "Capture job cannot terminate after its last update",
+        });
+    }
+});
+export const CaptureStatusSchema = CaptureStatusResponseSchema;
+export const CaptureReliabilityResultSchema = z
+    .object({
+    reliability: ReliabilityMetadataSchema,
+    acknowledgement: CaptureAcknowledgementSchema.nullable(),
+})
+    .strict()
+    .superRefine((result, context) => {
+    if (result.reliability.operation !== "capture") {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "operation"],
+            message: "A capture result must identify the capture operation",
+        });
+    }
+    if (result.reliability.status === "failed") {
+        if (result.acknowledgement !== null) {
+            context.addIssue({
+                code: "custom",
+                path: ["acknowledgement"],
+                message: "A failed capture cannot be acknowledged",
+            });
+        }
+        return;
+    }
+    if (result.acknowledgement === null) {
+        context.addIssue({
+            code: "custom",
+            path: ["acknowledgement"],
+            message: "A non-failed capture must include an acknowledgement",
+        });
+        return;
+    }
+    if (result.acknowledgement.state === "queued_local" &&
+        (result.reliability.status !== "degraded" ||
+            result.reliability.source !== "local_queue" ||
+            result.reliability.fallback !== "local_queue")) {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability"],
+            message: "A locally queued capture must report degraded local-queue use",
+        });
+    }
+    if (result.acknowledgement.state === "committed_server" &&
+        (result.reliability.status !== "ok" ||
+            result.reliability.source !== "live" ||
+            result.reliability.fallback !== "none")) {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability"],
+            message: "A server-committed capture must report a live success",
+        });
+    }
+    if (result.acknowledgement.state === "committed_server" &&
+        result.acknowledgement.replayed &&
+        !result.reliability.reasons.includes("idempotent_replay")) {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "reasons"],
+            message: "A replayed acknowledgement must identify idempotent replay",
+        });
+    }
+});
+const GuardConfirmationSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("approval"),
+        command: z.string().trim().min(1).max(500),
+        expiresAt: z.iso.datetime({ offset: true }),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("break_glass"),
+        command: z.string().trim().min(1).max(500),
+        expiresAt: z.iso.datetime({ offset: true }),
+    })
+        .strict(),
+]);
+export const ReliableGuardDecisionSchema = z
+    .discriminatedUnion("decision", [
+    z
+        .object({
+        decision: z.literal("allow"),
+        checkId: z.uuid(),
+        requiresConfirmation: z.literal(false),
+        matchedRuleIds: z.array(z.uuid()),
+    })
+        .strict(),
+    z
+        .object({
+        decision: z.literal("block"),
+        checkId: z.uuid(),
+        requiresConfirmation: z.literal(true),
+        blockingRuleIds: z.array(z.uuid()),
+        confirmation: GuardConfirmationSchema,
+    })
+        .strict(),
+    z
+        .object({
+        decision: z.literal("override"),
+        checkId: z.uuid(),
+        requiresConfirmation: z.literal(false),
+        overriddenRuleIds: z.array(z.uuid()),
+        override: z
+            .object({
+            id: z.uuid(),
+            reason: z.string().trim().min(1).max(1_000),
+            auditPending: z.boolean(),
+        })
+            .strict(),
+    })
+        .strict(),
+])
+    .superRefine((decision, context) => {
+    if (decision.decision === "block" &&
+        decision.confirmation.kind === "approval" &&
+        decision.blockingRuleIds.length === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["blockingRuleIds"],
+            message: "Rule approval requires at least one blocking rule",
+        });
+    }
+});
+export const GuardReliabilityResultSchema = z
+    .object({
+    reliability: ReliabilityMetadataSchema,
+    verdict: ReliableGuardDecisionSchema,
+})
+    .strict()
+    .superRefine((result, context) => {
+    if (result.reliability.operation !== "guard") {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "operation"],
+            message: "A guard result must identify the guard operation",
+        });
+    }
+    if (result.verdict.decision === "allow" &&
+        result.reliability.status !== "ok" &&
+        result.reliability.status !== "degraded") {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "status"],
+            message: "An allow verdict must be successful or explicitly degraded",
+        });
+    }
+    if (result.verdict.decision === "block" &&
+        result.reliability.status !== "blocked") {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "status"],
+            message: "A block verdict must report blocked status",
+        });
+    }
+    if (result.verdict.decision === "override" &&
+        result.reliability.status !== "overridden") {
+        context.addIssue({
+            code: "custom",
+            path: ["reliability", "status"],
+            message: "An override verdict must report overridden status",
+        });
+    }
+    if (result.verdict.decision === "block" &&
+        result.verdict.blockingRuleIds.length === 0) {
+        const outageReasons = [
+            "policy_unavailable",
+            "policy_expired",
+            "no_usable_cache",
+        ];
+        if (result.verdict.confirmation.kind !== "break_glass" ||
+            !result.reliability.reasons.some((reason) => outageReasons.includes(reason))) {
+            context.addIssue({
+                code: "custom",
+                path: ["verdict", "confirmation"],
+                message: "A policy-outage block must provide break-glass confirmation and an outage reason",
+            });
+        }
+    }
+});
+export const AgentReliabilityCapabilitiesSchema = z
+    .object({
+    contractVersion: ReliabilityContractVersionSchema,
+    agent: z.string().trim().min(1).max(100),
+    contextDelivery: z.enum(["none", "prompt", "pre_action"]),
+    captureDurability: z.enum([
+        "none",
+        "memory",
+        "local_disk",
+        "server",
+    ]),
+    guardBoundaryCoverage: z.enum(["none", "partial", "full"]),
+    guardedActions: z.array(GuardActionSchema),
+    enforcement: z.enum(["none", "context_only", "deny", "confirm"]),
+    stateDurability: z.enum(["none", "memory", "local_disk", "server"]),
+    runtimeCoverage: z.array(z.enum(["local", "cloud"])).min(1),
+})
+    .strict()
+    .superRefine((capabilities, context) => {
+    if (capabilities.guardBoundaryCoverage === "none" &&
+        capabilities.guardedActions.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["guardedActions"],
+            message: "An integration without guard boundaries cannot list actions",
+        });
+    }
+    if (capabilities.guardBoundaryCoverage !== "none" &&
+        capabilities.guardedActions.length === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["guardedActions"],
+            message: "A guarded integration must list its covered actions",
+        });
+    }
+    if ((capabilities.enforcement === "deny" ||
+        capabilities.enforcement === "confirm") &&
+        capabilities.guardBoundaryCoverage === "none") {
+        context.addIssue({
+            code: "custom",
+            path: ["enforcement"],
+            message: "Enforcement requires a host mutation boundary",
+        });
+    }
+    if (new Set(capabilities.runtimeCoverage).size !==
+        capabilities.runtimeCoverage.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["runtimeCoverage"],
+            message: "Runtime coverage entries must be unique",
+        });
+    }
+});
+//# sourceMappingURL=reliability-schemas.js.map