@sdd-method/maintain-cli 0.0.0-stage → 0.1.0-rc.0

package/dist/lib/catalogue/aggregation-manifest-loader.js

@@ -0,0 +1,173 @@
+// Aggregation-manifest loader per
+// docs/method/methods/aggregation-manifest-schema.yaml.
+//
+// v1 supports `pull.kind: filesystem` only; other kinds (git-ref,
+// release-asset, mcp-resource) are schema-reserved and reject with a
+// clear "deferred" error so adopters get unambiguous feedback.
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { SCHEMA_COMPAT, formatSchemaVersionMismatch } from "./schema-compat.js";
+import { isInRange } from "./manifest-loader.js";
+export const DEFAULT_AGGREGATION_MANIFEST_REL = "orchestration/aggregation-manifest.yaml";
+const PullSchema = z
+    .object({
+    kind: z.string(),
+    path: z.string().optional(),
+})
+    .passthrough();
+const SiblingSchema = z.object({
+    sdd_id: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+        message: "sdd_id must match /^[a-z][a-z0-9-]*$/",
+    }),
+    pull: PullSchema,
+    description: z.string().optional(),
+    level: z.string().optional(),
+});
+/**
+ * An ecosystem member that is real and intended but has no SDD yet
+ * (aggregation-manifest-schema 1.1.0, per M-ADR 0195 §4.3).
+ *
+ * A SEPARATE list rather than a flag on `siblings[]`: `pull` is required on a sibling
+ * and a pending member has nothing to pull, and `siblings[]` must keep meaning exactly
+ * "members whose catalogues merge in" — adding skippable entries would give one list
+ * two meanings, which every existing reader would keep miscounting.
+ *
+ * `reason` is required and non-empty. A bare marker suppresses the build failure while
+ * saying nothing about why, losing the signal that a pending member is a WORK ITEM —
+ * the state this replaces.
+ */
+const PendingMemberSchema = z.object({
+    sdd_id: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+        message: "pending_members[].sdd_id must match /^[a-z][a-z0-9-]*$/",
+    }),
+    reason: z.string().min(1, {
+        message: "pending_members[].reason must be non-empty — a marker without a reason suppresses a failure without explaining it",
+    }),
+    blocked_on: z.string().optional(),
+});
+const SLUG = /^[a-z][a-z0-9-]*$/;
+// M-ADR 0208 §4.3: `root_sdd_id` is canonical; `ecosystem_root` is its DEPRECATED alias
+// (at organisation tier the old name called an organisation-root an "ecosystem root").
+// Exactly one of the two must be present. Removed at 2.0.0.
+const AggregationManifestSchema = z
+    .object({
+    schema_version: z.string(),
+    root_sdd_id: z.string().regex(SLUG).optional(),
+    ecosystem_root: z.string().regex(SLUG).optional(),
+    level: z.enum(["platform", "organisation"]).optional(),
+    siblings: z.array(SiblingSchema),
+    pending_members: z.array(PendingMemberSchema).optional(),
+})
+    .refine((m) => (m.root_sdd_id !== undefined) !== (m.ecosystem_root !== undefined), {
+    message: "exactly one of `root_sdd_id` (canonical, M-ADR 0208 §4.3) or `ecosystem_root` (deprecated alias) must be present",
+});
+export async function loadAggregationManifest(manifestPath, options) {
+    let text;
+    try {
+        text = await readFile(manifestPath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Aggregation manifest not found at ${manifestPath}\n\n` +
+                `Ecosystem-root SDDs declare an aggregation manifest at the path\n` +
+                `recorded in .sdd/sdd-manifest.yaml#aggregation_manifest_path, or\n` +
+                `at ${DEFAULT_AGGREGATION_MANIFEST_REL} by default.\n` +
+                `Schema: docs/method/methods/aggregation-manifest-schema.yaml.`);
+        }
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`failed to parse YAML at ${manifestPath}: ${err.message}`);
+    }
+    const parsed = AggregationManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("\n");
+        throw new Error(`invalid aggregation manifest at ${manifestPath}:\n${issues}`);
+    }
+    if (!isInRange(parsed.data.schema_version, SCHEMA_COMPAT.aggregation_manifest)) {
+        throw new Error(formatSchemaVersionMismatch({
+            schema: "aggregation_manifest",
+            readVersion: parsed.data.schema_version,
+            cliVersion: options.cliVersion,
+            sourcePath: manifestPath,
+        }));
+    }
+    // Duplicate sibling-id check.
+    const seen = new Set();
+    for (const s of parsed.data.siblings) {
+        if (seen.has(s.sdd_id)) {
+            throw new Error(`aggregation manifest has duplicate sibling sdd_id "${s.sdd_id}"\n` +
+                `  (${manifestPath})`);
+        }
+        seen.add(s.sdd_id);
+    }
+    // Resolve each sibling's pull. v1 supports `kind: filesystem` only.
+    const resolved = [];
+    for (const s of parsed.data.siblings) {
+        const kind = s.pull.kind;
+        if (kind !== "filesystem") {
+            throw new Error(`aggregation manifest: sibling "${s.sdd_id}" uses pull.kind="${kind}"\n` +
+                `  v1 supports filesystem only. Other kinds (git-ref, release-asset,\n` +
+                `  mcp-resource) are schema-reserved and not yet implemented.\n` +
+                `  See: docs/method/methods/aggregation-manifest-schema.yaml#pull_kinds`);
+        }
+        const path = s.pull.path;
+        if (!path || typeof path !== "string") {
+            throw new Error(`aggregation manifest: sibling "${s.sdd_id}" pull.kind=filesystem requires \`path\``);
+        }
+        const cataloguesPath = isAbsolute(path)
+            ? path
+            : resolve(options.ecosystemRootPath, path);
+        // The sibling's repo root is the parent of `catalogues/`.
+        const sddRoot = resolve(cataloguesPath, "..");
+        // Portable form for the committed JSON snapshot: keep a relative source
+        // verbatim; anchor an absolute source to the ecosystem root so the emitted
+        // value never carries a machine-specific $HOME/checkout prefix.
+        const relativeCataloguesPath = isAbsolute(path)
+            ? relative(options.ecosystemRootPath, cataloguesPath)
+            : path;
+        resolved.push({
+            sddId: s.sdd_id,
+            description: s.description ?? "",
+            cataloguesPath,
+            relativeCataloguesPath,
+            sddRoot,
+            level: s.level,
+        });
+    }
+    // A member is pending authoring OR contributing catalogues, never both. Declaring
+    // both is a contradiction rather than something to merge, and silently preferring
+    // one reading would make the work queue untrustworthy — so it fails with the id.
+    const pendingMembers = [];
+    const siblingIds = new Set(resolved.map((r) => r.sddId));
+    for (const p of parsed.data.pending_members ?? []) {
+        if (siblingIds.has(p.sdd_id)) {
+            throw new Error(`aggregation manifest: "${p.sdd_id}" appears in BOTH siblings and pending_members.\n` +
+                `  A member is either pending authoring or contributing catalogues, not both.\n` +
+                `  Remove whichever declaration is stale (${parsed.data.root_sdd_id ?? parsed.data.ecosystem_root}).`);
+        }
+        pendingMembers.push({
+            sddId: p.sdd_id,
+            reason: p.reason,
+            ...(p.blocked_on !== undefined ? { blockedOn: p.blocked_on } : {}),
+        });
+    }
+    return {
+        schemaVersion: parsed.data.schema_version,
+        ecosystemRoot: (parsed.data.root_sdd_id ?? parsed.data.ecosystem_root),
+        level: parsed.data.level,
+        rootFieldDeprecated: parsed.data.root_sdd_id === undefined,
+        siblings: resolved,
+        pendingMembers,
+        sourcePath: manifestPath,
+    };
+}
+//# sourceMappingURL=aggregation-manifest-loader.js.map

package/dist/lib/catalogue/application-archetype/expectations.js

@@ -0,0 +1,119 @@
+// Archetype expectations overlay — the deviation-visible WARN (M-ADR 0191 §4.3,
+// given concrete content by M-ADR 0193 §4.4).
+//
+// An archetype supplies a DEFAULT data-plane composition (its `expected_bindings`
+// in the reference-architecture vocabulary). A product's declared bindings are
+// checked against that default:
+//   - a `required` expected pattern with no declared binding of that pattern, OR
+//   - a declared binding whose pattern is `absent-by-shape` for the archetype,
+// is a deviation. A deviation is a WARN (`convention` finding) UNLESS the product
+// declares a matching `data_plane.deviations` rationale — a declared deviation is
+// sanctioned variance, not silent drift.
+//
+// `typical` and `optional` expectations are advisory only: neither presence nor
+// absence warns. The check runs only when the archetype's overlay is discoverable
+// (the reference-architecture bundle is consumed); absence of an overlay is a
+// silent skip, never a coupling to bundle presence (M-ADR 0191 §4.1).
+import { UNCLASSIFIED } from "./vocabulary.js";
+/**
+ * Emit a deviation-visible WARN for each undeclared departure from the
+ * archetype's default composition. Returns the number of WARNs emitted.
+ */
+export function checkDataPlaneExpectations(inputs) {
+    const { productId, archetype, expectedBindings, declaredBindings, deviations, findings } = inputs;
+    const declaredPatterns = new Set(declaredBindings.map((b) => b.pattern));
+    const covered = new Set(deviations.map((d) => d.expectation));
+    let warned = 0;
+    for (const expected of expectedBindings) {
+        if (covered.has(expected.pattern))
+            continue; // declared deviation — sanctioned
+        if (expected.presence === "required" && !declaredPatterns.has(expected.pattern)) {
+            findings.add("convention", `data_plane: archetype "${archetype}" expects a required "${expected.pattern}" binding for ${productId}, ` +
+                `but none is declared and no data_plane.deviations rationale covers it (M-ADR 0191 §4.3)`);
+            warned++;
+        }
+        else if (expected.presence === "absent-by-shape" && declaredPatterns.has(expected.pattern)) {
+            findings.add("convention", `data_plane: archetype "${archetype}" is not expected to carry a "${expected.pattern}" binding ` +
+                `(absent-by-shape), but ${productId} declares one and no data_plane.deviations rationale covers it ` +
+                `(M-ADR 0191 §4.3)`);
+            warned++;
+        }
+    }
+    return warned;
+}
+/**
+ * Run the M-ADR 0191 §4.3 overlay at AGGREGATION tier — the deviation-visible
+ * WARN and the conformance surface — across every application-product. This is
+ * the tier where the reference-architecture bundle (and its `expected_bindings`)
+ * resolves; a per-SDD run would be inert for an SDD that consumes an adopter
+ * context-pack rather than the RA bundle (M-ADR 0191 §4.1; the 0.92.1 membership
+ * move). An archetype with no discoverable overlay is silently skipped.
+ */
+export function checkDataPlaneOverlayAtAggregation(inputs) {
+    const { products, bindings, deviations, conformanceCoverage, vocab, findings } = inputs;
+    const bindingsByProduct = new Map();
+    for (const b of bindings) {
+        const pid = String(b["product_id"] ?? "");
+        if (pid === "")
+            continue;
+        (bindingsByProduct.get(pid) ?? bindingsByProduct.set(pid, []).get(pid)).push({
+            pattern: String(b["pattern"] ?? ""),
+        });
+    }
+    const deviationsByProduct = new Map();
+    for (const d of deviations) {
+        const pid = String(d["product_id"] ?? "");
+        if (pid === "")
+            continue;
+        (deviationsByProduct.get(pid) ?? deviationsByProduct.set(pid, []).get(pid)).push({
+            expectation: String(d["expectation"] ?? ""),
+        });
+    }
+    // Conformance coverage: per product, the set of tags declared covered or
+    // deviated (both satisfy the gate — deviated is sanctioned variance).
+    const conformanceByProduct = new Map();
+    for (const c of conformanceCoverage) {
+        const pid = String(c["product_id"] ?? "");
+        const tag = String(c["tag"] ?? "");
+        if (pid === "" || tag === "")
+            continue;
+        (conformanceByProduct.get(pid) ?? conformanceByProduct.set(pid, new Set()).get(pid)).add(tag);
+    }
+    for (const p of products) {
+        if (String(p["profile"] ?? "") !== "application-product")
+            continue;
+        const archetype = String(p["application_archetype"] ?? "");
+        if (archetype === "" || archetype === UNCLASSIFIED)
+            continue;
+        const productId = String(p["id"] ?? "");
+        if (productId === "")
+            continue;
+        const term = vocab.terms.find((t) => t.id === archetype);
+        if (term === undefined)
+            continue;
+        if (term.expectedBindings !== undefined && term.expectedBindings.length > 0) {
+            checkDataPlaneExpectations({
+                productId,
+                archetype,
+                expectedBindings: term.expectedBindings,
+                declaredBindings: bindingsByProduct.get(productId) ?? [],
+                deviations: deviationsByProduct.get(productId) ?? [],
+                findings,
+            });
+        }
+        // Conformance GATE (M-ADR 0191 §4.3 WS4): each archetype-expected tag must be
+        // declared covered OR deviated; an uncovered, undeviated tag is a
+        // deviation-visible finding. Satisfied tags are silent.
+        if (term.conformanceExpectations !== undefined && term.conformanceExpectations.length > 0) {
+            const declared = conformanceByProduct.get(productId) ?? new Set();
+            for (const tag of term.conformanceExpectations) {
+                if (declared.has(tag))
+                    continue; // covered or deviated — satisfied
+                findings.add("coverage", `conformance: archetype "${archetype}" expects the "${tag}" conformance for ${productId}, ` +
+                    `but it is neither declared covered (conformance.coverage) nor deviated (conformance.deviations) ` +
+                    `— assert coverage or declare why it does not apply (M-ADR 0191 §4.3)`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=expectations.js.map

package/dist/lib/catalogue/application-archetype/vocabulary.js

@@ -0,0 +1,177 @@
+/**
+ * Application-archetype vocabulary resolution (M-ADR 0191 §4.2).
+ *
+ * The `application_archetype` manifest trait is a *classification* over a
+ * tiered vocabulary. This module resolves a declared value against the union
+ * of:
+ *   - the **method tier** — `unclassified` only, built into sdd-cli (mirrors
+ *     how the ADR 0173/0176 method-tier scaffold archetypes are built in);
+ *   - the **reference-architecture / adopter bundle tiers** — seedless
+ *     vocabulary files (`application-archetypes.yaml`) shipped in consumed
+ *     bundles and extracted to the local bundle cache
+ *     (`.sdd/bundle-cache/<bundle>@<version>/`);
+ *   - an optional **adopter-local** extension file at
+ *     `.sdd/application-archetypes.yaml` in the SDD repo.
+ *
+ * This deliberately does NOT reuse the ADR 0176 scaffold registry resolver
+ * (`scaffold/registry.ts`): that resolver is seed-oriented and drops any
+ * entry with no `seeds[]`, whereas a classification archetype is seedless by
+ * design. It DOES share the same bundle-cache distribution substrate — this
+ * is a distinct data type over a shared substrate, not a second distribution
+ * mechanism (M-ADR 0191 §6).
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { BUNDLE_CACHE_REL, VOCAB_FILE } from "../../sync/bundle-cache.js";
+/** The sentinel that lives in the method tier — the back-compat default. */
+export const UNCLASSIFIED = "unclassified";
+export { VOCAB_FILE };
+/** Adopter-local extension file, relative to the SDD repo root. */
+export const ADOPTER_VOCAB_REL = join(".sdd", VOCAB_FILE);
+const VALID_PRESENCE = new Set([
+    "required",
+    "typical",
+    "optional",
+    "absent-by-shape",
+]);
+/** The built-in method tier (M-ADR 0191 §4.2 — `unclassified` only). */
+const METHOD_TIER = [
+    {
+        id: UNCLASSIFIED,
+        tier: "method",
+        shape: "the back-compat default; a product that has not declared a shape",
+        source: "method",
+    },
+];
+function parseVocabFile(raw, source) {
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return []; // malformed vocab — skip rather than break the build
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return [];
+    if (!Array.isArray(parsed.archetypes))
+        return [];
+    const tier = typeof parsed.tier === "string" ? parsed.tier : "unknown";
+    const out = [];
+    for (const a of parsed.archetypes) {
+        if (a === null || typeof a !== "object")
+            continue;
+        const rec = a;
+        const id = typeof rec.id === "string" ? rec.id : undefined;
+        if (!id)
+            continue;
+        const expectedBindings = parseExpectedBindings(rec.expected_bindings);
+        const conformanceExpectations = parseStringList(rec.conformance);
+        out.push({
+            id,
+            tier,
+            source,
+            ...(typeof rec.layer === "string" && { layer: rec.layer }),
+            ...(typeof rec.shape === "string" && { shape: rec.shape }),
+            ...(expectedBindings.length > 0 && { expectedBindings }),
+            ...(conformanceExpectations.length > 0 && { conformanceExpectations }),
+        });
+    }
+    return out;
+}
+/** Parse an archetype's `expected_bindings:` list, dropping malformed entries
+ *  (an unknown presence or a missing pattern is skipped, not fatal). */
+function parseExpectedBindings(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (e === null || typeof e !== "object")
+            continue;
+        const rec = e;
+        const pattern = typeof rec.pattern === "string" ? rec.pattern : undefined;
+        const presence = typeof rec.presence === "string" ? rec.presence : undefined;
+        if (!pattern || !presence || !VALID_PRESENCE.has(presence))
+            continue;
+        out.push({ pattern, presence: presence });
+    }
+    return out;
+}
+/** Parse a `conformance:` list of opaque string tags, dropping non-strings. */
+function parseStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((v) => typeof v === "string" && v.trim() !== "");
+}
+/** readdir(withFileTypes) that yields [] on any error, sorted by name. */
+async function readDirSafe(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** Find every application-archetypes.yaml within a cached bundle (root + nested). */
+async function findVocabFiles(dir, depth = 0) {
+    const found = [];
+    for (const e of await readDirSafe(dir)) {
+        if (e.isFile() && e.name === VOCAB_FILE) {
+            found.push(join(dir, e.name));
+        }
+        else if (e.isDirectory() && depth < 4) {
+            found.push(...(await findVocabFiles(join(dir, e.name), depth + 1)));
+        }
+    }
+    return found;
+}
+/**
+ * Discover the active vocabulary for an SDD repo: method tier ∪ every bundle
+ * vocab file in the bundle cache ∪ the adopter-local extension file.
+ */
+export async function discoverVocabulary(targetRepo) {
+    const terms = [...METHOD_TIER];
+    // Bundle tiers (RA + adopter bundles both land in the cache).
+    const cacheRoot = join(targetRepo, BUNDLE_CACHE_REL);
+    for (const e of await readDirSafe(cacheRoot)) {
+        if (!e.isDirectory())
+            continue;
+        const bundleCacheDir = join(cacheRoot, e.name);
+        const at = e.name.lastIndexOf("@");
+        const bundleName = at > 0 ? e.name.slice(0, at) : e.name;
+        for (const vocabPath of await findVocabFiles(bundleCacheDir)) {
+            let raw;
+            try {
+                raw = await readFile(vocabPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            terms.push(...parseVocabFile(raw, bundleName));
+        }
+    }
+    // Adopter-local extension.
+    try {
+        const raw = await readFile(join(targetRepo, ADOPTER_VOCAB_REL), "utf8");
+        terms.push(...parseVocabFile(raw, "adopter-local"));
+    }
+    catch {
+        // absent — fine
+    }
+    return { terms, ids: new Set(terms.map((t) => t.id)) };
+}
+/**
+ * Resolve a declared archetype value against a vocabulary. `undefined`
+ * defaults to `unclassified` (always resolved). A declared value that is not
+ * in the vocabulary is unresolved (the caller emits an error finding).
+ */
+export function resolveArchetype(declared, vocab) {
+    const value = declared ?? UNCLASSIFIED;
+    return {
+        value,
+        resolved: vocab.ids.has(value),
+        unclassified: value === UNCLASSIFIED,
+    };
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/lib/catalogue/archetype/maps/android.yaml

@@ -0,0 +1,66 @@
+# Default archetype map — android (ADR 0169 §4.2). Method-owned.
+#
+# Android View + Material toolkit. These names are industry-standard (Google/AndroidX/Material)
+# and identical across every Android app — never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: android` frontmatter.
+
+map_version: "1.0.0"
+platform: android
+
+# Material/AndroidX vendor prefixes, stripped before token lookup.
+strip_prefixes: [Material, Appcompat, AppCompat, Androidx]
+
+by_token:
+  ConstraintLayout: stack
+  FrameLayout: stack
+  LinearLayout: stack
+  RelativeLayout: stack
+  CoordinatorLayout: scaffold
+  NestedScrollView: scroll
+  ScrollView: scroll
+  RecyclerView: list
+  ListView: list
+  GridLayout: grid
+  GridView: grid
+  ViewPager: paged-panes
+  ViewPager2: paged-panes
+  TabLayout: tab-strip
+  BottomNavigationView: tab-bar
+  NavigationView: sidebar
+  NavigationRailView: sidebar
+  Toolbar: app-bar
+  AppBarLayout: app-bar
+  ActionBar: app-bar
+  CollapsingToolbarLayout: app-bar
+  Button: button
+  MaterialButton: button
+  ImageButton: button
+  FloatingActionButton: fab
+  ExtendedFloatingActionButton: fab
+  Chip: tab
+  ChipGroup: button-group
+  ToggleButton: segmented-control
+  TextView: text
+  EditText: text
+  MaterialTextView: text
+  ImageView: image
+  ImageFilterView: image
+  CardView: card
+  MaterialCardView: card
+  Snackbar: banner
+  BottomSheetDialog: sheet
+  AlertDialog: modal
+  DialogFragment: modal
+
+by_suffix_heuristic:
+  Layout: stack
+  View: panel
+  Button: button
+  Bar: app-bar
+  Dialog: modal
+  Card: card
+  Text: text
+  Image: image
+
+default: panel

package/dist/lib/catalogue/archetype/maps/swiftui.yaml

@@ -0,0 +1,58 @@
+# Default archetype map — swiftui (ADR 0169 §4.2). Method-owned.
+#
+# Apple SwiftUI toolkit. Industry-standard Apple names, identical across every SwiftUI app —
+# never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: swiftui` frontmatter.
+
+map_version: "1.0.0"
+platform: swiftui
+
+strip_prefixes: []
+
+by_token:
+  VStack: stack
+  HStack: row
+  ZStack: stack
+  LazyVStack: stack
+  LazyHStack: row
+  Grid: grid
+  LazyVGrid: grid
+  LazyHGrid: grid
+  ScrollView: scroll
+  List: list
+  Section: panel
+  ForEach: list-item       # repeated child marker; rendered as a list-item row
+  Form: list
+  NavigationView: nav-bar
+  NavigationStack: nav-bar
+  NavigationSplitView: sidebar
+  NavigationLink: button
+  TabView: tab-bar
+  Button: button
+  Menu: list
+  Toolbar: app-bar
+  ToolbarItem: button
+  Text: text
+  Label: text
+  TextField: text
+  SecureField: text
+  Image: image
+  AsyncImage: image
+  Spacer: text             # decorative; flagged by screen-styling-primitive-as-structure
+  Divider: text            # decorative; flagged by screen-styling-primitive-as-structure
+  GroupBox: card
+  Sheet: sheet
+  Alert: modal
+  Picker: segmented-control
+
+by_suffix_heuristic:
+  Stack: stack
+  View: panel
+  Button: button
+  Link: button
+  Field: text
+  Image: image
+  Text: text
+
+default: panel

package/dist/lib/catalogue/archetype/maps/uikit.yaml

@@ -0,0 +1,48 @@
+# Default archetype map — uikit (ADR 0169 §4.2). Method-owned.
+#
+# Apple UIKit toolkit. Industry-standard Apple names (UI- prefixed), identical across every
+# UIKit app — never an adopter's bespoke vocabulary.
+# Resolution order (ADR 0169 §4.3): adopter overlay override -> by_token -> by_suffix_heuristic -> default.
+# Selected per screen by `platform: uikit` frontmatter.
+
+map_version: "1.0.0"
+platform: uikit
+
+# The `UI` vendor prefix is stripped, so the `by_token` keys are unprefixed.
+strip_prefixes: [UI, NS]
+
+by_token:
+  View: panel
+  StackView: stack
+  ScrollView: scroll
+  TableView: list
+  TableViewCell: list-item
+  CollectionView: grid
+  CollectionViewCell: card
+  NavigationBar: nav-bar
+  NavigationController: nav-bar
+  TabBar: tab-bar
+  TabBarController: tab-bar
+  Toolbar: app-bar
+  BarButtonItem: button
+  Button: button
+  Label: text
+  TextField: text
+  TextView: text
+  ImageView: image
+  PageViewController: paged-panes
+  SegmentedControl: segmented-control
+  ActivityIndicatorView: text
+  AlertController: modal
+  Stack: stack
+
+by_suffix_heuristic:
+  View: panel
+  Controller: panel
+  Button: button
+  Bar: app-bar
+  Label: text
+  Field: text
+  Image: image
+
+default: panel