@mstar-harness/dsh 2.1.1

package/dist/client/panel/graph/project-graph.d.ts

@@ -0,0 +1,499 @@
+/**
+ * `projectGraph(source): ZoneView` — the pure projection of the
+ * `mstar-engine-status` catalog source onto the zone dashboard view model
+ * (spec panel-zones §3). Total function: NEVER throws, produces no
+ * React render types, and degrades per field instead of guessing — the
+ * same philosophy as `selectEngineStatus`'s try/catch fallback and the
+ * `guards.ts` contract (missing → `unknown`, never a fabricated value).
+ *
+ * Two strictly separated inputs (spec §3):
+ * - schema constants (`./schema.ts`) — the 5 iteration steps (PHASE_IDS), the
+ *   5 kanban buckets (PLAN_STATE_IDS — Blocked/unknown merged into
+ *   `blocked-unknown`, plan 20260813-panel-quick-fixes Task 1) and the
+ *   expected role pipeline (EXPECTED_ROLE_FLOW), all client-side design
+ *   knowledge;
+ * - catalog evidence — `iteration.gate.transition` lights the current step
+ *   (steps before it become `done` — plan 20260812-panel-f5-iteration-zone-fix
+ *   Task 1, its forward target becomes `next`), `gate.ok/violations` become
+ *   the PASS/FAIL verdict + count, and `state.plans[].status` rows fall into
+ *   the exact-match kanban buckets. `iteration.compassStatus` (the steering
+ *   compass frontmatter `status`, `'active' | 'locked'` — spec panel-f4 §2.3
+ *   R9 / §5 D5) re-derives the current step during Phase 1: `'active'` WITH a
+ *   `phase-2-execute` transition (compass and gate mutually consistent — QC
+ *   wave F-001) → Step 1 (iteration-start) is current with verdict 'unknown'
+ *   (Phase 1 has no gate evaluation → no PASS/FAIL badge) + next Step 2;
+ *   `'active'` with a transition past Phase 2 (an inconsistent harness
+ *   state), `'locked'`, or missing → the transition-driven logic below
+ *   (Step 2→4 + gate verdict).
+ *
+ * Migration from the legacy graph GraphView (spec §3, per field):
+ * - kept & moved: `violations` / `flow.events` / `flow.unexpected` → top-level
+ *   `violations` / `events` / `unexpected` (FlowEventView projection unchanged,
+ *   incl. the `settled` pairing marker — shared with the agent-entity status
+ *   derivation via the single `pairSettleStatus` pairing walk); `iterationId`
+ *   → `iteration.iterationId`;
+ * - deleted (legacy graph structure): `phases`, `phaseEdges`,
+ *   `planStates`, `planEdges`, `connector`, `currentPhase`, `flow.stages`
+ *   (the stage skeleton + entities/edges now live in the `agents` projection —
+ *   spec §4);
+ * - added: `iteration.steps / currentStep / branches`, `tasks.columns / total
+ *   / truncated`, `agents` (entities + actual/supervise edges + executing/
+ *   pending counts — spec §4).
+ *
+ * Agent-entity semantics (plan 20260811-panel-f3-agent-general — the
+ * per-role aggregation refactor): entities aggregate by ROLE, not by session
+ * — a KNOWN_AGENTS roster role keys its own card (same role across sessions
+ * folds into one card ×N), and EVERY non-roster dispatch (`scout`,
+ * unregistered roles, anonymous `role === ''`) folds into the single
+ * `general` bucket entity (key `'general'`, role shown `'general'`). The
+ * legacy `unexpected` zone is GONE — stage-null non-on-demand entities now
+ * project `zone: 'general'`. Placement (plan 20260812-panel-f5-agent-layout
+ * Task 1, user 2026-08-12): the projection only declares the zone — the
+ * RENDER places `zone: 'general'` entities in an unknown sub-partition at
+ * the bottom of the LAST column (plan 20260812-panel-f5-design-system Task
+ * 5, user 2026-08-12 feedback #3 — the standalone rightmost unknown column
+ * is superseded: 4 columns total). The SDD loop back-edge (sdd-implement →
+ * general) stays REMOVED from the projection (plan 20260811-panel-f4-agent-view
+ * Task 1); the F5 supervise line is a SEPARATE sub-bucket edge
+ * (`kind: 'supervise'`, see `superviseEdges`). The event-log `unexpected`
+ * badge is a SEPARATE, unchanged semantic (`expected` ⟺ role ∈
+ * EXPECTED_ROLE_FLOW union). The `sdd-implement` column is further split
+ * into implementor / reviewer SUB-BUCKETS (plan 20260812-panel-f5-agent-layout
+ * Task 1): every entity carries a projected `bucket` field ('implementor' /
+ * 'reviewer' / null via SDD_BUCKET_ROLES — a layout dimension ORTHOGONAL to
+ * expectedness: on-demand roles keep their `unexpected` badge inside the
+ * implementor bucket).
+ *
+ * Degradation (spec §8): `source === null` → legal empty view (the panel
+ * never mounts the graph for that case, but the projection stays total);
+ * missing iteration / unresolvable transition → `active: false` + 5 idle
+ * steps + `degraded.iteration` (the old `degraded.transition` is merged into
+ * `iteration.active === false` — `degraded.iteration ⟺ !active`); `state`
+ * null → 5-column skeleton (count 0) + `degraded.state`; `state.plans`
+ * missing → same skeleton + `degraded.plans`; `state.agentFlow`
+ * missing/unreadable → agents roster + `degraded` (full KNOWN_AGENTS idle
+ * cards, no executing/pending claims); 0 events → `empty` (idle roster +
+ * pending skeleton). `iteration.compassStatus` missing, non-union (old
+ * catalog rows / fixtures — the field is OPTIONAL, spec D5), or `'active'`
+ * with a transition past Phase 2 (an inconsistent harness state — QC wave
+ * F-001) degrades to the existing transition-driven current-step logic
+ * (Step 2→4) — backward compatible, `active` semantics unchanged.
+ */
+import type { MstarEngineStatusSource } from '../../../types.ts';
+import { type AgentZone, type PhaseId, type PlanStateId } from './schema.ts';
+/** Current-step verdict from `gate.ok` (spec §3). */
+export type PhaseVerdict = 'pass' | 'fail' | 'unknown';
+/** One gate violation row, str()-guarded (drives the footer collapsible list, spec §2). */
+export interface GraphViolation {
+    severity: string;
+    code: string;
+    message: string;
+}
+/** Event status coloring: dispatch → dispatched|advisory|denied; settle → ok|error|denied. */
+export type FlowEventStatus = 'dispatched' | 'advisory' | 'denied' | 'ok' | 'error';
+/**
+ * One projected agent-flow event (spec agent-flow-catalog-graph §2.4 —
+ * unchanged by the zone refactor). Every field degrades individually via
+ * `guards.ts` — a missing/illegal value becomes `null`/''/`0`/a base status,
+ * never a throw and never a guessed value. Rows whose `kind` is not
+ * dispatch/settle cannot be classified and are skipped entirely
+ * (belt-and-suspenders: the T1 ledger reader already normalizes kind).
+ */
+export interface FlowEventView {
+    /** `${ts}-${kind}-${index}` — stable id (index = position in the projected window). */
+    id: string;
+    ts: number;
+    kind: 'dispatch' | 'settle';
+    /** `Execute as`; '' for settle rows without a paired identity. */
+    role: string;
+    planId: string | null;
+    taskId: string | null;
+    taskCategory: string | null;
+    agent: string | null;
+    /** dispatch → dispatched|advisory|denied; settle → ok|error|denied (spec §2.4). */
+    status: FlowEventStatus;
+    /** `role` ∈ the EXPECTED_ROLE_FLOW role union (spec §2.3 exact-string match). */
+    expected: boolean;
+    /** The matched expected stage; null → unexpected role. */
+    stage: {
+        phase: PhaseId;
+        stage: string;
+    } | null;
+    /** dispatch: has an EXACT-identity-paired settle (exact pairing; an unpaired settle stays unpaired — honest); settle: always false. */
+    settled: boolean;
+    /** Settle rows only (plan `20260811-panel-f4-timeliness` Task 1): the settle carries the PAIRED dispatch's identity (exact pairing). */
+    paired?: boolean;
+    durationMs: number | null;
+}
+/**
+ * One iteration step (spec §3 + plan 20260812-panel-f5-iteration-zone-fix
+ * Task 1): the PHASE_IDS skeleton with current/next/done/idle lit by
+ * `gate.transition` evidence — the CURRENT step, its forward target (`next`)
+ * and every step BEFORE it (`done` — completed: the Task 1 fix, a finished
+ * Step 1 must not read as idle「待命」 while Step 2 is current). The `step`
+ * number is 1-based (1..5). `verdict` is carried by the CURRENT step only.
+ */
+export interface IterationStepView {
+    id: PhaseId;
+    /** 1-based position in PHASE_IDS (1..5). */
+    step: number;
+    /** 'current' (the gate transition) / 'next' (its forward target) / 'done'
+     * (a step BEFORE the current one — completed) / 'idle' (schema-only). */
+    state: 'current' | 'next' | 'done' | 'idle';
+    /** Current-step gate verdict; 'unknown' on non-current steps. */
+    verdict: PhaseVerdict;
+}
+/**
+ * One kanban column (spec §3 + plan 20260813-panel-quick-fixes Task 1): the
+ * PLAN_STATE_IDS skeleton with plan rows bucketed by status — `Blocked` and
+ * any non-matching status (the former `unknown` catch-all) both fold into the
+ * single `blocked-unknown` column. `count` is the FULL column count; `plans`
+ * keeps EVERY row (no slice — the render truncates to PLAN_CAP and offers a
+ * 「更多」 expand). The Done column is additionally sorted with the shared
+ * plan-sort key (`plan-sort.ts`); every other column keeps input order.
+ * `capped` carries PLAN_CAP when the column overflows, else null.
+ */
+export interface KanbanColumnView {
+    id: PlanStateId;
+    /** ALL rows (Done: plan-sort order; others: input order). */
+    plans: {
+        id: string;
+        status: string;
+    }[];
+    /** Full column count (equal to `plans.length`). */
+    count: number;
+    /** PLAN_CAP when the column overflows (count > PLAN_CAP); null otherwise. */
+    capped: number | null;
+}
+/**
+ * One agent-pipeline stage (spec §4): the EXPECTED_ROLE_FLOW skeleton with its
+ * expected role chips. No dispatch evidence → the stage renders as a dashed
+ * "待执行" placeholder and its expected roles count into `pending`.
+ */
+export interface AgentZoneStage {
+    /** `${phase}:${stage}`. */
+    id: string;
+    phase: PhaseId;
+    stage: string;
+    roles: readonly string[];
+    /**
+     * Dispatch evidence (spec §4): any dispatch row's role maps to this stage —
+     * the render shows the dashed "待执行" placeholder ONLY for un-evidenced
+     * stages (the `pending` count is the same per-stage test). Evidence comes
+     * from ALL dispatch rows, not just each entity's latest — an agent
+     * re-dispatched under another role still lights its earlier stage.
+     */
+    evidenced: boolean;
+}
+/**
+ * One agent entity card (spec §4 + §6.2 + plan 20260811-panel-f3-agent-general):
+ * either a ROLE aggregated across its dispatch rows (count + latest ts;
+ * identity fields reflect the LATEST dispatch — the same dispatch that
+ * decides the status; `agent` / `task` are record fields, never the title)
+ * or a synthesized `idle` card for a KNOWN_AGENTS roster member with NO
+ * dispatch evidence (key = role id; count 0 / ts 0 — never a guessed status).
+ * Non-roster dispatches (former `generalPurpose` / `scout` / anonymous '')
+ * aggregate into the single `general` bucket entity.
+ */
+export interface AgentEntityView {
+    /**
+     * THE ROLE id for lit cards (KNOWN_AGENTS membership — `general` for every
+     * non-roster dispatch); the KNOWN_AGENTS role id for idle cards. INVARIANT
+     * (spec §6.2, F-001): keys are UNIQUE across the whole `entities` array —
+     * an evidence-derived `general` key suppresses the idle general twin in
+     * `idleEntities`, so the React `key` / `layoutAgents` `cards.set` never see
+     * duplicates.
+     */
+    key: string;
+    /** The raw session id of the LATEST dispatch; null for idle cards. */
+    agent: string | null;
+    /** Display name = `agent ?? key` (spec §4); the role id for idle cards. */
+    name: string;
+    /** Role chip — the raw role of the latest dispatch; `'general'` for the
+     * bucket entity; the known role id for idle cards. */
+    role: string;
+    /** Task tag `${planId}#${taskId}` (missing planId → null; taskId missing → planId); null for idle cards. */
+    task: string | null;
+    /** Spec §4 hardcoded priority: latest-dispatch verdict → paired settle → running. */
+    status: AgentEntityStatus;
+    /** No dispatch evidence → the idle (muted "未工作") card; idle never counts into `executing`. */
+    idle: boolean;
+    /** Dispatch count of this entity in the window (settles never count); 0 for idle cards. */
+    count: number;
+    /** Latest dispatch ts (the status/identity source); 0 for idle cards. */
+    ts: number;
+    /** Latest dispatch's stage via `roleStageIndex` (first constant-order match); null → off-pipeline role; KNOWN_AGENTS stage for idle cards. */
+    stage: {
+        phase: PhaseId;
+        stage: string;
+    } | null;
+    /** Column zone (plan 20260811-panel-f3-agent-general — projection-owned,
+     * the render NEVER heuristically guesses): 'flow' (stage columns), 'on-demand'
+     * (ops-engineer / prompt-engineer — implementor-sub-bucket dispatches with
+     * an on-demand badge; the standalone on-demand column is REMOVED, plan
+     * 20260812-panel-f5-agent-layout Task 2) or 'general' (the general bucket —
+     * the rightmost UNKNOWN column, Task 2). Derived from the role for lit
+     * cards, from the KnownAgent `zone` for idle cards. */
+    zone: AgentZone;
+    /** SDD sub-bucket (plan 20260812-panel-f5-agent-layout Task 1 —
+     * projection-derived, the render ONLY consumes it): role ∈
+     * SDD_BUCKET_ROLES.implementor → 'implementor' (incl. on-demand roles),
+     * role ∈ SDD_BUCKET_ROLES.reviewer → 'reviewer' (code-reviewer); every
+     * other role (qc/qa/review-edit-chain/general) → null. Same rule for idle
+     * cards (KNOWN_AGENTS id → SDD_BUCKET_ROLES lookup). */
+    bucket: AgentBucket | null;
+    /** Transparency tier (plan 20260812-panel-f5-design-system Task 4 — the
+     * TIME dimension, design doc §3): the iteration's current phase vs the
+     * entity's pipeline-stage phase — 'current' (chrome full-strength), 'next'
+     * (mid transparency), 'off' (low transparency — passed phases, on-demand /
+     * general bucket), null (no iteration/plan — NO override, idle status quo).
+     * ORTHOGONAL to `bucket` (space: same-column partition) / `zone` (column) /
+     * `status` (evidence): the render fades the card CHROME only — the status
+     * point and the running ring/glow NEVER fade (design doc §3.4 HARD). */
+    emphasis: AgentEmphasis;
+}
+/** The SDD sub-bucket a role belongs to within the `sdd-implement` column
+ * (plan 20260812-panel-f5-agent-layout Task 1): 'implementor' | 'reviewer';
+ * roles in neither bucket project `null`. The bucket is a LAYOUT dimension,
+ * ORTHOGONAL to expectedness (SDD_BUCKET_ROLES vs EXPECTED_ROLE_FLOW — an
+ * on-demand role in the implementor bucket stays OUTSIDE the expected union). */
+export type AgentBucket = 'implementor' | 'reviewer';
+/** Transparency tier (plan 20260812-panel-f5-design-system Task 4 — design
+ * doc §3.1): the TIME dimension of an entity — the iteration's current phase
+ * vs the entity's pipeline-stage phase. 'current' → chrome full-strength,
+ * 'next' → mid transparency (expected but not yet), 'off' → low transparency
+ * (already-passed phase, or NO stage — on-demand / general bucket), null →
+ * no iteration/plan (NO override — the render keeps the idle status quo). */
+export type AgentEmphasis = 'current' | 'next' | 'off' | null;
+/**
+ * Entity status (spec §4, hardcoded priority; plan
+ * 20260813-panel-quick-fixes Task 2): `denied` comes from the LATEST dispatch's
+ * verdict (the only terminal verdict — settle-independent); `error`/`settled`
+ * come from the settle paired with that dispatch; `running` = no paired settle
+ * yet (exact identity pairing — an unpaired settle stays unpaired, honest);
+ * `idle` = a KNOWN_AGENTS roster member with no dispatch evidence (spec §6.2 —
+ * never guessed as running/settled). `advisory` is RETAINED as a union member
+ * for backward shape, but the derivation (entityStatus) no longer emits it —
+ * an advisory-verdict dispatch now falls through to its settle pair (or
+ * `running`); the advisory VERDICT still renders in the event log.
+ */
+export type AgentEntityStatus = 'running' | 'settled' | 'error' | 'denied'
+/** Retained for shape compat; the derivation (entityStatus) no longer emits it. */
+ | 'advisory' | 'idle';
+/** Edge kinds (spec §4 + plan 20260812-panel-f5-design-system Task 5 — the
+ * 2026-08-12 finalized line semantics, design doc §2.2): handoff / sub-bucket
+ * supervision arrows. `expected` (stage skeleton) and `next` (running
+ * animation) are REMOVED — the column order implies the flow, the running
+ * card glow/status point carries the position (user feedback #1/#5). */
+export type AgentEdgeKind = 'actual' | 'supervise';
+/**
+ * One agents-zone arrow (spec §4 + plan 20260812-panel-f5-agent-layout Task
+ * 1 + plan 20260812-panel-f5-design-system Task 5):
+ * - `actual`: same-plan handoff between ts-adjacent dispatch ENTITY keys
+ *   (source/target = entity key — role-based since plan
+ *   20260811-panel-f3-agent-general). Task 5 filters general-bucket endpoints
+ *   (a general handoff is noise, not a meaningful transfer) and keeps at most
+ *   ONE edge per entity-key pair (the latest direction) — design doc §2.2;
+ * - `supervise`: ONE static sub-bucket line inside the `sdd-implement`
+ *   column — implementor ↔ reviewer mutual supervision (mstar-sdd contract;
+ *   the render draws it as a bidirectional double arrow, Task 2).
+ *   source/target embed the column id as an anchor prefix:
+ *   `<stage-id>:implementor` / `<stage-id>:reviewer`. NOT per-entity pairs —
+ *   drawing per-role pairs would fabricate concrete supervision relations
+ *   where no evidence exists (evidence-level handoffs are covered by
+ *   `actualEdges`). STATIC presence (design knowledge) + evidence-driven
+ *   lighting via `evidenced` (dim without implement/review dispatch
+ *   evidence, lit with it — never a fabricated activation).
+ */
+export interface AgentEdge {
+    kind: AgentEdgeKind;
+    /** actual: entity key; supervise: `<stage-id>:implementor|reviewer`. */
+    source: string;
+    target: string;
+    /** Unused by the Task 5 line set (the removed `next` arrow carried the
+     * running entity key); kept for shape stability — always null. */
+    entityKey: string | null;
+    /** Supervise edges only (plan 20260812-panel-f5-agent-layout Task 1):
+     * evidence-driven lighting — true when any dispatch row's role belongs to
+     * an SDD sub-bucket (implementor ∪ reviewer), false otherwise (dim).
+     * Absent (undefined) for actual. */
+    evidenced?: boolean;
+}
+/**
+ * The canvas degradation-note classification (spec §8, F-002): the projection
+ * decides the note from the RAW ledger (never a UI-side heuristic on the
+ * entity list): `empty` = 0 events; `settle-only` = events present but NO
+ * dispatch row (all settle / garbage rows — genuinely no dispatch evidence);
+ * `null` = dispatch evidence present (incl. anonymous dispatch rows — they
+ * are evidence, not settle-only). The unreadable-ledger case is the SEPARATE
+ * `degraded` flag, not a note value.
+ */
+export type AgentZoneNote = 'empty' | 'settle-only' | null;
+/**
+ * The projected agents zone (spec §4 + §6.2): the EXPECTED_ROLE_FLOW stage
+ * skeleton plus the dispatch-derived entity cards and the actual/supervise
+ * arrows. Total function — NEVER throws and NEVER fabricates: the KNOWN_AGENTS
+ * roster always projects as entities (idle cards when there is no evidence) —
+ * agentFlow missing/unreadable → `degraded` (full idle roster + no
+ * executing/pending claims); 0 events → `empty` (full idle roster + pending
+ * skeleton); settle-only ledger → full idle roster (settles never produce
+ * cards) + full pending skeleton.
+ */
+export interface AgentZoneView {
+    /** The EXPECTED_ROLE_FLOW skeleton (pending stages). */
+    stages: readonly AgentZoneStage[];
+    /** `state.agentFlow` missing/unreadable (ledger absent → no evidence to show). */
+    degraded: boolean;
+    /** `state.agentFlow` present but 0 events (recording started at plan merge). */
+    empty: boolean;
+    /** The projected canvas note (spec §8, F-002 — see `AgentZoneNote`). */
+    note: AgentZoneNote;
+    /** Evidence-derived dispatch entities ∪ idle KNOWN_AGENTS cards — the full roster is NEVER hidden (spec §6.2). */
+    entities: readonly AgentEntityView[];
+    /** expected (stage skeleton) + actual (same-plan handoffs) + at most one next (latest running). */
+    edges: readonly AgentEdge[];
+    /** `running` entity count — the summary "N 执行中" (idle cards never count). */
+    executing: number;
+    /** Sum of expected roles of stages with no dispatch evidence — the summary "M 待执行". */
+    pending: number;
+    /** The FIRST `state.plans[]` row with status 'InProgress' (catalog order);
+     * null when no plan is in progress (plan 20260812-panel-f5-design-system
+     * Task 8 — the Phase 2 group's current-plan annotation, user 2026-08-12
+     * feedback #2). Total function: state/plans missing or no InProgress row →
+     * null (never fabricated). */
+    activePlanId: string | null;
+    /** How many `state.plans[]` rows are InProgress (the render shows
+     * `+N more` when several plans run in parallel — honest, same shape as the
+     * kanban overflow hint; never hides the count behind the first id). */
+    activePlanCount: number;
+}
+export interface ZoneView {
+    iteration: {
+        /** Iteration exists AND `gate.transition` resolves (spec §3; `degraded.iteration ⟺ !active`). */
+        active: boolean;
+        iterationId: string | null;
+        /** 5 steps in PHASE_IDS order (spec §3). */
+        steps: IterationStepView[];
+        /** 1-based index of the current step in PHASE_IDS; null = inactive. */
+        currentStep: number | null;
+        /** Branch anchors from `state`; null while inactive (rendered only when active, spec §3). */
+        branches: {
+            iterationBase: string | null;
+            target: string | null;
+            specIntegration: string | null;
+        } | null;
+        /** Current-step gate verdict; 'unknown' when inactive. */
+        verdict: PhaseVerdict;
+        /** Current-step `gate.violations` count; null when inactive. */
+        violationCount: number | null;
+    };
+    tasks: {
+        /** 5 columns: Todo/InProgress/InReview/Done/blocked-unknown (spec §3). */
+        columns: KanbanColumnView[];
+        /** Plan total across all columns, the merged column included. */
+        total: number;
+        /** Any column overflow (rows > PLAN_CAP). */
+        truncated: boolean;
+    };
+    agents: AgentZoneView;
+    /** Current-step gate verdict — footer gate-summary seat (spec §3). */
+    verdict: PhaseVerdict;
+    /** Gate violations (str()-guarded), for the footer list. */
+    violations: GraphViolation[];
+    /** Actual agent-flow events, latest first, ≤50 (spec §3; `flow.events` moved top-level). */
+    events: FlowEventView[];
+    /** Off-pipeline-role DISPATCH events (settles never appear). */
+    unexpected: FlowEventView[];
+    degraded: {
+        iteration: boolean;
+        state: boolean;
+        plans: boolean;
+    };
+}
+export declare function projectGraph(source: MstarEngineStatusSource | null): ZoneView;
+/**
+ * `projectAgents(source, currentStep): AgentZoneView` — the agents zone (spec
+ * §4 + §6.2). `currentStep` is the ITERATION's current step (1-based into
+ * PHASE_IDS, null when inactive — already computed by `projectGraph`, spec
+ * §3): it drives each entity's `emphasis` tier (plan
+ * 20260812-panel-f5-design-system Task 4 — design doc §3.3; `null` → every
+ * entity `emphasis: null`, no override).
+ * Total function: NEVER throws and NEVER fabricates values:
+ *
+ * - `state.agentFlow` null/unreadable → `degraded`: the FULL KNOWN_AGENTS
+ *   roster as idle entities + skeleton (executing 0, pending 0 — never a
+ *   guessed count; the roster is never hidden);
+ * - a MISSING ledger file reads as the server's empty view → present with 0
+ *   events → `empty`: full idle roster + pending skeleton (every expected
+ *   role is pending);
+ * - otherwise: entities aggregated from dispatch rows (with `idle: false`),
+ *   statuses via the shared pairing walk, the un-evidenced KNOWN_AGENTS
+ *   members appended as idle cards, actual/supervise edges (design doc §2.2 —
+ *   the `expected` skeleton and `next` animation edges are REMOVED by plan
+ *   20260812-panel-f5-design-system Task 5), and the
+ *   executing (running entities — idle never counts) / pending
+ *   (un-evidenced stage roles) counts.
+ *
+ * Entity-key invariant (F-001 — qc1/qc2 Warning): the concatenated key space
+ * (evidence keys ∪ idle role ids) is UNIQUE by construction — `idleEntities`
+ * suppresses a known role's idle card when its id already exists as an
+ * evidence-derived entity key (a NON-roster dispatch produces a lit `general`
+ * key while the roster `general` id stays un-evidenced — the twin is
+ * suppressed via `litKeys`), so the render layer's `key`/`cards.set` never
+ * collide.
+ *
+ * Canvas note (F-002 — qc1 Warning): `note` classifies the readable ledger in
+ * the projection ('empty' / 'settle-only' / null — see `AgentZoneNote`); the
+ * UI consumes it directly and never infers settle-only from the entity list
+ * (garbage rows would fake it).
+ *
+ * Phase-2 plan note (plan 20260812-panel-f5-design-system Task 8 — user
+ * 2026-08-12 feedback #2): `activePlanId` / `activePlanCount` ride the
+ * `state.plans[]` InProgress rows (catalog order) — the Phase 2 group label
+ * annotates the current plan; degraded/empty branches include the note too
+ * (it is a state.plans annotation, independent of the ledger evidence).
+ */
+export declare function projectAgents(source: MstarEngineStatusSource | null, currentStep: number | null): AgentZoneView;
+/** One row of the pairing walk — the identity a PAIRED settle carries (plan
+ * `20260811-panel-f4-timeliness` Task 1, spec R1: exact identity pairing,
+ * never owner+time guessing). */
+interface PairingRow {
+    kind: 'dispatch' | 'settle';
+    agent: string | null;
+    role?: string;
+    planId?: string | null;
+    taskId?: string | null;
+    /** Settle rows only: true → the settle carries the paired dispatch's identity (exact pairing). */
+    paired?: boolean;
+    status?: FlowEventStatus;
+}
+/**
+ * The paired dispatch index set (spec §4): the events projection's `settled`
+ * marker. Same walk as the entity status derivation — `pairSettleStatus`
+ * minus the settle statuses.
+ */
+export declare function pairSettleIndexes(rows: readonly PairingRow[]): ReadonlySet<number>;
+/**
+ * `projectFlowEvents(source): { events, unexpected }` — the flow events
+ * projection (spec §3: `flow.events` / `flow.unexpected` moved top-level;
+ * `flow.stages` merged into the plan-3 agents projection). Total function:
+ * NEVER throws, NEVER fabricates values.
+ *
+ * - events: the actual events, latest first, ≤50 (dispatch + settle rows);
+ * - unexpected: DISPATCH events whose role is not in the expected role union
+ *   (e.g. `general` / `explore` / `scout`). Settle rows are completion
+ *   records — they carry no role at all, so they never flag as unexpected
+ *   even though their `expected` field is false ('' ∉ union);
+ * - settled: EXACT identity pairing via `pairSettleIndexes` (the same walk the
+ *   agent-entity status derivation uses; an unpaired settle stays unpaired —
+ *   honest). The panel never depends on the pairing's correctness;
+ * - degradation: agentFlow null/unreadable → no events (the `agents`
+ *   skeleton carries the `degraded` marker); the MISSING ledger file reads as
+ *   the server's empty view → present with 0 events → no events either (the
+ *   `agents` skeleton carries `empty`).
+ */
+export declare function projectFlowEvents(source: MstarEngineStatusSource | null): {
+    events: FlowEventView[];
+    unexpected: FlowEventView[];
+};
+export {};