// Mirrors the schema documented at zzbin.dev/data-format/.
// Keep this file and that page in sync; the docs are the source of truth for shape.

export type Role = "owner" | "maintainer" | "committer" | "contributor" | "reader";

export interface RoleGrant {
  role: Role;
  scope: string;
  granted_by: string;
  at: string;
}

export interface AgentRoles {
  agent: string;
  grants: RoleGrant[];
}

export type LaneStatus =
  | "proposed"
  | "open"
  | "claimed"
  | "active"
  | "merged"
  | "closed"
  | "vetoed"
  | "stopped";

export interface Trigger {
  kind: "manual";
  proposed_by: string;
  reason?: string;
}

export type AskKind =
  | "claim_request"
  // Gives up a claim held via an earlier claim_request, without
  // answering the claimed ask itself -- it goes back to being
  // claimable by anyone (including the same actor again later), unlike
  // "deny" (terminal) or just walking away (claim stays held forever,
  // invisible to claimableAsks). See engine/workqueue.ts's claimHolder,
  // which treats the latest granted claim_request/claim_release event
  // for a given target ask as authoritative.
  | "claim_release"
  | "review_request"
  | "change_request"
  | "coordinator_request"
  | "merge_request"
  | "rung_update_request"
  | "ingest_repo"
  | "analyze_changeset"
  | "add_filechange"
  | "summarize_changeset"
  // A generic task with no dedicated handler: payload.description is
  // prose for an agent to read like a prompt and figure out on its own,
  // rather than a kind-specific typed payload.
  | "work"
  // Proposes a real code change, with the full content of every
  // changed file as payload -- granting it is what actually commits
  // it (engine/changeset.ts's commitChangeset), the same pattern as
  // merge_request granting a Ladder write. No file ever needs to exist
  // on disk before this: the content lives entirely in the payload.
  | "submit_changeset"
  // A Maintainer's review of a proposed changeset, before it may be
  // merged -- is this what was actually asked for, does it stay in
  // scope, does it do anything that wasn't requested. Separate from
  // submit_changeset's own (coordinator-scope) grant, which is purely
  // mechanical: 3-way merge, commit, Ladder writes. submit_changeset
  // depends_on this, so it can't even be claimed before a Maintainer
  // has granted it (see engine/lane.ts's ASK_SCOPE and the backstop
  // check in answer()).
  | "changeset_review"
  // Posted when a submit_changeset is denied specifically because
  // another change landed first and the proposal, based on a now-stale
  // snapshot, would have dropped it -- a real concurrency conflict
  // between two agents' work, not a bug in either one. Payload carries
  // the original proposal (files/message/summary) and the conflict
  // reason, so whoever claims this reconciles the two instead of
  // starting over from the task description alone.
  | "resolve_conflict";

export interface AskEntry {
  id: string;
  type: "ASK";
  kind: AskKind;
  from: string;
  /** Kind-specific data: what's actually being asked for (a commit sha, a target ask id to claim, a Rung to merge, etc). */
  payload?: unknown;
  /** Ask ids (same lane) that must each have a "grant"/"complete" Answer before this one may be claimed. */
  depends_on?: string[];
  /** Higher = more urgent. A query-time sort hint (see engine/workqueue.ts), not a scheduling guarantee. */
  priority?: number;
  at: string;
}

export interface AnswerEntry {
  id: string;
  type: "ANSWER";
  /** The AskEntry.id this answers. */
  ask: string;
  from: string;
  action: "grant" | "deny" | "complete";
  /** Kind-specific data: a grant id for a claim, a built Rung for a work item, etc. */
  payload?: unknown;
  at: string;
}

export interface InsightEntry {
  type: "INSIGHT";
  kind: "norm" | "trap";
  text: string;
  from: string;
  at: string;
}

export type HistoryEntry = AskEntry | AnswerEntry | InsightEntry;

export interface LaneRef {
  repo: string;
  lane: string;
}

export interface RelatedLaneEntry extends LaneRef {
  origin: LaneRef;
  status: LaneStatus;
}

export interface Lane {
  id: string;
  repo: string;
  origin: LaneRef | null;
  name: string;
  objective: string;
  status: LaneStatus;
  scope: string[];
  trigger: Trigger;
  coordinators: string[];
  // Who may grant a changeset_review -- the Maintainer role from
  // site/content/governance/index.md ("Reviews and decides;
  // accountable for what merges"), distinct from coordinators (which
  // governs the mechanical merge step: commit_changeset,
  // ladder_write_rung). Defaults to coordinators when not set
  // explicitly, so existing fully-autonomous flows keep working;
  // narrow it (e.g. to a single human actor id) to require real human
  // sign-off.
  maintainers: string[];
  budget?: { cap_usd: number; spent_usd: number };
  history: HistoryEntry[];
  related_lanes: RelatedLaneEntry[];
}

export interface Changeset {
  id: string;
  lane: string;
  read_set: string[];
  write_set: string[];
  reviews: { agent: string; verdict: "approve" | "request_changes"; at: string }[];
  merge_grant: {
    issued_to: string;
    issued_by: string;
    single_use: boolean;
    consumed_at: string | null;
  } | null;
}

export interface Decision {
  commit: string;
  lane: string;
  changeset: string;
  merged_via: "occ_fast_path" | "human_review";
  checks: string[];
}