Schema Rules and Open Questions

Fields live in owner docs; this doc fixes how they may evolve.

Schema Evolution and Field Grammar

Postel’s Law, asymmetric:

• Requests: unknown fields inside a known schema are preserved verbatim. Unknown top-level fields are rejected. An undeclared sidecar_schema or crypto_suite_id is rejected outright.
• Responses: unknown fields are preserved verbatim, so a newer server never breaks an older client.
• Bounded sizes: every field has a schema-declared maximum; oversize is rejected.

Closed Enums

Every enum in a signed or validated structure is closed per protocol_version: an unknown value is a structural error, never a future value to ignore. Adding a value requires a new protocol_version (album pinning). Enforced by both server (invariant 16) and client decode (Validation). Value sets live in their owner docs (actions, metadata enums, derivatives, stacks).

Timestamp Grammar

timestamp/ts fields are RFC 3339, self-asserted and audit-only — never used for authorization or ordering (Write Authorization). The server records its own received_at for time-based policy. A write-only drift bound (default ±30 days) surfaces broken clocks; not a security control.

Forbidden Client Behaviors

Index of negated owner-doc rules; receivers reject the consequence structurally regardless.

A correct client never…	Owner
Re-signs under a lower crypto_suite_id	Primitives
Signs for an epoch whose write-tier key it lacks	Keys
Removes an OR-set add_id it never observed	Metadata
Strips _unknown or superseded_captions on write-back	Metadata
Overwrites or truncates a provenance chain	Provenance
Sends revoke_all_sessions without master-key proof	Authentication
Decodes non-home-peer bytes outside the sandbox	Clients
Promotes an AI tag to a user tag except by a signed op	Metadata
Retries 429/409/426 with the same payload	Validation

Min-Supported-Client Deprecation Policy

1. Announce at /.well-known/capsule/deprecation at least the announcement window (default 90 days) before cutoff, naming the date and the minimum surviving protocol_version.
2. Warn: until cutoff, responses carry X-Capsule-Min-Client-Build and a Warning: header.
3. Cut off: the version leaves [Min, Max]; its writes get 426, reads still succeed.
4. No stranded data: every recovery path still works; only the old binary is stranded.

Never retroactive: albums pinned to a dropped version stay readable forever, just not writable.

Open Questions

• Cross-server album replication (deferred to v2). v1 pins each album to one home server; the interim answer is the aggregated album.