@warpgogol/werkstatt-shared 0.2.0

package/src/surface/decision-composer.ts

@@ -0,0 +1,156 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Architecture review 2026-07-10: compose the final IndexDecision from pure gate results.
+  Each gate (demand, evidence, substance, freshness, budget) is a small pure function that
+  returns a GateResult. The composer applies precedence and produces the final IndexDecision.
+  This concentrates all indexability logic in one module instead of scattered inline mutations
+  in the consumer's expandBlueprint.
+</purpose>
+<non-goals>
+  <item>Do not load data from the filesystem — gate inputs are supplied by the caller.</item>
+  <item>Do not mutate VirtualRouteEntry — the caller applies the composed decision.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Architecture review 2026-07-10: initial implementation of composeIndexDecision and pure gate functions.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { IndexDecision, IndexReason } from "./types.ts";
+
+/** The outcome of one gate evaluation. */
+export interface GateResult {
+  readonly gate: "demand" | "evidence" | "substance" | "freshness" | "budget";
+  readonly pass: boolean;
+  readonly reason?: IndexReason;
+  readonly noindex: boolean;
+  /** When true, the entry should be dropped entirely (do-not-emit). */
+  readonly suppress?: boolean;
+  /** Gate-specific score (e.g. substance score 0..100). */
+  readonly score?: number;
+  /** Gate-specific metadata (e.g. werkEvidenceCount). */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/** Precedence order: earlier gates take priority for the reason field when multiple fail. */
+const GATE_PRECEDENCE: readonly GateResult["gate"][] = [
+  "demand",
+  "evidence",
+  "freshness",
+  "substance",
+  "budget",
+];
+
+/**
+ * Compose the final IndexDecision from a base decision (record gate) and an array of gate results.
+ * Applies precedence: the first failing gate in precedence order sets the reason. Any failing gate
+ * sets noindex=true. If any gate requests suppress, the entry should be dropped entirely.
+ */
+export function composeIndexDecision(
+  base: IndexDecision,
+  results: readonly GateResult[],
+): { decision: IndexDecision; suppress: boolean } {
+  const decision = { ...base };
+  let suppress = false;
+
+  const byGate = new Map<GateResult["gate"], GateResult>();
+  for (const r of results) byGate.set(r.gate, r);
+
+  for (const r of results) {
+    if (r.suppress) suppress = true;
+    if (!r.pass && r.noindex) decision.noindex = true;
+    if (r.score !== undefined) decision.substanceScore = r.score;
+    if (r.metadata?.werkEvidenceCount !== undefined) {
+      decision.werkEvidenceCount = r.metadata.werkEvidenceCount as number;
+    }
+  }
+
+  for (const gate of GATE_PRECEDENCE) {
+    const r = byGate.get(gate);
+    if (r && !r.pass && r.reason) {
+      decision.reason = r.reason;
+      break;
+    }
+  }
+
+  if (byGate.get("demand")) decision.demandGate = byGate.get("demand")!.pass;
+  if (byGate.get("evidence")) decision.evidenceGate = byGate.get("evidence")!.pass;
+  if (byGate.get("substance")) decision.substanceGate = byGate.get("substance")!.pass;
+  if (byGate.get("freshness")) decision.fresh = byGate.get("freshness")!.pass;
+  if (byGate.get("budget")) decision.withinBudget = byGate.get("budget")!.pass;
+
+  return { decision, suppress };
+}
+
+/** Demand gate: checks whether at least one qualifying demand signal exists for this entry. */
+export function evaluateDemandGate(
+  hasMatchingDemand: boolean,
+  missingPolicy: "noindex" | "do-not-emit" = "noindex",
+): GateResult {
+  if (hasMatchingDemand) {
+    return { gate: "demand", pass: true, noindex: false };
+  }
+  return {
+    gate: "demand",
+    pass: false,
+    reason: "missing-demand",
+    noindex: true,
+    suppress: missingPolicy === "do-not-emit",
+  };
+}
+
+/** Evidence gate: checks whether enough Werk evidence records exist for this entry. */
+export function evaluateEvidenceGate(
+  matchingCount: number,
+  minRequired: number | undefined,
+  existenceSource: "works" | undefined,
+): GateResult {
+  if (typeof minRequired !== "number" && !existenceSource) {
+    return { gate: "evidence", pass: true, noindex: false };
+  }
+  const pass = typeof minRequired !== "number" || matchingCount >= minRequired;
+  if (pass) {
+    return {
+      gate: "evidence",
+      pass: true,
+      noindex: false,
+      metadata: { werkEvidenceCount: matchingCount },
+    };
+  }
+  return {
+    gate: "evidence",
+    pass: false,
+    reason: "missing-werk-evidence",
+    noindex: true,
+    suppress: existenceSource === "works",
+    metadata: { werkEvidenceCount: matchingCount },
+  };
+}
+
+/** Substance gate: checks whether the page substance score meets the minimum threshold. */
+export function evaluateSubstanceGate(score: number, substanceMin: number): GateResult {
+  if (substanceMin === 0 || score >= substanceMin) {
+    return { gate: "substance", pass: true, noindex: false, score };
+  }
+  return { gate: "substance", pass: false, reason: "thin", noindex: true, score };
+}
+
+/** Freshness gate: checks whether the page's records are fresh within the SLA. */
+export function evaluateFreshnessGate(fresh: boolean, hasInvalidDate: boolean): GateResult {
+  if (hasInvalidDate) {
+    return { gate: "freshness", pass: false, reason: "invalid-freshness", noindex: true };
+  }
+  if (fresh) {
+    return { gate: "freshness", pass: true, noindex: false };
+  }
+  return { gate: "freshness", pass: false, reason: "decayed", noindex: true };
+}
+
+/** Budget gate: checks whether the entry is within the index budget. */
+export function evaluateBudgetGate(withinBudget: boolean): GateResult {
+  if (withinBudget) {
+    return { gate: "budget", pass: true, noindex: false };
+  }
+  return { gate: "budget", pass: false, reason: "over-budget", noindex: true };
+}

package/src/surface/eligibility.ts

@@ -0,0 +1,372 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0192] Axis-generic eligibility engine. The legacy foerderung matrix generalized over an
+  arbitrary record set and a declarative axis→field binding: enumerate candidate tuples per depth,
+  count matching active records, derive live / noindex / redirect-stub decisions, and expose
+  live children / siblings for internal-link grids. Pure — no I/O.
+</purpose>
+<non-goals>
+  <item>Do not build URLs or blocks (the Blueprint provider does).</item>
+  <item>Do not read content (the kernel command supplies records + universes).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0192: initial axis-generic engine.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  AxisTuple,
+  EligibilityPolicy,
+  IndexDecision,
+  SurfaceAxis,
+  SurfaceRecord,
+} from "./types.ts";
+
+/** Axis id → the record field carrying that axis's membership value(s). */
+export type AxisFieldMap = Readonly<Record<string, string>>;
+
+/** Pre-built index: axisId → value → Set<record index>. */
+export interface RecordIndex {
+  byAxisValue: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<number>>>;
+  records: readonly SurfaceRecord[];
+}
+
+/** A single resolved combination at one depth. */
+export interface MatrixEntry {
+  depth: number;
+  tuple: AxisTuple;
+  recordCount: number;
+  indexable: boolean;
+  noindex: boolean;
+  decision: IndexDecision;
+}
+
+export interface EligibilityMatrix {
+  /** All emitted entries (live + shallow stubs), ordered by depth then enumeration order. */
+  entries: MatrixEntry[];
+  /** pathKey → entry, for ancestor/child/sibling lookups. */
+  byKey: Map<string, MatrixEntry>;
+  /** depth → set of live pathKeys. */
+  liveKeysByDepth: Map<number, Set<string>>;
+  axisOrder: readonly string[];
+}
+
+const DEFAULT_MAX_STUB_DEPTH = 1;
+
+/** Lowercase, dash-only normalization. Throws on characters outside the policy pattern. */
+export function normalizeSegment(value: string, pattern: RegExp): string {
+  const trimmed = value.trim().toLowerCase().replace(/_/g, "-");
+  if (!pattern.test(trimmed)) {
+    throw new Error(`Invalid surface URL segment: "${value}" (normalized: "${trimmed}")`);
+  }
+  return trimmed;
+}
+
+/** True when `value` (string or array) includes the wanted axis value. */
+function fieldIncludes(value: SurfaceRecord[string], wanted: string): boolean {
+  if (Array.isArray(value)) return value.includes(wanted);
+  return value === wanted;
+}
+
+/**
+ * Axis-generic membership test: a record matches a partial tuple when, for every constrained axis,
+ * the record's bound field carries the chosen value. An unconstrained axis imposes no filter.
+ */
+export function matchesRecord(
+  record: SurfaceRecord,
+  tuple: AxisTuple,
+  axisFieldMap: AxisFieldMap,
+): boolean {
+  for (const [axisId, wanted] of Object.entries(tuple)) {
+    if (wanted === undefined) continue;
+    const field = axisFieldMap[axisId];
+    if (!field) return false;
+    if (!fieldIncludes(record[field], wanted)) return false;
+  }
+  return true;
+}
+
+/** Count active records matching the tuple. */
+export function countMatching(
+  records: readonly SurfaceRecord[],
+  tuple: AxisTuple,
+  axisFieldMap: AxisFieldMap,
+): number {
+  let count = 0;
+  for (const record of records) {
+    if (record.status === "archived") continue;
+    if (matchesRecord(record, tuple, axisFieldMap)) count += 1;
+  }
+  return count;
+}
+
+/** Build a per-axis-value index so countMatching can run in intersection time instead of linear time. */
+export function buildRecordIndex(
+  records: readonly SurfaceRecord[],
+  axisFieldMap: AxisFieldMap,
+): RecordIndex {
+  const byAxisValue = new Map<string, Map<string, Set<number>>>();
+  for (let i = 0; i < records.length; i += 1) {
+    const record = records[i];
+    if (record.status === "archived") continue;
+    for (const [axisId, field] of Object.entries(axisFieldMap)) {
+      const value = record[field];
+      if (value === undefined) continue;
+      let axisMap = byAxisValue.get(axisId);
+      if (!axisMap) {
+        axisMap = new Map<string, Set<number>>();
+        byAxisValue.set(axisId, axisMap);
+      }
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          let set = axisMap.get(v);
+          if (!set) {
+            set = new Set<number>();
+            axisMap.set(v, set);
+          }
+          set.add(i);
+        }
+      } else {
+        let set = axisMap.get(value);
+        if (!set) {
+          set = new Set<number>();
+          axisMap.set(value, set);
+        }
+        set.add(i);
+      }
+    }
+  }
+  // Freeze inner structures so callers cannot mutate them.
+  const frozenByAxisValue = new Map<string, ReadonlyMap<string, ReadonlySet<number>>>();
+  for (const [axisId, axisMap] of byAxisValue) {
+    const frozenAxisMap = new Map<string, ReadonlySet<number>>();
+    for (const [value, set] of axisMap) {
+      frozenAxisMap.set(value, set);
+    }
+    frozenByAxisValue.set(axisId, frozenAxisMap);
+  }
+  return { byAxisValue: frozenByAxisValue, records };
+}
+
+/** O(k) count using the pre-built index, where k is the number of matching records. */
+export function countMatchingIndexed(
+  tuple: AxisTuple,
+  axisFieldMap: AxisFieldMap,
+  index: RecordIndex,
+): number {
+  let candidates: Set<number> | undefined;
+  for (const [axisId, wanted] of Object.entries(tuple)) {
+    if (wanted === undefined) continue;
+    const field = axisFieldMap[axisId];
+    if (!field) return 0;
+    const axisMap = index.byAxisValue.get(axisId);
+    if (!axisMap) return 0;
+    const set = axisMap.get(wanted);
+    if (!set) return 0;
+    if (candidates === undefined) {
+      candidates = new Set(set);
+    } else {
+      for (const idx of candidates) {
+        if (!set.has(idx)) candidates.delete(idx);
+      }
+      if (candidates.size === 0) return 0;
+    }
+  }
+  if (candidates === undefined) {
+    // No axis constrained — count all active records.
+    let count = 0;
+    for (const record of index.records) {
+      if (record.status !== "archived") count += 1;
+    }
+    return count;
+  }
+  let count = 0;
+  for (const idx of candidates) {
+    const record = index.records[idx];
+    if (record && record.status !== "archived") count += 1;
+  }
+  return count;
+}
+
+/** Stable key for a (depth, tuple) pair. */
+export function pathKey(depth: number, tuple: AxisTuple, axisOrder: readonly string[]): string {
+  const parts: string[] = [String(depth)];
+  for (let i = 0; i < depth; i += 1) {
+    parts.push(tuple[axisOrder[i]!] ?? "");
+  }
+  return parts.join("|");
+}
+
+/** Enumerate every candidate tuple at `depth` (cartesian over the first `depth` axes' universes). */
+export function* enumerateCandidateTuples(
+  axes: readonly SurfaceAxis[],
+  depth: number,
+): Generator<AxisTuple> {
+  if (depth === 0) {
+    yield {};
+    return;
+  }
+  const head = axes.slice(0, depth);
+  const indices = new Array(depth).fill(0);
+  const universes = head.map((axis) => axis.universe);
+  // Guard against an empty universe producing an infinite/empty product.
+  if (universes.some((u) => u.length === 0)) return;
+  for (;;) {
+    const tuple: AxisTuple = {};
+    for (let i = 0; i < depth; i += 1) tuple[head[i]!.id] = universes[i]![indices[i]!];
+    yield tuple;
+    let carry = depth - 1;
+    while (carry >= 0) {
+      indices[carry] += 1;
+      if (indices[carry] < universes[carry]!.length) break;
+      indices[carry] = 0;
+      carry -= 1;
+    }
+    if (carry < 0) break;
+  }
+}
+
+function deriveDecision(
+  depth: number,
+  recordCount: number,
+  policy: EligibilityPolicy,
+  forceNonIndexable: boolean,
+): IndexDecision {
+  const min = policy.minRecordsPerDepth[depth] ?? 1;
+  const recordGate = recordCount >= min;
+  const noindexThreshold = policy.noindexBelowPerDepth[depth];
+  const noindex = recordGate && noindexThreshold !== undefined && recordCount < noindexThreshold;
+  if (recordGate && forceNonIndexable) {
+    // RFC-0240: a depth gated behind the regional-hub-or-higher tier — the record gate passed but
+    // the resolved entitlement tier has not unlocked this depth (e.g. d3 region hubs on the base tier).
+    return { recordGate, indexable: false, noindex: true, reason: "regional-gated" };
+  }
+  return {
+    recordGate,
+    indexable: recordGate,
+    noindex,
+    ...(recordGate ? {} : { reason: "too-few-records" as const }),
+  };
+}
+
+/**
+ * Build the eligibility matrix. Shallow empty combinations (depth ≤ maxStubDepth) are emitted as
+ * non-live stubs (for 301 redirects); deeper empty combinations are dropped so the build graph
+ * stays bounded.
+ */
+export function buildEligibilityMatrix(
+  axes: readonly SurfaceAxis[],
+  axisFieldMap: AxisFieldMap,
+  records: readonly SurfaceRecord[],
+  policy: EligibilityPolicy,
+  options?: {
+    maxDepth?: number;
+    maxStubDepth?: number;
+    /** RFC-0240: depths forced non-indexable (dropped) unless the resolved entitlement tier unlocks them. */
+    forceNonIndexableDepths?: readonly number[];
+  },
+): EligibilityMatrix {
+  const axisOrder = axes.map((axis) => axis.id);
+  const maxDepth = options?.maxDepth ?? axes.length;
+  const maxStubDepth = options?.maxStubDepth ?? DEFAULT_MAX_STUB_DEPTH;
+  const forceNonIndexableDepths = new Set(options?.forceNonIndexableDepths ?? []);
+
+  const entries: MatrixEntry[] = [];
+  const byKey = new Map<string, MatrixEntry>();
+  const liveKeysByDepth = new Map<number, Set<string>>();
+  const recordIndex = buildRecordIndex(records, axisFieldMap);
+
+  for (let depth = 0; depth <= maxDepth; depth += 1) {
+    const liveSet = new Set<string>();
+    liveKeysByDepth.set(depth, liveSet);
+    for (const tuple of enumerateCandidateTuples(axes, depth)) {
+      const recordCount = countMatchingIndexed(tuple, axisFieldMap, recordIndex);
+      const decision = deriveDecision(
+        depth,
+        recordCount,
+        policy,
+        forceNonIndexableDepths.has(depth),
+      );
+      if (!decision.indexable && depth > maxStubDepth) continue;
+      const entry: MatrixEntry = {
+        depth,
+        tuple,
+        recordCount,
+        indexable: decision.indexable,
+        noindex: decision.noindex,
+        decision,
+      };
+      const key = pathKey(depth, tuple, axisOrder);
+      entries.push(entry);
+      byKey.set(key, entry);
+      if (decision.indexable) liveSet.add(key);
+    }
+  }
+
+  return { entries, byKey, liveKeysByDepth, axisOrder };
+}
+
+/** Walk shallower, dropping one axis at a time, to the nearest live ancestor (or root). */
+export function nearestLiveAncestor(
+  entry: MatrixEntry,
+  matrix: EligibilityMatrix,
+  policy: EligibilityPolicy,
+): MatrixEntry | null {
+  if (policy.redirectPolicy === "root") {
+    return matrix.byKey.get(pathKey(0, {}, matrix.axisOrder)) ?? null;
+  }
+  for (let depth = entry.depth - 1; depth >= 0; depth -= 1) {
+    const tuple: AxisTuple = {};
+    for (let i = 0; i < depth; i += 1) {
+      const axisId = matrix.axisOrder[i]!;
+      if (entry.tuple[axisId] !== undefined) tuple[axisId] = entry.tuple[axisId];
+    }
+    const key = pathKey(depth, tuple, matrix.axisOrder);
+    if (matrix.liveKeysByDepth.get(depth)?.has(key)) return matrix.byKey.get(key) ?? null;
+  }
+  return matrix.byKey.get(pathKey(0, {}, matrix.axisOrder)) ?? null;
+}
+
+/** Live entries one level deeper that extend the given parent tuple. */
+export function liveChildrenOf(parent: MatrixEntry, matrix: EligibilityMatrix): MatrixEntry[] {
+  const childDepth = parent.depth + 1;
+  const liveKeys = matrix.liveKeysByDepth.get(childDepth);
+  if (!liveKeys) return [];
+  const results: MatrixEntry[] = [];
+  for (const key of liveKeys) {
+    const entry = matrix.byKey.get(key);
+    if (!entry) continue;
+    const matchesParent = matrix.axisOrder.slice(0, parent.depth).every((axisId) => {
+      const pv = parent.tuple[axisId];
+      return pv === undefined || pv === entry.tuple[axisId];
+    });
+    if (matchesParent) results.push(entry);
+  }
+  return results;
+}
+
+/** Live entries at the same depth sharing the same parent tuple. */
+export function liveSiblingsOf(entry: MatrixEntry, matrix: EligibilityMatrix): MatrixEntry[] {
+  if (entry.depth === 0) return [];
+  const parentDepth = entry.depth - 1;
+  const parentTuple: AxisTuple = {};
+  for (let i = 0; i < parentDepth; i += 1) {
+    const axisId = matrix.axisOrder[i]!;
+    if (entry.tuple[axisId] !== undefined) parentTuple[axisId] = entry.tuple[axisId];
+  }
+  const parentEntry: MatrixEntry = {
+    depth: parentDepth,
+    tuple: parentTuple,
+    recordCount: 0,
+    indexable: true,
+    noindex: false,
+    decision: { recordGate: true, indexable: true, noindex: false },
+  };
+  return liveChildrenOf(parentEntry, matrix).filter(
+    (sibling) =>
+      pathKey(sibling.depth, sibling.tuple, matrix.axisOrder) !==
+      pathKey(entry.depth, entry.tuple, matrix.axisOrder),
+  );
+}

package/src/surface/evidence-records.ts

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0280/RFC-0281 contracts for evidence-backed Programmatic Surface inputs:
+  aggregate search-demand signals and consented Werk records.
+</purpose>
+<non-goals>
+  <item>Do not read files or call external demand APIs.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0280/RFC-0281: first-class demand and Werk evidence contracts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const demandIntentSchema = z.enum([
+  "informational",
+  "commercial",
+  "transactional",
+  "navigational",
+]);
+
+export const demandSignalSourceSchema = z.enum(["gsc", "keyword-planner", "manual", "derived"]);
+
+export const demandAxesSchema = z
+  .object({
+    industry: z.string().min(1).optional(),
+    country: z.string().min(1).optional(),
+    region: z.string().min(1).optional(),
+    city: z.string().min(1).optional(),
+    demand: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const demandSignalSchema = z
+  .object({
+    id: z.string().min(1),
+    query: z.string().min(1),
+    intent: demandIntentSchema,
+    axes: demandAxesSchema,
+    volume: z.number().min(0).optional(),
+    competition: z.number().min(0).max(1).optional(),
+    source: demandSignalSourceSchema,
+    observedAt: z.string().datetime({ offset: true }),
+    provenance: z.object({
+      importId: z.string().min(1),
+      sourceRef: z.string().min(1).optional(),
+    }),
+  })
+  .strict();
+
+export type DemandIntent = z.infer<typeof demandIntentSchema>;
+export type DemandSignalSource = z.infer<typeof demandSignalSourceSchema>;
+export type DemandAxes = z.infer<typeof demandAxesSchema>;
+export type DemandSignal = z.infer<typeof demandSignalSchema>;
+
+export const werkRecordSchema = z
+  .object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    axes: z
+      .object({
+        industry: z.array(z.string().min(1)).min(1),
+        country: z.string().min(1).optional(),
+        region: z.string().min(1).optional(),
+        city: z.string().min(1),
+        demand: z.array(z.string().min(1)).optional(),
+      })
+      .strict(),
+    facts: z
+      .object({
+        materials: z.array(z.string().min(1)).optional(),
+        scope: z.string().min(1).optional(),
+        problem: z.string().min(1).optional(),
+        outcome: z.string().min(1).optional(),
+        completedAt: z.string().datetime({ offset: true }).optional(),
+        durationDays: z.number().int().min(0).optional(),
+      })
+      .strict(),
+    media: z.array(z.object({ ref: z.string().min(1), creditRef: z.string().min(1) })).optional(),
+    provenance: z.object({
+      sourceRef: z.string().min(1),
+      anchoredHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    }),
+    consent: z
+      .object({
+        publishable: z.boolean(),
+        clientApproved: z.boolean(),
+        redactions: z.array(z.string().min(1)).optional(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export type WerkRecord = z.infer<typeof werkRecordSchema>;

package/src/surface/fleet.ts

@@ -0,0 +1,60 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/surface/src/fleet.ts as an authored surface authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not replace per-site Bordbuch, autonomy, breaker, or approval state.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0284: initial implementation of fleet Leitstand contracts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const fleetBreakerStateSchema = z.enum(["armed", "tripped", "frozen"]);
+
+export const fleetSiteStatusSchema = z.object({
+  site: z.string().min(1),
+  path: z.string().min(1),
+  bordbuchHash: z.string().min(1).nullable(),
+  autonomy: z.record(z.string(), z.string()),
+  openEscalations: z.number().int().nonnegative(),
+  breaker: fleetBreakerStateSchema,
+  dirtyFlags: z.array(z.string().min(1)),
+  lastOutcomeWindow: z.string().datetime().optional(),
+  humanMinutesPer1000Pages: z.number().min(0).optional(),
+});
+
+export const fleetJobKindSchema = z.enum(["generate", "enrich", "translate", "review", "rollback"]);
+
+export const fleetJobSchema = z.object({
+  site: z.string().min(1),
+  kind: fleetJobKindSchema,
+  scope: z.string().min(1).optional(),
+  priority: z.number(),
+  safety: z.boolean().default(false),
+  estimatedCost: z.object({
+    llmTokens: z.number().int().nonnegative().optional(),
+    reviewMinutes: z.number().nonnegative().optional(),
+    ciSeconds: z.number().nonnegative().optional(),
+  }),
+});
+
+export const fleetPlanSchema = z.object({
+  collectedAt: z.string().datetime().nullable(),
+  budgets: z.object({
+    llmTokens: z.number().int().nonnegative(),
+    reviewMinutes: z.number().nonnegative(),
+    ciSeconds: z.number().nonnegative(),
+  }),
+  jobs: z.array(fleetJobSchema),
+  blocked: z.array(z.object({ site: z.string().min(1), reason: z.string().min(1) })),
+  humanMinutesPer1000Pages: z.number().min(0),
+});
+
+export type FleetBreakerState = z.infer<typeof fleetBreakerStateSchema>;
+export type FleetSiteStatus = z.infer<typeof fleetSiteStatusSchema>;
+export type FleetJobKind = z.infer<typeof fleetJobKindSchema>;
+export type FleetJob = z.infer<typeof fleetJobSchema>;
+export type FleetPlan = z.infer<typeof fleetPlanSchema>;