@coreplane/switchboard 0.0.0 → 1.18.0

package/dist/assets/src/core/memory/scorer.ts

@@ -0,0 +1,147 @@
+import type { MemoryRecord } from "./types.js";
+
+// Pure retrieval scoring, budgeting, and rendering. No I/O, no clock of its own
+// (the caller passes `now`) — so every branch is unit-testable in isolation.
+// MVP score = α·keywordMatch + β·recency (Generative-Agents-style, minus the
+// embedding-relevance term): keyword+recency is a legitimate MVP; vectors are an
+// upgrade behind the unchanged seam ("do you even need vectors at MVP?").
+
+/** Relative weights of the two scoring terms. */
+export interface ScoreWeights {
+  keyword: number;
+  recency: number;
+}
+
+/** α (keyword) dominates; β (recency) breaks ties and sinks stale records. */
+export const DEFAULT_WEIGHTS: ScoreWeights = { keyword: 0.7, recency: 0.3 };
+
+/** Exponential-decay time constant for the recency term (~1 week). A record
+ *  one τ old scores 1/e on recency; the decay makes stale facts sink without a
+ *  sweeper job (decay lives in the score). */
+export const RECENCY_TAU_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Default read budget: at most 8 records / ~800 tokens injected, regardless of
+ *  store size — context never bloats. */
+export const DEFAULT_MEMORY_LIMIT = 8;
+export const DEFAULT_MEMORY_TOKENS = 800;
+
+export interface MemoryBudget {
+  maxRecords: number;
+  maxTokens: number;
+}
+
+/** Split text into lowercased alphanumeric tokens for keyword matching. */
+export function tokenize(text: string): string[] {
+  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+
+/** Fraction of the query's word-tokens that appear as a word in the record (its
+ *  keyword set or its text). 0 when the query has no tokens. Whole-token
+ *  matching, not raw substring: substring matching lets a one-letter query token
+ *  ("a") match inside an unrelated word ("comm-a-nd") and pollute retrieval. */
+export function keywordMatch(record: MemoryRecord, query: string | readonly string[]): number {
+  const queryTokens = typeof query === "string" ? tokenize(query) : query;
+  if (queryTokens.length === 0) return 0;
+  const recordTokens = new Set([...tokenize(record.keywords.join(" ")), ...tokenize(record.text)]);
+  let hits = 0;
+  for (const token of queryTokens) {
+    if (recordTokens.has(token)) hits++;
+  }
+  return hits / queryTokens.length;
+}
+
+/** Exponential recency decay over `lastUsedAt ?? createdAt`, in (0, 1]. */
+export function recencyScore(record: MemoryRecord, now: number, tau: number = RECENCY_TAU_MS): number {
+  const ts = record.lastUsedAt ?? record.createdAt;
+  const age = Math.max(0, now - ts);
+  return Math.exp(-age / tau);
+}
+
+/** score = α·keywordMatch + β·recency. Pure; the caller supplies `now`. */
+export function scoreRecord(
+  record: MemoryRecord,
+  query: string | readonly string[],
+  now: number,
+  weights: ScoreWeights = DEFAULT_WEIGHTS,
+  tau: number = RECENCY_TAU_MS,
+): number {
+  return weights.keyword * keywordMatch(record, query) + weights.recency * recencyScore(record, now, tau);
+}
+
+/** Rough token estimate (~4 chars/token) for the budget cap. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Apply the hard budget: at most `maxRecords`, and stop before the running
+ *  token estimate would exceed `maxTokens` (the first record is always kept so a
+ *  single large record is never silently dropped). Input is assumed already
+ *  ranked; order is preserved. Each record is costed at its *rendered* bullet
+ *  (`renderMemoryBullet`) — sanitized/escaped text plus the `- … (source: …)`
+ *  boilerplate — not the raw `record.text`. `sanitizeMemoryField` can lengthen
+ *  text (`<`→`&lt;` is +3 chars each), so budgeting the raw text would
+ *  under-count and let the rendered block exceed `maxTokens`; costing the
+ *  rendered bullet keeps the estimate an upper bound on the injected records. */
+export function applyBudget(records: MemoryRecord[], budget: MemoryBudget): MemoryRecord[] {
+  const out: MemoryRecord[] = [];
+  let tokens = 0;
+  for (const record of records) {
+    if (out.length >= budget.maxRecords) break;
+    const cost = estimateTokens(renderMemoryBullet(record));
+    if (out.length > 0 && tokens + cost > budget.maxTokens) break;
+    out.push(record);
+    tokens += cost;
+  }
+  return out;
+}
+
+/** The exact prefix line of the injected context block. */
+export function memoryBlockPrefix(resource: string): string {
+  return `Background memory for ${resource} (may be outdated — verify before acting):`;
+}
+
+/** Neutralize a memory record field before it is spliced into the system
+ *  prompt: strip control characters and any newline/line-separator (so a
+ *  record can never inject extra lines or fake role turns), collapse the
+ *  resulting whitespace, then escape `&`\u2192`&amp;` FIRST, then `<`\u2192`&lt;` and
+ *  `>`\u2192`&gt;`. Escaping `&` before the angle brackets keeps the escaping
+ *  complete and unambiguous: a record's literal `&lt;` becomes `&amp;lt;`, so it
+ *  no longer renders identically to an escaped `<`. Escaping angle brackets means
+ *  a record field can contain no literal `<` or `>`, so it can never forge the
+ *  `<background_memory>`/`</background_memory>` fence delimiter \u2014 or any other
+ *  tag \u2014 inline within a bullet. This is the anti-poisoning containment for the
+ *  memory block (see docs/reference/specs/memory.md). */
+export function sanitizeMemoryField(s: string): string {
+  return (
+    s
+      // eslint-disable-next-line no-control-regex -- control characters are exactly what this strips
+      .replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+  );
+}
+
+/** The exact rendered bullet for one record — the single source of truth shared
+ *  by `renderMemoryBlock` (what is injected) and `applyBudget` (what is costed),
+ *  so the budget estimate can never diverge from what is actually rendered. Both
+ *  record fields pass through `sanitizeMemoryField` (control/newline strip +
+ *  `&`/`<`/`>` escape). */
+function renderMemoryBullet(record: MemoryRecord): string {
+  return `- ${sanitizeMemoryField(record.text)} (source: ${sanitizeMemoryField(record.sourceThreadKey)})`;
+}
+
+/** Render the dedicated advisory context block: the exact prefix line, then one
+ *  bullet per record with its provenance, fenced by an unambiguous
+ *  `<background_memory>` delimiter. Framed as advisory ("may be outdated —
+ *  verify") — memory is context, never instructions. The fence lines are
+ *  written here literally; the record-derived fields pass through
+ *  `sanitizeMemoryField` (control/newline strip + `&`/`<`/`>` escape), so a
+ *  record can neither inject extra lines / fake role turns nor forge the fence
+ *  delimiter — or any tag — from within a bullet (anti-poisoning). */
+export function renderMemoryBlock(resource: string, records: MemoryRecord[]): string {
+  const bullets = records.map(renderMemoryBullet);
+  return [memoryBlockPrefix(resource), "<background_memory>", ...bullets, "</background_memory>"].join("\n");
+}

package/dist/assets/src/core/memory/types.ts

@@ -0,0 +1,120 @@
+// Cross-session self-learning memory. The seam: distilled records scoped to a
+// resource, retrieved by keyword+recency and injected as a dedicated advisory
+// context block before the model turn. The READ path sits behind a flag
+// (default off → zero behavior change); the write/reflection path and the
+// durable Worker store hang off the same interface. See docs/reference/specs/memory.md and
+// docs/decisions/0017-memory-off-by-default.md.
+
+/** A distilled, self-contained memory record. Never a raw transcript — those
+ *  live in thread history; duplicating them defeats the token win. Every record
+ *  keeps provenance (`sourceThreadKey`/`sourceRunId`) so a distilled fact can be
+ *  re-grounded in the run that produced it. */
+import type { TraceOptions } from "../trace/types.js";
+
+export interface MemoryRecord {
+  /** Internal id, namespaced per AGENTS.md invariant 4 (`mem:<scopeKey>:<n>`). */
+  id: string;
+  /** The resource this record belongs to: `org:<organization>` (the config's organization) or `user:slack:U…`. */
+  scopeKey: string;
+  /** Semantic fact vs. episodic thread summary. */
+  kind: "fact" | "summary";
+  /** Self-contained natural-language statement. */
+  text: string;
+  /** Lowercased keywords for keyword/FTS retrieval at MVP (no embeddings). */
+  keywords: string[];
+  /** Provenance: the thread this was distilled from (`slack:C…:<ts>`). */
+  sourceThreadKey: string;
+  /** Provenance: ties to the runRegistry / live-view page, when known. */
+  sourceRunId?: string;
+  createdAt: number;
+  /** Bumped on retrieval → drives the recency term and decay. */
+  lastUsedAt?: number;
+  useCount: number;
+  /** Extractor's importance/confidence (0–1); folded into scoring later. */
+  confidence?: number;
+  /** id this record replaces (conflict resolution / supersession). */
+  supersedes?: string;
+  /** `evicted`: dropped by the per-scope cap (least recently used);
+   *  `superseded`: replaced by a newer record; `forgotten`: removed by a human
+   *  via `memory forget`. Both are soft deletes — the row stays for
+   *  provenance but is invisible to retrieval, list, and dedup. */
+  status: "active" | "superseded" | "forgotten" | "evicted";
+}
+
+/** What the reflection extractor emits. The store assigns id/timestamps/useCount/
+ *  status on write, so a candidate carries only the distilled content and its
+ *  provenance. */
+export interface MemoryCandidate {
+  kind: "fact" | "summary";
+  text: string;
+  keywords?: string[];
+  sourceThreadKey: string;
+  sourceRunId?: string;
+  confidence?: number;
+  supersedes?: string;
+}
+
+/** A retrieval request: which resource, what to match, how many at most. */
+export interface MemoryQuery {
+  scopeKey: string;
+  query: string;
+  limit: number;
+}
+
+/** The boundary the core sees (AGENTS.md invariant 2: the dispatcher depends on
+ *  this interface, never a concrete store). Three implementations:
+ *  `NullMemoryStore` (disabled default), `InMemoryMemoryStore` (tests/dev) and
+ *  the durable `WorkerMemoryStore`. */
+export interface MemoryStore {
+  /** Scope-partitioned retrieval, ranked by the pure scorer, oldest-irrelevant
+   *  dropped. Returns [] when nothing matches. */
+  retrieve(q: MemoryQuery, trace?: TraceOptions): Promise<MemoryRecord[]>;
+  /** Persist distilled candidates. Dedup (identical normalized text → bump
+   *  `useCount`) and supersede (`supersedes` id → old record soft-deleted) live
+   *  inside the store. Driven by the post-run reflection pass (reflection.ts). */
+  write(scopeKey: string, records: MemoryCandidate[]): Promise<void>;
+  /** Human view: a scope's ACTIVE records, newest first, at most
+   *  `limit`. Unlike `retrieve` this never bumps usage. */
+  /** `query`: when given, only records that a query token hits
+   *  (whole-token, text or keywords) are listed — the filter narrows, it
+   *  never ranks or bumps usage. */
+  list(scopeKey: string, limit: number, query?: string): Promise<MemoryRecord[]>;
+  /** Human control: soft-delete one ACTIVE record of this scope
+   *  (`status: "forgotten"`, row kept for provenance). Resolves true when a
+   *  record was forgotten, false when the id names nothing active in this
+   *  scope — a foreign-scope id can never be forgotten through another scope. */
+  forget(scopeKey: string, id: string): Promise<boolean>;
+}
+
+/** The resources memory is scoped to. `org` is the shared resource every
+ *  request reads; `user` is the requesting person's own records,
+ *  read and written only for that person; `repo` (the run's bound repository)
+ *  and `channel` (the message's channel) are shared by everyone who runs there
+ *  in the same place. Tighter scope prevents cross-context poisoning (mirrors
+ *  Claude's compartmentalization). */
+export type MemoryScope = "org" | "user" | "repo" | "channel";
+
+/** The `memory` config section (all optional; default OFF). */
+export interface MemoryConfig {
+  /** Master switch. Default false → `NullMemoryStore` → zero behavior change. */
+  enabled?: boolean;
+  /** Max records retrieved/injected per request. Default 8. */
+  limit?: number;
+  /** Hard token budget for the injected block. Default ~800. */
+  maxTokens?: number;
+  /** Per-scope cap on ACTIVE records. A write that would leave a scope
+   *  over the cap evicts the least recently used records (soft delete, status
+   *  `evicted`) down to it, inside the same write. Default 500. */
+  maxRecordsPerScope?: number;
+  /** `<provider>/<model>` ref for the post-run reflection (write path) — a cheap
+   *  tier. Absent → the run's own resolved model. Never hardcoded (invariant 7). */
+  model?: string;
+  /** The durable store: the Memory Worker (deploy/cloudflare-memory/). Absent →
+   *  an in-process store that a restart loses (dev only; startup warns). */
+  worker?: {
+    /** Base URL, e.g. https://switchboard-memory.example.com */
+    baseUrl: string;
+    /** Env var holding the bearer secret. Default MEMORY_TOKEN. */
+    tokenEnv?: string;
+  };
+}

package/dist/assets/src/core/normalizeSpans.ts

@@ -0,0 +1,299 @@
+import { isSpanRecord, type RunEvent, type SpanEndEvent, type SpanStartEvent } from "./runEvents.js";
+import type { LossInterval } from "./trace/partition.js";
+import type { SpanRecord } from "./trace/types.js";
+import type { SpanAttrs } from "./trace/attrs.js";
+
+// The one Adapter between a run stream and the span set the partition, the
+// analyzer and the timeline read (docs/reference/specs/tracing.md). A stream is
+// span schema (`SPAN_SCHEMA`): spans carry the timing. A content pair whose
+// `tool.*` twin was dropped by the record budget still deserves a span, so
+// `normalizeSpans` adds a synthesized span for every stamped, `callId`-keyed
+// pair that lacks one and never touches a pair that has one — it is idempotent
+// and the identity on a complete stream. A record below `SPAN_SCHEMA` is never
+// normalized: its readers show no timing (docs/reference/migrations.md).
+// `spansFromEvents` pairs the records into `SpanRecord`s and `lossesFromStream`
+// derives the loss intervals from the `seq` gaps, the `spans_dropped` notes and
+// the live transport's elided ranges.
+
+/** The stream schema from which spans are the timing record. A record whose
+ *  `schema` is absent or below it carries no timing. */
+export const SPAN_SCHEMA = 2;
+
+/** A synthesized span's id: `synth:<callId>` for a call whose id is a plain
+ *  token, else `synth:<content index>`. */
+function synthId(callId: string, index: number): string {
+  return /^[A-Za-z0-9_-]{1,64}$/.test(callId) ? `synth:${callId}` : `synth:${index}`;
+}
+
+interface OpenAgent {
+  spanId: string;
+  startedAt: number;
+  endedAt: number;
+}
+
+/** The `run.agent` spans that survive on the stream, as intervals — a
+ *  synthesized span's parent is the innermost one containing it. */
+function agentSpans(events: readonly RunEvent[]): OpenAgent[] {
+  const out: OpenAgent[] = [];
+  for (const e of events) {
+    if (e.type === "span_end" && e.name === "run.agent") {
+      out.push({ spanId: e.spanId, startedAt: e.startedAt, endedAt: e.startedAt + e.durationMs });
+    }
+  }
+  return out;
+}
+
+function parentFor(agents: readonly OpenAgent[], at: number): string | undefined {
+  let best: OpenAgent | undefined;
+  for (const a of agents) {
+    if (a.startedAt <= at && at <= a.endedAt && (!best || a.endedAt - a.startedAt < best.endedAt - best.startedAt))
+      best = a;
+  }
+  return best?.spanId;
+}
+
+/**
+ * Synthesize the `tool.*` spans a stream is missing: one per stamped
+ * `tool_call` with a `callId` and no twin, closed by the `tool_result` with the
+ * same `callId`. Returns a new array; the input is never mutated. The
+ * synthesized `span_start` is placed right before the call, the `span_end`
+ * right after the result, so a per-event fold sees them where the emitter
+ * would have put them. A call with no `callId` or no `at` gets no span: there
+ * is nothing to key or to time it by.
+ */
+export function normalizeSpans(events: readonly RunEvent[]): RunEvent[] {
+  const agents = agentSpans(events);
+
+  // What already has a twin.
+  const toolSpanCallIds = new Set<string>();
+  for (const e of events) {
+    if (!isSpanRecord(e)) continue;
+    const attrs = (e.attrs ?? {}) as Record<string, unknown>;
+    if (e.name.startsWith("tool.") && typeof attrs.callId === "string") toolSpanCallIds.add(attrs.callId);
+  }
+
+  const out: RunEvent[] = [];
+  // A call's synthesized start, keyed by callId, until its result closes it.
+  const openCalls = new Map<string, { spanId: string; startedAt: number }>();
+
+  events.forEach((e, index) => {
+    switch (e.type) {
+      case "tool_call": {
+        const callId = e.callId;
+        if (callId === undefined || e.at === undefined || toolSpanCallIds.has(callId)) {
+          out.push(e);
+          return;
+        }
+        const spanId = synthId(callId, index);
+        out.push(spanStart(spanId, `tool.${e.tool}`, e.at, parentFor(agents, e.at), { callId }), e);
+        openCalls.set(callId, { spanId, startedAt: e.at });
+        return;
+      }
+      case "tool_result": {
+        out.push(e);
+        if (e.callId === undefined) return;
+        const open = openCalls.get(e.callId);
+        if (!open) return; // a result whose call has a real twin (or no call at all): nothing to close
+        openCalls.delete(e.callId);
+        const endedAt = e.at ?? open.startedAt;
+        const attrs: Record<string, string | number | boolean> = { ok: e.ok, callId: e.callId };
+        if (e.exitCode !== undefined) attrs.exitCode = e.exitCode;
+        if (e.infra) attrs.infra = true;
+        out.push(
+          spanEnd(
+            open.spanId,
+            `tool.${e.tool}`,
+            open.startedAt,
+            Math.max(0, endedAt - open.startedAt),
+            parentFor(agents, open.startedAt),
+            attrs,
+            e.ok ? "ok" : "error",
+          ),
+        );
+        return;
+      }
+      default:
+        out.push(e);
+    }
+  });
+  return out;
+}
+
+function spanStart(
+  spanId: string,
+  name: string,
+  at: number,
+  parentSpanId?: string,
+  attrs?: Record<string, string | number | boolean>,
+): SpanStartEvent {
+  return {
+    type: "span_start",
+    spanId,
+    ...(parentSpanId !== undefined ? { parentSpanId } : {}),
+    name,
+    ...(attrs ? { attrs } : {}),
+    at,
+  };
+}
+
+function spanEnd(
+  spanId: string,
+  name: string,
+  startedAt: number,
+  durationMs: number,
+  parentSpanId?: string,
+  attrs?: Record<string, string | number | boolean>,
+  status: "ok" | "error" = "ok",
+): SpanEndEvent {
+  return {
+    type: "span_end",
+    spanId,
+    ...(parentSpanId !== undefined ? { parentSpanId } : {}),
+    name,
+    startedAt,
+    durationMs,
+    status,
+    ...(attrs ? { attrs } : {}),
+    at: startedAt + durationMs,
+  };
+}
+
+/** Pair the span records of a (normalized) stream into `SpanRecord`s. A
+ *  `span_start` with no `span_end` is an open span (no `endedAt`); a `span_end`
+ *  with no start is complete on its own. `traceId` is the stream's — the run id
+ *  the caller names, since a stream belongs to one run. */
+export function spansFromEvents(events: readonly RunEvent[], traceId: string): SpanRecord[] {
+  const byId = new Map<string, SpanRecord>();
+  for (const e of events) if (isSpanRecord(e)) foldSpanRecord(byId, e, traceId);
+  return [...byId.values()];
+}
+
+/** Fold one span record into the set: a start opens the record (unless an end
+ *  already made it), an end completes it, keeping a start's parent and attrs.
+ *  The per-frame half of `spansFromEvents`, for a page that folds live. */
+export function foldSpanRecord(byId: Map<string, SpanRecord>, e: SpanStartEvent | SpanEndEvent, traceId: string): void {
+  const prior = byId.get(e.spanId);
+  if (e.type === "span_start") {
+    if (prior) return; // an end already made the record
+    byId.set(e.spanId, {
+      traceId,
+      spanId: e.spanId,
+      ...(e.parentSpanId !== undefined ? { parentSpanId: e.parentSpanId } : {}),
+      name: e.name,
+      startedAt: e.at ?? 0,
+      attrs: (e.attrs ?? {}) as SpanAttrs,
+    });
+    return;
+  }
+  byId.set(e.spanId, {
+    traceId,
+    spanId: e.spanId,
+    ...(e.parentSpanId !== undefined
+      ? { parentSpanId: e.parentSpanId }
+      : prior?.parentSpanId !== undefined
+        ? { parentSpanId: prior.parentSpanId }
+        : {}),
+    name: e.name,
+    startedAt: e.startedAt,
+    endedAt: e.startedAt + e.durationMs,
+    durationMs: e.durationMs,
+    status: e.status,
+    ...(e.error !== undefined ? { errorMessage: e.error } : {}),
+    attrs: { ...(prior?.attrs ?? {}), ...((e.attrs ?? {}) as SpanAttrs) },
+  });
+}
+
+export interface ElidedRange {
+  fromSeq: number;
+  toSeq: number;
+}
+
+/**
+ * The loss intervals of a stream, in stream time: `[windowStart, at(first)]`
+ * when the first stored `seq` is above 1 (the registry trimmed the head —
+ * always `lost`), `[min(at(prev), at(next)), max(…)]` for each interior `seq`
+ * gap (`elided` when the gap lies inside a range the live transport reported,
+ * `lost` otherwise), and every `spans_dropped` note's own `from`/`to` (`lost`).
+ * `replay_note` markers are never consulted. Events without `at` contribute no
+ * interval.
+ */
+export function lossesFromStream(
+  events: readonly RunEvent[],
+  opts: { windowStart?: number; elided?: readonly ElidedRange[] } = {},
+): LossInterval[] {
+  const tracker = createLossTracker();
+  for (const e of events) tracker.push(e);
+  return tracker.losses(opts);
+}
+
+export interface LossTracker {
+  /** One more event of the stream, in order. */
+  push(event: RunEvent): void;
+  /** The loss intervals so far, for the window's start and the ranges the live
+   *  transport has reported by now. O(gaps), never a rescan of the stream. */
+  losses(opts?: { windowStart?: number; elided?: readonly ElidedRange[] }): LossInterval[];
+}
+
+/** The incremental form of `lossesFromStream`: a live page pushes each frame
+ *  as it arrives and reads the intervals per tick without holding the stream.
+ *  Kept per event: the first event's `seq` and stamp (the head loss), each
+ *  interior `seq` gap with the stamps around it (its kind decided at read time,
+ *  since the `replay_elided` range that covers a gap can arrive after it), and
+ *  every `spans_dropped` note's own interval — in stream order. */
+export function createLossTracker(): LossTracker {
+  let first: { seq: number; at: number | undefined } | undefined;
+  let prev: { seq: number | undefined; at: number | undefined } | undefined;
+  const entries: Array<
+    | { kind: "gap"; fromSeq: number; toSeq: number; from: number; to: number }
+    | { kind: "note"; from: number; to: number }
+  > = [];
+  return {
+    push(e) {
+      if (!first) {
+        first = { seq: e.seq ?? 1, at: e.at };
+      } else if (prev && e.seq !== undefined && prev.seq !== undefined && e.seq > prev.seq + 1) {
+        if (prev.at !== undefined && e.at !== undefined) {
+          entries.push({
+            kind: "gap",
+            fromSeq: prev.seq + 1,
+            toSeq: e.seq - 1,
+            from: Math.min(prev.at, e.at),
+            to: Math.max(prev.at, e.at),
+          });
+        }
+      }
+      if (
+        e.type === "run_note" &&
+        e.kind === "spans_dropped" &&
+        e.from !== undefined &&
+        e.to !== undefined &&
+        e.to >= e.from
+      ) {
+        entries.push({ kind: "note", from: e.from, to: e.to });
+      }
+      prev = { seq: e.seq, at: e.at };
+    },
+    losses(opts = {}) {
+      const elided = opts.elided ?? [];
+      const inElided = (from: number, to: number) => elided.some((r) => r.fromSeq <= from && to <= r.toSeq);
+      const out: LossInterval[] = [];
+      if (
+        first &&
+        first.seq > 1 &&
+        opts.windowStart !== undefined &&
+        first.at !== undefined &&
+        first.at > opts.windowStart
+      ) {
+        out.push({ from: opts.windowStart, to: first.at, kind: "lost" });
+      }
+      for (const g of entries) {
+        out.push(
+          g.kind === "note"
+            ? { from: g.from, to: g.to, kind: "lost" }
+            : { from: g.from, to: g.to, kind: inElided(g.fromSeq, g.toSeq) ? "elided" : "lost" },
+        );
+      }
+      return out;
+    },
+  };
+}

package/dist/assets/src/core/prDescriptionTypes.ts

@@ -0,0 +1,54 @@
+// The PrDescription SHAPE, dependency-free. runEvents.ts (the node-free
+// run-event contract compiled by the memory Worker's and web app's own
+// tsconfigs) carries a PrDescription on the `pr_description` event, so the
+// type must be importable without dragging zod into those compile graphs —
+// the schema and validation live in prDescription.ts, which imports these
+// types and enforces (via its annotated parse return) that the zod output
+// stays assignable to them. Add a field here first, then to the schema.
+
+/** A hunk the reader is pointed at: a path + inclusive 1-based line range in
+ *  the PR head. The sha is NOT stored here — it is supplied at render time. */
+export interface TourAnchor {
+  path: string;
+  from: number;
+  to: number;
+}
+
+/** One Tour step, reader-first: heading (what the change is), the explanation,
+ *  an optional "look for" pointer, then the code. */
+export interface TourStep {
+  title: string;
+  description: string;
+  lookFor?: string;
+  anchor: TourAnchor;
+}
+
+/** A Tour anchor with the sha its permalink was rendered at — what a reader
+ *  gets back from a rendered body (or from a submitted object at the head it
+ *  was rendered for), so a surface can tell whether the anchors are at the
+ *  head it is looking at. */
+export interface RenderedTourAnchor extends TourAnchor {
+  sha: string;
+}
+
+/** A Tour step whose anchor carries its render sha. Assignable to `TourStep`. */
+export interface RenderedTourStep extends TourStep {
+  anchor: RenderedTourAnchor;
+}
+
+export interface PrDescription {
+  /** The PR title's single source. Metadata for the PR's own title field —
+   *  never rendered into the body (GitHub shows the title itself). */
+  title: string;
+  tldr: string;
+  whatWhy: string;
+  tour: TourStep[];
+  /** Every touched file the Tour steps did not cover, one line each. */
+  remaining: { path: string; note: string }[];
+  decisions: { title: string; rationale: string }[];
+  risks: string;
+  validation: {
+    summary?: string;
+    criteria: { criterion: string; proof: string }[];
+  };
+}