@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/tools/setup/audience-layer.ts

@@ -0,0 +1,207 @@
+// oxlint-disable no-await-in-loop
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { getActiveDistribution } from "../../distribution";
+import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import {
+  audienceLayerDir,
+  audienceLayersRoot,
+  CURRENT_LAYER_LINK,
+} from "../../runtime/audience-layer";
+import {
+  dynamicPluginsWorkspaceRoot,
+  pluginLocalOverridesPath,
+  pluginPackageRoot,
+} from "./dynamic-plugins/paths";
+import { collectAudienceInputs, RUNTIME_SURFACE_RECONCILERS } from "./engine";
+import type { PluginRegistration, SetupContext } from "./plugin";
+import { projectionTarget } from "./surface-target";
+
+/**
+ * Writes the active audience's layer through each runtime's Runtime Surface,
+ * under the pass's layer root only. Refuses any other target, and a pass that
+ * names no audience.
+ */
+export async function reconcileAudienceLayer(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+): Promise<void> {
+  if (projectionTarget(ctx) !== "audience-layer") {
+    throw new Error("an audience layer is reconciled with the audience-layer target only");
+  }
+  for (const [runtimeId, inputs] of await collectAudienceInputs(
+    ctx,
+    registrations,
+    ctx.audience!,
+  )) {
+    const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
+    if (!reconcile || inputs.length === 0) continue;
+    await reconcile(ctx, inputs);
+  }
+}
+
+/** Bumped when the layout a layer pass writes changes, so old layers are re-rendered. */
+const LAYER_FORMAT = 1;
+
+/** A render that never finished, or a superseded layer, is left this long for sessions still reading it. */
+const STALE_LAYER_MS = 24 * 60 * 60 * 1000;
+
+const FINGERPRINT_FILE = ".fingerprint";
+
+export interface AudienceLayerRequest {
+  companionPath: string;
+  config: FrameworkConfig;
+  audience: string;
+  /** The Agent Runtimes the layer is rendered for. */
+  activeProviders: string[];
+  /** The process's registrations; only the audience's own are rendered. */
+  registrations: PluginRegistration[];
+  homeDir?: string;
+}
+
+export interface RenderedAudienceLayer {
+  audience: string;
+  /** The complete layer a launch attaches; never changed once in place. */
+  root: string;
+  /** False when an unchanged layer was reused. */
+  rendered: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The installed version of each package, from the committed lockfile, else the installed manifest. */
+async function lockedVersions(
+  companionPath: string,
+  packages: string[],
+): Promise<Record<string, string | null>> {
+  const lock = await fs
+    .readFile(path.join(dynamicPluginsWorkspaceRoot(companionPath), "package-lock.json"), "utf8")
+    .then((text) => JSON.parse(text) as unknown)
+    .catch(() => null);
+  const lockPackages = isRecord(lock) && isRecord(lock.packages) ? lock.packages : {};
+  const versions: Record<string, string | null> = {};
+  for (const name of packages.toSorted()) {
+    const locked = lockPackages[`node_modules/${name}`];
+    if (isRecord(locked) && typeof locked.version === "string") {
+      versions[name] = locked.version;
+      continue;
+    }
+    const manifest = await fs
+      .readFile(path.join(pluginPackageRoot(companionPath, name), "package.json"), "utf8")
+      .then((text) => JSON.parse(text) as unknown)
+      .catch(() => null);
+    versions[name] =
+      isRecord(manifest) && typeof manifest.version === "string" ? manifest.version : null;
+  }
+  return versions;
+}
+
+/**
+ * What a layer depends on: the audience's declaration, the installed versions
+ * of its packages, the local plugin overrides, the Mate version and the active
+ * runtimes. Anything else changing leaves the layer as it is.
+ */
+export async function audienceLayerFingerprint(request: AudienceLayerRequest): Promise<string> {
+  const entry = request.config.audiences?.[request.audience] ?? null;
+  const packages = (entry?.plugins ?? []).map((declaration) => declaration.package);
+  const overrides = await fs
+    .readFile(pluginLocalOverridesPath(request.companionPath), "utf8")
+    .catch(() => null);
+  const inputs = {
+    format: LAYER_FORMAT,
+    audience: request.audience,
+    entry,
+    versions: await lockedVersions(request.companionPath, packages),
+    overrides,
+    mate: getActiveDistribution().config.version,
+    runtimes: [...new Set(request.activeProviders)].toSorted(),
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(inputs)).digest("hex").slice(0, 24);
+}
+
+async function exists(target: string): Promise<boolean> {
+  return fs
+    .access(target)
+    .then(() => true)
+    .catch(() => false);
+}
+
+/** Points `current` at `fingerprint` with one rename, so a reader never finds it missing. */
+async function pointCurrentAt(dir: string, fingerprint: string): Promise<void> {
+  const link = path.join(dir, CURRENT_LAYER_LINK);
+  if ((await fs.readlink(link).catch(() => null)) === fingerprint) return;
+  const staged = path.join(dir, `.${CURRENT_LAYER_LINK}-${crypto.randomUUID()}`);
+  await fs.symlink(fingerprint, staged);
+  await fs.rename(staged, link);
+}
+
+/** Superseded layers and abandoned renders, once no session can still be starting from them. */
+async function pruneStaleLayers(dir: string, keep: string): Promise<void> {
+  const now = Date.now();
+  for (const name of await fs.readdir(dir).catch(() => [])) {
+    /** Launch settings files live here too; each launch rewrites its own. */
+    if (name === keep || name === CURRENT_LAYER_LINK || name.startsWith("launch-")) continue;
+    const target = path.join(dir, name);
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat || now - stat.mtimeMs < STALE_LAYER_MS) continue;
+    await fs.rm(target, { recursive: true, force: true });
+  }
+}
+
+/** Creates the layers root and every level below it for the current user only. */
+async function ensurePrivateDir(root: string, dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  for (let level = dir; level.startsWith(root); level = path.dirname(level)) {
+    await fs.chmod(level, 0o700);
+    if (level === root) break;
+  }
+}
+
+/**
+ * Renders the audience's layer, or reuses it when nothing it depends on
+ * changed. A render is built in a private staging directory and renamed into a
+ * directory named by its fingerprint, so a reader sees a complete layer or
+ * none; concurrent renders of the same inputs agree on one result.
+ */
+export async function renderAudienceLayer(
+  request: AudienceLayerRequest,
+): Promise<RenderedAudienceLayer> {
+  const dir = audienceLayerDir(request.companionPath, request.audience, request.homeDir);
+  const fingerprint = await audienceLayerFingerprint(request);
+  const root = path.join(dir, fingerprint);
+
+  await ensurePrivateDir(audienceLayersRoot(request.homeDir), dir);
+  if (await exists(path.join(root, FINGERPRINT_FILE))) {
+    await pointCurrentAt(dir, fingerprint);
+    return { audience: request.audience, root, rendered: false };
+  }
+
+  const staging = await fs.mkdtemp(path.join(dir, ".render-"));
+  try {
+    await reconcileAudienceLayer(
+      {
+        companionPath: request.companionPath,
+        config: request.config,
+        mode: "sync",
+        activeProviders: request.activeProviders,
+        target: "audience-layer",
+        audience: request.audience,
+        layerRoot: staging,
+      },
+      request.registrations,
+    );
+    await fs.writeFile(path.join(staging, FINGERPRINT_FILE), `${fingerprint}\n`, "utf8");
+    await fs.rename(staging, root);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    /** Another launch renamed the same inputs into place first: its layer is this one. */
+    if (!(await exists(path.join(root, FINGERPRINT_FILE)))) throw error;
+  }
+  await pointCurrentAt(dir, fingerprint);
+  await pruneStaleLayers(dir, fingerprint);
+  return { audience: request.audience, root, rendered: true };
+}

package/src/tools/setup/audience-registrations.ts

@@ -0,0 +1,52 @@
+// oxlint-disable no-await-in-loop
+import { getActiveDistribution } from "../../distribution";
+import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import { validateDeclaration } from "./dynamic-plugins/declarations";
+import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./dynamic-plugins/loader";
+import type { PluginRegistry, NormalizedRegistration } from "./registry";
+
+export interface LoadedAudience {
+  registrations: NormalizedRegistration[];
+  warnings: string[];
+}
+
+/**
+ * The registrations of one named audience, independent of `MATE_AUDIENCE`: a
+ * plugin this process already hydrated is reused, any other is loaded for its
+ * declarations only — never activated, no lifecycle hook run. Used where the
+ * audience comes from a checkout's wrap rather than the environment.
+ */
+export async function loadAudienceRegistrations(
+  companionPath: string,
+  config: FrameworkConfig,
+  audience: string,
+  registry: PluginRegistry = getActiveDistribution().registry,
+  deps: DynamicPluginLoadDeps = {},
+): Promise<LoadedAudience> {
+  const loaded: LoadedAudience = { registrations: [], warnings: [] };
+  const hydrated = registry.getEntries();
+  for (const entry of config.audiences?.[audience]?.plugins ?? []) {
+    const { declaration, error } = validateDeclaration(entry);
+    if (!declaration) {
+      if (error) loaded.warnings.push(error);
+      continue;
+    }
+    const known = hydrated.find((candidate) => candidate.packageName === declaration.package);
+    if (known) {
+      loaded.registrations.push({ ...known, audience });
+      continue;
+    }
+    const result = await loadDynamicPlugin(companionPath, declaration, deps);
+    if (!result.ok) {
+      loaded.warnings.push(`audience "${audience}": ${result.warning}`);
+      continue;
+    }
+    loaded.registrations.push({
+      plugin: result.plugin,
+      policy: "required",
+      audience,
+      packageName: declaration.package,
+    });
+  }
+  return loaded;
+}

package/src/tools/setup/capabilities/openspec.ts

@@ -66,6 +66,13 @@ const OPENSPEC_TOOLS_BY_RUNTIME = {
 
 const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
 
+/**
+ * Store metadata `openspec store register` writes beside the companion. Its id
+ * is machine-local, and companion Git sync would otherwise stash it on every
+ * launch. Persisted: the registration outlives the capability.
+ */
+const OPENSPEC_GITIGNORE_ENTRIES = [".openspec-store/"];
+
 type OpenSpecTool =
   (typeof OPENSPEC_TOOLS_BY_RUNTIME)[keyof typeof OPENSPEC_TOOLS_BY_RUNTIME][number];
 type OpenSpecRunCommand = typeof runCommandSilently;
@@ -394,6 +401,8 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
         },
       };
     },
+    gitignoreEntries: () => OPENSPEC_GITIGNORE_ENTRIES,
+    persistGitignoreEntries: true,
     getInstallRequirements: (): InstallRequirement[] => [
       {
         id: "capability:openspec",

package/src/tools/setup/capabilities/tokensave.ts

@@ -14,6 +14,8 @@ export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
 export const TOKENSAVE_STORE_CONFIG_FILE = "config.json";
+/** The index itself: `tokensave sync` refuses a store without it. */
+const TOKENSAVE_STORE_DATABASE_FILE = "tokensave.db";
 export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
 /** Single-graph posture Mate owns in the per-project store config; every other key is left as found. */
 const TOKENSAVE_OWNED_POSTURE = { auto_track: false, suppress_scope_warning: true } as const;
@@ -357,6 +359,15 @@ async function deactivateTokensaveBranchMetadata(repoPath: string): Promise<void
   }
 }
 
+/**
+ * Whether the working repo holds a TokenSave index `tokensave sync` accepts.
+ * The database, not the store folder: an empty or half-initialized
+ * `.tokensave/` must still get `tokensave init`, or every pass fails on sync.
+ */
+export async function isTokensaveIndexed(repoPath: string): Promise<boolean> {
+  return fileExists(path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_DATABASE_FILE));
+}
+
 /**
  * Reconciles Mate's single-graph branching posture into the working repo's
  * git-excluded `.tokensave/config.json` and deactivates existing branch

package/src/tools/setup/contribution-ledger.ts

@@ -0,0 +1,207 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { writeAtomic } from "../../runtime/write-atomic";
+import { instructionBlockKey } from "./context-services";
+import type { CapabilityContributionInput, RuntimeContributions } from "./plugin";
+
+/**
+ * Contribution Ledger: which plugin owns each contribution a persisted pass
+ * applied to the companion, per Agent Runtime. Committed with the companion,
+ * because it describes committed files: a clone that never loaded a plugin
+ * must still be able to remove what another clone committed. It records
+ * identities only (names, block keys, markers, entries), never a value, so it
+ * carries no secret.
+ */
+
+export const CONTRIBUTION_LEDGER_VERSION = 1;
+
+/** The identities one owner applied on one runtime. Absent kinds are none. */
+export interface LedgerIdentities {
+  mcpServers?: string[];
+  guidanceKeys?: string[];
+  skillTrees?: string[];
+  agentDefinitions?: string[];
+  hookMarkers?: string[];
+  permissionEntries?: string[];
+  pluginReferences?: string[];
+}
+
+export interface ContributionLedger {
+  version: number;
+  /** Runtime id → owning plugin id → identities. */
+  runtimes: Record<string, Record<string, LedgerIdentities>>;
+  /** Audience plugin packages the upgrade sweep could not load; retried by every pass. */
+  unswept?: string[];
+}
+
+export function contributionLedgerPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "contribution-ledger.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+
+const IDENTITY_KINDS = [
+  "agentDefinitions",
+  "guidanceKeys",
+  "hookMarkers",
+  "mcpServers",
+  "permissionEntries",
+  "pluginReferences",
+  "skillTrees",
+] as const satisfies readonly (keyof LedgerIdentities)[];
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].toSorted();
+}
+
+/** Sorted kinds and values, empty kinds dropped; `null` when nothing is left. */
+function normalizeIdentities(identities: LedgerIdentities): LedgerIdentities | null {
+  const normalized: LedgerIdentities = {};
+  for (const kind of IDENTITY_KINDS) {
+    const values = sortedUnique(identities[kind] ?? []);
+    if (values.length > 0) normalized[kind] = values;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+/** Sorted runtimes and owners; empty owners and runtimes dropped. */
+function normalizeLedger(ledger: ContributionLedger): ContributionLedger {
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const runtimeId of Object.keys(ledger.runtimes).toSorted()) {
+    const owners: Record<string, LedgerIdentities> = {};
+    for (const owner of Object.keys(ledger.runtimes[runtimeId] ?? {}).toSorted()) {
+      const identities = normalizeIdentities(ledger.runtimes[runtimeId]![owner]!);
+      if (identities) owners[owner] = identities;
+    }
+    if (Object.keys(owners).length > 0) runtimes[runtimeId] = owners;
+  }
+  const unswept = sortedUnique(ledger.unswept ?? []);
+  return {
+    version: CONTRIBUTION_LEDGER_VERSION,
+    runtimes,
+    ...(unswept.length > 0 ? { unswept } : {}),
+  };
+}
+
+/** The companion's ledger; `null` when absent or unreadable, which a pass treats as never recorded. */
+export async function readContributionLedger(
+  companionPath: string,
+): Promise<ContributionLedger | null> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await fs.readFile(contributionLedgerPath(companionPath), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.runtimes)) return null;
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const [runtimeId, owners] of Object.entries(parsed.runtimes)) {
+    if (!isRecord(owners)) continue;
+    runtimes[runtimeId] = {};
+    for (const [owner, identities] of Object.entries(owners)) {
+      if (!isRecord(identities)) continue;
+      const read: LedgerIdentities = {};
+      for (const kind of IDENTITY_KINDS) read[kind] = stringList(identities[kind]);
+      runtimes[runtimeId][owner] = read;
+    }
+  }
+  return normalizeLedger({
+    version: CONTRIBUTION_LEDGER_VERSION,
+    runtimes,
+    unswept: stringList(parsed.unswept),
+  });
+}
+
+/** Writes the ledger in its stable form; an unchanged ledger leaves the file untouched. */
+export async function writeContributionLedger(
+  companionPath: string,
+  ledger: ContributionLedger,
+): Promise<void> {
+  const target = contributionLedgerPath(companionPath);
+  const text = `${JSON.stringify(normalizeLedger(ledger), null, 2)}\n`;
+  const existing = await fs.readFile(target, "utf8").catch(() => null);
+  if (existing === text) return;
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeAtomic(target, text);
+}
+
+/** The identities a contribution set applies for `pluginId`. */
+export function identitiesOf(
+  pluginId: string,
+  contributions: RuntimeContributions,
+): LedgerIdentities {
+  return {
+    mcpServers: (contributions.mcpServers ?? []).map((server) => server.name),
+    guidanceKeys: (contributions.guidanceSections ?? []).map((section) =>
+      instructionBlockKey(pluginId, section.content),
+    ),
+    skillTrees: (contributions.skillTrees ?? []).map((tree) => tree.name),
+    agentDefinitions: (contributions.agentDefinitions ?? []).map((agent) => agent.name),
+    hookMarkers: (contributions.hookGroups ?? []).map((hook) => hook.marker),
+    permissionEntries: [...(contributions.permissionEntries ?? [])],
+    pluginReferences: (contributions.pluginReferences ?? []).map((entry) => entry.reference),
+  };
+}
+
+/** The ledger a pass leaves: what its enabled inputs applied, per runtime and owner. */
+export function ledgerFromInputs(
+  inputsByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
+  unswept: readonly string[] = [],
+): ContributionLedger {
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const [runtimeId, inputs] of inputsByRuntime) {
+    const owners: Record<string, LedgerIdentities> = {};
+    for (const input of inputs) {
+      if (!input.enabled) continue;
+      const identities = identitiesOf(input.pluginId, input.contributions);
+      const merged = owners[input.pluginId] ?? {};
+      for (const kind of IDENTITY_KINDS) {
+        merged[kind] = [...(merged[kind] ?? []), ...(identities[kind] ?? [])];
+      }
+      owners[input.pluginId] = merged;
+    }
+    runtimes[runtimeId] = owners;
+  }
+  return normalizeLedger({ version: CONTRIBUTION_LEDGER_VERSION, runtimes, unswept: [...unswept] });
+}
+
+/**
+ * A disabled input naming every recorded identity of `owner`, so each Runtime
+ * Surface removes them through its existing disabled-input path. Removal keys
+ * on identity only, so no value is needed: guidance is stripped by owner, a
+ * hook group by its marker, a plugin reference by its exact entry.
+ */
+export function ledgerTeardownInput(
+  owner: string,
+  identities: LedgerIdentities,
+): CapabilityContributionInput {
+  return {
+    pluginId: owner,
+    enabled: false,
+    capabilityEnabled: false,
+    contributions: {
+      mcpServers: (identities.mcpServers ?? []).map((name) => ({ name })),
+      guidanceSections: (identities.guidanceKeys ?? []).length > 0 ? [{ content: "" }] : [],
+      skillTrees: (identities.skillTrees ?? []).map((name) => ({ name, sourceDir: "" })),
+      agentDefinitions: (identities.agentDefinitions ?? []).map((name) => ({ name, content: "" })),
+      hookGroups: (identities.hookMarkers ?? []).map((marker) => ({
+        event: "",
+        marker,
+        group: {},
+      })),
+      permissionEntries: [...(identities.permissionEntries ?? [])],
+      pluginReferences: (identities.pluginReferences ?? []).map((reference) => ({
+        reference,
+        isManagedReference: (entry: unknown) => entry === reference,
+      })),
+    },
+  };
+}

package/src/tools/setup/dynamic-plugins/audiences.ts

@@ -4,10 +4,16 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "../../../framework";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { ConfigError, type PluginDeclaration } from "../../../lib/orchestrator/types";
 
 export const AUDIENCE_ENV = "MATE_AUDIENCE";
 
+/** The reserved audience holding the base set: always applied, never selected or listed. */
+export const BASE_AUDIENCE = "base";
+
+/** The base set's audience-scoped keys; companion-wide keys stay at the root. */
+export const BASE_AUDIENCE_KEYS = ["capabilities", "plugins", "studio"] as const;
+
 export type AudienceResolution =
   | { ok: true; active: string | null }
   | { ok: false; requested: string; declared: string[] };
@@ -17,11 +23,19 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function pluginList(value: unknown): unknown[] {
+  if (
+    isRecord(value) &&
+    isRecord(value.audiences) &&
+    Object.hasOwn(value.audiences, BASE_AUDIENCE)
+  ) {
+    return pluginList(normalizeBaseAudience(value));
+  }
   return isRecord(value) && Array.isArray(value.plugins) ? value.plugins : [];
 }
 
 function audienceEntry(raw: unknown, audience: string | null): unknown {
-  if (audience === null || !isRecord(raw) || !isRecord(raw.audiences)) return undefined;
+  if (audience === null || audience === BASE_AUDIENCE) return undefined;
+  if (!isRecord(raw) || !isRecord(raw.audiences)) return undefined;
   return Object.hasOwn(raw.audiences, audience) ? raw.audiences[audience] : undefined;
 }
 
@@ -32,6 +46,38 @@ function studioAgent(value: unknown): unknown {
   return value.studio.terminal.agent;
 }
 
+/**
+ * The base set at the root, whichever shape the file uses: `audiences.base`
+ * keys are lifted to the root and `base` leaves `audiences`. A file in the
+ * root shape is returned as it is. Throws when a key is declared in both
+ * places, or `audiences.base` holds a key the base set does not have.
+ */
+export function normalizeBaseAudience<T>(raw: T): T {
+  if (!isRecord(raw) || !isRecord(raw.audiences) || !Object.hasOwn(raw.audiences, BASE_AUDIENCE)) {
+    return raw;
+  }
+  const { [BASE_AUDIENCE]: baseEntry, ...others } = raw.audiences;
+  const lifted: Record<string, unknown> = { ...raw };
+  if (isRecord(baseEntry)) {
+    for (const [key, value] of Object.entries(baseEntry)) {
+      if (!(BASE_AUDIENCE_KEYS as readonly string[]).includes(key)) {
+        throw new ConfigError(
+          `audiences.${BASE_AUDIENCE} may contain only ${BASE_AUDIENCE_KEYS.join(", ")}; "${key}" belongs at the root of framework.yaml.`,
+        );
+      }
+      if (Object.hasOwn(raw, key)) {
+        throw new ConfigError(
+          `"${key}" is declared both at the root of framework.yaml and under audiences.${BASE_AUDIENCE}; keep one.`,
+        );
+      }
+      lifted[key] = value;
+    }
+  }
+  if (Object.keys(others).length > 0) lifted.audiences = others;
+  else delete lifted.audiences;
+  return lifted as T;
+}
+
 /** `MATE_AUDIENCE` from the environment; unset, empty or blank means none. */
 export function readAudienceSelection(env: Record<string, string | undefined>): string | null {
   const value = env[AUDIENCE_ENV]?.trim();
@@ -40,11 +86,14 @@ export function readAudienceSelection(env: Record<string, string | undefined>):
 
 /** Audience names declared by raw parsed `framework.yaml`, in declared order. */
 export function declaredAudiences(raw: unknown): string[] {
-  return isRecord(raw) && isRecord(raw.audiences) ? Object.keys(raw.audiences) : [];
+  return isRecord(raw) && isRecord(raw.audiences)
+    ? Object.keys(raw.audiences).filter((name) => name !== BASE_AUDIENCE)
+    : [];
 }
 
+/** `MATE_AUDIENCE=base` selects the base set alone, the same as no audience. */
 export function resolveAudience(raw: unknown, audience: string | null): AudienceResolution {
-  if (audience === null) return { ok: true, active: null };
+  if (audience === null || audience === BASE_AUDIENCE) return { ok: true, active: null };
   const declared = declaredAudiences(raw);
   if (declared.includes(audience)) return { ok: true, active: audience };
   return { ok: false, requested: audience, declared };
@@ -58,6 +107,33 @@ export function effectivePluginDeclarations(raw: unknown, audience: string | nul
   return [...pluginList(raw), ...pluginList(audienceEntry(raw, audience))];
 }
 
+/** One effective declaration and its source: `null` for base, else the audience name. */
+export interface SourcedDeclaration {
+  entry: unknown;
+  audience: string | null;
+}
+
+/** `effectivePluginDeclarations`, each entry marked with the source that declared it. */
+export function effectivePluginDeclarationSources(
+  raw: unknown,
+  audience: string | null,
+): SourcedDeclaration[] {
+  return [
+    ...pluginList(raw).map((entry) => ({ entry, audience: null })),
+    ...pluginList(audienceEntry(raw, audience)).map((entry) => ({ entry, audience })),
+  ];
+}
+
+/** The declarations of one audience only, without base. */
+export function audiencePluginDeclarations(raw: unknown, audience: string): unknown[] {
+  return pluginList(audienceEntry(raw, audience));
+}
+
+/** The raw `audiences.<name>` entry, for fingerprinting what a layer depends on. */
+export function audienceDeclarationEntry(raw: unknown, audience: string): unknown {
+  return audienceEntry(raw, audience);
+}
+
 /**
  * Base plugins followed by every audience's, for installation only: a
  * package shared by audiences appears once since validation guarantees one
@@ -96,24 +172,28 @@ export function installPluginDeclarations(config: unknown): PluginDeclaration[]
  * as found: the caller owns rejecting a value that is not a safe name.
  */
 export function effectiveStudioAgent(raw: unknown, audience: string | null): unknown {
-  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(raw);
+  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(normalizeBaseAudience(raw));
 }
 
 /**
- * Raw read of the companion's `framework.yaml`. Deliberately avoids
- * `ConfigStore.load()` — hydration runs on every invocation and must never
- * create or migrate config files as a side effect.
+ * Raw read of the companion's `framework.yaml`, the base set at the root
+ * whichever shape the file uses. Deliberately avoids `ConfigStore.load()` —
+ * hydration runs on every invocation and must never create or migrate config
+ * files as a side effect.
  */
 export async function readFrameworkRaw(companionPath: string): Promise<unknown> {
+  let raw: unknown;
   try {
     const text = await fs.readFile(
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    return (parse(text) as unknown) ?? null;
+    raw = (parse(text) as unknown) ?? null;
   } catch {
     return null;
   }
+  /** Outside the catch: a base key in both places is the operator's to fix, never silently base-less. */
+  return normalizeBaseAudience(raw);
 }
 
 export async function readEffectiveDeclarations(