Skip to content

Device binding contract: versioned range plan from onggi diff (ADR-0010) #75

Open

Description

@gspark-etri

Problem

onggi diff --ranges --json is already what a runtime consumes to update only the bytes that changed between two
variants (#46; rngd-pd resident delta). But the output has no schema name or version, the per-range class is implicit
(only the changed [offset, length] runs are listed, without saying whether a run is elsewhere in the base or new, or
where in the base its bytes lie), and nothing written down says what a runtime may assume or must do with it. Each
runtime integration therefore reads the output its own way.

In the design, only two parts are vendor-specific: the publisher-declared variant coordinate and the device
binding
that maps byte ranges to device memory. The binding needs one explicit, versioned contract.

Scope

  • ADR docs/adr/0010-device-binding-contract.md (status: proposed): the range plan of onggi diff --ranges --json is
    the only interface between onggi and a runtime; its fields (file, base file, offset, length, kind
    same/elsewhere/new, source offset in the base for elsewhere); the binding's obligations (map to whole device
    rows or request a full reload; verify; roll back).
  • Give the JSON output an explicit schema name/version and a per-range list with kinds, keeping the existing fields so
    current consumers keep working.

Out of scope: runtime code (rngd-pd), any vendor-specific mapping.

Done when

  • ADR-0010 merged as proposed
  • onggi diff --ranges --json carries schema and the typed range plan; old fields unchanged (test)
  • CI green

Activity

  1. gspark-etri commented on Oct 30, 2026

    @gspark-etri
    ContributorAuthor

    Scope expanded (user-approved): ADR-0010 becomes the device binding interface: five JSON operations (describe, resident, plan, apply, rollback), conformance levels B0/B1/B2, versioned schemas onggi.switchplan.v1 (= onggi diff --ranges --json), onggi.updateplan.v1, onggi.verification.v1, onggi.resident.v1 under docs/schemas/ with examples, and a conformance kit under conformance/binding/ (golden switch plans, stdlib-only reference fake binding, tests). Done when: ADR draft PR with schemas and kit, kit runs in CI, CI green. PR #76.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions