Define the PMM readiness contract consumed by pjson objects

[netkeep80]

Parent: #399
Depends on: #404, #410, #415, #416, #426
Related: #418, #419, #422, #428
Consumer: netkeep80/pjson#34

Problem

pjson object storage is intentionally waiting on PMM rather than building a private workaround. The dependency is distributed across several PMM issues: relocation-safe pmap, relocation-safe forest registry, binary-safe pstringview keys, an executable pmap<K,V> lifetime restriction, and collision-safe persistent type identity for typed handles.

Without one explicit readiness contract, the upper layer can start against a subset of these guarantees and accidentally encode temporary compatibility storage that becomes permanent architecture.

Goal

Define a narrow PMM→pjson handoff contract for persistent JSON object keys/values. This issue does not implement JSON semantics; it proves that the storage primitives required by pjson#34 are stable enough to consume directly.

Required PMM guarantees

Object container

• canonical pmap<K,V> mutation survives whole-arena relocation;
• K/V supported lifetime class is compile-time explicit (Define and enforce pmap key/value object-lifetime contract #415);
• persistent handles used by pjson fit that supported class;
• insert/find/erase/clear preserve forest/tree invariants.

Persistent type identity

• semantically distinct pptr<T> representations cannot silently alias one pmap forest domain because their size/traits happen to match (Make pmap persistent type identity collision-safe for typed handles #426);
• the identity used by pmap is stable across supported compilers and reloads and does not depend on RTTI, compiler-specific type strings or process addresses;
• the exact pjson-shaped value handle (pptr<pjson::node_payload<Manager>> at the consumer boundary) can be represented by an explicit stable pointee identity rather than a pjson-only map registry;
• existing primitive/scalar pmap domain identity remains compatible unless an explicit migration is proven necessary.

Object keys

• pstringview identity is (length, bytes), not C-string termination (Make pstringview interning length-aware and embedded-NUL safe #416);
• embedded NUL is preserved and distinct;
• persistence/reload preserves exact key bytes;
• the persistent node representation is not mixed with transient constructor/conversion state;
• no second JSON-only intern table is required.

Registry / bootstrap

• forest registry/domain operations are relocation-safe (Compaction: eliminate forest_domain_mixin.inc and fix registry relocation lifetimes #410);
• legacy .inc implementation is gone;
• system/domain symbols retain existing semantics.

Pointer lifetime

• pjson may retain persistent handles/offset identities across PMM calls;
• pjson must re-resolve raw views after any call that may allocate/remap;
• PMM documentation gives enough information to audit this rule (Docs: define resolved-pointer lifetime across arena relocation #408).

Failure behavior

• document the mutation failure guarantee required by the first pjson object implementation; link Define failure-atomic semantics for relocation-capable mutations #419 rather than silently assuming transactions.

Conformance test

Add a PMM-level consumer-shaped test using the same representation shape intended by pjson#34: persistent pstringview key handle plus a distinct tagged persistent value-handle pointee that mirrors pjson's node_payload boundary without importing pjson.

The test must cover:

• insertion of ordinary UTF-8 key;
• insertion of embedded-NUL key distinct from its prefix;
• lookup after forced arena relocation;
• two semantically distinct typed-handle pmap specializations remain in distinct forest domains;
• erase and reinsert;
• save/load or equivalent persistence round-trip reproduces the same domain identity;
• verify().ok throughout.

Do not import pjson into PMM; mirror only the minimal representation boundary so dependency direction remains PMM → pjson.

Documentation closure

• Docs: define pmap persistent key/value representation contract #422 documents the landed pmap K/V lifetime/representation contract.
• Docs: define binary-safe pstringview node and interning API #428 documents the landed binary-safe pstringview node/interner API.
• The conformance test and this issue must agree with those canonical docs; do not create a pjson-specific exception.

Non-goals

• JSON parsing/serialization;
• RFC6901 escaping semantics;
• $ref behavior;
• pjson compatibility adapters;
• adding a second PMM map/string/type registry implementation.

Acceptance criteria

• all blocking PMM issues are closed with green gates;
• the consumer-shaped conformance test is green on the full compiler/sanitizer matrix;
• the exact key/value types, stable type identity and lifetime rules intended for pjson#34 are documented in this issue or existing API docs;
• pjson#34 can begin without adding a storage/lifetime/type-identity workaround beneath its JSON semantics.

[netkeep80]

Readiness contract amendment: #426 is now a required pre-handoff gate for the exact pjson-shaped pmap<pptr<...>, pptr/handle...> representation. #415 proves raw-storage object lifetime, #416 proves (length, bytes) key semantics, and #426 separately proves that semantically distinct typed handles cannot alias the same forest domain merely because their structural fingerprints match. Keep these concerns separate; do not solve #426 with a pjson-only domain/tag workaround.