Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/v0.1.0/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ example on Linux or macOS. On Windows, use a Linux environment such as WSL.

Start the minimal Provider-side Bootstrap server:

```console title="Terminal 1 — Provider runtime"
```console title="Terminal 1 - Provider runtime"
python -m examples.bootstrap.server \
unix:/tmp/stateforge-bootstrap.sock \
7f7db7d8-68b4-4f71-9769-065b5c4f941c \
Expand All @@ -80,7 +80,7 @@ The server binds one local endpoint for the supplied Provider instance and
endpoint generation. Leave it running, then open a second terminal with the
same virtual environment activated:

```console title="Terminal 2 — Agent runtime"
```console title="Terminal 2 - Agent runtime"
python -m examples.bootstrap.client \
unix:/tmp/stateforge-bootstrap.sock \
7f7db7d8-68b4-4f71-9769-065b5c4f941c \
Expand Down
6 changes: 6 additions & 0 deletions docs/v0.1.0/procedures/operation-admission.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,12 @@ only; an existing terminal operation still resolves to the same admission
record, while its retained terminal outcome is read through the operation
lifecycle procedure.

Provider presentation is not an admission input. An operation request surface
may help a user construct an invocation, but only the accepted operation
identifier and authoritative `input_schema` govern validation.
`presentation_revision` is not part of the invocation or its canonical request
fingerprint.

## Request model

`StartOperationRequest` deliberately separates the immutable semantic
Expand Down
89 changes: 66 additions & 23 deletions docs/v0.1.0/procedures/provider-manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,8 @@ python -m pip install stateforge-protocol grpcio
| Source | Responsibility |
| --- | --- |
| [`manifest.proto`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto) | Owns messages, field numbers, and the unary `ManifestService.GetManifest` RPC. |
| [`contract.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/contract.py) | Owns the canonical service identity and request, response, declaration, schema, and revision resource limits. |
| [`validation.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/validation.py) | Owns packaged-schema validation, embedded-schema inspection, bounded canonicalization, revision calculation and verification, and cache-key validation. |
| [`contract.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/contract.py) | Owns the canonical service identity and the limits for declarations, presentation overlays, assets, schemas, and revisions. |
| [`validation.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/validation.py) | Owns complete exchange validation, independent manifest and presentation acceptance, embedded-schema inspection, canonical revisions, and cache keys. |
| [`manifest.schema.json`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json) | Defines the request and response ProtoJSON projections and manifest schema-1 structure. |

### Python API surface
Expand All @@ -101,9 +101,11 @@ python -m pip install stateforge-protocol grpcio
| Server interface and registration | `manifest_pb2_grpc.ManifestServiceServicer` and `add_ManifestServiceServicer_to_server` |
| Service identity and resource limits | `stateforge_protocol.sfp.manifest.v1.contract` |
| Complete response validation | `validation.validate_manifest_response` |
| Operational and presentation snapshot validation | `validation.validate_manifest_exchange` |
| Declaration and embedded-schema validation | `validation.validate_manifest_document` and `validation.validate_schema` |
| Deterministic revision | `validation.compute_manifest_revision` |
| Cache-key validation | `validation.validate_manifest_key` |
| Presentation overlay validation | `validation.validate_presentation_document` |
| Deterministic revisions | `validation.compute_manifest_revision` and `validation.compute_presentation_revision` |
| Cache-key validation | `validation.validate_manifest_key` and `validation.validate_presentation_key` |

Import the complete public surface from the versioned package:

Expand Down Expand Up @@ -146,6 +148,8 @@ revisioned declaration snapshot.
| Response | `manifest_schema_version` | Highest manifest schema version supported by both peers. |
| Response | `manifest` | Complete Provider declaration for the selected schema. |
| Response | `manifest_revision` | Deterministic SHA-256 revision of the accepted declaration snapshot. |
| Response | `presentation` | Optional Provider, operation, and trigger surfaces described by bounded component trees, renderer requirements, and embedded assets. |
| Response | `presentation_revision` | Independent SHA-256 revision bound to this manifest; present exactly when `presentation` is present. |

=== "Example request"

Expand Down Expand Up @@ -251,9 +255,8 @@ different response fences.
### Session binding

`GetManifestRequest.expected_session_id` uses field **4** and
`GetManifestResponse.session_id` uses field **6**. Existing field numbers and
meanings are preserved. Both are required opaque strings of 1–255 Unicode
code points, matching capability assessment. Preserve exact case and contents;
`GetManifestResponse.session_id` uses field **6**. Both are required opaque strings of
1–255 Unicode code points, matching capability assessment. Preserve exact case and contents;
do not trim, normalize, parse as UUID, or derive them from endpoint identity.
No mandatory session metadata header is introduced.

Expand All @@ -276,6 +279,24 @@ express negotiated context; they are not authentication credentials or
permission to execute operations. Existing channel trust requirements still
apply.

## Presentation snapshot

The operational manifest already contains everything needed to build a correct
default interface. Its JSON Schemas define fields, types, required values,
validation, and secret-bearing inputs. The optional `presentation` snapshot
selects versioned renderer components and binds them to defined data sources
without changing any of those facts.

The presentation and its revision are present as a pair. The Agent validates
the operational manifest first and can use it even when presentation is
absent or rejected. A valid presentation is revised independently and bound
to the accepted `manifest_revision`.

The [Provider presentation guide](provider-presentation.md) explains surfaces,
the generic component tree, core renderers, custom renderer metadata and
fallback, data bindings, and embedded assets. The wire fields, validation
pipeline, and limits remain defined on this page.

## Declaration model

The public Provider framework constructs these declarations from Python
Expand Down Expand Up @@ -422,7 +443,12 @@ flowchart TB
Decode --> Document["Validate the packaged<br/>document schema"]
Document --> Embedded["Validate embedded<br/>Draft 2020-12 schemas"]
Embedded --> Semantic["Validate session fences,<br/>declaration semantics, and revision"]
Semantic --> Accept["Manifest accepted"]
Semantic --> Accept["Operational manifest accepted"]
Accept --> Overlay{"Presentation present<br/>and supported?"}
Overlay -->|No| Fallback["Use schema-derived rendering"]
Overlay -->|Yes| Presentation["Validate overlay references,<br/>assets, and revision"]
Presentation -->|Valid| Enhanced["Accept presentation snapshot"]
Presentation -->|Invalid| Fallback
```

| Stage | Question answered |
Expand All @@ -432,6 +458,7 @@ flowchart TB
| Packaged document schema | Is the complete request or response structurally valid? |
| Embedded-schema validation | Are operation, result, configuration, and trigger schemas safe Draft 2020-12 documents? |
| Semantic validation | Do identities, session fences, declaration rules, and the deterministic revision agree? |
| Presentation validation | Do optional views refer only to declared capabilities and schema fields, use compatible preferences, carry safe assets, and match their independent revision? |

!!! important "Decoding is not validation"

Expand Down Expand Up @@ -470,7 +497,7 @@ validation or revision calculation.
| --- | --- |
| `manifest.proto` | Field names, numbers, wire types, messages, and service shape. |
| `manifest.schema.json` | Required fields, identifier syntax, uniqueness, counts, and nested structural constraints. |
| `validation.py` | Embedded-schema inspection, bounded canonicalization, revision calculation, and revision verification. |
| `validation.py` | Embedded-schema and presentation semantics, bounded canonicalization, independent revision calculation, and cache-key validation. |
| Provider and Agent runtimes | Live-session lookup, declaration construction, request correlation, cache storage, and admission decisions. |

The protocol package exposes validation functions; callers invoke them
Expand All @@ -487,6 +514,8 @@ declarations, or maintain Agent caches.
| Operation, trigger, requirement, and profile identifiers | Their respective canonical identifier syntax. |
| Manifest schema version | A known supported version. |
| Manifest revision | `sha256:` followed by 64 lowercase hexadecimal characters. |
| Presentation schema version | Version `1` when a presentation snapshot is included. |
| Presentation revision | `sha256:` followed by 64 lowercase hexadecimal characters and bound to the accepted manifest revision. |
| Repeated declarations | Unique where the contract defines set-like semantics. |

### Bounded validation
Expand All @@ -498,12 +527,15 @@ Implementations enforce these limits before accepting a snapshot:
| Serialized request | 8 KiB |
| Serialized response | 2 MiB |
| Canonical revision preimage | 1 MiB |
| Canonical presentation revision preimage | 2 MiB |
| JSON nodes processed during validation | 100,000 |
| Schema nodes processed per embedded document | 25,000 |
| Each operations, triggers, or requirements map | 1,024 entries |
| Platform pairs | 256 unique pairs |
| Profile claims per operation | 64 unique claims |
| Embedded JSON nesting | 64 containers |
| Presentation assets | 64 assets; 256 KiB each; 1 MiB total |
| Presentation dimensions | 8192 × 8192 pixels |

!!! warning "Reject expensive input early"

Expand All @@ -516,13 +548,13 @@ Implementations enforce these limits before accepting a snapshot:
Input, result, configuration, and trigger schemas are Draft 2020-12 documents
carried in `google.protobuf.Struct`.

| Area | Rule |
| --- | --- |
| Root | Explicitly declare `$schema` and `type: object`. Boolean subschemas are allowed below the root. |
| References | Use only local fragment references that resolve inside the same document. Never retrieve a remote schema. |
| Base URI | `$id` is prohibited, so nested content cannot change the reference base. |
| JSON values | Reject duplicate object keys, NaN, infinity, invalid Unicode, non-JSON values, and numbers outside RFC 8785's interoperable domain. |
| Content | Carry types, constraints, and safe static metadata—not configured values, credentials, customer data, or component bindings. |
| Area | Rule |
| --- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Root | Explicitly declare `$schema` and `type: object`. Boolean subschemas are allowed below the root. |
| References | Use only local fragment references that resolve inside the same document. Never retrieve a remote schema. |
| Base URI | `$id` is prohibited, so nested content cannot change the reference base. |
| JSON values | Reject duplicate object keys, NaN, infinity, invalid Unicode, non-JSON values, and numbers outside RFC 8785's interoperable domain. |
| Content | Carry types, constraints, and safe static metadata, not configured values, credentials, customer data, or component bindings. |
| Secrets | Mark secret-bearing inputs with `writeOnly: true`. They cannot expose `default`, `examples`, `const`, or `enum` values, directly or through references and composed schemas. |

### What validation cannot prove
Expand Down Expand Up @@ -598,7 +630,11 @@ is `sha256:6bfdf3aedc2d4e45d77d4787cc0e744a488208b2510d81788291f51d24a623e8`.
limits, and canonical digest. Store only accepted snapshots. A revision is
a change detector, not authentication. Profile-specific conformance still
requires the validators and behavior tests defined by that profile.
5. An invalid manifest leaves the integration unusable even if gRPC health is
5. Validate `presentation` independently. Cache it by Provider identity,
accepted manifest revision, presentation schema version, and presentation
revision. If it is absent, unsupported, or invalid, discard it and retain
complete schema-derived rendering from the accepted manifest.
6. An invalid manifest leaves the integration unusable even if gRPC health is
`SERVING`. Block operational requests. A valid changed manifest replaces the
normalized declaration and triggers Agent-owned reconciliation.

Expand All @@ -617,6 +653,7 @@ protocol package does not implement the cache or inventory.
| Session unknown/inactive, handshake missing, or instance/generation does not match the requested active session | Provider returns `FAILED_PRECONDITION`; Agent re-establishes a session (rediscovering if needed) before a new attempt. |
| No common manifest schema version | Provider returns `UNIMPLEMENTED`; Agent marks the endpoint incompatible instead of indefinitely retrying unchanged capabilities. |
| Provider cannot produce a valid snapshot | Fail startup before ready publication where possible; otherwise return `INTERNAL` with sanitized diagnostics, never partial success. |
| Presentation is absent, unsupported, invalid, or its revision does not match | Accept the operational manifest, discard the presentation snapshot, and render directly from the manifest schemas. |
| Transport lost or temporarily unavailable | `UNAVAILABLE`; bounded read retries with backoff are safe after validating/re-establishing the session. |
| Client deadline or cancellation | Standard `DEADLINE_EXCEEDED` / `CANCELLED`; no operation is started or cancelled by this read. |
| Success payload fails Agent validation or revision check | Local manifest rejection, independently of transport health; it is not a successful capability negotiation. |
Expand Down Expand Up @@ -645,13 +682,19 @@ no generic target-kind declaration or configured resource. An operation's
`input_schema` defines any resource information that operation needs. The
manifest contains schemas, not configuration values or operation inputs.

`ProviderPresentation` is a separate optional snapshot in the same response.
It describes the Provider itself and overlays declared operations, triggers,
and schema fields. It cannot add or hide capabilities, redefine schemas, carry
runtime values, or affect operation and trigger protocol semantics.

The `manifest_revision` hashes the canonical declaration, schema version, and
Provider instance identity. Session ID and endpoint generation are not part of
that preimage. Consumers must validate the full response and revision before
caching it; a changed declaration has a different revision.
Provider instance identity. `presentation_revision` separately hashes the
presentation snapshot while binding it to that accepted manifest revision.
Session ID and endpoint generation are not part of either preimage. Consumers
must validate each snapshot before caching it.

This package defines wire messages, validation schemas, and conformance
vectors, not Provider session storage or an Agent client. The portable
`tests/fixtures/manifest/request.json`, `response.json`, and
`session-binding.json` fixtures exercise the current schema and session
binding.
`tests/fixtures/manifest/request.json`, `response.json`,
`presentation-response.json`, and `session-binding.json` fixtures exercise the
schema, presentation overlay, and session binding.
Loading
Loading