wehub-resource-sync
e7738de6d2
CI / Deep Native Runtime Cases (1/6) (push) Has been skipped
CI / Native Preflight (push) Failing after 1s
CI / Native Runtime Cases (1/2) (push) Failing after 0s
CI / Native Runtime Cases (2/2) (push) Failing after 1s
CI / Native Metadata Reports (push) Failing after 0s
CI / Native Direct Backend Artifacts (push) Failing after 0s
CI / Native Sanitizer Smoke (push) Failing after 1s
CI / Command Contract Snapshots (push) Failing after 1s
CI / Deep Conformance Suite (push) Has been skipped
CI / Graph Build Perf (push) Failing after 1s
CI / Deep Native Preflight (push) Has been skipped
CI / Deep Native Runtime Cases (2/6) (push) Has been skipped
CI / Deep Native Runtime Cases (3/6) (push) Has been skipped
CI / Conformance Suite (push) Failing after 1s
CI / Workspace Checks (push) Failing after 0s
CI / Deep Native Runtime Cases (5/6) (push) Has been skipped
CI / Deep Native Runtime Cases (6/6) (push) Has been skipped
CI / Deep Native Runtime Cases (4/6) (push) Has been skipped
CI / Deep Graph Build Perf (push) Has been skipped
108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
## 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:
|
||
|
||
```text
|
||
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
|
||
|
||
```json-render
|
||
{
|
||
"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:
|
||
|
||
```sh
|
||
zero check
|
||
zero explain NAM003
|
||
```
|
||
|
||
Use JSON when a tool needs exact spans, codes, fix ids, or nested readiness
|
||
facts:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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.
|