@usefragments/core 1.10.2 → 2.0.0

package/src/registry.ts

@@ -141,6 +141,8 @@ const registryManifestBaseSchema = z.object({
   generatedAt: z.string().datetime(),
   source: registrySourceSchema,
   packageFiles: z.array(registryFileSchema).default([]),
+  /** Files every install writes, whatever the selection: the stylesheet entry and its closure. */
+  baseFiles: z.array(registryFileSchema).default([]),
   entrypoints: z.array(registryEntrypointSchema).default([]),
   components: z.record(z.string(), registryComponentSchema),
   dependencies: z.array(registryDependencySchema).default([]),
@@ -173,6 +175,7 @@ export const registryArtifactSchema = z
 
     const manifestFiles = [
       ...artifact.manifest.packageFiles,
+      ...artifact.manifest.baseFiles,
       ...artifact.manifest.entrypoints.map((entrypoint) => ({
         path: entrypoint.sourcePath,
         role: "barrel" as const,
@@ -367,3 +370,237 @@ export function registryManifestCanonicalPreimage(
 ): string {
   return canonicalPreimage(registryHashPayload(manifest));
 }
+
+// ============================================================================
+// Sharded artifact (schema v2): index without bodies + content shards
+// ============================================================================
+
+export const REGISTRY_INDEX_SCHEMA_VERSION = "fragments.registry-index.v2";
+export const REGISTRY_SHARD_SCHEMA_VERSION = "fragments.registry-shard.v2";
+
+const registryShardPathSchema = registryFilePathSchema.superRefine((value, ctx) => {
+  if (!value.endsWith(".json")) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Shard path must end with .json" });
+  }
+});
+
+export const registryShardSchema = z
+  .object({
+    schemaVersion: z.literal(REGISTRY_SHARD_SCHEMA_VERSION),
+    files: z.record(z.string().min(1), registryFileContentSchema),
+  })
+  .superRefine((shard, ctx) => {
+    for (const [contentRef, file] of Object.entries(shard.files)) {
+      if (contentRef !== `sha256:${file.sha256}`) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["files", contentRef],
+          message: `Shard key ${contentRef} does not match content hash of ${file.path}`,
+        });
+      }
+    }
+  });
+
+export const registryIndexSchema = z
+  .object({
+    schemaVersion: z.literal(REGISTRY_INDEX_SCHEMA_VERSION),
+    manifest: registryManifestSchema,
+    /** Shard path (relative to the index) → registry file paths whose bodies it carries. */
+    shards: z.record(registryShardPathSchema, z.array(registryFilePathSchema).min(1)),
+  })
+  .superRefine((index, ctx) => {
+    const owner = new Map<string, string>();
+    for (const [shardPath, paths] of Object.entries(index.shards)) {
+      for (const path of paths) {
+        const existing = owner.get(path);
+        if (existing) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["shards", shardPath],
+            message: `Registry file ${path} is listed in both ${existing} and ${shardPath}`,
+          });
+        }
+        owner.set(path, shardPath);
+      }
+    }
+    for (const path of registryManifestFilePaths(index.manifest)) {
+      if (!owner.has(path)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["shards"],
+          message: `Registry file ${path} is not carried by any shard`,
+        });
+      }
+    }
+  });
+
+/**
+ * A short-lived pointer (`latest.json`) to an immutable versioned index. One hop only;
+ * `index` is a relative path so the hop cannot leave the pointer's origin.
+ */
+export const REGISTRY_POINTER_SCHEMA_VERSION = "fragments.registry-pointer.v1";
+
+export const registryPointerSchema = z.object({
+  schemaVersion: z.literal(REGISTRY_POINTER_SCHEMA_VERSION),
+  registryId: z.string().min(1),
+  version: z.string().min(1),
+  registryHash: sha256Schema,
+  index: registryShardPathSchema,
+  generatedAt: z.string().datetime(),
+});
+
+export type RegistryShard = z.infer<typeof registryShardSchema>;
+export type RegistryIndex = z.infer<typeof registryIndexSchema>;
+export type RegistryPointer = z.infer<typeof registryPointerSchema>;
+
+export function buildRegistryPointer(index: RegistryIndex, indexPath: string): RegistryPointer {
+  return registryPointerSchema.parse({
+    schemaVersion: REGISTRY_POINTER_SCHEMA_VERSION,
+    registryId: index.manifest.registryId,
+    version: index.manifest.version,
+    registryHash: index.manifest.registryHash,
+    index: indexPath,
+    generatedAt: index.manifest.generatedAt,
+  });
+}
+
+/** Every file path the manifest references, sorted and unique. */
+export function registryManifestFilePaths(manifest: RegistryManifest): string[] {
+  return [...registryManifestFileMetadata(manifest).keys()].sort((left, right) =>
+    left.localeCompare(right)
+  );
+}
+
+/** Path → metadata for every manifest file; entrypoint-only paths map to `null`. */
+export function registryManifestFileMetadata(
+  manifest: RegistryManifest
+): Map<string, RegistryFile | null> {
+  const files = new Map<string, RegistryFile | null>();
+  const add = (file: RegistryFile) => {
+    if (!files.get(file.path)) files.set(file.path, file);
+  };
+  manifest.packageFiles.forEach(add);
+  manifest.baseFiles.forEach(add);
+  for (const component of Object.values(manifest.components)) component.files.forEach(add);
+  for (const entrypoint of manifest.entrypoints) {
+    if (!files.has(entrypoint.sourcePath)) files.set(entrypoint.sourcePath, null);
+  }
+  return files;
+}
+
+/**
+ * Default shard layout: one shard per component directory, one shard per shared
+ * top-level directory under `src/` (`shared/tokens.json`, `shared/utils.json`, …),
+ * `shared/src.json` for files directly under `src/`, and `shared/package.json` for
+ * package-root files (`package.json`, `fragments.json`) that only complete installs need.
+ */
+export function defaultRegistryShardPath(path: string): string {
+  const componentMatch = /^src\/components\/([^/]+)\//.exec(path);
+  if (componentMatch) return `components/${componentMatch[1]}.json`;
+  if (!path.startsWith("src/")) return "shared/package.json";
+  const segments = path.slice("src/".length).split("/");
+  return segments.length > 1 ? `shared/${segments[0]}.json` : "shared/src.json";
+}
+
+export interface ShardedRegistryArtifact {
+  index: RegistryIndex;
+  shards: Map<string, RegistryShard>;
+}
+
+function shardKeyFor(metadata: RegistryFile | null | undefined, sha256: string): string {
+  return metadata?.contentRef ?? `sha256:${sha256}`;
+}
+
+export function shardRegistryArtifact(
+  artifact: RegistryArtifact,
+  shardPathFor: (path: string) => string = defaultRegistryShardPath
+): ShardedRegistryArtifact {
+  const metadata = registryManifestFileMetadata(artifact.manifest);
+  const shards = new Map<string, RegistryShard>();
+  const shardPaths: Record<string, string[]> = {};
+
+  for (const [path, content] of Object.entries(artifact.files).sort(([left], [right]) =>
+    left.localeCompare(right)
+  )) {
+    const shardPath = shardPathFor(path);
+    const shard = shards.get(shardPath) ?? {
+      schemaVersion: REGISTRY_SHARD_SCHEMA_VERSION,
+      files: {},
+    };
+    shard.files[shardKeyFor(metadata.get(path), content.sha256)] = content;
+    shards.set(shardPath, shard);
+    (shardPaths[shardPath] ??= []).push(path);
+  }
+
+  const index = registryIndexSchema.parse({
+    schemaVersion: REGISTRY_INDEX_SCHEMA_VERSION,
+    manifest: artifact.manifest,
+    shards: shardPaths,
+  });
+  for (const [path, shard] of shards) shards.set(path, registryShardSchema.parse(shard));
+  return { index, shards };
+}
+
+function shardOwnerMap(index: RegistryIndex): Map<string, string> {
+  const owner = new Map<string, string>();
+  for (const [shardPath, paths] of Object.entries(index.shards)) {
+    for (const path of paths) owner.set(path, shardPath);
+  }
+  return owner;
+}
+
+/** The shards (sorted, unique) that carry the given registry file paths. */
+export function registryShardsForPaths(index: RegistryIndex, paths: readonly string[]): string[] {
+  const owner = shardOwnerMap(index);
+  const shards = new Set<string>();
+  for (const path of paths) {
+    const shardPath = owner.get(path);
+    if (!shardPath) throw new Error(`Registry index has no shard for ${path}`);
+    shards.add(shardPath);
+  }
+  return [...shards].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Rebuild a v1-shaped artifact from an index plus the shards that cover `paths`.
+ * Only the requested paths are materialised; every body is checked against the
+ * manifest's hash and size before it is accepted.
+ */
+export function assembleRegistryArtifact(args: {
+  index: RegistryIndex;
+  shards: ReadonlyMap<string, RegistryShard>;
+  paths: readonly string[];
+}): RegistryArtifact {
+  const metadata = registryManifestFileMetadata(args.index.manifest);
+  const owner = shardOwnerMap(args.index);
+  const files: Record<string, RegistryFileContent> = {};
+
+  for (const path of [...new Set(args.paths)].sort((left, right) => left.localeCompare(right))) {
+    const shardPath = owner.get(path);
+    if (!shardPath) throw new Error(`Registry index has no shard for ${path}`);
+    const shard = args.shards.get(shardPath);
+    if (!shard) throw new Error(`Registry shard ${shardPath} was not loaded (needed for ${path})`);
+    const expected = metadata.get(path) ?? null;
+    const content = expected
+      ? shard.files[expected.contentRef]
+      : Object.values(shard.files).find((file) => file.path === path);
+    if (!content || content.path !== path) {
+      throw new Error(`Registry shard ${shardPath} is missing content for ${path}`);
+    }
+    // Re-hash the body: a shard's own sha256/size fields are claims, the index is the truth.
+    const actualSha256 = hashRegistryFileContent(content.content);
+    const actualSize = registryFileSize(content.content);
+    const expectedSha256 = expected?.sha256 ?? content.sha256;
+    const expectedSize = expected?.size ?? content.size;
+    if (actualSha256 !== expectedSha256 || actualSize !== expectedSize) {
+      throw new Error(`Registry shard ${shardPath} content for ${path} does not match the index`);
+    }
+    files[path] = content;
+  }
+
+  return {
+    schemaVersion: REGISTRY_ARTIFACT_SCHEMA_VERSION,
+    manifest: args.index.manifest,
+    files,
+  };
+}

package/src/repository-binding.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeRepositoryBindingKeyV1,
+  repositoryBindingDigestV1,
+  repositoryBindingKeyV1Schema,
+} from "./repository-binding.js";
+
+const binding = {
+  provider: "github",
+  providerInstanceId: "github.com",
+  repositoryExternalId: "R_kgDOOpaqueCase",
+  bindingId: "binding_OpaqueCase",
+};
+
+describe("RepositoryBindingKeyV1", () => {
+  it("normalizes provider and instance syntax without changing opaque IDs", () => {
+    expect(
+      normalizeRepositoryBindingKeyV1({
+        ...binding,
+        provider: " GitHub ",
+        providerInstanceId: "HTTPS://GitHub.COM/",
+      })
+    ).toEqual(binding);
+  });
+
+  it("has a checked-in stable identity digest", () => {
+    expect(repositoryBindingDigestV1(binding)).toBe(
+      "b0460189d57f386bab0043a08df24af05b736bb8393a9de429a973b5e26e7898"
+    );
+  });
+
+  it("ignores display data by rejecting it at the canonical boundary", () => {
+    expect(() => repositoryBindingKeyV1Schema.parse({ ...binding, owner: "renamed" })).toThrow();
+  });
+
+  it("changes identity when opaque repository identity changes", () => {
+    expect(repositoryBindingDigestV1({ ...binding, repositoryExternalId: "R_other" })).not.toBe(
+      repositoryBindingDigestV1(binding)
+    );
+  });
+
+  it("rejects oversized and malformed identity fields", () => {
+    expect(() =>
+      normalizeRepositoryBindingKeyV1({ ...binding, bindingId: "x".repeat(257) })
+    ).toThrow();
+    expect(() =>
+      normalizeRepositoryBindingKeyV1({ ...binding, providerInstanceId: "https://github.com/a" })
+    ).toThrow();
+  });
+});

package/src/repository-binding.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { canonicalPreimage, sha256Hex } from "./contract/hash.js";
+import { digestHexSchema, type DigestHex } from "./domain-ids.js";
+
+export const REPOSITORY_BINDING_ID_MAX_BYTES_V1 = 256;
+export const PROVIDER_ID_MAX_BYTES_V1 = 64;
+
+const utf8Length = (value: string): number => new TextEncoder().encode(value).byteLength;
+const boundedString = (label: string, maxBytes: number) =>
+  z
+    .string()
+    .min(1, `${label} is required`)
+    .refine((value) => utf8Length(value) <= maxBytes, `${label} exceeds ${maxBytes} UTF-8 bytes`);
+
+const providerSchema = boundedString("provider", PROVIDER_ID_MAX_BYTES_V1)
+  .transform((value) => value.trim().toLowerCase())
+  .refine(
+    (value) => /^[a-z][a-z0-9_-]*$/u.test(value),
+    "provider must be a bounded lowercase identifier"
+  );
+
+function normalizeProviderInstanceId(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) throw new TypeError("providerInstanceId is required");
+
+  if (trimmed.includes("://")) {
+    const url = new URL(trimmed);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      throw new TypeError("providerInstanceId URL must use http or https");
+    }
+    if (
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash ||
+      (url.pathname !== "" && url.pathname !== "/")
+    ) {
+      throw new TypeError("providerInstanceId must identify an origin, not a path or credential");
+    }
+    return url.host.toLowerCase().replace(/\.$/u, "");
+  }
+
+  const normalized = trimmed.toLowerCase().replace(/\.$/u, "");
+  if (!/^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$/u.test(normalized)) {
+    throw new TypeError("providerInstanceId must be a normalized origin or tenant key");
+  }
+  return normalized;
+}
+
+const providerInstanceSchema = boundedString(
+  "providerInstanceId",
+  REPOSITORY_BINDING_ID_MAX_BYTES_V1
+).transform((value, context) => {
+  try {
+    return normalizeProviderInstanceId(value);
+  } catch (error) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return z.NEVER;
+  }
+});
+
+export const repositoryBindingKeyV1Schema = z
+  .object({
+    provider: providerSchema,
+    providerInstanceId: providerInstanceSchema,
+    repositoryExternalId: boundedString("repositoryExternalId", REPOSITORY_BINDING_ID_MAX_BYTES_V1),
+    bindingId: boundedString("bindingId", REPOSITORY_BINDING_ID_MAX_BYTES_V1),
+  })
+  .strict();
+
+export type RepositoryBindingKeyV1 = z.output<typeof repositoryBindingKeyV1Schema>;
+export type RepositoryBindingKeyV1Input = z.input<typeof repositoryBindingKeyV1Schema>;
+
+export function normalizeRepositoryBindingKeyV1(
+  value: RepositoryBindingKeyV1Input
+): RepositoryBindingKeyV1 {
+  return repositoryBindingKeyV1Schema.parse(value);
+}
+
+export function repositoryBindingDigestV1(value: RepositoryBindingKeyV1Input): DigestHex {
+  const binding = normalizeRepositoryBindingKeyV1(value);
+  return digestHexSchema.parse(
+    sha256Hex(
+      canonicalPreimage({
+        schema: "repository-binding.v1",
+        provider: binding.provider,
+        providerInstanceId: binding.providerInstanceId,
+        repositoryExternalId: binding.repositoryExternalId,
+        bindingId: binding.bindingId,
+      })
+    )
+  );
+}

package/src/rules/families.test.ts

@@ -7,6 +7,7 @@ import {
   ruleFamilyMembers,
 } from "./families.js";
 import { compileGlobalGovernanceFacts } from "../facts/index.js";
+import { markPresetSourcedRules } from "../governance.js";
 import { RULES } from "./index.js";
 import { RULE_TIER } from "./tiers.js";
 
@@ -60,6 +61,41 @@ describe("rule families", () => {
     expect(compiled).toContain("styles/no-raw-typography");
   });
 
+  it("lets an authored family entry override preset-sourced member entries", () => {
+    const enabledMap = (rules: Record<string, unknown>) =>
+      new Map(
+        compileGlobalGovernanceFacts({ rules })
+          .filter((fact) => fact.kind === "governance_rule_config")
+          .map((fact) => [fact.ruleId, fact.enabled] as const)
+      );
+
+    // Customer default (members off, preset-sourced) + the user turning the family on.
+    const turnedOn = enabledMap({
+      ...markPresetSourcedRules({
+        "components/forbidden-prop-value": { enabled: false },
+        "components/unknown-prop": { enabled: false },
+      }),
+      "components/usage": { enabled: true, severity: "error" },
+    });
+    expect(turnedOn.get("components/forbidden-prop-value")).toBe(true);
+    expect(turnedOn.get("components/unknown-prop")).toBe(true);
+
+    // `fragments` preset (members on, preset-sourced) + the user turning the family off.
+    const turnedOff = enabledMap({
+      ...markPresetSourcedRules({ "styles/no-raw-color": { enabled: true, severity: "warn" } }),
+      "tokens/hardcoded-values": false,
+    });
+    expect(turnedOff.get("styles/no-raw-color")).toBe(false);
+
+    // An authored member entry is the more specific statement and beats the aggregate.
+    const memberWins = enabledMap({
+      "tokens/hardcoded-values": { enabled: true, severity: "warn" },
+      "styles/no-raw-color": false,
+    });
+    expect(memberWins.get("styles/no-raw-color")).toBe(false);
+    expect(memberWins.get("styles/no-raw-spacing")).toBe(true);
+  });
+
   it("expands a family and passes a concrete rule id through unchanged", () => {
     expect(ruleFamilyMembers("tokens/hardcoded-values")).toContain("styles/no-raw-typography");
     expect(ruleFamilyMembers("styles/no-raw-color")).toEqual(["styles/no-raw-color"]);

package/src/rules/finding.ts

@@ -12,7 +12,7 @@
 import type { GovernanceSeverity } from "../governance.js";
 import type { FactEvidence, FactLocation } from "../facts/index.js";
 import { canonicalJson, hash64Hex } from "../facts/ids.js";
-import { byRuleId } from "../codes/index.js";
+import { byCode, byRuleId } from "../codes/index.js";
 import { normalizeFinding, normalizeSeverity } from "../schemas/index.js";
 import type { Severity } from "../schemas/index.js";
 import type { EvidenceGrade } from "../evidence.js";
@@ -28,6 +28,11 @@ export interface MakeFindingInput {
   evidence: FactEvidence[];
   evidenceGrade?: EvidenceGrade;
   fingerprintIdentity: Record<string, unknown>;
+  /**
+   * Override the FUI code looked up from `ruleId`. Use when one rule emits a
+   * distinct config-level diagnostic alongside its ordinary findings.
+   */
+  code?: string;
   /**
    * Legacy identity tuple from before a fingerprint migration. When present,
    * the finding also carries `previousFingerprint` (the legacy hash) so
@@ -60,7 +65,7 @@ export function makeFinding(input: MakeFindingInput): Finding {
   const previousFingerprint = input.previousFingerprintIdentity
     ? hash64Hex(canonicalJson({ ruleId: input.ruleId, ...input.previousFingerprintIdentity }))
     : undefined;
-  const code = byRuleId.get(input.ruleId);
+  const code = input.code ? byCode.get(input.code) : byRuleId.get(input.ruleId);
   return normalizeFinding({
     ruleId: input.ruleId,
     ruleVersion: input.ruleVersion,

package/src/rules/index.ts

@@ -38,6 +38,7 @@ import { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 import { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
 import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
 import { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
+import { readRuleConfig } from "./rule-config.js";
 import type { Finding } from "./types.js";
 
 export type RuleFn = (ix: FactIndex) => Finding[];
@@ -183,8 +184,15 @@ export const RULES: readonly Rule[] = [
  * fingerprint)` so output is stable across runs.
  */
 export function runRules(ix: FactIndex): Finding[] {
+  // Enablement is read from the `governance_rule_config` facts so that every
+  // evaluator running the rules over the same index (engine scan, kernel
+  // facts mode) agrees on which rules exist. A disabled rule costs nothing.
+  const { disabled } = readRuleConfig(ix);
   const findings: Finding[] = [];
-  for (const rule of RULES) findings.push(...rule.run(ix));
+  for (const rule of RULES) {
+    if (disabled.has(rule.id)) continue;
+    findings.push(...rule.run(ix));
+  }
   return sortFindings(findings);
 }
 
@@ -211,6 +219,12 @@ export { makeFinding } from "./finding.js";
 // Blocking deny-set (Contract Mode Phase 0): the shared "may this finding
 // hard-deny a write" criteria, used by the CLI pre-write hook and the emit gate.
 export { BLOCKING_RULE_ALLOWLIST, gatesCi, isDenyEligible } from "./emit-gate.js";
+export {
+  capConfiguredSeverity,
+  configuredFindingSeverity,
+  readRuleConfig,
+  type RuleConfigView,
+} from "./rule-config.js";
 export { ruleComponentsUnknownProp } from "./components-unknown-prop.js";
 export { ruleComponentsForbiddenPropValue } from "./components-forbidden-prop-value.js";
 export { ruleComponentsPreferLibrary } from "./components-prefer-library.js";
@@ -232,6 +246,8 @@ export { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js
 export {
   ruleTokensCssVarsMustBeDefined,
   contractTokenReferenceCensus,
+  EMPTY_VOCABULARY_MESSAGE,
+  emptyVocabularyConfigFile,
 } from "./tokens-css-vars-must-be-defined.js";
 export type { ContractTokenReferenceCensus } from "./tokens-css-vars-must-be-defined.js";
 export { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";

package/src/rules/rule-config.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import { FactIndex, makeGovernanceRuleConfigFact } from "../facts/index.js";
+import { capConfiguredSeverity, configuredFindingSeverity, readRuleConfig } from "./rule-config.js";
+
+describe("readRuleConfig", () => {
+  it("splits rule-config facts into disabled ids and configured severities", () => {
+    const ix = new FactIndex();
+    ix.add(makeGovernanceRuleConfigFact({ ruleId: "styles/no-raw-dimensions", enabled: false }));
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "styles/no-raw-color",
+        enabled: true,
+        severity: "info",
+      })
+    );
+    ix.add(makeGovernanceRuleConfigFact({ ruleId: "components/prefer-library", enabled: true }));
+
+    const view = readRuleConfig(ix);
+    expect([...view.disabled]).toEqual(["styles/no-raw-dimensions"]);
+    expect([...view.severities]).toEqual([["styles/no-raw-color", "info"]]);
+  });
+});
+
+describe("capConfiguredSeverity", () => {
+  it("passes a configured severity through for confident findings", () => {
+    expect(capConfiguredSeverity({ severity: "minor" }, "serious")).toBe("serious");
+    expect(capConfiguredSeverity({ severity: "serious" }, "minor")).toBe("minor");
+  });
+
+  it("never promotes an advisory finding to error", () => {
+    const advisory = { attributes: { advisory: true } } as const;
+    expect(capConfiguredSeverity({ severity: "moderate", ...advisory }, "serious")).toBe(
+      "moderate"
+    );
+    expect(capConfiguredSeverity({ severity: "serious", ...advisory }, "critical")).toBe(
+      "moderate"
+    );
+    expect(capConfiguredSeverity({ severity: "serious", ...advisory }, "minor")).toBe("minor");
+  });
+});
+
+describe("configuredFindingSeverity", () => {
+  it("keeps the finding's own severity when the rule has no configured severity", () => {
+    const ix = new FactIndex();
+    const view = readRuleConfig(ix);
+    expect(
+      configuredFindingSeverity({ ruleId: "styles/no-raw-color", severity: "serious" }, view)
+    ).toBe("serious");
+  });
+
+  it("maps the configured level onto the finding", () => {
+    const ix = new FactIndex();
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "styles/no-raw-color",
+        enabled: true,
+        severity: "warn",
+      })
+    );
+    const view = readRuleConfig(ix);
+    expect(
+      configuredFindingSeverity({ ruleId: "styles/no-raw-color", severity: "serious" }, view)
+    ).toBe("moderate");
+  });
+});

package/src/rules/rule-config.ts

@@ -0,0 +1,73 @@
+/**
+ * Rule enablement and configured severity, read from the fact index.
+ *
+ * `govern.rules` is compiled into one `governance_rule_config` fact per rule
+ * (`compileRuleConfigFacts`). Every evaluator that runs the rules — the engine
+ * scan and the Evaluation kernel's facts mode — reads the SAME facts here, so
+ * "which rules exist and how loud they are" cannot diverge between the
+ * findings a scan prints and the verdict that gates `--ci` / a Check Run.
+ *
+ * Before this module the kernel re-ran every rule over the fact index and
+ * ignored the config facts entirely: a rule disabled in `fragments.config.ts`
+ * still blocked under `--ci`, and the CLI printed zero gating findings for the
+ * block (the docs app: 16 `styles/no-raw-dimensions` blocks from a rule the
+ * config turned off).
+ *
+ * Cost: one pass over the rule-config facts per run (tens of facts). A
+ * disabled rule is never executed, so the change removes work rather than
+ * adding any.
+ */
+import type { FactIndex } from "../facts/index.js";
+import type { GovernanceSeverity } from "../governance.js";
+import { severityFromLevel, severityLevel, type Severity } from "../severity.js";
+import type { Finding } from "./types.js";
+
+export interface RuleConfigView {
+  /** Rule ids whose `governance_rule_config` fact says `enabled: false`. */
+  disabled: ReadonlySet<string>;
+  /** Configured severity per enabled rule id (absent = the rule's own default). */
+  severities: ReadonlyMap<string, GovernanceSeverity>;
+}
+
+export function readRuleConfig(ix: FactIndex): RuleConfigView {
+  const disabled = new Set<string>();
+  const severities = new Map<string, GovernanceSeverity>();
+  for (const fact of ix.byKind("governance_rule_config")) {
+    if (!fact.enabled) {
+      disabled.add(fact.ruleId);
+      continue;
+    }
+    if (fact.severity) severities.set(fact.ruleId, fact.severity);
+  }
+  return { disabled, severities };
+}
+
+/**
+ * Apply a configured severity to a finding without erasing the rule's own
+ * confidence boundary: advisory findings (the low-confidence precision tiers a
+ * rule flags with `attributes.advisory`) are useful signal but never
+ * CI-blocking evidence, so a configured `error` caps at the finding's own
+ * severity (or `warn` when the rule itself emitted an error-level face).
+ */
+export function capConfiguredSeverity(
+  finding: Pick<Finding, "severity" | "attributes">,
+  configured: Severity
+): Severity {
+  if (finding.attributes?.advisory === true && severityLevel(configured) === "error") {
+    return severityLevel(finding.severity) === "error"
+      ? severityFromLevel("warn")
+      : finding.severity;
+  }
+  return configured;
+}
+
+/** The severity a finding carries once its rule's configured severity is applied. */
+export function configuredFindingSeverity(
+  finding: Pick<Finding, "ruleId" | "severity" | "attributes">,
+  config: RuleConfigView
+): Severity {
+  const configured = config.severities.get(finding.ruleId);
+  return configured
+    ? capConfiguredSeverity(finding, severityFromLevel(configured))
+    : finding.severity;
+}