v0.3.0

Project status: Experimental / pre-1.0. The Canonical Model, REST API surface, Graph Schema,
Adapter SPI, and configuration format are not yet guaranteed stable — expect breaking changes on a
future minor version bump. See
ROADMAP.md.

License: Apache License, Version 2.0.

What v0.3 proves

AIP v0.3.0 proves that the architecture intelligence validated reproducibly in v0.2 survives two
independently authored real systems — an external reference architecture and mature real-world
OSS software — and hardens the Canonical Model only where real evidence justifies it.

v0.2 proved AIP's architecture intelligence behaves correctly against known, hand-authored
ground truth. v0.3 does not add another architecture-intelligence dimension — it tests the same
model against systems AIP's own authors did not build: Quarkus Super Heroes (a controlled,
externally authored microservice reference architecture) and Apache Airflow (a mature real-world
system with API server, scheduler, workers, and asynchronous task execution). The result is
deliberately bounded, not a claim of complete conformance: supported claims are materially
correct, unsupported mechanisms remain explicit, unresolved identity is never guessed, and
non-observation is never treated as absence.

Candidate identity

Candidate SHA:            eeff933da3a8f1e5fc6749cb9a77bbf2e5123fd1
Dependency-lock SHA-256:  484361e9e5fc5f498809549cc413e4545832cd91e8720e8bb16406dcdfca0644
Promoted from RC:         v0.3.0-rc.2 (v0.3.0-rc.1 preceded it but was superseded by a required
                          pyproject.toml/uv.lock version-consistency fix before GO)

Quarkus Super Heroes result

Two different counts, per the frozen dossier's own convention — the comparator only scores what
expected.yaml declares, and expected.yaml declares no insufficient_evidence: entries:

                          Comparator-only   Overall dossier
Correct:                  38                38
Unsupported:                2                 2
Unresolved identity:        0                 0
Insufficient evidence:      0                 1  (qsh-kafka-operation-type-gap — found by a
                                                    separate diagnostic inspection, not the
                                                    comparator itself)
Incorrect supported:        0                 0

The comparator result reproduced across two independent runs against the qualifying candidate,
with byte-identical captures and comparator reports both times. The separate diagnostic finding
(qsh-kafka-operation-type-gap) was not emitted by either comparator run — it was discovered once,
by a distinct raw-telemetry inspection, and carried forward as part of the accepted overall dossier
disposition.

Apache Airflow result

Correct:                 9
Unsupported:              3
Unresolved identity:      2
Insufficient evidence:    1
Incorrect supported:      0

Two independent runs against the qualifying candidate, byte-identical.

Cross-system hardening outcome

Every finding from both dossiers (10 total) was dispositioned NO_CHANGE, DOCUMENT_UNSUPPORTED,
or DEFER — zero required a production fix. The canonical-redesign gate answered NO: no
fundamental Canonical Model redesign is required before v0.4. Full ledger, decision records, and
evidence:
docs/real-world-validation/cross-system/report.md.

Deterministic evaluation result

AIP Evaluation — I4

Scenarios:          10
Passed:             10
Failed:             0

Missing facts:      0
Unexpected facts:   0
Forbidden facts present: 0
Wrong statuses:     0
Evidence errors:    0

RESULT: PASS

Reproduced deterministically across repeated runs, requires no LLM API key.

Quick Start

git clone --branch v0.3.0 --depth 1 \
  https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
docker compose up

Then open http://localhost:8000. See the root
README.md
for the full Quick Start, runtime demo, and feature walkthrough.

Known limitations

• gRPC/protobuf calls (Quarkus) — unsupported.
• Kafka topic/subscription semantics (Quarkus) — unsupported.
• messaging.operation legacy-attribute recognition gap (Quarkus) — insufficient evidence,
  deferred.
• PostgreSQL/database dependencies (Airflow) — unsupported.
• Airflow Execution API caller identity — unresolved by design, not guessed.
• Airflow runtime-role / Celery messaging identity — unresolved, deferred.
• Pre-1.0: Canonical Model, REST API, Graph Schema, Adapter SPI, and configuration format are not
  yet guaranteed stable.

None of the above represents an incorrect supported claim — each is explicit and bounded.

What changed since v0.2.0

See
CHANGELOG.md
for the full entry. In summary: no production architecture-intelligence semantics changed. This
release is validation and hardening evidence, not a new capability.

What's next

v0.4 — Architecture Intelligence Tools, goal: Trusted Architecture Context for Agents.
v0.4 will expose snapshot-bound, evidence-qualified, auditable architecture answers through
structured contracts and read-only tools — an agent may consume and reason over AIP evidence, but
it must never become the source of architectural truth. See
ROADMAP.md
for the full v0.4 → v0.5 → v0.9 → v1.0 sequence.

Documentation

• README.md — project overview, Quick Start, runtime demo
• docs/real-world-validation/ — the full Quarkus and Airflow dossiers and the cross-system decision trail
• docs/specifications/0.3.0/ — the v0.3.0 design/implementation history (I1-I5)
• ROADMAP.md / CHANGELOG.md — where this is headed, and what's shipped so far
• docs/release-validation/v0.3.0-post-release-verification.md — independent verification of this exact published release: GHCR digest match, anonymous pull, non-root execution, health/import smoke, and a fresh tagged-source clone

Security

Please report security vulnerabilities privately — see
SECURITY.md.
Never report a vulnerability as a public issue.

v0.3.0-rc.2

v0.3.0-rc.2 release notes

Project status: candidate frozen; real-system revalidation pending (I5.2). This tag is not
ready to ship as v0.3.0.

Why this candidate exists

v0.3.0-rc.1
completed I1-I4 (real-world validation against Quarkus Super Heroes and Apache Airflow, plus
cross-system model hardening) with zero production changes. During I5 entry qualification, an
independent audit found that pyproject.toml and uv.lock's root package both still declared
project version 0.2.0, even though rc.1 was the v0.3.0 release candidate — a release-blocking
inconsistency per the
I5 specification
§10.

That fix (0.2.0 → 0.3.0, a one-line uv.lock diff, no dependency re-resolution) changes the
source tree and therefore creates a new candidate, under this project's own no-substitution policy —
see
v0.3.0-rc.2-candidate-preparation.md
for the full entry-audit and fix record.

What is verified at this exact commit

• pyproject.toml/uv.lock consistently declare 0.3.0.
• Ruff lint and format: green.
• Unit tests: 508 passed. Integration tests: 160 passed.
• Deterministic v0.2 evaluation: 10/10 PASS.
• pip-audit: no known vulnerabilities.
• CI, CodeQL (Python + Actions): green at this exact commit.

What is explicitly NOT yet verified against this candidate

• Quarkus Super Heroes and Apache Airflow real-system revalidation. v0.3.0-rc.1's real-system
  evidence is bound to commit 9f95d48, not this one, and does not transfer by content-equivalence
  argument. Fresh, full revalidation (two runs each, from clean state) against this exact candidate
  is I5.2's next task.
• Fresh Quick Start / clean-checkout qualification against this exact tag.
• GHCR artifact verification for this tag.
• A GO/NO-GO decision. This tag exists to freeze the candidate identity, not to declare readiness.

What's next

I5.2 will execute the real-system revalidation and remaining qualification gates against this exact
candidate. Only after that completes, and a GO is recorded, will a final v0.3.0 tag be cut — at
this commit if no further defect is found, or at a later one if it is.

v0.3.0-rc.1 remains immutable and is not superseded in the sense of being deleted or moved — it
stands as historical record of the pre-version-fix candidate.

v0.3.0-rc.1

v0.3.0-rc.1 release notes

Project status: Real-World Validation and Cross-System Hardening (I1-I4) complete; I5 (release
qualification) pending before v0.3.0 ships.

This is the release candidate for v0.3.0 — the release that proves the architecture intelligence
validated reproducibly in v0.2.0 survives real, independently authored systems, and hardens the
Canonical Model only where real evidence justifies it.

Highlights

• I1 — real-world validation contract frozen: finding vocabulary, ground-truth independence
  rules, supported-scope rules, comparator semantics, dossier structure, runbook contract.
• I2 — Quarkus Super Heroes (external reference architecture): 38 correct, 2 unsupported, 1
  insufficient evidence overall (0 in the comparator-only score), 0 incorrect/missing supported.
  Two independent runs, byte-identical.
• I3 — Apache Airflow (real-world OSS software): 9 correct, 3 unsupported, 2 unresolved
  identity, 1 insufficient evidence, 0 incorrect/missing supported. Two independent runs,
  byte-identical.
• I4 — Cross-System Model Hardening: all 10 findings from both dossiers dispositioned — zero
  required a production fix (NO_CHANGE/DOCUMENT_UNSUPPORTED/DEFER only). The
  canonical-redesign gate answered NO: no fundamental Canonical Model redesign is required
  before v0.4. Both systems revalidated twice each against this exact candidate, byte-identical
  captures and comparator output both times.

Full deterministic cross-system report:
docs/real-world-validation/cross-system/report.md.

No production changes

Every real-system finding from either dossier was NO_CHANGE, DOCUMENT_UNSUPPORTED, or DEFER —
AIP's supported-scope semantics are unchanged from v0.2.0.

Known limitations

• gRPC/protobuf calls (Quarkus) — unsupported
• Kafka topic/subscription semantics (Quarkus) — unsupported
• messaging.operation legacy-attribute gap (Quarkus) — insufficient evidence, deferred
• PostgreSQL/database dependencies (Airflow) — unsupported
• Airflow Execution API caller identity — unresolved
• Airflow runtime-role / Celery messaging identity — unresolved, deferred

None of these represents an incorrect supported claim — each is explicit and bounded.

What's next

I5 will qualify this exact candidate and publish v0.3.0. See
ROADMAP.md
for the full v0.3 track and the v0.4 (tools) → v0.5 (discovery) → v0.9 (freeze) → v1.0 (stable)
sequence.

Documentation

docs/real-world-validation/ — full Quarkus and Airflow dossiers, the cross-system decision trail,
and the report above.

v0.2.0

Project status: Experimental / pre-1.0. The Canonical Model, REST API surface, Graph Schema,
Adapter SPI, and configuration format are not yet guaranteed stable — expect breaking changes on a
future minor version bump. See ROADMAP.md.

License: Apache License, Version 2.0.

What v0.2 proves

AIP v0.2.0 adds a deterministic evaluation suite that verifies the architecture intelligence
introduced in v0.1 against independently authored ground truth.

v0.1 already builds an evidence-backed architecture knowledge graph from OpenAPI, AsyncAPI, and
OpenTelemetry, and classifies every relationship as CONFIRMED, OBSERVED_ONLY, or
NOT_OBSERVED_IN_WINDOW. v0.2 does not add another architecture-intelligence dimension — it
proves, reproducibly, that the intelligence v0.1 already produces is actually correct: known
declared input plus known observed input plus an observation context, run through real AIP
ingestion and runtime resolution, projected to canonical facts, and compared against
independently authored ground truth for a deterministic PASS/FAIL.

Highlights

• A deterministic evaluation kernel (evaluation/) — real AIP ingestion and runtime resolution,
  never a second implementation of AIP's own semantics.
• Ten core scenarios: REST and queue-based dependencies, CONFIRMED/OBSERVED_ONLY/
  NOT_OBSERVED_IN_WINDOW classification, topology/directionality, partial observation with
  qualitative coverage, evidence reconciliation, and a pure declared-only REST relation.
• Exhaustive missing/unexpected/forbidden-fact detection — no in-scope actual fact escapes
  assertion.
• Strict expected.yaml schema validation and deterministic comparison/report ordering.
• Fully local reproducibility: no separately running Neo4j, no LLM API key required.

How to run the evaluator

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
uv sync
uv run python -m evaluation run

Requires Docker (an ephemeral Testcontainers Neo4j) — no separately running Neo4j, no
OPENAI_API_KEY. See evaluation/README.md for scenario details,
the ground-truth format, and how to read a failure report.

Evaluation result

AIP Evaluation — I4

[PASS] 01-rest-confirmed
[PASS] 02-rest-observed-only
[PASS] 03-async-confirmed
[PASS] 04-orphan-messaging
[PASS] 05-mixed-rest-async
[PASS] 06-request-response-queue-pair
[PASS] 07-not-observed-in-window
[PASS] 08-evidence-reconciliation
[PASS] 09-partial-observation
[PASS] 10-declared-rest-relation

Scenarios:          10
Passed:             10
Failed:             0

Missing facts:      0
Unexpected facts:   0
Forbidden facts present: 0
Wrong statuses:     0
Evidence errors:    0

RESULT: PASS

Reproduced deterministically across repeated runs against independent fresh evaluation state.

What changed since v0.1.0

See CHANGELOG.md for the full entry. In summary: the
entire deterministic evaluation suite above is new; no v0.1 architecture-intelligence semantics
(canonical model, adapters, graph schema, runtime status classification, evidence model) changed.

Known limitations

• Pre-1.0 surfaces (Canonical Model, REST API, Graph Schema, Adapter SPI, configuration format)
  are not yet guaranteed stable.
• No Kubernetes/cloud discovery, no gRPC/protobuf adapter, no GraphRAG.
• No broad validation against independent real-world reference systems yet (planned as a separate
  pre-1.0 qualification track, not part of this release).
• Natural-language query requires an LLM provider key; deterministic evaluation does not.
• DLQ directionality and cross-batch HTTP correlation remain optional, not-yet-added evaluation
  scenarios (both already covered by other means: DLQ mapping is captured declaratively, and
  cross-batch correlation is exercised in the runtime demo).

Quick Start

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
docker compose up

Then open http://localhost:8000. See the root README.md for the full Quick
Start, runtime demo, and feature walkthrough.

Documentation

• README.md — project overview, Quick Start, runtime demo
• evaluation/README.md — the deterministic evaluation suite
• docs/ — architecture, canonical model, graph/evidence model, ingestion, analyses,
  OpenTelemetry, configuration, security model, development, adapter development
• docs/specifications/0.2.0/ — the v0.2.0 design/implementation
  history (I1-I5)
• ROADMAP.md / CHANGELOG.md — where this is headed,
  and what's shipped so far

Security

Please report security vulnerabilities privately — see SECURITY.md. Never
report a vulnerability as a public issue.

v0.1.0

Project status: Experimental / Alpha
License: Apache-2.0

First v0.1.0 release, superseding v0.1.0-alpha.1/v0.1.0-alpha.2. Two alpha releases were cut
first specifically to validate the release pipeline itself (fresh clone, fresh runtime demo, a
pulled GHCR image, a fully independent smoke test) before this tag — see docs/release-validation/
for the full evidence trail and the GO/NO-GO decision record.

Highlights

• OpenAPI ingestion (REST provider extraction)
• AsyncAPI queue topology (send/receive, DLQ mapping)
• Architecture Manifest adapter (the one thing OpenAPI can't express: who calls a REST operation)
• Evidence/provenance — every architecture fact is persisted with a traceable source
• Five deterministic architecture analyses (no LLM): queue senders/consumers, orphan queues,
  mixed sync/async blast radius
• Semantic query validation (Graph Schema + Cypher validator) for the optional natural-language
  query layer
• OpenTelemetry runtime discovery — /v1/traces OTLP ingestion, resolved against declared
  architecture
• Declared vs. observed architecture comparison: CONFIRMED / OBSERVED_ONLY /
  NOT_OBSERVED_IN_WINDOW
• Architecture drift detection — undocumented dependencies surface as OBSERVED_ONLY findings
• Runtime evidence reconciliation — removing a stale declaration degrades a relation to
  OBSERVED_ONLY, never silently deletes it
• Cross-batch HTTP correlation — a CLIENT span and its matching SERVER span can arrive in separate
  OTLP requests and still resolve to one observed dependency

Changed since v0.1.0-alpha.2

Nothing functional — this tag exists to promote the already-verified v0.1.0-alpha.2 state
(commit 65264a12, plus this session's release-readiness documentation) to the non-prerelease
v0.1.0 tag. See CHANGELOG.md for the full alpha.1/alpha.2 change history that led here.

Known limitations

• Pre-1.0 — the Canonical Model, REST API, Graph Schema, Adapter SPI, and configuration format are
  not yet guaranteed stable (see ROADMAP.md).
• No Kubernetes/cloud discovery yet (planned for v0.2).
• The natural-language query layer requires an LLM provider API key; everything else works without
  one.

Quick Start

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
docker compose up

Then open http://localhost:8000. See README.md for the full Quick Start and the Collector-based
runtime demo.

Documentation

docs/ — architecture, canonical model, graph/evidence model, OpenTelemetry, security model,
adapter development, and more. docs/adr/ for the reasoning behind the core design decisions.
docs/release-validation/ for exactly what's been verified about this release and how, including
the GO/NO-GO decision record.

Security

See SECURITY.md — please report vulnerabilities via GitHub's private vulnerability reporting, not
as a public issue.

v0.1.0-alpha.2

Project status: Experimental / Alpha
License: Apache-2.0

Second public pre-release, superseding v0.1.0-alpha.1. v0.1.0-alpha.1's own verification (fresh
clone, fresh runtime demo, a pulled GHCR image) surfaced several real issues — this tag exists
specifically to confirm they're fixed, and to give the release pipeline itself one clean run before
promoting to v0.1.0. See docs/release-validation/ for the full verification record, including
why alpha.1's own GHCR tag ended up pointing to an image built before one of these fixes.

Changed since v0.1.0-alpha.1

• Container now runs as a non-root user (alpha.1's published image ran as root — no USER
  instruction in Dockerfile).
• Fixed a CodeQL finding: GET /health/neo4j no longer leaks exception detail (e.g. connection
  info) to the caller on failure — logged server-side only now.
• Fixed the base Quick Start: docker-compose.yml required OPENAI_API_KEY even though the
  platform is documented as working without one; README.md's Quick Start also had a placeholder
  clone URL and never mentioned creating .env at all.
• Fixed the runtime demo's natural-language query: it silently returned zero rows against demo
  data, because the default analysis window was scoped to the wrong environment.
• Release pipeline hardening: the GitHub Actions Docker workflow previously fired twice per
  release (a real race that split alpha.1's build across two different image digests); branch
  protection, dependency alerts, and dependabot security updates are now all enabled; pyproject.toml
  no longer carries stale PoC-era metadata.

Highlights

• OpenAPI ingestion (REST provider extraction)
• AsyncAPI queue topology (send/receive, DLQ mapping)
• Architecture Manifest adapter (the one thing OpenAPI can't express: who calls a REST operation)
• Evidence/provenance — every architecture fact is persisted with a traceable source
• Five deterministic architecture analyses (no LLM): queue senders/consumers, orphan queues,
  mixed sync/async blast radius
• Semantic query validation (Graph Schema + Cypher validator) for the optional natural-language
  query layer
• OpenTelemetry runtime discovery — /v1/traces OTLP ingestion, resolved against declared
  architecture
• Declared vs. observed architecture comparison: CONFIRMED / OBSERVED_ONLY /
  NOT_OBSERVED_IN_WINDOW
• Architecture drift detection — undocumented dependencies surface as OBSERVED_ONLY findings
• Runtime evidence reconciliation — removing a stale declaration degrades a relation to
  OBSERVED_ONLY, never silently deletes it
• Cross-batch HTTP correlation — a CLIENT span and its matching SERVER span can arrive in separate
  OTLP requests and still resolve to one observed dependency

Known limitations

• Pre-1.0 — the Canonical Model, REST API, Graph Schema, Adapter SPI, and configuration format are
  not yet guaranteed stable (see ROADMAP.md).
• No Kubernetes/cloud discovery yet (planned for v0.2).
• The natural-language query layer requires an LLM provider API key; everything else works without
  one.

Quick Start

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
docker compose up

Then open http://localhost:8000. See README.md for the full Quick Start and the Collector-based
runtime demo.

Documentation

docs/ — architecture, canonical model, graph/evidence model, OpenTelemetry, security model,
adapter development, and more. docs/adr/ for the reasoning behind the core design decisions.
docs/release-validation/ for exactly what's been verified about this release and how.

Security

See SECURITY.md — please report vulnerabilities via GitHub's private vulnerability reporting, not
as a public issue.

v0.1.0-alpha.1

v0.1.0-alpha.1 release notes (12G Phase 1, step 12)

Project status: Experimental / Alpha
License: Apache-2.0

This is the first public pre-release, cut specifically to validate the complete release pipeline
(GitHub Actions, CodeQL, GHCR publishing) before promoting to v0.1.0. Expect the occasional rough
edge — that's exactly what this tag exists to surface.

Highlights

• OpenAPI ingestion (REST provider extraction)
• AsyncAPI queue topology (send/receive, DLQ mapping)
• Architecture Manifest adapter (the one thing OpenAPI can't express: who calls a REST operation)
• Evidence/provenance — every architecture fact is persisted with a traceable source
• Five deterministic architecture analyses (no LLM): queue senders/consumers, orphan queues,
  mixed sync/async blast radius
• Semantic query validation (Graph Schema + Cypher validator) for the optional natural-language
  query layer
• OpenTelemetry runtime discovery — /v1/traces OTLP ingestion, resolved against declared
  architecture
• Declared vs. observed architecture comparison: CONFIRMED / OBSERVED_ONLY /
  NOT_OBSERVED_IN_WINDOW
• Architecture drift detection — undocumented dependencies surface as OBSERVED_ONLY findings
• Runtime evidence reconciliation — removing a stale declaration degrades a relation to
  OBSERVED_ONLY, never silently deletes it
• Cross-batch HTTP correlation — a CLIENT span and its matching SERVER span can arrive in separate
  OTLP requests and still resolve to one observed dependency

Known limitations

• Pre-1.0 — the Canonical Model, REST API, Graph Schema, Adapter SPI, and configuration format are
  not yet guaranteed stable (see ROADMAP.md).
• No Kubernetes/cloud discovery yet (planned for v0.2).
• The natural-language query layer requires an LLM provider API key; everything else works without
  one.

Quick Start

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
docker compose up

Then open http://localhost:8000. See README.md for the full Quick Start and the Collector-based
runtime demo.

Documentation

docs/ — architecture, canonical model, graph/evidence model, OpenTelemetry, security model,
adapter development, and more. docs/adr/ for the reasoning behind the core design decisions.

Security

See SECURITY.md — please report vulnerabilities via GitHub's private vulnerability reporting, not
as a public issue.