prismatica 0.2.0

package/dist/records/types.js

@@ -0,0 +1,836 @@
+/**
+ * Every Prismatica record type is defined ONCE, here, as a zod schema.
+ * The schema gives runtime validation (gates fail closed on anything malformed)
+ * and the inferred static type — no second definition anywhere.
+ *
+ * All schemas are strict: unknown keys are rejected, because a record we do not
+ * fully understand is a record we cannot trust.
+ */
+import { z } from 'zod';
+// ── Risk tiers ────────────────────────────────────────────────────────────────
+export const RISK_TIERS = ['light', 'normal', 'heavy'];
+export const RiskTierSchema = z.enum(RISK_TIERS);
+// ── Lifecycle ────────────────────────────────────────────────────────────────
+/** The eight stages a change moves through, in order. */
+export const STAGES = [
+    'frame',
+    'pack',
+    'build',
+    'prove',
+    'review',
+    'accept',
+    'ship',
+    'verify',
+];
+export const StageSchema = z.enum(STAGES);
+/** The six board states (columns). */
+export const STATES = ['planned', 'building', 'checking', 'needs_you', 'shipping', 'live'];
+export const StateSchema = z.enum(STATES);
+/** Which board column a change in a given stage sits in. 'live' is reached only once its passport exists. */
+export const STAGE_TO_STATE = {
+    frame: 'planned',
+    pack: 'planned',
+    build: 'building',
+    prove: 'checking',
+    review: 'checking',
+    accept: 'needs_you',
+    ship: 'shipping',
+    verify: 'shipping',
+};
+// ── Config (.prismatica/config.json) ─────────────────────────────────────────
+const CheckToggleSchema = z.strictObject({
+    enabled: z.boolean(),
+    command: z.string().optional(),
+    note: z.string().optional(),
+});
+const SecretsCheckSchema = z.strictObject({
+    enabled: z.boolean(),
+    mode: z.enum(['gitleaks', 'regex']),
+    note: z.string().optional(),
+});
+export const ChecksSchema = z.strictObject({
+    typecheck: CheckToggleSchema,
+    lint: CheckToggleSchema,
+    unit: CheckToggleSchema,
+    build: CheckToggleSchema,
+    journeys: CheckToggleSchema,
+    secrets: SecretsCheckSchema,
+});
+export const TierRuleSchema = z.strictObject({
+    tier: RiskTierSchema,
+    paths: z.array(z.string()).min(1),
+});
+/**
+ * `govern` runs the full assurance loop (gate, hooks, signing keys). `map-only`
+ * is Atlas without governance — comprehension with no gates, for an owner who
+ * just wants to understand an app before (or without ever) adopting the gate.
+ * `prismatica upgrade` moves a repo from map-only to govern; there is no
+ * downgrade command (archive over delete — flip it back by hand if you must).
+ */
+export const PRISMATICA_MODES = ['govern', 'map-only'];
+export const ModeSchema = z.enum(PRISMATICA_MODES);
+export const ConfigSchema = z.strictObject({
+    version: z.literal(1),
+    app: z.strictObject({
+        name: z.string().min(1),
+        deployTarget: z.string().optional(),
+    }),
+    mode: ModeSchema.default('govern'),
+    stack: z.array(z.string()).default([]),
+    mainBranch: z.string().min(1).default('main'),
+    wipLimit: z.number().int().min(1).default(2),
+    defaultTier: RiskTierSchema.default('normal'),
+    tierRules: z.array(TierRuleSchema).default([]),
+    checks: ChecksSchema,
+    owner: z.strictObject({ publicKey: z.string().optional() }).default({}),
+    /**
+     * The non-retroactive compatibility boundary for release follow-through
+     * (`next`, the board): a contract `createdAt` before this timestamp is a
+     * LEGACY record — its release proof was never tracked, so it is never
+     * queued for `ship --verify` and never described as shipped or verified.
+     * Optional so every config written before this field existed keeps parsing.
+     */
+    releaseTrackingSince: z.iso.datetime().optional(),
+});
+// ── Intent (intents/<id>.md frontmatter) ─────────────────────────────────────
+export const IntentSchema = z.strictObject({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    state: z.enum(['open', 'partly', 'proven']),
+    checks: z
+        .array(z.strictObject({
+        id: z.string().min(1),
+        description: z.string().min(1),
+        status: z.enum(['unproven', 'proven']),
+    }))
+        .min(2)
+        .max(4),
+    createdAt: z.string(),
+});
+// ── Contract (contracts/<id>.md frontmatter) ─────────────────────────────────
+export const AcceptanceCheckSchema = z.strictObject({
+    id: z.string().min(1),
+    description: z.string().min(1),
+    /** A test id the check engine can trace, or `manual:<OWNER>`. */
+    test: z.string().min(1),
+});
+const AmendmentSchema = z.strictObject({
+    at: z.string(),
+    reason: z.string().min(1),
+    description: z.string().min(1),
+});
+/**
+ * The shape a recorded builder name may take: a bare identifier, no more.
+ *
+ * This is a RENDERING safety rule, not a policy about which agents exist —
+ * `Contract.builder` is interpolated into copy-ready shell commands, so it must
+ * not be able to carry shell syntax (`;`, `|`, `$(`, backticks, quotes,
+ * whitespace, a newline) into something the owner pastes. Anchored, and the
+ * first character may not be `-` so a name can never read as a flag.
+ *
+ * Deliberately NARROWER than what `open` will LAUNCH: `open` still accepts any
+ * executable the owner names, including a path like `./my-agent`. Such a name
+ * launches exactly as before and simply is not recorded — see `runOpen`. The
+ * asymmetry is the point: launching is the owner's live argv, whereas a
+ * recorded name is replayed later, out of their sight, into a paste.
+ *
+ * This constraint sits on the schema — which CLAUDE.md otherwise reserves for
+ * untrusted-input boundaries — only because `builder` is a NEW field. No
+ * record on disk carries one, so unlike an id pattern it cannot refuse to read
+ * a record that already exists.
+ */
+export const BUILDER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export const ContractSchema = z.strictObject({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    /** Linked GitHub issue (URL or #number). No contract without an issue; no merge without a contract. */
+    issue: z.string().min(1),
+    intent: z.string().optional(),
+    tier: RiskTierSchema,
+    stage: StageSchema,
+    /** Recorded at frame time and never re-baselined mid-change. */
+    baseline: z.strictObject({
+        commit: z.string().min(1),
+        branch: z.string().min(1),
+    }),
+    branch: z.string().min(1),
+    worktree: z.string().optional(),
+    /**
+     * Which agent is building THIS change (`claude`, `codex`, or another agent
+     * the owner names). Routing only — it decides what `next`/`pack`/`start`
+     * print, never who is permitted to do anything. The gate does not read it,
+     * and nothing here binds a vendor to a role: the owner may swap builder and
+     * reviewer at any point, including mid-change.
+     *
+     * OPTIONAL because every contract written before this field existed must
+     * still parse; absent means "not recorded", and the printers fall back to
+     * `DEFAULT_BUILDER`. Deliberately excluded from `contractScopeHash`, which
+     * enumerates its fields explicitly — changing the builder is not a scope
+     * change and must never stale an existing pack.
+     *
+     * CONSTRAINED to `BUILDER_NAME_PATTERN` because this value is interpolated
+     * into copy-ready commands the owner is invited to paste into a shell
+     * (`next`, `pack`, `start` all print `prismatica open <builder> <id>`). A
+     * contract rides a PR, so its bytes are not the owner's own typing by the
+     * time they are rendered; a bare identifier is the only shape that cannot
+     * carry shell syntax into that paste.
+     */
+    builder: z.string().regex(BUILDER_NAME_PATTERN).optional(),
+    /**
+     * sha256 over the COMPLETE approved Start plan — the one durable binding
+     * between a lane and the semantic document its owner said yes to.
+     *
+     * `start --resume` exists to finish a change whose lane already exists, and
+     * it must be unable to substitute a DIFFERENT plan. Comparing the fields
+     * `runFrame` derives is not enough: two plans can produce a byte-identical
+     * contract while disagreeing about the request, the rationale, current and
+     * desired behaviour, the Delta or the Planned Flow — every part of the
+     * meaning the owner approved that a contract does not carry. One canonical
+     * digest answers that question once, instead of a widening set of partial
+     * comparisons that can only ever cover the fields someone remembered.
+     *
+     * Written by `frame` — the exact point from which `--resume` becomes
+     * possible — from `startPlanHash` in `commands/start.ts`, which owns the
+     * canonical representation (the parsed proposal with the echoed `snapshot`
+     * omitted, since that is transport, not meaning). Plain `frame` and
+     * `frame --from-delta` record nothing here: they frame no plan.
+     *
+     * OPTIONAL because every contract written before this field existed must
+     * still parse — the `builder` precedent, and the `unbound` ledger entry's:
+     * a schema constraint must never refuse to READ a record already on disk,
+     * and the decision point fails closed instead. `--resume` therefore REFUSES
+     * a contract with no `planHash` rather than falling back to a field
+     * comparison, because a lane that records no binding can prove nothing about
+     * which plan it was framed from.
+     *
+     * Deliberately excluded from `contractScopeHash`, which enumerates its
+     * fields explicitly: the plan is not the scope, and recording it must never
+     * stale a pack.
+     */
+    planHash: z.string().length(64).optional(),
+    allowedPaths: z.array(z.string()).min(1),
+    forbiddenPaths: z.array(z.string()).default([]),
+    nonGoals: z.array(z.string()).default([]),
+    acceptanceChecks: z.array(AcceptanceCheckSchema).min(1),
+    docsDelta: z.array(z.string()).default([]),
+    createdAt: z.string(),
+    amendments: z.array(AmendmentSchema).default([]),
+});
+// ── Pack (packs/<id>.md frontmatter) ─────────────────────────────────────────
+export const PackSchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    /** sha256 of the contract file at pack time; a mismatch later means the pack is stale. */
+    contractHash: z.string().length(64),
+    createdAt: z.string(),
+    skills: z.array(z.string()).default([]),
+    agent: z.string().optional(),
+});
+// ── Review (reviews/<id>.md frontmatter) ─────────────────────────────────────
+export const ReviewSchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    /** Stable patch id of the diff the review looked at. If the code moves, the seal breaks. */
+    patchId: z.string().min(1),
+    reviewer: z.string().min(1),
+    state: z.enum(['draft', 'sealed']),
+    verdict: z.enum(['approve', 'request_changes']).optional(),
+    createdAt: z.string(),
+    sealedAt: z.string().optional(),
+});
+// ── Decision (decisions/<id>.json) ───────────────────────────────────────────
+export const DecisionSchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    patchId: z.string().min(1),
+    decision: z.enum(['approved', 'rejected']),
+    by: z.string().min(1),
+    at: z.string(),
+    algorithm: z.literal('ed25519'),
+    /** base64 Ed25519 signature over `<contractId>\n<patchId>\n<decision>`. */
+    signature: z.string().min(1),
+    publicKey: z.string().min(1),
+});
+// ── Runtime provenance, shared by every durable record that records it ───────
+/**
+ * Which Prismatica wrote this durable record — `src/runtime.ts`'s own version.
+ * Carried by Check evidence, an assurance ledger row, and a passport.
+ *
+ * OPTIONAL, and that is the whole compatibility contract in one field: every
+ * record written before 0.2.0 carries none and must keep parsing forever (the
+ * `builder`/`planHash`/`checkedHead` precedent — a schema constraint must never
+ * refuse to READ a record already on disk). Absent means "not recorded", never
+ * "old and therefore suspect": nothing in the assurance path reads this, no
+ * gate, hash, signature, patch-id or proof binding consults it, and no version
+ * comparison happens anywhere. It exists so a record can say which reader
+ * produced it.
+ *
+ * The promise it belongs to is deliberately ONE-WAY. A newer runtime reads every
+ * record an older released runtime could write (proved on disk by
+ * `records/compatibility.test.ts`); an older, STRICT runtime is not promised to
+ * read what a newer one writes — this very field would be an unknown key to it.
+ * So an adopted repository moves its CI gate pin to a reader that understands a
+ * new shape before, or with, the first change that writes one.
+ */
+const PrismaticaVersionSchema = z.string().min(1).optional();
+// ── Passport (passports/<id>.md frontmatter) ─────────────────────────────────
+// Written only after a successful ship + verify — never before.
+export const PassportSchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    title: z.string().min(1),
+    shippedAt: z.string(),
+    pr: z.string().min(1),
+    deploy: z.strictObject({
+        target: z.string().optional(),
+        result: z.string().min(1),
+    }),
+    verify: z.strictObject({
+        journey: z.string().min(1),
+        result: z.literal('pass'),
+    }),
+    rollback: z.strictObject({
+        route: z.string().min(1),
+        testedAt: z.string().min(1),
+    }),
+    /**
+     * Recorded when the passport is written, and additive in the strictest sense:
+     * it changes nothing about WHEN a passport may be written. Every requirement
+     * `ship --verify` already had — a confirmed merged PR into the configured
+     * base from this contract's own branch, the merged head's patch-id equalling
+     * the diff this change's tier of proof covers, exactly one passing
+     * `prismatica-gate` check on that head, real deploy-result and
+     * rollback-route text, and a passing live smoke journey — is untouched, and
+     * none of them becomes mandatory anywhere it was optional.
+     */
+    prismaticaVersion: PrismaticaVersionSchema,
+});
+// ── Ledger (ledger.jsonl, one line per assurance or ready-run event) ─────────
+export const CheckResultSchema = z.strictObject({
+    name: z.string().min(1),
+    // 'warn' never fails a check or gate run by itself — it surfaces something
+    // worth the owner's attention (e.g. an Atlas impact finding) without being
+    // a proof-check failure; only an explicit gate requirement can turn it into one.
+    status: z.enum(['pass', 'fail', 'skipped', 'warn']),
+    detail: z.string().optional(),
+});
+export const CheckEvidenceSchema = z.strictObject({
+    contractId: z.string().min(1),
+    event: z.enum(['check_run', 'gate_run']),
+    at: z.string(),
+    pass: z.boolean(),
+    outcomes: z.array(CheckResultSchema),
+    changedFiles: z.array(z.string()),
+    /** Which runtime ran these checks. See `PrismaticaVersionSchema`. */
+    prismaticaVersion: PrismaticaVersionSchema,
+});
+export const LedgerEntrySchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    tier: RiskTierSchema,
+    event: z.enum(['check_run', 'gate_run']),
+    at: z.string(),
+    pass: z.boolean(),
+    checks: z.array(CheckResultSchema),
+    /**
+     * The commit the run actually inspected. OPTIONAL so entries written before
+     * it existed still parse — the `builder` precedent: a shape constraint on a
+     * record schema must never refuse to READ a record already on disk. Failing
+     * closed on its absence is the assessment's job, not the schema's (see
+     * `ledger.ts`'s `latestCheckStanding`, state `unbound`), which is what keeps
+     * "can this be read" and "does this prove anything" as two separate layers.
+     */
+    checkedHead: z.string().min(1).optional(),
+    /**
+     * Which runtime produced this row. See `PrismaticaVersionSchema` — it is
+     * recorded, never consulted: `latestCheckStanding` reads exactly the same
+     * fields it always did, so a row with no version keeps precisely the standing
+     * it had.
+     */
+    prismaticaVersion: PrismaticaVersionSchema,
+    reworkCount: z.number().int().min(0),
+    durationMs: z.number().int().min(0).optional(),
+    skillsUsed: z.array(z.string()).default([]),
+    cost: z.number().optional(),
+    escapedBugs: z.array(z.string()).default([]),
+});
+/**
+ * Get Change Ready is orchestration state, never assurance evidence. Its
+ * events share the append-only ledger so a controller can disappear and be
+ * replaced without introducing a second store. Existing check/gate entries
+ * stay byte-for-byte compatible; consumers that decide proof continue to read
+ * only `LedgerEntrySchema` (see `ledger.ts`).
+ */
+export const READY_RECORD_FORMAT = 'prismatica/ready-record@1';
+/**
+ * All three values are CONSTRAINED to `BUILDER_NAME_PATTERN`, for the reason
+ * `Contract.builder` is: each is interpolated into a copy-ready command the
+ * owner — or the controller — is invited to paste into a shell
+ * (`prismatica open <provider> <id> --model <model> --effort <effort>`), and
+ * they arrive from an imported document rather than from the owner's own
+ * typing. A bare identifier is the only shape that cannot carry shell syntax
+ * or a terminal escape into that paste, which is why quoting each render site
+ * was not the fix there and is not the fix here. Safe to state on the schema
+ * because Get Change Ready is new: no record on disk carries one of these, so
+ * the pattern can never refuse to READ a record that already parses.
+ */
+export const ReadyProviderSelectionSchema = z.strictObject({
+    provider: z.string().regex(BUILDER_NAME_PATTERN),
+    model: z.string().regex(BUILDER_NAME_PATTERN).nullable(),
+    effort: z.string().regex(BUILDER_NAME_PATTERN).nullable(),
+});
+export const ReadyRunPlanSchema = z.strictObject({
+    builder: ReadyProviderSelectionSchema,
+    reviewer: ReadyProviderSelectionSchema,
+});
+export const ReadyStopStateSchema = z.enum([
+    'running',
+    'awaiting_owner',
+    'blocked',
+    'check_budget_exhausted',
+    'review_budget_exhausted',
+    'complete',
+]);
+const ReadyEventBase = {
+    format: z.literal(READY_RECORD_FORMAT),
+    id: z.string().uuid(),
+    contractId: z.string().min(1),
+    at: z.iso.datetime(),
+    runId: z.string().uuid(),
+    plan: ReadyRunPlanSchema,
+    stopState: ReadyStopStateSchema,
+    nextOwnerAction: z.string().min(1),
+};
+export const ReadyRunStartedEventSchema = z.strictObject({
+    ...ReadyEventBase,
+    event: z.literal('ready_run_started'),
+    /**
+     * The run this boundary REPLACES — written by the CLI, never by the imported
+     * document, and only for an owner-authorised rollover (`ready record --import
+     * <start.json> --new-run`).
+     *
+     * It is what lets the ledger alone tell a legitimate second boundary from an
+     * injected one. Before it existed a contract could hold exactly ONE
+     * `ready_run_started` row and a second was refused as ambiguous — the only
+     * thing standing between a hand-appended line and a reset attempt budget. A
+     * chain keeps that guard while allowing the rollover: the first boundary
+     * names no predecessor, every later one must name the immediately-preceding
+     * boundary's `runId`, and `runStartFor` still refuses anything else. The
+     * predecessor's STOP STATE is deliberately not recorded here — it is
+     * recomputed from that run's own events, so the chain is audited rather than
+     * self-asserted.
+     *
+     * Optional, the `planHash`/`builder` precedent: the first boundary of every
+     * run legitimately has none, and a schema constraint must never refuse to
+     * READ a record already on disk.
+     */
+    supersedes: z.string().uuid().optional(),
+    boundary: z.strictObject({
+        head: z.string().min(1),
+        ledgerRecordsBefore: z.number().int().min(0),
+        checkRunsBefore: z.number().int().min(0),
+    }),
+});
+export const ReadyCheckAttemptEventSchema = z.strictObject({
+    ...ReadyEventBase,
+    event: z.literal('ready_check_attempt'),
+    attempt: z.number().int().min(1).max(3),
+    check: z.strictObject({
+        ledgerEntryId: z.string().min(1),
+        evidencePath: z.string().min(1),
+        checkedHead: z.string().min(1),
+        pass: z.boolean(),
+    }),
+});
+export const ReadyReviewAttemptEventSchema = z.strictObject({
+    ...ReadyEventBase,
+    event: z.literal('ready_review_attempt'),
+    attempt: z.number().int().min(1).max(3),
+    review: z.strictObject({
+        path: z.string().min(1),
+        patchId: z.string().min(1),
+        createdAt: z.iso.datetime(),
+    }),
+    verdict: z.enum(['SAFE TO SEAL', 'DO NOT SEAL']),
+    findings: z.array(z.string()),
+});
+/**
+ * A review attempt STARTED — written by `review` the instant it drafts the
+ * record, before anything can replace it.
+ *
+ * The attempt event above is written after the reviewer has finished and the
+ * controller has read the verdict, which is principle 4 and stays that way. But
+ * a review record is ONE file rewritten in place, so between the draft and that
+ * event the only evidence the attempt happened is the uncommitted draft itself
+ * — and the next `review` overwrites it. A controller that died in that window
+ * came back to a run whose budget had silently been restored.
+ *
+ * So the durable half is split off and written at the point the draft exists:
+ * same run, same `sightingKey` (`patchId` + `createdAt`), so it dedupes against
+ * both the recorded attempt and the record on disk rather than counting twice.
+ *
+ * Deliberately NO `attempt` number. This is evidence that a draft happened, not
+ * a claim about which place it takes — `spentIn` derives the numbers, and a
+ * bounded field here would make a fourth `review` throw a schema error from
+ * inside a command that has already written the record it is reporting.
+ */
+export const ReadyReviewDraftedEventSchema = z.strictObject({
+    ...ReadyEventBase,
+    event: z.literal('ready_review_drafted'),
+    review: z.strictObject({
+        path: z.string().min(1),
+        patchId: z.string().min(1),
+        createdAt: z.iso.datetime(),
+    }),
+});
+export const ReadyStoppedEventSchema = z.strictObject({
+    ...ReadyEventBase,
+    event: z.literal('ready_stopped'),
+    stopState: ReadyStopStateSchema.exclude(['running']),
+    detail: z.string().optional(),
+});
+export const ReadyLedgerEventSchema = z.discriminatedUnion('event', [
+    ReadyRunStartedEventSchema,
+    ReadyCheckAttemptEventSchema,
+    ReadyReviewAttemptEventSchema,
+    ReadyReviewDraftedEventSchema,
+    ReadyStoppedEventSchema,
+]);
+/** Every line the append-only ledger can contain. */
+export const LedgerRecordSchema = z.union([LedgerEntrySchema, ReadyLedgerEventSchema]);
+const ReadyImportBase = {
+    format: z.literal(READY_RECORD_FORMAT),
+    nextOwnerAction: z.string().min(1),
+};
+/**
+ * Strict JSON accepted by `ready record`. The contract id, event id, starting
+ * run id, timestamp and attempt number never come from this document; the CLI
+ * fixes or generates them. Later events must echo that generated run id.
+ * Findings are file content, never argv or shell text.
+ */
+export const ReadyRecordImportSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        ...ReadyImportBase,
+        kind: z.literal('start'),
+        plan: ReadyRunPlanSchema,
+    }),
+    z.strictObject({
+        ...ReadyImportBase,
+        kind: z.literal('check'),
+        runId: z.string().uuid(),
+        checkLedgerEntryId: z.string().min(1),
+        evidencePath: z.string().min(1),
+        stopState: ReadyStopStateSchema,
+    }),
+    z.strictObject({
+        ...ReadyImportBase,
+        kind: z.literal('review'),
+        runId: z.string().uuid(),
+        reviewPatchId: z.string().min(1),
+        verdict: z.enum(['SAFE TO SEAL', 'DO NOT SEAL']),
+        findings: z.array(z.string()),
+        stopState: ReadyStopStateSchema,
+    }),
+    z.strictObject({
+        ...ReadyImportBase,
+        kind: z.literal('stop'),
+        runId: z.string().uuid(),
+        stopState: ReadyStopStateSchema.exclude(['running']),
+        detail: z.string().optional(),
+    }),
+]);
+// ── Flow (flows/<slug>.md) — the comprehension layer's canonical unit ────────
+//
+// A Flow is a complete end-to-end route through the app. It splits into two
+// parts with different ownership: `truth` is product truth — agents may only
+// PROPOSE changes to it, the owner approves — and `mechanics` is where-it-lives
+// bookkeeping that agents update freely, with no approval. `status` sits
+// OUTSIDE `truth` deliberately (see DECISIONS.md "status sits outside the
+// truth hash"): the common planned→works transition should not need approval
+// ceremony, and the honest guard is the visible evidence state instead.
+export const FLOW_STATUSES = ['works', 'planned', 'idea', 'uncertain'];
+export const FlowStatusSchema = z.enum(FLOW_STATUSES);
+export const EVIDENCE_METHODS = ['manual', 'test', 'inferred'];
+export const EvidenceMethodSchema = z.enum(EVIDENCE_METHODS);
+/**
+ * Evidence attaches to the exact step or rule it supports — never a single
+ * flow-level claim, so one test can never be read as proving an entire flow.
+ */
+export const EvidenceSchema = z.strictObject({
+    method: EvidenceMethodSchema,
+    at: z.string(),
+    commit: z.string().optional(),
+    note: z.string().optional(),
+});
+/** One step of a flow: who does what, what the app shows, what changes, only if what. */
+export const FlowStepSchema = z.strictObject({
+    actor: z.string().min(1),
+    action: z.string().min(1),
+    shows: z.string().optional(),
+    changes: z.string().optional(),
+    assumes: z.array(z.string()).default([]),
+    /** Excluded from the truth hash — updating evidence is never a truth rewrite. */
+    evidence: EvidenceSchema.optional(),
+});
+/**
+ * A variation on the main path. More than ~4 is a readability SUGGESTION
+ * surfaced by the CLI/GUI ("consider splitting this flow") — never a schema
+ * rejection, so there is no arbitrary hard cap here.
+ */
+export const FlowVariationSchema = z.strictObject({
+    name: z.string().min(1),
+    differs: z.string().min(1),
+    status: FlowStatusSchema.optional(),
+});
+/** The product-truth block. Agents may only propose changes; the owner approves. */
+export const FlowTruthSchema = z.strictObject({
+    goal: z.string().min(1),
+    startsWhen: z.string().min(1),
+    /** Preconditions — distinct from the trigger in `startsWhen`. */
+    needs: z.array(z.string()).default([]),
+    steps: z.array(FlowStepSchema).min(1),
+    endsWith: z.string().min(1),
+    variations: z.array(FlowVariationSchema).default([]),
+    /** Free text, or a stable rule id ("r-offline-first") from rules.md. */
+    rules: z.array(z.string()).default([]),
+    involves: z.array(z.string()).default([]),
+});
+const FlowMechanicsTestSchema = z.strictObject({
+    file: z.string().min(1),
+    /** Which step numbers (1-based) this test actually covers. */
+    steps: z.array(z.number().int().min(1)).default([]),
+});
+/** Mechanics: agents keep this current freely — never gated by owner approval. */
+export const FlowMechanicsSchema = z.strictObject({
+    touchpoints: z.array(z.string()).default([]),
+    routes: z.array(z.string()).default([]),
+    components: z.array(z.string()).default([]),
+    entities: z.array(z.string()).default([]),
+    tests: z.array(FlowMechanicsTestSchema).default([]),
+});
+/**
+ * Recorded whenever `truth` is approved. `hash` covers `truth` only (with each
+ * step's `evidence` stripped) — see atlas/store.ts `computeTruthHash`. In
+ * `govern` mode this is additionally signed with the owner's Ed25519 key
+ * (reusing keys.ts, the same machinery `accept` uses); in `map-only` mode the
+ * hash alone is the guard.
+ */
+export const FlowApprovalSchema = z.strictObject({
+    hash: z.string().length(64),
+    at: z.string(),
+    by: z.string().min(1),
+    signature: z.string().optional(),
+    publicKey: z.string().optional(),
+});
+/**
+ * Owner-facing presentation only — a concise title, which journey the flow
+ * belongs to, and where it sits in that journey. Deliberately a SIBLING of
+ * `truth` (like `status` and `mechanics`), never a member of it: `truthHashInput`
+ * spreads `truth`, so anything placed inside would silently enter the truth hash
+ * and invalidate every already-signed record. Because it sits outside, editing
+ * presentation leaves `approval` — hash and signature — byte-for-byte intact.
+ *
+ * Every field is optional, and nothing populates it automatically: records
+ * written before this block existed parse unchanged and render through the
+ * deterministic fallbacks in atlas/presentation.ts. There is no migration and
+ * no backfill; `flow approve` (carrying a proposal's block through) is the only
+ * path by which PRISMATICA ITSELF writes it.
+ *
+ * It is therefore UNSIGNED display metadata, not truth, and nothing
+ * deterministic prevents a hand edit of this block on disk: the truth hash and
+ * signature it sits outside of stay valid across such an edit — by design, and
+ * that is precisely why it is safe. An edit here cannot forge truth, invalidate
+ * a signature, or change any hash; the worst it can do is mislabel a flow in
+ * the owner's own view. Anything that must be governed belongs in `truth`.
+ */
+export const FlowPresentationSchema = z.strictObject({
+    /** A short human title, e.g. "Prove a change with check". Falls back to the id. */
+    title: z.string().min(1).max(80).optional(),
+    /** The journey this flow belongs to, e.g. "Make a change". Groups the Flow Map. */
+    journey: z.string().min(1).max(60).optional(),
+    /** Position within the journey. Lower comes first; ties fall back to the id. */
+    order: z.number().int().min(0).optional(),
+});
+export const FlowSchema = z.strictObject({
+    id: z.string().min(1),
+    createdAt: z.string(),
+    status: FlowStatusSchema,
+    presentation: FlowPresentationSchema.optional(),
+    truth: FlowTruthSchema,
+    mechanics: FlowMechanicsSchema.default({
+        touchpoints: [],
+        routes: [],
+        components: [],
+        entities: [],
+        tests: [],
+    }),
+    approval: FlowApprovalSchema,
+});
+export const FLOW_PROPOSAL_TYPES = ['draft', 'update'];
+export const FlowProposalTypeSchema = z.enum(FLOW_PROPOSAL_TYPES);
+export const ProposedBySchema = z.enum(['agent', 'owner']);
+/**
+ * A discovery draft (`proposalType: 'draft'`) or a proposed change to an
+ * existing flow (`'update'`, same `id` as the target canonical flow). Nothing
+ * here is accepted automatically — the owner reviews and runs `flow approve`.
+ */
+export const FlowProposalSchema = z.strictObject({
+    id: z.string().min(1),
+    proposalType: FlowProposalTypeSchema,
+    reason: z.string().min(1),
+    proposedBy: ProposedBySchema.default('agent'),
+    createdAt: z.string(),
+    status: FlowStatusSchema,
+    presentation: FlowPresentationSchema.optional(),
+    truth: FlowTruthSchema,
+    mechanics: FlowMechanicsSchema.default({
+        touchpoints: [],
+        routes: [],
+        components: [],
+        entities: [],
+        tests: [],
+    }),
+});
+// ── App rules (rules.md) — cross-flow truth, one list per app ────────────────
+//
+// A short list of rules that sit ABOVE flows and apply across them (e.g.
+// "offline-first", "no API keys"). Stable ids so Flows and Deltas can cite them
+// reliably (a flow's `truth.rules` entry, or a future Delta's "Keep").
+export const RuleSchema = z.strictObject({
+    /** Stable, immutable, slug-generated at creation (e.g. "r-offline-first"). */
+    id: z.string().min(1),
+    text: z.string().min(1),
+    createdAt: z.string(),
+    evidence: EvidenceSchema.optional(),
+});
+/** One file, one list, one approval — "one concept, one list per app". */
+export const RulesFileSchema = z.strictObject({
+    rules: z.array(RuleSchema).default([]),
+    approval: FlowApprovalSchema,
+});
+/** A candidate new rule, or a proposed change to an existing one (`id` = target). */
+export const RuleProposalSchema = z.strictObject({
+    id: z.string().min(1),
+    proposalType: FlowProposalTypeSchema,
+    reason: z.string().min(1),
+    proposedBy: ProposedBySchema.default('agent'),
+    createdAt: z.string(),
+    text: z.string().min(1),
+});
+// ── Flow Delta (deltas/<id>.md) — a change speaks Flow before it speaks code ──
+//
+// The owner's unit of intent for a change: which Flow (and optionally which
+// step) it's about, what happens today, what should happen instead, what must
+// not change, and how the result will be demonstrated (seeds an acceptance
+// check). Owner-authored via `delta new`, never agent-proposed — deltas carry
+// no truth hash or signature; they're a plan record, not governed truth.
+export const DELTA_STATUSES = ['proposed', 'approved', 'framed', 'done', 'rejected'];
+export const DeltaStatusSchema = z.enum(DELTA_STATUSES);
+export const DeltaSchema = z.strictObject({
+    id: z.string().min(1),
+    /** The Flow this delta is about — must exist, or be a fresh id for a new Flow. */
+    flowId: z.string().min(1),
+    /** Which step (1-based), if the delta is about one specific step. */
+    step: z.number().int().min(1).optional(),
+    today: z.string().min(1),
+    instead: z.string().min(1),
+    keep: z.array(z.string()).default([]),
+    assumptions: z.array(z.string()).default([]),
+    showMe: z.string().min(1),
+    status: DeltaStatusSchema,
+    /** Set once `frame --from-delta` maps this delta onto a contract. */
+    contractId: z.string().optional(),
+    createdAt: z.string(),
+});
+// ── Flow Report (reports/<contractId>.md, rides the lane — Model B) ──────────
+//
+// An agent's (or owner's) honest per-flow account of what a change touched,
+// written before `check`. Entries cover only flows EXAMINED or AFFECTED —
+// never a listing of every flow in the app. `unchanged` exists precisely to
+// answer the honesty gap: "files overlap but this flow is unaffected because
+// <reason>" — an ASSESSMENT a person or agent makes and signs their name to,
+// which is why `atlas/impact.ts` accepts it on a directly-affected flow.
+// The file/touchpoint math decides who must ANSWER, never what the answer is:
+// deterministic code cannot tell whether behaviour changed, and a code path
+// that tried would be deciding truth from filenames. What it can do is put the
+// facts beside the claim. Those facts are derived at render time rather than
+// persisted, so older strict readers can still parse the report.
+export const FLOW_REPORT_STATUSES = [
+    'unchanged',
+    'mechanics-updated',
+    'truth-proposed',
+    'new',
+    'unsure',
+];
+export const FlowReportStatusSchema = z.enum(FLOW_REPORT_STATUSES);
+export const FlowReportReverifySchema = z.strictObject({
+    flowId: z.string().min(1),
+    step: z.number().int().min(1),
+});
+export const FlowReportEntrySchema = z.strictObject({
+    flowId: z.string().min(1),
+    status: FlowReportStatusSchema,
+    reason: z.string().min(1),
+    steps: z.array(z.number().int().min(1)).default([]),
+    reverify: z.array(FlowReportReverifySchema).default([]),
+});
+export const FlowReportSchema = z.strictObject({
+    contractId: z.string().min(1),
+    at: z.string(),
+    by: ProposedBySchema.default('agent'),
+    /** true = an explicit "no flows affected" assertion — distinct from an empty entries list. */
+    none: z.boolean().default(false),
+    entries: z.array(FlowReportEntrySchema).default([]),
+});
+// ── Abandonment (abandonments/<id>.md, on the RETAINED branch only) ──────────
+//
+// A change the owner stopped. Additive and strict, and deliberately NOT a
+// lifecycle stage: `state.ts` is untouched, because abandoning is leaving the
+// lifecycle rather than a step along it, and a stage would imply this record
+// can be progressed from. Nothing reads it to make a decision — it exists so
+// that the reason survives the lane, which is the whole point of writing it
+// before the worktree goes (principle 5: archive over delete).
+//
+// It never reaches main: `abandon` commits it on the change's own retained
+// branch, so `classifyMainPush` needs no new partition to accept it.
+export const AbandonmentSchema = z.strictObject({
+    id: z.string().min(1),
+    contractId: z.string().min(1),
+    title: z.string().min(1),
+    /** The owner's own words. Required — an abandonment with no reason teaches nobody anything. */
+    reason: z.string().min(1),
+    at: z.string(),
+    branch: z.string().min(1),
+    /** What happened to the linked issue. `failed` is recorded, never hidden — closing it is best effort. */
+    issue: z.strictObject({
+        url: z.string().min(1),
+        disposition: z.enum(['closed', 'failed', 'none']),
+        detail: z.string().optional(),
+    }),
+    /**
+     * What happened to the pull request. `closed` means gh confirmed it; `none`
+     * means gh positively reported that no PR existed. There is no "unknown" —
+     * an uncertain remote state refuses the whole command before this is
+     * written, because a lane removed while a gate-passing PR stays mergeable
+     * leaves work that anyone could merge with nobody left to review it.
+     */
+    pr: z.strictObject({
+        url: z.string().optional(),
+        disposition: z.enum(['closed', 'already-closed', 'none']),
+    }),
+    /** Every record archived by the same commit — what a restorer will find on the branch. */
+    archived: z.array(z.string()).default([]),
+});
+// ── Repo registry (~/.config/prismatica/repos.json) ──────────────────────────
+// Pointers for the cross-repo board only. Never in the trust path.
+export const RegistrySchema = z.strictObject({
+    version: z.literal(1),
+    repos: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        path: z.string().min(1),
+        addedAt: z.string(),
+    }))
+        .default([]),
+});
+//# sourceMappingURL=types.js.map