nornir 0.4.21

//! Iceberg spec::Schema definitions mirroring `super::schema::*` Arrow
//! schemas. Field IDs are explicit and stable — append new fields with
//! a fresh, unused ID; never reuse, never renumber.

use std::sync::Arc;

use anyhow::Result;
use iceberg::spec::{NestedField, PrimitiveType, Schema, Type};

pub fn bench_runs() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(4, "date", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "machine", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "cores", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

pub fn bench_results() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "result_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "metric_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "metric_value", Type::Primitive(PrimitiveType::Double))),
        ])
        .build()?)
}

/// Per-bench runtime telemetry, one row per `(run_id, bench)` — the CPU/mem
/// footprint the in-bench sampler captured while that unit ran. Sibling of
/// `bench_results` (which is one row per scalar metric); kept separate so the
/// load profile never competes in the docs metric-comparison renderer and can
/// be queried on its own. `repo` is carried so reads prune by repo like
/// `bench_runs`. See `.nornir/bencher.md` for what each column means.
pub fn bench_telemetry() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "bench", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "n_cores", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(5, "cpu_pct_avg", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(6, "cpu_pct_max", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(7, "cores_busy_avg", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(8, "cores_busy_max", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(9, "mem_peak_mb", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(10, "mem_pct_max", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(11, "elapsed_ms", Type::Primitive(PrimitiveType::Double))),
        ])
        .build()?)
}

pub fn test_outcomes() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "test_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "passed", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(4, "duration_ms", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::optional(5, "message", Type::Primitive(PrimitiveType::String))),
            // Impact selection (feature: run only tests downstream of a changed crate).
            Arc::new(NestedField::optional(6, "source_repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(7, "source_crate", Type::Primitive(PrimitiveType::String))),
            // Flake bookkeeping (feature: auto-quarantine).
            Arc::new(NestedField::optional(8, "attempt_idx", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::optional(9, "retry_of_run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(10, "quarantined", Type::Primitive(PrimitiveType::Boolean))),
        ])
        .build()?)
}

/// First-class test-matrix results — one row per `(run_id, suite, test_name)`.
///
/// Where `test_outcomes` is keyed to a `bench_runs.run_id` (bench-shaped,
/// co-written with a bench), this is the standalone green/red board the C6
/// test-matrix writes: `nornir test <repo>` runs the repo's `cargo test`
/// (or `cargo nextest run`), parses each test's pass/fail + duration, and
/// appends one row per case under a fresh `run_id`. The viz **Test** pane
/// reads it back as a per-repo matrix (newest run on top, green/red per test).
///
/// Grain: one row per test case in a run. `(run_id, suite, test_name)` is the
/// logical key. `status` ∈ `pass | fail | ignored | stalled` (the stall
/// watchdog records `stalled` + red when a subprocess goes silent). `suite` is
/// the crate / test target the case lives in. `message` carries the failure
/// detail (`""` = none, never null). `ts_micros` is the run time (shared by all
/// of a run's rows). See `.nornir/test-matrix.md`.
pub fn test_results() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "suite", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "test_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "duration_ms", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(7, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(8, "message", Type::Primitive(PrimitiveType::String))),
            // EPIC L — multi-aspect engine. Which aspect produced the row
            // (`unit` default, `build`, `clippy`, `coverage`, …) + its numeric
            // metric (coverage %, warning count, advisory count; 0.0 = N/A).
            // OPTIONAL so the columns are migration-safe: tables written before
            // EPIC L carry neither, and the reader defaults them back to
            // `aspect = "unit"`, `metric = 0.0`.
            Arc::new(NestedField::optional(9, "aspect", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(10, "metric", Type::Primitive(PrimitiveType::Double))),
        ])
        .build()?)
}

pub fn dep_graph_edges() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(4, "from_repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "to_repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "via_crate", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// One row per (release, repo). A release's full provenance — which
/// git SHAs of which repos went into it, against which dep-graph
/// snapshot, in which order, and with what gate outcome.
///
/// `gate_status` is per-repo so a partial release that only got
/// through `znippy` before tripping a gate on `holger` is fully
/// reconstructable.
///
/// `published_versions_csv` is `crate@version,crate@version` for the
/// crates this repo actually shipped (empty for dry-runs / failed
/// gates).
pub fn release_lineage() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(4, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "build_order_idx", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(6, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "git_branch", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "git_dirty", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(10, "gate_status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(11, "tests_passed", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(12, "tests_failed", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(13, "dry_run", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(14, "published_versions_csv", Type::Primitive(PrimitiveType::String))),
            // Time-machine pins: each release can attach immutable
            // derived artifacts captured at the same `git_sha`. Nullable
            // because (a) the table predates the time machine and
            // (b) not every artifact kind exists for every repo.
            Arc::new(NestedField::optional(15, "tantivy_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(16, "dwarf_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(17, "gimli_snapshot_id", Type::Primitive(PrimitiveType::String))),
            // Cargo-pipeline pins.
            Arc::new(NestedField::optional(18, "git_tag", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(19, "git_tag_matches_published", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(20, "rustdoc_json_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(21, "patch_lines_stripped", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

/// Release events: a clean row-level DAG of a `nornir release run`.
///
/// Where `release_lineage` records the *outcome* per `(release, repo)`,
/// this records the *shape* of the operation: one row per
/// `component × op × phase` boundary as the pipeline walks the build
/// order. `depends_on` carries the components this one waited on (the
/// upstream producers from the dep graph), so a reader can draw the live
/// op DAG and see exactly where a partial release stalled — the
/// structural twin of `funnel_events`.
///
/// Grain: one row per emitted boundary. `(run_id, seq)` is the stable
/// ordering key — `seq` is a per-run monotonic counter minted at emit
/// time (Iceberg gives no scan order, so reads sort by `seq`).
///
/// `depends_on` is `list<string>` (the dependency component names);
/// nullable so a no-dep root op writes a null rather than an empty list.
/// `elapsed_ms` is nullable — only `phase = end` rows carry a duration.
pub fn release_events() -> Result<Schema> {
    use iceberg::spec::ListType;

    let depends_on = Type::List(ListType::new(Arc::new(NestedField::required(
        111,
        "element",
        Type::Primitive(PrimitiveType::String),
    ))));

    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "seq", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(3, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(4, "component", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "op", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "phase", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "detail", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(10, "depends_on", depends_on)),
            Arc::new(NestedField::optional(11, "elapsed_ms", Type::Primitive(PrimitiveType::Long))),
        ])
        .build()?)
}

/// Funnel events: every mutation to the idea-intake DAG lands here as
/// a new row. Each Iceberg append produces a new snapshot, so the
/// table at snapshot T is the funnel state as of time T.
///
/// Schema is **wide** — one optional column per variant-specific field —
/// rather than a JSON blob, so SQL readers (DuckDB / PyIceberg) can
/// query the DAG directly without re-parsing.
///
/// Nested types in use:
///   * `refs`, `targets`, `produced_test_runs` → `list<string>`
///   * `produced_commits` → `list<struct{repo, sha}>`
///
/// `params_json` stays a string because `NodeAdded.params` is an
/// open-ended `serde_json::Map` with no fixed value type. If we ever
/// constrain it, promote to a typed map<string, *>.
pub fn funnel_events() -> Result<Schema> {
    use iceberg::spec::{ListType, StructType};

    // produced_commits element struct {repo, sha}
    let commit_struct = Type::Struct(StructType::new(vec![
        Arc::new(NestedField::required(101, "repo", Type::Primitive(PrimitiveType::String))),
        Arc::new(NestedField::required(102, "sha", Type::Primitive(PrimitiveType::String))),
    ]));

    let list_string = |elem_id: i32| {
        Type::List(ListType::new(Arc::new(NestedField::required(
            elem_id,
            "element",
            Type::Primitive(PrimitiveType::String),
        ))))
    };

    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            // Envelope
            Arc::new(NestedField::required(1, "event_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "kind", Type::Primitive(PrimitiveType::String))),

            // Common id refs (any subset depending on kind)
            Arc::new(NestedField::optional(4, "idea_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(5, "plan_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(6, "node_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(7, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(8, "from_node", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(9, "to_node", Type::Primitive(PrimitiveType::String))),

            // IdeaSubmitted
            Arc::new(NestedField::optional(10, "source", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(11, "text", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(12, "refs", list_string(112))),

            // IdeaTriaged / NodeStatusChanged / PlanStatusChanged / RunRecorded
            Arc::new(NestedField::optional(13, "decision", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(14, "node_status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(15, "plan_status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(16, "why", Type::Primitive(PrimitiveType::String))),

            // PlanCreated
            Arc::new(NestedField::optional(17, "summary", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(18, "planner", Type::Primitive(PrimitiveType::String))),

            // NodeAdded
            Arc::new(NestedField::optional(19, "node_kind", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(20, "targets", list_string(120))),
            Arc::new(NestedField::optional(21, "prompt_excerpt", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(22, "params_json", Type::Primitive(PrimitiveType::String))),

            // RunRecorded
            Arc::new(NestedField::optional(23, "ran_by", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(24, "outcome", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(25, "log_ref", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(26, "produced_commits",
                Type::List(ListType::new(Arc::new(NestedField::required(126, "element", commit_struct)))))),
            Arc::new(NestedField::optional(27, "produced_test_runs", list_string(127))),
        ])
        .build()?)
}

// ─── Generic artifact blob tables (time machine) ────────────────────
//
// Uniform two-table shape used by every immutable derived artifact
// (Tantivy index, DWARF debuginfo, gimli unwind tables, …):
//
//   <artifact>_snapshots — metadata, one row per (repo, git_sha) capture
//   <artifact>_blobs     — raw bytes, one row per file inside the capture
//
// Restore = SELECT blobs WHERE snapshot_id=X → write each (filename,
// bytes) row to a tmpdir → open with the artifact's native loader.
// No re-tokenize, no rebuild — Tantivy / gimli mmap the bytes back as
// if they had been written by the original producer.
//
// Field IDs use disjoint ranges per artifact kind so future renames /
// merges stay safe:
//   tantivy_index_snapshots : 1–9
//   tantivy_index_blobs     : 1–5
//   (future artifacts re-use the same low IDs — each table is its own
//    schema, IDs don't collide across tables.)

/// Snapshot metadata table for any artifact kind.
pub fn artifact_snapshots() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "branch", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(7, "schema_hash", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "blob_count", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(9, "total_bytes", Type::Primitive(PrimitiveType::Long))),
        ])
        .build()?)
}

/// Blob payload table for any artifact kind.
pub fn artifact_blobs() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "filename", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "bytes", Type::Primitive(PrimitiveType::Binary))),
            Arc::new(NestedField::required(4, "byte_len", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(5, "sha256", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Rendered-document exports, historized inline (one row per distinct
/// `(repo, doc_name, version, format, sha256)`). The `bytes` column carries
/// the full artifact so any past version is recoverable by warehouse read —
/// the file directory under `<gitroot>/docs/` only holds the current copy.
pub fn doc_exports() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "export_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "doc_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "format", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(9, "sha256", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(10, "byte_len", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(11, "bytes", Type::Primitive(PrimitiveType::Binary))),
        ])
        .build()?)
}

// ─── Vector / semantic-search tables ────────────────────────────────
//
// Materialized embeddings live in the warehouse so semantic search at any
// historical git_sha is a warehouse read — never a re-embed, never a git
// walk (the performance point for mega codebases). Three tables:
//
//   embeddings           : content-addressed, deduped vector store. A chunk's
//                          768-float vector for a given model is ONE row,
//                          stored once ever regardless of how many commits
//                          contain that chunk. The vector is a native Arrow
//                          `list<float32>` column — a contiguous f32 buffer
//                          that maps straight to/from VectorIndex's Vec<f32>
//                          (no byte (de)serialization), and stays queryable by
//                          DuckDB / Polars / DataFusion.
//   embedding_snapshots  : identity of one semantic index build —
//                          (repo, git_sha, model_profile, chunker_hash,
//                          fileset_hash, complete). Makes re-index idempotent.
//   embedding_manifest   : per-occurrence rows for a snapshot — which
//                          content_hash sits at which file/span. NO vector and
//                          NO source text (code stays in git, identity =
//                          git_sha). Time-travel = filter manifest by
//                          snapshot_id, JOIN embeddings, build the index.
//
// Field IDs are per-table and start at 1.

/// Content-addressed, deduped vector store. PK (logical) = (content_hash,
/// model_profile).
pub fn embeddings() -> Result<Schema> {
    use iceberg::spec::ListType;
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "content_hash", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "model_profile", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "dim", Type::Primitive(PrimitiveType::Int))),
            // Native Arrow list<float32>: a contiguous f32 buffer, mapped
            // straight to/from VectorIndex's Vec<f32> with no byte coding.
            Arc::new(NestedField::required(
                4,
                "vector",
                Type::List(ListType::new(Arc::new(NestedField::required(
                    104,
                    "element",
                    Type::Primitive(PrimitiveType::Float),
                )))),
            )),
            Arc::new(NestedField::required(5, "normalized", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(6, "vector_sha256", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Identity of one semantic-index build.
pub fn embedding_snapshots() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "branch", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "model_profile", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "chunker_hash", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "fileset_hash", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "complete", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(10, "row_count", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(11, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Per-occurrence rows belonging to one `embedding_snapshots` row.
pub fn embedding_manifest() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ordinal", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(3, "content_hash", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "model_profile", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "start_line", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(7, "end_line", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

// ─── Cargo-pipeline tables ──────────────────────────────────────────
//
// Each table is release-scoped (joined to `release_lineage.release_id`)
// or dep-graph-snapshot-scoped (joined to `dep_graph_edges.snapshot_id`)
// or stand-alone (events / plans). Field IDs restart at 1 per table —
// they are local to each schema.

/// Feature 1 — audit version= on every path-dep.
/// One row per (release, repo, manifest_path, dep_name).
pub fn path_dep_audits() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "manifest_path", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "dep_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "dep_path", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "has_version", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(7, "version_req", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "ok", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(9, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 2 (rich variant) — per-line patch-strip events.
pub fn patch_strip_events() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "line", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(5, "raw_line", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "action", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 3 — replaces the planned `sleep 20` between publishes.
/// Loop writes a row per attempt; `index_seen_ts_micros` is set when
/// crates.io's index advertises the new version.
pub fn publish_attempts() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "attempt_idx", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(6, "started_ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(7, "index_seen_ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(8, "wait_ms", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::optional(9, "http_status", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(10, "outcome", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(11, "stderr_excerpt", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 4 — gate readme/license/repository/description metadata.
pub fn crate_metadata_checks() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "has_readme", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(6, "has_license", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(7, "license_expr", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "has_repository", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(9, "repository_url", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(10, "has_description", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(11, "description_len", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(12, "ok", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(13, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 5 — `.crate` tarball size + largest file warning.
pub fn crate_tarball_stats() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "tarball_bytes", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(6, "file_count", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::optional(7, "largest_file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(8, "largest_file_bytes", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::optional(9, "p50_bytes_baseline", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(10, "exceeds_threshold", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(11, "threshold_bytes", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(12, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 6 — cascade yank/un-yank in dep order. Self-referential via
/// `cascade_root_event_id` so a yank-and-its-cascade is one query.
pub fn yank_events() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "event_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "action", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(8, "reason", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(9, "requested_by", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(10, "cascade_root_event_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(11, "http_status", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

/// Feature 7 — rustdoc-json semver diff. `from`/`to` reference
/// `rustdoc_json_snapshots.snapshot_id` (the existing artifact-snapshot
/// pattern).
pub fn semver_diffs() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "from_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "to_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "added_items", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(6, "removed_items", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(7, "changed_items", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(8, "suggested_bump", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 8 — `links =` declarations from every manifest in a
/// dep-graph snapshot. Conflicts: `GROUP BY links_value
/// HAVING COUNT(DISTINCT crate_name) > 1`.
pub fn links_declarations() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "links_value", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "manifest_path", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 9 — resolved feature set per workspace member, long/narrow.
/// `SELECT … FROM resolved_features WHERE member_repo='a' EXCEPT
///  SELECT … FROM resolved_features WHERE member_repo='b'`.
pub fn resolved_features() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "workspace_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "member_repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "member_crate", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "dep_crate", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "dep_version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "feature", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "source", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 10 — actual MSRV via cargo +<toolchain> check probes.
pub fn msrv_probes() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "probe_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(4, "declared_rust_version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "probed_rust_version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "probe_status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(8, "ci_run_id", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 11 — auditable record of which tests nornir chose to run
/// for an impact-set selection (so a green run is reproducible from
/// the dep-graph snapshot + the changed-crate set).
pub fn test_impacted_selections() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "changed_repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "selected_test_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "reason", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// Feature 12 — flake decision state (the rates themselves come from
/// a window query over `test_outcomes`).
pub fn test_quarantines() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "test_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "quarantined_at_ts", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(4, "unquarantined_at_ts", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(5, "pass_rate_window", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(6, "sample_size", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(7, "decision_reason", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(8, "decided_by", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 13 — commits between previous release SHA and current,
/// parsed as conventional commits for CHANGELOG generation.
pub fn release_commits() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(4, "parent_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "author", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(7, "conventional_type", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(8, "scope", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "breaking", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::required(10, "subject", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(11, "body", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 14 — mirror crates.io publishes to additional registries
/// (e.g. holger). One row per (crate@version, target_registry).
pub fn registry_mirrors() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "mirror_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "release_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "source_registry", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "target_registry", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "started_ts", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(9, "completed_ts", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::optional(10, "bytes_copied", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::optional(11, "sha256", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(12, "outcome", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(13, "error", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 15 — coordinated cross-workspace version bump (plan header).
pub fn version_bump_plans() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "plan_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "dep_graph_snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "scope", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(5, "requested_by", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Feature 15 — coordinated bump (targets / per-crate rows).
pub fn version_bump_targets() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "plan_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "from_version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "to_version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "reason", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "applied", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(8, "applied_release_id", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

// ─── knowledge map: pure-Rust producers (syn + gix) ─────────────────────
//
// One snapshot_id groups every row emitted by a single
// `nornir knowledge scan <repo>` invocation, so the renderer can
// reconstruct a consistent point-in-time map.

/// Symbol facts: one row per public item discovered by the syn walker.
/// `item_kind` ∈ {fn,struct,enum,trait,impl,mod,type,const,static,macro}.
/// `module_path` is `crate::a::b`. `visibility` ∈ {pub,pub(crate),priv}.
pub fn symbol_facts() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "module_path", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "item_kind", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "item_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "visibility", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(10, "line", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::required(11, "doc_lines", Type::Primitive(PrimitiveType::Int))),
            Arc::new(NestedField::optional(12, "signature", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Call edges discovered by walking syn::ItemFn bodies. `callee_ident`
/// is the unresolved identifier — name-resolution is a follow-up.
pub fn call_edges() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "caller_path", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "callee_ident", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "call_kind", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "line", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

/// Feature-gate facts: one row per `#[cfg(...)]` attribute attached to
/// a discovered item. `cfg_expr` is the raw text.
pub fn feature_gate_facts() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "crate_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "module_path", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "item_name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "cfg_expr", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(8, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(9, "line", Type::Primitive(PrimitiveType::Int))),
        ])
        .build()?)
}

/// Per-file git activity heat. One row per file at scan time.
pub fn git_heat_facts() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "file", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "commits_total", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(6, "commits_30d", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(7, "commits_90d", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(8, "authors_total", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(9, "last_commit_ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// MCP server call telemetry — one row per tool invocation. Metrics only
/// (no request/response payloads): which tool, ok/err, and how long it took.
/// Lets the viz answer "are agents using the MCP, and which tools?".
pub fn mcp_requests() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(2, "tool", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "status", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "latency_ms", Type::Primitive(PrimitiveType::Long))),
        ])
        .build()?)
}

/// N5 — viz **action trail** durable sink. One row per user-action the viz
/// records (tab switch, button click, query, RPC, error, lifecycle), the same
/// stream that also tails to the `$NORNIR_VIZ_ACTIONLOG` `/tmp` file (the file
/// stays a fast local live-channel; THIS is the durable, queryable sink, per
/// the persist-to-warehouse-stream-not-`/tmp` law).
///
/// Grain: one row per pushed action. `session_id` groups one viz launch's
/// trail (a fresh UUID minted per `ActionLog`); `seq` is that session's
/// monotonic counter — the stable ordering key (Iceberg gives no scan order, so
/// reads sort by `(session_id, seq)`). `kind` ∈
/// `LIFE | TAB | CLICK | QUERY | RPC | ERROR` (the action category). `workspace`
/// and `tab` carry the active context at push time (`""` when not applicable,
/// never null). `detail` is the free-form action text. Partitioned by
/// `session_id` so a per-session read prunes to that launch's files.
/// See `.nornir/viz-action-trail.md`.
pub fn viz_actions() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "session_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "seq", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(3, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(4, "kind", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "workspace", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "tab", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "detail", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// Cached OSV/RUSTSEC vulnerability findings keyed by the immutable
/// `crate@version` — the security scan reads this warehouse-first and only hits
/// OSV (or a local advisory-db) for crate@versions not yet cached.
pub fn vuln_findings() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "crate", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "version", Type::Primitive(PrimitiveType::String))),
            // comma-joined advisory ids (empty string = checked, no vulns)
            Arc::new(NestedField::required(3, "ids", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "summary", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "checked_at_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}

/// SBOM component rows (one per resolved dependency in a repo's closure):
/// `(name, version, license)`, captured from a deep-scan / `cargo metadata`
/// sweep and keyed by `repo` + capture `snapshot_id`. Lets the CycloneDX SBOM
/// be assembled from the warehouse (the latest snapshot per repo) instead of
/// re-invoking `cargo metadata` server-side.
pub fn sbom_components() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "name", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "version", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "license", Type::Primitive(PrimitiveType::String))),
        ])
        .build()?)
}

/// H5 — local-LLM / model **bake-off** results. One row per
/// `(run_id, agent, model, prompt_id)`: a single **(agent × model)** cell's
/// answer to one task in a bake-off **matrix**, with the latency + token
/// economics needed to rank it.
///
/// Grain: one row per `(agent, model)` cell in a bake-off run. `run_id` groups
/// the cells a single `nornir bakeoff` invocation pitted against each other (all
/// share the run's `ts_micros`), so the viz Leaderboard reads a run back and
/// ranks its cells by `score` then `tokens_per_s`. The matrix axis is
/// `agent × model`: `agent` is the harness/caller identity (claude / kilo / a
/// local-LLM driver) and `model` the model it drove. `prompt_id` is a stable
/// handle for the task (so two runs of the same task compare); `prompt` is the
/// task text and `output` the cell's completion (`""` = none, never null).
/// `tokens_in`/`tokens_out` are the prompt/completion token counts,
/// `tokens_per_s` the decode throughput, `latency_ms` the wall-clock call time.
/// `score` is a 0..=1 quality number (a judge/heuristic; `0.0` if unscored),
/// `ok` records whether the cell answered without error, `cost_usd` its price
/// (`0.0` = free/local), `mcp_tool_calls` how many MCP tool calls it made.
/// Partitioned by `run_id` (a bake-off writes every cell in one batch; the
/// leaderboard reads the whole run back). See `.nornir/bakeoff.md`.
pub fn agent_model_runs() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "run_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "ts_micros", Type::Primitive(PrimitiveType::Timestamptz))),
            Arc::new(NestedField::required(3, "model", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "prompt_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(5, "prompt", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(6, "output", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(7, "latency_ms", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(8, "tokens_in", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(9, "tokens_out", Type::Primitive(PrimitiveType::Long))),
            Arc::new(NestedField::required(10, "tokens_per_s", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(11, "score", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::required(12, "ok", Type::Primitive(PrimitiveType::Boolean))),
            Arc::new(NestedField::optional(13, "error", Type::Primitive(PrimitiveType::String))),
            // H5 bake-off **matrix** axis. A run crosses agents × models, one row
            // per `(task_id, agent, model)`. The `agent` is the harness/caller
            // identity (claude / kilo / a local-LLM driver) that produced the
            // answer; `cost` is its USD price (`0.0` = free/local) and
            // `mcp_tool_calls` how many MCP tool calls it made. OPTIONAL so the
            // columns are migration-safe — single-axis rows written before the
            // matrix carry none, and the reader defaults `agent = "-"`,
            // `cost = 0.0`, `mcp_tool_calls = 0`.
            Arc::new(NestedField::optional(14, "agent", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::optional(15, "cost_usd", Type::Primitive(PrimitiveType::Double))),
            Arc::new(NestedField::optional(16, "mcp_tool_calls", Type::Primitive(PrimitiveType::Long))),
        ])
        .build()?)
}

/// Knowledge-scan ledger: one row per `(repo, git_sha)` that has been
/// knowledge-scanned, recording the snapshot it produced. The republish path
/// reads this to make re-scanning an unchanged SHA a no-op (idempotency).
pub fn knowledge_scans() -> Result<Schema> {
    Ok(Schema::builder()
        .with_schema_id(0)
        .with_fields(vec![
            Arc::new(NestedField::required(1, "repo", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(2, "git_sha", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(3, "snapshot_id", Type::Primitive(PrimitiveType::String))),
            Arc::new(NestedField::required(4, "scanned_at_micros", Type::Primitive(PrimitiveType::Timestamptz))),
        ])
        .build()?)
}