ADR-065: Canonical Context-Package Format (BYOC / Plugin-Packaged)

Status: v0.1 (filed 2026-06-06) — Architect-authored; companion to PDR-005 v1.0 §Open question 6; in-house material per Klatch-pause Evolution-section convention (HOST 2026-05-24). Three-fire bursty-lane drafted (Fire 1 skeleton + plugin-packaging framing; Fire 2 §Decision D1-D6 substantive content; Fire 3 polish + §Consequences refinement + v0.1 final).

Date: 2026-06-06

Authors: Chief Architect (Arch)

Reviewers: PPM (PDR-005 owner), Lead Dev (implementation lane), CIO (methodology), CEO (xian)


Status

Context

What problem does this ADR solve?

PDR-005 v1.0 (Bring Your Own Chat, ratified 2026-06-05) commits Piper Morgan to MCP server primary + thin bespoke UI distribution. The mechanism set #5 names “context-package format negotiated with sibling projects” as an architectural commitment. PDR-005 §Open question 6 routes the specific format decision to this ADR.

The concrete need: when Piper Morgan exposes its context state to a host (MCP client like Claude Desktop, ChatGPT, Slack) or a sibling project (Klatch, future systems), or when Piper Morgan consumes context state offered by an external surface, the shape of that interchange has to be canonical and stable enough that:

Why “plugin-packaged”?

PM clarified 2026-06-01 (via PA): the plugin is the canonical Anthropic-side packaging unit — config + CLAUDE.md + skills + MCP server. MCPB and hosted-MCP are NOT the packaging unit; they are deployment targets for the plugin’s MCP server component. The context-package format is what flows between the plugin’s MCP server and connected hosts/projects.

So Q6 has two layers:

  1. The context-package wire format — the actual bytes/JSON/whatever Piper Morgan emits or accepts at the MCP boundary
  2. The plugin-packaging context — how the format relates to the plugin’s other components (config, CLAUDE.md, skills, MCP server)

This ADR addresses both. Layer 1 is the load-bearing decision; layer 2 is how the format fits into the plugin’s distribution shape.

Klatch alignment context

Per Architect↔Daedalus alignment brief (Architect to Janus, 2026-05-15) the cross-project alignment question is: “What is the canonical context package?” The brief asked Klatch’s read on:

Klatch paused 2026-05-20 before Daedalus’s reply landed. This ADR proceeds with in-house material per the Pattern-064 Evolution-section convention HOST lifted (2026-05-24) as the general operating norm for uncertain external-alignment dependencies. Klatch refinements fold into §Evolution when alignment resumes; the ADR does not block on Klatch reply.

Format-decision space (from the Janus brief)

Four sub-decisions inside Q6:

Prior art / cross-references


Decision

The canonical context-package format is JSON-encoded, three-layer (envelope + body + extensions), with typed-enum capability primitives, ADR-063 READ-side error envelopes, Postel-ish forward compat, and plugin-config-declared format versions. Each sub-decision is grounded in either prior architectural commitments (PDR-005, ADR-061, ADR-063), prior cross-project alignment work (Janus brief 2026-05-15), or existing pattern catalog entries (Pattern-072, methodology-32).

D1: Wire format = JSON with explicit schema-version field

Decision: All context packages are JSON-encoded text with a mandatory top-level schema_version field (MAJOR.MINOR.PATCH SemVer-flavored).

Justification:

Alternatives considered:

Trade-off acknowledged: JSON’s representation limits mean binary primitives (images, audio, large blobs) live outside the format and are carried by reference (URI / content-addressable hash). This is captured under §Consequences/Negative.

D2: Three layers per package — envelope + body + extensions

Decision: Every context package is structurally a three-field JSON object:

{
  "envelope": {
    "schema_version": "1.0.0",
    "package_type": "capability_claim | context_slice | tool_call | tool_result | audit_event | error",
    "source": {
      "agent": "piper-morgan",
      "host_surface": "claude_desktop | chatgpt | slack_thread | bespoke_ui | sibling_project",
      "host_surface_version": "..."
    },
    "timestamp": "ISO-8601 UTC",
    "trace_id": "stable-cross-package correlation token"
  },
  "body": {
    /* package-type-specific payload */
  },
  "extensions": {
    "vendor": { /* host-or-project-specific opt-in */ },
    "experimental": { /* feature-flagged opt-in */ }
  }
}

Justification:

Composes with: ADR-063 audit envelope read-surface (audit_event package_type’s body shape IS the ADR-063 envelope); ADR-061 LLM-touch four-element principle (the envelope IS the audit-envelope element at LLM-touch boundaries).

D3: Capability-advertisement primitive = typed VERB enum + surface_type slot

Decision: When Piper Morgan advertises a capability (PDR-005 AC-1 host-aware capability map), the package body uses the verb-enum + slot shape established by the 2026-06-06 ADR-060 amendment ratification:

{
  "envelope": { "package_type": "capability_claim", ... },
  "body": {
    "verb": "tool.call | resource.read | prompt.complete | audit.read | surface.detect | ...",
    "surface_type": "claude_desktop | chatgpt | slack_thread | bespoke_ui | sibling_project",
    "claim": "available | conditionally_available | unavailable",
    "conditions": { /* per-host predicates, e.g. requires_user_consent: true */ }
  }
}

Justification — three reasons this shape is right:

  1. Conditional-claim-per-host (EC-2 architectural input, 2026-06-03 PPM synthesis) — capabilities are NOT universally claimed; the format carries the per-host context the receiver evaluates. claim: conditionally_available + conditions lets the receiver decide whether the capability applies in its environment.
  2. Verb-source-slot per Pattern-072 — the 6th Pattern-072 application (after task_type, safe_surface, probe registry, IndexDeclaration, PrivacyLevel, [now confirmed as 6th] action VERB enum). Capability primitive becomes the 7th Pattern-072 application: typed enum of verbs + documented consumers (the receiving hosts) + register-time validation + default policy (capability-unknown → unavailable, the safe fallback per ADR-060 floor-first).
  3. Layer-then-migrate inherits naturally — the same supersede-vs-layer ruling I issued on ADR-060 today applies if BYOC ever absorbs an existing capability registry. The verb enum becomes source-of-truth for the verb dimension; legacy registrations migrate progressively.

Crucially NOT: capability is NOT a verb-object name collapsed string (tool_call_for_github_issue). That’s the #1158 failure mode this ADR + ADR-060 amendment are designed to prevent. One name collapsed, two slots separated.

D4: Error envelope = ADR-063 READ-side four-element principle extended cross-host

Decision: Error packages (envelope.package_type == "error") use a body shape that adapts ADR-063’s user-facing audit envelope READ-surface to cross-host error surfacing. The four READ-side elements:

{
  "envelope": { "package_type": "error", ... },
  "body": {
    /* Element 1: User-visible field set */
    "error_code": "ENVELOPE_MALFORMED | CAPABILITY_UNAVAILABLE | TOOL_FAILED | RATE_LIMITED | AUTH_REQUIRED | ...",
    "human_message": "Short human-readable description suitable for surfacing to the user",
    "retry_hint": "transient | needs_user_action | permanent",

    /* Element 2: Schema-validated at consumption — receiver verifies error envelope conforms to schema_version */

    /* Element 3: Safe-fallback — if envelope is malformed, receiver treats as error_code: ENVELOPE_MALFORMED instead of crashing */

    /* Element 4: JWT-bound access control */
    "audit_visible": true,
    "diagnostic": {
      /* Only populated/sent to receivers with matching JWT scope — full trace_id chain, stack snippet, internal IDs */
    }
  }
}

Justification — three reasons:

  1. Composes with #1017’s audit_envelope hash strategy — the error envelope shape IS a generalization. The audit case has a specific JWT scope and a specific diagnostic shape; the error case extends to all package types but keeps the four-element discipline.
  2. No silent failure cross-host — without a canonical error envelope, every host invents its own error shape; receivers can’t disambiguate “this tool doesn’t exist” from “this tool exists but isn’t available in your host” from “this tool failed transiently.” error_code + retry_hint separate those clearly.
  3. JWT-bound diagnostic visibility — same ADR-063 discipline. The user sees human_message + error_code + retry_hint; the auditor with the right JWT scope sees diagnostic.* too. Cross-host the JWT-binding has to be host-aware; receivers without the scope filter out diagnostic before surfacing.

Open question 5 resolution: Yes, the #1017 audit_envelope hash strategy carries over — the error envelope is the read-surface; the audit envelope is the write-surface with same JWT discipline. Confirmed.

D5: Versioning = SemVer-flavored + Postel-ish forward compat

Decision: schema_version follows MAJOR.MINOR.PATCH SemVer convention with per-axis producer/consumer rules:

Axis Producer must Consumer must
MAJOR Bump on breaking changes (field removal, type change, required→optional flip on input side) Reject same-MAJOR mismatch with ENVELOPE_MALFORMED error envelope
MINOR Bump on additive changes (new optional fields, new enum values where unknown→default semantics hold) Accept ANY same-MAJOR version; unknown fields outside extensions.* log a warning but do NOT break
PATCH Bump on bug fixes (no schema change) Accept silently
extensions.* Add freely under namespace; never break compat Silently ignore unknown namespaces

Justification — methodology-32 Postel discipline applied:

Trade-off acknowledged: Schema-version coordination across plugin deploys creates a small operational cost (the plugin’s config must declare format_versions_emitted + format_versions_accepted; doc-sync-sweep catches drift). This is captured under §Consequences/Negative.

D6: Plugin packaging — context-package format declared in config; source-of-truth is the schema spec file

Decision: The plugin (config + CLAUDE.md + skills + MCP server per PM’s 2026-06-01 clarification) carries the context-package format declaration in config, but the source-of-truth is a separate schema spec file referenced by both config and the MCP server implementation.

# plugin/config (excerpt)
context_package_format:
  spec: "schemas/context-package-1.0.0.json"   # source of truth
  versions_emitted: ["1.0.0"]
  versions_accepted: ["1.0.0", "0.9.x"]        # backward compat range
  extensions_namespace: "vendor.piper-morgan"
<!-- plugin/CLAUDE.md (excerpt) -->
## Context Package Format

This plugin emits and accepts context packages per ADR-065
(`docs/internal/architecture/adrs/adr-065-canonical-context-package-format.md`).
The canonical schema is at `plugin/schemas/context-package-1.0.0.json`.
See ADR-065 §Decision D2 for envelope/body/extensions structure.
# plugin/mcp_server/serializer.py (excerpt)
SCHEMA_SPEC_PATH = "schemas/context-package-1.0.0.json"  # MUST match config

Justification — Pattern-073 drift discipline:

Open question 3 resolution: spec file is source of truth; config declares versions; MCP server implements; CLAUDE.md describes by reference; skills reference by name. Doc-sync-sweep catches drift. Confirmed.


Consequences

Positive

Negative / Tradeoffs

Non-consequences


Evolution

(Empty at v0.1 filing. Klatch-pause framing per Pattern-064 convention: when Klatch resumes and Daedalus relays refinements via Janus, fold into this section as dated entry.)


Open questions (v0.1)

  1. Specific JSON schema — concrete context-package-1.0.0.json schema file to be drafted as a follow-up artifact; this ADR specifies the structure (D1-D6); Lead Dev review at schema draft.
  2. Klatch L1-L5 mapping — pending Klatch resumption; if/when Daedalus relays the layer-model alignment, folds into §Evolution per Pattern-064 convention.
  3. Plugin vs MCP-server separation of concerns for format declaration — RESOLVED in D6: spec file is the source of truth; config declares versions; MCP server implements against the spec; CLAUDE.md describes by reference; skills reference by name. Doc-sync-sweep catches drift (Pattern-073 layer).
  4. Capability-advertisement registry name + Pattern-072 application count — RESOLVED: this is Pattern-072’s 7th application (after the 6th confirmed by 2026-06-06 ADR-060 amendment ratification: VERB enum). Capability primitive becomes the 7th: typed enum + documented consumers + register-time validation + default policy. Flagging to CIO for catalog awareness (non-gating) at the cron-shape findings memo (~Jun 13).
  5. Error envelope cross-host semantics — does the #1017 audit_envelope hash strategy carry over? — RESOLVED in D4: Yes. Error envelope is the read-surface; audit envelope is the write-surface with the same JWT-binding discipline. Cross-host the JWT scope filters diagnostic.* from human_message + error_code + retry_hint.
  6. (NEW) Wire-transport binding — current binding is MCP stdio; if/when WebSocket or HTTP bindings are added (BYOC second wave), does the format need transport-specific framing? Lean: no, JSON-encoded text is transport-agnostic; framing is the transport’s concern. Confirm at Q7 (ADR-066) packaging-layer abstraction. Cross-reference noted.
  7. (NEW) Schema spec file location + versioning — should the schema spec live in the plugin repo (per D6) or in a separate cross-project schema repo (sibling-shaped with Klatch’s potential spec)? Lean: plugin repo for v1.0; reconsider at v2.0 if cross-project alignment makes a shared repo attractive. Filed as forward-look.

What this ADR is NOT