@coreplane/switchboard 1.252.0 → 1.254.0

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -78,6 +78,18 @@ import {
   selectReclaim,
 } from "../../src/core/runLedger/decisions.ts";
 import { intakeReceiptRetentionMs } from "../../src/core/budgets.ts";
+import {
+  decide,
+  planeAskWordOf,
+  type PlaneAckOutcome,
+  type PlaneEffect,
+  type PlaneEvent,
+  type PlaneOutcomePost,
+  type PlaneQueueRow,
+  type PlaneStage,
+  type PlaneState,
+  type PlaneWrite,
+} from "../../src/core/plane/decide.ts";
 import {
   IDEMPOTENCY_KEY_PATTERN,
   capThreadEvent,
@@ -119,6 +131,8 @@ import {
   type McpTicketState,
   type SealedCredential,
 } from "../../src/mcp/registry.ts";
+import { isRunMetricsPoint, pointTurnsFinal, type RunMetricsPoint } from "../../src/core/runMetrics.ts";
+import { AnalyticsEngineSink, NullSink, type RunMetricsSink } from "./runMetricsSink.ts";
 import { injectedBuildStamp } from "../../src/deploy/buildStamp.ts";
 import { systemClock } from "../../src/core/trace/clock.ts";
 import { createTracer } from "../../src/core/trace/tracer.ts";
@@ -148,7 +162,7 @@ const traceSinks = [workerLogSink((line) => console.log(line))];
 //
 // Route surface (JSON in/out; bearer MEMORY_TOKEN on everything but /healthz):
 //   POST /retrieve {scopeKey, query, limit} → {records: MemoryRecord[]}
-//   POST /write    {scopeKey, records: MemoryCandidate[]} → {ok, inserted, deduped, superseded}
+//   POST /write    {scopeKey, records: MemoryCandidate[]} → {ok, inserted, deduped, restated, superseded, evicted}
 //   POST /sweep    {scopeKey, dryRun?} → {ok, swept} (+ ids under dryRun — the marked rows, flipped to `swept`)
 //   GET  /healthz  → {ok:true}  (deploy wake ping; touches no DO)
 // Scheduled-firing routes (the record behind the /runs Scheduled panel;
@@ -161,7 +175,7 @@ const traceSinks = [workerLogSink((line) => console.log(line))];
 // store key, owning the retention policy. Same bearer; /runs/put has its own 2 MiB
 // body fence (a record is budgeted to 1.5 MiB upstream), every other route
 // keeps the 512 KB one.
-//   POST /runs/put    {storeKey, record, policy?, policyUpdatedAt?} → {ok, retained, stored, rewritten}
+//   POST /runs/put    {storeKey, record, policy?, policyUpdatedAt?, point?} → {ok, retained, stored, rewritten}
 //   POST /runs/get    {storeKey, id} → {record: RunRecord | null}      (unknown/expired: null, 200)
 //   POST /runs/list   {storeKey, limit?, before?, beforeId?, sinceMs?, agent?, channel?, threadKey?, parentRunId?}
 //                       → {items: RunListItem[], nextBefore?: {finishedAt, id}}   (cursor = the last row's list key)
@@ -198,6 +212,14 @@ export interface Env {
    *  binding is a cross-script one, and the class must exist on the bot before
    *  the state Worker may name it), and a finish then commits with no event. */
   SHIP_COORDINATOR?: Workflow;
+  /** The run-metrics dataset (docs/reference/specs/run-metrics.md): where the
+   *  RunHistoryDO writes one point per run whose row turned final. Optional
+   *  like SHIP_COORDINATOR: this Worker deploys without it and every answer is
+   *  byte-identical — the NullSink swallows the points. */
+  RUN_METRICS?: AnalyticsEngineDataset;
+  /** The dataset's name, rendered beside the binding, so `/healthz` can answer
+   *  `runMetrics:<dataset>` and the bot's boot probe can compare names. */
+  RUN_METRICS_DATASET?: string;
   MEMORY_TOKEN?: string;
 }
 
@@ -381,8 +403,8 @@ export class MemoryDO extends DurableObject<Env> {
     scopeKey: string,
     candidates: MemoryCandidate[],
     cap: number = DEFAULT_SCOPE_CAP,
-  ): Promise<{ inserted: number; deduped: number; superseded: number; evicted: number }> {
-    const counts = { inserted: 0, deduped: 0, superseded: 0, evicted: 0 };
+  ): Promise<{ inserted: number; deduped: number; restated: number; superseded: number; evicted: number }> {
+    const counts = { inserted: 0, deduped: 0, restated: 0, superseded: 0, evicted: 0 };
     if (candidates.length === 0) return counts;
     this.ctx.storage.transactionSync(() => {
       let seq = this.sql.exec<{ next: number }>(`SELECT COALESCE(MAX(seq), -1) + 1 AS next FROM records`).one().next;
@@ -400,18 +422,41 @@ export class MemoryDO extends DurableObject<Env> {
         // own TRUTHINESS test: `supersedes: ""` passes validation but means NO
         // supersede to the engine, so it must dedup against the norm pool —
         // an `!== undefined` branch here would hand it an empty pool and
-        // insert a duplicate active row.
-        const relevant = (
-          cand.supersedes
-            ? this.sql.exec<Row>(`SELECT * FROM records WHERE id = ? AND status = 'active'`, cand.supersedes)
-            : this.sql.exec<Row>(
-                `SELECT * FROM records WHERE status = 'active' AND norm = ? ORDER BY seq`,
-                normalizeText(cand.text),
+        // insert a duplicate active row. A `restates` id is looked up first
+        // (the restate target); when it misses — not active, or another
+        // scope's id, which this DO simply doesn't hold — the candidate takes
+        // today's pool, so planWrite falls through to dedup-or-insert.
+        const restatePool = cand.restates
+          ? this.sql
+              .exec<Row>(`SELECT * FROM records WHERE id = ? AND status = 'active'`, cand.restates)
+              .toArray()
+              .map(toRecord)
+          : [];
+        const relevant =
+          restatePool.length > 0
+            ? restatePool
+            : (cand.supersedes
+                ? this.sql.exec<Row>(`SELECT * FROM records WHERE id = ? AND status = 'active'`, cand.supersedes)
+                : this.sql.exec<Row>(
+                    `SELECT * FROM records WHERE status = 'active' AND norm = ? ORDER BY seq`,
+                    normalizeText(cand.text),
+                  )
               )
-        )
-          .toArray()
-          .map(toRecord);
+                .toArray()
+                .map(toRecord);
         const plan = planWrite(relevant, cand, (c) => mintRecord(scopeKey, seq++, now, c));
+        if (plan.action === "restate") {
+          // The shown record is refreshed in place; COALESCE keeps the stored
+          // confidence when the plan carries none (neither side had a value).
+          this.sql.exec(
+            `UPDATE records SET use_count = use_count + 1, last_used_at = ?, confidence = COALESCE(?, confidence) WHERE id = ?`,
+            now,
+            plan.confidence ?? null,
+            plan.target.id,
+          );
+          counts.restated++;
+          continue;
+        }
         if (plan.action === "dedup") {
           this.sql.exec(`UPDATE records SET use_count = use_count + 1 WHERE id = ?`, plan.target.id);
           counts.deduped++;
@@ -1173,13 +1218,16 @@ export class CostsSnapshotDO extends DurableObject<Env> {
     `);
   }
 
-  /** Replace the snapshot whole: every part rewritten in one transaction. */
+  /** Replace the snapshot whole: every part rewritten in one transaction. Each
+   *  logical part is its own named row — `invoices` included, never a rest-spread
+   *  into the meta row that would silently absorb future fields. */
   async put(snapshot: CostsSnapshot): Promise<void> {
-    const { usage, llm, runUsage, ...meta } = snapshot;
+    const { usage, llm, invoices, runUsage, ...meta } = snapshot;
     const rows: Array<[string, unknown]> = [
       ["meta", meta],
       ...USAGE_PARTS.map((name): [string, unknown] => [`usage.${name}`, usage[name]]),
       ["llm", llm],
+      ...(invoices !== undefined ? [["invoices", invoices] as [string, unknown]] : []),
       ["runUsage", runUsage],
     ];
     this.ctx.storage.transactionSync(() => {
@@ -1204,10 +1252,12 @@ export class CostsSnapshotDO extends DurableObject<Env> {
       return body === undefined ? undefined : (JSON.parse(body) as unknown);
     };
     const usage = Object.fromEntries(USAGE_PARTS.map((name) => [name, read(`usage.${name}`)]));
+    const invoices = read("invoices");
     const snapshot = {
       ...(JSON.parse(meta) as Record<string, unknown>),
       usage,
       llm: read("llm"),
+      ...(invoices !== undefined ? { invoices } : {}),
       runUsage: read("runUsage"),
     };
     return isCostsSnapshot(snapshot) ? snapshot : null;
@@ -1481,14 +1531,32 @@ function rowToLive(r: LiveRow): LiveRunRow {
   };
 }
 
-type HeartbeatAnswer = FenceResult & { stop?: StopMode | null; phase?: LivePhase };
+type HeartbeatAnswer = FenceResult & { stop?: StopMode | null; phase?: LivePhase; effects?: PlaneEffect[] };
+
+/** Whether the bot's outcome and the decider's word agree (orchestration-plane item 8): `proceeded`
+ *  beside `proceed`, and a thread-live refusal beside `queued` — the refusal
+ *  IS the queue position the plane would hold. `null` for a pair the decider
+ *  does not model yet: logged, never counted. */
+function planeAgreementOf(outcome: string, decider: "proceed" | "queued"): boolean | null {
+  if (outcome === "proceeded") return decider === "proceed";
+  if (outcome === "refused:thread-live") return decider === "queued";
+  return null;
+}
+
+/** The most effects one answer carries (record 0064; orchestration-plane item 7): the rest ride the next heartbeat. */
+const PLANE_EFFECTS_PER_ANSWER = 32;
 
 export class RunHistoryDO extends DurableObject<Env> {
   private readonly sql: SqlStorage;
+  /** Where a turned-final run's point goes (run-metrics.md): the Analytics
+   *  Engine dataset when the deploy bound one, the NullSink otherwise —
+   *  selected once at construction, the `SHIP_COORDINATOR?` shape. */
+  private readonly metrics: RunMetricsSink;
 
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
     this.sql = ctx.storage.sql;
+    this.metrics = env.RUN_METRICS !== undefined ? new AnalyticsEngineSink(env.RUN_METRICS) : new NullSink();
     // Idempotent schema. `runs` carries the listing columns plus the record
     // minus its events as JSON (`summary_json`, what `list` returns); events
     // live one per row keyed (run_id, seq) so a 5000-event run is paged, never
@@ -1643,6 +1711,215 @@ export class RunHistoryDO extends DurableObject<Env> {
         PRIMARY KEY (instance_id, unit, seq)
       );
     `);
+    // The orchestration plane's tables (record 0064; orchestration-plane.md item 7):
+    // the queue with its conditions, the reservations, the quiet and pressure
+    // windows, the watches' findings, the offered effects and the residents'
+    // levels. This unit opens them all so a later Worker and an earlier one agree on
+    // the schema; only the queue and the effects are written yet.
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS plane_queue (
+        run_id TEXT PRIMARY KEY,
+        requester TEXT NOT NULL,
+        thread_key TEXT NOT NULL,
+        stage TEXT NOT NULL,
+        request_json TEXT NOT NULL,
+        conditions_json TEXT NOT NULL,
+        position_at INTEGER NOT NULL,
+        queued_at INTEGER NOT NULL,
+        state TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS plane_queue_waiting ON plane_queue(state, queued_at);
+      CREATE TABLE IF NOT EXISTS plane_reservations (
+        kind TEXT NOT NULL,
+        key TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        at INTEGER NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+      CREATE TABLE IF NOT EXISTS plane_windows (
+        kind TEXT NOT NULL,
+        key TEXT NOT NULL,
+        phase TEXT NOT NULL,
+        opened_at INTEGER NOT NULL,
+        reason_json TEXT NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+      CREATE TABLE IF NOT EXISTS plane_findings (
+        id TEXT PRIMARY KEY,
+        watch TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        timeline_json TEXT NOT NULL,
+        filed_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS plane_effects (
+        id TEXT PRIMARY KEY,
+        body_json TEXT NOT NULL,
+        offered_at INTEGER NOT NULL,
+        acked_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS plane_effects_open ON plane_effects(acked_at, offered_at);
+      CREATE TABLE IF NOT EXISTS plane_levels (
+        resident TEXT NOT NULL,
+        name TEXT NOT NULL,
+        side TEXT NOT NULL,
+        reported_at INTEGER NOT NULL,
+        generation TEXT NOT NULL,
+        PRIMARY KEY (resident, name)
+      );
+    `);
+  }
+
+  // ---- the orchestration plane (record 0064; orchestration-plane.md) ----------
+
+  /** The decider's state, read inside the caller's `transactionSync`: the
+   *  queue oldest first and the threads a live row holds. `excludeRunId` drops
+   *  that run's own live row from the view — a shadow post judged after the
+   *  dispatch it describes claimed the thread must not read its own claim as
+   *  "thread live" (orchestration-plane item 8). */
+  private planeState(excludeRunId?: string): PlaneState {
+    const queue = this.sql
+      .exec<{
+        run_id: string;
+        requester: string;
+        thread_key: string;
+        stage: string;
+        request_json: string;
+        conditions_json: string;
+        position_at: number;
+        queued_at: number;
+        state: string;
+      }>(`SELECT * FROM plane_queue ORDER BY queued_at ASC, run_id ASC`)
+      .toArray()
+      .map((r): PlaneQueueRow => ({
+        runId: r.run_id,
+        requester: r.requester,
+        threadKey: r.thread_key,
+        stage: r.stage as PlaneStage,
+        request: JSON.parse(r.request_json) as Record<string, unknown>,
+        conditions: JSON.parse(r.conditions_json) as PlaneQueueRow["conditions"],
+        position: r.position_at,
+        queuedAt: r.queued_at,
+        state: r.state as PlaneQueueRow["state"],
+      }));
+    const liveThreads = this.sql
+      .exec<{ thread_key: string }>(`SELECT thread_key FROM live_runs WHERE run_id IS NOT ?`, excludeRunId ?? null)
+      .toArray()
+      .map((r) => r.thread_key);
+    return { queue, liveThreads };
+  }
+
+  /** The decider's writes, applied inside the same `transactionSync` that read
+   *  the state — the decision and its consequences land together (orchestration-plane item 6). */
+  private applyPlaneWrites(writes: PlaneWrite[]): void {
+    for (const w of writes) {
+      if (w.table === "plane_queue" && w.op === "put") {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO plane_queue
+             (run_id, requester, thread_key, stage, request_json, conditions_json, position_at, queued_at, state)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          w.row.runId,
+          w.row.requester,
+          w.row.threadKey,
+          w.row.stage,
+          JSON.stringify(w.row.request),
+          JSON.stringify(w.row.conditions),
+          w.row.position,
+          w.row.queuedAt,
+          w.row.state,
+        );
+      } else if (w.table === "plane_queue" && w.op === "state") {
+        this.sql.exec(`UPDATE plane_queue SET state = ? WHERE run_id = ?`, w.state, w.runId);
+      } else {
+        // An offer keeps its first `offered_at`: a re-decided admit after a
+        // roll is the same effect, not a younger one.
+        this.sql.exec(
+          `INSERT OR IGNORE INTO plane_effects (id, body_json, offered_at, acked_at) VALUES (?, ?, ?, NULL)`,
+          w.effect.id,
+          JSON.stringify(w.effect),
+          w.at,
+        );
+      }
+    }
+  }
+
+  /** Apply one plane event: state read, decider, writes and effects in ONE
+   *  `transactionSync` (orchestration-plane item 6). The transport unit's routes feed it; the tests pin the atomicity. */
+  planeApply(event: PlaneEvent): { effects: PlaneEffect[] } {
+    let effects: PlaneEffect[] = [];
+    this.ctx.storage.transactionSync(() => {
+      const decision = decide(this.planeState(), event);
+      this.applyPlaneWrites(decision.writes);
+      effects = decision.effects;
+    });
+    return { effects };
+  }
+
+  /** The unacknowledged effects, oldest first, at most `PLANE_EFFECTS_PER_ANSWER`
+   *  (orchestration-plane item 7) — what every heartbeat and reclaim answer carries. Public: the
+   *  reclaim route composes it beside the runs it took. */
+  openPlaneEffects(): PlaneEffect[] {
+    return this.sql
+      .exec<{ body_json: string }>(
+        `SELECT body_json FROM plane_effects WHERE acked_at IS NULL ORDER BY offered_at ASC, id ASC LIMIT ?`,
+        PLANE_EFFECTS_PER_ANSWER,
+      )
+      .toArray()
+      .map((r) => JSON.parse(r.body_json) as PlaneEffect);
+  }
+
+  /** Shadow (orchestration-plane item 8): the bot's own outcome for one dispatch, judged beside the
+   *  decider's word for the same ask. Nothing runs and nothing queues from
+   *  the decider here — the comparison is logged, and a disagreement bumps a
+   *  per-condition counter in `meta` for the `plane disagreements` line. An
+   *  outcome the decider does not model yet (an allowlist refusal, a cold
+   *  fall) is logged uncounted. The post is fired without an await, so it can
+   *  arrive AFTER the dispatch it describes claimed this thread's `live_runs`
+   *  row; a post carrying the run's own id excludes that row from the live
+   *  view so the run's own claim never reads as a false disagreement. */
+  planeOutcome(
+    post: PlaneOutcomePost,
+    now: number,
+  ): { ok: true; decider: "proceed" | "queued"; agreed: boolean | null } {
+    let decider: "proceed" | "queued" = "proceed";
+    let agreed: boolean | null = null;
+    this.ctx.storage.transactionSync(() => {
+      const ask: PlaneEvent = {
+        kind: "ask",
+        at: now,
+        runId: post.runId ?? `ask:${post.threadKey}:${now}`,
+        requester: post.requester,
+        threadKey: post.threadKey,
+        stage: post.stage,
+        request: {},
+      };
+      decider = planeAskWordOf(decide(this.planeState(post.runId), ask), ask.runId);
+      agreed = planeAgreementOf(post.outcome, decider);
+      if (agreed === false) this.bumpPlaneDisagreement("thread_free");
+    });
+    console.log(
+      `[plane/outcome] ${post.threadKey} ${post.stage} bot=${post.outcome} decider=${decider} agreed=${agreed ?? "uncompared"}`,
+    );
+    return { ok: true, decider, agreed };
+  }
+
+  /** The per-condition disagreement counts (orchestration-plane item 8), kept in `meta` so the table's
+   *  later `plane disagreements` line can read them. */
+  private bumpPlaneDisagreement(condition: string): void {
+    const row = this.sql
+      .exec<{ value: string }>(`SELECT value FROM meta WHERE key = 'plane_disagreements'`)
+      .toArray()[0];
+    const counts = row ? (JSON.parse(row.value) as Record<string, number>) : {};
+    counts[condition] = (counts[condition] ?? 0) + 1;
+    this.sql.exec(`INSERT OR REPLACE INTO meta (key, value) VALUES ('plane_disagreements', ?)`, JSON.stringify(counts));
+  }
+
+  /** An effect's acknowledgement by id (orchestration-plane item 7): `done` and `skipped` close it,
+   *  `deferred` leaves it offered for the next answer. An unknown id is a
+   *  no-op — the bot may ack an effect an older table never held. */
+  planeAck(id: string, outcome: PlaneAckOutcome, now: number): { ok: true } {
+    if (outcome !== "deferred")
+      this.sql.exec(`UPDATE plane_effects SET acked_at = ? WHERE id = ? AND acked_at IS NULL`, now, id);
+    return { ok: true };
   }
 
   // ---- the coordinator's parent records (run-history item 49) -----------------
@@ -1931,7 +2208,10 @@ export class RunHistoryDO extends DurableObject<Env> {
         return;
       }
       this.sql.exec(`UPDATE live_runs SET lease_until = ? WHERE run_id = ?`, now + leaseMs, runId);
-      out = { ok: true, stop: row.stop, phase: row.phase };
+      // The plane's open effects ride every owner's heartbeat answer (record
+      // 0064; orchestration-plane item 7) — empty until a unit writes them, but always present, so the
+      // client's ack loop needs no version probe.
+      out = { ok: true, stop: row.stop, phase: row.phase, effects: this.openPlaneEffects() };
     });
     return out;
   }
@@ -2063,8 +2343,10 @@ export class RunHistoryDO extends DurableObject<Env> {
     gen: string,
     record: RunRecord,
     proposal?: RunPolicyProposal,
+    point?: RunMetricsPoint,
   ): Promise<FenceResult & { stored?: boolean; event?: RunFinishedSend["kind"] }> {
     let out: FenceResult & { stored?: boolean } = { ok: true };
+    let turnedFinal = false;
     this.ctx.storage.transactionSync(() => {
       const fence = checkFence(this.liveRow(runId), gen);
       if (!fence.ok) {
@@ -2073,9 +2355,14 @@ export class RunHistoryDO extends DurableObject<Env> {
       }
       const put = this.upsertInTransaction(record, proposal);
       this.deleteLiveRows([runId]);
+      turnedFinal = put.turnedFinal;
       out = { ok: true, stored: put.stored };
     });
     if (!out.ok) return out;
+    // The point after the commit, never inside it (`sendRunFinished`'s placement):
+    // the finish usually replaces the start tombstone, so this is where most
+    // runs are counted (run-metrics.md item 2).
+    this.writeMetricsPoint(runId, point, turnedFinal && out.stored === true);
     if ((await this.ctx.storage.getAlarm()) === null)
       await this.ctx.storage.setAlarm(systemClock() + RUN_SWEEP_INTERVAL_MS);
     await this.refreshSessionBytes(record.session?.key);
@@ -2338,15 +2625,21 @@ export class RunHistoryDO extends DurableObject<Env> {
    *  when the stored version changed (`event_count`, `finished_at`, `bytes`) —
    *  an identical retry is a no-op on `run_events`. `stored: false` when the
    *  record itself fell outside the (possibly just-updated) policy: it was
-   *  written and deleted in the same transaction, so nothing of it remains. */
+   *  written and deleted in the same transaction, so nothing of it remains.
+   *  `point` is the record's metrics point, computed by the client
+   *  (run-metrics.md): written to the sink AFTER the commit, only when the row
+   *  turned final and the record was stored — `turnedFinal` stays internal (the
+   *  route strips it), so the wire answer is exactly the shape it always was. */
   async put(
     record: RunRecord,
     proposal?: RunPolicyProposal,
-  ): Promise<{ ok: true; retained: number; stored: boolean; rewritten: boolean }> {
-    let result = { ok: true as const, retained: 0, stored: false, rewritten: false };
+    point?: RunMetricsPoint,
+  ): Promise<{ ok: true; retained: number; stored: boolean; rewritten: boolean; turnedFinal: boolean }> {
+    let result = { ok: true as const, retained: 0, stored: false, rewritten: false, turnedFinal: false };
     this.ctx.storage.transactionSync(() => {
       result = this.upsertInTransaction(record, proposal);
     });
+    this.writeMetricsPoint(record.id, point, result.turnedFinal && result.stored);
     // A coordinator child closed OUTSIDE the ledger's finish — the run loop or
     // a reclaim writing an `interrupted` record, the pi harness's typed restart,
     // a resume abandoning a lost workspace — still wakes its parent's wait at
@@ -2370,7 +2663,7 @@ export class RunHistoryDO extends DurableObject<Env> {
   private upsertInTransaction(
     record: RunRecord,
     proposal?: RunPolicyProposal,
-  ): { ok: true; retained: number; stored: boolean; rewritten: boolean } {
+  ): { ok: true; retained: number; stored: boolean; rewritten: boolean; turnedFinal: boolean } {
     {
       const now = systemClock();
       const policy = proposal ? this.applyProposal(proposal, now).policy : this.policyState().policy;
@@ -2387,11 +2680,29 @@ export class RunHistoryDO extends DurableObject<Env> {
       const { events, ...summary } = stored;
       const bytes = utf8ByteLength(JSON.stringify(stored));
       const existing = this.sql
-        .exec<{ event_count: number; finished_at: number; bytes: number }>(
-          `SELECT event_count, finished_at, bytes FROM runs WHERE run_id = ?`,
+        .exec<{ event_count: number; finished_at: number; bytes: number; summary_json: string }>(
+          `SELECT event_count, finished_at, bytes, summary_json FROM runs WHERE run_id = ?`,
           record.id,
         )
         .toArray()[0];
+      // The one field of the stored summary the emission rule reads (run-metrics.md
+      // item 2): the row's `provisional`, parsed alone — never deserialized whole.
+      const existingProvisional = existing !== undefined && summaryIsProvisional(existing.summary_json);
+      const turnedFinal = pointTurnsFinal(
+        existing !== undefined ? { provisional: existingProvisional } : undefined,
+        stored,
+      );
+      // A provisional record never overwrites a final row (run-history.md item 27;
+      // run-metrics.md item 3): a start tombstone sitting in retry backoff or a
+      // drain upgrade racing a fast finish would otherwise land after the finish
+      // record, overwrite it with `interrupted` — and let the run's point be
+      // written twice when a later final write turned the row "final" again.
+      // Answered as stored, with nothing written: the row, its events and the
+      // sessions table stay exactly as the final write left them.
+      if (stored.provisional === true && existing !== undefined && !existingProvisional) {
+        const retained = this.sql.exec<{ n: number }>(`SELECT COUNT(*) AS n FROM runs`).one().n;
+        return { ok: true as const, retained, stored: true, rewritten: false, turnedFinal: false };
+      }
       const unchanged =
         existing !== undefined &&
         sameStoredVersion(
@@ -2471,10 +2782,25 @@ export class RunHistoryDO extends DurableObject<Env> {
         retained: kept.size,
         stored: kept.has(record.id),
         rewritten: existing !== undefined && !unchanged,
+        turnedFinal,
       };
     }
   }
 
+  /** One point per run whose row turned final, AFTER the commit (run-metrics.md
+   *  item 2) — advisory: a throwing sink leaves the answer exactly as a
+   *  recording one would, and says so in one warn line with the run id and the
+   *  error's constructor name, never the point's contents. */
+  private writeMetricsPoint(runId: string, point: RunMetricsPoint | undefined, turnedFinal: boolean): void {
+    if (point === undefined || !turnedFinal) return;
+    try {
+      this.metrics.write(point);
+    } catch (err) {
+      const kind = err instanceof Error ? err.constructor.name : "Error";
+      console.warn(`[runs/metrics] ${runId} point not written: ${kind}`);
+    }
+  }
+
   /** Remove a run and its events. Returns whether a run row existed. */
   async delete(id: string): Promise<boolean> {
     let deleted = false;
@@ -2924,6 +3250,17 @@ function parseSummary(row: RunRow): Omit<RunRecord, "events"> | null {
   }
 }
 
+/** The one field of a stored row's summary the emission rule reads: whether the
+ *  row is a provisional tombstone. Deliberately not a full `RunRecord` parse
+ *  (run-metrics.md item 2) — this runs inside every upsert's transaction. */
+function summaryIsProvisional(summaryJson: string): boolean {
+  try {
+    return (JSON.parse(summaryJson) as { provisional?: unknown }).provisional === true;
+  } catch {
+    return false;
+  }
+}
+
 function parseRunId(v: unknown): Validated<string> {
   if (typeof v !== "string" || !RUN_ID_PATTERN.test(v)) return invalid("id must match ^[A-Za-z0-9_-]{1,64}$");
   return { ok: true, value: v };
@@ -2939,16 +3276,24 @@ function parsePositiveInt(v: unknown, name: string, max: number): Validated<numb
   return { ok: true, value: v };
 }
 
-function parseRunPut(body: unknown): Validated<{ storeKey: string; record: RunRecord; proposal?: RunPolicyProposal }> {
+function parseRunPut(
+  body: unknown,
+): Validated<{ storeKey: string; record: RunRecord; proposal?: RunPolicyProposal; point?: RunMetricsPoint }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
   const b = body as Record<string, unknown>;
   const key = parseStoreKey(b);
   if (!key.ok) return key;
   if (!isRunRecord(b.record)) return invalid("record must be a RunRecord");
-  const out: { storeKey: string; record: RunRecord; proposal?: RunPolicyProposal } = {
+  const out: { storeKey: string; record: RunRecord; proposal?: RunPolicyProposal; point?: RunMetricsPoint } = {
     storeKey: key.value,
     record: b.record,
   };
+  // The record's metrics point (run-metrics.md item 1), validated at the door
+  // like everything else that reaches storage.
+  if (b.point !== undefined) {
+    if (!isRunMetricsPoint(b.point)) return invalid("point must be a RunMetricsPoint");
+    out.point = b.point;
+  }
   if (b.policy !== undefined) {
     if (typeof b.policy !== "object" || b.policy === null) return invalid("policy must be an object");
     const p = b.policy as Record<string, unknown>;
@@ -3259,6 +3604,11 @@ function parseCandidate(v: unknown, i: number): Validated<MemoryCandidate> {
       return invalid(`${at}.supersedes must be a string`);
     out.supersedes = c.supersedes;
   }
+  if (c.restates !== undefined) {
+    if (typeof c.restates !== "string" || c.restates.length > MAX_KEY_CHARS)
+      return invalid(`${at}.restates must be a string`);
+    out.restates = c.restates;
+  }
   return { ok: true, value: out };
 }
 
@@ -3823,6 +4173,60 @@ const LEDGER_ROUTES = new Set([
   "/runs/session/notepad/write",
 ]);
 
+/** The plane's routes (record 0064; orchestration-plane items 7 and 8): the shadow outcome post and the
+ *  effect acknowledgement. Both land on the ledger object of the given store
+ *  key, like every `/runs/*` route. */
+const PLANE_ROUTES = new Set(["/plane/outcome", "/plane/ack"]);
+
+const PLANE_STAGES = new Set(["admission", "runner", "resident"]);
+const PLANE_OUTCOME = /^(proceeded|refused:[a-z0-9-]+|fell_cold:[a-z0-9_-]+)$/;
+const PLANE_ACK_OUTCOMES = new Set(["done", "skipped", "deferred"]);
+
+/** The `/plane/*` routes: validated before any object call, ids and words
+ *  only on the log lines. */
+async function handlePlane(pathname: string, body: unknown, env: Env): Promise<Response> {
+  if (typeof body !== "object" || body === null) return json({ error: "body must be a JSON object" }, 400);
+  const b = body as Record<string, unknown>;
+  const key = parseStoreKey(b);
+  if (!key.ok) return json({ error: key.error }, 400);
+  const stub = env.RUNS.get(env.RUNS.idFromName(key.value));
+  const now = systemClock();
+  if (pathname === "/plane/outcome") {
+    if (typeof b.threadKey !== "string" || b.threadKey.length === 0)
+      return json({ error: "threadKey must be a non-empty string" }, 400);
+    if (typeof b.requester !== "string" || b.requester.length === 0)
+      return json({ error: "requester must be a non-empty string" }, 400);
+    if (typeof b.stage !== "string" || !PLANE_STAGES.has(b.stage))
+      return json({ error: "stage must be admission, runner or resident" }, 400);
+    if (typeof b.outcome !== "string" || !PLANE_OUTCOME.test(b.outcome))
+      return json({ error: "outcome must be proceeded, refused:<code> or fell_cold:<token>" }, 400);
+    let runId: string | undefined;
+    if (b.runId !== undefined) {
+      const parsed = parseRunId(b.runId);
+      if (!parsed.ok) return json({ error: parsed.error }, 400);
+      runId = parsed.value;
+    }
+    const r = await stub.planeOutcome(
+      {
+        ...(runId !== undefined ? { runId } : {}),
+        requester: b.requester,
+        threadKey: b.threadKey,
+        stage: b.stage as PlaneStage,
+        outcome: b.outcome,
+      },
+      now,
+    );
+    return json(r);
+  }
+  if (pathname === "/plane/ack") {
+    if (typeof b.id !== "string" || b.id.length === 0) return json({ error: "id must be a non-empty string" }, 400);
+    if (typeof b.outcome !== "string" || !PLANE_ACK_OUTCOMES.has(b.outcome))
+      return json({ error: "outcome must be done, skipped or deferred" }, 400);
+    return json(await stub.planeAck(b.id, b.outcome as PlaneAckOutcome, now));
+  }
+  return json({ error: "not found" }, 404);
+}
+
 /** Routes whose bodies may carry a record, a transcript chunk, or an event batch. */
 const WIDE_BODY_ROUTES = new Set([
   "/runs/put",
@@ -4129,7 +4533,9 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     // declared shape.
     const runs = (await stub.reclaim(g.value, at, lease.value)) as unknown as ReclaimedRun[];
     console.log(`[runs/reclaim] ${key.value} ${g.value} took ${runs.length} run(s)`);
-    return json({ runs });
+    // The reclaim sweep's answer carries the plane's open effects like every
+    // heartbeat answer does (record 0064; orchestration-plane item 7) — empty until a unit writes them.
+    return json({ runs, effects: await stub.openPlaneEffects() });
   }
   if (pathname === "/runs/handoff") {
     const g = gen(b.gen);
@@ -4264,7 +4670,10 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
   if (pathname === "/runs/heartbeat") {
     const lease = parseLeaseMs(b.leaseMs);
     if (!lease.ok) return json({ error: lease.error }, 400);
-    const r = await stub.heartbeat(runId.value, g.value, lease.value, now);
+    // The RPC type mapping reads the effects' open-ended `request` JSON as
+    // unserializable; the values are plain JSON, so the cast only restores the
+    // declared shape (as the reclaim route's does).
+    const r = (await stub.heartbeat(runId.value, g.value, lease.value, now)) as unknown as HeartbeatAnswer;
     return r.ok ? json(r) : json(r, 409);
   }
   if (pathname === "/runs/append") {
@@ -4302,7 +4711,7 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     const parsed = parseRunPut({ ...b, storeKey: key.value });
     if (!parsed.ok) return json({ error: parsed.error }, 400);
     if (parsed.value.record.id !== runId.value) return json({ error: "record.id must equal runId" }, 400);
-    const r = await stub.finish(runId.value, g.value, parsed.value.record, parsed.value.proposal);
+    const r = await stub.finish(runId.value, g.value, parsed.value.record, parsed.value.proposal, parsed.value.point);
     console.log(
       `[runs/finish] ${key.value} ${runId.value} ok=${r.ok}${r.ok ? ` stored=${r.stored} event=${r.event}` : ` ${r.reason}`}`,
     );
@@ -4319,8 +4728,10 @@ async function handleRuns(pathname: string, body: unknown, env: Env): Promise<Re
   if (pathname === "/runs/put") {
     const parsed = parseRunPut(body);
     if (!parsed.ok) return json({ error: parsed.error }, 400);
-    const { storeKey, record, proposal } = parsed.value;
-    const result = await stub(storeKey).put(record, proposal);
+    const { storeKey, record, proposal, point } = parsed.value;
+    // `turnedFinal` stays internal: the wire answer is exactly the shape it
+    // always was, binding or no binding (run-metrics.md item 4).
+    const { turnedFinal: _turnedFinal, ...result } = await stub(storeKey).put(record, proposal, point);
     console.log(
       `[runs/put] ${storeKey} <- ${record.id} (${record.storedEventCount} events, stored=${result.stored}, ${result.retained} retained)`,
     );
@@ -4394,6 +4805,7 @@ const ROUTES = new Set([
   "/runs/usage",
   "/runs/delete",
   ...LEDGER_ROUTES,
+  ...PLANE_ROUTES,
 ]);
 
 /** The two decisions `fetch` makes once and hands down: is the path one of
@@ -4404,11 +4816,21 @@ interface Admission {
   authorized: boolean;
 }
 
+/** What this deploy carries, for the bot's boot probe: the fixed route set,
+ *  plus `runMetrics:<dataset>` when the deploy bound the Analytics Engine
+ *  dataset (run-metrics.md item 5) — the name from the `RUN_METRICS_DATASET`
+ *  var rendered beside the binding, so the probe can compare it to the bot's. */
+export function featuresOf(env: Pick<Env, "RUN_METRICS" | "RUN_METRICS_DATASET">): string[] {
+  const features = ["memory", "schedules", "runs", "config", "delivery", "costs", "plane"];
+  if (env.RUN_METRICS !== undefined) features.push(`runMetrics:${env.RUN_METRICS_DATASET ?? "unknown"}`);
+  return features;
+}
+
 /** Every request, once `fetch` has decided whether it gets a root. */
 async function handleRequest(request: Request, env: Env, admission: Admission): Promise<Response> {
   const url = new URL(request.url);
   if (url.pathname === "/healthz" && request.method === "GET")
-    return json({ ok: true, build: BUILD, features: ["memory", "schedules", "runs", "config", "delivery", "costs"] });
+    return json({ ok: true, build: BUILD, features: featuresOf(env) });
   if (!admission.known) return json({ error: "not found" }, 404);
   if (request.method !== "POST") return json({ error: "method not allowed" }, 405);
   if (!admission.authorized) return json({ error: "unauthorized" }, 401);
@@ -4458,6 +4880,7 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
     return json({ firings });
   }
   if (url.pathname.startsWith("/runs/")) return handleRuns(url.pathname, body, env);
+  if (url.pathname.startsWith("/plane/")) return handlePlane(url.pathname, body, env);
   if (url.pathname.startsWith("/config/")) return handleConfig(url.pathname, body, env);
   if (url.pathname.startsWith("/delivery/")) return handleDelivery(url.pathname, body, env);
   if (url.pathname.startsWith("/costs/")) return handleCosts(url.pathname, body, env);