architecture-metamodel 1.4.0

Reusable architecture metamodel and validators

architecture-metamodel

This repository is the standalone Python metamodel package for architecture governance across projects.

It is a library repository, not a downstream architecture-instance repository. Downstream repos are expected to import this package to validate their own architecture-instance YAML artifacts.

Authority Model

The authoritative machine-readable metamodel now lives under src/architecture_metamodel/.

• The supported public contact surface is architecture_metamodel.api.
• The Python package is the canonical source of truth for element schemas, declarative policy, parsing, graph behavior, validation, and derived-artifact generation.
• Markdown, YAML, and PlantUML artifacts in metamodel/ are generated downstream artifacts, not hand-maintained structural sources.

Package Layout

src/architecture_metamodel/
  api.py
  enums.py
  issues.py
  aliases.py
  metadata/
  elements/
  rules/
  parsing/
  graph/
  validation/
  generation/
  tools/

Key organization rules:

• api.py The only supported public API surface.
• rules/ Declarative metamodel policy such as inverse relationships, target-type policy, required relationships, and recommended metadata.
• metadata/ Shared reusable metadata blocks.
• elements/ One module per metamodel element type.
• parsing/ Canonical element registry and payload parsing.
• graph/ Architecture graph container and YAML loading.
• validation/ Executable validation passes and orchestration.
• generation/ Deterministic derived-artifact generators for Markdown, PlantUML, and YAML reference outputs.
• tools/ CLI-oriented tooling built on the canonical package API.

Generated Artifacts

Generated reference artifacts live under metamodel/:

• metamodel/architecture_metamodel.md
• metamodel/architecture_metamodel_overview.puml
• metamodel/physical_interaction_view.puml
• metamodel/architecture_element_template.yaml
• metamodel/architecture_valid_example.yaml

Generated public API documentation lives under docs/:

• docs/public_api.md

These files are generated from the authoritative Python package and are clearly marked as generated.

Install

For local development:

python -m pip install -e ".[dev]"

The dev extra includes cross-version test dependencies used by workflow/verifier policy tests (for example tomli on Python <3.11 and jsonschema for promotion-schema checks).

For downstream-consumer usage:

python -m pip install architecture-metamodel

Quickstart

Validate a downstream architecture directory through the supported public API:

from architecture_metamodel.api import ArchitectureLoadError, validate_architecture_with_report

try:
    report = validate_architecture_with_report("architecture/instance_architecture")
except ArchitectureLoadError as exc:
    raise SystemExit(exc.to_dict())

if report.failed:
    raise SystemExit("\n".join(report.to_lines()))

print(report.overall_status)
print(report.to_json())

Validate a single YAML file:

from architecture_metamodel.api import validate_architecture_with_report

report = validate_architecture_with_report("architecture/instance_architecture/architecture.yaml")

Run the CLI validator:

architecture-validate path/to/architecture
architecture-validate path/to/architecture --format json
architecture-validate architecture/instance_architecture --mode traceability-only --codebase-root . --source-root src --test-root tests --traceability-report reports/traceability.json --format json

The CLI prints:

• overall PASS / FAIL
• total error and warning counts
• successful validation checks
• failed validation checks with issue detail

Stable exit codes:

• 0 for validation pass
• 1 for validation fail
• 2 for load/input failure
• 3 for unexpected adapter failure

Use the module entrypoint if preferred:

python -m architecture_metamodel.tools.validate_architecture path/to/architecture

A consumer-oriented example script is available at examples/consumer_validate.py.

The supported public API now provides a structured validation summary for downstream consumers:

• report.overall_status
• report.successful_checks
• report.failed_checks
• report.issues
• report.to_lines()
• report.to_dict()
• report.to_json()
• report.passed / report.failed

The current validation stack also enforces the split logical/physical interface model:

• INT_L represents the logical capability contract that FCN invokes and DOBJ traverses
• INT_P represents the concrete physical interaction path between SWA, SW, PSYS, and HW
• cross-LSYS invocation is allowed only when the target LSYS is classified as PLATFORM or CROSS_CUTTING
• INT_P must realize exactly one INT_L, and ownership plus traceability must be explicit rather than inferred
• legacy INT remains load-compatible but is deprecated and emits migration warnings
• direct function-to-function invocation must stay at equal architecture levels
• only Level1 functions may implement operational activities

The validation stack now also enforces governed DOBJ semantics:

• DOBJ remains a single element type; data_object_level distinguishes logical from physical governance
• ownership is explicit through owned_by and is separate from stored_by
• physical authoritative DOBJ requires exactly one explicit owner
• logical DOBJ traversal belongs on INT_L, while physical DOBJ traversal belongs on INT_P
• role, mutability, provenance, lineage, and physical-to-logical traceability are validated when modeled explicitly enough to do so deterministically
• FCN transforms_dobj is allowed for high-level intent, but decomposed FCN transformation of physical DOBJ must resolve to explicit SWF transforms_dobj detail
• GSWF remains reusable internal helper logic; it may be invoked by SWF and other GSWF elements, but it must not own interface/boundary behavior or transform DOBJ that traverses INT_P

The Task 027 traceability stack can validate downstream code/test linkage:

• source_traceability: source docstrings trace to canonical SW, SWF, or used GSWF IDs
• test_traceability: TC elements bind to repo-relative executable Python test files, and test files trace back to canonical TC IDs
• verification_closure: governed architecture behavior has TC coverage and interface perspective coverage
• gswf_governance: global software functions stay inside helper-logic boundaries

Load/input failures are raised as explicit exceptions instead of being returned as validation reports:

• ArchitecturePathNotFoundError
• ArchitecturePathTypeError
• EmptyArchitectureError
• NoArchitectureInputsError
• ArchitectureParseError

Generated API reference:

• see docs/public_api.md for the supported exports from architecture_metamodel.api
• see docs/consumer_usage.md for API, CLI, and GitHub Action usage guidance
• see docs/interface_migration_guide.md for the required INT to INT_L / INT_P migration path
• see docs/dobj_migration_guide.md for the required DOBJ governance migration path
• see docs/traceability_governance.md for source/test traceability usage, runtime report output, and CI guidance

Generate all derived artifacts:

architecture-generate

Check whether generated artifacts are stale:

architecture-generate --check

Run release-oriented smoke checks:

architecture-release-check

This command builds a local wheel, installs it into a temporary consumer virtual environment, then exercises:

• the supported public API from the installed package
• the installed architecture-validate console script
• the actual composite action definition in action.yml

The shakedown command now preflights the local wheel build prerequisite and bootstraps it when missing, so failures indicate real smoke-check issues rather than missing baseline packaging tooling.

Run categorized system tests and generate the markdown report artifact:

architecture-system-test run-all --json-dir test_reports/json --output-dir test_reports

Local Workflow

• Make structural changes in Python under src/architecture_metamodel/.
• Regenerate artifacts with architecture-generate.
• Run the test suite with python -m unittest discover -s tests.
• The categorized release-hardening test stack includes unit, integration, API contract, architectural boundary, and surface consistency coverage.
• Run the consumer-facing validation pass with python -m unittest tests.api_contract.test_consumer_validation_api tests.integration.test_consumer_validation_cli.
• The consumer validation suite is designed to run against both the source checkout and an installed package; the CLI tests resolve the installed architecture-validate console script when available.
• The consumer validation inventory now includes INT_L / INT_P migration warnings, LSYS classification governance, valid and invalid physical endpoint participation, and canonical zero-warning artifact behavior.
• Run release smoke checks with architecture-release-check.
• Optionally install pre-commit and enable the local hook:

python -m pre_commit install

The included pre-commit configuration runs the same repo-owned generation command used elsewhere.

CI Enforcement

GitHub Actions is split into four explicit workflows:

• development.yml Runs on branch pushes, skips version-tag release behavior, and keeps feedback lighter by running:
  • artifact currency
  • unit tests
  • API contract tests
  • architectural boundary tests
• pull-request.yml Runs on pull requests targeting main and acts as the full merge gate by running:
  • artifact currency
  • unit tests
  • integration tests
  • API contract tests
  • architectural boundary tests
  • surface consistency tests
  • markdown system-test report aggregation
  • architecture-release-check
• release.yml Runs on version tag pushes matching v*, derives and validates the paired stage_vX.Y.Z tag on the same commit, retrieves and verifies the stage promotion bundle (manifest/schema/approval/hashes/clean-room consumer evidence), and publishes only those preserved immutable artifacts to PyPI with no release-time rebuild.
• stage.yml Runs on stage tag pushes matching stage_v*, validates strict tag/version alignment (stage_vX.Y.Z and package X.Y.Z), builds immutable distributions once, publishes those exact artifacts to TestPyPI, installs the built artifact in a clean-room virtual environment, runs the consumer API/CLI suite there, pauses at stage-uat for manual approval, and then creates a promotion bundle containing distribution artifacts, hashes, promotion manifest, and validation plus consumer evidence outputs.

These workflows do not embed generation or validation logic beyond invoking the same repo-owned commands used locally.

Release Impact for 024

The logical/physical interface rollout should be treated as a MAJOR downstream release impact:

• canonical modeling changes from INT to INT_L plus INT_P
• validators now enforce LSYS classification and explicit physical traceability
• downstream repositories must migrate legacy INT usage rather than treating warnings as optional

Downstream Repository Consumption

Downstream architecture-instance repositories should treat this repo as an importable governing library.

Expected usage pattern:

• install or depend on architecture-metamodel
• author instance YAML in the downstream repo
• invoke the library validator through the API or CLI
• do not copy or fork the metamodel structure into the downstream repo as a separate source of truth

Example:

from architecture_metamodel.api import validate_architecture_with_report

report = validate_architecture_with_report("architecture/instance_architecture")
if report.failed:
    raise SystemExit("\n".join(report.to_lines()))

Scope of This Repository

This repository now owns:

• the authoritative Python metamodel
• declarative metamodel policy
• validation behavior
• deterministic generation of reference artifacts for this repo

This repository does not own:

• downstream architecture-instance repositories
• downstream repo-specific CI policy
• downstream repo-local copies of the metamodel structure

Future Direction

Structural changes should originate in the Python models and propagate outward through generation. Future enhancements should continue to treat src/architecture_metamodel/ as the authority and the files in metamodel/ as deterministic derived outputs.