@coreplane/switchboard 0.0.0 → 1.18.1

package/dist/assets/src/core/authz/resource.ts

@@ -0,0 +1,147 @@
+// What a condition may read off a resource.
+//
+// Every condition in the closed vocabulary relates the actor to ONE resource
+// attribute: `member-of` → channelId, `is-self` → userId, `owner-of` → repo,
+// a `has-grant` placeholder → the named attribute. `TARGET_ATTRIBUTES` states
+// which attributes each resource target (type, or type/kind for the kinded
+// resources) can carry, so `validatePolicy` can refuse a row that reads an
+// attribute its resource never has — at module load, not at request time.
+
+import type { ChannelVisibility, KindOf, Resource, ResourceType } from "./types.js";
+
+export interface ResourceAttributes {
+  readonly channelId?: string;
+  readonly userId?: string;
+  /** `owner/name`. */
+  readonly repo?: string;
+  /** Agent name. */
+  readonly name?: string;
+  /** Visibility of the channel the resource originated in; absent → `unknown` (fail-closed).
+   *  Read by the `originVisibility` row selector. */
+  readonly visibility: ChannelVisibility;
+  /** Visibility of the channel the resource IS or LIVES IN — a `run`'s stamped
+   *  `channelVisibility`, a `channel`'s own — read by `member-of`'s public half.
+   *  Absent on every other target: a memory scope's origin visibility says
+   *  where a fact came from, never that its scope is public. */
+  readonly channelVisibility?: ChannelVisibility;
+}
+
+export type AttributeName = Exclude<keyof ResourceAttributes, "visibility">;
+
+/** The kinds each kinded resource type takes. Types absent here are not kinded. */
+export const RESOURCE_KINDS: { readonly [T in ResourceType]?: readonly KindOf<T>[] } = {
+  "memory-scope": ["org", "user", "repo", "channel"],
+  "config-scope": ["channel", "user", "org"],
+};
+
+/** A resource type, or `type/kind` for the kinded ones — the unit a rule row targets. */
+export type Target =
+  | Exclude<ResourceType, "memory-scope" | "config-scope">
+  | `memory-scope/${"org" | "user" | "repo" | "channel"}`
+  | `config-scope/${"channel" | "user" | "org"}`;
+
+export const TARGET_ATTRIBUTES: Readonly<Record<Target, readonly AttributeName[]>> = {
+  run: ["channelId", "userId", "repo"],
+  channel: ["channelId"],
+  "memory-scope/org": [],
+  "memory-scope/user": ["userId"],
+  "memory-scope/channel": ["channelId"],
+  "memory-scope/repo": ["repo"],
+  repo: ["repo"],
+  "config-scope/channel": ["channelId"],
+  "config-scope/user": ["userId"],
+  "config-scope/org": [],
+  agent: ["name"],
+  command: [],
+};
+
+export const RESOURCE_TYPES: readonly ResourceType[] = [
+  "run",
+  "channel",
+  "memory-scope",
+  "repo",
+  "config-scope",
+  "agent",
+  "command",
+];
+
+export const CHANNEL_VISIBILITIES: readonly ChannelVisibility[] = ["public", "private", "dm", "machine", "unknown"];
+
+/** The target a rule row names; `undefined` when the (type, kind) pair is not a valid target. */
+export function targetOf(type: string, kind?: string): Target | undefined {
+  const kinds: readonly string[] | undefined = RESOURCE_KINDS[type as ResourceType];
+  if (kinds) {
+    if (kind === undefined || !kinds.includes(kind)) return undefined;
+    return `${type}/${kind}` as Target;
+  }
+  if (kind !== undefined) return undefined;
+  return type in TARGET_ATTRIBUTES ? (type as Target) : undefined;
+}
+
+export function targetOfResource(resource: Resource): Target {
+  const kind = "kind" in resource ? resource.kind : undefined;
+  const target = targetOf(resource.type, kind);
+  if (!target) throw new TypeError(`authz: no target for resource type ${resource.type}`);
+  return target;
+}
+
+/** Strip `<prefix>:` from a memory-scope key; `undefined` when the key is not of that prefix
+ *  (the condition then fails — a malformed key never widens access). */
+function scopeId(key: string, prefix: "user" | "channel" | "repo"): string | undefined {
+  const head = `${prefix}:`;
+  return key.startsWith(head) && key.length > head.length ? key.slice(head.length) : undefined;
+}
+
+export function attributesOf(resource: Resource): ResourceAttributes {
+  switch (resource.type) {
+    case "run": {
+      const visibility = resource.channelVisibility ?? "unknown";
+      return {
+        channelId: resource.channelId,
+        userId: resource.userId,
+        ...(resource.repo !== undefined ? { repo: resource.repo } : {}),
+        visibility,
+        channelVisibility: visibility,
+      };
+    }
+    case "channel":
+      return { channelId: resource.id, visibility: resource.visibility, channelVisibility: resource.visibility };
+    case "memory-scope": {
+      const visibility = resource.originChannelVisibility ?? "unknown";
+      switch (resource.kind) {
+        case "org":
+          return { visibility };
+        case "user": {
+          const userId = scopeId(resource.key, "user");
+          return userId === undefined ? { visibility } : { userId, visibility };
+        }
+        case "channel": {
+          const channelId = scopeId(resource.key, "channel");
+          return channelId === undefined ? { visibility } : { channelId, visibility };
+        }
+        case "repo": {
+          const repo = scopeId(resource.key, "repo");
+          return repo === undefined ? { visibility } : { repo, visibility };
+        }
+      }
+      break;
+    }
+    case "repo":
+      return { repo: `${resource.owner}/${resource.name}`, visibility: "unknown" };
+    case "config-scope":
+      switch (resource.kind) {
+        case "channel":
+          return { channelId: resource.id, visibility: "unknown" };
+        case "user":
+          return { userId: resource.id, visibility: "unknown" };
+        case "org":
+          return { visibility: "unknown" };
+      }
+      break;
+    case "agent":
+      return { name: resource.name, visibility: "unknown" };
+    case "command":
+      return { visibility: "unknown" };
+  }
+  return { visibility: "unknown" };
+}

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

@@ -0,0 +1,164 @@
+// One authorization model — the shared contract
+// (docs/decisions/0007-authorization-policy-table.md).
+//
+// Every surface resolves WHO is asking into an `Actor`; every command names
+// WHAT it does as an `Action`; every thing acted on is a typed `Resource`.
+// `authorize(actor, action, resource)` is the only decision; the same policy
+// rules compile into store predicates for list-shaped reads.
+// This file is types only — no logic, no I/O, node-free (importable by the
+// state Worker like `runRecord.ts`).
+
+/** Who is asking. `agent` acts on behalf of a principal and never exceeds it. */
+export type ActorKind = "user" | "service" | "schedule" | "agent";
+
+/** A set of names, or everything. `"all"` is explicit, never a default. */
+export type GrantSet = ReadonlySet<string> | "all";
+
+/** What an actor may do. One shape for humans, ingress
+ *  tokens, Access identities, schedule actors, and agents. */
+export interface Grants {
+  /** Action ids: `runs:read`, `friction:write`, `repo:exec`, `agent:run:<name>`, `memory:write`, … */
+  readonly actions: GrantSet;
+  /** Platform-namespaced channel ids the actor is a member of (`slack:C…`, `http:ops`), or every channel. */
+  readonly channels: GrantSet;
+  /** `owner/name` repos the actor may use, or every repo (open-when-absent today → `"all"`). */
+  readonly repos: GrantSet;
+}
+// Which agents an actor may run is NOT a separate axis: it is the action
+// `agent:run:<name>` (or `agent:run:*`) in `actions`, so `has-grant` covers it
+// and the condition vocabulary stays closed.
+
+/** The empty grant. `Object.freeze` is shallow and a frozen `Set` still
+ *  accepts `add`, so the inner sets are protected by the `ReadonlySet` type
+ *  alone — never hand this object to code that takes a mutable `Set`. */
+export const NO_GRANTS: Grants = Object.freeze({
+  actions: new Set<string>(),
+  channels: new Set<string>(),
+  repos: new Set<string>(),
+});
+
+export interface Actor {
+  readonly kind: ActorKind;
+  /** Platform-namespaced (invariant 4): `slack:U…`, `http:<subject>`, `mcp:<subject>`,
+   *  `access:<sub>`, `access:svc:<common_name>`, `cli:local`, `schedule:<name>`, `agent:<name>`. */
+  readonly id: string;
+  readonly grants: Grants;
+  /** For `agent` actors: the principal the run acts for. Effective grants are the intersection. */
+  readonly onBehalfOf?: Actor;
+  /** Where a chat actor is speaking from — context, never authority. */
+  readonly origin?: { readonly channelId: string; readonly threadKey: string };
+}
+
+/** `<group>:<read|write|exec>` plus the non-command actions. A plain
+ *  string on purpose: command ids are derived from the registry at runtime, so
+ *  the closed set lives in the policy table, which validates every action it
+ *  names against the registry at module load rather than in the type. */
+export type Action = string;
+
+/** How a channel's content may travel. `machine` = `http:*` / `mcp:*`. */
+export type ChannelVisibility = "public" | "private" | "dm" | "machine" | "unknown";
+
+export type Resource =
+  | {
+      readonly type: "run";
+      readonly id: string;
+      readonly channelId: string;
+      readonly userId: string;
+      readonly repo?: string;
+      readonly channelVisibility?: ChannelVisibility;
+    }
+  | { readonly type: "channel"; readonly id: string; readonly visibility: ChannelVisibility }
+  | {
+      readonly type: "memory-scope";
+      readonly key: string;
+      readonly kind: "org" | "user" | "repo" | "channel";
+      readonly originChannelVisibility?: ChannelVisibility;
+    }
+  | { readonly type: "repo"; readonly owner: string; readonly name: string }
+  /** A config tier (routing-and-config: a channel's or a user's scope, or the
+   *  org-wide defaults — the three tiers MCP servers live in as well). */
+  | { readonly type: "config-scope"; readonly kind: "channel" | "user"; readonly id: string }
+  | { readonly type: "config-scope"; readonly kind: "org" }
+  | { readonly type: "agent"; readonly name: string }
+  /** List-shaped actions with no single resource (`runs.list`, `friction.report`). */
+  | { readonly type: "command"; readonly id: string };
+
+export type ResourceType = Resource["type"];
+
+/** The CLOSED condition vocabulary. Every condition is both evaluable
+ *  against one resource and compilable to a store predicate. Adding a member
+ *  is a decision-record-level change, never a local convenience. */
+export type Condition =
+  | { readonly kind: "has-grant"; readonly grant: string }
+  /** actor.grants.channels contains resource.channelId (or is "all"), OR the
+   *  resource's channel is `public` (a run's stamped `channelVisibility`;
+   *  `unknown` is never public). One definition for both evaluators. */
+  | { readonly kind: "member-of" }
+  /** resource.userId === actor.id (or the on-behalf-of principal's id). */
+  | { readonly kind: "is-self" }
+  /** actor.grants.repos contains the resource's repo (or is "all"). */
+  | { readonly kind: "owner-of" }
+  /** actor.grants.channels === "all". */
+  | { readonly kind: "all-channels" };
+
+/** The `kind` discriminator of a kinded resource type (`memory-scope`,
+ *  `config-scope`); `never` for the others, so a row cannot carry a kind its
+ *  resource does not have. */
+export type KindOf<T extends ResourceType> =
+  Extract<Resource, { readonly type: T }> extends { readonly kind: infer K } ? K : never;
+
+/** Every kind any kinded resource has (distributed per type — a conditional over the whole union would be `never`). */
+export type ResourceKind = { [T in ResourceType]: KindOf<T> }[ResourceType];
+
+/** `resourceKind` is REQUIRED for a kinded resource type and FORBIDDEN for the
+ *  others — enforced by the type, not by a comment. */
+type KindField<T extends ResourceType> = [KindOf<T>] extends [never]
+  ? { readonly resourceKind?: never }
+  : { readonly resourceKind: KindOf<T> };
+
+/** One policy row: `when` conditions are ANDed; rows for the same
+ *  (action, resource type[/kind]) are ORed. No row → deny (fail-closed).
+ *  `actorKinds`, `resourceKind`, and `originVisibility` SELECT which rows
+ *  apply; `when` decides. Selectors read one side only (the actor's kind or a
+ *  resource attribute); conditions relate the two — so selectors never widen
+ *  the closed condition vocabulary. */
+export type RuleFor<T extends ResourceType> = {
+  readonly action: Action;
+  readonly resource: T;
+  /** Restrict the row to these actor kinds; absent = any kind. */
+  readonly actorKinds?: readonly ActorKind[];
+  /** Restrict the row to resources whose origin channel has one of these
+   *  visibilities (an `org` memory write from a `private`/`dm`/`unknown`
+   *  origin has no row). A row carrying it is point-check only — `predicateFor`
+   *  compiles it to `none`, since a store predicate cannot see the origin. */
+  readonly originVisibility?: readonly ChannelVisibility[];
+  readonly when: readonly Condition[];
+} & KindField<T>;
+
+/** A row for any resource type — distributed, so the kind stays tied to the type. */
+export type Rule = { [T in ResourceType]: RuleFor<T> }[ResourceType];
+
+export type Decision = { readonly allow: true } | { readonly allow: false; readonly reason: string };
+
+/** What a list-shaped read may return, derived from the rules.
+ *  Stores translate it to their own filter; handlers never see it. */
+export type Predicate =
+  | { readonly kind: "none" } // nothing is visible
+  | { readonly kind: "all" }
+  | { readonly kind: "channels-in"; readonly channelIds: ReadonlySet<string> }
+  | { readonly kind: "user-is"; readonly userId: string }
+  | { readonly kind: "repos-in"; readonly repos: ReadonlySet<string> }
+  /** The record's stamped `channelVisibility` is one of these (`member-of`'s
+   *  public half). A record without the stamp is `unknown` and never matches
+   *  `visibility-in(["public"])`. */
+  | { readonly kind: "visibility-in"; readonly visibilities: ReadonlySet<ChannelVisibility> }
+  /** Rows for one (action, resource type) OR together. */
+  | { readonly kind: "or"; readonly of: readonly Predicate[] }
+  /** The compilable conditions of ONE row AND together (e.g. member-of ∧ is-self). */
+  | { readonly kind: "and"; readonly of: readonly Predicate[] };
+
+/** Adapter-supplied channel facts. `unknown` is never a member (fail-closed). */
+export interface ChannelDirectory {
+  info(channelId: string): Promise<{ visibility: ChannelVisibility }>;
+  isMember(actorId: string, channelId: string): Promise<boolean | "unknown">;
+}

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

@@ -0,0 +1,54 @@
+// Graceful-drain timing facts, shared by the drain itself (`src/index.ts`),
+// the `/healthz` body (`src/channels/health.ts`) and the Slack reconnect
+// catch-up (`src/channels/slackCatchUp.ts`). Node-free and Bolt-free on purpose
+// so tests can pin the relationship between them without loading the adapter.
+//
+// Why they are one module: on SIGTERM the drain closes the Slack socket
+// at once and holds the container until in-flight runs finish, up to
+// DRAIN_DEADLINE_MS. Cloudflare starts the replacement container only after
+// this one exits, so a deploy that lands on a run in flight blacks Slack out
+// for the run's remaining duration (minutes, in practice). Mentions in
+// that gap are recovered ONLY by the catch-up scan on the next connect, whose
+// window must therefore cover the worst blackout: the full drain deadline plus
+// the new container's cold start. Keeping the socket open during the drain was
+// rejected — see the drain in `src/index.ts`.
+
+/** How long the drain waits for in-flight work after SIGTERM before exiting —
+ *  the grace Cloudflare's rollout allows before SIGKILL. With the run ledger on,
+ *  the runs a resume can continue are handed off instead of waited for
+ *  (docs/reference/specs/run-history.md item 39); this is the wait for the rest. */
+export const DRAIN_DEADLINE_MS = 15 * 60_000;
+
+/** The handoff's own budget (plan D8): after every resumable run is marked
+ *  `handoff`, the drain waits this long for pending history writes and
+ *  reflections, then exits — the next generation takes the runs. */
+export const HANDOFF_BUDGET_MS = 6_000;
+
+/** Time budgeted for the replacement container to boot and reach Socket Mode
+ *  `connected` (image pull + Node start + Bolt handshake), when the catch-up
+ *  scan runs. */
+export const COLD_START_ALLOWANCE_MS = 5 * 60_000;
+
+/** The smallest catch-up window that still covers a full-length drain. A
+ *  smaller window leaves mentions posted early in a long drain un-run forever. */
+export const MIN_CATCH_UP_WINDOW_MS = DRAIN_DEADLINE_MS + COLD_START_ALLOWANCE_MS;
+
+/**
+ * Startup validation for `slack.catchUp.windowMinutes`. Returns a warning to
+ * log when the configured window cannot cover a full drain, or is not a usable
+ * duration; `undefined` when unset (the default applies) or safe. Never clamps:
+ * the operator's value stands — the warning names what it costs.
+ */
+export function catchUpWindowWarning(windowMinutes: number | undefined): string | undefined {
+  if (windowMinutes === undefined) return undefined;
+  if (!Number.isFinite(windowMinutes) || windowMinutes <= 0) {
+    return `slack.catchUp.windowMinutes must be a positive number of minutes (got ${String(windowMinutes)}); no catch-up window is usable`;
+  }
+  const windowMs = windowMinutes * 60_000;
+  if (windowMs >= MIN_CATCH_UP_WINDOW_MS) return undefined;
+  return (
+    `slack.catchUp.windowMinutes=${windowMinutes} (${windowMinutes} min) is below the safe minimum of ${MIN_CATCH_UP_WINDOW_MS / 60_000} min ` +
+    `(the ${DRAIN_DEADLINE_MS / 60_000} min drain deadline + ${COLD_START_ALLOWANCE_MS / 60_000} min cold start): ` +
+    `mentions posted early in a deploy-time drain longer than ${windowMinutes} min will never be caught up. Keeping the configured value.`
+  );
+}

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

@@ -0,0 +1,64 @@
+// The ingress token map, parsed without any Node dependency so BOTH the bot
+// (src/channels/http.ts, src/channels/mcp.ts) and the Cloudflare Worker shim
+// (deploy/cloudflare/worker.ts, which fires scheduled runs through /ingress)
+// read `SWITCHBOARD_INGRESS_TOKENS` with ONE parser. The shape is
+//   {"<raw bearer token>": {"subject": "alice", "channel": "ops"}, ...}
+// A token is a CREDENTIAL, nothing more: what its bearer may do — start a run
+// (`dispatch`), read runs, anything else — is the `grants` entry for
+// `http:<subject>` / `mcp:<subject>` in config.yaml (docs/reference/specs/authorization.md
+// item 9). Absent, empty, or malformed => an empty map. Callers treat an empty
+// map as "ingress disabled" (fail-closed) — this module never decides that, it
+// only parses. Token material is never logged here; the caller may log the reason.
+
+/** The identity a token maps to. `subject` becomes the platform-namespaced user
+ *  id (`http:<subject>`); an optional `channel` names the channel a dispatch
+ *  through this token is recorded under (`http:<channel>`) — routing, not a
+ *  grant. These two are the whole identity: any other field in an entry is
+ *  ignored, so nothing in the token map can widen what the grants entry says. */
+export interface IngressIdentity {
+  subject: string;
+  channel?: string;
+}
+
+export type IngressTokenMap = Record<string, IngressIdentity>;
+
+export type ParsedIngressTokens =
+  | { ok: true; tokens: IngressTokenMap }
+  /** `reason` names the shape problem (never the token material). */
+  | { ok: false; reason: string; tokens: IngressTokenMap };
+
+/** Parse the raw env value. Entries with an empty token, a non-object value, a
+ *  missing/empty `subject`, or a non-string `channel` are skipped; the rest are
+ *  kept, each reduced to `{ subject, channel? }`. `ok: false` only for a value
+ *  that is not a JSON object at all. */
+export function parseIngressTokenMap(raw: string | undefined): ParsedIngressTokens {
+  if (!raw || raw.trim() === "") return { ok: true, tokens: {} };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "not valid JSON", tokens: {} };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, reason: "must be a JSON object", tokens: {} };
+  }
+  const tokens: IngressTokenMap = {};
+  for (const [token, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (token === "") continue;
+    if (typeof value !== "object" || value === null) continue;
+    const v = value as Record<string, unknown>;
+    const subject = v.subject;
+    const channel = v.channel;
+    if (typeof subject !== "string" || subject === "") continue;
+    if (channel !== undefined && typeof channel !== "string") continue;
+    tokens[token] = typeof channel === "string" ? { subject, channel } : { subject };
+  }
+  return { ok: true, tokens };
+}
+
+/** The raw token that maps to `subject`, or undefined when no entry does (or
+ *  more than one does — an ambiguous identity is refused, never guessed). */
+export function tokenForSubject(tokens: IngressTokenMap, subject: string): string | undefined {
+  const matches = Object.entries(tokens).filter(([, id]) => id.subject === subject);
+  return matches.length === 1 ? matches[0][0] : undefined;
+}

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

@@ -0,0 +1,115 @@
+import type { MemoryCandidate, MemoryRecord } from "./types.js";
+import { keywordMatch, scoreRecord, tokenize } from "./scorer.js";
+
+// The store-agnostic memory algorithms: retrieval ranking and the write plan
+// (dedup / supersede). Pure functions over plain records, no I/O and no clock
+// of their own, so BOTH MemoryStore implementations — the in-process
+// `InMemoryMemoryStore` and the Durable Object behind `WorkerMemoryStore`
+// (deploy/cloudflare-memory/worker.ts imports this file by relative path and
+// bundles it) — run the exact same rules from one source. A store only owns
+// persistence: fetching the active rows of a scope and applying the plan.
+
+/** Normalized text key for write-time dedup (trim + lowercase + collapse
+ *  internal whitespace). Stored alongside the text by durable backends so the
+ *  dedup lookup is an index hit, not a scan. */
+export function normalizeText(text: string): string {
+  return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/** Rank a scope's ACTIVE records for a query: relevance-gated (a record the
+ *  query does not touch is dropped), scored by the pure scorer, best first,
+ *  cut at `limit`. Does NOT bump usage — the caller persists that. */
+export function rankRecords(active: MemoryRecord[], query: string, now: number, limit: number): MemoryRecord[] {
+  // The query (up to ~4k chars) is tokenized ONCE here, not once per record per
+  // pass: the Memory Worker runs this over its FTS candidate pool (up to
+  // max(50, 5×limit) bm25-ordered rows) on a single Durable Object
+  // thread, and each record's match is computed exactly once — the relevance
+  // gate and the score share it.
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+  const scored: Array<{ r: MemoryRecord; score: number }> = [];
+  for (const r of active) {
+    if (r.status !== "active") continue;
+    const match = keywordMatch(r, queryTokens);
+    if (match <= 0) continue;
+    scored.push({ r, score: scoreRecord(r, queryTokens, now) });
+  }
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ r }) => r);
+}
+
+/** Default per-scope cap on ACTIVE records when config does not set one. */
+export const DEFAULT_SCOPE_CAP = 500;
+
+/** Per-scope cap: which ACTIVE records a store must evict so that at
+ *  most `cap` remain — the least recently USED first (`lastUsedAt ??
+ *  createdAt` ascending; ties broken by lower `createdAt`, so the older record
+ *  goes first), exactly `active.length - cap` of them, none at or under the
+ *  cap. Non-active rows are ignored (they neither count nor get evicted).
+ *  Pure: the caller flips status (soft delete — provenance stays). */
+export function planEviction(active: MemoryRecord[], cap: number): MemoryRecord[] {
+  const live = active.filter((r) => r.status === "active");
+  const excess = live.length - cap;
+  if (excess <= 0) return [];
+  return live
+    .slice()
+    .sort((a, b) => (a.lastUsedAt ?? a.createdAt) - (b.lastUsedAt ?? b.createdAt) || a.createdAt - b.createdAt)
+    .slice(0, excess);
+}
+
+/** What a store must do for one candidate. `dedup`: bump `target.useCount`,
+ *  insert nothing. `insert`: append `record` (already minted) and, when
+ *  `supersede` is set, flip that record to `superseded`. */
+export type WritePlan =
+  { action: "dedup"; target: MemoryRecord } | { action: "insert"; record: MemoryRecord; supersede?: MemoryRecord };
+
+/**
+ * Decide how one candidate lands among a scope's ACTIVE records (docs/reference/specs/
+ * memory.md §8):
+ * - **Supersede target** = the active same-scope record whose id equals
+ *   `cand.supersedes`; an unknown/foreign id resolves to nothing (the new
+ *   record still lands, superseding nothing).
+ * - **Dedup**: a candidate WITHOUT `supersedes` dedups against every active
+ *   record (normalized-text equality → bump, no insert). A candidate WITH
+ *   `supersedes` is an explicit correction and dedups ONLY against its own
+ *   target — and against nothing when the id doesn't resolve — so a text
+ *   collision with an unrelated record can never swallow the correction (the
+ *   extractor sees existing text verbatim; a poisoned transcript could induce
+ *   such a collision to keep a stale record alive).
+ * - Otherwise **insert** the minted record (`mint` assigns id/timestamps),
+ *   soft-deleting the target if there is one.
+ */
+export function planWrite(
+  active: MemoryRecord[],
+  cand: MemoryCandidate,
+  mint: (cand: MemoryCandidate) => MemoryRecord,
+): WritePlan {
+  const norm = normalizeText(cand.text);
+  const target = cand.supersedes ? active.find((r) => r.status === "active" && r.id === cand.supersedes) : undefined;
+  const dedupPool = cand.supersedes ? (target ? [target] : []) : active.filter((r) => r.status === "active");
+  const existing = dedupPool.find((r) => normalizeText(r.text) === norm);
+  if (existing) return { action: "dedup", target: existing };
+  return { action: "insert", record: mint(cand), ...(target ? { supersede: target } : {}) };
+}
+
+/** Build the record a store persists for a candidate. Ids are namespaced per
+ *  AGENTS.md invariant 4 (`mem:<scopeKey>:<seq>`); keywords default to the
+ *  text's tokens so keyword retrieval always has something to hit. */
+export function mintRecord(scopeKey: string, seq: number, now: number, cand: MemoryCandidate): MemoryRecord {
+  return {
+    id: `mem:${scopeKey}:${seq}`,
+    scopeKey,
+    kind: cand.kind,
+    text: cand.text,
+    keywords: cand.keywords ?? tokenize(cand.text),
+    sourceThreadKey: cand.sourceThreadKey,
+    sourceRunId: cand.sourceRunId,
+    createdAt: now,
+    useCount: 0,
+    confidence: cand.confidence,
+    supersedes: cand.supersedes,
+    status: "active",
+  };
+}