@goodbones/core 0.1.0-beta.10 → 0.1.0-beta.12

package/src/load/policy.ts

@@ -7,13 +7,6 @@ import {
   EMPTY_BASELINE,
   makeBaselineFilter,
 } from "../core/baseline.js";
-import {
-  type CampaignPredicate,
-  campaignsFailingTheirProbe,
-  compileCampaignRules,
-  type CompiledCampaign,
-  leafTermsOf,
-} from "../core/campaigns.js";
 import {
   type CompiledExportRule,
   compileExportRules,
@@ -29,7 +22,6 @@ import {
   compileImportRules,
   rulesFailingTheirProbe,
 } from "../core/imports.js";
-import { decodeLedger, type Ledger } from "../core/ledger.js";
 import {
   type CompiledMemberRule,
   compileMemberRules,
@@ -54,19 +46,24 @@ import {
 import type { SourceFacts } from "../domain/facts.js";
 import type { ManifestLocator } from "../domain/manifest-location.js";
 import { type LoweredRules, lowerManifest } from "../manifest/compile.js";
-import { decodeManifest, DEFAULT_LEDGER_DIR, type Manifest } from "../manifest/manifest.js";
+import { decodeManifest, type Manifest } from "../manifest/manifest.js";
 import type { FactExtractor } from "../ports/fact-extractor.js";
 import type { FileSystem } from "../ports/file-system.js";
 import type { Language } from "../ports/language.js";
 import type { ModuleResolver } from "../ports/module-resolver.js";
-import { NO_REPORTS, type ReportSource } from "../ports/report-source.js";
 import type { SyntaxMatcher } from "../ports/syntax-matcher.js";
+import type { ExtensionRoute, PolicyExtension } from "./extension.js";
 
 // A manifest, read by a host, turned into the policy both adapters evaluate.
 // Decoding, lowering, compiling and probing happen here, once, with whatever
 // languages the host hands in — this tier never names one. The host reads the
 // manifest file, constructs its language packs and the live file system, and
 // hands them over; that is the whole of what a host has to know.
+//
+// A family the core does not own arrives the same way: as a `PolicyExtension`
+// in `extensions`, which claims its keys of the manifest, decodes them, and
+// hands back a value carried on `extensions` below. The core never looks
+// inside that value; the package that produced it exports the accessor.
 
 export type LoadedPolicy = {
   readonly repoRoot: string;
@@ -80,18 +77,9 @@ export type LoadedPolicy = {
   readonly graph: CompiledGraph;
   readonly adoption: LoweredRules["adoption"];
   readonly structure: CompiledStructure;
-  // Evaluated by both hosts, one file at a time; the ledgers say which hits
-  // are already counted. A campaign with no ledger is one `campaigns init`
-  // has not been run for, and `check` says so.
-  readonly campaignRules: ReadonlyArray<CompiledCampaign>;
-  readonly ledgers: ReadonlyMap<string, Ledger>;
-  // Repo-relative; `<ledgerDir>/<id>.json` is a campaign's ledger.
-  readonly ledgerDir: string;
-  // The predicate functions the host imported for the `fn` terms.
-  readonly functions: ReadonlyMap<string, CampaignPredicate>;
-  // Answers the `report` terms: the host's live source, or nothing.
-  readonly reports: ReportSource;
-  // The clock the campaigns are judged by — stalls, timestamps.
+  // What each loaded extension loaded, keyed by its id. Opaque here.
+  readonly extensions: ReadonlyMap<string, unknown>;
+  // The clock the policy is judged by — a stall, a window, a timestamp.
   readonly now: number;
   readonly fileSystem: FileSystem;
   // The language packs this policy is evaluated with. The walker takes its
@@ -108,6 +96,8 @@ export type LoadedPolicy = {
   // Routes each file to the syntax matcher of the language whose scope
   // covers it; `parse` answers `null` for a file whose language has none.
   readonly syntax: SyntaxMatcher;
+  // Which scope, and so which language, covers a given file.
+  readonly routeFor: (file: string) => ExtensionRoute | undefined;
   readonly ignoreUnresolved: ReadonlyArray<RegExp>;
   // Deprecation notices from reading the manifest. The host prints them once.
   readonly notices: ReadonlyArray<string>;
@@ -121,17 +111,14 @@ export type LoadPolicyInput = {
   // document — before decoding.
   readonly manifest: unknown;
   // From a data file, where a path in the manifest was written, so a decode
-  // error names a line. A module manifest has none to give.
+  // error names a line. A module manifest has none.
   readonly locate?: ManifestLocator | undefined;
   readonly languages: ReadonlyArray<Language>;
   readonly fileSystem: FileSystem;
-  // The predicate functions the manifest's `fn` terms name, imported by the
-  // host before loading — the core touches no module loader.
-  readonly functions?: ReadonlyMap<string, CampaignPredicate> | undefined;
-  // The host's report source, for the `report` terms. Absent, a term
-  // answers nothing — a policy with one is refused, since it would be a
-  // campaign that can never fire.
-  readonly reports?: ReportSource | undefined;
+  // The families the core does not own, composed by the host. A manifest key
+  // one of these claims is decoded by it; a key none claims is refused as the
+  // excess property it is.
+  readonly extensions?: ReadonlyArray<PolicyExtension> | undefined;
   // For tests and for a CI that pins the clock; defaults to `Date.now()`.
   readonly now?: number | undefined;
 };
@@ -179,20 +166,6 @@ const routesOf = (
 const routeFor = (routes: ReadonlyArray<Route>, file: string): Route | undefined =>
   routes.find((route) => route.matches.test(file));
 
-const referencedFunctions = (detect: CompiledCampaign["detect"]): ReadonlyArray<string> => {
-  switch (detect.kind) {
-    case "all":
-    case "any":
-      return detect.terms.flatMap(referencedFunctions);
-    case "not":
-      return referencedFunctions(detect.term);
-    case "fn":
-      return [detect.name];
-    default:
-      return [];
-  }
-};
-
 // One resolver per scope, built by the scope's language, behind one port that
 // picks the scope by the importing file.
 const makeRouter = (
@@ -235,56 +208,12 @@ const makeRoutingExtractor = (routes: ReadonlyArray<Route>): FactExtractor => ({
 
 // One matcher per scope, behind one port that picks the scope by the file. A
 // language without one parses nothing, which a `syntax` term reads as no
-// matches — and which the probe check below refuses for a campaign that
+// matches — and which an extension's probe check refuses for a family that
 // depends on it.
 const makeRoutingMatcher = (routes: ReadonlyArray<Route>): SyntaxMatcher => ({
   parse: (file, text) => routeFor(routes, file)?.language.syntax?.parse(file, text) ?? null,
 });
 
-// The ledgers, read through the port. An absent file is a campaign with no
-// ledger yet; a malformed one is refused, since reading it as empty would
-// report every hit as unrecorded growth.
-const readLedgers = (
-  configPath: string,
-  fileSystem: FileSystem,
-  ledgerDir: string,
-  campaigns: ReadonlyArray<CompiledCampaign>,
-): Result.Result<ReadonlyMap<string, Ledger>, ConfigInvalid> => {
-  const ledgers = new Map<string, Ledger>();
-  for (const campaign of campaigns) {
-    const at = `${ledgerDir}/${campaign.id}.json`;
-    const text = fileSystem.readText(at);
-    if (text === null) continue;
-    let raw: unknown;
-    try {
-      raw = JSON.parse(text);
-    } catch (cause) {
-      return Result.fail(
-        new ConfigInvalid({ configPath, detail: `the ledger ${at} is not JSON: ${String(cause)}` }),
-      );
-    }
-    const decoded = decodeLedger(raw);
-    if (Result.isFailure(decoded)) {
-      return Result.fail(
-        new ConfigInvalid({
-          configPath,
-          detail: `the ledger ${at} does not decode:\n${decoded.failure}`,
-        }),
-      );
-    }
-    if (decoded.success.id !== campaign.id) {
-      return Result.fail(
-        new ConfigInvalid({
-          configPath,
-          detail: `the ledger ${at} says it belongs to "${decoded.success.id}", not "${campaign.id}".`,
-        }),
-      );
-    }
-    ledgers.set(campaign.id, decoded.success);
-  }
-  return Result.succeed(ledgers);
-};
-
 // The baseline is read through the port, so this tier touches no file itself.
 // An absent or unreadable one carries nothing, which is the safe direction:
 // every violation reports.
@@ -306,8 +235,12 @@ export const loadPolicy = (
   input: LoadPolicyInput,
 ): Result.Result<LoadedPolicy, ConfigInvalid | PatternInvalid> => {
   const { configPath, fileSystem, languages, repoRoot } = input;
+  const extensions = input.extensions ?? [];
 
-  const decoded = decodeManifest(configPath, input.manifest, { locate: input.locate });
+  const decoded = decodeManifest(configPath, input.manifest, {
+    locate: input.locate,
+    extensions,
+  });
   if (Result.isFailure(decoded)) return Result.fail(decoded.failure);
   const config = decoded.success.manifest;
 
@@ -381,78 +314,49 @@ export const loadPolicy = (
   const structure = compileStructure(rules.structure);
   if (Result.isFailure(structure)) return Result.fail(structure.failure);
 
-  const campaignRules = compileCampaignRules(rules.campaigns);
-  if (Result.isFailure(campaignRules)) return Result.fail(campaignRules.failure);
-
-  // A `fn` term names a function the host was to import. One it did not is
-  // a term that would answer false for every file, and is refused.
-  const functions = input.functions ?? new Map<string, CampaignPredicate>();
-  const missing = campaignRules.success.flatMap((rule) =>
-    referencedFunctions(rule.detect).filter((name) => !functions.has(name)),
-  );
-  if (missing.length > 0) {
-    return Result.fail(
-      new ConfigInvalid({
-        configPath,
-        detail:
-          `these campaigns name a predicate function the host did not load: ` +
-          `${[...new Set(missing)].join(", ")}. A \`fn\` term is \`module#export\`, resolved ` +
-          `relative to the manifest, and the export must be a function.`,
-      }),
-    );
-  }
-
-  // A `report` term is answered by the host's source. Without one every
-  // such campaign would report nothing and look complete.
-  const reporting = campaignRules.success.filter((rule) =>
-    leafTermsOf(rule.detect).includes("report"),
-  );
-  if (input.reports === undefined && reporting.length > 0) {
-    return Result.fail(
-      new ConfigInvalid({
-        configPath,
-        detail:
-          `these campaigns hold a \`report\` term and the host provided no report source: ` +
-          `${reporting.map((rule) => rule.name).join(", ")}.`,
-      }),
-    );
-  }
-
-  // A `syntax` term needs a matcher for the language of every file in its
-  // scope. The probes are the files the campaign is proven on; a probe whose
-  // language has none would pass no probe and mean nothing.
-  const syntaxless = campaignRules.success.flatMap((rule) => {
-    if (!leafTermsOf(rule.detect).includes("syntax")) return [];
-    return [...rule.probes.fires, ...rule.probes.ignores].flatMap((probe) => {
-      const route = routeFor(routes.success, probe.path);
-      return route === undefined || route.language.syntax !== undefined
-        ? []
-        : [`${rule.name} (${probe.path}: ${route.language.id} carries no syntax matcher)`];
-    });
-  });
-  if (syntaxless.length > 0) {
-    return Result.fail(
-      new ConfigInvalid({
-        configPath,
-        detail:
-          `these campaigns hold a \`syntax\` term in a scope whose language has no syntax ` +
-          `matcher: ${[...new Set(syntaxless)].join(", ")}. Compose the language pack with ` +
-          `one (\`@goodbones/ast-grep\` for TypeScript), or write the detector without it.`,
-      }),
-    );
-  }
-
   // A probe carrying a source snippet is parsed by the extractor of the
   // language whose scope covers the probe's file — the same extractor the CLI
   // reads that file through. The plugin reads through oxlint's tree instead,
   // and the parity suite is what holds that tree to this one.
   const extractor = makeRoutingExtractor(routes.success);
+  const syntax = makeRoutingMatcher(routes.success);
+  const routeOf = (file: string): ExtensionRoute | undefined => {
+    const found = routeFor(routes.success, file);
+    return found === undefined ? undefined : { language: found.language, scope: found.scope };
+  };
+  const now = input.now ?? Date.now();
+
+  // Each family the core does not own compiles and probes its own rules, with
+  // the same extractor and matcher the core used for its. Its probe failures
+  // join the one refusal below, so a vacuous campaign and a vacuous import
+  // rule are reported in the same sentence.
+  const loadedExtensions = new Map<string, unknown>();
+  const extensionVacuous: Array<string> = [];
+  for (const extension of extensions) {
+    const loaded = extension.load({
+      spec: decoded.success.extensions.get(extension.id),
+      configPath,
+      repoRoot,
+      config,
+      languages,
+      fileSystem,
+      extractor,
+      syntax,
+      routeFor: routeOf,
+      now,
+    });
+    if (Result.isFailure(loaded)) return Result.fail(loaded.failure);
+    loadedExtensions.set(extension.id, loaded.success.value);
+    for (const name of loaded.success.vacuous ?? []) extensionVacuous.push(name);
+  }
+
   const parsedBy = (rule: { readonly probe: { readonly from: string } }): string => {
     const route = routeFor(routes.success, rule.probe.from);
     return route === undefined
       ? ` — no resolve scope covers its probe ${JSON.stringify(rule.probe.from)}, so no language parsed it`
       : ` — probe parsed by ${route.language.id}, selected by the scope ${JSON.stringify(route.scope.files)}`;
   };
+
   const vacuous = [
     ...rulesFailingTheirProbe(importRules.success).map((rule) => rule.name),
     ...exportRulesFailingTheirProbe(exportRules.success, extractor).map(
@@ -466,19 +370,7 @@ export const loadPolicy = (
     ),
     ...structureRulesFailingTheirProbe(structure.success),
     ...graphRulesFailingTheirProbe(graph.success),
-    ...campaignsFailingTheirProbe(
-      campaignRules.success,
-      extractor,
-      (file) => routeFor(routes.success, file)?.language.syntax ?? null,
-      functions,
-    ).map((failed) =>
-      failed.outOfScope === true
-        ? `${failed.name} (its probe ${failed.probe.path} is outside the campaign's own scope)`
-        : failed.expected === "fires"
-          ? `${failed.name} (fires probe ${failed.probe.path} did not fire)`
-          : `${failed.name} (ignores probe ${failed.probe.path} fired` +
-            (failed.admittedBy === undefined ? ")" : `, admitted by \`${failed.admittedBy}\`)`),
-    ),
+    ...extensionVacuous,
   ];
   if (vacuous.length > 0) {
     return Result.fail(
@@ -500,10 +392,6 @@ export const loadPolicy = (
   const resolver = makeRouter(configPath, repoRoot, routes.success);
   if (Result.isFailure(resolver)) return Result.fail(resolver.failure);
 
-  const ledgerDir = config.ledger ?? DEFAULT_LEDGER_DIR;
-  const ledgers = readLedgers(configPath, fileSystem, ledgerDir, campaignRules.success);
-  if (Result.isFailure(ledgers)) return Result.fail(ledgers.failure);
-
   return Result.succeed({
     repoRoot,
     config,
@@ -514,18 +402,15 @@ export const loadPolicy = (
     graph: graph.success,
     adoption: rules.adoption,
     structure: structure.success,
-    campaignRules: campaignRules.success,
-    ledgers: ledgers.success,
-    ledgerDir,
-    functions,
-    reports: input.reports ?? NO_REPORTS,
-    now: input.now ?? Date.now(),
+    extensions: loadedExtensions,
+    now,
     fileSystem,
     languages,
     baseline: makeBaselineFilter(readBaseline(fileSystem, config.baseline)),
     resolver: resolver.success,
     extractor,
-    syntax: makeRoutingMatcher(routes.success),
+    syntax,
+    routeFor: routeOf,
     ignoreUnresolved: (config.resolve.ignoreUnresolved ?? []).map(
       (pattern: string) => new RegExp(pattern),
     ),

package/src/manifest/compile.ts

@@ -1,7 +1,5 @@
 import {
   type Allowance,
-  type CampaignRule,
-  type Detector,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -17,15 +15,11 @@ import type { ManifestPath } from "../domain/manifest-location.js";
 import { fragmentOf, type Substitution } from "./expand.js";
 import { anchored, type CaptureIndex, globToRegexSource, prefixed } from "./glob.js";
 import {
-  type CampaignSpec,
-  type DetectorSpec,
-  durationMs,
   globsOf,
   type ImportsSpec,
   type Manifest,
   type ManifestNode,
   type NamingSpec,
-  type SyntaxTermSpec,
 } from "./manifest.js";
 
 // The manifest is the authoring surface; these flat rules are the machine's.
@@ -37,8 +31,6 @@ export type LoweredRules = {
   readonly members: ReadonlyArray<MemberRule>;
   readonly surface: ReadonlyArray<SurfaceRule>;
   readonly graph: GraphConfig;
-  // Campaigns pass through by their own id, as top-level `exports` rules do.
-  readonly campaigns: ReadonlyArray<CampaignRule>;
   // The nodes that said "not tightened yet", by name — the adoption backlog,
   // and what `limits` puts a ceiling on.
   readonly adoption: {
@@ -80,7 +72,7 @@ const alternativesOf = (key: string): ReadonlyArray<string> =>
     .map(stripSlash)
     .filter((one) => one !== "");
 
-const expandAliases = (glob: string, aliases: Readonly<Record<string, string>>): string => {
+export const expandAliases = (glob: string, aliases: Readonly<Record<string, string>>): string => {
   for (const [alias, target] of Object.entries(aliases)) {
     if (glob === alias) return target;
     if (glob.startsWith(`${alias}/`)) return target + glob.slice(alias.length);
@@ -146,7 +138,7 @@ const probeMemberName = (match: string | ReadonlyArray<string> | undefined): str
 
 // Each convention pairs the shape a name must have with a name that does not
 // have it, so the rule's probe is generated rather than written.
-const CONVENTIONS: Readonly<
+export const CONVENTIONS: Readonly<
   Record<string, { readonly source: string; readonly violating: string; readonly shape: string }>
 > = {
   "kebab-case": {
@@ -1058,216 +1050,13 @@ export const lowerManifest = (
     })),
   };
 
-  const campaigns = (manifest.campaigns ?? []).map((campaign) => lowerCampaign(campaign, aliases));
-
   return {
     imports,
     exports,
     members,
     surface,
     graph,
-    campaigns,
     adoption: { unrestricted: unrestrictedNodes, partial: partialNodes },
     structure: { roots, folders, parity, naming: namingRules },
   };
 };
-
-// The keys of a `syntax` term that belong to the engine's rule; `where` is
-// the one that does not.
-const SYNTAX_RULE_KEYS = [
-  "pattern",
-  "kind",
-  "regex",
-  "nthChild",
-  "inside",
-  "has",
-  "precedes",
-  "follows",
-  "all",
-  "any",
-  "not",
-] as const;
-
-const syntaxRuleOf = (term: SyntaxTermSpec): unknown =>
-  Object.fromEntries(
-    SYNTAX_RULE_KEYS.flatMap((key) => (term[key] === undefined ? [] : [[key, term[key]]])),
-  );
-
-// The leaf terms a path alone cannot exercise: each reads the file's text,
-// its syntax, or its facts, so a probe for a detector holding one must carry
-// a `source`.
-const TERMS_NEEDING_SOURCE = ["content", "syntax", "exports", "members", "fn"] as const;
-
-const leafTermsOf = (detector: DetectorSpec): ReadonlyArray<string> => {
-  if ("all" in detector) return detector.all.flatMap(leafTermsOf);
-  if ("any" in detector) return detector.any.flatMap(leafTermsOf);
-  if ("not" in detector) return leafTermsOf(detector.not);
-  return Object.keys(detector);
-};
-
-// A campaign's globs resolved: `scope` and a path-shaped `resolves` the way
-// graph rules resolve theirs, `exports`/`members` names the way `surface` and
-// `members` rules do, and the rest carried as written. The `fn` string is
-// kept verbatim for the loader, which holds the function it names.
-const lowerCampaign = (
-  campaign: CampaignSpec,
-  aliases: Readonly<Record<string, string>>,
-): CampaignRule => {
-  const asPath = (glob: string): string =>
-    prefixed(
-      globToRegexSource(expandAliases(glob, aliases), {}, { declaring: false, nextGroup: 1 })
-        .source,
-    );
-  const asName = (globs: string | ReadonlyArray<string>): ReadonlyArray<string> =>
-    globsOf(globs).map((one) =>
-      anchored(globToRegexSource(one, {}, { declaring: false, nextGroup: 1 }).source),
-    );
-  const name = `campaign/${campaign.id}`;
-
-  const lower = (detector: DetectorSpec): Detector => {
-    if ("all" in detector) return { all: detector.all.map(lower) };
-    if ("any" in detector) return { any: detector.any.map(lower) };
-    if ("not" in detector) return { not: lower(detector.not) };
-    if ("path" in detector) {
-      const { convention, ...rest } = detector.path;
-      const conventionSource =
-        convention === undefined
-          ? undefined
-          : typeof convention === "string"
-            ? CONVENTIONS[convention]?.source
-            : convention.regex;
-      if (convention !== undefined && conventionSource === undefined) {
-        throw new Error(`campaign "${campaign.id}" names an unknown convention "${convention}".`);
-      }
-      if (conventionSource !== undefined && rest.subject === undefined) {
-        throw new Error(
-          `campaign "${campaign.id}" states a path convention with no \`subject\`: say which ` +
-            `capture group of \`file\` holds the name the convention is about.`,
-        );
-      }
-      return {
-        path: {
-          file: globsOf(rest.file),
-          ...(rest.fileNot === undefined ? {} : { fileNot: globsOf(rest.fileNot) }),
-          ...(rest.subject === undefined ? {} : { subject: rest.subject }),
-          ...(conventionSource === undefined ? {} : { convention: conventionSource }),
-        },
-      };
-    }
-    if ("imports" in detector) {
-      const { resolves, symbols } = detector.imports;
-      return {
-        imports: {
-          resolves: typeof resolves === "string" ? asPath(resolves) : resolves,
-          ...(symbols === undefined ? {} : { symbols: [...symbols] }),
-        },
-      };
-    }
-    if ("exports" in detector) {
-      const term = detector.exports;
-      return {
-        exports: {
-          ...(term.name === undefined ? {} : { name: asName(term.name) }),
-          ...(term.kinds === undefined ? {} : { kinds: [...term.kinds] }),
-          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
-          ...(term.reexport === undefined ? {} : { reexport: term.reexport }),
-        },
-      };
-    }
-    if ("members" in detector) {
-      const term = detector.members;
-      return {
-        members: {
-          subject: term.subject,
-          ...(term.name === undefined ? {} : { name: asName(term.name) }),
-          ...(term.in === undefined ? {} : { in: asName(term.in) }),
-          ...(term.declares === undefined ? {} : { declares: [...term.declares] }),
-        },
-      };
-    }
-    if ("requires" in detector) return { requires: [...detector.requires] };
-    if ("content" in detector) return { content: { regex: detector.content.regex } };
-    if ("report" in detector) {
-      // Exactly one of `command` and `file`, and a pattern for `regex`: the
-      // manifest schema refused anything else at decode.
-      const term = detector.report;
-      return {
-        report: {
-          ...(term.command === undefined ? {} : { command: globsOf(term.command) }),
-          ...(term.file === undefined ? {} : { file: globsOf(term.file) }),
-          format: term.format,
-          ...(term.pattern === undefined ? {} : { pattern: term.pattern }),
-          ...(term.codes === undefined ? {} : { codes: [...term.codes] }),
-          ...(term.codesNot === undefined ? {} : { codesNot: [...term.codesNot] }),
-        },
-      };
-    }
-    if ("syntax" in detector) {
-      const { where } = detector.syntax;
-      const narrowed =
-        where === undefined
-          ? {}
-          : {
-              where: Object.fromEntries(
-                Object.entries(where).map(([capture, narrowing]) => [
-                  capture,
-                  {
-                    ...(narrowing.regex === undefined ? {} : { regex: narrowing.regex }),
-                    ...(narrowing.binding === undefined
-                      ? {}
-                      : {
-                          binding: {
-                            resolves:
-                              typeof narrowing.binding.resolves === "string"
-                                ? asPath(narrowing.binding.resolves)
-                                : narrowing.binding.resolves,
-                            ...(narrowing.binding.member === undefined
-                              ? {}
-                              : { member: [...narrowing.binding.member] }),
-                          },
-                        }),
-                  },
-                ]),
-              ),
-            };
-      return { syntax: { rule: syntaxRuleOf(detector.syntax), ...narrowed } };
-    }
-    return { fn: detector.fn };
-  };
-
-  // A probe without a source proves only the path; a detector that reads the
-  // file needs the file. Refused here, with the term named, rather than at
-  // load as a probe that mysteriously never fires.
-  const leaves = leafTermsOf(campaign.detect);
-  const needsSource = TERMS_NEEDING_SOURCE.filter((term) => leaves.includes(term));
-  const probes = [...campaign.probes.fires, ...(campaign.probes.ignores ?? [])];
-  const sourceless = probes.find((probe) => probe.source === undefined);
-  if (needsSource.length > 0 && sourceless !== undefined) {
-    throw new Error(
-      `campaign "${campaign.id}" has a probe (${sourceless.path}) with no \`source\`, and its ` +
-        `detector holds a ${needsSource.map((term) => `\`${term}\``).join(", ")} term, which ` +
-        `a path alone cannot exercise. Give every probe a source.`,
-    );
-  }
-  if (campaign.probes.fires.length === 0) {
-    throw new Error(
-      `campaign "${campaign.id}" carries no \`probes.fires\`. A campaign proves it can fire ` +
-        `the way every rule does; write at least one source it must report.`,
-    );
-  }
-
-  return {
-    name,
-    id: campaign.id,
-    ...(campaign.title === undefined ? {} : { title: campaign.title }),
-    message: campaign.how,
-    why: campaign.why,
-    ...(campaign.owner === undefined ? {} : { owner: campaign.owner }),
-    scope: globsOf(campaign.scope).map(asPath),
-    unit: campaign.unit,
-    detect: lower(campaign.detect),
-    probes: { fires: [...campaign.probes.fires], ignores: [...(campaign.probes.ignores ?? [])] },
-    staleAfter: durationMs(campaign.staleAfter),
-    onComplete: campaign.onComplete ?? "keep",
-  };
-};

package/src/manifest/extension.ts

@@ -0,0 +1,41 @@
+import type * as Result from "effect/Result";
+
+import type { ManifestPath } from "../domain/manifest-location.js";
+
+// A family the core does not own.
+//
+// The five per-file families, the graph and the limits are the core's: it
+// declares their vocabulary, decodes it and evaluates it. A family that is
+// not — `campaigns`, which @goodbones/campaigns owns — states which top-level
+// manifest keys it claims, and decodes them itself. The core splits those
+// keys off the expanded manifest before decoding what is left, so the core's
+// codec never learns a word of the family's vocabulary and a key no
+// extension claims is still the excess property it always was.
+//
+// This is the decode half. The load half — compiling, probing, and whatever
+// state the family reads off disk — is `PolicyExtension` in `load/`, which
+// needs the ports and so cannot live here.
+
+export type ManifestExtension<Spec = unknown> = {
+  // Names the family in errors, and keys it in `LoadedPolicy.extensions`.
+  readonly id: string;
+  // The top-level keys of the manifest this family owns.
+  readonly manifestKeys: ReadonlyArray<string>;
+  // The slice, as the expansion passes left it: the claimed keys that were
+  // present, with `defs`/`use` and `include` already resolved.
+  //
+  // `describe` renders one issue the way the core's own decoder does — the
+  // position in the file, the path, and the `use` it came through — so a
+  // decode error from a family the core does not own reads exactly like one
+  // from a tree node. Failure is a list of rendered lines, because a manifest
+  // is edited by hand and the reader fixing one wants the other three.
+  //
+  // Declared as a method rather than a function property on purpose: the
+  // loader holds extensions as `PolicyExtension<unknown, unknown>`, having
+  // erased what each one decodes, and method signatures are what let a
+  // concretely-typed extension be one of those.
+  decode(
+    slice: Readonly<Record<string, unknown>>,
+    describe: (path: ManifestPath, detail: string) => string,
+  ): Result.Result<Spec, ReadonlyArray<string>>;
+};

package/src/manifest/glob.ts

@@ -106,3 +106,8 @@ export const globToRegexSource = (
 export const anchored = (source: string): string => `^${source}$`;
 
 export const prefixed = (source: string): string => `^${source}`;
+
+// A repo-relative glob as the sector discovery compiles a marker's `owns`:
+// anchored at the start, so it names a subtree.
+export const globToRegExp = (glob: string): RegExp =>
+  new RegExp(prefixed(globToRegexSource(glob, {}, { declaring: false, nextGroup: 1 }).source));