@coreplane/switchboard 1.251.0 → 1.253.0

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

@@ -7,6 +7,7 @@ import {
   planEviction,
   planWrite,
   rankRecords,
+  rejectionMarkers,
 } from "../../src/core/memory/engine.ts";
 import { tokenize } from "../../src/core/memory/scorer.ts";
 import { FIRING_DETAIL_MAX, isScheduleFiring, type ScheduleFiring } from "../../src/core/schedules.ts";
@@ -118,6 +119,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";
@@ -147,7 +150,8 @@ 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;
 // written by the bot's Worker shim after every cron firing, read by the bot's
@@ -159,7 +163,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)
@@ -196,6 +200,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;
 }
 
@@ -379,8 +391,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;
@@ -398,18 +410,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++;
@@ -463,14 +498,19 @@ export class MemoryDO extends DurableObject<Env> {
     return counts;
   }
 
-  /** Human view (docs/reference/specs/memory.md item 24): the scope's ACTIVE rows, newest first, no usage
-   *  bump. With `query`, only rows an FTS token hits (the same quoted-OR MATCH
-   *  as retrieve, so user text never reaches the FTS parser as syntax); a
-   *  query with no tokens lists nothing. */
-  async list(_scopeKey: string, limit: number, query?: string): Promise<MemoryRecord[]> {
+  /** Human view and the repository window's read (docs/reference/specs/memory.md items 22, 26): the
+   *  scope's ACTIVE rows, newest first, no usage bump. With `query`, only rows
+   *  an FTS token hits (the same quoted-OR MATCH as retrieve, so user text
+   *  never reaches the FTS parser as syntax); a query with no tokens lists
+   *  nothing. With `kind`, only rows of that kind (the window lists facts). */
+  async list(_scopeKey: string, limit: number, query?: string, kind?: MemoryRecord["kind"]): Promise<MemoryRecord[]> {
     if (query === undefined) {
       return this.sql
-        .exec<Row>(`SELECT * FROM records WHERE status = 'active' ORDER BY seq DESC LIMIT ?`, limit)
+        .exec<Row>(
+          `SELECT * FROM records WHERE status = 'active'${kind === undefined ? "" : " AND kind = ?"} ORDER BY seq DESC LIMIT ?`,
+          ...(kind === undefined ? [] : [kind]),
+          limit,
+        )
         .toArray()
         .map(toRecord);
     }
@@ -480,9 +520,10 @@ export class MemoryDO extends DurableObject<Env> {
       .exec<Row>(
         `SELECT r.* FROM records r
            JOIN records_fts f ON f.id = r.id
-          WHERE r.status = 'active' AND records_fts MATCH ?
+          WHERE r.status = 'active'${kind === undefined ? "" : " AND r.kind = ?"} AND records_fts MATCH ?
           ORDER BY r.seq DESC
           LIMIT ?`,
+        ...(kind === undefined ? [] : [kind]),
         match,
         limit,
       )
@@ -504,6 +545,33 @@ export class MemoryDO extends DurableObject<Env> {
       return flipped;
     });
   }
+
+  /** Human control (docs/reference/specs/memory.md item 27): retire every
+   *  ACTIVE fact whose text the write gate would reject today — the same
+   *  `rejectionMarkers` the bot's write path runs, imported from the shared
+   *  engine, so the sweep and the gate can never disagree. Summaries are never
+   *  gated, so never swept. The scan, the flips and the FTS deletes run in ONE
+   *  sync transaction (the per-scope cap's atomicity rule): the sweep commits
+   *  whole or not at all. Idempotent — swept rows are no longer active, so a
+   *  second call answers 0. Under `dryRun` nothing flips. */
+  async sweep(_scopeKey: string, dryRun: boolean): Promise<{ swept: number; ids: string[] }> {
+    return this.ctx.storage.transactionSync(() => {
+      const ids = this.sql
+        .exec<Row>(`SELECT * FROM records WHERE status = 'active' AND kind = 'fact'`)
+        .toArray()
+        .filter((row) => rejectionMarkers(row.text).length > 0)
+        .map((row) => row.id);
+      if (!dryRun) {
+        for (const id of ids) {
+          // Soft delete for the record row, hard delete for its FTS entry —
+          // the forget/supersede/evict hygiene rule (§15).
+          this.sql.exec(`UPDATE records SET status = 'swept' WHERE id = ? AND status = 'active'`, id);
+          this.sql.exec(`DELETE FROM records_fts WHERE id = ?`, id);
+        }
+      }
+      return { swept: ids.length, ids };
+    });
+  }
 }
 
 /** Build the FTS5 MATCH expression for a query: each engine token (`[a-z0-9]+`
@@ -1450,10 +1518,15 @@ type HeartbeatAnswer = FenceResult & { stop?: StopMode | null; phase?: LivePhase
 
 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
@@ -2028,8 +2101,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) {
@@ -2038,9 +2113,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);
@@ -2303,15 +2383,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
@@ -2335,7 +2421,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;
@@ -2352,11 +2438,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(
@@ -2436,10 +2540,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;
@@ -2889,6 +3008,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 };
@@ -2904,16 +3034,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>;
@@ -3121,8 +3259,10 @@ function parseLimit(v: unknown): Validated<number> {
   return { ok: true, value: v };
 }
 
-/** `POST /list {scopeKey, limit, query?}`. */
-function parseList(body: unknown): Validated<{ scopeKey: string; limit: number; query?: string }> {
+/** `POST /list {scopeKey, limit, query?, kind?}`. */
+function parseList(
+  body: unknown,
+): Validated<{ scopeKey: string; limit: number; query?: string; kind?: MemoryRecord["kind"] }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
   const b = body as Record<string, unknown>;
   const scope = parseScopeKey(b.scopeKey);
@@ -3133,12 +3273,29 @@ function parseList(body: unknown): Validated<{ scopeKey: string; limit: number;
     if (typeof b.query !== "string") return invalid("query must be a string");
     if (b.query.length > MAX_QUERY_CHARS) return invalid(`query must be at most ${MAX_QUERY_CHARS} characters`);
   }
+  if (b.kind !== undefined && b.kind !== "fact" && b.kind !== "summary")
+    return invalid('kind must be "fact" or "summary"');
   return {
     ok: true,
-    value: { scopeKey: scope.value, limit: limit.value, ...(typeof b.query === "string" ? { query: b.query } : {}) },
+    value: {
+      scopeKey: scope.value,
+      limit: limit.value,
+      ...(typeof b.query === "string" ? { query: b.query } : {}),
+      ...(b.kind === "fact" || b.kind === "summary" ? { kind: b.kind } : {}),
+    },
   };
 }
 
+/** `POST /sweep {scopeKey, dryRun?}`. */
+function parseSweep(body: unknown): Validated<{ scopeKey: string; dryRun: boolean }> {
+  if (!isJsonObject(body)) return invalid("body must be a JSON object");
+  const b = body;
+  const scope = parseScopeKey(b.scopeKey);
+  if (!scope.ok) return scope;
+  if (b.dryRun !== undefined && typeof b.dryRun !== "boolean") return invalid("dryRun must be a boolean");
+  return { ok: true, value: { scopeKey: scope.value, dryRun: b.dryRun === true } };
+}
+
 /** `POST /forget {scopeKey, id}`: the id is an opaque key, same caps as scopeKey. */
 function parseForget(body: unknown): Validated<{ scopeKey: string; id: string }> {
   if (typeof body !== "object" || body === null) return invalid("body must be a JSON object");
@@ -3205,6 +3362,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 };
 }
 
@@ -4248,7 +4410,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}`}`,
     );
@@ -4265,8 +4427,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)`,
     );
@@ -4329,6 +4493,7 @@ const ROUTES = new Set([
   "/write",
   "/list",
   "/forget",
+  "/sweep",
   "/schedules/record",
   "/schedules/latest",
   "/runs/put",
@@ -4349,11 +4514,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"];
+  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);
@@ -4422,8 +4597,8 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
   if (url.pathname === "/list") {
     const parsed = parseList(body);
     if (!parsed.ok) return json({ error: parsed.error }, 400);
-    const { scopeKey, limit, query } = parsed.value;
-    const records = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).list(scopeKey, limit, query);
+    const { scopeKey, limit, query, kind } = parsed.value;
+    const records = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).list(scopeKey, limit, query, kind);
     console.log(`[list] ${scopeKey} -> ${records.length} records`);
     return json({ records });
   }
@@ -4436,6 +4611,16 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
     console.log(`[forget] ${scopeKey} ${id} -> ${forgotten}`);
     return json({ ok: true, forgotten });
   }
+  if (url.pathname === "/sweep") {
+    const parsed = parseSweep(body);
+    if (!parsed.ok) return json({ error: parsed.error }, 400);
+    const { scopeKey, dryRun } = parsed.value;
+    const out = await env.MEMORY.get(env.MEMORY.idFromName(scopeKey)).sweep(scopeKey, dryRun);
+    // Observability: scope + count only (ids carry no record text; they ride
+    // the dryRun answer, not the log).
+    console.log(`[sweep] ${scopeKey} -> ${out.swept}${dryRun ? " (dry run)" : ""}`);
+    return json({ ok: true, swept: out.swept, ...(dryRun ? { ids: out.ids } : {}) });
+  }
 
   const parsed = parseWrite(body);
   if (!parsed.ok) return json({ error: parsed.error }, 400);

package/dist/assets/deploy/cloudflare-memory/wrangler.template.jsonc

@@ -66,6 +66,18 @@
       "script_name": "{{bot.script}}"
     }
   ],
+  // {{#if metrics}}
+  // The run-metrics dataset (docs/reference/specs/run-metrics.md): where RunHistoryDO
+  // writes a turned-final run's point, bound only when the deployment profile names a
+  // dataset (`metrics.dataset`) — nothing is created ahead of the deploy; the platform
+  // creates the dataset on first write. Without it the Worker deploys without the
+  // binding and writes no points.
+  "analytics_engine_datasets": [{ "binding": "RUN_METRICS", "dataset": "{{metrics.dataset}}" }],
+  // The dataset's name beside its binding (rendered together): /healthz `features`
+  // says `runMetrics:<dataset>` from it, so the bot's boot probe can compare the
+  // name its own config carries with the one this deploy bound.
+  "vars": { "RUN_METRICS_DATASET": "{{metrics.dataset}}" },
+  // {{/if}}
   // SQLite-backed DOs (durable across restarts — AGENTS.md invariant 6).
   "migrations": [
     { "tag": "v1", "new_sqlite_classes": ["MemoryDO"] },