Metadata-Version: 2.4
Name: architecture-metamodel
Version: 1.4.0
Summary: Reusable architecture metamodel and validators
Author: architecture-metamodel maintainers
Maintainer: architecture-metamodel maintainers
Project-URL: Homepage, https://github.com/ndbach/architecture-metamodel
Project-URL: Repository, https://github.com/ndbach/architecture-metamodel
Project-URL: Issues, https://github.com/ndbach/architecture-metamodel/issues
Keywords: architecture,metamodel,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2
Requires-Dist: PyYAML<7,>=6
Provides-Extra: dev
Requires-Dist: jsonschema<5,>=4; extra == "dev"
Requires-Dist: pre-commit<5,>=3; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: tomli<3,>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: wheel; extra == "dev"

# 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

```text
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:

```bash
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:

```bash
python -m pip install architecture-metamodel
```

## Quickstart

Validate a downstream architecture directory through the supported public API:

```python
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:

```python
from architecture_metamodel.api import validate_architecture_with_report

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

Run the CLI validator:

```bash
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:

```bash
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:

```bash
architecture-generate
```

Check whether generated artifacts are stale:

```bash
architecture-generate --check
```

Run release-oriented smoke checks:

```bash
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:

```bash
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:

```bash
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:

```python
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.
