RFC 011: Reconcile Run additionalProperties with extensionPolicy

[brettin]

Summary

Adds RFC 011, which requests resolving the contradiction between run.schema.json (additionalProperties: false) and core-v3 extensionPolicy (x-gmp-* allowed). Options: permit x-gmp-* via patternProperties (recommended) or formalize a sibling-result endpoint with optional resultRef. Disposition: Issue (maintainer call).

RFC document

Full text of contracts/rfcs/011-run-document-extensibility.md (also in this PR's Files tab):

# RFC 011: Reconcile `Run` `additionalProperties: false` with `extensionPolicy`

**Gap IDs:** `provisional-gap-002` (provisional — replace before opening upstream)

## Problem

core-v3 documents two contradictory rules for `Run`:

- [`run.schema.json`](../schemas/common/run.schema.json) sets
  `additionalProperties: false` on the top-level `Run` document.
- [`core-v3.json` `extensionPolicy`](../profiles/core-v3.json) explicitly permits
  implementations to carry their own data via `x-gmp-*` field-name prefixes.

In practice, the strict schema wins for wire conformance: any implementation
that puts an `x-gmp-foo` key directly on a Run fails JSON-Schema validation
against `run.schema.json`. Implementers face three unattractive choices:

1. **Drop the strict schema check.** Skip `additionalProperties: false` validation
   in the conformance harness — defeats the point of the schema.
2. **Move per-implementation domain payload off the Run document entirely.**
   Standard workaround today: per-implementation data lives on a sibling
   endpoint (e.g., `GET /v3/runs/{runId}/result`) with an out-of-band pointer
   field. Works, but every consumer of "the full Run picture" now does two
   round-trips, and Run + payload joins are awkward in audit queries.
3. **Vendor-extend the schema locally.** Fork `run.schema.json`, relax
   `additionalProperties` to `true` for the local conformance run. Diverges
   every implementer.

The contradiction also undermines `extensionPolicy` itself: if the canonical
document carrying the most extension-worthy data (per-implementation domain
payload) can't actually use `x-gmp-*`, the policy's stated permission is empty
in the most important case.

The same contradiction recurs on event payload schemas (`tool-call-event`,
`policy-check-event`, `reasoning-node-event`, `classification-shift-event`).
This RFC picks the precedent on `Run`; downstream RFCs (including our
[RFC 012](012-tool-call-extensibility.md)) follow the same shape once the `Run`
case is settled.

## Proposal

Two options are presented. Either resolves the contradiction. Option A is
recommended for ergonomic and policy-consistency reasons; Option B is the
strict-schema-preserving alternative.

### Option A — Permit `x-gmp-*` on `Run`

Change `run.schema.json`:

```diff
 {
   "type": "object",
   "additionalProperties": false,
   "properties": { ... }
+  ,
+  "patternProperties": {
+    "^x-gmp-": { "type": ["object", "string", "number", "boolean", "array", "null"] }
+  }
 }

Semantics

• Required and optional fields are unchanged.
• Implementations MAY add x-gmp-<name> keys for per-deployment data.
• Conformance validation continues to forbid arbitrary keys; only
  x-gmp-*-prefixed keys are admitted.

Backward-compatible — no existing Run document is invalidated.

Option B — Formalize the sibling-payload pattern

Keep run.schema.json strict. Add a normative section to
v3-design-notes.md codifying:

• Per-implementation domain payload MUST live at GET /v3/runs/{runId}/result
  or under /v3/experimental/<capability>/{runId} per extensionPolicy.
• The result endpoint's shape is governed by the implementation's
  Capability.artifact ref (an existing field on
  capability.schema.json).
• A new optional Run field resultRef: string (URI) names the canonical
  location of the per-implementation payload, so a single Run fetch reveals
  where to go next.

Backward-compatible — resultRef is optional and additive.

Recommendation

Option A. Rationale:

• extensionPolicy already promises the surface; Option A makes the promise
  real.
• The sibling-endpoint pattern is a workaround for the contradiction, not a
  feature worth canonizing. Adopting it spec-wide encourages proliferation of
  /v3/runs/{runId}/<thing> endpoints per implementation.
• Option A is a one-block schema change; Option B is documentation plus
  operational discipline that every implementer has to re-learn.

Both options resolve the contradiction; either is acceptable.

Deferred (out of scope for this RFC)

• Same contradiction on event payloads.
  tool-call-event.schema.json, policy-check-event.schema.json, and others
  have the same additionalProperties: false vs. extensionPolicy conflict.
  RFC 012 addresses tool.call specifically
  (the most pressing case for accounting telemetry); a general sweep covering
  all event payloads should follow once the Run precedent is set.
• x-gmp-* key naming rules. Collision avoidance across deployments,
  whether a deployment-id prefix is required, JSON Pointer reservation. Worth
  its own RFC if Option A is picked.
• OpenAPI surface implications. Auto-generated clients may strip unknown
  fields silently; documenting the round-trip-preservation contract for
  x-gmp-* is a follow-up.

Platform v0 alignment (out of scope)

Item	Current drift	Target
Per-implementation Run payload	Vendor-extended schema or sibling endpoint	Option A: native x-gmp-* key under strict schema
Conformance harness	Often skips additionalProperties: false on Run	Validate strictly; x-gmp-* admitted via patternProperties
Sibling result endpoint	Implementer-defined (e.g., /v3/runs/{runId}/result)	Optional under Option A; canonical under Option B with Run.resultRef

Platform reference

ARIAPlatform platform-v0-implementation-profile.json
— Run, extensionPolicy. The platform profile today documents the
sibling-endpoint pattern as a workaround; this RFC formalizes one direction or
the other so implementers stop diverging on the workaround shape.

## Test plan

- [ ] Review proposed contract change against cited schemas/profiles
- [ ] Confirm disposition (Ship / Issue / Hold) and whether to proceed to an impl PR
- [ ] Approve or request changes on this RFC PR (do not merge until implementation decision is clear)


Made with [Cursor](https://cursor.com)