v0.4.0

AIP v0.4.0 — Trusted Architecture Context for Agents

Project status: Experimental / pre-1.0. The Canonical Model, REST/MCP 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.4 proves

AIP v0.4.0 exposes the architecture intelligence validated through v0.3 as stable,
snapshot-bound, evidence-backed, machine-consumable context for AI agents and architecture
tools — through exactly three read-only MCP tools, deterministically qualified, with an agent
never able to become the source of architectural truth.

v0.3 proved AIP's architecture intelligence survives contact with real, independently authored
systems. v0.4 does not add another architecture-intelligence dimension — it makes that already-
qualified intelligence safely consumable by external MCP clients: get_service_dependencies
(qualified one-hop dependencies), get_architecture_drift (only the declared-versus-observed
discrepancies — OBSERVED_ONLY/NOT_OBSERVED_IN_WINDOW, never a match), and get_evidence
(bounded, sanitized provenance resolution). Every answer is snapshot-bound; the dependency and
drift answers are explicitly qualified and evidence-linked, while get_evidence resolves
provenance for already-identified references rather than producing qualified claims of its own.
Nothing is invented, guessed, or silently absorbed.

Candidate identity

Candidate SHA:            a906a5895f803287aec973e9e3678655fd8c0f8a
Dependency-lock SHA-256:  b67974c65faf78d5fce1e55fb5ba39eb7852bf3ed28eb603b679195ac37c8f4e
Qualifying RC tag:        v0.4.0-rc.1
GHCR image digest:        sha256:e4da1bf42d7ed491ee3b7e3645ddcc1f83a56ef3e6251c59b63f94a904beb720

The three MCP tools

get_architecture_drift      — direct dependencies whose evidence shows a declared-versus-observed
                               discrepancy, bound to one stable snapshot
get_evidence                 — resolves 1-20 opaque evidence references to sanitized provenance
                               for one explicit snapshot
get_service_dependencies    — one-hop direct dependencies, qualified against declared and
                               observed evidence, bound to a stable snapshot

tools/list always returns exactly these three, in this fixed lexicographic order. All three are
read-only (zero graph writes), require no LLM API key, and enforce closed input/output JSON
Schemas — see docs/mcp.md.

Deterministic evaluation result

AIP Evaluation — Architecture Answers (I3)

Suite:              architecture-answers
Scenarios:          23
Passed:             23
Failed:             0

Two full clean-state passes: semantic outputs identical
Cross-tool invariants (dependency<->drift, drift<->evidence): PASS

RESULT: PASS

Reproduced deterministically across two independent full clean-state runs, requires no LLM API key.

Frozen Quarkus/Airflow-derived qualification

The three-tool surface is qualified against both systems' already-validated (v0.3.0) evidence,
frozen and reused rather than re-executed live:

quarkus-super-heroes    PASS
apache-airflow          PASS

No fresh live rerun against either system occurred for v0.4.0 — see
docs/specifications/0.4.0/i3-drift-capability-and-deterministic-qualification.md
§20/§64 for why a fresh rerun is explicitly out of scope absent a semantic reason.

The hero demo

An independent client — plain HTTP/JSON-RPC, no AIP internal module, no LLM — discovers all three
tools via tools/list, then calls get_architecture_drift for service:order-service and finds:

OrderService -> LegacyPricingService     OBSERVED_ONLY   (never declared, real dependency)
OrderService -> unused-q                 NOT_OBSERVED_IN_WINDOW

then resolves the finding's evidence through get_evidence at the same snapshot. Reproducible from
a clean state in about five minutes, using fixed/frozen telemetry timestamps rather than a moving
window — see examples/runtime-demo/hero-demo.md.

Quick Start

git clone --branch v0.4.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 and feature walkthrough, and docs/mcp.md for the MCP tool walkthrough.

Known limitations

• Direct dependencies only — no transitive dependency traversal.
• Current state only — no historical/point-in-time snapshots, no snapshot diffing.
• No generic Cypher/graph query surface through any tool.
• MCP is exposed for a local/trusted-network posture — not hardened for direct public-internet
  exposure, no authentication/authorization, no multi-tenancy.
• Every limitation already documented under v0.3.0 (unsupported gRPC/Kafka-topic/database
  mechanisms, unresolved Airflow caller/runtime-role identity, insufficient-evidence Celery
  messaging identity) still applies — v0.4 reuses that frozen evidence unchanged.
• Pre-1.0: Canonical Model, REST/MCP API surface, 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.3.0

See CHANGELOG.md for the full entry. In summary: no architecture-discovery
semantics changed — this release exposes the already-validated model through a new, read-only tool
layer for AI agents.

What's next

v0.5 — Broader Architecture Discovery. Kubernetes discovery, candidate additional source
adapters, and deeper runtime discovery — reconciled with existing declared/observed evidence under
the same safety rules already governing v0.1-v0.4. See ROADMAP.md for the
full v0.5 → v0.9 → v1.0 sequence.

Documentation

• README.md — project overview, Quick Start, runtime demo
• docs/mcp.md — the three MCP tools and a runnable hero-demo walkthrough
• docs/specifications/0.4.0/ — the v0.4.0 design/implementation
  history (I1-I4)
• 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.