---
id: SMH-PLAN-X6PZJ6M5
type: plan
title: "Smith-Owned JSON and Structured-Data Boundaries"
spec: SMH-SPEC-SPEC0001
status: approved
---

# Smith-Owned JSON and Structured-Data Boundaries

## Intent

Smith owns shared data contracts; serde_json remains an implementation detail at those boundaries.
Keep serde and serde_json; skip simd-json.
Do not build a replacement JSON parser or DOM.

## Entry

Generic JSON values cross tool, message, stream, schema, metadata, and provider-effect boundaries.
Some payloads have known shapes; others genuinely contain arbitrary structured data.
A type alias hides neither representation nor semantics.
A universal wrapper forwarding every DOM operation adds little value.

## Approval gate

Inventory current consumers before implementation.
Present required spec coverage and dependency-policy changes for explicit approval.
Current rules permit vocabulary types at public boundaries; this draft proposes a narrower Smith-owned contract, not an already-binding rule.
Do not edit specs, rules, or protected dependency files without approval.

## Order

1. Inventory production JSON seams and serde trait consumers.
   Separate typed domain records, arbitrary payloads, adapter-local documents, and test-only uses.
   Pin current wire behavior and secret-masking boundaries before refactoring.
2. Define the smallest shared structured-value access contract required by tools, validation, masking, and request encoding.
   Support borrowed access and fallible traversal without requiring an owned JSON tree or JSON text as storage.
   Keep parser and codec engine types private.
3. Replace known-shape generic records with typed domain data, starting with known session metadata and provider-effect records.
   Preserve extensible payloads where structure is genuinely plugin-defined.
4. Introduce semantic owners for tool arguments, tool schemas, and extension data only where they enforce a contract or centralize behavior.
   Share their underlying implementation; start owned storage with serde_json where appropriate.
   Keep ownership conversion explicit; avoid unrestricted mutable DOM access across boundaries.
5. Migrate shared message, stream, tool, and recording contracts to those types.
   Keep provider/RPC envelope parsing local; preserve arbitrary RPC payloads where required.
   Retain useful serde derives; remove unused impls only after checking consumers.
6. Exercise provider requests, fragmented tool arguments, tool validation, secret masking, RPC, eval JSON, catalog loading, and plugin JSON exchange.
   Review deterministic serialization and snapshots; run all applicable gates.

## Coordination

Borrowed CBOR reads must satisfy the same consumer-facing access contract without first constructing an owned JSON tree.
The CBOR plan owns decoding and encoding implementation; this plan owns shared semantics and access boundaries.
Neither plan promises a storage-layout performance gain without measurement.

## Verification

- Known records reject invalid shapes at their owning boundary.
- Tool arguments and schemas cannot be accidentally interchanged.
- Owned and borrowed representations expose equivalent values and destination encodings.
- Canonicalization and secret masking retain their properties across nested values.
- Numeric handling, object ordering, escaping, and malformed-input behavior remain explicit and tested.
- Existing user-visible JSON workflows remain compatible unless a separate change is approved.

## Execution evidence

### Streamed tool round

Tool JSON fragments become distinct `ToolArguments`; schemas become `ToolSchema`.
Message, stream, tool, provider-request, and recording contracts use those roles.
Provider/RPC document assembly remains adapter-local.
Shared validation consumes owned and validated borrowed CBOR views.
Borrowed argument validation and traversal allocate zero bytes; view/array-iterator/object-iterator sizes are 16/24/40 bytes on x86_64.
Existing mock-turn bound remains 47 allocations.

### Known metadata roundtrip

Compaction and tool-mutation producers serialize typed records, not ad hoc JSON trees.
Reserved metadata kinds reject malformed shapes on owned encode and borrowed decode.
Legacy compaction summaries without `complete` remain valid; extension metadata remains arbitrary structured data.
Successful borrowed validation of each reserved kind allocates zero bytes.
Tool-mutation/compaction records occupy 17/32 bytes on x86_64.
Invalid compaction fixtures were corrected without relaxing storage or allocation assertions.

### Proof

`cargo x check`: 471 tests pass; formatting, strict linting, docs and dependency-use checks pass.
`cargo x e2e`: 32 real-binary tests pass on final implementation.
`cargo x arch` passes.
Tool arguments cannot substitute for schemas: compile-fail doctest passes.
Scoped mutation run: 61 candidates, 47 caught, 10 missed, 4 unviable.
Owner-crate schema/depth tests catch meaningful misses; redundant duplicate-field guards were removed.
Follow-up iteration: 27 caught; final missing-field mutant caught after adding both one-field omissions.
No remaining meaningful miss in that scoped worklist; untested mutation scopes remain unclaimed.

### Closeout blockers

`cargo x audit` rejects yanked `yoke-derive 0.8.3`; dependency upgrade belongs in a separate deliberate change.
Pinned CI-image instruction budgets require deliberate re-pins despite lower measured counts.
Current deltas: masked 1000-message turn −5.94 %, nested canonicalization −10.03 %, mock eval startup −4.49 %.
No budget pins, dependency versions, commits or pushes changed in this execution.
Plan remains todo until all gates pass.

## Exit

Shared domain APIs express Smith-owned contracts rather than exposing serde_json storage choices.
Generic JSON remains only where payload structure is genuinely arbitrary or adapter-local.
Facade operations correspond to real consumers; no mirrored serde_json API, custom parser, or duplicated DOM implementation.
Serde remains supported; simd-json is absent from this work.
All gates pass.