vercel-labs--zerolang/docs/articles/diagnostics.md

Read The Error As A Repair Contract

Zerolang diagnostics are written for humans and agents together. A human should see what went wrong. An agent should see the safest next edit shape.

Example:

error[NAM003]: Unknown identifier
  unknown identifier 'message'
  examples/hello.0:2:27

  2 |     check world.out.write(message)
    |                           ^^^^^^^
  rule: Names must be declared before use in the current lexical scope.
  expected: local binding, parameter, function, builtin value
  actual: no visible symbol named 'message'
  fix: Introduce a local binding before this use (local-edit)
  explain: zero explain NAM003

The path may name a .0 projection because source maps point at readable text. That does not mean the agent should edit that file. In a graph-first package, the repair should normally be a graph patch.

Agent Repair Flow

{
  "messages": [
    {
      "role": "user",
      "text": "this fails with NAM003. can you fix it?"
    },
    {
      "role": "assistant",
      "text": "I’ll inspect the diagnostic, patch the missing binding, and rerun the focused check."
    },
    {
      "role": "tools",
      "calls": [
        {
          "command": "zero explain NAM003",
          "output": "NAM003: unresolved name\nfix: introduce a binding or use an in-scope symbol"
        },
        {
          "command": "zero query --fn main",
          "output": "main\n  check world.out.write message"
        },
        {
          "command": "zero patch /tmp/introduce-message.patch",
          "output": "program graph patch ok"
        }
      ]
    }
  ]
}

Text And JSON Modes

Use text first:

zero check
zero explain NAM003

Use JSON when a tool needs exact spans, codes, fix ids, or nested readiness facts:

zero check --json
zero fix --plan --json
zero doctor --json

Agents should not default to JSON for every command. JSON is for automation, edit planning, CI, editors, and exact diagnostic fields.

Common Graph-First Diagnostics

BLD002 means a command expected graph-backed input but received a projection or another unsupported input. Import the projection or pass the package/graph store.

RGP003 means projection state is invalid, stale, conflicting, or impossible to verify. Use zero status, then choose zero export, zero import, or manual review.

GRF013 and related graph diagnostics mean the proposed graph edit would leave an invalid shape, such as a sparse ordered group.

CIMP003 and CIMP005 report unsafe or incomplete C import/link metadata. Use package-relative headers/libraries or configure target C dependency facts instead of relying on host paths.

Fix Plans

zero fix --plan --json returns a repair plan, not an automatic edit:

zero fix --plan --json

Use it when an agent needs a safer next step. The agent should still explain the patch it will apply and validate the user-visible behavior afterward.