[gspark-etri]

Background

For onggi to work with any accelerator, the runtime side needs one public, versioned interface. In the design only
two parts are vendor-specific: the publisher-declared variant coordinate and the runtime's device binding, which
maps byte ranges to device memory. onggi diff --ranges --json was already what runtime experiments read (#46,
rngd-pd resident delta), but it had no schema or version, did not say which runs the base holds elsewhere or where,
and no document said what a runtime may assume or must guarantee.

Changes

• docs/adr/0010-device-binding-contract.md (status proposed), "Device binding interface":
  • five operations, JSON in and out, process-boundary friendly (BINDING <op>, stdin/stdout): describe(artifact) -> onggi.profile.v1, resident() -> onggi.resident.v1, plan(switchplan) -> updateplan | reload (pure),
    apply(updateplan, target) -> verification (staged, drained boundary, per-unit digests), rollback();
  • what onggi guarantees and what a binding must do (plan purely, map or refuse, read verified bytes, stage/drain/
    verify, roll back, public vendor APIs only, ADR-0009);
  • conformance levels B0 (no binding: files only), B1 (describe + resident + plan that always reloads),
    B2 (all five: resident row-level updates) and what onggi does at each.
• docs/schemas/: JSON Schema 2020-12 for onggi.switchplan.v1, onggi.updateplan.v1,
  onggi.verification.v1, onggi.resident.v1, with examples (onggi.profile.v1 is feat: select and prepare artifacts by exact compatibility profile #71/Integrate verified delta comparison and compatible artifact preparation #72's store.Profile).
• pkg/store/diff.go: the diff JSON carries schema: "onggi.switchplan.v1", base_manifest, manifest; with
  --ranges each file gains ranges[] = {offset, length, kind: same|elsewhere|new, source_file, source_offset}
  covering the file in order. All earlier fields unchanged.
• conformance/binding/ (Python 3.6+, stdlib, Apache-2.0): golden switch plans for four synthetic switches
  (identical, in place, shifted by 17,952 B, rearranged), their byte generator, a reference fake binding on a
  simulated device of 4 KiB rows, and conformance.py (plan purity, refusal for a non-resident base, coverage of
  every changed byte, apply digests = target, identity after apply, rollback digests = base, B1 always reloads).
• CI: runs the kit against the fake binding at B2 and B1.

Verification

• TestRangePlan: runs cover each file in order, sums equal same/moved/new, every same run equals the base at
  that offset, every elsewhere run equals the base bytes at its source; without --ranges the plan is absent.
• TestGoldenSwitchPlans: onggi diff --ranges --json output equals the checked-in golden plans (manifest digests
  aside, which carry creation times).
• python3 conformance/binding/conformance.py (B2) and --level B1: 0 failed locally.
• All examples and golden plans validate against the schemas (jsonschema 2020-12, command in docs/schemas/README.md).
• go test -race ./..., go vet ./..., gofmt -l . clean locally (Go 1.24.13 in golang:1.24-bookworm).
• Real-data plan on the ATOM B2 → B8 and B2 → prefill switches: posted as a comment once measured.

Compatibility and limits

• JSON only gains fields; changed and all summary fields keep their meaning; text output unchanged. The current
  rngd-pd consumer keeps working; it can move to schema + files[].ranges (Codex owns rngd-pd).
• Expected rebase conflicts: PR Reuse target metadata plan to speed up live delta comparison #70 and Integrate verified delta comparison and compatible artifact preparation #72 also edit pkg/store/diff.go (reuse of the target plan around
  ne/nodes); mechanical. Integrate verified delta comparison and compatible artifact preparation #72 defines onggi.profile.v1, which this ADR references unchanged.
• onggi does not invoke bindings yet; a node agent calling resident/plan/apply is follow-up work.
• The kit checks the contract, not timing or draining, which belong to each runtime's own tests.

Related Issue

Closes #75

🤖 Generated with Claude Code

[gspark-etri]

Real-data check of onggi.switchplan.v1 (binary from this branch at 2d84ac3, lab node, ATOM Llama-3.1-8B build set, stores created with the default policy of that binary):

switch	same	elsewhere	new	ranges	plan JSON	onggi diff --ranges --json wall / RSS
decode B2_lm → B8_lm (15.2 GB)	15.01 GB (2 runs)	0	218.2 MB (3 runs)	5	1.4 KB	—
decode B2 → B8_lm	0	13.96 GB (82 runs)	1.27 GB (7 runs)	89	17.7 KB	11.1 s / 2.1 GB
decode B2 → prefill C128 (14.0 GB)	0	11.13 GB (226,894 runs)	2.89 GB (226,845 runs)	453,739	68.2 MB	11.0 s / 2.0 GB

The decode switch is the expected binding case: two same runs and three new runs, the largest 218 MB at the end. Decode → prefill, rearranged in short runs, produces ~454k runs and a 68 MB plan. A binding answers reload there, as ADR-0010 expects, and the plan is printed only with --ranges. Raw summaries are in onggi#78's docs/data/sub-chunk-policy-20261030.json (switch_plans).