@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/runtime/managed-block.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared by the setup writers and the Companion Instructions reader. In
+ * `runtime/` because hooks may import nothing outside it.
+ */
+
+import { fencedRanges, trimBlankLines } from "./markdown-scan";
+
+export interface ManagedBlockMarkers {
+  start: string;
+  end: string;
+}
+
+export function managedBlockMarkers(frameworkName: string, blockKey: string): ManagedBlockMarkers {
+  return {
+    start: `<!-- ${frameworkName}:managed:${blockKey} start -->`,
+    end: `<!-- ${frameworkName}:managed:${blockKey} end -->`,
+  };
+}
+
+export function companionBlockMarkers(frameworkName: string): ManagedBlockMarkers {
+  const name = frameworkName.toUpperCase();
+  return {
+    start: `<!-- ${name}:COMPANION:START -->`,
+    end: `<!-- ${name}:COMPANION:END -->`,
+  };
+}
+
+/**
+ * The plugin owning a block whose key is `<pluginId>:<content hash>`, the
+ * shape every setup writer produces; a key without a hash is returned whole.
+ */
+export function managedBlockPluginId(blockKey: string): string {
+  const separator = blockKey.lastIndexOf(":");
+  return separator === -1 ? blockKey : blockKey.slice(0, separator);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Matches a start marker; group 1 is the key. Given `pluginId`, only that plugin's blocks match. */
+export function managedBlockStartPattern(frameworkName: string, pluginId?: string): RegExp {
+  const keyPattern = pluginId === undefined ? "[^\\s]+" : `${escapeRegExp(pluginId)}:[0-9a-f]+`;
+  return new RegExp(`<!-- ${escapeRegExp(frameworkName)}:managed:(${keyPattern}) start -->`, "g");
+}
+
+export interface ManagedBlock {
+  key: string;
+  /** Offsets of the whole block, markers included. */
+  start: number;
+  end: number;
+  body: string;
+}
+
+/** A marker quoted in a code fence is an example, not a block. */
+function inFence(fenced: readonly [number, number][], index: number): boolean {
+  return fenced.some(([from, to]) => index >= from && index < to);
+}
+
+/** The first `marker` at or after `from` outside a code fence, or -1. */
+function indexOutsideFence(
+  text: string,
+  marker: string,
+  from: number,
+  fenced: readonly [number, number][],
+): number {
+  let index = text.indexOf(marker, from);
+  while (index !== -1 && inFence(fenced, index)) {
+    index = text.indexOf(marker, index + marker.length);
+  }
+  return index;
+}
+
+/** Offsets of the first `MATE:COMPANION` block, markers included; `null` without one. */
+export function findCompanionBlock(
+  text: string,
+  frameworkName: string,
+): { start: number; end: number } | null {
+  const { start, end } = companionBlockMarkers(frameworkName);
+  const fenced = fencedRanges(text);
+  const startIndex = indexOutsideFence(text, start, 0, fenced);
+  if (startIndex === -1) return null;
+  const endIndex = indexOutsideFence(text, end, startIndex + start.length, fenced);
+  return endIndex === -1 ? null : { start: startIndex, end: endIndex + end.length };
+}
+
+export function findManagedBlocks(text: string, frameworkName: string): ManagedBlock[] {
+  const blocks: ManagedBlock[] = [];
+  const fenced = fencedRanges(text);
+  for (const match of text.matchAll(managedBlockStartPattern(frameworkName))) {
+    if (inFence(fenced, match.index)) continue;
+    const key = match[1]!;
+    const { start, end } = managedBlockMarkers(frameworkName, key);
+    const bodyStart = match.index + start.length;
+    const endIndex = indexOutsideFence(text, end, bodyStart, fenced);
+    if (endIndex === -1) continue;
+    const previous = blocks.at(-1);
+    if (previous && match.index < previous.end) continue;
+    blocks.push({
+      key,
+      start: match.index,
+      end: endIndex + end.length,
+      body: trimBlankLines(text.slice(bodyStart, endIndex)),
+    });
+  }
+  return blocks;
+}
+
+export function stripManagedBlocks(text: string, frameworkName: string): string {
+  let result = "";
+  let cursor = 0;
+  for (const block of findManagedBlocks(text, frameworkName)) {
+    result += text.slice(cursor, block.start);
+    cursor = block.end;
+  }
+  return result + text.slice(cursor);
+}

package/src/runtime/markdown-scan.ts

@@ -0,0 +1,266 @@
+/**
+ * A line scan of CommonMark, deep enough to find `##` sections, fenced code
+ * and block-level HTML comments as Claude Code's memory loading reads them.
+ */
+
+/** A block quote, or a list item whose content starts `width` columns into its parent's. */
+type Container = { kind: "quote" } | { kind: "item"; width: number };
+
+interface Fence {
+  char: string;
+  length: number;
+  /** The containers the fence opened in, outermost first; a line that leaves one ends the fence. */
+  containers: readonly Container[];
+}
+
+const FENCE_OPEN = /^(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^(`{3,}|~{3,})[ \t]*$/;
+const LIST_MARKER = /^(?:[-+*]|\d{1,9}[.)])/;
+const BLANK = /^[ \t]*$/;
+
+function indentation(text: string, from: number): { column: number; rest: string } {
+  let column = from;
+  let index = 0;
+  for (; index < text.length; index++) {
+    if (text[index] === " ") column++;
+    else if (text[index] === "\t") column += 4 - (column % 4);
+    else break;
+  }
+  return { column, rest: text.slice(index) };
+}
+
+/** Where a line's text stands: `rest` starts at `column`; the innermost container's content starts at `base`. */
+interface Position {
+  column: number;
+  rest: string;
+  base: number;
+}
+
+/** CommonMark: `>` after up to three spaces of indentation, and one optional space that belongs to the marker. */
+function afterQuoteMarker({ column, rest, base }: Position): Position | null {
+  if (column - base > 3 || !rest.startsWith(">")) return null;
+  const marker = column + 1;
+  const after = indentation(rest.slice(1), marker);
+  return { ...after, base: after.column > marker ? marker + 1 : marker };
+}
+
+/** The open containers a line continues, outermost first. A blank line continues list items, never a quote. */
+function continueContainers(
+  line: string,
+  containers: readonly Container[],
+): { matched: Container[]; at: Position } {
+  let at: Position = { ...indentation(line, 0), base: 0 };
+  const matched: Container[] = [];
+  for (const container of containers) {
+    if (container.kind === "quote") {
+      const next = afterQuoteMarker(at);
+      if (!next) break;
+      at = next;
+    } else {
+      if (at.rest !== "" && at.column < at.base + container.width) break;
+      at = { ...at, base: at.base + container.width };
+    }
+    matched.push(container);
+  }
+  return { matched, at };
+}
+
+/** The open containers carried from line to line. */
+interface ContainerContext {
+  containers: readonly Container[];
+  /** A paragraph is open, so a line that leaves its containers may continue it lazily. */
+  paragraph: boolean;
+  /** The innermost item opened on a blank line, so a blank line next ends it. */
+  emptyItem: boolean;
+}
+
+const TOP_LEVEL: ContainerContext = { containers: [], paragraph: false, emptyItem: false };
+
+/** CommonMark: a line that starts a block, so it ends a paragraph rather than continuing it. */
+const INTERRUPTS = /^(?:`{3,}|~{3,}|#{1,6}(?:[ \t]|$)|>|<!--|(?:[-+*]|\d{1,9}[.)])(?:[ \t]|$))/;
+const THEMATIC_BREAK = /^(?:(?:\*[ \t]*){3,}|(?:-[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+
+/**
+ * Tracks only as much of CommonMark's block quotes and list items as placing a
+ * fence needs. A backtick fence's info string may hold no backtick, so
+ * ```` ```a``` ```` is inline code.
+ */
+function lineBlock(
+  line: string,
+  context: ContainerContext,
+): { fence: Fence | null; context: ContainerContext } {
+  const { matched, at } = continueContainers(line, context.containers);
+  const continues = matched.length === context.containers.length;
+  let { column, rest, base } = at;
+  if (rest === "") {
+    const containers = continues && context.emptyItem ? matched.slice(0, -1) : matched;
+    return { fence: null, context: { containers, paragraph: false, emptyItem: false } };
+  }
+  if (!continues) {
+    const starts = INTERRUPTS.test(rest) || THEMATIC_BREAK.test(rest);
+    const lazy = context.paragraph && !(column - base <= 3 && starts);
+    if (lazy) return { fence: null, context };
+  }
+  let containers = matched;
+  let paragraph = context.paragraph && continues;
+
+  while (column - base <= 3 && !THEMATIC_BREAK.test(rest)) {
+    const quoted = afterQuoteMarker({ column, rest, base });
+    if (quoted) {
+      containers = [...containers, { kind: "quote" }];
+      ({ column, rest, base } = quoted);
+      paragraph = false;
+      if (rest === "") return { fence: null, context: { containers, paragraph, emptyItem: false } };
+      continue;
+    }
+    const marker = LIST_MARKER.exec(rest);
+    if (!marker) break;
+    const markerEnd = column + marker[0].length;
+    const after = indentation(rest.slice(marker[0].length), markerEnd);
+    const gap = after.column - markerEnd;
+    if (gap < 1 && after.rest !== "") break;
+    const ordered = marker[0].length > 1;
+    if (paragraph && (after.rest === "" || (ordered && Number.parseInt(marker[0], 10) !== 1))) {
+      break;
+    }
+    const content = gap > 4 || after.rest === "" ? markerEnd + 1 : after.column;
+    containers = [...containers, { kind: "item", width: content - base }];
+    base = content;
+    paragraph = false;
+    if (after.rest === "") {
+      return { fence: null, context: { containers, paragraph, emptyItem: true } };
+    }
+    column = after.column;
+    rest = after.rest;
+  }
+
+  if (column - base > 3) {
+    return { fence: null, context: { containers, paragraph, emptyItem: false } };
+  }
+  const match = FENCE_OPEN.exec(rest);
+  const run = match?.[1];
+  if (run && !(run.startsWith("`") && match[2]!.includes("`"))) {
+    const fence = { char: run[0]!, length: run.length, containers };
+    return { fence, context: { containers, paragraph: false, emptyItem: false } };
+  }
+  paragraph = !THEMATIC_BREAK.test(rest) && !/^#{1,6}(?:[ \t]|$)/.test(rest);
+  return { fence: null, context: { containers, paragraph, emptyItem: false } };
+}
+
+/** `ends`: a line that leaves one of the fence's containers ends it; fenced code never continues lazily. */
+function fenceLine(line: string, fence: Fence): "content" | "close" | "ends" {
+  const { matched, at } = continueContainers(line, fence.containers);
+  if (matched.length < fence.containers.length) return "ends";
+  if (at.rest === "") return "content";
+  const match = at.column - at.base <= 3 ? FENCE_CLOSE.exec(at.rest) : null;
+  return match !== null && match[1]!.startsWith(fence.char) && match[1]!.length >= fence.length
+    ? "close"
+    : "content";
+}
+
+/** CommonMark: an ATX heading may be indented by up to three spaces, and be empty. */
+const HEADING = /^ {0,3}##(?:[ \t]+(.*))?$/;
+/** CommonMark: a closing run of `#`s, after a space or tab, is no part of the heading. */
+const CLOSING_SEQUENCE = /(?:^|[ \t]+)#+[ \t]*$/;
+
+function headingText(line: string): string | null {
+  const match = HEADING.exec(line);
+  if (!match) return null;
+  return (match[1] ?? "").replace(CLOSING_SEQUENCE, "").trim();
+}
+
+export interface ScannedLine {
+  text: string;
+  /** The heading text, `""` when empty, when the line opens a top-level (`##`) section: outside fenced code, list items and block quotes, whose scope it would otherwise leave. */
+  heading: string | null;
+  /** Inside fenced code, where blank lines are content. */
+  fenced: boolean;
+  /** Where the source line starts in the scanned text. */
+  offset: number;
+}
+
+/** CommonMark: an HTML block opens on a line that begins, after up to three spaces, with `<!--`. */
+const BLOCK_COMMENT_OPEN = /^ {0,3}<!--/;
+/** Claude Code's own pattern for the comments it removes from such a block. */
+const CLOSED_COMMENT = /<!--[\s\S]*?-->/g;
+
+type ScanState = { in: "prose" } | { in: "fence"; fence: Fence } | { in: "comment" };
+
+const PROSE: ScanState = { in: "prose" };
+const COMMENT: ScanState = { in: "comment" };
+
+/**
+ * Strips block-level HTML comments as Claude Code's memory loading does: only
+ * an HTML block that opens with `<!--` and holds a `-->`, so a `<!--` inside
+ * prose, inside fenced code, or never closed stays. The rest of a closing line
+ * is still part of the HTML block, so it opens no heading and no fence.
+ */
+export function scanLinesWithoutComments(text: string): ScannedLine[] {
+  const lines: ScannedLine[] = [];
+  let state = PROSE;
+  let list = TOP_LEVEL;
+  let offset = 0;
+
+  const emit = (line: string): void => {
+    const next = lineBlock(line, list);
+    const heading = next.context.containers.length === 0 ? headingText(line) : null;
+    lines.push({ text: line, heading, fenced: false, offset });
+    list = next.context;
+    state = next.fence ? { in: "fence", fence: next.fence } : PROSE;
+  };
+  /** A comment's lines are one HTML block: it ends the containers it leaves. */
+  const enterComment = (line: string): void => {
+    list = { ...lineBlock(line, list).context, paragraph: false };
+  };
+  const emitAfterClose = (line: string, close: number): void => {
+    const rest = line.slice(close + 3).replace(CLOSED_COMMENT, "");
+    lines.push({ text: rest, heading: null, fenced: false, offset });
+    state = PROSE;
+  };
+
+  for (const raw of text.split("\n")) {
+    const inFence = state.in === "fence" ? fenceLine(raw, state.fence) : "ends";
+    if (inFence !== "ends") {
+      lines.push({ text: raw, heading: null, fenced: true, offset });
+      if (inFence === "close") state = PROSE;
+    } else if (state.in === "comment") {
+      const close = raw.indexOf("-->");
+      if (close !== -1) emitAfterClose(raw, close);
+    } else if (BLOCK_COMMENT_OPEN.test(raw)) {
+      const close = text.indexOf("-->", offset + raw.indexOf("<!--") + 4);
+      if (close === -1) emit(raw);
+      else {
+        enterComment(raw);
+        if (close < offset + raw.length) emitAfterClose(raw, close - offset);
+        else state = COMMENT;
+      }
+    } else {
+      emit(raw);
+    }
+    offset += raw.length + 1;
+  }
+  return lines;
+}
+
+/** Offsets `[start, end)` of the lines inside fenced code. */
+export function fencedRanges(text: string): [number, number][] {
+  return scanLinesWithoutComments(text)
+    .filter((line) => line.fenced)
+    .map((line) => [line.offset, line.offset + line.text.length]);
+}
+
+export function joinLines(lines: readonly ScannedLine[]): string {
+  const kept: string[] = [];
+  let afterBlank = false;
+  for (const line of lines) {
+    const blank = !line.fenced && BLANK.test(line.text);
+    if (!(blank && afterBlank)) kept.push(blank ? "" : line.text);
+    afterBlank = blank;
+  }
+  return trimBlankLines(kept.join("\n"));
+}
+
+/** Drops the blank lines around a text but no indentation: an indented fence opener keeps its meaning. */
+export function trimBlankLines(text: string): string {
+  return text.replace(/^(?:[ \t]*\n)+/, "").trimEnd();
+}

package/src/runtime/policy.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "./framework";
+import { defaultSecretPolicy, parseSecretsConfig, type SecretPolicy } from "./secret-patterns";
 
 /**
  * Predicates that are never projected: they are read live from the companion
@@ -14,12 +15,18 @@ export interface CompanionPolicy {
   /** Names of the Capabilities the companion has enabled. */
   enabledCapabilities: string[];
   gitAutoMode: boolean;
+  /**
+   * Secret guardrails. Unlike the other fields, a missing or broken config
+   * yields guardrails on: protection never fails open.
+   */
+  secrets: SecretPolicy;
 }
 
 export const emptyCompanionPolicy = (): CompanionPolicy => ({
   allowedAgents: [],
   enabledCapabilities: [],
   gitAutoMode: false,
+  secrets: defaultSecretPolicy(),
 });
 
 export function companionFrameworkConfigPath(companionPath: string): string {
@@ -40,20 +47,10 @@ function capabilityNames(value: unknown): string[] {
     .filter((name): name is string => typeof name === "string");
 }
 
-/**
- * A base-set key from `audiences.base`, the shape a companion is saved in. The
- * lenient twin of the setup normalizer, which `runtime/` cannot import.
- */
-function baseAudienceKey(config: Record<string, unknown>, key: string): unknown {
-  const audiences = config.audiences;
-  if (!audiences || typeof audiences !== "object") return undefined;
-  const base = (audiences as Record<string, unknown>).base;
-  return base && typeof base === "object" ? (base as Record<string, unknown>)[key] : undefined;
-}
-
 /**
  * Synchronous so it composes into `readCompanionRuntimeContext`. A missing or
- * unparseable companion config yields an inert policy rather than throwing.
+ * unparseable companion config yields an inert policy rather than throwing,
+ * with secret guardrails active.
  */
 export function readCompanionPolicy(companionPath: string): CompanionPolicy {
   let parsed: unknown;
@@ -67,13 +64,17 @@ export function readCompanionPolicy(companionPath: string): CompanionPolicy {
   const config = parsed as Record<string, unknown>;
   return {
     allowedAgents: stringList(config.allowedAgents),
-    enabledCapabilities: capabilityNames(
-      config.capabilities ?? baseAudienceKey(config, "capabilities"),
-    ),
+    enabledCapabilities: capabilityNames(config.capabilities),
     gitAutoMode: config.git === "auto",
+    secrets: parseSecretsConfig(config.secrets),
   };
 }
 
+/** The companion's live secret policy, read on every call. */
+export function resolveSecretPolicy(companionPath: string): SecretPolicy {
+  return readCompanionPolicy(companionPath).secrets;
+}
+
 export function isCapabilityEnabled(policy: CompanionPolicy, name: string): boolean {
   return policy.enabledCapabilities.includes(name);
 }

package/src/runtime/projected-flag.ts

@@ -0,0 +1,7 @@
+/**
+ * Marks the hook copies a Claude wrap inlines into a Working Repository's
+ * settings. A managed launch loads the bundled plugin's copy of the same hooks
+ * against the same environment, so nothing inside the process tells the two
+ * apart but this flag.
+ */
+export const PROJECTED_FLAG = "--projected";

package/src/runtime/projected-guidance.ts

@@ -38,6 +38,7 @@ export function buildProjectedGuidance(
       companionPath: projection.companionPath,
       repository: { id: projection.repositoryId, path: projection.repositoryPath },
       capabilities: policy.enabledCapabilities.map((name) => ({ name })),
+      secretGuardrails: policy.secrets.guardrails,
     },
     /** The projected path, not the running install's: a wrap may be another mate's. */
     { wrapperBinPath: projection.wrapperBinPath },

package/src/runtime/runtime-document-manifest.ts

@@ -62,6 +62,30 @@ export interface RenderedRuntimeDocument {
   readonly regions: readonly ManagedRegion[];
 }
 
+/** What a working-target render returns: its warnings are data for the caller, never printed. */
+export interface RenderedRuntimeDocuments {
+  documents: RenderedRuntimeDocument[];
+  warnings: string[];
+}
+
+function nonEmpty(region: ManagedRegion): boolean {
+  if (region.kind === "list") return region.values.length > 0;
+  /** A stripping map still heals what an older Mate left, with no entry of its own. */
+  if (region.kind === "map") {
+    return Object.keys(region.entries).length > 0 || region.stripPrefix !== undefined;
+  }
+  return true;
+}
+
+/** One rendered document of its non-empty regions, or none when every region is empty. */
+export function renderedDocument(
+  documentPath: string,
+  regions: ManagedRegion[],
+): RenderedRuntimeDocument[] {
+  const kept = regions.filter(nonEmpty);
+  return kept.length > 0 ? [{ path: documentPath, regions: kept }] : [];
+}
+
 /** An owned companion copy: the hash of what Mate last wrote there. */
 export interface CopyRecord {
   runtime: WrapRuntime;
@@ -80,8 +104,6 @@ export interface Manifest {
   readonly runtimes: Readonly<Record<string, WrapRuntime>>;
   readonly copies: Readonly<Record<string, CopyRecord>>;
   readonly links: Readonly<Record<string, LinkRecord>>;
-  /** The audience `mate wrap --audience` recorded; the only source of a bare session's audience. */
-  readonly audience?: string;
 }
 
 export const EMPTY_MANIFEST: Manifest = Object.freeze({
@@ -126,23 +148,9 @@ function manifestOf(parsed: Record<string, unknown>): Manifest {
     runtimes: isRecord(parsed.runtimes) ? (parsed.runtimes as Manifest["runtimes"]) : {},
     copies: isRecord(parsed.copies) ? (parsed.copies as Manifest["copies"]) : {},
     links: isRecord(parsed.links) ? (parsed.links as Manifest["links"]) : {},
-    ...(typeof parsed.audience === "string" && parsed.audience
-      ? { audience: parsed.audience }
-      : {}),
   };
 }
 
-/** The audience the checkout is wrapped for; `null` for base only. */
-export function recordedAudience(manifest: Manifest): string | null {
-  return manifest.audience ?? null;
-}
-
-/** Records the checkout's audience, or none with `null`. */
-export function withAudience(manifest: Manifest, audience: string | null): Manifest {
-  const { audience: _previous, ...rest } = manifest;
-  return audience ? { ...rest, audience } : rest;
-}
-
 function recordedRuntime(manifest: Manifest, documentPath: string): WrapRuntime {
   return manifest.runtimes[documentPath] ?? documentRuntime(documentPath);
 }
@@ -166,7 +174,6 @@ export function serializeManifest(manifest: Manifest): string | null {
       ...(recorded.length > 0 ? { runtimes } : {}),
       ...(copied.length > 0 ? { copies: manifest.copies } : {}),
       ...(linked.length > 0 ? { links: manifest.links } : {}),
-      ...(manifest.audience ? { audience: manifest.audience } : {}),
     },
     null,
     2,
@@ -202,14 +209,24 @@ export function copies(manifest: Manifest, runtime?: WrapRuntime): Record<string
   );
 }
 
+/** Narrows link records to one link root, e.g. `.claude/skills/`. */
+export interface LinkScope {
+  prefix?: string;
+}
+
 /** Links Mate created, keyed by repo-relative POSIX path. */
-export function links(manifest: Manifest, runtime?: WrapRuntime): Record<string, LinkRecord> {
+export function links(
+  manifest: Manifest,
+  runtime?: WrapRuntime,
+  scope: LinkScope = {},
+): Record<string, LinkRecord> {
   return Object.fromEntries(
     Object.entries(manifest.links).filter(
-      ([, record]) =>
+      ([key, record]) =>
         isRecord(record) &&
         typeof record.target === "string" &&
-        (!runtime || record.runtime === runtime),
+        (!runtime || record.runtime === runtime) &&
+        key.startsWith(scope.prefix ?? ""),
     ),
   );
 }
@@ -232,11 +249,23 @@ export function recordedMapKeys(
   documentPath: string,
   at: readonly string[],
 ): string[] {
-  return (documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
-    isRecord(region) && region.kind === "map" && isAt(region.at, at) && isRecord(region.entries)
-      ? Object.keys(region.entries)
-      : [],
-  );
+  return Object.keys(recordedMapEntries(manifest, documentPath, at));
+}
+
+/** The entries of the `map` regions recorded at `at` in one document, checked like {@link recordedMapKeys}. */
+export function recordedMapEntries(
+  manifest: Manifest,
+  documentPath: string,
+  at: readonly string[],
+): Record<string, unknown> {
+  return Object.assign(
+    {},
+    ...(documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
+      isRecord(region) && region.kind === "map" && isAt(region.at, at) && isRecord(region.entries)
+        ? [region.entries]
+        : [],
+    ),
+  ) as Record<string, unknown>;
 }
 
 /** Every value of the `list` regions recorded under `prefix` in one document. */
@@ -279,14 +308,15 @@ export function withoutDocuments(manifest: Manifest, documentPaths: readonly str
   };
 }
 
-/** Replaces one runtime's records, leaving every other record as it is. */
+/** Replaces one runtime's records under `prefix`, leaving every other record as it is. */
 function replaceRuntimeRecords<T>(
   existing: Readonly<Record<string, T>>,
   runtime: WrapRuntime,
   records: Readonly<Record<string, T>>,
+  prefix = "",
 ): Record<string, T> {
   const kept = Object.entries(existing).filter(
-    ([, record]) => !(isRecord(record) && record.runtime === runtime),
+    ([key, record]) => !(isRecord(record) && record.runtime === runtime && key.startsWith(prefix)),
   );
   return { ...Object.fromEntries(kept), ...records };
 }
@@ -303,8 +333,12 @@ export function withLinks(
   manifest: Manifest,
   runtime: WrapRuntime,
   records: Readonly<Record<string, LinkRecord>>,
+  scope: LinkScope = {},
 ): Manifest {
-  return { ...manifest, links: replaceRuntimeRecords(manifest.links, runtime, records) };
+  return {
+    ...manifest,
+    links: replaceRuntimeRecords(manifest.links, runtime, records, scope.prefix),
+  };
 }
 
 export function manifestPath(repoPath: string): string {