@uniqbit/mate-core 0.18.3 → 0.18.4

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

@@ -6,13 +6,14 @@ import { parse } from "yaml";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { normalizeBaseAudience } from "./audiences";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /**
- * Raw read of the companion's `plugins:` list. Deliberately avoids
+ * Raw read of the companion's base `plugins:` list, from either shape. Deliberately avoids
  * `ConfigStore.load()` — hydration runs on every invocation and must never
  * create or migrate config files as a side effect.
  */
@@ -22,7 +23,7 @@ export async function readDeclarations(companionPath: string): Promise<unknown[]
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    const parsed = parse(raw) as unknown;
+    const parsed = normalizeBaseAudience(parse(raw) as unknown);
     if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
     return parsed.plugins;
   } catch {

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

@@ -9,7 +9,7 @@ import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
 import {
   describeUnknownAudience,
-  effectivePluginDeclarations,
+  effectivePluginDeclarationSources,
   readAudienceSelection,
   readFrameworkRaw,
   resolveAudience,
@@ -71,7 +71,8 @@ function activateDeclaredPlugin(plugin: Plugin): Plugin {
 /**
  * Registers the companion's effective plugins (base plus the active
  * `MATE_AUDIENCE`) into the active registry — compiled-in plugins first
- * (they are already registered), declared order after. Runs before cap-command detection on every invocation. No-op
+ * (they are already registered), declared order after. Each registration is
+ * marked with its source, so persisted passes can keep to base. Runs before cap-command detection on every invocation. No-op
  * without a companion or `plugins:` entries; all diagnostics go to stderr;
  * never throws.
  */
@@ -89,12 +90,12 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
     if (!audience.ok) {
       warn(`${describeUnknownAudience(audience)}; applying the base configuration only`);
     }
-    const entries = effectivePluginDeclarations(raw, audience.ok ? audience.active : null);
+    const entries = effectivePluginDeclarationSources(raw, audience.ok ? audience.active : null);
     if (entries.length === 0) return;
 
     const registry = deps.registry ?? getActiveDistribution().registry;
 
-    for (const entry of entries) {
+    for (const { entry, audience: source } of entries) {
       const { declaration, error } = validateDeclaration(entry);
       if (!declaration) {
         if (error) warn(error);
@@ -122,6 +123,8 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
       registry.register({
         plugin: activateDeclaredPlugin(result.plugin),
         policy: declaration.policy ?? "optional",
+        audience: source,
+        packageName: declaration.package,
       });
       hydratedPackages.add(declaration.package);
     }

package/src/tools/setup/engine.ts

@@ -4,6 +4,13 @@ import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
 import type { RenderedRuntimeDocument } from "../../runtime/runtime-document-manifest";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
+import {
+  ledgerFromInputs,
+  ledgerTeardownInput,
+  readContributionLedger,
+  writeContributionLedger,
+  type ContributionLedger,
+} from "./contribution-ledger";
 import type {
   CapabilityContributionInput,
   CapabilityPlugin,
@@ -15,6 +22,8 @@ import { reconcileClaudeContributions } from "./providers/claude";
 import { reconcileOpenCodeContributions } from "./providers/opencode";
 import { mergeCompanionOpenCodeConfig, renderDocumentsForTarget } from "./runtime-documents";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
+import { surfaceRoot } from "./surface-target";
+import { removeForeignGuidanceBlocks, sweepAudienceDeclarations } from "./upgrade-sweep";
 
 export interface SetupInstallationPlanAction {
   phase: Plugin["kind"];
@@ -35,11 +44,23 @@ export interface SetupInstallationOutcome {
   warnings: string[];
 }
 
+/**
+ * The registrations a pass that writes a persisted surface may reconcile:
+ * base only. An audience registration takes part in no such pass — neither
+ * its lifecycle hooks nor its declared contributions — whatever audience is
+ * active; its contributions reach sessions only through the launch layer.
+ */
+export function persistedRegistrations(
+  registrations: PluginRegistration[],
+): NormalizedRegistration[] {
+  return registrations.map(normalizeRegistration).filter((entry) => entry.audience === null);
+}
+
 export function buildSetupInstallationPlan(
   config: FrameworkConfig,
   registrations: PluginRegistration[],
 ): SetupInstallationPlan {
-  const entries = registrations.map(normalizeRegistration);
+  const entries = persistedRegistrations(registrations);
   // Required plugins are always treated as enabled: saved selections cannot
   // deselect them and deselection never produces a teardown action.
   const isEntryEnabled = (entry: NormalizedRegistration) =>
@@ -109,7 +130,7 @@ export async function executeSetupInstallationPlan(
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
 ): Promise<SetupInstallationOutcome> {
-  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
+  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
   const pluginById = new Map(plugins.map((plugin) => [plugin.id, plugin]));
   const executedActions: SetupInstallationPlanAction[] = [];
   const skippedActions: SetupInstallationPlanAction[] = [];
@@ -176,13 +197,22 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
-  await reconcileCapabilityContributions(ctx, plugins, plan);
+  const reconcileWarnings = await reconcileCapabilityContributions(
+    ctx,
+    plugins,
+    plan,
+    registrations.map(normalizeRegistration),
+  );
+  for (const warning of reconcileWarnings) {
+    warnings.push(warning);
+    process.stderr.write(`${warning}\n`);
+  }
 
   return { executedActions, skippedActions, warnings };
 }
 
 // The Runtime Surface of each active Agent Runtime, by runtime id.
-const RUNTIME_SURFACE_RECONCILERS: Record<
+export const RUNTIME_SURFACE_RECONCILERS: Record<
   string,
   (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<void>
 > = {
@@ -243,13 +273,104 @@ async function reconcileCapabilityContributions(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
-): Promise<void> {
+  registrations: NormalizedRegistration[],
+): Promise<string[]> {
   const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
+  const ledgerRoot = surfaceRoot(ctx);
+  const ledger = await readContributionLedger(ledgerRoot);
+  const warnings: string[] = [];
+  let unswept = ledger?.unswept ?? [];
+  if (!ledger || unswept.length > 0) {
+    if (!ledger) {
+      await removeForeignGuidanceBlocks(ledgerRoot, new Set(plugins.map((plugin) => plugin.id)));
+    }
+    const sweep = await sweepAudienceDeclarations(ctx, {
+      registrations,
+      ...(ledger ? { packages: new Set(unswept) } : {}),
+    });
+    prependTeardown(inputsByRuntime, sweep.teardown);
+    unswept = sweep.unswept;
+    warnings.push(...sweep.warnings);
+  }
+  prependLedgerTeardown(inputsByRuntime, ledger);
   for (const [runtimeId, inputs] of inputsByRuntime) {
     const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
     if (!reconcile || inputs.length === 0) continue;
     await reconcile(ctx, inputs);
   }
+  await writeContributionLedger(ledgerRoot, ledgerFromInputs(inputsByRuntime, unswept));
+  return warnings;
+}
+
+/**
+ * Disabled inputs placed first, skipping any owner that is an enabled input
+ * of the pass on that runtime: removal runs before enabled inputs apply.
+ */
+function prependTeardown(
+  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
+  teardownByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
+): void {
+  for (const [runtimeId, teardown] of teardownByRuntime) {
+    const inputs = inputsByRuntime.get(runtimeId) ?? [];
+    const enabled = new Set(inputs.filter((input) => input.enabled).map((input) => input.pluginId));
+    const kept = teardown.filter((input) => !enabled.has(input.pluginId));
+    if (kept.length > 0) inputsByRuntime.set(runtimeId, [...kept, ...inputs]);
+  }
+}
+
+/**
+ * Every recorded owner that is not an enabled input of this pass, as a
+ * disabled input placed first: its entries are removed before enabled inputs
+ * apply, so an identity another plugin still declares is re-applied after.
+ * Entries the ledger does not record are never named, so they survive.
+ */
+function prependLedgerTeardown(
+  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
+  ledger: ContributionLedger | null,
+): void {
+  prependTeardown(
+    inputsByRuntime,
+    new Map(
+      Object.entries(ledger?.runtimes ?? {}).map(([runtimeId, owners]) => [
+        runtimeId,
+        Object.entries(owners).map(([owner, identities]) => ledgerTeardownInput(owner, identities)),
+      ]),
+    ),
+  );
+}
+
+/**
+ * The declared contributions of one audience's plugins, as enabled inputs per
+ * active runtime. No plugin phase and no lifecycle hook runs: an audience
+ * plugin contributes declaratively only. OpenCode plugin references are
+ * dropped — the Mate plugin has no way to load another plugin.
+ */
+export async function collectAudienceInputs(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  audience: string,
+): Promise<Map<string, CapabilityContributionInput[]>> {
+  const inputsByRuntime = new Map<string, CapabilityContributionInput[]>();
+  for (const entry of registrations.map(normalizeRegistration)) {
+    if (entry.audience !== audience || entry.plugin.kind !== "capability") continue;
+    const capability = entry.plugin as CapabilityPlugin;
+    if (!capability.getRuntimeContributions) continue;
+    if (entry.policy !== "required" && !capability.isEnabled(ctx.config)) continue;
+    const byRuntime = await capability.getRuntimeContributions(ctx);
+    for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
+      if (!contributions || !ctx.activeProviders.includes(runtimeId)) continue;
+      const { pluginReferences: _dropped, ...declarative } = contributions;
+      const inputs = inputsByRuntime.get(runtimeId) ?? [];
+      inputs.push({
+        pluginId: capability.id,
+        enabled: true,
+        capabilityEnabled: true,
+        contributions: declarative,
+      });
+      inputsByRuntime.set(runtimeId, inputs);
+    }
+  }
+  return inputsByRuntime;
 }
 
 /** What a render returns: its warnings are data for the caller, never printed here. */
@@ -267,12 +388,22 @@ export async function renderRuntimeDocuments(
   ctx: SetupContext,
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
+  wrapped?: { audience: string; registrations: PluginRegistration[] },
 ): Promise<RenderedRuntimeDocuments> {
-  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
-  const documents = renderDocumentsForTarget(
-    ctx,
-    await collectContributionInputs(ctx, plugins, plan),
-  );
+  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
+  const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
+  /** A checkout wrapped for an audience carries it beside base; no other audience ever. */
+  if (wrapped) {
+    const audienceInputs = await collectAudienceInputs(
+      ctx,
+      wrapped.registrations,
+      wrapped.audience,
+    );
+    for (const [runtimeId, inputs] of audienceInputs) {
+      inputsByRuntime.set(runtimeId, [...(inputsByRuntime.get(runtimeId) ?? []), ...inputs]);
+    }
+  }
+  const documents = renderDocumentsForTarget(ctx, inputsByRuntime);
   if (ctx.target !== "working") return { documents, warnings: [] };
   return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
 }

package/src/tools/setup/isolation-diagnostics.ts

@@ -0,0 +1,139 @@
+// oxlint-disable no-await-in-loop
+import path from "node:path";
+
+import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import {
+  readContributionLedger,
+  type ContributionLedger,
+  type LedgerIdentities,
+} from "./contribution-ledger";
+import type { CapabilityPlugin, SetupContext } from "./plugin";
+import type { PluginRegistry } from "./registry";
+import { managedGuidanceOwners } from "./upgrade-sweep";
+
+/**
+ * What `mate doctor` reports about audience isolation: contributions on the
+ * companion's persisted surfaces that no base plugin owns, audience plugins
+ * the upgrade sweep could not load, and the active audience's plugins whose
+ * imperative parts a launch layer cannot deliver.
+ */
+
+export interface LeakedContribution {
+  /** Companion-relative file or directory. */
+  surface: string;
+  kind: string;
+  /** The entry's name; absent where the surface entry is the owner's block. */
+  identity?: string;
+  owner: string;
+}
+
+export interface UndeliveredAudiencePlugin {
+  pluginId: string;
+  /** `apply`, `teardown`, `forProvider` or `pluginReferences`. */
+  parts: string[];
+}
+
+export interface AudienceIsolationReport {
+  leaked: LeakedContribution[];
+  unswept: string[];
+  undelivered: UndeliveredAudiencePlugin[];
+}
+
+/** Ledger kinds by where each runtime keeps them; guidance is read from the files themselves. */
+const LEDGER_SURFACES: Record<string, Partial<Record<keyof LedgerIdentities, string>>> = {
+  claude: {
+    mcpServers: ".mcp.json",
+    skillTrees: path.join(".claude", "skills"),
+    agentDefinitions: path.join(".claude", "agents"),
+    hookMarkers: path.join(".claude", "settings.local.json"),
+    permissionEntries: path.join(".claude", "settings.local.json"),
+  },
+  opencode: {
+    mcpServers: path.join(".opencode", "opencode.json"),
+    pluginReferences: path.join(".opencode", "opencode.json"),
+    skillTrees: path.join(".agents", "skills"),
+    agentDefinitions: path.join(".opencode", "agents"),
+  },
+};
+
+function leakedLedgerContributions(
+  ledger: ContributionLedger | null,
+  baseIds: ReadonlySet<string>,
+): LeakedContribution[] {
+  const leaked: LeakedContribution[] = [];
+  for (const [runtimeId, owners] of Object.entries(ledger?.runtimes ?? {})) {
+    for (const [owner, identities] of Object.entries(owners)) {
+      if (baseIds.has(owner)) continue;
+      for (const [kind, surface] of Object.entries(LEDGER_SURFACES[runtimeId] ?? {})) {
+        for (const identity of identities[kind as keyof LedgerIdentities] ?? []) {
+          leaked.push({ surface: surface!, kind, identity, owner });
+        }
+      }
+    }
+  }
+  return leaked;
+}
+
+/**
+ * Whether a lifecycle hook does anything. `apply` and `teardown` are required
+ * members, so a declarative plugin carries empty ones; only a body counts.
+ */
+function hasBody(hook: unknown): boolean {
+  if (typeof hook !== "function") return false;
+  const source = Function.prototype.toString.call(hook);
+  const open = source.indexOf("{");
+  const close = source.lastIndexOf("}");
+  if (open === -1 || close <= open) return true;
+  const body = source
+    .slice(open + 1, close)
+    .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "")
+    .trim();
+  return body.length > 0;
+}
+
+async function undeliveredParts(plugin: CapabilityPlugin, ctx: SetupContext): Promise<string[]> {
+  const parts: string[] = [];
+  if (hasBody(plugin.apply)) parts.push("apply");
+  if (hasBody(plugin.teardown)) parts.push("teardown");
+  if (plugin.forProvider && Object.keys(plugin.forProvider).length > 0) parts.push("forProvider");
+  try {
+    const byRuntime = (await plugin.getRuntimeContributions?.(ctx)) ?? {};
+    if (Object.values(byRuntime).some((runtime) => (runtime?.pluginReferences ?? []).length > 0)) {
+      parts.push("pluginReferences");
+    }
+  } catch {
+    /** A plugin whose declarations fail is the plugin checks' finding, not this one. */
+  }
+  return parts;
+}
+
+export async function inspectAudienceIsolation(
+  companionPath: string,
+  config: FrameworkConfig,
+  registry: PluginRegistry,
+  activeAudience: string | null,
+): Promise<AudienceIsolationReport> {
+  const baseIds = new Set(registry.baseRegistrations().map((entry) => entry.plugin.id));
+  const leaked: LeakedContribution[] = [];
+
+  for (const [surface, owners] of await managedGuidanceOwners(companionPath)) {
+    for (const owner of owners) {
+      if (!baseIds.has(owner)) leaked.push({ surface, kind: "guidance", owner });
+    }
+  }
+
+  const ledger = await readContributionLedger(companionPath);
+  leaked.push(...leakedLedgerContributions(ledger, baseIds));
+
+  const undelivered: UndeliveredAudiencePlugin[] = [];
+  if (activeAudience) {
+    const ctx: SetupContext = { companionPath, config, mode: "sync", activeProviders: [] };
+    for (const { plugin } of registry.audienceRegistrations(activeAudience)) {
+      if (plugin.kind !== "capability") continue;
+      const parts = await undeliveredParts(plugin as CapabilityPlugin, ctx);
+      if (parts.length > 0) undelivered.push({ pluginId: plugin.id, parts });
+    }
+  }
+
+  return { leaked, unswept: ledger?.unswept ?? [], undelivered };
+}

package/src/tools/setup/plugin.ts

@@ -7,9 +7,10 @@ export type SetupScope = "companion" | "hub";
 /**
  * Where a reconcile pass lands its documents. `companion` writes the material's
  * own repository; `working` renders the documents an Agent Runtime discovers by
- * its own upward walk and leaves the placing to the Projection Root.
+ * its own upward walk and leaves the placing to the Projection Root;
+ * `audience-layer` writes one audience's launch layer, outside every repository.
  */
-export type ProjectionTarget = "companion" | "working";
+export type ProjectionTarget = "companion" | "working" | "audience-layer";
 
 export interface SetupContext {
   companionPath: string;
@@ -22,6 +23,14 @@ export interface SetupContext {
   repoPath?: string;
   /** Defaults to `companion`, so a caller that names no target is unchanged. */
   target?: ProjectionTarget;
+  /** The audience an `audience-layer` pass renders; required by that target only. */
+  audience?: string;
+  /**
+   * Where an `audience-layer` pass writes: the staging directory a render is
+   * built in before it is renamed into place. The audience's layer directory
+   * when absent.
+   */
+  layerRoot?: string;
   /**
    * Provider-mediated context services. Always populated when the engine
    * executes a plugin; optional so hand-built contexts (tests, direct calls)
@@ -122,9 +131,15 @@ export type PluginPolicy = "required" | "default" | "optional";
 
 /**
  * A plugin registration entry. Bare plugins derive their policy from
- * `defaultSelected` (`true` → "default", `false` → "optional").
+ * `defaultSelected` (`true` → "default", `false` → "optional"). `audience` is
+ * the source of a declared plugin: `null` (or absent) for compiled-in plugins
+ * and top-level `plugins` declarations, the audience name for a declaration
+ * under `audiences.<name>.plugins`. `packageName` names the declared package a
+ * dynamic plugin was loaded from.
  */
-export type PluginRegistration = Plugin | { plugin: Plugin; policy: PluginPolicy };
+export type PluginRegistration =
+  | Plugin
+  | { plugin: Plugin; policy: PluginPolicy; audience?: string | null; packageName?: string };
 
 /**
  * A hook group a Capability contributes to a runtime's settings. `marker` is

package/src/tools/setup/plugins/gitignore.ts

@@ -97,7 +97,13 @@ export function createGitignorePlugin(
 ): Plugin {
   // Resolve lazily so plugin sets can be built before a distribution is active.
   const resolveName = typeof frameworkName === "function" ? frameworkName : () => frameworkName;
-  const resolvePlugins = allPlugins ?? (() => getActiveDistribution().registry.getAll());
+  /** Base only: an audience plugin's entries would reach the committed `.gitignore`. */
+  const resolvePlugins =
+    allPlugins ??
+    (() =>
+      getActiveDistribution()
+        .registry.baseRegistrations()
+        .map((entry) => entry.plugin));
   return {
     id: "gitignore",
     kind: "root",

package/src/tools/setup/providers/claude.ts

@@ -11,7 +11,7 @@ import {
   upsertManagedBlock,
 } from "../context-services";
 import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
-import { surfaceRoot } from "../surface-target";
+import { projectionTarget, surfaceRoot } from "../surface-target";
 import { mergeDir, pruneEmptyAncestors } from "../utils";
 import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
 import { patchSkillTreeMarkdownFiles } from "./skill-tree";
@@ -164,6 +164,23 @@ export function renderManagedClaudeHookGroups(
   return hooks;
 }
 
+/**
+ * A layer's Claude settings: the enabled inputs' hook groups and permission
+ * entries, nothing of Mate's own. The launch merges them over its base settings.
+ */
+export function renderLayerClaudeSettings(
+  contributions: CapabilityContributionInput[] = [],
+): ClaudeSettings {
+  const hooks = renderManagedClaudeHookGroups(contributions);
+  const allow = contributions
+    .filter((input) => input.enabled)
+    .flatMap((input) => input.contributions.permissionEntries ?? []);
+  return {
+    ...(Object.keys(hooks).length > 0 ? { hooks } : {}),
+    ...(allow.length > 0 ? { permissions: { allow } } : {}),
+  };
+}
+
 // Reconcile the Mate-managed Claude settings shape (hooks, permissions, MCP
 // servers) on top of whatever already exists in the settings document. Managed
 // groups/entries always lead their arrays so the emitted shape stays stable
@@ -287,7 +304,15 @@ export async function reconcileClaudeContributions(
   // The settings sync (re)creates the managed settings document, so it only
   // runs while the Claude runtime is active; a deactivated runtime's pass is
   // teardown-only and must not resurrect files the provider teardown removed.
-  if (ctx.activeProviders.includes("claude")) {
+  // A layer carries its plugins' hooks and permission entries only, for the
+  // launch to merge into its one `--settings` file.
+  if (projectionTarget(ctx) === "audience-layer") {
+    await writeClaudeSettings(
+      getCompanionClaudeSettingsPath(root),
+      renderLayerClaudeSettings(inputs),
+    );
+    await syncCompanionClaudeMcpConfig(root);
+  } else if (ctx.activeProviders.includes("claude")) {
     await syncCompanionClaudeSettings(root, config, inputs);
   }
 

package/src/tools/setup/providers/opencode.ts

@@ -416,6 +416,16 @@ export async function removeOpenCodeForeignPluginReferences(
 
 const OPENCODE_CONTRIBUTION_CONFIG_FILES = ["opencode.json"];
 
+/**
+ * The surface's reader for an audience layer it wrote: what the Mate OpenCode
+ * plugin applies. Defined under `runtime/` so the import-isolated plugin can
+ * reach it; this surface owns the format it reads.
+ */
+export {
+  readOpenCodeAudienceLayer,
+  type OpenCodeLayerContents,
+} from "../../../runtime/opencode-audience-layer";
+
 export async function reconcileOpenCodeContributions(
   ctx: SetupContext,
   inputs: CapabilityContributionInput[],

package/src/tools/setup/registry.ts

@@ -3,13 +3,22 @@ import type { Plugin, PluginPolicy, PluginRegistration } from "./plugin";
 export interface NormalizedRegistration {
   plugin: Plugin;
   policy: PluginPolicy;
+  /** The audience that declared the plugin; `null` for base. */
+  audience: string | null;
+  /** The declared package a dynamic plugin was loaded from; absent for compiled-in plugins. */
+  packageName?: string;
 }
 
 export function normalizeRegistration(entry: PluginRegistration): NormalizedRegistration {
   if ("plugin" in entry && "policy" in entry) {
-    return { plugin: entry.plugin, policy: entry.policy };
+    return {
+      plugin: entry.plugin,
+      policy: entry.policy,
+      audience: entry.audience ?? null,
+      ...(entry.packageName ? { packageName: entry.packageName } : {}),
+    };
   }
-  return { plugin: entry, policy: entry.defaultSelected ? "default" : "optional" };
+  return { plugin: entry, policy: entry.defaultSelected ? "default" : "optional", audience: null };
 }
 
 export class PluginRegistry {
@@ -32,6 +41,19 @@ export class PluginRegistry {
     return this.entries.map((entry) => ({ ...entry }));
   }
 
+  /**
+   * Compiled-in plugins and top-level declarations: the only registrations a
+   * pass that writes a persisted surface may reconcile.
+   */
+  baseRegistrations(): NormalizedRegistration[] {
+    return this.getEntries().filter((entry) => entry.audience === null);
+  }
+
+  /** The registrations one audience declared; only its launch layer renders them. */
+  audienceRegistrations(audience: string): NormalizedRegistration[] {
+    return this.getEntries().filter((entry) => entry.audience === audience);
+  }
+
   getPolicy(pluginId: string): PluginPolicy | undefined {
     return this.entries.find((entry) => entry.plugin.id === pluginId)?.policy;
   }

package/src/tools/setup/surface-target.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import { audienceLayerDir } from "../../runtime/audience-layer";
 import type { ProjectionTarget, SetupContext } from "./plugin";
 
 /**
@@ -14,6 +15,9 @@ export function projectionTarget(ctx: SetupContext): ProjectionTarget {
       "a working-target reconcile needs a Working Repository in scope; none was supplied",
     );
   }
+  if (target === "audience-layer" && !ctx.audience) {
+    throw new Error("an audience-layer reconcile needs an audience; none was supplied");
+  }
   return target;
 }
 
@@ -38,13 +42,18 @@ export function projectionRepoRoot(ctx: SetupContext): string {
 }
 
 /**
- * The root a Runtime Surface writes into. Defined for the companion target
- * only: a working-target pass renders its documents for the Projection Root to
- * place, so no Runtime Surface ever computes a path inside a Working Repository.
+ * The root a Runtime Surface writes into: the companion, or one audience's
+ * layer outside every repository. Never a Working Repository: a working-target
+ * pass renders its documents for the Projection Root to place, so no Runtime
+ * Surface ever computes a path inside one.
  */
 export function surfaceRoot(ctx: SetupContext): string {
-  if (projectionTarget(ctx) === "working") {
+  const target = projectionTarget(ctx);
+  if (target === "working") {
     throw new Error("a working-target reconcile renders its documents; it writes no surface root");
   }
+  if (target === "audience-layer") {
+    return ctx.layerRoot ?? audienceLayerDir(ctx.companionPath, ctx.audience!);
+  }
   return ctx.companionPath;
 }