@sdd-method/sdd-cli 0.10.0 → 0.12.0

package/dist/lib/catalogue/canonical-schema.yaml

@@ -0,0 +1,624 @@
+# Catalogue Schema (Canonical)
+#
+# Authoritative schema for all catalogues defined by the SDD method's shared
+# catalogue metamodel. Consumed by:
+#   - Catalogue builders (forward + reverse) for column ordering and FK
+#     validation.
+#   - The catalogue-integrity gate skill (FK PASS, coverage, drift).
+#   - Downstream tools (DuckDB, pandas) for type information.
+#   - sdd-mcp `sdd://catalogue/schema` resource (Phase 8).
+#
+# Distribution: ships in every method baseline (platform-baseline,
+# app-baseline, integration-baseline) via the seed-file lists at
+# docs/method/foundations/*-method-seed-files.txt. Consumers receive it
+# through `sdd-cli sync`. Drift detection comes for free from the
+# refuse-or-overwrite model in ADR 0114 — the schema is in
+# MANAGED_PATHS.txt; consumer-side modification fails the next sync.
+#
+# Schema versioning: every structural change increments schema_version.
+# Per resolution of adopt-canonical-catalogue-builder.md §7.5, this schema
+# versions independently of sdd-manifest-schema.yaml and
+# aggregation-manifest-schema.yaml. The CLI declares per-schema compat
+# ranges in `src/lib/catalogue/schema-compat.ts` and fails fast on
+# out-of-range versions. Per ADR 0133 the canonical builder + aggregator
+# update in lockstep with this schema; with the canonical builder shipped
+# from sdd-method, "lockstep" collapses to a single CLI version bump.
+#
+# Bump rules:
+#   - Patch (1.X.0 → 1.X.1): typo / description / non-structural fix.
+#   - Minor (1.X.0 → 1.(X+1).0): additive change (new optional column,
+#     new entity catalogue, new enum value, new nullable FK). Backward
+#     compatible — older readers ignore new fields/catalogues.
+#   - Major (1.X.0 → 2.0.0): breaking change (column rename, retype,
+#     required-field addition, enum-value removal, edge-FK retype). CLI
+#     MUST release in lockstep with `supports` updated; migration tooling
+#     required.
+#
+# Federation: per ADR 0134 catalogues are built per SDD and aggregated at
+# the ecosystem root. Every node catalogue carries a `source_sdd_id`
+# column populated by the aggregator. Foreign keys may declare
+# `external: true` — these are skipped by the per-SDD builder (logged as
+# `[finding] external`) and validated by the aggregator after merge.
+# Default for unspecified `external` is `false` (internal FK).
+#
+# Conceptual model: see docs/method/methods/catalogue-metamodel.md.
+# Builder contract: see docs/method/methods/catalogue-builder-specification.md.
+# Category taxonomy: see docs/method/methods/product-category-taxonomy.md.
+
+schema_version: "2.1.0"
+schema_owner: "sdd-method"
+schema_status: "canonical"
+
+# ─── Canonical enums ────────────────────────────────────────────────────────
+#
+# Enums constrain the values certain string columns may take. The canonical
+# builder (sdd-cli catalogue build, per ADR 0134 §4.6) reads these from the
+# schema rather than hardcoding them, so adopters can update the canonical
+# enum here without forking builder code.
+
+enums:
+
+  c4_system_kind:
+    description: >
+      Architectural kind of a C4 system. Derived 1:1 from the originating
+      SDD manifest's category — every architectural product (the only
+      ones that get a c4_systems row) maps to exactly one of these three
+      kinds. Non-architectural categories (platform-subsystem,
+      integration-umbrella, support-repo) emit no c4_systems row.
+      Mapping table:
+        platform-root        → platform
+        application-product  → application
+        integration-provider → integration
+    values:
+      - { value: platform, description: "The ecosystem's platform-root system. Exactly one per ecosystem after federation aggregation." }
+      - { value: application, description: "An application-product system, consumes platform services and contracts." }
+      - { value: integration, description: "An integration-provider system, bridges an external provider into the platform." }
+
+  service_type:
+    description: >
+      Type of repository, declared in `orchestration/repo-config/*.yaml` as
+      `service_type` and surfaced in `repositories.service_type` and
+      `services.component_type`. The canonical builder uses this to decide
+      which repos are runtime services (api_service, worker, gateway,
+      frontend, mobile) and which are non-runtime (library, infrastructure,
+      documentation). Whether a repo is a vertical-domain application is
+      conveyed by its SDD manifest's `profile: application-product`, not by
+      a service_type tag — this enum is strictly about runtime artefact
+      shape (per resolution of adopt-canonical-catalogue-builder.md §7.1).
+    values:
+      - { value: api_service, runtime: true,  emits_service_row: true,  description: "REST/GraphQL/RPC service exposing an API." }
+      - { value: worker, runtime: true,  emits_service_row: true,  description: "Background event/queue processor." }
+      - { value: gateway, runtime: true,  emits_service_row: true,  description: "Edge or API gateway (Zuplo, Apigee, etc.)." }
+      - { value: frontend, runtime: true,  emits_service_row: true,  description: "Web UI deployable (Vue, React, Svelte, etc.). Includes vertical-domain application frontends — the SDD profile distinguishes platform-frontends from app-frontends." }
+      - { value: mobile, runtime: true,  emits_service_row: true,  description: "Mobile app deployable (iOS, Android)." }
+      - { value: library, runtime: false, emits_service_row: false, description: "Shared package shipped to consumers (npm, PyPI, Maven, etc.)." }
+      - { value: infrastructure, runtime: false, emits_service_row: false, description: "IaC, CI/CD, build tooling — not a runtime deployable." }
+      - { value: documentation, runtime: false, emits_service_row: false, description: "Docs-only repo." }
+
+catalogues:
+
+  domains:
+    primary_key: id
+    columns:
+      - { name: id, type: string, nullable: false, description: "Slug, e.g. identity, asset." }
+      - { name: name, type: string, nullable: false, description: "Display name." }
+      - { name: description, type: string, nullable: false }
+      - { name: method_profile, type: string, nullable: false, description: "platform-profile | application-product | integration-product." }
+      - { name: reference_architecture_equivalent, type: string, nullable: true }
+      - { name: status, type: string, nullable: false, description: "active | deferred | absent." }
+      - { name: repo_count, type: int, nullable: false }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator at merge time per ADR 0134; left empty by per-SDD builders." }
+
+  products: &products_def
+    primary_key: id
+    foreign_keys:
+      - { column: domain_id, references: domains.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "product_id slug." }
+      - { name: name, type: string, nullable: false }
+      - { name: domain_id, type: string, nullable: true, description: "Owning capability domain. Populated for platform-profile products (platform-root, platform-subsystem). App and integration products do not have a primary domain — see ADR 0136." }
+      - { name: profile, type: string, nullable: false, description: "platform-profile | application-product | integration-product | support-repo." }
+      - { name: category, type: string, nullable: true, description: "Architectural classification per docs/method/methods/product-category-taxonomy.md. Values: platform-root | platform-subsystem | application-product | integration-provider | integration-umbrella | support-repo. Determines whether the Product gets a c4_systems row." }
+      - { name: doc_path, type: string, nullable: false, description: "Path to _product/ directory, relative to docs/." }
+      - { name: status, type: string, nullable: true, description: "scaffolded | populated | reviewed | ..." }
+      - { name: synthesis_quality, type: int, nullable: true, description: "Score 0-10 from assessment block (reverse method only)." }
+      - { name: synthesis_band, type: string, nullable: true, description: "developing | working | strong." }
+      - { name: last_assessed, type: date, nullable: true }
+      - { name: highest_snapshot_impact, type: string, nullable: true }
+      - { name: repo_count, type: int, nullable: false, description: "Number of repos mapped to this product." }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  applications:
+    <<: *products_def
+    description: "Filtered view of products where profile = application-product."
+
+  integrations:
+    primary_key: id
+    description: "Granular provider adapters. Each row is one provider folder under an umbrella integration-product."
+    foreign_keys:
+      - { column: domain_id, references: domains.id, nullable: true }
+      - { column: parent_product_id, references: products.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Provider slug." }
+      - { name: name, type: string, nullable: false }
+      - { name: domain_id, type: string, nullable: true, description: "Provider adapters are federation nodes, not capability-domain members. Left empty per ADR 0136." }
+      - { name: parent_product_id, type: string, nullable: true, description: "Umbrella integration-product." }
+      - { name: category, type: string, nullable: false, description: "oem | device | fleet | camera | legacy | data-sharing | gateway-framework (extensible per ecosystem)." }
+      - { name: doc_path, type: string, nullable: false }
+      - { name: repo_count, type: int, nullable: false }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  adrs:
+    primary_key: id
+    foreign_keys:
+      - { column: domain_id, references: domains.id, nullable: false }
+      - { column: superseded_by_id, references: adrs.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "ADR id, e.g. ADR-0001 or {domain}-D001." }
+      - { name: title, type: string, nullable: false }
+      - { name: status, type: string, nullable: true, description: "Accepted | Proposed | Superseded | Deprecated | Deferred (forward) plus reverse-inferred | reverse-adapted (reverse)." }
+      - { name: domain_id, type: string, nullable: false, description: "'platform' for cross-cutting ADRs; domain slug otherwise." }
+      - { name: decision_date, type: date, nullable: true }
+      - { name: doc_path, type: string, nullable: false }
+      - { name: superseded_by_id, type: string, nullable: true }
+      - { name: inference_confidence, type: string, nullable: true, description: "high | medium | low (reverse-inferred ADRs only)." }
+      - { name: supersedes_raw, type: string, nullable: true, description: "Raw text from Supersedes bullet for later parsing." }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  glossary_items:
+    primary_key: id
+    foreign_keys:
+      - { column: owning_domain_id, references: domains.id, nullable: true }
+      - { column: canonical_term_id, references: glossary_items.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Slug: {domain}-{term-slug} for uniqueness." }
+      - { name: term, type: string, nullable: false }
+      - { name: definition, type: string, nullable: false }
+      - { name: owning_domain_id, type: string, nullable: true, description: "Null for platform-level terms." }
+      - { name: canonical_term_id, type: string, nullable: true, description: "Set when this term is an alias for another." }
+      - { name: aliases, type: string, nullable: true, description: "';'-separated list." }
+      - { name: evidence, type: string, nullable: true }
+      - { name: notes, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  glossary_xref:
+    primary_key: id
+    description: "Edge: cross-domain glossary relationships from glossary-alignment-manifest.yaml."
+    foreign_keys:
+      - { column: source_id, references: glossary_items.id, nullable: false }
+      - { column: target_id, references: glossary_items.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Composite: {source_id}__{relation}__{target_id}." }
+      - { name: source_id, type: string, nullable: false }
+      - { name: target_id, type: string, nullable: false }
+      - { name: relation, type: string, nullable: false, description: "alias-of | conflicts-with." }
+
+  services:
+    primary_key: id
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+      - { column: domain_id, references: domains.id, nullable: true }
+      - { column: primary_repo_id, references: repositories.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Service id, derived from artifact_id where artifact_type=service." }
+      - { name: name, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false }
+      - { name: domain_id, type: string, nullable: true, description: "Owning capability domain. Populated when the repo-config declared domain resolves to a docs/domains/<slug>/ in the local SDD; left empty otherwise per ADR 0136." }
+      - { name: primary_repo_id, type: string, nullable: true, description: "Main contributing repo. Nullable when service spans repos." }
+      - { name: runtime_type, type: string, nullable: true, description: "serverless-framework | jvm-service | lambda | k8s | ..." }
+      - { name: language, type: string, nullable: true }
+      - { name: component_type, type: string, nullable: true, description: "bff | api | consumer | ui | collector | processor | ..." }
+      - { name: status, type: string, nullable: true, description: "production-wired | non-production | library." }
+      - { name: confidence, type: string, nullable: true, description: "high | medium | low (reverse-method classification)." }
+      - { name: description, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+    column_enums:
+      component_type: enums.service_type  # canonical builder validates against the service_type enum above
+
+  capabilities:
+    primary_key: id
+    foreign_keys:
+      - { column: domain_id, references: domains.id, nullable: false }
+      - { column: parent_capability_id, references: capabilities.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Capability slug." }
+      - { name: name, type: string, nullable: false }
+      - { name: domain_id, type: string, nullable: false }
+      - { name: tree_category, type: string, nullable: true, description: "Top-level grouping when capability comes from a capability tree (reverse)." }
+      - { name: parent_capability_id, type: string, nullable: true }
+      - { name: description, type: string, nullable: true }
+      - { name: status, type: string, nullable: false, description: "active | planned | deprecated. Default 'active'." }
+      - { name: spec_path, type: string, nullable: true, description: "Path to capability spec file when one exists." }
+      - { name: source, type: string, nullable: false, description: "capability-tree | product-map | capability-spec." }
+      - { name: runway_classification, type: string, nullable: true, description: "Business | Enabler-Runway | Hybrid (forward declares; reverse nullable until backfilled)." }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  feature_groups:
+    primary_key: id
+    description: >
+      Hierarchical grouping for features. First-class entity per resolution
+      of adopt-canonical-catalogue-builder.md §7.2 — replaces the previous
+      reverse-only synthetic `feature-tree-group` rows in features.csv.
+      Both forward and reverse can use feature_groups: forward
+      application-product SDDs whose `feature-tree.md` has H2/H3 structure,
+      reverse SDDs whose extracted feature trees are inherently
+      hierarchical, and any SDD that promotes groups to first-class with
+      authored metadata. Groups can nest via `parent_group_id`.
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: true }
+      - { column: capability_id, references: capabilities.id, nullable: true }
+      - { column: parent_group_id, references: feature_groups.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{product_id|capability_id}-group-{slug}[-{nested-slug}]." }
+      - { name: name, type: string, nullable: false, description: "Display name from H2/H3 heading or authored." }
+      - { name: product_id, type: string, nullable: true, description: "Owning product (when group is product-scoped)." }
+      - { name: capability_id, type: string, nullable: true, description: "Owning capability (when group is capability-scoped)." }
+      - { name: parent_group_id, type: string, nullable: true, description: "Self-reference for nested groups (H3 within H2)." }
+      - { name: description, type: string, nullable: true, description: "Authored description (when group has explicit metadata) or null when derived from heading only." }
+      - { name: source, type: string, nullable: false, description: "feature-tree-h2 | feature-tree-h3 | feature-spec-explicit (when an authored feature spec declares group membership) | capability-spec-explicit." }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  features:
+    primary_key: id
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: true }
+      - { column: capability_id, references: capabilities.id, nullable: true }
+      - { column: parent_group_id, references: feature_groups.id, nullable: true }
+      - { column: parent_feature_id, references: features.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{product_id|capability_id}-{feature-slug}." }
+      - { name: name, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: true, description: "Owning product (null for capability-spec-sourced features)." }
+      - { name: capability_id, type: string, nullable: true }
+      - { name: parent_group_id, type: string, nullable: true, description: "Owning feature_group (typical when feature comes from a hierarchical feature-tree.md). Use this OR parent_feature_id, not both." }
+      - { name: parent_feature_id, type: string, nullable: true, description: "Self-reference for explicit feature nesting (rare — most hierarchies are group-based via parent_group_id)." }
+      - { name: description, type: string, nullable: true }
+      - { name: maturity, type: string, nullable: true, description: "Standard: working | provisional | unknown | absent. Ecosystem-specific values may be added with parser awareness." }
+      - { name: status, type: string, nullable: false, description: "Default 'active'." }
+      - { name: source, type: string, nullable: false, description: "feature-tree | feature-set | capability-spec | feature-spec (forward-only). NOTE: feature-tree-group source removed in 1.3.0 — groups are now first-class in feature_groups.csv." }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  personas:
+    primary_key: id
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{product_id}-{persona-slug}." }
+      - { name: name, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: true }
+      - { name: description, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  user_journeys:
+    primary_key: id
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{product_id}-{journey-slug}." }
+      - { name: name, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false }
+      - { name: primary_persona, type: string, nullable: true, description: "Free-text. Supports 'X → Y (handoff)'." }
+      - { name: supporting_personas, type: string, nullable: true }
+      - { name: trigger, type: string, nullable: true }
+      - { name: goal, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  contracts:
+    primary_key: id
+    foreign_keys:
+      - { column: service_id, references: services.id, nullable: true }
+      - { column: source_repo_id, references: repositories.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: name, type: string, nullable: false, description: "Display name from info.title or artifact_id." }
+      - { name: service_id, type: string, nullable: true, description: "Exposing service; resolved via primary_repo_id ↔ OpenAPI x-source-repo." }
+      - { name: source_repo_id, type: string, nullable: true, description: "Repo owning the contract source. Distinct from exposing service's repo per ADR 0110 (sibling-repo pattern)." }
+      - { name: kind, type: string, nullable: false, description: "rest | graphql | rpc | event. rpc covers Proto/gRPC; event covers Avro schemas." }
+      - { name: version, type: string, nullable: true }
+      - { name: status, type: string, nullable: false, description: "active | deprecated. Default 'active'." }
+      - { name: spec_path, type: string, nullable: true }
+      - { name: visibility, type: string, nullable: true, description: "public | private | internal." }
+      - { name: description, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  events:
+    primary_key: id
+    description: "Asynchronous messages. Cross-domain events (e.g. shared envelopes) leave domain_id empty."
+    foreign_keys:
+      - { column: publisher_service_id, references: services.id, nullable: true }
+      - { column: domain_id, references: domains.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: name, type: string, nullable: false }
+      - { name: publisher_service_id, type: string, nullable: true }
+      - { name: domain_id, type: string, nullable: true }
+      - { name: transport, type: string, nullable: true, description: "kafka | sns | sqs | kinesis | eventbridge | mongodb-change-stream." }
+      - { name: schema_path, type: string, nullable: true }
+      - { name: version, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  c4_systems:
+    primary_key: id
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "Typically {product_id}-system." }
+      - { name: name, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false, description: "Owning product. Architectural products only (per category taxonomy)." }
+      - { name: kind, type: string, nullable: false, description: "platform | application | integration. Derived 1:1 from manifest.category — see enums.c4_system_kind." }
+      - { name: diagram_path, type: string, nullable: true, description: "Path to L1 mermaid/markdown. Nullable — row exists for any architectural Product even if no L1 diagram has been authored yet (visible coverage gap)." }
+      - { name: description, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+    column_enums:
+      kind: enums.c4_system_kind
+
+  c4_containers:
+    primary_key: id
+    description: >
+      C4 L2. Each container belongs to exactly one C4 system. `domain_id`
+      is a denormalised organisational tag, not a C4-structural attribute
+      — multi-domain ecosystems use it for filtering/reporting.
+      `service_id` is the optional "may represent" link to a runtime
+      service when the container is a deployable application.
+    foreign_keys:
+      - { column: system_id, references: c4_systems.id, nullable: false }
+      - { column: domain_id, references: domains.id, nullable: true }
+      - { column: service_id, references: services.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{system_id}-{container-slug}." }
+      - { name: name, type: string, nullable: false }
+      - { name: system_id, type: string, nullable: false, description: "Owning C4 system (every container is in exactly one system)." }
+      - { name: domain_id, type: string, nullable: true, description: "Optional organisational domain tag (denormalised; not C4-structural)." }
+      - { name: service_id, type: string, nullable: true, description: "Matched by container name ↔ service name/repo where possible." }
+      - { name: type, type: string, nullable: true, description: "Application | Data Store | Infrastructure | External System." }
+      - { name: technology, type: string, nullable: true }
+      - { name: description, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  c4_components:
+    primary_key: id
+    description: >
+      C4 L3. Each component belongs to exactly one C4 container.
+      `service_id` is denormalised from `c4_containers.service_id` for
+      query convenience — populated when the parent container represents
+      a runtime service.
+    foreign_keys:
+      - { column: container_id, references: c4_containers.id, nullable: false }
+      - { column: service_id, references: services.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{container_id}-{component-slug}." }
+      - { name: name, type: string, nullable: false }
+      - { name: container_id, type: string, nullable: false, description: "Owning C4 container." }
+      - { name: service_id, type: string, nullable: true, description: "Denormalised: the service the parent container represents, when applicable." }
+      - { name: path, type: string, nullable: true }
+      - { name: responsibility, type: string, nullable: true }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+
+  repositories:
+    primary_key: id
+    foreign_keys:
+      - { column: domain_id, references: domains.id, nullable: true }
+      - { column: product_id, references: products.id, nullable: true }
+    columns:
+      - { name: id, type: string, nullable: false, description: "canonical_repo_key." }
+      - { name: name, type: string, nullable: false }
+      - { name: domain_id, type: string, nullable: true, description: "Owning capability domain. Populated when the repo-config declared domain resolves to a docs/domains/<slug>/ in the local SDD; left empty otherwise per ADR 0136." }
+      - { name: product_id, type: string, nullable: true }
+      - { name: profile, type: string, nullable: false }
+      - { name: group, type: string, nullable: true }
+      - { name: category, type: string, nullable: true }
+      - { name: tier, type: string, nullable: true, description: "S1..S4 for support repos, else null." }
+      - { name: component_type, type: string, nullable: true }
+      - { name: files, type: int, nullable: true }
+      - { name: code, type: int, nullable: true }
+      - { name: comment, type: int, nullable: true }
+      - { name: blank, type: int, nullable: true }
+      - { name: total_lines, type: int, nullable: true }
+      - { name: languages, type: string, nullable: true, description: "';'-separated." }
+      - { name: doc_path, type: string, nullable: false }
+      - { name: source_sdd_id, type: string, nullable: true, description: "Originating SDD slug. Populated by the aggregator per ADR 0134." }
+    column_enums:
+      service_type: enums.service_type  # canonical builder validates against the service_type enum above
+
+  # ---- Edge catalogues ----
+  # Edge catalogues do not carry source_sdd_id — provenance is recoverable
+  # from either endpoint's row per ADR 0134.
+
+  repo_capability:
+    primary_key: id
+    description: "Edge: repo contributes to capability. From contributes_to.artifact_type=capability."
+    foreign_keys:
+      - { column: repo_id, references: repositories.id, nullable: false }
+      - { column: capability_id, references: capabilities.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: repo_id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+
+  repo_contract:
+    primary_key: id
+    description: "Edge: repo implements contract. From contributes_to.artifact_type=contract-surface."
+    foreign_keys:
+      - { column: repo_id, references: repositories.id, nullable: false }
+      - { column: contract_id, references: contracts.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: repo_id, type: string, nullable: false }
+      - { name: contract_id, type: string, nullable: false }
+
+  product_capability:
+    primary_key: id
+    description: "Edge: product depends on / consumes capability. Forward sources from app-platform-dependencies.yaml. capability_id is external because the consuming product (an application-product SDD) references a capability owned by the platform SDD."
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+      - { column: capability_id, references: capabilities.id, nullable: false, external: true }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "consumes." }
+      - { name: notes, type: string, nullable: true }
+
+  product_service:
+    primary_key: id
+    description: "Edge: product depends on / consumes service. Forward sources from app-platform-dependencies.yaml. service_id is external because the consuming product (an application-product SDD) references a service owned by the platform SDD."
+    foreign_keys:
+      - { column: product_id, references: products.id, nullable: false }
+      - { column: service_id, references: services.id, nullable: false, external: true }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: product_id, type: string, nullable: false }
+      - { name: service_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "consumes." }
+      - { name: required_stability, type: string, nullable: true, description: "provisional | locked." }
+
+  service_contract:
+    primary_key: id
+    description: "Edge: service exposes or consumes contract."
+    foreign_keys:
+      - { column: service_id, references: services.id, nullable: false }
+      - { column: contract_id, references: contracts.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{service_id}__{contract_id}__{role}." }
+      - { name: service_id, type: string, nullable: false }
+      - { name: contract_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "exposes | consumes." }
+
+  service_event:
+    primary_key: id
+    description: "Edge: service publishes or consumes event."
+    foreign_keys:
+      - { column: service_id, references: services.id, nullable: false }
+      - { column: event_id, references: events.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false, description: "{service_id}__{event_id}__{role}." }
+      - { name: service_id, type: string, nullable: false }
+      - { name: event_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "publishes | consumes." }
+
+  capability_feature:
+    primary_key: id
+    description: "Edge: capability decomposes into features. Forward: traceability.runway.enables. Reverse: parsed from spec Feature Grounding."
+    foreign_keys:
+      - { column: capability_id, references: capabilities.id, nullable: false }
+      - { column: feature_id, references: features.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: feature_id, type: string, nullable: false }
+
+  capability_service:
+    primary_key: id
+    description: "Edge: capability is realised by services. Parsed from Related Services table in capability spec."
+    foreign_keys:
+      - { column: capability_id, references: capabilities.id, nullable: false }
+      - { column: service_id, references: services.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: service_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: true }
+
+  capability_event:
+    primary_key: id
+    description: "Edge: capability publishes or consumes event. Parsed from `## Related Events` table in capability spec."
+    foreign_keys:
+      - { column: capability_id, references: capabilities.id, nullable: false }
+      - { column: event_id, references: events.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: event_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "publishes | consumes." }
+
+  capability_contract:
+    primary_key: id
+    description: "Edge: capability exposes or depends on contract. Forward: declared in traceability.contracts. Reverse: derived via service_contract ⋈ capability_service."
+    foreign_keys:
+      - { column: capability_id, references: capabilities.id, nullable: false }
+      - { column: contract_id, references: contracts.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: contract_id, type: string, nullable: false }
+      - { name: source, type: string, nullable: false, description: "declared (forward) | derived (reverse)." }
+
+  journey_feature:
+    primary_key: id
+    description: "Edge: journey touches features. Parsed from Related features bullet."
+    foreign_keys:
+      - { column: journey_id, references: user_journeys.id, nullable: false }
+      - { column: feature_id, references: features.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: journey_id, type: string, nullable: false }
+      - { name: feature_id, type: string, nullable: false }
+
+  persona_feature:
+    primary_key: id
+    description: "Edge: persona uses features. Parsed from Related features bullet."
+    foreign_keys:
+      - { column: persona_id, references: personas.id, nullable: false }
+      - { column: feature_id, references: features.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: persona_id, type: string, nullable: false }
+      - { name: feature_id, type: string, nullable: false }
+
+  feature_service:
+    primary_key: id
+    description: "Edge: feature is implemented by service. Parsed from Feature Services table in feature-tree.md."
+    foreign_keys:
+      - { column: feature_id, references: features.id, nullable: false }
+      - { column: service_id, references: services.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: feature_id, type: string, nullable: false }
+      - { name: service_id, type: string, nullable: false }
+
+  feature_repo:
+    primary_key: id
+    description: "Edge: feature is implemented in repo. From contributes_to.artifact_type=feature-set."
+    foreign_keys:
+      - { column: feature_id, references: features.id, nullable: false }
+      - { column: repo_id, references: repositories.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: feature_id, type: string, nullable: false }
+      - { name: repo_id, type: string, nullable: false }
+
+  persona_journey:
+    primary_key: id
+    description: "Edge: persona participates in journey. Roles: primary | handoff | supporting."
+    foreign_keys:
+      - { column: persona_id, references: personas.id, nullable: false }
+      - { column: journey_id, references: user_journeys.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: persona_id, type: string, nullable: false }
+      - { name: journey_id, type: string, nullable: false }
+      - { name: role, type: string, nullable: false, description: "primary | handoff | supporting." }
+
+  capability_adr:
+    primary_key: id
+    description: "Edge: ADR informs capability. Forward: declared in capability spec Architecture Decisions. Reverse: same plus heuristic match supplements with confidence."
+    foreign_keys:
+      - { column: capability_id, references: capabilities.id, nullable: false }
+      - { column: adr_id, references: adrs.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: capability_id, type: string, nullable: false }
+      - { name: adr_id, type: string, nullable: false }
+      - { name: confidence, type: string, nullable: false, description: "spec | high | medium." }
+
+  adr_supersedes:
+    primary_key: id
+    description: "Edge: superseding ADR → superseded ADR. Parsed from Supersedes bullets where prose references a known ADR id."
+    foreign_keys:
+      - { column: superseding_adr_id, references: adrs.id, nullable: false }
+      - { column: superseded_adr_id, references: adrs.id, nullable: false }
+    columns:
+      - { name: id, type: string, nullable: false }
+      - { name: superseding_adr_id, type: string, nullable: false }
+      - { name: superseded_adr_id, type: string, nullable: false }

package/dist/lib/catalogue/cli-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * sdd-cli version constant, used in error messages from the catalogue
+ * builder + aggregator + validate subcommands.
+ *
+ * Read from package.json at build time would be cleaner, but Node's ESM
+ * loader doesn't import JSON without flags. Hardcoding here is the
+ * simpler short-term path; keep in sync with package.json's `version`.
+ */
+export declare const CLI_VERSION = "0.11.0";
+//# sourceMappingURL=cli-version.d.ts.map

package/dist/lib/catalogue/cli-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-version.d.ts","sourceRoot":"","sources":["../../../src/lib/catalogue/cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,WAAW,WAAW,CAAC"}

package/dist/lib/catalogue/cli-version.js

@@ -0,0 +1,10 @@
+/**
+ * sdd-cli version constant, used in error messages from the catalogue
+ * builder + aggregator + validate subcommands.
+ *
+ * Read from package.json at build time would be cleaner, but Node's ESM
+ * loader doesn't import JSON without flags. Hardcoding here is the
+ * simpler short-term path; keep in sync with package.json's `version`.
+ */
+export const CLI_VERSION = "0.11.0";
+//# sourceMappingURL=cli-version.js.map

package/dist/lib/catalogue/cli-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-version.js","sourceRoot":"","sources":["../../../src/lib/catalogue/cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC"}