ABI Evolution Policy

This policy governs externally visible capOS ABIs:

• Cap’n Proto schema in schema/capos.capnp.
• Generated schema bindings checked by make generated-code-check.
• Ring and bootstrap ABI constants and layouts in capos-config/src/ring.rs, capos-config/src/capset.rs, and capos-abi/src/lib.rs.
• Debug/log formats only when a document explicitly declares them stable.

The current project is still a research tree, not a released platform with a public compatibility promise. Even so, schema and ring changes must follow this policy before external clients, host tools, or out-of-tree runtimes depend on them.

Design Grounding

This policy is grounded in current capOS docs and the checked-in prior-art notes that apply to schema and transport evolution:

• docs/architecture/capability-ring.md for the implemented process-wide ring, fixed 64-byte CapSqe, fixed 32-byte CapCqe, opcode boundary, and current completion semantics.
• docs/proposals/ring-v2-smp-proposal.md for the undecided future per-thread-ring version-negotiation shape.
• docs/proposals/error-handling-proposal.md for the transport/application error split and unsupported-operation behavior.
• docs/trusted-build-inputs.md for generated-code drift checks and pinned Cap’n Proto tooling.
• docs/design-risks-register.md for the prior open ABI compatibility and Ring v2 compatibility questions.
• docs/research/capnp-error-handling.md for Cap’n Proto exception and schema error-model precedent. Other files in docs/research/ were listed during review; no OS scheduling, filesystem, networking, or hardware prior-art file directly changes this schema/ring ABI policy.

Compatibility Classes

Every ABI change must name one class in its task, review, or commit message.

Cap’n Proto Schema Rules

Schema interface IDs, method ordinals, struct field ordinals, enum discriminants, union tags, and named constants are stable once checked in.

Allowed compatible changes:

• Add a new field with a new ordinal and a default value that old readers can safely ignore.
• Add a new method with a new ordinal when old clients do not need it.
• Add a new result union arm only when old clients already treat unknown or unsupported domain outcomes as a controlled failure.
• Add a new interface or struct with a fresh ID/name.
• Add documentation that narrows previously undocumented behavior without changing wire compatibility.

Disallowed without a breaking-change plan:

• Reuse a removed field, method, enum, or union ordinal.
• Change the meaning, type, units, authority, or lifetime of an existing field.
• Rename a schema item when generated code or logs expose the old name as a public integration surface.
• Make an optional/defaulted field mandatory for existing callers without a versioned fallback.
• Replace a schema result union with a transport error or vice versa without an error-layer migration note.

Removed schema space stays reserved. If a field or method is retired, leave a comment at the old ordinal explaining why it is reserved and where the replacement lives.

Ring ABI Rules

The ring ABI is a fixed-layout shared-memory contract. CapSqe, CapCqe, ring header fields, opcodes, flags, transfer descriptor layout, CQE result codes, and fixed virtual addresses are kernel/userspace ABI.

Rules for the current process-wide ring:

• Do not change the size, alignment, byte order, or meaning of an existing ring struct field without a breaking-change plan.
• Preserve objective layout checks for current ABI structs. At minimum, capos-config/src/ring.rs must keep compile-time checks for CapSqe, CapCqe, CapTransferDescriptor, endpoint caller-session metadata, endpoint message headers, and ring capture records. Any new negotiated ring layout must add equivalent checked constants for SQE size, CQE size, transfer descriptor size, ring header offsets, SQE/CQE array offsets, and feature/version fields.
• Do not change SQE_ARRAY_OFFSET, CQE_ARRAY_OFFSET, SQ_ENTRIES, CQ_ENTRIES, RING_VADDR, or fixed SQE/CQE sizes by arithmetic side effect. A change to any of those values is a layout change and must name its compatibility class.
• Reserved SQE fields must be rejected unless the opcode explicitly defines them. New meanings for reserved fields require hostile tests that old kernels fail closed.
• New opcodes must start as reserved or unsupported. A reserved opcode should return CAP_ERR_UNSUPPORTED_OPCODE; malformed non-reserved opcodes should return CAP_ERR_INVALID_REQUEST.
• New flags must specify whether old kernels reject them, ignore them, or treat them as malformed. Silent ignore is allowed only for flags that cannot carry authority or resource effects.
• New negative CQE result codes must be appended as new constants. Existing negative result codes cannot be renumbered or repurposed.
• Capability transfer descriptors must continue to reject unknown reserved bits until a documented transfer mode consumes them.

Ring v2 or per-thread-ring work must declare whether it is:

• a negotiated compatible extension to the current ring page;
• a new ring layout selected by boot/runtime version negotiation; or
• an intentional ABI break.

That decision belongs in the Ring v2 proposal/backlog before implementation.

Version Negotiation

When an ABI cannot be evolved by compatible addition, introduce an explicit version gate instead of inferring compatibility from struct size or accidental behavior.

Acceptable gates include:

• manifest or boot-package schemaVersion fields;
• a future runtime boot-info field that names ring layout and feature bits;
• interface methods that return a structured unsupported-version result;
• manifest/tooling checks that reject unsupported data versions before boot.

Unsupported versions must fail closed with a stable, documented error. A client must not need to parse debug text to distinguish “unsupported version” from “malformed input”.

Deprecation Window

Before external consumers exist, a deprecation may be removed after the replacement path, docs, and smokes land in main.

After external consumers are declared for an ABI, deprecated schema or ring surfaces must remain for at least one full selected milestone after the replacement is documented and tested. Removing them earlier is a breaking change and must be called out as such.

Deprecation notes must name:

• the old field, method, opcode, flag, or constant;
• the replacement;
• the last proof target that still exercises the old shape;
• the planned removal condition.

Review Gates

Schema or ring ABI changes must include the relevant checks:

• make generated-code-check for schema/capos.capnp changes.
• cargo test-config for manifest/schema validation changes.
• cargo test-ring-loom for ring queue protocol changes.
• Compile-time layout assertions and host tests for ring struct size, alignment, offsets, entry counts, and fixed virtual addresses when a ring layout changes.
• cargo test-lib for CapTable/capability transfer semantics.
• A focused QEMU smoke when a userspace-visible behavior changes.
• make docs for policy or manual changes.

Reviewers should reject ABI changes that lack a compatibility class, migration notes for breaking behavior, or an unsupported-version/error story for new version gates.

Current Open ABI Decisions

• Ring v2 backward compatibility remains undecided. Until it is decided, do not claim per-thread rings are compatible with the current process-wide ring.
• Production release reproducibility remains separate from ABI compatibility. Final ISO, manifest, and embedded ELF checksums are tracked in docs/trusted-build-inputs.md and REVIEW_FINDINGS.md.