@isaacriehm/cairn-state 0.22.5

package/dist/schemas.d.ts

@@ -0,0 +1,789 @@
+import { z } from "zod";
+export declare const Audience: z.ZodEnum<{
+    "ai-only": "ai-only";
+    dual: "dual";
+    "human-only": "human-only";
+}>;
+export type Audience = z.infer<typeof Audience>;
+export declare const ProvenanceFrontmatter: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    "source-commits": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type ProvenanceFrontmatter = z.infer<typeof ProvenanceFrontmatter>;
+export declare const ManifestEntry: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    classification: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    verified_at: z.ZodOptional<z.ZodString>;
+    generator: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ManifestEntry = z.infer<typeof ManifestEntry>;
+export declare const Manifest: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    generator: z.ZodOptional<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        classification: z.ZodString;
+        audience: z.ZodOptional<z.ZodString>;
+        verified_at: z.ZodOptional<z.ZodString>;
+        generator: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Manifest = z.infer<typeof Manifest>;
+export declare const DecisionAssertion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"schema_must_contain">;
+    table: z.ZodString;
+    column: z.ZodString;
+    column_type: z.ZodOptional<z.ZodString>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"text_must_match">;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"text_must_not_match">;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"index_must_exist">;
+    table: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    where: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"ast_pattern">;
+    language: z.ZodString;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"file_must_not_be_modified">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"query_must_filter_by">;
+    orm: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+    table: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    operator: z.ZodEnum<{
+        in: "in";
+        eq: "eq";
+        between: "between";
+        is_not_null: "is_not_null";
+    }>;
+    require_combination: z.ZodEnum<{
+        and: "and";
+        or: "or";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"route_must_have_guard">;
+    in_globs: z.ZodArray<z.ZodString>;
+    guard: z.ZodString;
+    require_on: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"event_must_emit">;
+    in_globs: z.ZodArray<z.ZodString>;
+    after_method: z.ZodString;
+    event_key: z.ZodString;
+    payload_must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"service_method_must_call">;
+    in_globs: z.ZodArray<z.ZodString>;
+    in_method: z.ZodString;
+    must_call: z.ZodString;
+    before_returning: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"human_review_hint">;
+    description: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type DecisionAssertion = z.infer<typeof DecisionAssertion>;
+/**
+ * sot_kind = where the canonical prose lives for this DEC.
+ *   "ledger" — body in this DEC file is canonical (source-comment essay,
+ *              operator-recorded). Lens renders body verbatim.
+ *   "path"   — sot_path points at the canonical location (doc paragraph,
+ *              CLAUDE.md section). Lens renders live content from there.
+ */
+export declare const SotKind: z.ZodEnum<{
+    path: "path";
+    ledger: "ledger";
+}>;
+export type SotKind = z.infer<typeof SotKind>;
+export declare const DecisionFrontmatter: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"adr">>;
+    status: z.ZodString;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    "source-commits": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    decided_at: z.ZodOptional<z.ZodString>;
+    decided_by: z.ZodOptional<z.ZodString>;
+    scope_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assertions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"schema_must_contain">;
+        table: z.ZodString;
+        column: z.ZodString;
+        column_type: z.ZodOptional<z.ZodString>;
+        nullable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"text_must_match">;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"text_must_not_match">;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"index_must_exist">;
+        table: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        where: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"ast_pattern">;
+        language: z.ZodString;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"file_must_not_be_modified">;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"query_must_filter_by">;
+        orm: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+        table: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        operator: z.ZodEnum<{
+            in: "in";
+            eq: "eq";
+            between: "between";
+            is_not_null: "is_not_null";
+        }>;
+        require_combination: z.ZodEnum<{
+            and: "and";
+            or: "or";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"route_must_have_guard">;
+        in_globs: z.ZodArray<z.ZodString>;
+        guard: z.ZodString;
+        require_on: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"event_must_emit">;
+        in_globs: z.ZodArray<z.ZodString>;
+        after_method: z.ZodString;
+        event_key: z.ZodString;
+        payload_must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"service_method_must_call">;
+        in_globs: z.ZodArray<z.ZodString>;
+        in_method: z.ZodString;
+        must_call: z.ZodString;
+        before_returning: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"human_review_hint">;
+        description: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+    human_review_hint: z.ZodOptional<z.ZodString>;
+    related_invariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sot_kind: z.ZodEnum<{
+        path: "path";
+        ledger: "ledger";
+    }>;
+    sot_path: z.ZodString;
+    sot_content_hash: z.ZodString;
+    related: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    derived_from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type DecisionFrontmatter = z.infer<typeof DecisionFrontmatter>;
+export declare const InvariantFrontmatter: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"invariant">>;
+    status: z.ZodOptional<z.ZodEnum<{
+        superseded: "superseded";
+        archived: "archived";
+        active: "active";
+    }>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    source_run: z.ZodOptional<z.ZodString>;
+    source_decision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    introduced_for_bug: z.ZodOptional<z.ZodString>;
+    sensor: z.ZodOptional<z.ZodString>;
+    e2e: z.ZodOptional<z.ZodString>;
+    naming_convention: z.ZodOptional<z.ZodString>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sot_kind: z.ZodEnum<{
+        path: "path";
+        ledger: "ledger";
+    }>;
+    sot_path: z.ZodString;
+    sot_content_hash: z.ZodString;
+    related: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    derived_from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type InvariantFrontmatter = z.infer<typeof InvariantFrontmatter>;
+export declare const DecisionLedgerEntry: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodString;
+    scope_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DecisionLedgerEntry = z.infer<typeof DecisionLedgerEntry>;
+export declare const InvariantLedgerEntry: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodString;
+    source_decision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type InvariantLedgerEntry = z.infer<typeof InvariantLedgerEntry>;
+export declare const QualityGrade: z.ZodObject<{
+    module: z.ZodString;
+    score: z.ZodNumber;
+    pass_rate: z.ZodNumber;
+    drift_count: z.ZodNumber;
+    last_updated: z.ZodString;
+    recent_run_count: z.ZodNumber;
+}, z.core.$strip>;
+export type QualityGrade = z.infer<typeof QualityGrade>;
+export declare const QualityGrades: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    modules: z.ZodArray<z.ZodObject<{
+        module: z.ZodString;
+        score: z.ZodNumber;
+        pass_rate: z.ZodNumber;
+        drift_count: z.ZodNumber;
+        last_updated: z.ZodString;
+        recent_run_count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type QualityGrades = z.infer<typeof QualityGrades>;
+/**
+ * Topic-index entry — one row per content-fingerprint slug across all
+ * scanned sources. `sot_source` is the canonical source path picked by
+ * priority order (docs/* > CLAUDE.md > AGENTS.md > source comments).
+ * `candidates` lists every place the same prose appears (one becomes the
+ * SoT, the rest become §DEC-<id> cites).
+ *
+ * `marker_kind` is stamped at walk-time when the SoT block sits under a
+ * `cairn:` frontmatter key (file-level) or has a `<!-- cairn:decision -->`
+ * / `<!-- cairn:rule -->` HTML comment within 3 lines of its heading
+ * (block-level). Phase 6 Stage 3 reads this field directly off the
+ * topic-index and bypasses Stages 1+2 (file-purpose + section batch
+ * classifiers) for marked entries — the operator has already declared
+ * the block authoritative, so Haiku adds no signal.
+ *
+ * `content_hash` mirrors the SoT block's body hash at walk-time. Used by
+ * `cairn_propose_decision` (PR 2) and the alignment hooks to detect
+ * source drift before promoting a candidate to a draft.
+ */
+export declare const TopicIndexEntry: z.ZodObject<{
+    slug: z.ZodString;
+    dec_id: z.ZodOptional<z.ZodString>;
+    sot_source: z.ZodString;
+    candidates: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        kind: z.ZodEnum<{
+            doc: "doc";
+            claudemd: "claudemd";
+            agentsmd: "agentsmd";
+            rule: "rule";
+            "source-comment": "source-comment";
+        }>;
+        anchor: z.ZodOptional<z.ZodString>;
+        line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    created_at: z.ZodString;
+    marker_kind: z.ZodOptional<z.ZodEnum<{
+        rule: "rule";
+        decision: "decision";
+    }>>;
+    content_hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TopicIndexEntry = z.infer<typeof TopicIndexEntry>;
+export declare const TopicIndex: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    topics: z.ZodRecord<z.ZodString, z.ZodObject<{
+        slug: z.ZodString;
+        dec_id: z.ZodOptional<z.ZodString>;
+        sot_source: z.ZodString;
+        candidates: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            kind: z.ZodEnum<{
+                doc: "doc";
+                claudemd: "claudemd";
+                agentsmd: "agentsmd";
+                rule: "rule";
+                "source-comment": "source-comment";
+            }>;
+            anchor: z.ZodOptional<z.ZodString>;
+            line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strip>>;
+        created_at: z.ZodString;
+        marker_kind: z.ZodOptional<z.ZodEnum<{
+            rule: "rule";
+            decision: "decision";
+        }>>;
+        content_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TopicIndex = z.infer<typeof TopicIndex>;
+/**
+ * SoT bindings — bidirectional map between DEC ids and their canonical
+ * source paths. Forward index is one-to-one. Reverse index is one-to-many
+ * because supersedes chains keep the same sot_path across multiple DEC
+ * ids.
+ */
+export declare const SotBindings: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    forward: z.ZodRecord<z.ZodString, z.ZodString>;
+    reverse: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SotBindings = z.infer<typeof SotBindings>;
+/**
+ * Sot-cache — tokenized DEC body shingles for Jaccard pre-filter in the
+ * Layer A alignment hook. Mtime-keyed so the cache rebuilds incrementally
+ * on PostToolUse Write events.
+ */
+export declare const SotCacheEntry: z.ZodObject<{
+    dec_id: z.ZodString;
+    sot_path: z.ZodString;
+    body_hash: z.ZodString;
+    tokens: z.ZodArray<z.ZodString>;
+    shingles: z.ZodArray<z.ZodString>;
+    mtime_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type SotCacheEntry = z.infer<typeof SotCacheEntry>;
+export declare const SotCache: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        dec_id: z.ZodString;
+        sot_path: z.ZodString;
+        body_hash: z.ZodString;
+        tokens: z.ZodArray<z.ZodString>;
+        shingles: z.ZodArray<z.ZodString>;
+        mtime_ms: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SotCache = z.infer<typeof SotCache>;
+/**
+ * Anchor-map — external map from topic slug to its current location in
+ * source. Allows operator's docs to stay pristine (no `<!-- cairn-anchor -->`
+ * injected) while drift detection reconciles via content_hash.
+ */
+export declare const AnchorMapEntry: z.ZodObject<{
+    file: z.ZodString;
+    current_anchor: z.ZodOptional<z.ZodString>;
+    content_hash: z.ZodString;
+    line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    kind: z.ZodEnum<{
+        doc: "doc";
+        claudemd: "claudemd";
+        agentsmd: "agentsmd";
+        rule: "rule";
+        "source-comment": "source-comment";
+    }>;
+}, z.core.$strip>;
+export type AnchorMapEntry = z.infer<typeof AnchorMapEntry>;
+export declare const AnchorMap: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    anchors: z.ZodRecord<z.ZodString, z.ZodObject<{
+        file: z.ZodString;
+        current_anchor: z.ZodOptional<z.ZodString>;
+        content_hash: z.ZodString;
+        line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        kind: z.ZodEnum<{
+            doc: "doc";
+            claudemd: "claudemd";
+            agentsmd: "agentsmd";
+            rule: "rule";
+            "source-comment": "source-comment";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AnchorMap = z.infer<typeof AnchorMap>;
+export declare const DriftEvent: z.ZodObject<{
+    ts: z.ZodString;
+    kind: z.ZodEnum<{
+        frontmatter_stale: "frontmatter_stale";
+        generator_drift: "generator_drift";
+        broken_link: "broken_link";
+        orphan_path: "orphan_path";
+        orphan_entity: "orphan_entity";
+        manifest_hash_changed: "manifest_hash_changed";
+        "doc-drift": "doc-drift";
+        "paragraph-deleted": "paragraph-deleted";
+        "pre-commit-drift": "pre-commit-drift";
+    }>;
+    path: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        soft: "soft";
+        hard: "hard";
+    }>>;
+    dec_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DriftEvent = z.infer<typeof DriftEvent>;
+/**
+ * Layer B pre-commit-drift log entry written by the git pre-commit
+ * hook (`cairn hook pre-commit-align`). SessionStart Drain SessionStart drain
+ * consumes this file, re-checks each entry against the (possibly
+ * changed) source location, and runs the Haiku judge for ambiguous
+ * candidates.
+ *
+ * Path: `.cairn/staleness/pre-commit-deferred.jsonl`.
+ *
+ * `tier: tier1` — deterministic match passed (Jaccard ≥ 0.85, shingle
+ * ≥ 0.6, length ratio 0.5–2.0). SessionStart Drain can auto-cite without Haiku
+ * if the block survives.
+ *
+ * `tier: tier2-3` — Jaccard pre-filter survivors only; Tier 1 didn't
+ * fire. SessionStart Drain invokes Haiku dedup judge.
+ */
+export declare const PreCommitDriftCandidate: z.ZodObject<{
+    id: z.ZodString;
+    similarity: z.ZodNumber;
+    body_hash: z.ZodString;
+    sot_path: z.ZodString;
+}, z.core.$strip>;
+export type PreCommitDriftCandidate = z.infer<typeof PreCommitDriftCandidate>;
+export declare const PreCommitDriftLogEntry: z.ZodObject<{
+    ts: z.ZodString;
+    file: z.ZodString;
+    block_start_line: z.ZodNumber;
+    block_end_line: z.ZodNumber;
+    block_content_hash: z.ZodString;
+    block_prose: z.ZodString;
+    tier: z.ZodEnum<{
+        tier1: "tier1";
+        "tier2-3": "tier2-3";
+    }>;
+    candidates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        similarity: z.ZodNumber;
+        body_hash: z.ZodString;
+        sot_path: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PreCommitDriftLogEntry = z.infer<typeof PreCommitDriftLogEntry>;
+/**
+ * Rejected-candidate ledger entry (`.cairn/ground/_rejected.yaml`).
+ *
+ * Records topic-index slugs the operator (or `ai-curator`) decided are
+ * *not* canonical — false positives, research notes, planning prose,
+ * etc. The drift sensor reads this file and suppresses any candidate
+ * whose slug appears here; phase 6 / `cairn ingest` skip rejected slugs
+ * on the next pass instead of re-proposing them.
+ *
+ * Dedup is by slug. First writer wins the `reason` string; subsequent
+ * writes only refresh `rejected_at`. Phase 5b GC drops entries whose
+ * slug is no longer present in the freshly-built topic-index.
+ */
+export declare const RejectedEntry: z.ZodObject<{
+    slug: z.ZodString;
+    rejected_at: z.ZodString;
+    rejected_by: z.ZodEnum<{
+        operator: "operator";
+        "ai-curator": "ai-curator";
+        "cairn-init": "cairn-init";
+    }>;
+    reason: z.ZodString;
+    sot_source: z.ZodString;
+    line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+export type RejectedEntry = z.infer<typeof RejectedEntry>;
+export declare const RejectedYaml: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    rejected: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        rejected_at: z.ZodString;
+        rejected_by: z.ZodEnum<{
+            operator: "operator";
+            "ai-curator": "ai-curator";
+            "cairn-init": "cairn-init";
+        }>;
+        reason: z.ZodString;
+        sot_source: z.ZodString;
+        line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RejectedYaml = z.infer<typeof RejectedYaml>;
+/**
+ * `.cairn/ground/file-candidates-map.yaml` — per-file count of
+ * topic-index entries with `dec_id IS NULL`. Built at the end of phase
+ * 5b (and refreshed whenever `dec_id` is stamped — phase 6, the PR 2
+ * `cairn_propose_decision` tool, etc.). The read-enrich hook consults
+ * this map to inject a candidate-count warning when an AI agent reads a
+ * file with unpromoted candidates, without scanning the whole topic
+ * index per Read.
+ */
+export declare const FileCandidatesMap: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    file_candidates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>;
+export type FileCandidatesMap = z.infer<typeof FileCandidatesMap>;
+export type CommentLang = "js" | "py" | "rs" | "go" | "java" | "c" | "cs" | "rb" | "sh" | "php" | "lua" | "dart" | "kt" | "swift" | "scala" | "unknown";
+export type CommentKind = "block" | "jsdoc" | "line-cluster" | "license";
+export interface CommentBlock {
+    /** Stable per-walk id: `<rel-path>:<startLine>-<endLine>` */
+    id: string;
+    /** Repo-relative POSIX path. */
+    file: string;
+    lang: CommentLang;
+    kind: CommentKind;
+    /** 1-based, inclusive. */
+    startLine: number;
+    /** 1-based, inclusive. */
+    endLine: number;
+    /** Raw text including comment markers. */
+    raw: string;
+    /** Stripped prose — markers + leading `*` removed, used for word count. */
+    prose: string;
+    lineCount: number;
+    charCount: number;
+    wordCount: number;
+    /** Index where `raw` starts in the file (UTF-8 bytes ≈ chars for source). */
+    startOffset: number;
+    /** Index immediately after `raw`. */
+    endOffset: number;
+}
+/**
+ * Per-mission default exit gate, with optional per-phase override in
+ * roadmap.md frontmatter.
+ *   - `prompt` — Stop hook surfaces inline AskUserQuestion on phase complete.
+ *   - `auto`   — cursor advances silently when last phase task graduates.
+ *   - `manual` — operator advances explicitly via cairn_mission_advance.
+ */
+export declare const MissionExitGate: z.ZodEnum<{
+    prompt: "prompt";
+    auto: "auto";
+    manual: "manual";
+}>;
+export type MissionExitGate = z.infer<typeof MissionExitGate>;
+export declare const MissionPhase: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    exit_criteria: z.ZodString;
+    exit_gate: z.ZodOptional<z.ZodEnum<{
+        prompt: "prompt";
+        auto: "auto";
+        manual: "manual";
+    }>>;
+}, z.core.$strip>;
+export type MissionPhase = z.infer<typeof MissionPhase>;
+/**
+ * Roadmap frontmatter — `.cairn/ground/missions/<id>/roadmap.md`. Lives
+ * in committed ground state; multi-dev visible. Phase YAML is canonical;
+ * any prose body is operator notes ignored by Cairn parsing.
+ */
+export declare const MissionRoadmapFrontmatter: z.ZodObject<{
+    mission_id: z.ZodString;
+    title: z.ZodString;
+    spec_path: z.ZodString;
+    created_at: z.ZodString;
+    exit_gate: z.ZodEnum<{
+        prompt: "prompt";
+        auto: "auto";
+        manual: "manual";
+    }>;
+    phases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exit_criteria: z.ZodString;
+        exit_gate: z.ZodOptional<z.ZodEnum<{
+            prompt: "prompt";
+            auto: "auto";
+            manual: "manual";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type MissionRoadmapFrontmatter = z.infer<typeof MissionRoadmapFrontmatter>;
+export declare const MissionPhaseState: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    done: "done";
+}>;
+export type MissionPhaseState = z.infer<typeof MissionPhaseState>;
+export declare const MissionPhaseProgressEntry: z.ZodObject<{
+    state: z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        done: "done";
+    }>;
+    task_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    graduated_at: z.ZodOptional<z.ZodString>;
+    ready_emitted: z.ZodOptional<z.ZodBoolean>;
+    brief_status: z.ZodOptional<z.ZodEnum<{
+        accepted: "accepted";
+        drafted: "drafted";
+    }>>;
+}, z.core.$strip>;
+export type MissionPhaseProgressEntry = z.infer<typeof MissionPhaseProgressEntry>;
+/**
+ * One resolved fork captured during per-phase tightening — the question
+ * the brief closed plus the operator's (or, in autonomous mode, the
+ * model's) choice. Mirrors a lightweight DEC without graduating to the
+ * decision graph; phase-scoped and archived with the mission.
+ */
+export declare const MissionPhaseBriefDecision: z.ZodObject<{
+    question: z.ZodString;
+    choice: z.ZodString;
+    rationale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MissionPhaseBriefDecision = z.infer<typeof MissionPhaseBriefDecision>;
+/**
+ * Per-phase brief — `.cairn/ground/missions/<id>/briefs/<phase-id>.md`.
+ * The just-in-time tightening artifact for a single phase: the forks the
+ * operator resolved, the constraints tasks in this phase must honour,
+ * the phase acceptance bar, and the in-scope ground-state cites that
+ * pre-answered the rest. Committed alongside the roadmap (multi-dev
+ * visible). Frontmatter is canonical; prose body is operator notes.
+ */
+export declare const MissionPhaseBrief: z.ZodObject<{
+    phase_id: z.ZodString;
+    drafted_at: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        accepted: "accepted";
+        drafted: "drafted";
+    }>>;
+    autonomous: z.ZodOptional<z.ZodBoolean>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        choice: z.ZodString;
+        rationale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    constraints: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cite_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cite_invariants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type MissionPhaseBrief = z.infer<typeof MissionPhaseBrief>;
+export declare const MissionCursor: z.ZodObject<{
+    active_phase: z.ZodNullable<z.ZodString>;
+    active_phase_started_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MissionCursor = z.infer<typeof MissionCursor>;
+export declare const MissionOutcome: z.ZodEnum<{
+    active: "active";
+    done: "done";
+    aborted: "aborted";
+}>;
+export type MissionOutcome = z.infer<typeof MissionOutcome>;
+/**
+ * Per-clone mission state — `.cairn/missions/<id>/state.json`.
+ * Tracks the cursor + phase progress. Never committed (gitignored under
+ * `.cairn/missions/`).
+ */
+export declare const MissionState: z.ZodObject<{
+    mission_id: z.ZodString;
+    started_at: z.ZodString;
+    cursor: z.ZodObject<{
+        active_phase: z.ZodNullable<z.ZodString>;
+        active_phase_started_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    phase_progress: z.ZodRecord<z.ZodString, z.ZodObject<{
+        state: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            done: "done";
+        }>;
+        task_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        graduated_at: z.ZodOptional<z.ZodString>;
+        ready_emitted: z.ZodOptional<z.ZodBoolean>;
+        brief_status: z.ZodOptional<z.ZodEnum<{
+            accepted: "accepted";
+            drafted: "drafted";
+        }>>;
+    }, z.core.$strip>>;
+    outcome: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        done: "done";
+        aborted: "aborted";
+    }>>;
+    closed_at: z.ZodOptional<z.ZodString>;
+    abort_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MissionState = z.infer<typeof MissionState>;
+/**
+ * Mission journal entry — `.cairn/missions/<id>/journal.jsonl`. One
+ * record per mission-level event (start, advance, resync, close).
+ */
+export declare const MissionJournalEntry: z.ZodObject<{
+    ts: z.ZodString;
+    kind: z.ZodEnum<{
+        started: "started";
+        "phase-advanced": "phase-advanced";
+        "phase-deferred": "phase-deferred";
+        "phase-brief-set": "phase-brief-set";
+        "task-attached": "task-attached";
+        "resync-pending": "resync-pending";
+        "resync-applied": "resync-applied";
+        "drift-detected": "drift-detected";
+        closed: "closed";
+        reopened: "reopened";
+        "exit-gate-changed": "exit-gate-changed";
+    }>;
+    phase_id: z.ZodOptional<z.ZodString>;
+    task_id: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MissionJournalEntry = z.infer<typeof MissionJournalEntry>;