Registry contracts¶

New snapshots definitions, validates identifiers and handlers, checks budgets and compiles schemas before returning. Operation names match [A-Za-z0-9_.-]{1,128} and are case-sensitive. Names must be unique and summaries nonblank UTF-8. There is no runtime registration or global catalogue. Handlers may hold application state; hosts own its concurrency.

Policy and discovery¶

Both policy callbacks are required. Authorize receives Discover for search/inspection and Execute with detached, validated arguments for invocation. Return a typed FailureUnavailable for a denial. Other callback failures and panics fail the request; they never produce successful authorization or a successful empty catalogue. Unknown errors are sanitized, and private causes remain available to the host. Unknown and undiscoverable names use the same safe unavailable response.

ScopeKey must return a nonempty opaque principal/authorization-revision key without credentials. Search and invocation require it. The host must change it when the effective authorization scope changes. Each page still rechecks discovery policy; no filtered-page cache is shared between callers. Callbacks must honor context and support concurrent calls.

Search defaults to five summaries, allows at most twenty, and accepts at most 256 UTF-8 bytes each for query and group. An exact authorized identifier resolves directly. Otherwise, all query terms must match case-insensitively across indexed names, groups, summaries, descriptions, examples or source text. Name matches outrank group matches, then summary matches, then other documentation; ties use case-sensitive name order. An empty query browses names. Group filtering ignores case. Schemas are excluded from the index and pages. Full schemas appear through Inspect.

Pages fit a 16 KiB JSON budget, with a small conservative envelope/cursor reserve. An item that cannot fit an empty page fails explicitly. Larger selections use complete summaries and a cursor; no summary is truncated or silently skipped. Cursors expire after ten minutes and are encrypted/authenticated with a per-registry random key. They bind method, registry revision, whitespace-normalized query, normalized group, position and host scope. Query casing remains significant for cursor binding because exact identifiers are case-sensitive. Altered, expired or mismatched cursors fail rather than restarting. Page size may change on continuation. Permission changes do not turn paging into a transactional snapshot.

Schema and numeric profile¶

The private compiler is jsonschema/v6 v6.0.3. Draft 2020-12 is the default; explicit draft-07 is also supported. Other declared dialects fail, including declarations inside schema resources. Input schema documents must be objects; a declared top-level type must be object. The gateway independently requires object arguments. Output schemas can describe any JSON value. Internal $ref targets and bundled $id resources are supported. File/network loading and custom external metaschemas are disabled. Defaults remain annotations. Format behavior follows the selected compiler dialect: draft-07 asserts known formats; 2020-12 leaves them annotations unless its vocabulary requires assertions. Content decoding is disabled.

Duplicate decoded object member names fail at JSON entry points. Canonical arguments sort keys, remove insignificant whitespace and normalize numbers using decimal coefficient/exponent arithmetic. 1, 1.0 and 1e0 compare identically; negative zero becomes zero. Strings and array order retain their meaning. No float64 conversion or default insertion occurs.

Before compiler validation, nonzero numbers use a fixed work profile: absolute written exponent and decimal adjustment are each at most 4,096, and normalized coefficient digits plus absolute normalized exponent total at most 4,096. Zero normalizes directly without expanding its exponent. Out-of-profile schemas fail construction; arguments fail with invalid_arguments; schema-validated output fails with invalid_result. This avoids a reproduced upstream panic for 1e1000000000 under a numeric minimum and bounds big-rational conversion work. It is a module validation limit, not a JSON syntax restriction or a float64 precision limit. Standalone owned-value constructors still accept structurally valid JSON. Schema length/item/property count constraints must also fit 0–2,147,483,647; the compiler otherwise narrows them to a native integer. Startup rejects overflowing counts instead of silently weakening constraints. This fixed ceiling is portable across Go architectures and does not limit ordinary numeric instance values to 32 bits.

Limits and result validation¶

WithLimits uses zero fields for defaults and rejects negatives or repeated limit options. Raising one field does not raise a related budget. Current operation limits are:

Ordinary text, structured JSON, links and metadata count toward encoded result size. Inline media counts each occurrence; embedded text counts its UTF-8 bytes. Resource references are not fetched. The protocol adapter must separately account for wire framing, envelopes, compatibility copies, generated blocks and its final reserve before delivery.

Configuration requires at least 16 KiB for results, 256 bytes for a definition, and 64 bytes for cursors/continuation tokens. Inline budget cannot exceed result budget. Continuation configuration must fit arguments, form schema, state, answers and fixed transition overhead in its retained-byte budget. Interaction limits are enforced by the private ledger; see interaction contracts for its defaults, reservations and replay rules. Ledger records are allocated on demand.

A zero Call, zero handler Outcome, or Finish containing an unconstructed result cannot produce successful output. On success, an output schema requires matching structured data. On failure, structured diagnostics are optional but must match that same schema if present. Invalid diagnostics are withheld; causes stay private. Context cancellation/deadline is checked before dispatch and before returning validated output. Arbitrary Go callbacks cannot be forcibly terminated.