@intentset/architecture 0.1.0

package/src/check.ts

@@ -0,0 +1,197 @@
+/**
+ * `checkArchitecture`: the Traceable VSA check over one snapshot (VSA §2,
+ * profile §2–§4). It is pure: the graph and registries come from core, the
+ * repository arrives as a map of path to text, and nothing is read from disk,
+ * executed or fetched (invariant 7), so the conformance harness can run it
+ * over an in-memory tree.
+ *
+ * Order: configuration (`.intentset/architecture.yaml` in the tree, then the
+ * caller's), claims and ownership, the import graph and its boundaries,
+ * dependencies and cycles, then exceptions (VSA §9), then the baseline in
+ * migration mode. What could not be checked is listed in `unresolved` and,
+ * for imports, reported as a TS004 warning: never a pass (invariant 6).
+ */
+import { type Diagnostic, type Graph, type Level, type Registries, sortDiagnostics } from "@intentset/core";
+import { applyBaseline, type BaselineEntry, type Mode } from "./baseline.ts";
+import { checkBoundaries, checkUnclassified } from "./boundaries.ts";
+import { checkClaims } from "./claims.ts";
+import { ARCHITECTURE_CONFIG_PATH, type ArchitectureConfig, readArchitectureConfig, resolveConfig } from "./config.ts";
+import { checkDependencies } from "./dependencies.ts";
+import { applyExceptions, type ExceptionRecord, readExceptionRecord, readExceptions } from "./exceptions.ts";
+import { type Finding, finding } from "./finding.ts";
+import { buildImportGraph, type ImportEdge } from "./imports.ts";
+import { checkOwnership } from "./ownership.ts";
+import { isCode } from "./paths.ts";
+import { compareStrings } from "./patterns.ts";
+import { buildModel } from "./regions.ts";
+import { Resolver } from "./resolve.ts";
+
+export interface CheckOptions {
+  /** Laid over the defaults and over `.intentset/architecture.yaml`. */
+  config?: Partial<ArchitectureConfig>;
+  /** Conformance level; VSA001 runs at L2 and above. Default L2. */
+  level?: Level;
+  /** Exception records handed in, in addition to architecture/exceptions/*.yaml in the tree. */
+  exceptions?: readonly (ExceptionRecord | Record<string, unknown>)[];
+  baseline?: readonly BaselineEntry[];
+  /** "migration" applies the baseline; "strict" ignores it. Default migration. */
+  mode?: Mode;
+  /** The date exceptions expire against, YYYY-MM-DD. Default today, UTC. */
+  today?: string;
+  /** Where registries.yaml lives, for diagnostics about resources. Default "registries.yaml". */
+  registriesPath?: string;
+}
+
+export interface ArchitectureSummary {
+  mode: Mode;
+  level: Level;
+  /** Active (non-retired) slices. */
+  slices: number;
+  /** Files, tests excluded, that some slice claims. */
+  filesClaimed: number;
+  /** In-scope code files under source and backend roots that no slice, region or resource owns. */
+  filesUnclaimed: number;
+  /** Code files outside the declared scope: counted, never reported one by one (Core §11). */
+  outOfScope: number;
+  /** Resolved file-to-file import edges from in-scope production files. */
+  edges: number;
+  /** Those that cross from one slice into another. */
+  crossSliceEdges: number;
+  /** Dependency cycles found (VSA005), excepted or not. */
+  cycles: number;
+  /** Diagnostics a current exception turned into warnings. */
+  excepted: number;
+  /** Diagnostics the baseline turned into warnings (migration mode only). */
+  baselined: number;
+  /** Baseline entries that matched nothing and can be retired. */
+  baselineStale: number;
+  /** What could not be checked: never a pass (invariant 6). */
+  unresolved: string[];
+  /** Rules this check cannot decide from source and leaves to review (VSA §2). */
+  reviewRequired: string[];
+}
+
+export interface ArchitectureResult {
+  diagnostics: Diagnostic[];
+  summary: ArchitectureSummary;
+  /** The resolved import graph, for reports and impact views. */
+  edges: ImportEdge[];
+}
+
+/** VSA §2: the rules that are review assertions, snapshot diffs or contract diffs rather than structure. */
+export const REVIEW_REQUIRED = [
+  "VSA007 business behavior is not owned by shared, infrastructure or composition: an architecture review assertion",
+  "VSA008 verification definitions cover negative and authorization cases: core links plus review",
+  "VSA010 backend access passes through the seam: imports are checked, dynamic network access is not",
+  "VSA011 public contract changes carry a compatibility assessment: needs a contract diff and review record",
+  "VSA012 deleting or splitting a slice dispositions what it owned: needs a diff between two snapshots",
+  "TS005 runtime resolver and type-checker agree on aliases: bundler configuration is not read",
+];
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function checkArchitecture(
+  graph: Graph,
+  registries: Registries,
+  tree: { files: ReadonlyMap<string, string> },
+  options: CheckOptions = {},
+): ArchitectureResult {
+  const level = options.level ?? "L2";
+  const mode = options.mode ?? "migration";
+  const registriesPath = options.registriesPath ?? "registries.yaml";
+  const configDiagnostics: Diagnostic[] = [];
+  let fileConfig: Partial<ArchitectureConfig> | undefined;
+  const configText = tree.files.get(ARCHITECTURE_CONFIG_PATH);
+  if (configText !== undefined) {
+    const read = readArchitectureConfig(configText, ARCHITECTURE_CONFIG_PATH);
+    fileConfig = read.config;
+    configDiagnostics.push(...read.diagnostics);
+  }
+  const config = resolveConfig(fileConfig, options.config);
+  const model = buildModel(graph, registries, tree.files, config);
+  const unresolved: string[] = [];
+
+  for (const slice of model.slices) {
+    for (const i of slice.invalidClaims) {
+      unresolved.push(
+        `${slice.path}: claim ${i} of ${slice.id} (${slice.meta.claims[i].path}) is not a valid pattern and was not resolved`,
+      );
+    }
+  }
+
+  const codeFiles = new Map([...model.files].filter(([path]) => isCode(path)));
+  const resolver = new Resolver(model.files, config);
+  const imports = buildImportGraph(codeFiles, resolver);
+  const findings: Finding[] = [];
+  for (const item of imports.unresolved) {
+    if (!model.inScope(item.path)) continue;
+    const where = item.line === null ? item.path : `${item.path}:${item.line}`;
+    unresolved.push(`${where}: ${item.message}`);
+    findings.push(
+      finding({
+        code: "TS004",
+        severity: "warning",
+        artifact: model.regionOf(item.path).kind === "slice" ? (model.regionOf(item.path).owner ?? null) : null,
+        path: item.path,
+        ...(item.line !== null ? { location: { line: item.line } } : {}),
+        message: `${item.message.charAt(0).toUpperCase()}${item.message.slice(1)}; the reference was left out of boundary analysis.`,
+        remediation:
+          "Use a literal specifier that resolves to a file in the repository or to a package, so the boundary can be checked (TS004).",
+      }),
+    );
+  }
+  for (const note of [...resolver.tsconfigs.notes, ...resolver.notes]) unresolved.push(`${note.path}: ${note.message}`);
+
+  findings.push(...checkClaims(model, graph, registriesPath));
+  findings.push(...checkOwnership(model, graph, level));
+  const boundaries = checkBoundaries(model, imports.edges, resolver);
+  findings.push(...boundaries.findings);
+  findings.push(...checkUnclassified(model));
+  const dependencies = checkDependencies(model, graph, boundaries.sliceEdges);
+  findings.push(...dependencies.findings);
+
+  // Exceptions: the tree's records and any handed in.
+  const fromTree = readExceptions(model.files);
+  const records = [...fromTree.records];
+  const recordProblems = [...fromTree.findings];
+  for (const raw of options.exceptions ?? []) {
+    const { source, ...fields } = raw as Record<string, unknown>;
+    const read = readExceptionRecord(fields, typeof source === "string" ? source : null);
+    recordProblems.push(...read.findings);
+    if (read.record !== null) records.push(read.record);
+  }
+  const excepted = applyExceptions(findings, records, options.today ?? today());
+
+  let diagnostics: Diagnostic[] = [
+    ...configDiagnostics,
+    ...excepted.findings.map((item) => item.diagnostic),
+    ...recordProblems.map((item) => item.diagnostic),
+    ...excepted.recordFindings.map((item) => item.diagnostic),
+  ];
+  const baseline = applyBaseline(diagnostics, options.baseline ?? [], mode);
+  diagnostics = sortDiagnostics(baseline.diagnostics);
+
+  const owned = (path: string) => {
+    const kind = model.regionOf(path).kind;
+    return kind !== "backend" && kind !== "unowned";
+  };
+  const summary: ArchitectureSummary = {
+    mode,
+    level,
+    slices: model.slices.length,
+    filesClaimed: model.production.filter((path) => (model.claimOwners.get(path) ?? []).length > 0).length,
+    filesUnclaimed: model.production.filter((path) => isCode(path) && model.inScope(path) && !owned(path)).length,
+    outOfScope: [...model.files.keys()].filter((path) => isCode(path) && !model.inScope(path)).length,
+    edges: boundaries.fileEdges,
+    crossSliceEdges: boundaries.crossSliceEdges,
+    cycles: dependencies.cycles,
+    excepted: excepted.excepted,
+    baselined: baseline.baselined,
+    baselineStale: baseline.stale.length,
+    unresolved: [...new Set(unresolved)].sort(compareStrings),
+    reviewRequired: [...REVIEW_REQUIRED],
+  };
+  return { diagnostics, summary, edges: imports.edges };
+}

package/src/claims.ts

@@ -0,0 +1,229 @@
+/**
+ * Path and resource ownership (VSA §3, §7; VSA009; profile AMP004).
+ *
+ * - A nonempty claim that matches no file is VSA009.
+ * - Two slices resolving one file is VSA009, once per pair of claims, naming
+ *   both slices, both claims and the files.
+ * - A file claimed by a slice and recorded as a registry resource has two
+ *   owners, which is VSA009 too: a shared resource has one recorded owner.
+ * - A registry resource path that matches no file, or names a consumer that
+ *   is no slice, is VSA009; consumers and `usesResources` that disagree are
+ *   a VSA009 warning, since the registry restates what the slices declare.
+ * - A code file under a backend root owned by no slice and no resource is
+ *   AMP004; one under a source root owned by nothing is VSA009. Both only
+ *   inside the declared scope.
+ *
+ * A resource that a slice uses but the registry does not declare is core's
+ * CORE003, and an invalid claim pattern core already rejects is CORE001;
+ * neither is repeated here.
+ */
+import { type Graph, patternProblem } from "@intentset/core";
+import { type Finding, finding, listSome, plural } from "./finding.ts";
+import { isCode } from "./paths.ts";
+import { compareStrings, validatePattern } from "./patterns.ts";
+import type { Model } from "./regions.ts";
+
+export function checkClaims(model: Model, graph: Graph, registriesPath: string): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const slice of model.slices) {
+    slice.meta.claims.forEach((claim, i) => {
+      const field = `/intentset/slice/claims/${i}/path`;
+      const why = validatePattern(claim.path);
+      if (why !== null) {
+        if (patternProblem(claim.path) === null) {
+          findings.push(
+            finding({
+              code: "VSA009",
+              artifact: slice.id,
+              path: slice.path,
+              field,
+              message: `Claim ${i} of ${slice.id}, ${claim.path}, ${why}, so it resolves to no file.`,
+              remediation: "Use literal segments, `*` within a segment and `**` standing alone as a segment (VSA §3).",
+            }),
+          );
+        }
+        return;
+      }
+      if (slice.claimFiles[i].length === 0) {
+        findings.push(
+          finding({
+            code: "VSA009",
+            artifact: slice.id,
+            path: slice.path,
+            field,
+            message: `The ${claim.kind} claim ${claim.path} of ${slice.id} matches no file in the repository.`,
+            remediation:
+              "Correct the path, add the files it promises, or remove the claim; an empty claim is not ownership (VSA §3).",
+          }),
+        );
+      }
+    });
+  }
+
+  // Two slices, one file: one finding per pair of claims.
+  const pairs = new Map<
+    string,
+    { a: { slice: string; claim: number }; b: { slice: string; claim: number }; files: string[] }
+  >();
+  for (const [file, owners] of [...model.claimOwners].sort(([x], [y]) => compareStrings(x, y))) {
+    for (let x = 0; x < owners.length; x++) {
+      for (let y = x + 1; y < owners.length; y++) {
+        if (owners[x].slice === owners[y].slice) continue;
+        const [a, b] = [owners[x], owners[y]].sort((p, q) => compareStrings(p.slice, q.slice) || p.claim - q.claim);
+        const key = `${a.slice}#${a.claim}|${b.slice}#${b.claim}`;
+        const entry = pairs.get(key) ?? { a, b, files: [] };
+        entry.files.push(file);
+        pairs.set(key, entry);
+      }
+    }
+  }
+  for (const key of [...pairs.keys()].sort(compareStrings)) {
+    const { a, b, files } = pairs.get(key)!;
+    const sliceA = model.sliceById.get(a.slice)!;
+    const sliceB = model.sliceById.get(b.slice)!;
+    const claimA = sliceA.meta.claims[a.claim].path;
+    const claimB = sliceB.meta.claims[b.claim].path;
+    findings.push(
+      finding({
+        code: "VSA009",
+        artifact: a.slice,
+        path: files[0],
+        message: `${a.slice} (claim ${claimA}) and ${b.slice} (claim ${claimB}) both resolve ${plural(files.length, "file")}: ${listSome(files)}.`,
+        remediation: `Narrow one claim so each file has one owner, or extract the shared code into a contract or a technical owner (VSA §3).`,
+        paths: [...files, sliceA.path, sliceB.path],
+        edges: [{ from: a.slice, to: b.slice }],
+      }),
+    );
+  }
+
+  // A resource has one recorded owner; a slice claiming its file is a second.
+  for (const info of model.resources) {
+    const { resource, index, files } = info;
+    const field = `/resources/${index}/path`;
+    const why = validatePattern(resource.path);
+    if (why !== null) {
+      findings.push(
+        finding({
+          code: "VSA009",
+          artifact: null,
+          path: registriesPath,
+          field,
+          message: `Resource ${resource.id} has the path ${resource.path}, which ${why}.`,
+          remediation: "Give the repository-relative path or pattern of the files that define the resource (VSA §3).",
+        }),
+      );
+      continue;
+    }
+    if (files.length === 0) {
+      findings.push(
+        finding({
+          code: "VSA009",
+          artifact: null,
+          path: registriesPath,
+          field,
+          message: `Resource ${resource.id} records the path ${resource.path}, which matches no file in the repository.`,
+          remediation: "Correct the path to the file that defines the resource, or remove the record (VSA §7).",
+        }),
+      );
+    }
+    const claimedBy = new Map<string, string[]>();
+    for (const file of files) {
+      for (const owner of model.claimOwners.get(file) ?? []) {
+        const list = claimedBy.get(owner.slice) ?? [];
+        if (!list.includes(file)) list.push(file);
+        claimedBy.set(owner.slice, list);
+      }
+    }
+    for (const sliceId of [...claimedBy.keys()].sort(compareStrings)) {
+      const claimed = claimedBy.get(sliceId)!;
+      findings.push(
+        finding({
+          code: "VSA009",
+          artifact: sliceId,
+          path: claimed[0],
+          message: `${listSome(claimed)} ${claimed.length === 1 ? "is" : "are"} recorded as resource ${resource.id}, owned by ${resource.owner}, and also claimed by ${sliceId}.`,
+          remediation: `Keep the resource's one recorded owner and have ${sliceId} list ${resource.id} in usesResources instead of claiming its file (VSA §7, profile §6).`,
+          paths: [...claimed, model.sliceById.get(sliceId)!.path],
+          edges: [{ from: sliceId, to: resource.id }],
+        }),
+      );
+    }
+
+    resource.consumers.forEach((consumer, k) => {
+      const artifact = graph.artifacts.get(consumer);
+      if (artifact === undefined || artifact.meta.type !== "slice") {
+        findings.push(
+          finding({
+            code: "VSA009",
+            artifact: null,
+            path: registriesPath,
+            field: `/resources/${index}/consumers/${k}`,
+            message: `Resource ${resource.id} lists the consumer ${consumer}, which is not a slice in the graph.`,
+            remediation: "List the IDs of the slices that use the resource, as they appear in their usesResources.",
+          }),
+        );
+      } else if (!(artifact.meta.slice?.usesResources ?? []).includes(resource.id)) {
+        findings.push(
+          finding({
+            code: "VSA009",
+            severity: "warning",
+            artifact: consumer,
+            path: registriesPath,
+            field: `/resources/${index}/consumers/${k}`,
+            message: `Resource ${resource.id} lists ${consumer} as a consumer, but ${consumer} does not list it in usesResources.`,
+            remediation: `Add ${resource.id} to the usesResources of ${consumer}, or remove ${consumer} from the resource's consumers.`,
+          }),
+        );
+      }
+    });
+  }
+  const resourceById = new Map(model.resources.map((info) => [info.resource.id, info.resource]));
+  for (const slice of model.slices) {
+    slice.meta.usesResources.forEach((id, k) => {
+      const resource = resourceById.get(id);
+      if (resource === undefined || resource.consumers.includes(slice.id)) return;
+      findings.push(
+        finding({
+          code: "VSA009",
+          severity: "warning",
+          artifact: slice.id,
+          path: slice.path,
+          field: `/intentset/slice/usesResources/${k}`,
+          message: `${slice.id} uses resource ${id}, but the registry does not list it among the resource's consumers.`,
+          remediation: `Add ${slice.id} to the consumers of ${id} in the registry, so the deployment inventory matches the slices.`,
+        }),
+      );
+    });
+  }
+
+  // Unowned files inside the declared scope.
+  for (const file of model.production) {
+    if (!isCode(file) || !model.inScope(file)) continue;
+    const region = model.regionOf(file);
+    if (region.kind === "backend") {
+      findings.push(
+        finding({
+          code: "AMP004",
+          artifact: null,
+          path: file,
+          message: `Backend file ${file} is claimed by no slice and recorded as no resource.`,
+          remediation:
+            "Add it to the backend claim of the slice that owns it, or record it in the resource registry with its technical owner (AMP004).",
+        }),
+      );
+    } else if (region.kind === "unowned") {
+      findings.push(
+        finding({
+          code: "VSA009",
+          artifact: null,
+          path: file,
+          message: `Source file ${file} is claimed by no slice and lies in no shared, infrastructure or composition region.`,
+          remediation: "Claim it from the slice that owns it, or move it into a declared region (VSA §3, VSA009).",
+        }),
+      );
+    }
+  }
+
+  return findings;
+}

package/src/config.ts

@@ -0,0 +1,212 @@
+/**
+ * Where the regions are, what counts as a test, which files may import
+ * screens or the response parser, and the declared scope (VSA §5, §6, §9;
+ * profile §2–§4). Every value has a default for the reference layout of
+ * profile §1. A repository states its own in `.intentset/architecture.yaml`,
+ * a file of its own because `.intentset/config.yaml` belongs to core and
+ * rejects keys it does not know.
+ */
+import { type Diagnostic, parseYamlDetailed } from "@intentset/core";
+import { compareStrings, validatePattern } from "./patterns.ts";
+
+export const ARCHITECTURE_CONFIG_PATH = ".intentset/architecture.yaml";
+
+export interface ArchitectureConfig {
+  /** Declared scope (VSA §9, Core §11): files outside it are counted, never reported one by one. */
+  scope: string[];
+  /** Where product source lives; an in-scope code file here that nothing owns is VSA009. */
+  sourceRoots: string[];
+  /** Neutral shared abstractions (VSA §5). */
+  shared: string[];
+  /** Technical infrastructure (VSA §5). */
+  infrastructure: string[];
+  /** Application and route composition (VSA §6). */
+  composition: string[];
+  /** The unified backend deployment root (profile §1, AMP001, AMP004). */
+  backendRoots: string[];
+  /** The named Router files that may import screens directly (TS003). Never widened to a directory by default. */
+  routerFiles: string[];
+  /** The named response-parser modules a client seam may import from the backend (profile §4 inherited exception). */
+  responseParserModules: string[];
+  /** Generated, vendored and build output: excluded from everything (VSA §3 versioned ignore list). */
+  ignore: string[];
+  /** Test files: excluded from boundary checks except foreign internals (profile §3). */
+  tests: string[];
+  /** Screens; only a router file may import another slice's (TS003). */
+  screensGlob: string;
+  /** Backend SDK specifiers, matched as patterns against the import specifier (AMP002, AMP006). */
+  backendSdks: string[];
+  /** The internal layer matrix (profile §3): each layer may import itself and the layers listed. */
+  layerMatrix: Record<string, string[]>;
+  /** Export conditions tried first when resolving a workspace package's entry, before types, import and default. */
+  conditions: string[];
+}
+
+export const DEFAULT_ARCHITECTURE_CONFIG: ArchitectureConfig = {
+  scope: ["**"],
+  sourceRoots: ["src/**"],
+  shared: ["src/shared/**"],
+  infrastructure: ["src/infrastructure/**"],
+  composition: ["src/app/**"],
+  backendRoots: ["amplify/**"],
+  routerFiles: [],
+  responseParserModules: [],
+  ignore: ["**/node_modules/**", "**/dist/**", ".git/**"],
+  tests: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"],
+  screensGlob: "**/ui/screens/**",
+  backendSdks: ["aws-amplify/**", "@aws-amplify/**", "@aws-sdk/**"],
+  layerMatrix: {
+    presentation: ["presentation", "application", "policy", "model"],
+    application: ["application", "policy", "model", "external"],
+    policy: ["policy", "model"],
+    model: ["model"],
+    external: ["external", "model"],
+  },
+  conditions: [],
+};
+
+const LIST_KEYS = [
+  "scope",
+  "sourceRoots",
+  "shared",
+  "infrastructure",
+  "composition",
+  "backendRoots",
+  "routerFiles",
+  "responseParserModules",
+  "ignore",
+  "tests",
+  "backendSdks",
+  "conditions",
+] as const;
+
+/** Keys whose entries are path patterns and must pass validatePattern. */
+const PATTERN_KEYS = new Set<string>([
+  "scope",
+  "sourceRoots",
+  "shared",
+  "infrastructure",
+  "composition",
+  "backendRoots",
+  "routerFiles",
+  "responseParserModules",
+  "ignore",
+  "tests",
+  "screensGlob",
+]);
+
+const KNOWN_KEYS = [...LIST_KEYS, "screensGlob", "layerMatrix"].sort(compareStrings);
+
+/** The defaults with a partial configuration laid over them; a key given replaces the default whole. */
+export function resolveConfig(...layers: (Partial<ArchitectureConfig> | undefined)[]): ArchitectureConfig {
+  const config: ArchitectureConfig = structuredClone(DEFAULT_ARCHITECTURE_CONFIG);
+  for (const layer of layers) {
+    if (layer === undefined) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      if (value !== undefined) (config as unknown as Record<string, unknown>)[key] = structuredClone(value);
+    }
+  }
+  return config;
+}
+
+/**
+ * Read `.intentset/architecture.yaml` with core's strict reader. Every key is
+ * optional; an unknown key, a wrong shape or an invalid pattern is CFG001
+ * with origin "architecture", and that key keeps its default.
+ */
+export function readArchitectureConfig(
+  text: string,
+  path: string = ARCHITECTURE_CONFIG_PATH,
+): { config: Partial<ArchitectureConfig>; diagnostics: Diagnostic[] } {
+  const config: Partial<ArchitectureConfig> = {};
+  const diagnostics: Diagnostic[] = [];
+  const parsed = parseYamlDetailed(text);
+  const report = (field: string | undefined, line: number | undefined, message: string, remediation: string) => {
+    diagnostics.push({
+      code: "CFG001",
+      severity: "error",
+      origin: "architecture",
+      artifact: null,
+      path,
+      ...(line !== undefined ? { location: { line } } : {}),
+      ...(field !== undefined ? { field } : {}),
+      message,
+      remediation,
+    });
+  };
+  if (parsed.error !== null) {
+    report(
+      undefined,
+      parsed.error.line,
+      `The architecture configuration does not parse: ${parsed.error.message}`,
+      "Write it as a block mapping of the keys documented for ArchitectureConfig.",
+    );
+    return { config, diagnostics };
+  }
+  const root = parsed.value;
+  const at = (field: string) => parsed.lines.get(field);
+
+  for (const key of Object.keys(root).sort(compareStrings)) {
+    const field = `/${key}`;
+    const value = root[key];
+    if (!KNOWN_KEYS.includes(key)) {
+      report(
+        field,
+        at(field),
+        `Unknown architecture configuration key \`${key}\`.`,
+        `Remove it; the keys are ${KNOWN_KEYS.join(", ")}.`,
+      );
+      continue;
+    }
+    if (value === null) continue;
+    if (key === "screensGlob") {
+      const why = typeof value === "string" ? validatePattern(value) : "is not a string";
+      if (why !== null) {
+        report(field, at(field), `screensGlob ${why}.`, "Give one pattern such as **/ui/screens/**.");
+      } else config.screensGlob = value as string;
+      continue;
+    }
+    if (key === "layerMatrix") {
+      const matrix = readMatrix(value);
+      if (matrix === null) {
+        report(
+          field,
+          at(field),
+          "layerMatrix must map each layer name to a list of layer names.",
+          "Write each layer as `presentation: [presentation, application]`.",
+        );
+      } else config.layerMatrix = matrix;
+      continue;
+    }
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item !== "")) {
+      report(field, at(field), `\`${key}\` must be a list of non-empty strings.`, `Write ${key} as a sequence.`);
+      continue;
+    }
+    const list = value as string[];
+    if (PATTERN_KEYS.has(key)) {
+      const bad = list.findIndex((pattern) => validatePattern(pattern) !== null);
+      if (bad !== -1) {
+        const pointer = `${field}/${bad}`;
+        report(
+          pointer,
+          at(pointer) ?? at(field),
+          `Pattern ${list[bad]} in \`${key}\` ${validatePattern(list[bad])}.`,
+          "Use literal segments, `*` within a segment and `**` across segments only (VSA §3).",
+        );
+        continue;
+      }
+    }
+    (config as Record<string, unknown>)[key] = [...list];
+  }
+  return { config, diagnostics };
+}
+
+function readMatrix(value: unknown): Record<string, string[]> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const matrix: Record<string, string[]> = {};
+  for (const [layer, targets] of Object.entries(value)) {
+    if (!Array.isArray(targets) || !targets.every((item) => typeof item === "string")) return null;
+    matrix[layer] = [...(targets as string[])];
+  }
+  return matrix;
+}