toolroll 0.9.41 → 0.9.43

package/dist/contracts/store-json.d.ts

@@ -0,0 +1,315 @@
+/**
+ * The JSON columns the store reads back (docs/plans/zod-revamp.md, item 18): one schema per `table.column`, read
+ * through `readVersioned`. Every writer through 0.9.41 stores the bare value, and writes are unchanged, so a row reads
+ * as version 0 and is upgraded in memory only to `{ version: 1, value }`; nothing is rewritten.
+ *
+ * Existing field contracts describe known shapes, without imposing their write-time limits on old rows.
+ * Legacy cast-only readers also accepted null,
+ * partial objects and wrong-shaped JSON: LEGACY_JSON_COLUMNS names those compatibility exceptions. Such rows keep
+ * their original values and report legacyIssues, rather than newly throwing or taking a different fallback.
+ * List readers still filter, coerce, clip and default after parsing. No reader serializes a schema's output back.
+ * Contracts owned elsewhere stay there: flow.ts, route.ts, stage-output.ts, flow-send.ts and chat-content.ts
+ * (chat-tables.ts only owns DDL). Plan and handoff artifacts are files, not JSON columns in store.ts.
+ */
+import { z } from "zod";
+import { type ContractIssue } from "./contract.js";
+/** A teammate's rule for one tool action, as `teammates.ts` writes it. */
+export declare const savedToolRuleSchema: z.ZodObject<{
+    use: z.ZodEnum<{
+        ask: "ask";
+        free: "free";
+        never: "never";
+    }>;
+    limit: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        over: z.ZodNumber;
+    }, z.core.$loose>>;
+    undo: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const savedToolActionSchema: z.ZodObject<{
+    name: z.ZodString;
+    about: z.ZodString;
+    input: z.ZodNullable<z.ZodObject<{}, z.core.$loose>>;
+    readOnly: z.ZodBoolean;
+}, z.core.$loose>;
+export type SavedToolRule = z.infer<typeof savedToolRuleSchema>;
+export type SavedToolAction = z.infer<typeof savedToolActionSchema>;
+export declare const savedDecisionOptionSchema: z.ZodObject<{
+    reversible: z.ZodBoolean;
+    id: z.ZodString;
+    label: z.ZodString;
+    consequence: z.ZodString;
+}, z.core.$loose>;
+declare const STORE_COLUMN_VALUES: {
+    readonly "run_check.suites_json": z.ZodArray<z.ZodUnknown>;
+    readonly "teammate_suggestion.rule_json": z.ZodObject<{
+        use: z.ZodEnum<{
+            ask: "ask";
+            free: "free";
+            never: "never";
+        }>;
+        limit: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            over: z.ZodNumber;
+        }, z.core.$loose>>;
+        undo: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly "teammate_suggestion.was_json": z.ZodObject<{
+        use: z.ZodEnum<{
+            ask: "ask";
+            free: "free";
+            never: "never";
+        }>;
+        limit: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            over: z.ZodNumber;
+        }, z.core.$loose>>;
+        undo: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly "teammate_suggestion.evidence_json": z.ZodArray<z.ZodNumber>;
+    readonly "teammate_call.input_json": z.ZodObject<{}, z.core.$loose>;
+    readonly "teammate_tool.actions_json": z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        about: z.ZodString;
+        input: z.ZodNullable<z.ZodObject<{}, z.core.$loose>>;
+        readOnly: z.ZodBoolean;
+    }, z.core.$loose>>;
+    readonly "teammate_tool.rules_json": z.ZodObject<{}, z.core.$catchall<z.ZodObject<{
+        use: z.ZodEnum<{
+            ask: "ask";
+            free: "free";
+            never: "never";
+        }>;
+        limit: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            over: z.ZodNumber;
+        }, z.core.$loose>>;
+        undo: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    readonly "teammate_question.options_json": z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$loose>>;
+    readonly "teammate_event.detail_json": z.ZodObject<{}, z.core.$loose>;
+    readonly "flow_card.source_json": z.ZodObject<{
+        label: z.ZodString;
+    }, z.core.$loose>;
+    readonly "flow_comment.mentions_json": z.ZodArray<z.ZodUnknown>;
+    readonly "task_scope.touches": z.ZodLazy<z.ZodArray<z.ZodString>>;
+    /** Read by the scope contract's `parseAcceptanceCriteria` (`scope.ts`), which owns the criterion's shape. */
+    readonly "task_scope.acceptance_json": z.ZodLazy<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+    }, z.core.$strict>>>;
+    readonly "operating_mode.terms_json": z.ZodObject<{
+        dailyRunCap: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        dailyMeasuredCapMicrousd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reviewAuto: z.ZodOptional<z.ZodBoolean>;
+        quickMint: z.ZodOptional<z.ZodBoolean>;
+        publication: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly "attended_authorization.terms_json": z.ZodObject<{
+        profileJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>;
+    readonly "approval_policy.protected_paths": z.ZodArray<z.ZodUnknown>;
+    readonly "fallback_config.entries_json": z.ZodArray<z.ZodUnknown>;
+    readonly "runner.repos": z.ZodArray<z.ZodUnknown>;
+    readonly "runner.agents": z.ZodArray<z.ZodUnknown>;
+    readonly "decision.options": z.ZodArray<z.ZodObject<{
+        reversible: z.ZodBoolean;
+        id: z.ZodString;
+        label: z.ZodString;
+        consequence: z.ZodString;
+    }, z.core.$loose>>;
+    readonly "tool_seal.tools_json": z.ZodArray<z.ZodUnknown>;
+    readonly "run_tool.tools_json": z.ZodObject<{
+        tools: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        skipped: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        fence: z.ZodOptional<z.ZodObject<{
+            method: z.ZodString;
+            paths: z.ZodNumber;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    /** `json_extract(tools_json, '$.fence')`: the fence an attempt ran with. */
+    readonly "run_tool.tools_json.fence": z.ZodObject<{
+        method: z.ZodString;
+        paths: z.ZodNumber;
+    }, z.core.$loose>;
+    readonly "mate_ask.options_json": z.ZodArray<z.ZodString>;
+    readonly "lead_config.about_json": z.ZodArray<z.ZodUnknown>;
+    readonly "mutation.result": z.ZodUnknown;
+    readonly "plan_revision.changed_fields": z.ZodArray<z.ZodString>;
+    readonly "run_checkpoint.snapshot_json": z.ZodObject<{
+        revisionHash: z.ZodString;
+        milestones: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodEnum<{
+                blocked: "blocked";
+                completed: "completed";
+                current: "current";
+                pending: "pending";
+            }>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    readonly "telegram_conversation_part.keyboard_json": z.ZodArray<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        callback_data: z.ZodString;
+    }, z.core.$loose>>>;
+    readonly "publication_grant.capabilities": z.ZodArray<z.ZodEnum<{
+        "open-pr": "open-pr";
+        "push-branch": "push-branch";
+    }>>;
+    readonly "task_ref.zones": z.ZodArray<z.ZodUnknown>;
+    readonly "task_ref.capability_requirements": z.ZodArray<z.ZodUnknown>;
+    readonly "routine.touches": z.ZodArray<z.ZodUnknown>;
+    readonly "routine.requirements": z.ZodArray<z.ZodUnknown>;
+    /** Read by `parseAcceptanceCriteria`, as `task_scope.acceptance_json`. */
+    readonly "routine.acceptance_json": z.ZodLazy<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+    }, z.core.$strict>>>;
+    readonly "tournament_terms.agents": z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        repairModel: z.ZodString;
+        permissionMode: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    readonly "coordinator_proposal.payload_json": z.ZodObject<{}, z.core.$loose>;
+    readonly "coordinator_proposal.outcome_json": z.ZodObject<{}, z.core.$loose>;
+    readonly "mate_proposal.payload_json": z.ZodUnion<readonly [z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        operation: z.ZodEnum<{
+            decision_record: "decision_record";
+            decision_retire: "decision_retire";
+            flow_card_add: "flow_card_add";
+            flow_card_approve: "flow_card_approve";
+            flow_card_assign: "flow_card_assign";
+            flow_card_cancel: "flow_card_cancel";
+            flow_card_choose: "flow_card_choose";
+            flow_card_comment: "flow_card_comment";
+            flow_card_move: "flow_card_move";
+            flow_card_send_back: "flow_card_send_back";
+            flow_card_watch: "flow_card_watch";
+            flow_create: "flow_create";
+            flow_edit: "flow_edit";
+            flow_script_save: "flow_script_save";
+            flow_starter: "flow_starter";
+            flow_trigger_add: "flow_trigger_add";
+            flow_trigger_pause: "flow_trigger_pause";
+            flow_trigger_remove: "flow_trigger_remove";
+            flow_trigger_resume: "flow_trigger_resume";
+            kit_setup: "kit_setup";
+            knowledge_instructions: "knowledge_instructions";
+            knowledge_remove: "knowledge_remove";
+            knowledge_restore: "knowledge_restore";
+            knowledge_save: "knowledge_save";
+            lead_about_you: "lead_about_you";
+            result_accept: "result_accept";
+            scope_approve: "scope_approve";
+            skill_disable: "skill_disable";
+            skill_enable: "skill_enable";
+            skill_import: "skill_import";
+            skill_restore: "skill_restore";
+            skill_test: "skill_test";
+            task_cancel: "task_cancel";
+            task_resume: "task_resume";
+            teammate_answer: "teammate_answer";
+            teammate_create: "teammate_create";
+            teammate_memory: "teammate_memory";
+            teammate_note: "teammate_note";
+            teammate_routine: "teammate_routine";
+            teammate_soul: "teammate_soul";
+            teammate_state: "teammate_state";
+            teammate_tools: "teammate_tools";
+            teammate_undo: "teammate_undo";
+            tool_add: "tool_add";
+            tool_remove: "tool_remove";
+        }>;
+        request: z.ZodObject<{}, z.core.$catchall<z.ZodUnknown>>;
+        repo: z.ZodString;
+        title: z.ZodString;
+        terms: z.ZodArray<z.ZodString>;
+        stamp: z.ZodString;
+        state: z.ZodObject<{}, z.core.$catchall<z.ZodUnknown>>;
+    }, z.core.$strict>, z.ZodObject<{}, z.core.$loose>]>;
+    readonly "mate_proposal.outcome_json": z.ZodObject<{}, z.core.$loose>;
+    readonly "proof_verdict.matrix_json": z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        requiredEvidence: z.ZodArray<z.ZodUnknown>;
+        state: z.ZodString;
+        detail: z.ZodArray<z.ZodUnknown>;
+        answered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                "changed-path": "changed-path";
+                check: "check";
+                "manual-review": "manual-review";
+                screenshot: "screenshot";
+            }>;
+            ref: z.ZodString;
+        }, z.core.$loose>>>;
+        review: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            judgement: z.ZodString;
+            note: z.ZodString;
+            author: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    readonly "proof_verdict.reasons_json": z.ZodArray<z.ZodUnknown>;
+    readonly "criterion_review.screenshots_json": z.ZodArray<z.ZodUnknown>;
+    readonly "repair_chain.unresolved_json": z.ZodArray<z.ZodUnknown>;
+    readonly "backend_grant.paths": z.ZodArray<z.ZodUnknown>;
+    readonly "backend_grant.mutations": z.ZodArray<z.ZodUnknown>;
+};
+export type StoreColumn = keyof typeof STORE_COLUMN_VALUES;
+export type StoreColumnValue<C extends StoreColumn> = z.infer<(typeof STORE_COLUMN_VALUES)[C]>;
+/** Every JSON column the store reads itself, by `table.column`. */
+export declare const STORE_COLUMNS: ("approval_policy.protected_paths" | "attended_authorization.terms_json" | "backend_grant.mutations" | "backend_grant.paths" | "coordinator_proposal.outcome_json" | "coordinator_proposal.payload_json" | "criterion_review.screenshots_json" | "decision.options" | "fallback_config.entries_json" | "flow_card.source_json" | "flow_comment.mentions_json" | "lead_config.about_json" | "mate_ask.options_json" | "mate_proposal.outcome_json" | "mate_proposal.payload_json" | "mutation.result" | "operating_mode.terms_json" | "plan_revision.changed_fields" | "proof_verdict.matrix_json" | "proof_verdict.reasons_json" | "publication_grant.capabilities" | "repair_chain.unresolved_json" | "routine.acceptance_json" | "routine.requirements" | "routine.touches" | "run_check.suites_json" | "run_checkpoint.snapshot_json" | "run_tool.tools_json" | "runner.agents" | "runner.repos" | "task_ref.capability_requirements" | "task_ref.zones" | "task_scope.acceptance_json" | "task_scope.touches" | "teammate_call.input_json" | "teammate_event.detail_json" | "teammate_question.options_json" | "teammate_suggestion.evidence_json" | "teammate_suggestion.rule_json" | "teammate_suggestion.was_json" | "teammate_tool.actions_json" | "teammate_tool.rules_json" | "telegram_conversation_part.keyboard_json" | "tool_seal.tools_json" | "tournament_terms.agents")[];
+/** A SQL projection, not a physical column; replay it separately after its owning column. */
+export declare const STORE_PROJECTIONS: readonly ["run_tool.tools_json.fence"];
+/** These readers historically only parsed JSON. Shape errors must not change their values or catch boundaries. */
+export declare const LEGACY_JSON_COLUMNS: readonly StoreColumn[];
+/** One column's versioned envelope: `{ version: 1, value }`, built in memory around the saved bare value. */
+export declare function storeColumnSchema<C extends StoreColumn>(column: C): z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    value: (typeof STORE_COLUMN_VALUES)[C];
+}, z.core.$strict>;
+/** What a column read finds: its value, or why not — `malformed` when the saved text is not JSON at all. */
+export type StoreColumnRead<T> = {
+    ok: true;
+    value: T;
+    legacyIssues?: ContractIssue[];
+} | {
+    ok: false;
+    malformed: boolean;
+    issues: ContractIssue[];
+};
+/**
+ * Read one saved column value (`String(raw)`, as every reader did) through its schema. Never throws: the caller keeps
+ * the fallback its reader always had.
+ */
+export declare function readStoreColumn<C extends StoreColumn>(column: C, raw: unknown): StoreColumnRead<StoreColumnValue<C>>;
+/**
+ * Read one saved column value for a reader that let a bad row throw: unreadable JSON throws the same SyntaxError
+ * `JSON.parse` threw. Legacy shape issues are advisory; only a previously enforced shape can throw.
+ */
+export declare function parseStoreColumn<C extends StoreColumn>(column: C, raw: unknown): StoreColumnValue<C>;
+/** A list of text, as `readJsonArray` always read one: unreadable or not a list is none; non-text items are dropped. */
+export declare function readStoreTextList(column: StoreColumn, raw: unknown): string[];
+/** A list read with every item as text (`String(item)`), as reasons and unresolved criteria always were; otherwise none. */
+export declare function readStoreStringifiedList(column: StoreColumn, raw: unknown): string[];
+export {};

package/dist/contracts/store-json.js

@@ -0,0 +1,196 @@
+/**
+ * The JSON columns the store reads back (docs/plans/zod-revamp.md, item 18): one schema per `table.column`, read
+ * through `readVersioned`. Every writer through 0.9.41 stores the bare value, and writes are unchanged, so a row reads
+ * as version 0 and is upgraded in memory only to `{ version: 1, value }`; nothing is rewritten.
+ *
+ * Existing field contracts describe known shapes, without imposing their write-time limits on old rows.
+ * Legacy cast-only readers also accepted null,
+ * partial objects and wrong-shaped JSON: LEGACY_JSON_COLUMNS names those compatibility exceptions. Such rows keep
+ * their original values and report legacyIssues, rather than newly throwing or taking a different fallback.
+ * List readers still filter, coerce, clip and default after parsing. No reader serializes a schema's output back.
+ * Contracts owned elsewhere stay there: flow.ts, route.ts, stage-output.ts, flow-send.ts and chat-content.ts
+ * (chat-tables.ts only owns DDL). Plan and handoff artifacts are files, not JSON columns in store.ts.
+ */
+import { z } from "zod";
+import { decisionOptionSchema } from "./decision.js";
+import { scopeTermsSchema, storedRubricSchema } from "./scope.js";
+import { criterionEvidenceSchema, proofCriterionSchema } from "./proof.js";
+import { sharedActionSchema } from "./chat-actions.js";
+import { telegramCallbackButtonSchema } from "./telegram-callback.js";
+import { readVersioned, versioned } from "./contract.js";
+/** Dynamic tool arguments, event details and operation results have no common field contract. */
+const savedObject = z.looseObject({});
+/** A JSON list; its reader filters, coerces and clips the items after parsing, as before. */
+const savedList = z.array(z.unknown());
+/** An object with a text `label`: a card's source (its reader keeps picking the fields it knows). */
+const cardSource = z.looseObject({ label: z.string() });
+/** A teammate's rule for one tool action, as `teammates.ts` writes it. */
+export const savedToolRuleSchema = z.looseObject({
+    use: z.enum(["free", "ask", "never"]),
+    limit: z.looseObject({ field: z.string(), over: z.number() }).optional(),
+    /** Another action of the same tool that undoes this one with the same input. */
+    undo: z.string().optional(),
+});
+export const savedToolActionSchema = z.looseObject({
+    name: z.string(), about: z.string(), input: savedObject.nullable(), readOnly: z.boolean(),
+});
+// Reuse the option's canonical fields, dropping only write-time text bounds on a saved row.
+export const savedDecisionOptionSchema = decisionOptionSchema.extend({
+    id: z.string(), label: z.string(), consequence: z.string(),
+}).loose();
+const savedQuestionOptionSchema = savedDecisionOptionSchema.pick({ id: true, label: true });
+const savedFenceSchema = z.looseObject({ method: z.string(), paths: z.number() });
+const savedToolsSchema = z.looseObject({
+    tools: savedList.optional(), skipped: savedList.optional(), fence: savedFenceSchema.optional(),
+});
+const savedModeTermsSchema = z.looseObject({
+    dailyRunCap: z.number().nullable().optional(), dailyMeasuredCapMicrousd: z.number().nullable().optional(),
+    reviewAuto: z.boolean().optional(), quickMint: z.boolean().optional(), publication: z.string().optional(),
+});
+const savedProgressSchema = z.looseObject({
+    revisionHash: z.string(),
+    milestones: z.array(z.looseObject({
+        id: z.string(), state: z.enum(["pending", "current", "completed", "blocked"]), note: z.string().nullable().optional(),
+    })),
+});
+const savedAgentSchema = z.looseObject({
+    provider: z.string(), model: z.string(), repairModel: z.string(), permissionMode: z.string().optional(),
+});
+const savedKeyboardSchema = z.array(z.array(telegramCallbackButtonSchema.extend({ callback_data: z.string() }).loose()));
+const savedMatrixRowSchema = proofCriterionSchema.pick({ id: true, statement: true }).extend({
+    id: z.string(), statement: z.string(), requiredEvidence: savedList, state: z.string(), detail: savedList,
+    answered: z.array(criterionEvidenceSchema.extend({ ref: z.string() }).loose()).optional(),
+    review: z.looseObject({ judgement: z.string(), note: z.string(), author: z.string() }).nullable().optional(),
+}).loose();
+const STORE_COLUMN_VALUES = {
+    "run_check.suites_json": savedList,
+    "teammate_suggestion.rule_json": savedToolRuleSchema,
+    "teammate_suggestion.was_json": savedToolRuleSchema,
+    "teammate_suggestion.evidence_json": z.array(z.number()),
+    "teammate_call.input_json": savedObject,
+    "teammate_tool.actions_json": z.array(savedToolActionSchema),
+    "teammate_tool.rules_json": z.object({}).catchall(savedToolRuleSchema),
+    "teammate_question.options_json": z.array(savedQuestionOptionSchema),
+    "teammate_event.detail_json": savedObject,
+    "flow_card.source_json": cardSource,
+    "flow_comment.mentions_json": savedList,
+    "task_scope.touches": z.lazy(() => scopeTermsSchema.unwrap().shape.touches.unwrap()),
+    /** Read by the scope contract's `parseAcceptanceCriteria` (`scope.ts`), which owns the criterion's shape. */
+    "task_scope.acceptance_json": storedRubricSchema,
+    "operating_mode.terms_json": savedModeTermsSchema,
+    "attended_authorization.terms_json": z.looseObject({ profileJson: z.string().nullable().optional() }),
+    "approval_policy.protected_paths": savedList,
+    "fallback_config.entries_json": savedList,
+    "runner.repos": savedList,
+    "runner.agents": savedList,
+    "decision.options": z.array(savedDecisionOptionSchema),
+    "tool_seal.tools_json": savedList,
+    "run_tool.tools_json": savedToolsSchema,
+    /** `json_extract(tools_json, '$.fence')`: the fence an attempt ran with. */
+    "run_tool.tools_json.fence": savedFenceSchema,
+    "mate_ask.options_json": z.array(z.string()),
+    "lead_config.about_json": savedList,
+    "mutation.result": z.unknown(),
+    "plan_revision.changed_fields": z.array(z.string()),
+    "run_checkpoint.snapshot_json": savedProgressSchema,
+    "telegram_conversation_part.keyboard_json": savedKeyboardSchema,
+    "publication_grant.capabilities": z.array(z.enum(["push-branch", "open-pr"])),
+    "task_ref.zones": savedList,
+    "task_ref.capability_requirements": savedList,
+    "routine.touches": savedList,
+    "routine.requirements": savedList,
+    /** Read by `parseAcceptanceCriteria`, as `task_scope.acceptance_json`. */
+    "routine.acceptance_json": storedRubricSchema,
+    "tournament_terms.agents": z.array(savedAgentSchema),
+    "coordinator_proposal.payload_json": savedObject,
+    "coordinator_proposal.outcome_json": savedObject,
+    // Other proposal kinds have operation-specific fields; the action variant already has a canonical contract.
+    "mate_proposal.payload_json": z.union([sharedActionSchema, savedObject]),
+    "mate_proposal.outcome_json": savedObject,
+    "proof_verdict.matrix_json": z.array(savedMatrixRowSchema),
+    "proof_verdict.reasons_json": savedList,
+    "criterion_review.screenshots_json": savedList,
+    "repair_chain.unresolved_json": savedList,
+    "backend_grant.paths": savedList,
+    "backend_grant.mutations": savedList,
+};
+/** Every JSON column the store reads itself, by `table.column`. */
+export const STORE_COLUMNS = Object.keys(STORE_COLUMN_VALUES).filter(column => column !== "run_tool.tools_json.fence");
+/** A SQL projection, not a physical column; replay it separately after its owning column. */
+export const STORE_PROJECTIONS = ["run_tool.tools_json.fence"];
+/** These readers historically only parsed JSON. Shape errors must not change their values or catch boundaries. */
+export const LEGACY_JSON_COLUMNS = [
+    "teammate_suggestion.rule_json", "teammate_suggestion.was_json", "teammate_suggestion.evidence_json",
+    "teammate_call.input_json", "teammate_tool.actions_json", "teammate_tool.rules_json", "teammate_question.options_json",
+    "teammate_event.detail_json", "task_scope.touches", "task_scope.acceptance_json", "routine.acceptance_json",
+    "operating_mode.terms_json", "attended_authorization.terms_json", "decision.options", "run_tool.tools_json",
+    "run_tool.tools_json.fence", "mate_ask.options_json", "mutation.result", "plan_revision.changed_fields",
+    "run_checkpoint.snapshot_json", "telegram_conversation_part.keyboard_json", "publication_grant.capabilities",
+    "tournament_terms.agents", "coordinator_proposal.payload_json", "coordinator_proposal.outcome_json",
+    "mate_proposal.payload_json", "mate_proposal.outcome_json",
+];
+/** One column's versioned envelope: `{ version: 1, value }`, built in memory around the saved bare value. */
+export function storeColumnSchema(column) {
+    return versioned(1, { value: STORE_COLUMN_VALUES[column] });
+}
+const SCHEMAS = new Map([...STORE_COLUMNS, ...STORE_PROJECTIONS].map(column => [column, storeColumnSchema(column)]));
+/** A saved bare value is version 0; its upgrade wraps it. */
+const UPGRADES = { 0: (payload) => ({ version: 1, value: payload["value"] }) };
+/**
+ * Read one saved column value (`String(raw)`, as every reader did) through its schema. Never throws: the caller keeps
+ * the fallback its reader always had.
+ */
+export function readStoreColumn(column, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(String(raw));
+    }
+    catch (error) {
+        return { ok: false, malformed: true, issues: [{ path: "payload", kind: "invalid", line: `payload: ${column} is not JSON (${error instanceof Error ? error.message : String(error)})` }] };
+    }
+    return readParsedColumn(column, parsed);
+}
+function readParsedColumn(column, parsed) {
+    const read = readVersioned(SCHEMAS.get(column), { value: parsed }, UPGRADES);
+    // Return the original JSON, including unknown keys, property order and own __proto__ keys. In particular, never
+    // replace old cast-only values with a schema's stripped/defaulted output. A matrix historically accepted any list.
+    const legacy = LEGACY_JSON_COLUMNS.includes(column) || (column === "proof_verdict.matrix_json" && Array.isArray(parsed));
+    if (read.ok || legacy)
+        return {
+            ok: true, value: parsed,
+            ...(!read.ok ? { legacyIssues: read.issues.map(unwrap) } : {}),
+        };
+    return { ok: false, malformed: false, issues: read.issues.map(unwrap) };
+}
+/** `value.label: required` reads as `label: required`: the envelope is the reader's, not the row's. */
+function unwrap(issue) {
+    const at = issue.path === "value" ? "payload" : issue.path.startsWith("value.") ? issue.path.slice(6) : issue.path.startsWith("value[") ? `payload${issue.path.slice(5)}` : issue.path;
+    return { ...issue, path: at, line: issue.line.startsWith(`${issue.path}:`) ? `${at}${issue.line.slice(issue.path.length)}` : issue.line };
+}
+/**
+ * Read one saved column value for a reader that let a bad row throw: unreadable JSON throws the same SyntaxError
+ * `JSON.parse` threw. Legacy shape issues are advisory; only a previously enforced shape can throw.
+ */
+export function parseStoreColumn(column, raw) {
+    const parsed = JSON.parse(String(raw));
+    const read = readParsedColumn(column, parsed);
+    if (!read.ok)
+        throw new Error(`${column}: ${read.issues.map(issue => issue.line).join("; ")}`);
+    return read.value;
+}
+/** A list of text, as `readJsonArray` always read one: unreadable or not a list is none; non-text items are dropped. */
+export function readStoreTextList(column, raw) {
+    const read = readStoreColumn(column, raw);
+    return read.ok && Array.isArray(read.value) ? read.value.filter((one) => typeof one === "string") : [];
+}
+/** A list read with every item as text (`String(item)`), as reasons and unresolved criteria always were; otherwise none. */
+export function readStoreStringifiedList(column, raw) {
+    const read = readStoreColumn(column, raw);
+    try {
+        return read.ok && Array.isArray(read.value) ? read.value.map(one => String(one)) : [];
+    }
+    catch {
+        // JSON objects can shadow toString with a non-function. The old readers caught failed coercion too.
+        return [];
+    }
+}