@zaip-ai/cli 1.0.6 → 1.0.7

package/templates/.agents/dashboard/modules/operations/src/server/build-operations-projection.ts

@@ -0,0 +1,787 @@
+import type { WorkspaceFileSystem, WorkspaceLayout } from "@zaip-ai/core";
+import { DecisionV2Repository } from "@zaip-ai/decisions";
+import { type LifecycleManifestEntity, LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
+import {
+  type ChangeV2,
+  ChangeV2Repository,
+  type DeliverySpecV2,
+  DeliverySpecV2Repository,
+  type ExecutionV2,
+  ExecutionV2Repository,
+  type PrdV2,
+  PrdV2Repository,
+} from "@zaip-ai/specs";
+import { type TaskV2, TaskV2Repository } from "@zaip-ai/tasks";
+import {
+  globalLegacyEffortDurationMs,
+  type OperationsProjection,
+  type ProjectionTimeFilter,
+  type RunProjection,
+  saoPauloPeriodKey,
+} from "../contracts.js";
+import { rootExecutionDurationRuns } from "../duration-population.js";
+import { taskIdsWithStartedExecution } from "../work-readiness.js";
+import { manifestQualityProjection, taskTelemetry } from "./build-operations-projection-helpers.js";
+import { effectiveOperationsDurationMs, projectCanonicalRun } from "./canonical-run-projection.js";
+import { executionRelationshipCounts } from "./execution-relationship-counts.js";
+import { normalizeFilter } from "./filter.js";
+import { plannedTaskPreviews, taskExecutionIds } from "./planned-task-previews.js";
+import { recentRunsFirst } from "./run-order.js";
+import { readScopedRuns } from "./runs.js";
+import { countTaskTestArtifacts } from "./task-test-counts.js";
+import {
+  decisionCounts,
+  executionWorkStatus,
+  latestTimestamp,
+  macroWorkStatus,
+  reconciliation,
+  taskProgress,
+} from "./usage.js";
+
+export {
+  createDescendantQueries,
+  latestObservedSourceTiming,
+  observedSourceTiming,
+} from "./canonical-compat.js";
+
+export function overviewMetricTotals(
+  runs: readonly {
+    id: string;
+    started_at: string;
+    source_duration_ms?: number | null;
+    duration_ms: number | null;
+    duration_provenance?: RunProjection["duration_provenance"];
+    usage: { total: { tokens: { total: number | null }; cost: { brl: number | null } } };
+  }[],
+  includeLegacyEffort: boolean,
+) {
+  const unique = [...new Map(runs.map((run) => [run.id, run] as const)).values()];
+  const durationOf = (run: (typeof unique)[number]) => {
+    const source = run.source_duration_ms;
+    if (source !== null && source !== undefined && source > 0) return source;
+    return run.duration_provenance === "reconciled" || run.duration_provenance === "legacy_inferred"
+      ? run.duration_ms !== null && run.duration_ms > 0
+        ? run.duration_ms
+        : null
+      : null;
+  };
+  const observedDurations = unique
+    .map(durationOf)
+    .filter((value): value is number => value !== null);
+  const numeric = (values: readonly (number | null)[]) => {
+    const known = values.filter((value): value is number => value !== null);
+    return known.length === 0 ? null : known.reduce((sum, value) => sum + value, 0);
+  };
+  const executionRoots = rootExecutionDurationRuns(unique);
+  return {
+    duration_ms: includeLegacyEffort
+      ? globalLegacyEffortDurationMs(unique, durationOf)
+      : observedDurations.length === 0
+        ? null
+        : observedDurations.reduce((sum, value) => sum + value, 0),
+    execution_day_count: new Set(
+      executionRoots
+        .map((run) => saoPauloPeriodKey(run.started_at, "day"))
+        .filter((value): value is string => value !== null),
+    ).size,
+    tokens: numeric(unique.map((run) => run.usage.total.tokens.total)),
+    cost_brl: numeric(unique.map((run) => run.usage.total.cost.brl)),
+  };
+}
+
+export async function buildOperationsProjection(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  filter: Partial<ProjectionTimeFilter> = {},
+  options: { overviewOnly?: boolean; skipTestArtifacts?: boolean } = {},
+): Promise<OperationsProjection> {
+  if (layout.version === 1)
+    throw new Error("Operations projection requires a modern WorkspaceLayout");
+  const normalizedFilter = normalizeFilter(filter);
+  const manifest = new LifecycleManifestStore(filesystem);
+  const prdsRepository = new PrdV2Repository(filesystem, layout);
+  const specsRepository = new DeliverySpecV2Repository(filesystem, layout);
+  const changesRepository = new ChangeV2Repository(filesystem, layout);
+  const executionsRepository = new ExecutionV2Repository(filesystem, layout);
+  const tasksRepository = new TaskV2Repository(filesystem, layout);
+  const decisionsRepository = new DecisionV2Repository(filesystem, layout);
+  const [entities, scopedRuns] = await Promise.all([
+    manifest.readEntities(),
+    readScopedRuns(filesystem, layout, normalizedFilter),
+  ]);
+  if (
+    entities.length === 0 &&
+    (await manifest.readSummary()) === null &&
+    !(await filesystem.exists(".agents/records/lifecycle/.gitkeep"))
+  ) {
+    throw new Error(
+      "Lifecycle manifest is not initialized; run `zaip manifest rebuild --confirm-full-scan`",
+    );
+  }
+  const allPrds = manifestData<PrdV2>(entities, "prd");
+  const allSpecs = manifestData<DeliverySpecV2>(entities, "spec");
+  const allChanges = manifestData<ChangeV2>(entities, "change");
+  const allExecutions = manifestData<ExecutionV2>(entities, "execution");
+  const allTasks = manifestData<TaskV2>(entities, "task");
+  const allDecisions = manifestDecisions(entities);
+  // Run manifests remain the canonical source for lifecycle entities. Run
+  // records retain independently observed source intervals (including
+  // Sub-Runs), which Operations uses for duration totals.
+  const allRuns = scopedRuns.map(projectCanonicalRun);
+  const prds = allPrds.filter((row) => lifecycleRowInWindow(row, normalizedFilter));
+  const specs = allSpecs.filter((row) => lifecycleRowInWindow(row, normalizedFilter));
+  const changes = allChanges.filter((row) => lifecycleRowInWindow(row, normalizedFilter));
+  const executions = allExecutions.filter((row) => lifecycleRowInWindow(row, normalizedFilter));
+  const tasks = allTasks.filter((row) => lifecycleRowInWindow(row, normalizedFilter));
+  const decisions = allDecisions.filter((row) =>
+    timestampInWindow(row.created_at, normalizedFilter),
+  );
+  const filteredRuns = allRuns.filter((row) =>
+    timestampInWindow(row.finished_at ?? row.started_at, normalizedFilter),
+  );
+  // Analytics need a numeric duration for every execution activity day, but
+  // lifecycle start/end timestamps are never an estimation source.
+  const runs = projectExecutionDurations(filteredRuns);
+
+  const changesById = new Map(allChanges.map((change) => [change.id, change] as const));
+  const tasksById = new Map(allTasks.map((task) => [task.id, task] as const));
+  const executionsById = new Map(
+    allExecutions.map((execution) => [execution.id, execution] as const),
+  );
+  const descendants = createManifestDescendantQueries({
+    changes: allChanges,
+    tasks: allTasks,
+    executions: allExecutions,
+    prds: allPrds,
+    specs: allSpecs,
+    runs,
+  });
+  const taskTestCounts =
+    options.overviewOnly || options.skipTestArtifacts
+      ? new Map<string, number>()
+      : await countTaskTestArtifacts(filesystem, tasks, (changeId) =>
+          changesRepository.path(changeId),
+        );
+  const startedExecutionTaskIds = taskIdsWithStartedExecution(allExecutions);
+  const executionIdsByTask = taskExecutionIds(allExecutions);
+  const telemetryByTask = taskTelemetry(runs);
+  const plannedTasks = plannedTaskPreviews(allPrds, allSpecs);
+
+  const prdRows = prds.map((prd) => {
+    const related = descendants.forPrd(prd.id);
+    return manifestMacroProjection({
+      id: prd.id,
+      title: prd.title,
+      createdAt: prd.created_at,
+      updatedAt: prd.updated_at,
+      kind: "prd",
+      parentId: null,
+      artifactPath: prdsRepository.path(prd.id),
+      lifecycleStatus: prd.status,
+      ...related,
+      decisions: allDecisions,
+      executions: executionsById,
+      tasks: tasksById,
+      plannedTasks: plannedTasks.byPrd.get(prd.id) ?? [],
+    });
+  });
+  const specRows = specs.map((spec) => {
+    const related = descendants.forSpec(spec.id);
+    return manifestMacroProjection({
+      id: spec.id,
+      title: spec.title,
+      createdAt: spec.created_at,
+      updatedAt: spec.updated_at,
+      kind: "spec",
+      parentId: spec.prd_id,
+      artifactPath: specsRepository.path(spec.id),
+      lifecycleStatus: spec.status,
+      ...related,
+      decisions: allDecisions,
+      executions: executionsById,
+      tasks: tasksById,
+      plannedTasks: plannedTasks.bySpec.get(spec.id) ?? [],
+    });
+  });
+  const taskRows = tasks.map((task) => {
+    const change = changesById.get(task.change_id);
+    return {
+      ...task,
+      attempt_count: task.attempt_count ?? null,
+      artifact_path: tasksRepository.path(task.id),
+      progress: taskProgress(task.status),
+      test_count: taskTestCounts.get(task.id) ?? 0,
+      spec_id:
+        change?.source.type === "spec"
+          ? change.source.spec_id
+          : change?.source.type === "prd"
+            ? change.source.spec_id
+            : null,
+      execution_started: startedExecutionTaskIds.has(task.id),
+      execution_ids: executionIdsByTask.get(task.id) ?? [],
+      execution_count: executionIdsByTask.get(task.id)?.length ?? 0,
+      telemetry: telemetryByTask.get(task.id) ?? null,
+    };
+  });
+  const allUsage = manifestUsageProjection(runs);
+  const executionRuns = rootExecutionDurationRuns(runs);
+  const overviewMetrics = overviewMetricTotals(
+    runs,
+    normalizedFilter.from === null && normalizedFilter.to === null,
+  );
+  const origins = {
+    conversation: manifestUsageProjection(runs.filter((run) => run.entrypoint === "conversation")),
+    task: manifestUsageProjection(runs.filter((run) => run.entrypoint === "task")),
+    spec: manifestUsageProjection(runs.filter((run) => run.entrypoint === "spec")),
+    prd: manifestUsageProjection(runs.filter((run) => run.entrypoint === "prd")),
+  };
+
+  return {
+    schema_version: 2,
+    layout_version: layout.version,
+    readonly: true,
+    source: ".agents/records",
+    filters: normalizedFilter,
+    summary: {
+      prd_count: prdRows.length,
+      spec_count: specRows.length,
+      execution_count: executions.length,
+      task_count: tasks.length,
+      run_count: runs.length,
+      execution_duration_ms: executionRuns.reduce((sum, run) => sum + (run.duration_ms ?? 0), 0),
+      execution_day_count: new Set(executionRuns.map((run) => run.started_at.slice(0, 10))).size,
+      ...(options.overviewOnly
+        ? {
+            overview_metrics: {
+              ...overviewMetrics,
+            },
+          }
+        : {}),
+      decisions: decisionCounts(decisions),
+      source_latest_at: latestTimestamp([
+        ...prds.map((prd) => prd.updated_at),
+        ...specs.map((spec) => spec.updated_at),
+        ...changes.map((change) => change.updated_at),
+        ...executions.map((execution) => execution.updated_at),
+        ...tasks.map((task) => task.updated_at),
+        ...decisions.map((decision) => decision.created_at),
+        ...runs.map((run) => run.finished_at ?? run.started_at),
+      ]),
+      quality: manifestQualityProjection(tasks, runs),
+      reconciliation: reconciliation(allUsage, origins),
+      usage: allUsage,
+    },
+    origins,
+    prds: prdRows,
+    specs: specRows,
+    tasks: taskRows,
+    changes: options.overviewOnly
+      ? []
+      : changes.map((change) => ({
+          ...change,
+          artifact_path: changesRepository.path(change.id),
+        })),
+    executions: options.overviewOnly
+      ? []
+      : executions.map((execution) => ({
+          ...execution,
+          kind: execution.kind ?? "delivery",
+          client_turn_id: execution.client_turn_id ?? null,
+          ...executionRelationshipCounts(execution, {
+            runs: runs.map((run) => ({
+              agent: run.agent,
+              call_count: run.call_count,
+              duration_ms: run.duration_ms,
+              execution_id: run.execution_id,
+              finished_at: run.finished_at,
+              parent_run_id: run.parent_run_id,
+              run_purpose: run.run_purpose,
+              source_duration_ms: run.source_duration_ms ?? null,
+              started_at: run.started_at,
+              status: run.status,
+              task_id: run.task_id,
+            })),
+            tasks,
+            changes,
+            specs,
+          }),
+          artifact_path: executionsRepository.path(execution.id),
+          work_status: executionWorkStatus(execution.status),
+        })),
+    runs: options.overviewOnly ? [] : recentRunsFirst(runs),
+    decisions: options.overviewOnly
+      ? []
+      : decisions.map((decision) => ({
+          id: decision.id,
+          title: decision.title,
+          origin: decision.origin,
+          scope_type: decision.scope_type,
+          scope_id: decision.scope_id,
+          artifact_path: decisionsRepository.path(
+            decision.scope_type,
+            decision.scope_id,
+            decision.id,
+          ),
+          created_at: decision.created_at,
+        })),
+  };
+}
+
+const TERMINAL_LIFECYCLE_STATUSES = new Set([
+  "completed",
+  "delivered",
+  "failed",
+  "cancelled",
+  "superseded",
+  "rolled_back",
+]);
+
+function manifestData<T>(
+  entities: readonly LifecycleManifestEntity[],
+  kind: LifecycleManifestEntity["kind"],
+): T[] {
+  return entities.flatMap((entity) =>
+    entity.kind === kind && entity.data !== null
+      ? [
+          {
+            ...entity.data,
+            id: entity.id,
+            title: entity.title ?? entity.data.title,
+            status: entity.status ?? entity.data.status,
+            risk: entity.risk ?? entity.data.risk,
+            priority: entity.priority ?? entity.data.priority,
+            updated_at: entity.updated_at,
+          } as T,
+        ]
+      : [],
+  );
+}
+
+interface ManifestDecision {
+  id: string;
+  title: string;
+  origin: "human" | "agent";
+  scope_type: "change" | "execution";
+  scope_id: string;
+  created_at: string;
+}
+
+function manifestDecisions(entities: readonly LifecycleManifestEntity[]): ManifestDecision[] {
+  return entities.flatMap((entity) => {
+    if (entity.kind !== "decision" || entity.data === null) return [];
+    const data = entity.data;
+    if (
+      (data.origin !== "human" && data.origin !== "agent") ||
+      (data.scope_type !== "change" && data.scope_type !== "execution") ||
+      typeof data.scope_id !== "string" ||
+      typeof data.created_at !== "string"
+    ) {
+      return [];
+    }
+    return [
+      {
+        id: entity.id,
+        title: entity.title ?? entity.id,
+        origin: data.origin,
+        scope_type: data.scope_type,
+        scope_id: data.scope_id,
+        created_at: data.created_at,
+      },
+    ];
+  });
+}
+
+function lifecycleRowInWindow(
+  row: { status: string; updated_at: string; finished_at?: string | null },
+  filter: ProjectionTimeFilter,
+): boolean {
+  if (!TERMINAL_LIFECYCLE_STATUSES.has(row.status)) return true;
+  return timestampInWindow(row.finished_at ?? row.updated_at, filter);
+}
+
+function timestampInWindow(timestamp: string, filter: ProjectionTimeFilter): boolean {
+  const normalized = new Date(timestamp).toISOString();
+  return (
+    (filter.from === null || normalized >= filter.from) &&
+    (filter.to === null || normalized <= filter.to)
+  );
+}
+
+function _projectManifestRun(
+  entity: LifecycleManifestEntity,
+  layout: WorkspaceLayout,
+): OperationsProjection["runs"][number] {
+  const data = entity.data ?? {};
+  const startedAt = stringValue(data.started_at) ?? entity.updated_at;
+  const finishedAt = stringValue(data.finished_at);
+  const sourceDurationMs = numberValue(data.source_duration_ms);
+  const lifecycleDurationMs =
+    finishedAt === null ? null : Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt));
+  const runUsage = usageFromManifestData(data.entrypoint_usage, stringValue(data.work_type));
+  return {
+    id: entity.id,
+    artifact_path: layout.activePath("run", entity.id),
+    status: runStatus(entity.status),
+    phase: stringValue(data.phase) ?? "execution",
+    entrypoint: entrypointValue(data.entrypoint),
+    work_type: data.work_type === "rework" ? "rework" : "new",
+    run_role: runRoleValue(data.run_role),
+    run_kind: data.run_kind === "subrun" ? "subrun" : "run",
+    run_purpose: runPurposeValue(data.run_purpose),
+    requires_finalizer: data.requires_finalizer === true,
+    parent_run_id: stringValue(data.parent_run_id),
+    client: stringValue(data.client) ?? "unknown",
+    agent: stringValue(data.agent) ?? "unknown",
+    agent_name: stringValue(data.agent_name) ?? stringValue(data.agent) ?? "unknown",
+    provider: stringValue(data.provider),
+    model: stringValue(data.model) ?? "unknown",
+    reasoning_effort: stringValue(data.reasoning_effort),
+    effective_model: stringValue(data.effective_model),
+    effective_reasoning_effort: stringValue(data.effective_reasoning_effort),
+    effective_config_mixed: data.effective_config_mixed === true,
+    service_tier: stringValue(data.service_tier),
+    call_count: numberValue(data.call_count),
+    terminal_call_count: numberValue(data.terminal_call_count),
+    failed_call_count: numberValue(data.failed_call_count),
+    cancelled_call_count: numberValue(data.cancelled_call_count),
+    conversation_id: stringValue(data.conversation_id) ?? "unknown",
+    client_thread_id: stringValue(data.client_thread_id),
+    client_turn_id: stringValue(data.client_turn_id),
+    execution_id: stringValue(data.execution_id),
+    task_id: stringValue(data.task_id),
+    spec_id: stringValue(data.spec_id),
+    prd_id: stringValue(data.prd_id),
+    change_id: stringValue(data.change_id),
+    started_at: startedAt,
+    finished_at: finishedAt,
+    duration_ms: effectiveOperationsDurationMs(sourceDurationMs, lifecycleDurationMs),
+    source_started_at: stringValue(data.source_started_at),
+    source_finished_at: stringValue(data.source_finished_at),
+    source_duration_ms: sourceDurationMs,
+    capture_lag_ms: numberValue(data.capture_lag_ms),
+    pricing_segments: Array.isArray(data.pricing_segments)
+      ? (data.pricing_segments as NonNullable<
+          OperationsProjection["runs"][number]["pricing_segments"]
+        >)
+      : [],
+    usage: runUsage,
+  };
+}
+
+export { effectiveOperationsDurationMs } from "./canonical-run-projection.js";
+
+export function projectExecutionDurations<T extends RunProjection>(runs: readonly T[]): T[] {
+  return runs.map((run) => {
+    if (typeof run.source_duration_ms === "number" && run.source_duration_ms > 0) {
+      return {
+        ...run,
+        duration_ms: run.source_duration_ms,
+        duration_provenance: "observed",
+        estimation_basis: null,
+      };
+    }
+    if (
+      typeof run.duration_ms === "number" &&
+      run.duration_ms > 0 &&
+      (run.duration_provenance === "reconciled" || run.duration_provenance === "legacy_inferred")
+    ) {
+      return { ...run, estimation_basis: null };
+    }
+    return {
+      ...run,
+      duration_ms: null,
+      duration_provenance: "unavailable",
+      estimation_basis: null,
+    };
+  });
+}
+
+function usageFromManifestData(value: unknown, workType: string | null) {
+  const source = recordValue(value);
+  const conversation = metricFromManifestBucket(source?.conversation);
+  const planning = metricFromManifestBucket(source?.planning);
+  const execution = metricFromManifestBucket(source?.execution);
+  const total = metricFromManifestBucket(source?.total);
+  return {
+    conversation,
+    planning,
+    execution,
+    total,
+    new_work: workType === "rework" ? emptyUsageMetric() : total,
+    rework: workType === "rework" ? total : emptyUsageMetric(),
+  };
+}
+
+function metricFromManifestBucket(value: unknown) {
+  const bucket = recordValue(value);
+  const tokens = recordValue(bucket?.tokens);
+  const cost = recordValue(bucket?.cost);
+  const coverage = recordValue(bucket?.coverage);
+  return {
+    events: numberValue(bucket?.usage_event_count) ?? 0,
+    tokens: {
+      input: numberValue(tokens?.input),
+      cached_input: numberValue(tokens?.cached_input),
+      output: numberValue(tokens?.output),
+      reasoning: numberValue(tokens?.reasoning),
+      total: numberValue(tokens?.total),
+    },
+    cost: {
+      usd: numberValue(cost?.usd),
+      brl: numberValue(cost?.brl),
+    },
+    coverage: {
+      events: numberValue(coverage?.events) ?? 0,
+      tokens: numberValue(coverage?.tokens) ?? 0,
+      usd: numberValue(coverage?.usd) ?? 0,
+      brl: numberValue(coverage?.brl) ?? 0,
+    },
+  };
+}
+
+function emptyUsageMetric(): OperationsProjection["summary"]["usage"]["total"] {
+  return {
+    events: 0,
+    tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null },
+    cost: { usd: null, brl: null },
+    coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+  };
+}
+
+function manifestUsageProjection(
+  runs: readonly OperationsProjection["runs"][number][],
+): OperationsProjection["summary"]["usage"] {
+  const sumMetric = (
+    selector: (
+      run: OperationsProjection["runs"][number],
+    ) => OperationsProjection["summary"]["usage"]["total"],
+  ) => {
+    const metrics = runs.map(selector);
+    const sumNullable = (values: readonly (number | null)[]) => {
+      const known = values.filter((value): value is number => value !== null);
+      return known.length === 0 ? null : known.reduce((sum, value) => sum + value, 0);
+    };
+    return {
+      events: metrics.reduce((sum, metric) => sum + metric.events, 0),
+      tokens: {
+        input: sumNullable(metrics.map((metric) => metric.tokens.input)),
+        cached_input: sumNullable(metrics.map((metric) => metric.tokens.cached_input)),
+        output: sumNullable(metrics.map((metric) => metric.tokens.output)),
+        reasoning: sumNullable(metrics.map((metric) => metric.tokens.reasoning)),
+        total: sumNullable(metrics.map((metric) => metric.tokens.total)),
+      },
+      cost: {
+        usd: sumNullable(metrics.map((metric) => metric.cost.usd)),
+        brl: sumNullable(metrics.map((metric) => metric.cost.brl)),
+      },
+      coverage: {
+        events: metrics.reduce((sum, metric) => sum + metric.coverage.events, 0),
+        tokens: metrics.reduce((sum, metric) => sum + metric.coverage.tokens, 0),
+        usd: metrics.reduce((sum, metric) => sum + metric.coverage.usd, 0),
+        brl: metrics.reduce((sum, metric) => sum + metric.coverage.brl, 0),
+      },
+    };
+  };
+  return {
+    conversation: sumMetric((run) => run.usage.conversation),
+    planning: sumMetric((run) => run.usage.planning),
+    execution: sumMetric((run) => run.usage.execution),
+    total: sumMetric((run) => run.usage.total),
+    new_work: sumMetric((run) => run.usage.new_work),
+    rework: sumMetric((run) => run.usage.rework),
+  };
+}
+
+export function recalculateOperationsRunSummary(
+  operations: OperationsProjection,
+): OperationsProjection {
+  const runs = projectExecutionDurations(operations.runs);
+  const executionRuns = rootExecutionDurationRuns(runs);
+  const allUsage = manifestUsageProjection(runs);
+  const origins = {
+    conversation: manifestUsageProjection(runs.filter((run) => run.entrypoint === "conversation")),
+    task: manifestUsageProjection(runs.filter((run) => run.entrypoint === "task")),
+    spec: manifestUsageProjection(runs.filter((run) => run.entrypoint === "spec")),
+    prd: manifestUsageProjection(runs.filter((run) => run.entrypoint === "prd")),
+  };
+  return {
+    ...operations,
+    runs,
+    origins,
+    summary: {
+      ...operations.summary,
+      run_count: runs.length,
+      execution_duration_ms: executionRuns.reduce((sum, run) => sum + (run.duration_ms ?? 0), 0),
+      execution_day_count: new Set(executionRuns.map((run) => run.started_at.slice(0, 10))).size,
+      source_latest_at: latestTimestamp([
+        operations.summary.source_latest_at,
+        ...runs.map((run) => run.finished_at ?? run.started_at),
+      ]),
+      quality: manifestQualityProjection(operations.tasks, runs),
+      reconciliation: reconciliation(allUsage, origins),
+      usage: allUsage,
+    },
+  };
+}
+
+function manifestMacroProjection(input: {
+  id: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  kind: "prd" | "spec";
+  parentId: string | null;
+  artifactPath: string;
+  lifecycleStatus: string;
+  changeIds: ReadonlySet<string>;
+  executionIds: ReadonlySet<string>;
+  taskIds: ReadonlySet<string>;
+  runs: readonly OperationsProjection["runs"][number][];
+  decisions: readonly ManifestDecision[];
+  executions: ReadonlyMap<string, ExecutionV2>;
+  tasks: ReadonlyMap<string, TaskV2>;
+  plannedTasks: OperationsProjection["prds"][number]["planned_tasks"];
+}): OperationsProjection["prds"][number] {
+  const scopedTasks = [...input.taskIds].flatMap((id) => {
+    const task = input.tasks.get(id);
+    return task === undefined ? [] : [task];
+  });
+  const relevantDecisions = input.decisions.filter(
+    (decision) =>
+      (decision.scope_type === "change" && input.changeIds.has(decision.scope_id)) ||
+      (decision.scope_type === "execution" && input.executionIds.has(decision.scope_id)),
+  );
+  const rootDurations = input.runs.flatMap((run) =>
+    run.parent_run_id === null && run.duration_ms !== null ? [run.duration_ms] : [],
+  );
+  return {
+    id: input.id,
+    title: input.title,
+    created_at: input.createdAt,
+    updated_at: input.updatedAt,
+    kind: input.kind,
+    parent_id: input.parentId,
+    artifact_path: input.artifactPath,
+    lifecycle_status: input.lifecycleStatus,
+    work_status: macroWorkStatus(
+      input.lifecycleStatus,
+      [...input.executionIds].map((id) => input.executions.get(id)),
+    ),
+    execution_ids: [...input.executionIds].sort(),
+    task_ids: [...input.taskIds].sort(),
+    planned_tasks: [...input.plannedTasks],
+    run_ids: input.runs.map((run) => run.id).sort(),
+    execution_count: input.executionIds.size,
+    task_count: Math.max(input.taskIds.size, input.plannedTasks.length),
+    run_count: input.runs.length,
+    duration_ms:
+      rootDurations.length === 0
+        ? null
+        : rootDurations.reduce((sum, duration) => sum + duration, 0),
+    decisions: decisionCounts(relevantDecisions),
+    rework_run_count: input.runs.filter((run) => run.work_type === "rework").length,
+    quality: manifestQualityProjection(scopedTasks, input.runs),
+    usage: manifestUsageProjection(input.runs),
+  };
+}
+
+function createManifestDescendantQueries(input: {
+  changes: readonly ChangeV2[];
+  tasks: readonly TaskV2[];
+  executions: readonly ExecutionV2[];
+  prds: readonly PrdV2[];
+  specs: readonly DeliverySpecV2[];
+  runs: readonly OperationsProjection["runs"][number][];
+}) {
+  function collect(specIds: ReadonlySet<string>, prdId: string | null) {
+    const creationRunIds = new Set(
+      [
+        ...(prdId === null
+          ? []
+          : input.prds.filter((prd) => prd.id === prdId).map((prd) => prd.creation_run_id)),
+        ...input.specs.filter((spec) => specIds.has(spec.id)).map((spec) => spec.creation_run_id),
+      ].filter((id): id is string => id !== null && id !== undefined),
+    );
+    const changeIds = new Set(
+      input.changes
+        .filter(
+          (change) =>
+            (prdId !== null && change.source.type === "prd" && change.source.prd_id === prdId) ||
+            ((change.source.type === "spec" || change.source.type === "prd") &&
+              change.source.spec_id !== null &&
+              change.source.spec_id !== undefined &&
+              specIds.has(change.source.spec_id)),
+        )
+        .map((change) => change.id),
+    );
+    const taskIds = new Set(
+      input.tasks.filter((task) => changeIds.has(task.change_id)).map((task) => task.id),
+    );
+    const executionIds = new Set(
+      input.executions
+        .filter(
+          (execution) =>
+            (prdId !== null &&
+              execution.origin.type === "prd" &&
+              execution.origin.prd_id === prdId) ||
+            (execution.origin.type === "spec" && specIds.has(execution.origin.spec_id)) ||
+            execution.dag.nodes.some((node) => taskIds.has(node.task_id)),
+        )
+        .map((execution) => execution.id),
+    );
+    const runs = input.runs.filter(
+      (run) =>
+        (run.spec_id !== null && specIds.has(run.spec_id)) ||
+        (run.task_id !== null && taskIds.has(run.task_id)) ||
+        creationRunIds.has(run.id) ||
+        (prdId !== null &&
+          (run.prd_id === prdId ||
+            (run.execution_id !== null && executionIds.has(run.execution_id)))),
+    );
+    return { changeIds, taskIds, executionIds, runs };
+  }
+  return {
+    forSpec: (specId: string) => collect(new Set([specId]), null),
+    forPrd: (prdId: string) =>
+      collect(
+        new Set(input.specs.filter((spec) => spec.prd_id === prdId).map((spec) => spec.id)),
+        prdId,
+      ),
+  };
+}
+
+function recordValue(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function runStatus(value: string | null): OperationsProjection["runs"][number]["status"] {
+  return value === "completed" || value === "failed" || value === "cancelled" ? value : "running";
+}
+
+function entrypointValue(value: unknown): OperationsProjection["runs"][number]["entrypoint"] {
+  return value === "conversation" || value === "spec" || value === "prd" ? value : "task";
+}
+
+function runRoleValue(value: unknown): OperationsProjection["runs"][number]["run_role"] {
+  return value === "intake" || value === "subagent" ? value : "orchestrator";
+}
+
+function runPurposeValue(value: unknown): OperationsProjection["runs"][number]["run_purpose"] {
+  return value === "intake" ||
+    value === "execution" ||
+    value === "review" ||
+    value === "audit" ||
+    value === "finalization"
+    ? value
+    : "orchestration";
+}