@open-cr-agent/cloud-contract 0.0.0-stage → 0.5.0

package/dist/providers.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** The providers the gateway knows today; GET /api/providers lists them with their paths. */
+export declare const PROVIDER_IDS: readonly ["openai", "anthropic", "openrouter", "gemini", "deepseek", "mistral", "groq", "xai", "together", "fireworks", "cerebras", "moonshot", "moonshot-cn", "kimi-coding", "zai", "zhipu", "qwen", "qwen-cn", "minimax", "minimax-cn", "siliconflow", "siliconflow-cn", "volcengine", "qianfan", "hunyuan", "stepfun", "baichuan", "longcat", "huggingface", "cohere", "vercel", "deepinfra", "perplexity", "venice", "novita", "nebius", "sambanova", "inference-net", "chutes", "upstage", "ai21", "ionos", "scaleway", "featherless", "opencode-zen"];
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+export declare const PROVIDER_ID: RegExp;
+export declare const MODEL_ID: RegExp;
+/** A path the gateway forwards, as GET /api/providers lists it. */
+export declare const GATEWAY_PATH: RegExp;
+export declare const CLOUD_PREFIX = "ocra-";
+/** Whether `model` is ocra-<provider>/<model> with a provider id and model id ocra Cloud may use. */
+export declare function isCloudModel(model: string): boolean;
+/** How a provider takes a reasoning effort; unlisted, OpenAI's `reasoning_effort`. */
+export declare const EFFORT_STYLES: readonly ["openai", "openrouter"];
+export type EffortStyle = (typeof EFFORT_STYLES)[number];
+export declare const providersAnswerSchema: z.ZodObject<{
+    providers: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const providerEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    paths: z.ZodArray<z.ZodUnknown>;
+    effort: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type ProviderEntry = z.infer<typeof providerEntrySchema>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+// The model providers ocra Cloud's gateway forwards to (ADR-0024). A model
+// named ocra-<provider>/<model> goes through the gateway with the key the
+// account stored for <provider>.
+/** The providers the gateway knows today; GET /api/providers lists them with their paths. */
+export const PROVIDER_IDS = [
+    "openai",
+    "anthropic",
+    "openrouter",
+    "gemini",
+    "deepseek",
+    "mistral",
+    "groq",
+    "xai",
+    "together",
+    "fireworks",
+    "cerebras",
+    "moonshot",
+    "moonshot-cn",
+    "kimi-coding",
+    "zai",
+    "zhipu",
+    "qwen",
+    "qwen-cn",
+    "minimax",
+    "minimax-cn",
+    "siliconflow",
+    "siliconflow-cn",
+    "volcengine",
+    "qianfan",
+    "hunyuan",
+    "stepfun",
+    "baichuan",
+    "longcat",
+    "huggingface",
+    "cohere",
+    "vercel",
+    "deepinfra",
+    "perplexity",
+    "venice",
+    "novita",
+    "nebius",
+    "sambanova",
+    "inference-net",
+    "chutes",
+    "upstage",
+    "ai21",
+    "ionos",
+    "scaleway",
+    "featherless",
+    "opencode-zen",
+];
+// What a provider id and a model id may look like. A client checks names
+// against these, not against PROVIDER_IDS, so a provider the gateway adds
+// later works without a new client.
+export const PROVIDER_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const MODEL_ID = /^[\w./:@-]{1,200}$/;
+/** A path the gateway forwards, as GET /api/providers lists it. */
+export const GATEWAY_PATH = /^\/[\w./-]+$/;
+export const CLOUD_PREFIX = "ocra-";
+/** Whether `model` is ocra-<provider>/<model> with a provider id and model id ocra Cloud may use. */
+export function isCloudModel(model) {
+    const slash = model.indexOf("/");
+    return (slash > 0 &&
+        model.startsWith(CLOUD_PREFIX) &&
+        PROVIDER_ID.test(model.slice(CLOUD_PREFIX.length, slash)) &&
+        MODEL_ID.test(model.slice(slash + 1)));
+}
+/** How a provider takes a reasoning effort; unlisted, OpenAI's `reasoning_effort`. */
+export const EFFORT_STYLES = ["openai", "openrouter"];
+// GET /api/providers. An entry that does not fit is left out on its own;
+// paths are checked one by one where they are used, and an effort style a
+// client does not know is refused there.
+export const providersAnswerSchema = z.object({ providers: z.array(z.unknown()) });
+export const providerEntrySchema = z.object({
+    name: z.string(),
+    paths: z.array(z.unknown()),
+    effort: z.unknown().optional(),
+});
+//# sourceMappingURL=providers.js.map

package/dist/redact.d.ts

@@ -0,0 +1,7 @@
+export declare const REDACTED = "[redacted]";
+/** The text with secret-looking tokens replaced, and whether any was. */
+export declare function redact(text: string): {
+    text: string;
+    redacted: boolean;
+};
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -0,0 +1,54 @@
+// Replaces secret-looking tokens in a shared finding (ADR-0028, 2): the CLI
+// before the finding leaves the machine, ocra Cloud again on what it
+// receives. fixtures/redaction-vectors.json pins what both must catch and
+// keep. It catches patterns, not every secret.
+export const REDACTED = "[redacted]";
+const PATTERNS = [
+    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g,
+    /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    /\b(ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    /\bglpat-[A-Za-z0-9_-]{20,}\b/g,
+    /\bsk-(ant-|or-|proj-)?[A-Za-z0-9_-]{20,}\b/g,
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+    /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    /\bnpm_[A-Za-z0-9]{36}\b/g,
+    /\bhttps:\/\/hooks\.slack\.com\/(services|workflows|triggers)\/[A-Za-z0-9/_-]+/g,
+    /\bhttps:\/\/(ptb\.|canary\.)?discord(app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+/g,
+];
+// The password in a URL's userinfo: postgres://user:password@host.
+const USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:)([^\s/@]+)@/gi;
+// A quoted value assigned to a name that says it is secret:
+// password = "…", "apiKey": "…", DB_PASSWORD: '…'.
+const ASSIGNED = /\b([A-Za-z0-9_.-]*(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credentials?)["']?\s*[:=]\s*)(["'`])([^"'`\n]{4,})\2/gi;
+// A long hex run with letters and digits: a key or token in hex.
+const HEX = /\b[0-9a-f]{32,}\b/gi;
+const isHexKey = (s) => /[0-9]/.test(s) && /[a-f]/i.test(s);
+// A long base64-like run that looks random: high entropy and a digit.
+// Identifiers stay under the entropy bar; a path or URL path (every segment
+// lowercase, or letters only) is left alone.
+const LONG_RUN = /[A-Za-z0-9+/_-]{32,}={0,2}/g;
+function entropy(s) {
+    const counts = new Map();
+    for (const ch of s)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let bits = 0;
+    for (const n of counts.values())
+        bits -= (n / s.length) * Math.log2(n / s.length);
+    return bits;
+}
+const isPath = (s) => s.includes("/") &&
+    s.split("/").every((seg) => /^[a-z0-9_-]*$/.test(seg) || /^[A-Za-z]+$/.test(seg));
+const looksRandom = (s) => /\d/.test(s) && entropy(s) >= 4.3 && !isPath(s);
+/** The text with secret-looking tokens replaced, and whether any was. */
+export function redact(text) {
+    let out = text;
+    for (const p of PATTERNS)
+        out = out.replace(p, REDACTED);
+    out = out.replace(USERINFO, (_m, head) => `${head}${REDACTED}@`);
+    out = out.replace(ASSIGNED, (_m, head, q) => `${head}${q}${REDACTED}${q}`);
+    out = out.replace(HEX, (m) => (isHexKey(m) ? REDACTED : m));
+    out = out.replace(LONG_RUN, (m) => (looksRandom(m) ? REDACTED : m));
+    return { text: out, redacted: out !== text };
+}
+//# sourceMappingURL=redact.js.map

package/dist/upload.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+export declare const severityCountsSchema: z.ZodCatch<z.ZodObject<{
+    critical: z.ZodCatch<z.ZodNumber>;
+    warning: z.ZodCatch<z.ZodNumber>;
+    suggestion: z.ZodCatch<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const reviewerCountsSchema: z.ZodObject<{
+    tasks: z.ZodCatch<z.ZodNumber>;
+    failedTasks: z.ZodCatch<z.ZodNumber>;
+    findings: z.ZodCatch<z.ZodObject<{
+        critical: z.ZodCatch<z.ZodNumber>;
+        warning: z.ZodCatch<z.ZodNumber>;
+        suggestion: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>;
+    costUsd: z.ZodCatch<z.ZodNumber>;
+    fixed: z.ZodCatch<z.ZodNumber>;
+    dismissed: z.ZodCatch<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReviewerCounts = z.input<typeof reviewerCountsSchema>;
+/** A finding's stable id across runs. */
+export declare const FINGERPRINT: RegExp;
+/**
+ * A finding as the CLI shares it when the account shares findings
+ * (ADR-0028, 2): already redacted and bounded (redact, MAX_FIELD), which
+ * the server does again. One that fails is left out on its own.
+ */
+export declare const sharedFindingSchema: z.ZodObject<{
+    fingerprint: z.ZodString;
+    reviewer: z.ZodString;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        suggestion: "suggestion";
+        warning: "warning";
+    }>;
+    category: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+    verification: z.ZodCatch<z.ZodNullable<z.ZodEnum<{
+        confirmed: "confirmed";
+        uncertain: "uncertain";
+        unchecked: "unchecked";
+    }>>>;
+    file: z.ZodString;
+    lineStart: z.ZodCatch<z.ZodNullable<z.ZodNumber>>;
+    lineEnd: z.ZodCatch<z.ZodNullable<z.ZodNumber>>;
+    title: z.ZodString;
+    body: z.ZodString;
+    suggestion: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+    code: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+    redacted: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+    truncated: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+}, z.core.$strip>;
+export type SharedFinding = z.input<typeof sharedFindingSchema>;
+/**
+ * The review's counts, and the shared findings in `findingList`. A finding
+ * or a reviewer's counts that do not fit read as null; the server keeps
+ * the first MAX_FINDINGS findings and the first MAX_REVIEWERS reviewers
+ * under a REVIEWER_ID, and answers what it left out as `dropped`.
+ */
+export declare const reviewUploadSchema: z.ZodObject<{
+    runId: z.ZodString;
+    repoHash: z.ZodString;
+    source: z.ZodEnum<{
+        github: "github";
+        gitlab: "gitlab";
+        local: "local";
+    }>;
+    tier: z.ZodCatch<z.ZodNullable<z.ZodEnum<{
+        full: "full";
+        lite: "lite";
+        trivial: "trivial";
+    }>>>;
+    verdict: z.ZodCatch<z.ZodNullable<z.ZodEnum<{
+        approved: "approved";
+        approved_with_comments: "approved_with_comments";
+        minor_issues: "minor_issues";
+        significant_concerns: "significant_concerns";
+    }>>>;
+    complete: z.ZodCatch<z.ZodBoolean>;
+    findings: z.ZodCatch<z.ZodObject<{
+        critical: z.ZodCatch<z.ZodNumber>;
+        warning: z.ZodCatch<z.ZodNumber>;
+        suggestion: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>;
+    files: z.ZodCatch<z.ZodObject<{
+        reviewed: z.ZodCatch<z.ZodNumber>;
+        notReviewed: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>;
+    tasks: z.ZodCatch<z.ZodObject<{
+        completed: z.ZodCatch<z.ZodNumber>;
+        failed: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>;
+    usage: z.ZodCatch<z.ZodObject<{
+        inputTokens: z.ZodCatch<z.ZodNumber>;
+        outputTokens: z.ZodCatch<z.ZodNumber>;
+        costUsd: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>;
+    durationMs: z.ZodCatch<z.ZodNumber>;
+    ocraVersion: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+    reviewers: z.ZodCatch<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodNullable<z.ZodObject<{
+        tasks: z.ZodCatch<z.ZodNumber>;
+        failedTasks: z.ZodCatch<z.ZodNumber>;
+        findings: z.ZodCatch<z.ZodObject<{
+            critical: z.ZodCatch<z.ZodNumber>;
+            warning: z.ZodCatch<z.ZodNumber>;
+            suggestion: z.ZodCatch<z.ZodNumber>;
+        }, z.core.$strip>>;
+        costUsd: z.ZodCatch<z.ZodNumber>;
+        fixed: z.ZodCatch<z.ZodNumber>;
+        dismissed: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>>>>>;
+    verification: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        confirmed: z.ZodOptional<z.ZodCatch<z.ZodNumber>>;
+        uncertain: z.ZodOptional<z.ZodCatch<z.ZodNumber>>;
+        unchecked: z.ZodOptional<z.ZodCatch<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    outcomes: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        fixed: z.ZodCatch<z.ZodNumber>;
+        dismissed: z.ZodCatch<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    findingList: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodCatch<z.ZodNullable<z.ZodObject<{
+        fingerprint: z.ZodString;
+        reviewer: z.ZodString;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            suggestion: "suggestion";
+            warning: "warning";
+        }>;
+        category: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+        verification: z.ZodCatch<z.ZodNullable<z.ZodEnum<{
+            confirmed: "confirmed";
+            uncertain: "uncertain";
+            unchecked: "unchecked";
+        }>>>;
+        file: z.ZodString;
+        lineStart: z.ZodCatch<z.ZodNullable<z.ZodNumber>>;
+        lineEnd: z.ZodCatch<z.ZodNullable<z.ZodNumber>>;
+        title: z.ZodString;
+        body: z.ZodString;
+        suggestion: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+        code: z.ZodCatch<z.ZodNullable<z.ZodString>>;
+        redacted: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+        truncated: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+    }, z.core.$strip>>>>>>;
+}, z.core.$strip>;
+export type ReviewUpload = z.input<typeof reviewUploadSchema>;
+/** What the server took: how many findings it kept, and what it left out. */
+export declare const uploadAnswerSchema: z.ZodObject<{
+    id: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    duplicate: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+    findings: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    truncated: z.ZodCatch<z.ZodOptional<z.ZodLiteral<true>>>;
+    dropped: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        findings: z.ZodOptional<z.ZodCatch<z.ZodNumber>>;
+        reviewers: z.ZodOptional<z.ZodCatch<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    findingsSkipped: z.ZodCatch<z.ZodOptional<z.ZodLiteral<"account_limit">>>;
+}, z.core.$strip>;
+export type UploadAnswer = z.input<typeof uploadAnswerSchema>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/upload.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { REPO_HASH, REVIEWER_ID, reviewSourceSchema, riskTierSchema, severitySchema, verdictSchema, verificationSchema, } from "./vocabulary.js";
+// POST /api/reviews: what a signed-in CLI sends after a review (ADR-0024,
+// ADR-0028), and what ocra Cloud answers.
+//
+// Each schema's input type is what a client sends; its output is what the
+// server keeps. Past the identifying fields, a value the server cannot use
+// becomes its default instead of refusing the upload, so a newer client (a
+// new tier, say) still has its counts kept.
+const count = z.number().int().min(0).max(1e12).catch(0);
+const costUsd = z.number().min(0).lt(1e6).catch(0);
+export const severityCountsSchema = z
+    .object({ critical: count, warning: count, suggestion: count })
+    .catch({ critical: 0, warning: 0, suggestion: 0 });
+export const reviewerCountsSchema = z.object({
+    tasks: count,
+    failedTasks: count,
+    findings: severityCountsSchema,
+    costUsd,
+    fixed: count,
+    dismissed: count,
+});
+/** A finding's stable id across runs. */
+export const FINGERPRINT = /^[\w:.-]{4,128}$/;
+const line = z.number().int().min(0).lt(10_000_000).nullable().catch(null);
+/**
+ * A finding as the CLI shares it when the account shares findings
+ * (ADR-0028, 2): already redacted and bounded (redact, MAX_FIELD), which
+ * the server does again. One that fails is left out on its own.
+ */
+export const sharedFindingSchema = z.object({
+    fingerprint: z.string().regex(FINGERPRINT),
+    reviewer: z.string().regex(REVIEWER_ID),
+    severity: severitySchema,
+    category: z.string().nullable().catch(null),
+    verification: verificationSchema.nullable().catch(null),
+    file: z.string().min(1).max(1024),
+    lineStart: line,
+    lineEnd: line,
+    title: z.string(),
+    body: z.string(),
+    suggestion: z.string().nullable().catch(null),
+    code: z.string().nullable().catch(null),
+    // Set when the CLI replaced a secret-looking string or cut a long field.
+    redacted: z.literal(true).optional().catch(undefined),
+    truncated: z.literal(true).optional().catch(undefined),
+});
+/**
+ * The review's counts, and the shared findings in `findingList`. A finding
+ * or a reviewer's counts that do not fit read as null; the server keeps
+ * the first MAX_FINDINGS findings and the first MAX_REVIEWERS reviewers
+ * under a REVIEWER_ID, and answers what it left out as `dropped`.
+ */
+export const reviewUploadSchema = z.object({
+    runId: z.string().regex(/^[\w.-]{1,64}$/),
+    repoHash: z.string().regex(REPO_HASH),
+    source: reviewSourceSchema,
+    tier: riskTierSchema.nullable().catch(null),
+    verdict: verdictSchema.nullable().catch(null),
+    // As the exit code reads it: incomplete when files went unreviewed or a
+    // critical finding could not be verified.
+    complete: z.boolean().catch(true),
+    findings: severityCountsSchema,
+    files: z.object({ reviewed: count, notReviewed: count }).catch({ reviewed: 0, notReviewed: 0 }),
+    tasks: z.object({ completed: count, failed: count }).catch({ completed: 0, failed: 0 }),
+    usage: z
+        .object({ inputTokens: count, outputTokens: count, costUsd })
+        .catch({ inputTokens: 0, outputTokens: 0, costUsd: 0 }),
+    durationMs: count,
+    ocraVersion: z
+        .string()
+        .regex(/^[\w.+-]{1,32}$/)
+        .nullable()
+        .catch(null),
+    // Added by ADR-0028; optional so a server reading older uploads still can.
+    reviewers: z
+        .record(z.string(), reviewerCountsSchema.nullable().catch(null))
+        .optional()
+        .catch(undefined),
+    verification: z
+        .object({ confirmed: count, uncertain: count, unchecked: count })
+        .partial()
+        .optional()
+        .catch(undefined),
+    outcomes: z.object({ fixed: count, dismissed: count }).optional().catch(undefined),
+    findingList: z.array(sharedFindingSchema.nullable().catch(null)).optional().catch(undefined),
+});
+/** What the server took: how many findings it kept, and what it left out. */
+export const uploadAnswerSchema = z.object({
+    id: z.string().optional().catch(undefined),
+    // A retry of a run already uploaded; nothing new was kept.
+    duplicate: z.literal(true).optional().catch(undefined),
+    findings: z.number().int().positive().optional().catch(undefined),
+    truncated: z.literal(true).optional().catch(undefined),
+    dropped: z
+        .object({ findings: count.optional(), reviewers: count.optional() })
+        .optional()
+        .catch(undefined),
+    // The account holds as many findings as it may; the counts were kept.
+    findingsSkipped: z.literal("account_limit").optional().catch(undefined),
+});
+//# sourceMappingURL=upload.js.map

package/dist/vocabulary.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export declare const VERDICTS: readonly ["approved", "approved_with_comments", "minor_issues", "significant_concerns"];
+export declare const verdictSchema: z.ZodEnum<{
+    approved: "approved";
+    approved_with_comments: "approved_with_comments";
+    minor_issues: "minor_issues";
+    significant_concerns: "significant_concerns";
+}>;
+export type Verdict = z.infer<typeof verdictSchema>;
+/** The review's risk tier, as a report records it. */
+export declare const RISK_TIERS: readonly ["trivial", "lite", "full"];
+export declare const riskTierSchema: z.ZodEnum<{
+    full: "full";
+    lite: "lite";
+    trivial: "trivial";
+}>;
+export type RiskTier = z.infer<typeof riskTierSchema>;
+export declare const SEVERITIES: readonly ["critical", "warning", "suggestion"];
+export declare const severitySchema: z.ZodEnum<{
+    critical: "critical";
+    suggestion: "suggestion";
+    warning: "warning";
+}>;
+export type Severity = z.infer<typeof severitySchema>;
+export declare const VERIFICATIONS: readonly ["confirmed", "uncertain", "unchecked"];
+export declare const verificationSchema: z.ZodEnum<{
+    confirmed: "confirmed";
+    uncertain: "uncertain";
+    unchecked: "unchecked";
+}>;
+export type Verification = z.infer<typeof verificationSchema>;
+/** Where a review ran. */
+export declare const REVIEW_SOURCES: readonly ["local", "github", "gitlab"];
+export declare const reviewSourceSchema: z.ZodEnum<{
+    github: "github";
+    gitlab: "gitlab";
+    local: "local";
+}>;
+export type ReviewSource = z.infer<typeof reviewSourceSchema>;
+/** The model tiers, strongest first (ADR-0025). */
+export declare const MODEL_TIERS: readonly ["top", "standard", "light"];
+export declare const modelTierSchema: z.ZodEnum<{
+    light: "light";
+    standard: "standard";
+    top: "top";
+}>;
+export type ModelTier = z.infer<typeof modelTierSchema>;
+/** The agents that are not reviewers (ADR-0025). */
+export declare const AGENT_ROLES: readonly ["verifier", "judge", "helper"];
+export declare const agentRoleSchema: z.ZodEnum<{
+    helper: "helper";
+    judge: "judge";
+    verifier: "verifier";
+}>;
+export type AgentRole = z.infer<typeof agentRoleSchema>;
+/** How much a model reasons before it answers (ADR-0025). */
+export declare const EFFORTS: readonly ["none", "minimal", "low", "medium", "high"];
+export declare const effortSchema: z.ZodEnum<{
+    high: "high";
+    low: "low";
+    medium: "medium";
+    minimal: "minimal";
+    none: "none";
+}>;
+export type Effort = z.infer<typeof effortSchema>;
+/** The built-in runtimes an account may name; a plugin runtime would load code. */
+export declare const RUNTIMES: readonly ["direct", "opencode"];
+export declare const runtimeSchema: z.ZodEnum<{
+    direct: "direct";
+    opencode: "opencode";
+}>;
+export type Runtime = z.infer<typeof runtimeSchema>;
+/**
+ * A reviewer id as the engine makes them: built-in ids, SARIF tool slugs
+ * (which may start with a digit) and plugin reviewers. Bounded, and without
+ * spaces or punctuation that could mean something else.
+ */
+export declare const REVIEWER_ID: RegExp;
+/** A repository as the CLI uploads it: a salted SHA-256, never its name (ADR-0028). */
+export declare const REPO_HASH: RegExp;
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/vocabulary.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+// The words both sides use. The engine's core declares the same values for
+// its own domain (core depends on nothing); the cli's tests check the two
+// agree, so a new verdict or tier cannot reach one side only.
+export const VERDICTS = [
+    "approved",
+    "approved_with_comments",
+    "minor_issues",
+    "significant_concerns",
+];
+export const verdictSchema = z.enum(VERDICTS);
+/** The review's risk tier, as a report records it. */
+export const RISK_TIERS = ["trivial", "lite", "full"];
+export const riskTierSchema = z.enum(RISK_TIERS);
+export const SEVERITIES = ["critical", "warning", "suggestion"];
+export const severitySchema = z.enum(SEVERITIES);
+export const VERIFICATIONS = ["confirmed", "uncertain", "unchecked"];
+export const verificationSchema = z.enum(VERIFICATIONS);
+/** Where a review ran. */
+export const REVIEW_SOURCES = ["local", "github", "gitlab"];
+export const reviewSourceSchema = z.enum(REVIEW_SOURCES);
+/** The model tiers, strongest first (ADR-0025). */
+export const MODEL_TIERS = ["top", "standard", "light"];
+export const modelTierSchema = z.enum(MODEL_TIERS);
+/** The agents that are not reviewers (ADR-0025). */
+export const AGENT_ROLES = ["verifier", "judge", "helper"];
+export const agentRoleSchema = z.enum(AGENT_ROLES);
+/** How much a model reasons before it answers (ADR-0025). */
+export const EFFORTS = ["none", "minimal", "low", "medium", "high"];
+export const effortSchema = z.enum(EFFORTS);
+/** The built-in runtimes an account may name; a plugin runtime would load code. */
+export const RUNTIMES = ["direct", "opencode"];
+export const runtimeSchema = z.enum(RUNTIMES);
+/**
+ * A reviewer id as the engine makes them: built-in ids, SARIF tool slugs
+ * (which may start with a digit) and plugin reviewers. Bounded, and without
+ * spaces or punctuation that could mean something else.
+ */
+export const REVIEWER_ID = /^[A-Za-z0-9][\w.:@-]{0,99}$/;
+/** A repository as the CLI uploads it: a salted SHA-256, never its name (ADR-0028). */
+export const REPO_HASH = /^[0-9a-f]{64}$/;
+//# sourceMappingURL=vocabulary.js.map

package/fixtures/memory.json

@@ -0,0 +1,27 @@
+{
+  "about": "GET /api/memory as ocra Cloud answers it. The ocra CLI applies every entry.",
+  "answer": {
+    "entries": [
+      {
+        "id": "5f0a6c1e-2b7d-4c3e-8a9f-1d2e3f4a5b6c",
+        "repoHash": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
+        "repo": "8d969eef",
+        "fingerprint": "3f9a1c7e5b2d8a40",
+        "file": "src/db.ts",
+        "title": "SQL built from input",
+        "reason": "The id is validated by the router before it gets here.",
+        "createdAt": "2026-10-04T12:00:00.000Z"
+      },
+      {
+        "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
+        "repoHash": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
+        "repo": "8d969eef",
+        "fingerprint": "a07c4e9b1d3f5a62",
+        "file": "src/retry.ts",
+        "title": "Retry without a limit",
+        "reason": "Bounded by the caller's timeout.",
+        "createdAt": "2026-10-03T08:30:00.000Z"
+      }
+    ]
+  }
+}

package/fixtures/preferences.json

@@ -0,0 +1,44 @@
+{
+  "about": "GET /api/preferences as ocra Cloud answers it once every part is saved. The ocra CLI reads all of it as account settings; ocra Cloud saves it with PUT /api/preferences and answers it back unchanged. Its models name providers with an OpenAI-compatible chat route, the only ones ocra Cloud accepts.",
+  "answer": {
+    "runtime": "direct",
+    "models": {
+      "top": ["ocra-openrouter/anthropic/claude-opus-4.1"],
+      "standard": ["ocra-openrouter/openai/gpt-5-mini", "ocra-deepseek/deepseek-chat"],
+      "light": ["ocra-gemini/gemini-2.5-flash"]
+    },
+    "agents": {
+      "effort": { "top": "high", "light": "none" },
+      "reviewers": {
+        "security": {
+          "enabled": true,
+          "models": ["ocra-openrouter/anthropic/claude-opus-4.1"],
+          "effort": "high"
+        },
+        "style": { "enabled": false }
+      },
+      "roles": { "judge": { "models": ["ocra-openai/gpt-5"], "effort": "medium" } }
+    },
+    "settings": {
+      "ultra": true,
+      "concurrency": 4,
+      "taskTimeoutMinutes": 10,
+      "runTimeoutMinutes": 30,
+      "maxCostUsd": 2.5,
+      "maxTasks": 40,
+      "verify": true,
+      "judge": true,
+      "sampling": { "temperature": 0.2, "seed": 7 },
+      "include": ["src/**"],
+      "exclude": ["**/*.snap"],
+      "rules": [
+        { "path": "src/db/**", "rule": "Queries go through the scoped() helper." },
+        { "path": ["web/**/*.tsx", "web/**/*.ts"], "rule": "No inline styles." }
+      ],
+      "plugins": ["@acme/ocra-plugin-sql"],
+      "pluginSettings": { "@acme/ocra-plugin-sql": { "dialect": "sqlite" } }
+    },
+    "updatedAt": "2026-10-04T12:00:00.000Z",
+    "version": "0b6c1f0e-5d1e-4a8e-9d0e-6f6d5f4c3b2a"
+  }
+}