fix packet · the repair contract

The repaircontract.

When the build fails, axint writes a Fix Packet — a single structured file your coding agent reads to repair the failure, rerun, and ship.

the definition

A Fix Packet is the repair contract between your coding agent, axint, and Xcode.

Six fields. One JSON file. The smallest possible artifact that lets the agent decide whether to ship, repair, or run more tests — and act on it without copy-paste, chat, or human translation.

generate a packetread the docsview source

anatomy at a glance

axint

Fix
Packet.

.axint/fix/latest.json

agent-readable
verdict
fix_required
confidence
0.91 · high
findings
3 across 1 file
repair prompt
generated · drop into Claude Code, Cursor, Codex
xcode checklist
ready · open file · go to line · apply change · rerun
evidence trail
.axint/run/logs · .axint/run/xcresults · build_log

canonical schema

One JSON file.Versioned, public.

The full Fix Packet shape, exactly as axint writes it to .axint/fix/latest.json on every run. Schema versioned alongside the compiler. Use it to validate, generate types, or build your own consumers.

.axint/fix/latest.json
schema v1
{
  "verdict": "fix_required",
  "confidence": {
    "score": 0.91,
    "level": "high"
  },
  "duration_ms": 142000,
  "findings": [
    {
      "code": "AX764",
      "severity": "warning",
      "file": "Sources/Composer/HomeComposer.swift",
      "line": 142,
      "message": "TextField overlay missing .allowsHitTesting(false)",
      "why": "Decorative overlays steal hit-testing from the field.",
      "fix": "Add .allowsHitTesting(false) to the overlay modifier."
    }
  ],
  "ai_repair_prompt": "Open HomeComposer.swift line 142. Add .allowsHitTesting(false) to the .overlay() modifier. Rerun: axint run --only-testing testComposerAcceptsInput",
  "xcode_checklist": [
    "open HomeComposer.swift in Xcode",
    "navigate to line 142",
    "add .allowsHitTesting(false) to the .overlay() modifier",
    "rerun axint run --only-testing testComposerAcceptsInput"
  ],
  "next_command": "axint xcode check",
  "artifacts": {
    "swift": ".axint/run/latest.swift",
    "build_log": ".axint/run/logs/build-2026-05-02T14-32.log",
    "xcresult": ".axint/run/xcresults/HomeComposerUITests.xcresult"
  }
}

anatomy

Six fields.One contract.

Each field has one job. None of them duplicate each other. Together they form the smallest agent-readable repair contract that closes the loop without human translation.

01 · verdict

ready_to_ship · fix_required · evidence_required

One word the agent reads to decide.

The smallest possible signal — ship, repair, or run more tests. Not a build log, not a vibe, not a list of warnings. One enum value the agent compares against and routes on.

"verdict": "fix_required"

02 · confidence

0.0 → 1.0 · low · medium · high

How certain the verdict is.

Numeric and qualitative. high means runtime evidence has confirmed the verdict. low means the static check is firm but the runtime piece is still pending — the agent should run more tests before shipping.

"confidence": { "score": 0.91, "level": "high" }

03 · findings

ranked array of named issues

Each issue, named precisely.

AX code, severity, file path, line number, message, why it matters, suggested fix. The findings are ranked — the agent works the first one and reruns. No flailing through lists of warnings looking for the real problem.

"findings": [
  {
    "code": "AX764",
    "file": "HomeComposer.swift",
    "line": 142,
    "fix": "add .allowsHitTesting(false)"
  }
]

04 · ai_repair_prompt

drop-in prompt for Claude Code, Cursor, Codex

The exact instruction your agent runs.

Pre-formatted prompt the next agent run can act on without copy-paste. Already names the file, the line, the change to make, and the command to run after. Hosts can pipe this directly into the agent's next turn.

"ai_repair_prompt": "Open HomeComposer.swift line 142.\nAdd .allowsHitTesting(false) to the .overlay() modifier.\nRerun: axint run --only-testing testComposerAcceptsInput"

05 · xcode_checklist

human-readable steps

If a person wants to fix it themselves.

Same change as the AI prompt, but written for a human in Xcode. Open this file, go to this line, change this thing, rerun this command. Useful for code review, pair programming, or learning what the validator caught.

"xcode_checklist": [
  "open HomeComposer.swift",
  "navigate to line 142",
  "add .allowsHitTesting(false)",
  "rerun axint run"
]

06 · artifacts

.axint/* paths the agent can read

The full evidence trail.

Build log, .xcresult bundle, generated Swift, source the compiler emitted, run console output. Everything machine-readable, every path absolute, every artifact actually on disk.

"artifacts": {
  "swift": ".axint/run/latest.swift",
  "build_log": ".axint/run/logs/build-2026-05-02T14-32.log",
  "xcresult": ".axint/run/xcresults/HomeComposerUITests.xcresult"
}

the three verdicts

Three states.Zero ambiguity.

The verdict field can only be one of three values. Each one routes to a specific next action. No fuzzy “mostly passing” states, no warnings the agent can ignore.

enum value

ready_to_ship

agent action

Agent can proceed.

Static checks clean, focused tests passed, runtime evidence captured. The only verdict that lets the loop close.

enum value

fix_required

agent action

Agent should patch and verify.

axint found ranked findings with file, line, and reason. The repair prompt is pre-formatted for the agent's next run.

enum value

evidence_required

agent action

Agent needs more context before repair.

Compiler is happy. Validator is happy. But the focused test never ran, or the build artifact is stale. No false confidence.

logs vs packets

Logs are for humans.Packets are for agents.

log

A log tells you what failed.

Build output, stack traces, warnings, deprecation notices. A human reads it, decodes it, copies the relevant line into chat. The agent guesses. The build fails again. Repeat.

audience
human
format
unstructured text
interpretation
manual
loop
copy-paste
next move
undefined

fix packet

A Fix Packet tells the agent what to do next.

Verdict, confidence, named findings, AI-ready repair prompt, Xcode checklist, evidence trail. Agent reads, applies the change at the named line, reruns. No human translator in the middle.

audience
agent
format
structured JSON contract
interpretation
automatic
loop
agent-readable, no translation
next move
explicit next command

the loop in motion

From failureto ship.

A real failure mode, end-to-end. AX764 — TextField overlay missing .allowsHitTesting(false). The field renders. It just won't accept typing. Caught before the user ever sees it.

the handoff

  1. 01

    xcode failure

    build error · line 142

  2. 02

    fix packet

    verdict · prompt · checklist

  3. 03

    agent repair

    applies edit · reruns

  4. 04

    verify

    ready_to_ship

  1. 01 · agent

    Agent generates a feature.

    Coding agent writes a TextField with a decorative overlay. Code compiles in isolation. Agent calls axint compile to emit Swift.

    HomeComposer.swift · 142 lines · ready for build

  2. 02 · axint

    axint validates. Diagnostic fires.

    Validator catches AX764 — the .overlay() is missing .allowsHitTesting(false). The text field will render but won't accept typing. Cloud writes the Fix Packet.

    .axint/cloud/report.json · verdict: fix_required

  3. 03 · agent

    Agent reads the packet.

    Agent reads .axint/fix/latest.json, finds the AI repair prompt, applies the edit at line 142, saves the file. Total round-trip: about two seconds. No copy-paste, no chat back-and-forth.

    HomeComposer.swift · line 142 · .allowsHitTesting(false) added

  4. 04 · agent

    Agent reruns the loop.

    Agent calls axint run --only-testing testComposerAcceptsInput. Cloud revalidates, runs the focused UI test, confirms the field accepts input. New verdict: ready_to_ship.

    verdict: ready_to_ship · confidence: 0.94 · evidence captured

The whole loop ran in seconds. No copy-paste, no chat back-and-forth, no human translation between the build error and the agent. The Fix Packet closed the gap.

how to access it

Four ways in.Same contract.

The packet is the same artifact whether you read it as a file, get it from the CLI, receive it through MCP, or validate it against the schema. One contract, multiple entry points.

01 · file path

On disk, every run.

.axint/fix/latest.json. The current run's packet, always overwritten. Older packets archived under .axint/fix/history/. Stable path your agent can hardcode.

$cat .axint/fix/latest.json
02 · cli

axint command, structured output.

Run axint run or axint cloud check. The packet is written automatically. Pass --json for machine-readable output, or --markdown for the human-skimmable version.

$axint cloud check ./MyApp --json
03 · mcp tool

35 MCP tools speak the contract.

Hosts call axint.cloud.check or axint.run through MCP and receive the packet as the structured response. Claude Code, Cursor, Codex, Xcode, and 7 other agentic IDEs read it directly.

$tool: axint.cloud.check
result → fix packet
04 · json schema

Versioned, public, in the repo.

The Fix Packet schema is published in the open-source compiler repo. Versioned alongside axint releases. Use it to validate output, generate types, or build your own consumers.

$schemas/fix-packet/v1.json

try it

Generate a packet.Hand it to your agent.

Run a free Cloud Check on any Apple-native code. The Fix Packet writes itself, the agent reads it, and the loop closes.

Open the JSON schema if you want to verify the contract shape. Open the docs if you want to wire it into your own agent. Either way, the packet is the smallest agent-readable artifact that closes the repair loop.

generate a packetrun cloud checkview schemaread the docsview source