Architecture

Architectural intent

This repository implements one bounded, reproducible proof of concept. Its purpose is to demonstrate that the fixed Java 25 fixture can be statically extracted, observed at runtime, reconciled by exact identity, fused with provenance, reopened, and queried twice without mutating the graph.

poc/contract.md is the normative behavioral boundary. This document explains how the implementation supports that contract. If the two documents ever disagree, the contract wins and the discrepancy is a defect.

The architecture favors explicit data flow, exact validation, and small components over framework abstractions. It is intentionally not a production platform.

Documentation boundary

The VitePress site is a presentation projection of the repository's canonical Markdown. It has no authority over the contract, executable definition, finite oracles, retained evidence, verifier, or public result. If presentation text disagrees with an executable source or poc/contract.md, the disagreement is a documentation defect.

package.json, package-lock.json, .nvmrc, .vitepress/, and docs/ belong only to documentation authoring and publication. The exact Docker build-context allowlist excludes them, the Dockerfile does not copy them, and neither the semantic inventory nor the launcher/build execution boundary includes them. Changes limited to those documentation-only tooling and presentation files must not create a Node.js dependency for ./poc.sh or change POC source identity. Canonical Markdown is different: poc/contract.md is a semantic input, and README.md is copied into the image, so changing those files legitimately changes the relevant content identity and requires the corresponding review gates.

Execution flow

poc.sh
  -> Docker Compose and the restricted container runtime
  -> container_cli.py
       -> poc_runner.py
            -> poc_inventory.py and runtime_manifest.py
            -> process_control.py
                 -> harness.py build/extract/prepare/workload/complete stages
                 -> verify.py exact semantic verification
            -> four official negative semantic cases
       -> poc_analyze.py result reconstruction
       -> poc_analyze.py independent check-only reconstruction
  -> one compact JSON result on standard output

The runner captures the semantic inputs and builds the fixed fixture once. Each unit then extracts static facts, reopens the static snapshot, invokes the read-only query before fusion, prepares the candidate and selection policy, runs fresh baseline and traced JVMs in the scheduled order, reconciles exact identities, preserves every observation disposition, fuses accepted observations, persists and reopens the hybrid snapshot, invokes the same query after fusion, and verifies the exact result. The analyzer reconstructs the public result from retained evidence and then repeats that reconstruction in check-only mode.

Figure 1. The supported success path is vertical and bounded. Any failed exact gate terminates nonzero without a retry, repair, or fallback path.

Successful collaboration

The public command coordinates several narrow components rather than combining their responsibilities in one process. Controlled semantic stages receive deadlines and resource caps, publish process receipts and logs, and succeed only after their owned containment domain is empty.

Figure 2. The interaction shows only the successful path. Every failed call terminates the run nonzero, and the second analyzer invocation checks retained bytes without rewriting them.

Component responsibilities

Component	Responsibility	Explicit boundary
poc.sh	Validate launcher inputs, derive source revision metadata, and invoke Docker Compose.	Does not interpret semantic results.
docker-compose.yml and Dockerfile	Build the pinned toolchain image and request the non-root, capability-free, network-isolated, read-only runtime posture.	Containers do not stabilize the host kernel, CPU, scheduler, or container engine.
container_cli.py	Expose run, check, and test; enforce runtime posture before dispatch; sequence run and reconstruction.	Standard output is reserved for the public JSON result.
poc_runner.py	Materialize captured inputs, create the plan, schedule units, retain evidence, and execute negative cases.	Orchestration does not decide whether a semantic result is valid.
process_control.py	Own each subprocess group, enforce resource and time limits, reap descendants, and issue exact receipts.	It contains processes but does not interpret graph semantics.
harness.py	Build the fixture and implement static extraction, runtime collection, exact reconciliation, fusion, persistence, and both query invocations.	It produces evidence; it does not grant authority to a result.
verify.py	Compare one completed semantic unit with the independent finite oracles and exact invariants.	It never repairs or normalizes a failed result.
poc_analyze.py	Validate retained artifacts, reconstruct aggregate results, publish the compact output, and check an existing run without rewriting it.	It accepts only the declared artifact and schema sets.
poc_inventory.py	Bind the exact semantic input set and the launcher/build execution boundary.	It does not claim that hashes are signatures.
runtime_manifest.py	Record executable identities and observe the effective runtime posture.	It reports the current process and selected toolchain, not the entire host.

Figure 3. The contract is the normative human-readable boundary. The definition, query, and finite oracles are executable acceptance inputs; the harness produces evidence, while the verifier and analyzer reject disagreement at their respective boundaries.

Deployment boundary

The POC is a local, one-shot experiment on a Docker-capable host. The container narrows and records the execution posture, but it is not a virtual-machine trust boundary and does not turn the experiment into a deployed service. Image build and pull activity happens before the network-disabled runtime and is not claimed to be network-free.

Figure 4. Documentation tooling and generated site files remain outside the POC image. The host kernel, CPU, scheduler, WSL2 layer, and Docker Engine remain environmental dependencies.

Data and evidence boundaries

The repository separates four kinds of information:

1. Normative inputs: the contract, definition, fixture, query, and independent oracles. Their exact declared set and bytes are inventoried.
2. Execution identity: launcher and container definitions, source revision metadata, Python and JDK identities, and the observed runtime posture.
3. Raw evidence: schedules, process receipts, captured event streams, semantic verification receipts, negative cases, and retained unit results.
4. Derived results: the run summary and compact public output reconstructed by the analyzer.

Run artifacts are create-only within one new .runs/<run-id>/ directory. JSON artifacts are reopened and checked where the contract requires it. Raw and result manifests bind exact file membership and SHA-256 values, and the independent checker rejects stale, omitted, extra, or internally inconsistent artifacts.

These mechanisms provide deterministic correlation and integrity checks under the local, single-operator experiment model. They do not provide cryptographic authenticity against an actor who can replace the repository, the container launcher, and the complete .runs/ artifact set. There is no signing service, remote attestation, append-only external store, or independent trust authority in scope.

Failure behavior

The public path fails closed when an exact inventory, runtime posture, process receipt, semantic oracle, retained artifact, or reconstruction obligation is not satisfied. A failed contract is reported; it is not repaired, guessed, or routed through a fallback implementation.

The process controller applies explicit time, process, thread, descriptor, memory, output-size, and free-space limits. A stage is successful only after its owned containment domain is empty and its receipt satisfies the exact oracle.

Observability

The public container CLI and controlled runner stages emit strict JSON Lines to standard error. Progress records identify the component, phase, status, monotonic elapsed nanoseconds, and observed return code when available. Controlled stage output is also retained in per-stage log files.

Progress records are operational diagnostics, not semantic evidence and not part of any retained schema. Standard output remains reserved for the existing compact JSON result. Durations are descriptive and do not establish an SLO or benchmark.

Verification strategy

The verification layers have different jobs:

• focused contracts exercise stable boundaries, malformed inputs, process containment, runtime posture, inventory exactness, and artifact retention;
• a real canary executes the Java fixture through reconstruction;
• four official negative cases prove that plausible identity, provenance, fusion, and query mutations are rejected for the intended reasons; and
• test-only evidence probes mutate retained artifacts and deeper semantic obligations without changing the official four-case public contract.

Coverage percentage is not the acceptance criterion. The relevant criterion is whether every contract obligation and material failure boundary has executable evidence.

Deliberate omissions

The POC intentionally omits production authentication and authorization, multi-tenancy, service APIs, distributed storage, remote telemetry, high availability, autoscaling, deployment automation, capacity claims, and SLOs. Adding those systems would increase implementation surface without strengthening the bounded claim.

Evolution rules

• Preserve the supported claim during refactoring. A claim change requires an explicit design decision and corresponding updates to the contract, definition, oracles, and acceptance evidence.
• Make changes incrementally and protect existing behavior with focused contracts and the public gates.
• Prefer direct responsibilities and concrete data contracts over speculative abstractions or premature production infrastructure.
• Do not mask a failed obligation with a workaround or fallback path.
• Keep generated runs, logs, caches, and build outputs outside Git.
• Keep documentation tooling outside the Docker and semantic execution boundaries; presentation must not become an authority for experimental facts.
• Write all project content in US English, except when an established term from another language is specifically required.