@inflexa-ai/harness 0.1.1

package/dist/auth/types.js

@@ -0,0 +1,61 @@
+/**
+ * Request identity — typed value objects and the two lifetime-typed bundles.
+ *
+ * Per-request identity is decomposed into small immutable value objects
+ * (`Identity`, `Scope`, `Credential`, `Provenance`, `RunFrame`) plus an opaque
+ * `auth` capability (`AuthContext`), instead of the old flat `Session`
+ * grab-bag. The `auth` capability is the sole carrier of credential/org behind
+ * a session — there is no top-level `orgId` or `credential` field. Optional
+ * concerns are whole present-or-absent sub-objects: a `RunFrame` exists or it
+ * doesn't; a `Credential` is an opaque bearer capability — never a nullable
+ * field. Its concrete shape is a managed refinement; the harness never inspects it.
+ *
+ * Two bundles compose those objects with honest lifetimes:
+ *   - `RequestSession` — the live HTTP door. No RunFrame; never JSON-serialized
+ *     into durable state.
+ *   - `RunSession` — durable, JSON-serializable. Carries a `RunFrame`; minted
+ *     only at the run-authorization seam.
+ *
+ * Neither bundle carries resolved billing headers — billing is resolved
+ * lazily at the LLM call site (see `harness/billing/resolver.ts`).
+ */
+/**
+ * Derive the `{ resourceType, resourceId }` a scope resolves through.
+ * Analysis → `{ "analysis", analysisId }`; target-assessment →
+ * `{ "billing_context", billingContextId }` (TA resolves billing via the
+ * billing-context discriminator until it is a first-class resource).
+ */
+export function scopeResource(scope) {
+    return scope.kind === "analysis"
+        ? { resourceType: "analysis", resourceId: scope.analysisId }
+        : { resourceType: "billing_context", resourceId: scope.billingContextId };
+}
+/** The value stamped into the workload tag — the workload id for this scope. */
+export function scopeWorkloadId(scope) {
+    return scope.kind === "analysis" ? scope.analysisId : scope.targetAssessmentId;
+}
+/**
+ * Derive a child session for a sub-agent call — provenance only. Sets the
+ * child `agentId` and appends it to `callPath`, leaving identity, scope, and
+ * auth untouched. Works on either bundle (the input type is preserved).
+ */
+export function forSubAgent(session, agentId) {
+    return {
+        ...session,
+        provenance: {
+            agentId,
+            callPath: [...session.provenance.callPath, agentId],
+        },
+    };
+}
+/**
+ * Derive a child `RunSession` for a sandbox step — pure value derivation.
+ * Sets `runFrame.stepId`; identity, scope, auth, and provenance are
+ * unchanged. Used by parents when computing child workflow input.
+ */
+export function forStep(parent, stepId) {
+    return {
+        ...parent,
+        runFrame: { runId: parent.runFrame.runId, stepId },
+    };
+}

package/dist/billing/cached-resolver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generic single-flight LRU+TTL resolver.
+ *
+ * Resolves an input to a value via `fetch`, caching success only behind a
+ * bounded LRU with per-entry TTL. Concurrent callers for the same key coalesce
+ * onto one in-flight fetch; a fetch that throws is not cached and clears its
+ * in-flight slot. Callers supply their own key formula, fetch+validate step,
+ * and (optionally) cache hit/miss metrics; this module owns eviction,
+ * coalescing, and expiry — the deep, drift-prone plumbing.
+ */
+export interface CachedResolverMetrics {
+    onHit(): void;
+    /** Recorded once per upstream fetch — coalesced callers do not count. */
+    onMiss(): void;
+}
+export interface CachedResolverConfig<In, Out> {
+    readonly ttlMs: number;
+    readonly maxEntries: number;
+    readonly keyFn: (input: In) => string;
+    readonly fetch: (input: In) => Promise<Out>;
+    readonly metrics?: CachedResolverMetrics;
+}
+export declare function createCachedResolver<In, Out>(cfg: CachedResolverConfig<In, Out>): (input: In) => Promise<Out>;

package/dist/billing/cached-resolver.js

@@ -0,0 +1,61 @@
+/**
+ * Generic single-flight LRU+TTL resolver.
+ *
+ * Resolves an input to a value via `fetch`, caching success only behind a
+ * bounded LRU with per-entry TTL. Concurrent callers for the same key coalesce
+ * onto one in-flight fetch; a fetch that throws is not cached and clears its
+ * in-flight slot. Callers supply their own key formula, fetch+validate step,
+ * and (optionally) cache hit/miss metrics; this module owns eviction,
+ * coalescing, and expiry — the deep, drift-prone plumbing.
+ */
+export function createCachedResolver(cfg) {
+    // Map insertion order doubles as LRU recency: a hit re-inserts the key at
+    // the tail; eviction drops the head (oldest).
+    const cache = new Map();
+    const inflight = new Map();
+    function readFresh(key) {
+        const entry = cache.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            cache.delete(key);
+            return undefined;
+        }
+        cache.delete(key);
+        cache.set(key, entry);
+        return entry.value;
+    }
+    function store(key, value) {
+        cache.set(key, { value, expiresAt: Date.now() + cfg.ttlMs });
+        while (cache.size > cfg.maxEntries) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
+    }
+    return async function resolve(input) {
+        const key = cfg.keyFn(input);
+        const fresh = readFresh(key);
+        if (fresh !== undefined) {
+            cfg.metrics?.onHit();
+            return fresh;
+        }
+        const pending = inflight.get(key);
+        if (pending)
+            return pending;
+        cfg.metrics?.onMiss();
+        const promise = (async () => {
+            const value = await cfg.fetch(input);
+            store(key, value);
+            return value;
+        })();
+        inflight.set(key, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            inflight.delete(key);
+        }
+    };
+}

package/dist/billing/noop-resolver.d.ts

@@ -0,0 +1,6 @@
+import type { ResolveBilling } from "./resolver.js";
+/**
+ * Local/OSS billing resolver: resolves to an empty header map. No upstream
+ * call, no credential reads. Wire calls carry no attribution headers.
+ */
+export declare function createNoopBillingResolver(): ResolveBilling;

package/dist/billing/noop-resolver.js

@@ -0,0 +1,7 @@
+/**
+ * Local/OSS billing resolver: resolves to an empty header map. No upstream
+ * call, no credential reads. Wire calls carry no attribution headers.
+ */
+export function createNoopBillingResolver() {
+    return async () => ({});
+}

package/dist/billing/noop-run-charge.d.ts

@@ -0,0 +1,6 @@
+import type { RunCharge } from "./run-charge.js";
+/**
+ * Local/OSS run-charge seam: open and close are both no-ops. No external
+ * billing ledger in the cloud-free build.
+ */
+export declare function createNoopRunCharge(): RunCharge;

package/dist/billing/noop-run-charge.js

@@ -0,0 +1,10 @@
+/**
+ * Local/OSS run-charge seam: open and close are both no-ops. No external
+ * billing ledger in the cloud-free build.
+ */
+export function createNoopRunCharge() {
+    return {
+        open: async () => { },
+        close: async () => { },
+    };
+}

package/dist/billing/resolver.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Billing attribution seam.
+ *
+ * Defines the `ResolveBilling` contract the provider calls at the
+ * LLM/embedding call site, plus the session view and fetcher types a
+ * concrete resolver implements. The provider calls `resolveBilling(session)`
+ * just before the wire call; read-only routes never call it, so they never
+ * incur a billing round-trip.
+ *
+ * This module is the vendor-neutral seam: it declares types only. A concrete
+ * resolver (managed/upstream-backed or noop) supplies the fetch + assembly
+ * behavior behind the `ResolveBilling` function type.
+ */
+import type { AuthContext, BillingSessionView, Credential, ResourceCoordinates } from "../auth/types.js";
+export type BillingMap = Record<string, string>;
+/** Final wire-format header map sent to the upstream gateway. */
+export type BillingHeaders = Record<string, string>;
+/**
+ * Result of a single billing-attribution fetch. The seam's own type — a
+ * concrete resolver's richer result (e.g. a generic upstream envelope)
+ * structurally satisfies it. The failure branch carries what the resolver
+ * needs to raise a `BillingResolutionError`.
+ */
+export type BillingFetchResult = {
+    ok: true;
+    data: BillingMap;
+} | {
+    ok: false;
+    status: number;
+    error: {
+        error: string;
+        message: string;
+    };
+};
+/**
+ * The minimal session view a resolver reads. The cached map is keyed by
+ * `(user, resourceType, resourceId)` (from `identity`/`scope` on
+ * `BillingSessionView`); header assembly additionally consumes
+ * `provenance`/`runFrame` (per-call). The fetch resolves the credential
+ * + org via `getAuth(session)`, so only the opaque `auth` is needed here —
+ * `AgentSession` structurally satisfies it.
+ */
+export interface ResolvableSession extends BillingSessionView {
+    readonly auth: AuthContext;
+}
+/**
+ * Resolve the FINAL wire headers at the call site. The raw attribution map is
+ * fetched once per `(user, resource)` and cached; the per-call identity tags
+ * (`agentId`/`runId`/`stepId`) vary within that key, so header assembly runs
+ * POST-CACHE on every call against the live `session` — assembled headers are
+ * never cached.
+ */
+export type ResolveBilling = (session: ResolvableSession) => Promise<BillingHeaders>;
+/**
+ * The upstream call seam — overridable in tests with a fake. A concrete
+ * resolver resolves the attribution map for the given credential/org/coords.
+ */
+export type BillingFetcher = (credential: Credential, orgId: string, coords: ResourceCoordinates) => Promise<BillingFetchResult>;
+/** A billing-resolution failure (e.g. 403/404). Fails the LLM call. */
+export declare class BillingResolutionError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}

package/dist/billing/resolver.js

@@ -0,0 +1,24 @@
+/**
+ * Billing attribution seam.
+ *
+ * Defines the `ResolveBilling` contract the provider calls at the
+ * LLM/embedding call site, plus the session view and fetcher types a
+ * concrete resolver implements. The provider calls `resolveBilling(session)`
+ * just before the wire call; read-only routes never call it, so they never
+ * incur a billing round-trip.
+ *
+ * This module is the vendor-neutral seam: it declares types only. A concrete
+ * resolver (managed/upstream-backed or noop) supplies the fetch + assembly
+ * behavior behind the `ResolveBilling` function type.
+ */
+/** A billing-resolution failure (e.g. 403/404). Fails the LLM call. */
+export class BillingResolutionError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(`Billing resolution failed (${status} ${code}): ${message}`);
+        this.status = status;
+        this.code = code;
+        this.name = "BillingResolutionError";
+    }
+}

package/dist/billing/run-charge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `RunCharge` — the run-level billing-bracket seam.
+ *
+ * `executeAnalysis` opens a running charge at init and closes it on the
+ * terminal path with one of four reasons. A managed embedder wires an
+ * external running-charge bracket; OSS wires a no-op. The harness only ever sees this
+ * interface — the body brackets the run, the embedder owns the ledger.
+ */
+import type { AgentSession } from "../auth/types.js";
+export interface RunCharge {
+    /** Open the run's running charge at init. */
+    open(args: {
+        analysisId: string;
+        runId: string;
+        session: AgentSession;
+    }): Promise<void>;
+    /** Close the run's running charge with one of four terminal reasons. */
+    close(args: {
+        analysisId: string;
+        runId: string;
+        reason: "ok" | "error" | "canceled" | "budget_exceeded";
+        session: AgentSession;
+    }): Promise<void>;
+}

package/dist/billing/run-charge.js

@@ -0,0 +1,9 @@
+/**
+ * `RunCharge` — the run-level billing-bracket seam.
+ *
+ * `executeAnalysis` opens a running charge at init and closes it on the
+ * terminal path with one of four reasons. A managed embedder wires an
+ * external running-charge bracket; OSS wires a no-op. The harness only ever sees this
+ * interface — the body brackets the run, the embedder owns the ledger.
+ */
+export {};

package/dist/config/resource-limits.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ *
+ * Validates sandbox resource requests against cluster maximums.
+ * Used by K8sSandbox.
+ */
+import { z } from "zod";
+export declare const GpuSpecSchema: z.ZodObject<{
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ResourceSpecSchema: z.ZodObject<{
+    cpu: z.ZodNumber;
+    memoryGb: z.ZodNumber;
+    gpu: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ResourceLimitsSchema: z.ZodObject<{
+    maxCpu: z.ZodNumber;
+    maxMemoryGb: z.ZodNumber;
+    maxGpuCount: z.ZodNumber;
+}, z.core.$strip>;
+export declare const MachineBudgetSchema: z.ZodObject<{
+    cpu: z.ZodNumber;
+    memoryGb: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ResourcePolicySchema: z.ZodObject<{
+    perStep: z.ZodObject<{
+        maxCpu: z.ZodNumber;
+        maxMemoryGb: z.ZodNumber;
+        maxGpuCount: z.ZodNumber;
+    }, z.core.$strip>;
+    budget: z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryGb: z.ZodNumber;
+    }, z.core.$strip>;
+    ephemeral: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodNumber;
+        memoryGb: z.ZodNumber;
+        gpu: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GpuSpec = z.infer<typeof GpuSpecSchema>;
+export type ResourceSpec = z.infer<typeof ResourceSpecSchema>;
+export type ResourceLimits = z.infer<typeof ResourceLimitsSchema>;
+export type MachineBudget = z.infer<typeof MachineBudgetSchema>;
+export type ResourcePolicy = z.infer<typeof ResourcePolicySchema>;
+/** Default LLM-turn budget for a sandbox agent step. Covers simple,
+ *  standard, and complex analyses — extra headroom on simple steps is
+ *  cheaper than truncating complex ones. */
+export declare const DEFAULT_SANDBOX_MAX_STEPS = 75;
+export declare class ResourceLimitsConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load resource limits from environment variables.
+ *
+ * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
+ * @throws ResourceLimitsConfigError if configuration is invalid
+ */
+export declare function loadResourceLimits(): ResourceLimits;
+/**
+ * Validate an embedder-supplied resource policy.
+ *
+ * Invariant: a maximum-size step must be admissible against an empty budget,
+ * so the per-step ceilings may not exceed the machine budget.
+ * @throws ResourceLimitsConfigError if the policy is invalid
+ */
+export declare function parseResourcePolicy(input: unknown): ResourcePolicy;
+/**
+ * Clamp a resource request to cluster limits (cap, don't throw).
+ * Returns a new spec with values capped to the configured maximums.
+ */
+export declare function clampResources(spec: ResourceSpec, limits: ResourceLimits): ResourceSpec;

package/dist/config/resource-limits.js

@@ -0,0 +1,116 @@
+/**
+ * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ *
+ * Validates sandbox resource requests against cluster maximums.
+ * Used by K8sSandbox.
+ */
+import { z } from "zod";
+// ── Schemas ─────────────────────────────────────────────────────────
+export const GpuSpecSchema = z.object({
+    count: z.number().int().positive(),
+});
+export const ResourceSpecSchema = z.object({
+    cpu: z.number().positive(),
+    memoryGb: z.number().positive(),
+    gpu: GpuSpecSchema.optional(),
+});
+export const ResourceLimitsSchema = z.object({
+    maxCpu: z.number().positive(),
+    maxMemoryGb: z.number().positive(),
+    maxGpuCount: z.number().int().nonnegative(),
+});
+export const MachineBudgetSchema = z.object({
+    cpu: z.number().positive(),
+    memoryGb: z.number().positive(),
+});
+export const ResourcePolicySchema = z.object({
+    perStep: ResourceLimitsSchema,
+    budget: MachineBudgetSchema,
+    ephemeral: ResourceSpecSchema.optional(),
+});
+/** Default LLM-turn budget for a sandbox agent step. Covers simple,
+ *  standard, and complex analyses — extra headroom on simple steps is
+ *  cheaper than truncating complex ones. */
+export const DEFAULT_SANDBOX_MAX_STEPS = 75;
+// ── Error ───────────────────────────────────────────────────────────
+export class ResourceLimitsConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ResourceLimitsConfigError";
+    }
+}
+// ── Parsing ─────────────────────────────────────────────────────────
+function parsePositiveNumber(name, value) {
+    if (!value) {
+        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
+    }
+    const num = Number(value);
+    if (isNaN(num) || num <= 0) {
+        throw new ResourceLimitsConfigError(`${name} must be a positive number, got: ${value}`);
+    }
+    return num;
+}
+function parseNonNegativeInt(name, value) {
+    if (!value) {
+        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
+    }
+    const num = Number(value);
+    if (isNaN(num) || num < 0) {
+        throw new ResourceLimitsConfigError(`${name} must be a non-negative number, got: ${value}`);
+    }
+    if (!Number.isInteger(num)) {
+        throw new ResourceLimitsConfigError(`${name} must be an integer, got: ${value}`);
+    }
+    return num;
+}
+/**
+ * Load resource limits from environment variables.
+ *
+ * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
+ * @throws ResourceLimitsConfigError if configuration is invalid
+ */
+export function loadResourceLimits() {
+    const maxCpu = parsePositiveNumber("SANDBOX_MAX_CPU", process.env.SANDBOX_MAX_CPU);
+    const maxMemoryGb = parsePositiveNumber("SANDBOX_MAX_MEMORY_GB", process.env.SANDBOX_MAX_MEMORY_GB);
+    const maxGpuCount = parseNonNegativeInt("SANDBOX_MAX_GPU_COUNT", process.env.SANDBOX_MAX_GPU_COUNT);
+    const limits = { maxCpu, maxMemoryGb, maxGpuCount };
+    const result = ResourceLimitsSchema.safeParse(limits);
+    if (!result.success) {
+        throw new ResourceLimitsConfigError(`Invalid resource limits configuration: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Validate an embedder-supplied resource policy.
+ *
+ * Invariant: a maximum-size step must be admissible against an empty budget,
+ * so the per-step ceilings may not exceed the machine budget.
+ * @throws ResourceLimitsConfigError if the policy is invalid
+ */
+export function parseResourcePolicy(input) {
+    const result = ResourcePolicySchema.safeParse(input);
+    if (!result.success) {
+        throw new ResourceLimitsConfigError(`Invalid resource policy: ${result.error.message}`);
+    }
+    const policy = result.data;
+    if (policy.perStep.maxCpu > policy.budget.cpu) {
+        throw new ResourceLimitsConfigError(`perStep.maxCpu (${policy.perStep.maxCpu}) exceeds budget.cpu (${policy.budget.cpu}) — a maximum-size step could never be scheduled`);
+    }
+    if (policy.perStep.maxMemoryGb > policy.budget.memoryGb) {
+        throw new ResourceLimitsConfigError(`perStep.maxMemoryGb (${policy.perStep.maxMemoryGb}) exceeds budget.memoryGb (${policy.budget.memoryGb}) — a maximum-size step could never be scheduled`);
+    }
+    return policy;
+}
+/**
+ * Clamp a resource request to cluster limits (cap, don't throw).
+ * Returns a new spec with values capped to the configured maximums.
+ */
+export function clampResources(spec, limits) {
+    return {
+        cpu: Math.min(spec.cpu, limits.maxCpu),
+        memoryGb: Math.min(spec.memoryGb, limits.maxMemoryGb),
+        ...(spec.gpu && {
+            gpu: { count: Math.min(spec.gpu.count, limits.maxGpuCount) },
+        }),
+    };
+}

package/dist/contracts/analogy-report.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Analogy Report — produced by the `generateAnalogyReport` tool. Single
+ * source of truth for the JSON envelope returned to the conversation
+ * agent. Both Cortex and the frontend import from this module.
+ *
+ * Coverage discipline mirrors `target-dossier.ts`: every analogy carries a
+ * `coverage` discriminator. Only the extraction phase is allowed to throw;
+ * search-phase failures surface via `coverage: "search_failed" |
+ * "queried_no_data" | "not_loaded"`.
+ */
+import { z } from "zod";
+export declare const AnalogyCoverageSchema: z.ZodEnum<{
+    available: "available";
+    queried_no_data: "queried_no_data";
+    search_failed: "search_failed";
+    not_loaded: "not_loaded";
+}>;
+export type AnalogyCoverage = z.infer<typeof AnalogyCoverageSchema>;
+export declare const AnalogyReportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    problemSummary: z.ZodString;
+    problemObjects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>>;
+    problemRelations: z.ZodArray<z.ZodString>;
+    keyTerms: z.ZodArray<z.ZodString>;
+    analogies: z.ZodArray<z.ZodObject<{
+        targetDomain: z.ZodString;
+        analogyTitle: z.ZodString;
+        objectMappings: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            target: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>;
+        sharedRelations: z.ZodString;
+        coverage: z.ZodEnum<{
+            available: "available";
+            queried_no_data: "queried_no_data";
+            search_failed: "search_failed";
+            not_loaded: "not_loaded";
+        }>;
+        solutions: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            sourceDomain: z.ZodString;
+            description: z.ZodString;
+            keyConcepts: z.ZodArray<z.ZodString>;
+            relevance: z.ZodString;
+            sources: z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+            githubRepos: z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const AnalogyReportErrorSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "extraction-failed": "extraction-failed";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const AnalogicalReasonerOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    problemSummary: z.ZodString;
+    problemObjects: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>>;
+    problemRelations: z.ZodArray<z.ZodString>;
+    keyTerms: z.ZodArray<z.ZodString>;
+    analogies: z.ZodArray<z.ZodObject<{
+        targetDomain: z.ZodString;
+        analogyTitle: z.ZodString;
+        objectMappings: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            target: z.ZodString;
+            rationale: z.ZodString;
+        }, z.core.$strip>>;
+        sharedRelations: z.ZodString;
+        coverage: z.ZodEnum<{
+            available: "available";
+            queried_no_data: "queried_no_data";
+            search_failed: "search_failed";
+            not_loaded: "not_loaded";
+        }>;
+        solutions: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            sourceDomain: z.ZodString;
+            description: z.ZodString;
+            keyConcepts: z.ZodArray<z.ZodString>;
+            relevance: z.ZodString;
+            sources: z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+            githubRepos: z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "extraction-failed": "extraction-failed";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type AnalogyReport = z.infer<typeof AnalogyReportSchema>;
+export type AnalogyReportError = z.infer<typeof AnalogyReportErrorSchema>;
+export type AnalogicalReasonerOutput = z.infer<typeof AnalogicalReasonerOutputSchema>;

package/dist/contracts/analogy-report.js

@@ -0,0 +1,50 @@
+/**
+ * Analogy Report — produced by the `generateAnalogyReport` tool. Single
+ * source of truth for the JSON envelope returned to the conversation
+ * agent. Both Cortex and the frontend import from this module.
+ *
+ * Coverage discipline mirrors `target-dossier.ts`: every analogy carries a
+ * `coverage` discriminator. Only the extraction phase is allowed to throw;
+ * search-phase failures surface via `coverage: "search_failed" |
+ * "queried_no_data" | "not_loaded"`.
+ */
+import { z } from "zod";
+export const AnalogyCoverageSchema = z.enum(["available", "queried_no_data", "search_failed", "not_loaded"]);
+export const AnalogyReportSchema = z.object({
+    schemaVersion: z.literal("1"),
+    problemSummary: z.string(),
+    problemObjects: z.array(z.object({ name: z.string(), role: z.string() })),
+    problemRelations: z.array(z.string()),
+    keyTerms: z.array(z.string()),
+    analogies: z.array(z.object({
+        targetDomain: z.string(),
+        analogyTitle: z.string(),
+        objectMappings: z.array(z.object({
+            source: z.string(),
+            target: z.string(),
+            rationale: z.string(),
+        })),
+        sharedRelations: z.string(),
+        coverage: AnalogyCoverageSchema,
+        solutions: z.array(z.object({
+            title: z.string(),
+            sourceDomain: z.string(),
+            description: z.string(),
+            keyConcepts: z.array(z.string()),
+            relevance: z.string(),
+            sources: z.array(z.object({ url: z.string().url(), title: z.string() })),
+            githubRepos: z.array(z.object({
+                url: z.string().url(),
+                description: z.string().optional(),
+            })),
+        })),
+    })),
+});
+export const AnalogyReportErrorSchema = z.object({
+    schemaVersion: z.literal("1"),
+    error: z.object({
+        kind: z.enum(["extraction-failed"]),
+        message: z.string(),
+    }),
+});
+export const AnalogicalReasonerOutputSchema = z.union([AnalogyReportSchema, AnalogyReportErrorSchema]);