Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
212 lines (170 loc) · 8.73 KB

ARCHITECTURE.md

File metadata and controls

212 lines (170 loc) · 8.73 KB
Raw

Axint Architecture

Axint is the proof and repair layer for Apple coding agents. Its architecture combines an evidence runtime for existing Apple projects with optional authoring pipelines that generate inspectable Swift. Both paths converge on the same agent-facing contract: verdict, evidence, findings, next actions, and artifact paths.

System shape

flowchart LR
    A["Existing Swift changes"] --> C["Evidence-aware Swift checks"]
    B["TypeScript / Python / JSON authoring"] --> D["IR validation and Swift generation"]
    D --> C
    C --> E["Xcode build and test evidence"]
    E --> F["Finding reconciliation"]
    F --> G["Fix Packet"]
    F --> H["Signed source-free receipt"]
    G --> I["CLI / MCP / editor"]
    H --> I
Loading

The proof runtime is primary. Generation is one way to create a candidate change; it does not replace Xcode evidence.

Proof runtime

axint prove discovers an Apple project, selects the available Xcode container and scheme, runs evidence-aware Swift validation, executes a real build and any available tests, reconciles the findings, and emits a signed source-free receipt.

flowchart LR
    A["axint prove"] --> B["Project and test discovery"]
    B --> C["Static findings with stable IDs"]
    C --> D["Xcode build and test evidence"]
    D --> E["Evidence reconciliation"]
    E --> F["Optional deterministic repair"]
    F --> D
    E --> G["Canonical source-free payload"]
    G --> H["SHA-256 + Ed25519 receipt"]
    H --> I["axint receipt verify"]
Loading

Compiler-shaped findings can be confirmed by matching Xcode failures or suppressed by a successful selected build. Passing tests provide behavior context, but they do not automatically disprove accessibility, interaction, privacy, design, or runtime advisories. Gate decisions follow active blocking findings rather than raw diagnostic severity.

The local private signing key is stored outside the project under the Axint home directory with owner-only permissions. Receipts contain the public key and its fingerprint. Teams can provide a managed key through AXINT_PROOF_SIGNING_KEY and name it with AXINT_PROOF_SIGNER_NAME. Verification without --trusted-fingerprint proves payload integrity against the embedded key; it does not establish an externally trusted signer identity.

Repair artifacts

The Fix Packet is the local repair contract used by:

  • axint compile
  • axint watch
  • axint validate-swift
  • axint.fix-packet over MCP
  • axint xcode packet
  • project-aware repair and proof workflows

It preserves stable finding identity, evidence class, likely files, concrete next actions, and rerun guidance without forcing full logs into agent context. When coverage is incomplete, the packet lowers confidence instead of treating a heuristic as compiler truth.

TypeScript authoring pipeline

The TypeScript compiler parses supported define*() calls into a language- agnostic intermediate representation, validates that IR, generates Swift and companion metadata, then validates the generated Swift.

TypeScript source
  -> surface parser
  -> IR
  -> IR validator
  -> Swift / plist / entitlement generator
  -> Swift validator
  -> Fix Packet and proof workflow

The implemented dispatch covers intents, entities, views, widgets, apps, Live Activities, App Enums, UnionValue schemas, App Shortcuts, and extension scaffolds. Each surface owns its parser, validator, and generator while sharing diagnostic and repair contracts.

compileFromIR() accepts an intent IR object or JSON payload and skips the TypeScript parse step. That is the stable bridge used by JSON workflows and other language frontends.

Python authoring pipeline

The Python SDK is a native implementation, not a subprocess wrapper around the TypeScript generator. python/axint/ parses Python with the Python AST, produces compatible IR, validates it, and generates Swift directly through generator.py.

Python source
  -> Python AST parser
  -> compatible IR
  -> Python validator
  -> native Python Swift generator

The Python package therefore has no Node.js dependency for its normal parse, validate, and compile commands. Its IR can optionally be piped into the TypeScript CLI for an additional cross-surface validation path:

axint-py parse intent.py --json | axint compile - --from-ir --stdout

The two generators intentionally mirror shared contracts but are separate implementations. Parity tests and compatible IR make divergence visible; the documentation does not imply that Python shells out for normal generation.

The focused Python MCP server uses native Python generation. One optional Swift validation helper can call the installed Node package when available, so that helper is not equivalent to the fully local Python compile path.

Experimental .axint authoring surface

The .axint package under src/core/axint-dsl/ implements tokenization, recovery-aware parsing, canonical formatting, and lowering for intents, entities, enums, and safe public-page manifests. The APIs and axint format command are available without a feature flag.

The surface remains experimental because direct .axint input is not yet wired through the main axint compile command, and views, widgets, and apps are not implemented in the language. The language specification documents this boundary separately from the production proof runtime and the real brownfield benchmark.

MCP and CLI boundary

The CLI is the local process boundary for proof, generation, validation, repair, receipts, telemetry controls, and Xcode orchestration. The MCP server wraps the same application services for standards-compatible hosts and returns compact structured results.

Long-running build and test jobs persist status and log paths under .axint/run so a caller can reconnect, inspect, or cancel without keeping the original request alive. Full logs remain on disk; MCP responses carry summaries and artifact references.

A2A boundary

The A2A adapter exposes complete Apple check, diagnosis, proof, and repair-planning jobs to other agents. It is additive to MCP: MCP remains the fine-grained tool surface, while A2A owns durable task identity, streaming status, cancellation, owner-scoped persistence, and result artifacts.

src/a2a/ contains five explicit boundaries:

  1. Request parsing validates the structured contract and confines every local path to the operator-selected project root.
  2. The service adapter calls existing cloud-check, repair, run, and proof services without introducing a second implementation of product logic.
  3. Result shaping excludes source, raw logs, and absolute paths before an artifact reaches the protocol layer.
  4. The task store scopes durable JSON by tenant and authenticated caller.
  5. The Express transport owns Agent Card discovery, bearer authentication, body limits, rate limits, security headers, and A2A version negotiation.

Cancellation reaches the existing Xcode runner through AbortSignal and stops the child process group. Automatic fixes, repository cloning, outbound agent delegation, and push notifications are intentionally outside this boundary.

Distribution boundary

The public repository ships the open-source compiler, TypeScript and Python SDKs, CLI, proof runtime, MCP servers, templates, tests, Swift Package Manager plugins, and editor integrations. Hosted services consume those public contracts but do not redefine their implementation status.

Directory map

src/core/                 TypeScript parsers, IR, validators, generators
src/core/axint-dsl/       Experimental .axint lexer, parser, printer, lowering
src/proof/                Proof orchestration and signed receipts
src/run/                  Resumable project jobs and Xcode evidence
src/repair/               Fix Packets and project repair plans
src/feedback/             Source-free finding review and feedback
src/mcp/                  MCP server, manifest, and transports
src/a2a/                  A2A Agent Card, task adapter, persistence, and HTTP transport
src/cli/                  Command-line entry points
python/axint/             Native Python parser, IR, validator, generator, MCP
spm-plugin/               Xcode build and validation plugins
benchmarks/brownfield/    Reproducible precision and abstention gate
tests/                    TypeScript integration and unit coverage
python/tests/             Python integration and unit coverage

Extension principles

  1. New checks state their evidence boundary and abstain when it is unknown.
  2. New authoring surfaces separate parsing, validation, and generation.
  3. Generated output remains ordinary, inspectable Swift without runtime lock-in.
  4. Agent-facing output stays compact while complete artifacts remain on disk.
  5. Public proof claims require a reproducible test, benchmark, or Apple-tooling artifact.