harnery 0.32.0 → 0.34.0

package/src/core/events/v3/coordination-view.ts

@@ -0,0 +1,193 @@
+import type { EventV3, RuntimeAttestationV3 } from "./contract.ts";
+import {
+  EVENT_V3_SAFETY_REDUCER_BUILD,
+  type GenerationSafetyStateV3,
+  reduceSafetyProjectionV3,
+  type SafetyProjectionDiagnosticV3,
+  type SafetyProjectionV3,
+  type WaitProjectionV3,
+} from "./projection.ts";
+import { type ReadLedgerV3Result, readLedgerV3 } from "./reader.ts";
+
+export const EVENT_V3_COORDINATION_VIEW_VERSION = 1 as const;
+
+export interface CoordinationGenerationViewV3 {
+  contract_major: 2;
+  instance_id: string;
+  session_id: string;
+  generation_id: string;
+  root_id: string;
+  run_id?: string;
+  workflow_id?: string;
+  workflow_agent_id?: string;
+  identity_id?: string;
+  runtime_attestation: RuntimeAttestationV3;
+  parent_generation_id?: string;
+  delegation_id?: string;
+  delegation_role?: string;
+  phase: "live" | "terminal";
+  activity: "working" | "needs_input" | "idle" | "terminal";
+  task_state?: string;
+  task_state_updated_at?: string;
+  lifecycle_state?: string;
+  lifecycle_state_updated_at?: string;
+  presence_state?: string;
+  presence_state_updated_at?: string;
+  started_at: string;
+  last_observed_at: string;
+  last_event_id: string;
+  source_position: { segment_ordinal: number; byte_offset: number };
+  waits: WaitProjectionV3[];
+  files_touched: string[];
+  progress_count: number;
+  last_context_event_id?: string;
+  provisional_termination?: GenerationSafetyStateV3["provisional_termination"];
+  terminal?: GenerationSafetyStateV3["terminal"];
+  evidence_complete: boolean;
+  authority_eligible: boolean;
+}
+
+export interface CoordinationViewV3 {
+  projection_version: typeof EVENT_V3_COORDINATION_VIEW_VERSION;
+  contract_major: 2;
+  reducer_build_id: typeof EVENT_V3_SAFETY_REDUCER_BUILD;
+  source_complete: boolean;
+  authority_safe: boolean;
+  diagnostics: SafetyProjectionDiagnosticV3[];
+  instances: Record<string, CoordinationGenerationViewV3>;
+  terminal_generations: Record<string, CoordinationGenerationViewV3>;
+  delegations: SafetyProjectionV3["delegations"];
+  decisions: SafetyProjectionV3["decisions"];
+  health: SafetyProjectionV3["health"];
+}
+
+export class CoordinationViewV3Error extends Error {
+  constructor(public readonly diagnostics: SafetyProjectionDiagnosticV3[]) {
+    super("event_v3_coordination_view:authority_unsafe");
+    this.name = "CoordinationViewV3Error";
+  }
+}
+
+/** Read the complete V3 catalog and derive the disposable coordination view. */
+export function readCoordinationViewV3(coordRoot: string): CoordinationViewV3 {
+  return projectCoordinationViewV3(readLedgerV3(coordRoot));
+}
+
+/**
+ * Build the one privacy-safe lifecycle view shared by heartbeat, status,
+ * finalization, web, and Codec adapters. This function performs no writes.
+ */
+export function projectCoordinationViewV3(read: ReadLedgerV3Result): CoordinationViewV3 {
+  const safety = reduceSafetyProjectionV3(read);
+  const starts = new Map<string, Extract<EventV3, { event_type: "session.started" }>>();
+  const eventGeneration = new Map<string, string>();
+  for (const { event } of read.events) {
+    const generationId = "generation_id" in event.scope ? event.scope.generation_id : undefined;
+    if (generationId !== undefined) {
+      eventGeneration.set(event.event_id, generationId);
+    }
+    if (event.event_type === "session.started" && generationId !== undefined) {
+      starts.set(generationId, event as Extract<EventV3, { event_type: "session.started" }>);
+    }
+  }
+
+  const instances: Record<string, CoordinationGenerationViewV3> = {};
+  const terminalGenerations: Record<string, CoordinationGenerationViewV3> = {};
+  const states = Object.values(safety.generations).sort((left, right) =>
+    left.generation_id.localeCompare(right.generation_id),
+  );
+  for (const state of states) {
+    const started = starts.get(state.generation_id);
+    if (!started) continue;
+    const diagnostics = safety.diagnostics.filter(
+      (diagnostic) =>
+        diagnostic.generation_id === state.generation_id ||
+        diagnostic.subject_instance_id === state.instance_id ||
+        (diagnostic.event_id !== undefined &&
+          eventGeneration.get(diagnostic.event_id) === state.generation_id) ||
+        diagnostic.code === "ledger_incomplete",
+    );
+    const delegation = Object.values(safety.delegations).find(
+      (candidate) => candidate.child_generation_id === state.generation_id,
+    );
+    const filesTouched = Object.values(safety.claims)
+      .filter(
+        (claim) =>
+          claim.subject_instance_id === state.instance_id &&
+          claim.access === "write" &&
+          claim.target_kind === "workspace_path" &&
+          claim.target_display !== undefined,
+      )
+      .map((claim) => claim.target_display!)
+      .filter((path, index, all) => all.indexOf(path) === index)
+      .sort();
+    const view: CoordinationGenerationViewV3 = {
+      contract_major: 2,
+      instance_id: state.instance_id,
+      session_id: state.session_id,
+      generation_id: state.generation_id,
+      root_id: started.scope.root_id,
+      run_id: started.scope.run_id,
+      workflow_id: started.scope.workflow_id,
+      workflow_agent_id: started.scope.workflow_agent_id,
+      identity_id: safety.identities[state.instance_id],
+      runtime_attestation: started.payload.runtime_attestation,
+      parent_generation_id: (started.links as { parent_generation_id?: string })
+        .parent_generation_id,
+      delegation_id: delegation?.delegation_id,
+      delegation_role: delegation?.role,
+      phase: state.phase,
+      activity: state.activity,
+      task_state: state.task_state,
+      task_state_updated_at: state.task_state_updated_at,
+      lifecycle_state: state.lifecycle_state,
+      lifecycle_state_updated_at: state.lifecycle_state_updated_at,
+      presence_state: state.presence_state,
+      presence_state_updated_at: state.presence_state_updated_at,
+      started_at: state.started_at,
+      last_observed_at: state.last_observed_at,
+      last_event_id: state.last_event_id,
+      source_position: {
+        segment_ordinal: state.last_segment_ordinal,
+        byte_offset: state.last_byte_offset,
+      },
+      waits: Object.values(state.waits).sort((left, right) =>
+        left.started_event_id.localeCompare(right.started_event_id),
+      ),
+      files_touched: state.phase === "live" ? filesTouched : [],
+      progress_count: state.progress_event_ids.length,
+      last_context_event_id: state.last_context_event_id,
+      provisional_termination: state.provisional_termination,
+      terminal: state.terminal,
+      evidence_complete: safety.evidence_complete && diagnostics.length === 0,
+      authority_eligible: safety.authority_safe && state.phase === "live",
+    };
+    if (state.phase === "terminal") {
+      terminalGenerations[state.generation_id] = view;
+    } else if (safety.current_generation_by_instance[state.instance_id] === state.generation_id) {
+      instances[state.instance_id] = view;
+    }
+  }
+
+  return {
+    projection_version: EVENT_V3_COORDINATION_VIEW_VERSION,
+    contract_major: 2,
+    reducer_build_id: EVENT_V3_SAFETY_REDUCER_BUILD,
+    source_complete: read.complete,
+    authority_safe: safety.authority_safe,
+    diagnostics: safety.diagnostics,
+    instances,
+    terminal_generations: terminalGenerations,
+    delegations: safety.delegations,
+    decisions: safety.decisions,
+    health: safety.health,
+  };
+}
+
+/** Refuse authority decisions while still allowing callers to render diagnostics. */
+export function requireAuthoritySafeCoordinationViewV3(
+  view: CoordinationViewV3,
+): CoordinationViewV3 {
+  if (!view.authority_safe) throw new CoordinationViewV3Error(view.diagnostics);
+  return view;
+}

package/src/core/events/v3/economics.ts

@@ -0,0 +1,384 @@
+import type { LatencyMetricV3 } from "./latency.ts";
+import type { ReadLedgerV3Result } from "./reader.ts";
+
+export const EVENT_V3_ECONOMICS_PROJECTION_VERSION = "event-v3-economics-v1" as const;
+
+export interface TokenTotalsV3 {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+}
+
+export type TokenTotalsMetricV3 =
+  | { state: "observed"; value: TokenTotalsV3 }
+  | { state: "unknown"; known: TokenTotalsV3; reasons: string[] };
+
+export type CostMetricV3 =
+  | { state: "observed"; usd: number; pricing_key: string }
+  | { state: "unknown"; known_usd: number; reasons: string[] };
+
+export interface ModelPricingV3 {
+  input_usd_per_million: number;
+  output_usd_per_million: number;
+  cache_read_usd_per_million?: number;
+  cache_write_usd_per_million?: number;
+}
+
+export interface EconomicsProjectionOptionsV3 {
+  pricing?: Record<string, ModelPricingV3>;
+}
+
+export interface TurnEconomicsV3 {
+  generation_id: string;
+  turn_id: string;
+  terminal_event_id: string;
+  model_key: string | null;
+  usage_method: string | null;
+  tokens: TokenTotalsMetricV3;
+  inference_ms: LatencyMetricV3;
+  harness_ms: LatencyMetricV3;
+  slowest_hook: string | null;
+  slowest_hook_ms: number | null;
+  cost: CostMetricV3;
+}
+
+export interface GenerationEconomicsV3 {
+  generation_id: string;
+  turn_count: number;
+  tokens: TokenTotalsMetricV3;
+  inference_ms: LatencyMetricV3;
+  harness_ms: LatencyMetricV3;
+  cost: CostMetricV3;
+}
+
+export interface EconomicsProjectionV3 {
+  projection_version: typeof EVENT_V3_ECONOMICS_PROJECTION_VERSION;
+  turns: TurnEconomicsV3[];
+  generations: GenerationEconomicsV3[];
+}
+
+export type DelegationRollupDiagnosticCodeV3 = "delegation_cycle" | "generation_economics_missing";
+
+export interface DelegationRollupV3 {
+  root_generation_id: string;
+  generation_ids: string[];
+  tokens: TokenTotalsMetricV3;
+  inference_ms: LatencyMetricV3;
+  harness_ms: LatencyMetricV3;
+  cost: CostMetricV3;
+  diagnostics: Array<{
+    code: DelegationRollupDiagnosticCodeV3;
+    generation_id: string;
+  }>;
+}
+
+interface EventShape {
+  event_id: string;
+  event_type: string;
+  scope: { generation_id?: string; turn_id?: string };
+  payload: Record<string, unknown>;
+}
+
+export function projectEconomicsV3(
+  read: ReadLedgerV3Result,
+  options: EconomicsProjectionOptionsV3 = {},
+): EconomicsProjectionV3 {
+  if (!read.complete) throw new Error("economics projection requires a complete V3 ledger read");
+  const models = new Map<string, string | null>();
+  const turns: TurnEconomicsV3[] = [];
+  for (const positioned of read.events) {
+    const event = positioned.event as unknown as EventShape;
+    const generationId = event.scope.generation_id;
+    if (
+      generationId &&
+      (event.event_type === "session.started" || event.event_type === "session.attestation_changed")
+    ) {
+      models.set(generationId, modelKey(event.payload.runtime_attestation));
+    }
+    if (event.event_type !== "turn.completed") continue;
+    const tokens = tokensFromObservation(event.payload.usage);
+    const model = generationId ? (models.get(generationId) ?? null) : null;
+    const slowestHook = slowestHookFromObservation(event.payload.harness);
+    turns.push({
+      generation_id: generationId ?? "",
+      turn_id: event.scope.turn_id ?? "",
+      terminal_event_id: event.event_id,
+      model_key: model,
+      usage_method: usageMethod(event.payload.usage),
+      tokens,
+      inference_ms: timingFromObservation(
+        event.payload.inference,
+        "api_time_ms",
+        "inference_unknown",
+      ),
+      harness_ms: timingFromObservation(event.payload.harness, "hook_time_ms", "harness_unknown"),
+      slowest_hook: slowestHook.name,
+      slowest_hook_ms: slowestHook.duration_ms,
+      cost: costForTurn(tokens, model, options.pricing),
+    });
+  }
+  const grouped = new Map<string, TurnEconomicsV3[]>();
+  for (const turn of turns) {
+    const generationTurns = grouped.get(turn.generation_id) ?? [];
+    generationTurns.push(turn);
+    grouped.set(turn.generation_id, generationTurns);
+  }
+  const generations = [...grouped.entries()].map(([generationId, generationTurns]) => ({
+    generation_id: generationId,
+    turn_count: generationTurns.length,
+    tokens: sumTokenMetrics(generationTurns.map(({ tokens }) => tokens)),
+    inference_ms: sumTimingMetrics(generationTurns.map(({ inference_ms }) => inference_ms)),
+    harness_ms: sumTimingMetrics(generationTurns.map(({ harness_ms }) => harness_ms)),
+    cost: sumCostMetrics(generationTurns.map(({ cost }) => cost)),
+  }));
+  generations.sort((left, right) => left.generation_id.localeCompare(right.generation_id));
+  return { projection_version: EVENT_V3_ECONOMICS_PROJECTION_VERSION, turns, generations };
+}
+
+export function projectDelegationRollupV3(
+  read: ReadLedgerV3Result,
+  economics: EconomicsProjectionV3,
+  rootGenerationId: string,
+): DelegationRollupV3 {
+  if (!read.complete) throw new Error("delegation rollup requires a complete V3 ledger read");
+  const children = new Map<string, Set<string>>();
+  for (const positioned of read.events) {
+    const event = positioned.event as unknown as EventShape;
+    if (event.event_type !== "agent.completed") continue;
+    const parent = event.scope.generation_id;
+    const child = string(event.payload.child_generation_id);
+    if (!parent || !child) continue;
+    const set = children.get(parent) ?? new Set<string>();
+    set.add(child);
+    children.set(parent, set);
+  }
+
+  const generationIds: string[] = [];
+  const diagnostics: DelegationRollupV3["diagnostics"] = [];
+  const visited = new Set<string>();
+  const active = new Set<string>();
+  const visit = (generationId: string): void => {
+    if (active.has(generationId)) {
+      diagnostics.push({ code: "delegation_cycle", generation_id: generationId });
+      return;
+    }
+    if (visited.has(generationId)) return;
+    visited.add(generationId);
+    active.add(generationId);
+    generationIds.push(generationId);
+    for (const child of [...(children.get(generationId) ?? [])].sort()) visit(child);
+    active.delete(generationId);
+  };
+  visit(rootGenerationId);
+
+  const byGeneration = new Map(
+    economics.generations.map((generation) => [generation.generation_id, generation]),
+  );
+  const included = generationIds.flatMap((generationId) => {
+    const generation = byGeneration.get(generationId);
+    if (generation) return [generation];
+    diagnostics.push({ code: "generation_economics_missing", generation_id: generationId });
+    return [];
+  });
+  const missing = diagnostics
+    .filter(({ code }) => code === "generation_economics_missing")
+    .map(({ generation_id }) => `generation_economics_missing:${generation_id}`);
+  return {
+    root_generation_id: rootGenerationId,
+    generation_ids: generationIds,
+    tokens: sumTokenMetrics([
+      ...included.map(({ tokens }) => tokens),
+      ...missing.map((reason) => ({
+        state: "unknown" as const,
+        known: zeroTokens(),
+        reasons: [reason],
+      })),
+    ]),
+    inference_ms: sumTimingMetrics([
+      ...included.map(({ inference_ms }) => inference_ms),
+      ...missing.map((reason) => ({ state: "unknown" as const, known_ms: 0, reasons: [reason] })),
+    ]),
+    harness_ms: sumTimingMetrics([
+      ...included.map(({ harness_ms }) => harness_ms),
+      ...missing.map((reason) => ({ state: "unknown" as const, known_ms: 0, reasons: [reason] })),
+    ]),
+    cost: sumCostMetrics([
+      ...included.map(({ cost }) => cost),
+      ...missing.map((reason) => ({ state: "unknown" as const, known_usd: 0, reasons: [reason] })),
+    ]),
+    diagnostics,
+  };
+}
+
+function modelKey(runtimeAttestation: unknown): string | null {
+  const model = record(record(runtimeAttestation).model);
+  if (model.state !== "observed") return null;
+  const value = record(model.value);
+  const provider = string(value.provider);
+  const id = string(value.id);
+  return provider && id ? `${provider}/${id}` : null;
+}
+
+function tokensFromObservation(value: unknown): TokenTotalsMetricV3 {
+  const observation = record(value);
+  if (observation.state !== "observed") {
+    return { state: "unknown", known: zeroTokens(), reasons: [observationReason(value)] };
+  }
+  const usage = record(observation.value);
+  if (!nonnegative(usage.input_tokens) || !nonnegative(usage.output_tokens)) {
+    return { state: "unknown", known: zeroTokens(), reasons: ["usage_invalid"] };
+  }
+  return {
+    state: "observed",
+    value: {
+      input_tokens: usage.input_tokens as number,
+      output_tokens: usage.output_tokens as number,
+      cache_read_tokens: nonnegative(usage.cache_read_tokens)
+        ? (usage.cache_read_tokens as number)
+        : 0,
+      cache_write_tokens: nonnegative(usage.cache_write_tokens)
+        ? (usage.cache_write_tokens as number)
+        : 0,
+    },
+  };
+}
+
+function usageMethod(value: unknown): string | null {
+  const observation = record(value);
+  return observation.state === "observed" ? string(record(observation.value).method) || null : null;
+}
+
+function timingFromObservation(value: unknown, field: string, fallback: string): LatencyMetricV3 {
+  const observation = record(value);
+  const fieldValue = record(observation.value)[field];
+  return observation.state === "observed" && nonnegative(fieldValue)
+    ? { state: "observed", value_ms: fieldValue as number }
+    : { state: "unknown", known_ms: 0, reasons: [observationReason(value) || fallback] };
+}
+
+function slowestHookFromObservation(value: unknown): {
+  name: string | null;
+  duration_ms: number | null;
+} {
+  const observation = record(value);
+  if (observation.state !== "observed") return { name: null, duration_ms: null };
+  const harness = record(observation.value);
+  const name = string(harness.slowest_hook);
+  const duration = harness.slowest_hook_ms;
+  return name && nonnegative(duration) && Number.isSafeInteger(duration)
+    ? { name, duration_ms: duration as number }
+    : { name: null, duration_ms: null };
+}
+
+function costForTurn(
+  tokens: TokenTotalsMetricV3,
+  model: string | null,
+  pricing: Record<string, ModelPricingV3> | undefined,
+): CostMetricV3 {
+  const reasons: string[] = tokens.state === "unknown" ? ["usage_unknown"] : [];
+  const tokenValue = tokens.state === "observed" ? tokens.value : tokens.known;
+  if (!model)
+    return { state: "unknown", known_usd: 0, reasons: [...reasons, "model_unknown"].sort() };
+  const rates = pricing?.[model];
+  if (!rates) {
+    return {
+      state: "unknown",
+      known_usd: 0,
+      reasons: [...reasons, `pricing_unavailable:${model}`].sort(),
+    };
+  }
+  if (tokenValue.cache_read_tokens > 0 && rates.cache_read_usd_per_million === undefined) {
+    reasons.push("cache_read_pricing_unavailable");
+  }
+  if (tokenValue.cache_write_tokens > 0 && rates.cache_write_usd_per_million === undefined) {
+    reasons.push("cache_write_pricing_unavailable");
+  }
+  const usd =
+    (tokenValue.input_tokens * rates.input_usd_per_million +
+      tokenValue.output_tokens * rates.output_usd_per_million +
+      tokenValue.cache_read_tokens * (rates.cache_read_usd_per_million ?? 0) +
+      tokenValue.cache_write_tokens * (rates.cache_write_usd_per_million ?? 0)) /
+    1_000_000;
+  return reasons.length > 0
+    ? { state: "unknown", known_usd: roundUsd(usd), reasons }
+    : { state: "observed", usd: roundUsd(usd), pricing_key: model };
+}
+
+function sumTokenMetrics(metrics: TokenTotalsMetricV3[]): TokenTotalsMetricV3 {
+  const total = zeroTokens();
+  const reasons: string[] = [];
+  for (const metric of metrics) {
+    addTokens(total, metric.state === "observed" ? metric.value : metric.known);
+    if (metric.state === "unknown") reasons.push(...metric.reasons);
+  }
+  return reasons.length === 0
+    ? { state: "observed", value: total }
+    : { state: "unknown", known: total, reasons: unique(reasons) };
+}
+
+function sumTimingMetrics(metrics: LatencyMetricV3[]): LatencyMetricV3 {
+  let known = 0;
+  const reasons: string[] = [];
+  for (const metric of metrics) {
+    known += metric.state === "observed" ? metric.value_ms : metric.known_ms;
+    if (metric.state === "unknown") reasons.push(...metric.reasons);
+  }
+  return reasons.length === 0
+    ? { state: "observed", value_ms: known }
+    : { state: "unknown", known_ms: known, reasons: unique(reasons) };
+}
+
+function sumCostMetrics(metrics: CostMetricV3[]): CostMetricV3 {
+  let known = 0;
+  const reasons: string[] = [];
+  const keys = new Set<string>();
+  for (const metric of metrics) {
+    known += metric.state === "observed" ? metric.usd : metric.known_usd;
+    if (metric.state === "observed") keys.add(metric.pricing_key);
+    else reasons.push(...metric.reasons);
+  }
+  return reasons.length === 0
+    ? { state: "observed", usd: roundUsd(known), pricing_key: [...keys].sort().join("+") }
+    : { state: "unknown", known_usd: roundUsd(known), reasons: unique(reasons) };
+}
+
+function zeroTokens(): TokenTotalsV3 {
+  return { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 };
+}
+
+function addTokens(target: TokenTotalsV3, value: TokenTotalsV3): void {
+  target.input_tokens += value.input_tokens;
+  target.output_tokens += value.output_tokens;
+  target.cache_read_tokens += value.cache_read_tokens;
+  target.cache_write_tokens += value.cache_write_tokens;
+}
+
+function nonnegative(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function observationReason(value: unknown): string {
+  const observation = record(value);
+  const state = string(observation.state) || "unknown";
+  const reason = string(observation.reason);
+  return reason ? `${state}:${reason}` : state;
+}
+
+function roundUsd(value: number): number {
+  return Math.round(value * 1_000_000_000_000) / 1_000_000_000_000;
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function string(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}

package/src/core/events/v3/finalization-view.ts

@@ -0,0 +1,67 @@
+import {
+  type CoordinationViewV3,
+  projectCoordinationViewV3,
+  readCoordinationViewV3,
+} from "./coordination-view.ts";
+import type { ReadLedgerV3Result } from "./reader.ts";
+
+export const EVENT_V3_FINALIZATION_VIEW_VERSION = 1 as const;
+
+export type FinalizationScopeV3ErrorCode = "authority_unsafe" | "instance_not_live";
+
+export class FinalizationScopeV3Error extends Error {
+  constructor(public readonly code: FinalizationScopeV3ErrorCode) {
+    super(`event_v3_finalization_scope:${code}`);
+    this.name = "FinalizationScopeV3Error";
+  }
+}
+
+export interface FinalizationScopeV3 {
+  projection_version: typeof EVENT_V3_FINALIZATION_VIEW_VERSION;
+  contract_major: 2;
+  instance_id: string;
+  session_id: string;
+  generation_id: string;
+  lifecycle_state?: string;
+  files_touched: string[];
+  source_event_id: string;
+  source_position: { segment_ordinal: number; byte_offset: number };
+}
+
+/** Read and validate the current V3 finalization boundary for one live instance. */
+export function readFinalizationScopeV3(
+  coordRoot: string,
+  instanceId: string,
+): FinalizationScopeV3 {
+  return finalizationScopeFromCoordinationViewV3(readCoordinationViewV3(coordRoot), instanceId);
+}
+
+/** Pure adapter used by replay tests and safety consumers. */
+export function projectFinalizationScopeV3(
+  read: ReadLedgerV3Result,
+  instanceId: string,
+): FinalizationScopeV3 {
+  return finalizationScopeFromCoordinationViewV3(projectCoordinationViewV3(read), instanceId);
+}
+
+function finalizationScopeFromCoordinationViewV3(
+  view: CoordinationViewV3,
+  instanceId: string,
+): FinalizationScopeV3 {
+  if (!view.authority_safe) throw new FinalizationScopeV3Error("authority_unsafe");
+  const instance = view.instances[instanceId];
+  if (!instance?.authority_eligible) {
+    throw new FinalizationScopeV3Error("instance_not_live");
+  }
+  return {
+    projection_version: EVENT_V3_FINALIZATION_VIEW_VERSION,
+    contract_major: 2,
+    instance_id: instance.instance_id,
+    session_id: instance.session_id,
+    generation_id: instance.generation_id,
+    lifecycle_state: instance.lifecycle_state,
+    files_touched: [...instance.files_touched],
+    source_event_id: instance.last_event_id,
+    source_position: { ...instance.source_position },
+  };
+}