From 0603422e195e9305f6a2f50e737784286e535bf8 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 15:05:43 +0200 Subject: [PATCH 1/8] [TASK][MVP] Define Provider Views and Presentation Assets --- docs/v0.1.0/procedures/operation-admission.md | 6 + docs/v0.1.0/procedures/provider-manifest.md | 166 +++- docs/v0.1.0/procedures/triggers.md | 7 + docs/v0.1.0/reference/ci-automation.md | 7 +- docs/v0.1.0/reference/conformance-coverage.md | 2 +- docs/v0.1.0/reference/python-contracts.md | 28 +- .../sfp/manifest/v1/manifest.proto | 138 +++ scripts/ci/verify_installed.py | 27 +- .../sfp/manifest/v1/_presentation.py | 574 ++++++++++++ .../sfp/manifest/v1/contract.py | 26 + .../sfp/manifest/v1/manifest.schema.json | 467 +++++++++- .../sfp/manifest/v1/manifest_pb2.py | 78 +- .../sfp/manifest/v1/manifest_pb2.pyi | 517 ++++++++++- .../sfp/manifest/v1/validation.py | 258 +++++- .../manifest/presentation-response.json | 242 +++++ tests/test_manifest_contract.py | 210 ++++- tests/test_manifest_session_contract.py | 10 +- tests/test_manifest_validation.py | 851 +++++++++++++++++- 18 files changed, 3551 insertions(+), 63 deletions(-) create mode 100644 src/stateforge_protocol/sfp/manifest/v1/_presentation.py create mode 100644 tests/fixtures/manifest/presentation-response.json diff --git a/docs/v0.1.0/procedures/operation-admission.md b/docs/v0.1.0/procedures/operation-admission.md index c89099d..4f41b21 100644 --- a/docs/v0.1.0/procedures/operation-admission.md +++ b/docs/v0.1.0/procedures/operation-admission.md @@ -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. Labels, visual groups, field +order, widgets, displays, and assets 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 diff --git a/docs/v0.1.0/procedures/provider-manifest.md b/docs/v0.1.0/procedures/provider-manifest.md index 329f084..9129c1c 100644 --- a/docs/v0.1.0/procedures/provider-manifest.md +++ b/docs/v0.1.0/procedures/provider-manifest.md @@ -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 @@ -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: @@ -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, trigger, field, group, and embedded-asset presentation overlay. | + | Response | `presentation_revision` | Independent SHA-256 revision bound to this manifest; present exactly when `presentation` is present. | === "Example request" @@ -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. @@ -276,6 +279,115 @@ 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 a renderer needs to build +a correct default interface. Its JSON Schemas define fields, types, required +values, validation, and secret-bearing inputs. The optional `presentation` +snapshot improves that interface without changing any of those facts. + +```mermaid +flowchart LR + Manifest["Operational manifest
capabilities + JSON Schemas"] --> Default["Complete schema-derived UI"] + Manifest --> Merge["Validated overlay merge"] + Presentation["Presentation snapshot
labels + layout + assets"] --> Merge + Merge --> Enhanced["Enhanced Provider UI"] + Presentation -. "absent, unsupported,
or invalid" .-> Default +``` + +
+
+ PROVIDER +

Describe the integration

+

+ A summary, longer description, embedded visuals, and optional visual + groups describe the Provider without creating capabilities. +

+
+
+ CAPABILITIES +

Present operations and triggers

+

+ Views add labels, explanations, grouping, field order, and compatible + render preferences to capabilities already declared by identifier. +

+
+
+ ASSETS +

Ship Provider-owned visuals

+

+ Bounded PNG and sanitized SVG assets travel inside the snapshot and are + addressed by the SHA-256 digest of their exact bytes. +

+
+
+ +### The schema remains authoritative + +Every schema view points into exactly one authoritative schema using JSON +Pointer. Operation input hints resolve only against that operation's +`input_schema`; result hints resolve against `result_schema`; trigger hints +resolve against `payload_schema`. + +| Presentation can suggest | Presentation cannot change | +| --- | --- | +| Labels, help text, placeholders, units, field order, and visual groups | Field types, requiredness, defaults, validation, or secret semantics | +| A compatible input widget such as text, select, slider, or secret input | Operation input values or admission behavior | +| A compatible result display such as code, table, badge, or metric | Operation results or trigger payloads | +| Provider, operation, trigger, or group icons | Capability identifiers, membership, availability, or authorization | + +Groups are optional. An operation or trigger with an empty `group_id` remains +visible. A field omitted from `field_order`, `groups`, or `fields` also remains +visible through normal schema-derived rendering. There is no presentation +field that hides a capability or schema field. + +Widget and display preferences must agree with the referenced field schema. A +secret widget, for example, requires a string field marked `writeOnly`; a +slider requires a numeric field with explicit minimum and maximum; a table +requires an array. Input preferences are invalid on result and trigger payload +views. + +### Independent acceptance and revision + +The Agent validates the operational manifest first. It then handles the +presentation snapshot independently: + +| Presentation state | Result | +| --- | --- | +| Absent | Accept the manifest and render directly from its schemas. | +| Supported and valid | Accept both snapshots and merge the overlay into schema-derived rendering. | +| Unsupported schema version | Accept the manifest and ignore the presentation snapshot. | +| Invalid reference, preference, asset, or revision | Accept the manifest and ignore the presentation snapshot. | + +`manifest_revision` never includes presentation. Its value therefore remains +stable when only labels, layout, groups, or assets change. The separate +`presentation_revision` is SHA-256 over RFC 8785 canonical JSON of: + +```json +{ + "manifestRevision": "sha256:", + "presentation": {}, + "providerInstanceId": "" +} +``` + +Binding the presentation revision to `manifestRevision` prevents an overlay +from being reused with a different declaration. Session ID and endpoint +generation remain response fences and are excluded from both revisions. + +### Asset boundary + +Presentation assets are data, never executable extensions. A snapshot may +contain at most 64 assets, each no larger than 256 KiB and together no larger +than 1 MiB. Dimensions are positive and bounded to 8192 × 8192 pixels. Every +asset must be referenced, every reference must resolve, and each map key must +equal the SHA-256 digest of the exact content. + +Only validated PNG and sanitized SVG are accepted. SVG uses a closed element +and attribute allowlist and rejects scripts, event handlers, styles, external +references, data URLs, DTDs, and entities. The contract has no field for HTML, +CSS, JavaScript, a remote URL, or a filesystem path. + ## Declaration model The public Provider framework constructs these declarations from Python @@ -422,7 +534,12 @@ flowchart TB Decode --> Document["Validate the packaged
document schema"] Document --> Embedded["Validate embedded
Draft 2020-12 schemas"] Embedded --> Semantic["Validate session fences,
declaration semantics, and revision"] - Semantic --> Accept["Manifest accepted"] + Semantic --> Accept["Operational manifest accepted"] + Accept --> Overlay{"Presentation present
and supported?"} + Overlay -->|No| Fallback["Use schema-derived rendering"] + Overlay -->|Yes| Presentation["Validate overlay references,
assets, and revision"] + Presentation -->|Valid| Enhanced["Accept presentation snapshot"] + Presentation -->|Invalid| Fallback ``` | Stage | Question answered | @@ -432,6 +549,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" @@ -470,7 +588,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 @@ -487,6 +605,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 @@ -498,12 +618,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" @@ -598,7 +721,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. @@ -617,6 +744,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. | @@ -645,13 +773,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. diff --git a/docs/v0.1.0/procedures/triggers.md b/docs/v0.1.0/procedures/triggers.md index 5f4fcef..31c8080 100644 --- a/docs/v0.1.0/procedures/triggers.md +++ b/docs/v0.1.0/procedures/triggers.md @@ -232,6 +232,13 @@ The bound `manifest_revision` selects the declaration snapshot, so a publication has no separate schema-version field and cannot negotiate a schema independently. +Provider presentation does not participate in publication or acknowledgement. +Its labels, visual groups, field order, displays, and assets may improve how a +consumer renders a declared trigger, but the trigger identifier and +authoritative `payload_schema` remain the complete wire contract. +`presentation_revision` is not part of the stream binding or publication +content fingerprint. + The Provider normalizes and validates its payload before publishing. The Agent validates the decoded payload again against the exact accepted declaration. Trigger-specific repository, resource, project, or source identity belongs in diff --git a/docs/v0.1.0/reference/ci-automation.md b/docs/v0.1.0/reference/ci-automation.md index ed62d5d..9cdca87 100644 --- a/docs/v0.1.0/reference/ci-automation.md +++ b/docs/v0.1.0/reference/ci-automation.md @@ -24,7 +24,8 @@ flowchart LR

The contract is internally consistent

Protobuf sources, generated bindings, schemas, fixtures, validators, - documentation, and compatibility checks agree before packaging begins. + documentation, descriptor checks, and conformance fixtures agree before + packaging begins.

@@ -79,9 +80,9 @@ installation. No downstream job rebuilds the package. | Gate | What runs | What it proves | | --- | --- | --- | -| Source contracts | Dependency-lock check, Actionlint, Zizmor, Buf lint and format, deterministic generation, Buf compatibility, the complete test suite with coverage, Ruff, mypy, and strict documentation build | The source tree, generated outputs, automation, and documented contract agree | +| Source contracts | Dependency-lock check, Actionlint, Zizmor, Buf lint and format, deterministic generation, the complete test suite with coverage, Ruff, mypy, and strict documentation build | The source tree, generated outputs, automation, and documented contract agree, including Provider presentation overlays, revisions, assets, and fallback | | Distribution build | One wheel and one source distribution, followed by metadata, checksum, and provenance generation | The candidate has one attributable artifact identity | -| Installed package | Wheel and source-distribution installation in isolated virtual environments with the checkout removed from Python import resolution | The package contains its generated modules, public contracts, schemas, typing marker, and conformance fixtures | +| Installed package | Wheel and source-distribution installation in isolated virtual environments with the checkout removed from Python import resolution | The package contains its generated modules, public contracts, schemas, typing marker, Provider presentation fixture, and conformance fixtures | | Agent consumer | Exact wheel installation, package-origin verification, Protocol-ownership audit, and the complete Agent quality suite | The Agent consumes this candidate through public Protocol APIs | | Provider consumer | Exact wheel installation, package-origin verification, Protocol-ownership audit, and the complete Provider quality suite | StateForge Provider Python consumes this candidate through public Protocol APIs | diff --git a/docs/v0.1.0/reference/conformance-coverage.md b/docs/v0.1.0/reference/conformance-coverage.md index 55425d6..c3fac49 100644 --- a/docs/v0.1.0/reference/conformance-coverage.md +++ b/docs/v0.1.0/reference/conformance-coverage.md @@ -68,7 +68,7 @@ documentation. | [`endpoint-discovery`](../procedures/endpoint-discovery.md) | `sfp.endpoint_discovery.v1.contract` | Descriptor parsing, canonical serialization, filename, identity, generation, socket path, permissions, and size limits | | [`bootstrap`](../bootstrap.md) | `sfp.bootstrap.v1.contract` and `validation` | Handshake request and response validity, identity correlation, version selection, generation fencing, and session bounds | | [`health`](../procedures/health.md) | `sfp.health_contract` with `grpc.health.v1` | Standard service identity, Provider-wide Watch key, lifecycle states, eligibility inputs, failure scenarios, and diagnostic bounds | -| [`manifest`](../procedures/provider-manifest.md) | `sfp.manifest.v1.contract` and `validation` | Declaration shape, embedded schemas, identifiers, canonical revision, session binding, and invalid documents | +| [`manifest`](../procedures/provider-manifest.md) | `sfp.manifest.v1.contract` and `validation` | Declaration shape, embedded schemas, identifiers, session binding, independent manifest/presentation revisions, schema-addressed overlays, optional groups, safe assets, fallback, and invalid documents | | [`capability-assessment`](../procedures/capability-assessment.md) | `sfp.capability_assessment.v1.contract` and `validation` | Request and response validity, session and manifest correlation, mixed support findings, invalid invariants, and requirement states | ### Exchange and recover diff --git a/docs/v0.1.0/reference/python-contracts.md b/docs/v0.1.0/reference/python-contracts.md index 64cdae2..9fb5f16 100644 --- a/docs/v0.1.0/reference/python-contracts.md +++ b/docs/v0.1.0/reference/python-contracts.md @@ -112,7 +112,7 @@ The same pattern applies to each procedure: | Procedure | Message validation | Correlation and derived values | | --- | --- | --- | | Bootstrap | `validate_handshake_request`, `validate_handshake_response` | `validate_protocol_version` | -| Provider Manifest | `validate_manifest_document`, `validate_manifest_response` | `compute_manifest_revision`, `validate_manifest_key` | +| Provider Manifest | `validate_manifest_document`, `validate_presentation_document`, `validate_manifest_response`, `validate_manifest_exchange` | Independent manifest/presentation revision and cache-key helpers; `PresentationValidationStatus` for safe fallback | | Capability Assessment | `validate_assess_capabilities_request`, `validate_assess_capabilities_response` | `validate_assessment_exchange` | | Operation Admission | Request, response, record, and error-detail validators | `validate_admission_exchange`, `canonical_invocation`, `compute_request_fingerprint` | | Operation Lifecycle | Watch, Cancel, snapshot, and error-detail validators | Watch/Cancel exchange, transition, and terminal-replay validators | @@ -126,6 +126,32 @@ Endpoint Discovery is a filesystem contract rather than a protobuf procedure. Its public `contract` module owns `EndpointDescriptor`, `parse_descriptor`, filename derivation, permissions, size bounds, and generation validation. +### Manifest and presentation acceptance + +`validate_manifest_exchange` always validates the operational manifest first. +Its result reports whether the optional presentation snapshot was accepted, +absent, unsupported, or invalid without making presentation a prerequisite for +using the declared operations and triggers. + +```python +from stateforge_protocol.sfp.manifest.v1 import validation + +exchange = validation.validate_manifest_exchange(response) +manifest_bytes = exchange.manifest_document + +if ( + exchange.presentation_status + is validation.PresentationValidationStatus.ACCEPTED +): + presentation_bytes = exchange.presentation_document +else: + presentation_bytes = None # Render from the authoritative JSON Schemas. +``` + +Cache the two snapshots independently. A presentation cache key includes the +accepted `manifest_revision`, so an overlay can never move to a different +operational declaration by revision alone. + ## Contract constants Protobuf defines field types, but it cannot configure gRPC message ceilings or diff --git a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto index 6e3185f..4d8b072 100644 --- a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto +++ b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto @@ -52,6 +52,15 @@ message GetManifestResponse { // The Agent must match it to both the request and its current session before // accepting or reusing a cached declaration. Not part of manifest_revision. string session_id = 6; + // Optional declarative presentation snapshot. Operational JSON Schemas + // remain sufficient to render every declared capability when this field is + // absent, unsupported or rejected. Presentation never changes execution + // semantics and is not part of manifest_revision. + ProviderPresentation presentation = 7; + // Present exactly when presentation is present. "sha256:" plus 64 lowercase + // hex digits over the canonical presentation preimage defined by this + // package. Session ID and endpoint generation are excluded. + optional string presentation_revision = 8; } // ProviderManifest describes implementation-wide declarations, not configured @@ -119,3 +128,132 @@ message TriggerDeclaration { // Required Draft 2020-12 object schema, never an event instance. google.protobuf.Struct payload_schema = 1; } + +// ProviderPresentation is an optional, independently revised visual overlay +// on an accepted ProviderManifest. Maps use the exact operation and trigger +// identifiers declared by that manifest. Presentation cannot add, remove or +// redefine capabilities or their JSON Schemas. +message ProviderPresentation { + // Presentation document version. Version 1 is defined by this package. + uint32 presentation_schema_version = 1; + // Optional Provider-level description, branding and visual groups. + ProviderView provider = 2; + // Optional overlays keyed by declared operation identifier. + map operations = 3; + // Optional overlays keyed by declared trigger identifier. + map triggers = 4; + // Embedded content-addressed visuals keyed by their sha256 digest. + map assets = 5; +} + +// ProviderView describes the Provider itself. Group order is declaration order; +// operations and triggers opt into a group by ID, and ungrouped capabilities +// remain visible through schema-derived rendering. +message ProviderView { + string summary = 1; + string description = 2; + string icon_asset_digest = 3; + string banner_asset_digest = 4; + repeated CapabilityGroup groups = 5; +} + +// CapabilityGroup supplies optional visual organization without duplicating +// operation or trigger membership. +message CapabilityGroup { + string id = 1; + string label = 2; + string description = 3; + string icon_asset_digest = 4; +} + +// OperationView supplies labels and schema-addressed overlays for one declared +// operation. Empty group_id means that the operation is not grouped. +message OperationView { + string label = 1; + string summary = 2; + string description = 3; + string icon_asset_digest = 4; + string group_id = 5; + SchemaView input = 6; + SchemaView result = 7; +} + +// TriggerView supplies labels and a schema-addressed overlay for one declared +// trigger. Empty group_id means that the trigger is not grouped. +message TriggerView { + string label = 1; + string summary = 2; + string description = 3; + string icon_asset_digest = 4; + string group_id = 5; + SchemaView payload = 6; +} + +// SchemaView adds optional ordering, grouping and compatible render hints to a +// JSON Schema. Every pointer addresses a field schema in the corresponding +// operation input/result or trigger payload schema. Unmentioned fields remain +// visible and retain their schema-defined semantics. +message SchemaView { + repeated string field_order = 1; + repeated FieldGroup groups = 2; + map fields = 3; +} + +// FieldGroup visually groups schema fields. Field pointers may appear in at +// most one group and group order is declaration order. +message FieldGroup { + string id = 1; + string label = 2; + string description = 3; + repeated string fields = 4; +} + +// FieldView supplies optional text and compatible render preferences for one +// schema field. It cannot change validation, requiredness or visibility. +message FieldView { + string label = 1; + string help_text = 2; + string placeholder = 3; + string unit = 4; + InputWidget widget = 5; + DisplayStyle display = 6; +} + +// InputWidget selects an optional input control compatible with a field's +// authoritative JSON Schema. Unspecified delegates entirely to the renderer. +enum InputWidget { + INPUT_WIDGET_UNSPECIFIED = 0; + INPUT_WIDGET_TEXT = 1; + INPUT_WIDGET_MULTILINE = 2; + INPUT_WIDGET_SECRET = 3; + INPUT_WIDGET_NUMBER = 4; + INPUT_WIDGET_SLIDER = 5; + INPUT_WIDGET_CHECKBOX = 6; + INPUT_WIDGET_SELECT = 7; + INPUT_WIDGET_RADIO = 8; + INPUT_WIDGET_DATE_TIME = 9; + INPUT_WIDGET_JSON = 10; +} + +// DisplayStyle selects an optional read-only presentation compatible with a +// field's authoritative JSON Schema. Unspecified delegates to the renderer. +enum DisplayStyle { + DISPLAY_STYLE_UNSPECIFIED = 0; + DISPLAY_STYLE_TEXT = 1; + DISPLAY_STYLE_CODE = 2; + DISPLAY_STYLE_JSON = 3; + DISPLAY_STYLE_TABLE = 4; + DISPLAY_STYLE_BADGE = 5; + DISPLAY_STYLE_METRIC = 6; + DISPLAY_STYLE_DATE_TIME = 7; +} + +// PresentationAsset is embedded, content-addressed media. The map key is the +// sha256 digest of content. Remote URLs and filesystem paths have no wire field. +message PresentationAsset { + string media_type = 1; + bytes content = 2; + uint32 width = 3; + uint32 height = 4; + string alt_text = 5; +} diff --git a/scripts/ci/verify_installed.py b/scripts/ci/verify_installed.py index 28867e5..d055abd 100644 --- a/scripts/ci/verify_installed.py +++ b/scripts/ci/verify_installed.py @@ -212,7 +212,32 @@ def _verify_manifest_validation(fixture_root: Path) -> int: ) if key.revision != response.manifest_revision: raise ValueError("Installed Manifest key validation is invalid") - return 2 + + presented = ParseDict( + _read_json_object( + fixture_root / "manifest" / "presentation-response.json" + ), + manifest_pb2.GetManifestResponse(), + ) + exchange = manifest_validation.validate_manifest_exchange(presented) + if ( + exchange.presentation_status + is not manifest_validation.PresentationValidationStatus.ACCEPTED + or exchange.presentation_key is None + or exchange.presentation_document is None + ): + raise ValueError("Installed Provider presentation was not accepted") + + presented.presentation.provider.summary = "Tampered presentation" + rejected = manifest_validation.validate_manifest_exchange(presented) + if ( + rejected.presentation_status + is not manifest_validation.PresentationValidationStatus.INVALID + or rejected.presentation_document is not None + or rejected.manifest_document != exchange.manifest_document + ): + raise ValueError("Installed Provider presentation fallback is invalid") + return 4 def _verify_trigger_publication_validation(fixture_root: Path) -> int: diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py new file mode 100644 index 0000000..933f3fd --- /dev/null +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -0,0 +1,574 @@ +"""Validate Provider presentation overlays and embedded visual assets.""" + +from __future__ import annotations + +import hashlib +import re +import struct +import zlib +from collections.abc import Iterable +from typing import Any, Final, Never, cast +from urllib.parse import unquote +from xml.etree import ElementTree + +from stateforge_protocol.sfp.manifest.v1 import contract, manifest_pb2 + +_LOCAL_ASSET_REFERENCE: Final = re.compile( + r"url\(#[A-Za-z_][A-Za-z0-9_.:-]*\)" +) +_SVG_NAMESPACE: Final = "http://www.w3.org/2000/svg" +_SAFE_SVG_TAGS: Final = frozenset( + { + "circle", + "clipPath", + "defs", + "desc", + "ellipse", + "g", + "line", + "linearGradient", + "mask", + "path", + "polygon", + "polyline", + "radialGradient", + "rect", + "stop", + "svg", + "symbol", + "title", + } +) +_SAFE_SVG_ATTRIBUTES: Final = frozenset( + { + "aria-hidden", + "aria-label", + "clip-path", + "cx", + "cy", + "d", + "fill", + "fill-opacity", + "gradientTransform", + "gradientUnits", + "height", + "id", + "mask", + "offset", + "opacity", + "points", + "preserveAspectRatio", + "r", + "role", + "rx", + "ry", + "stop-color", + "stop-opacity", + "stroke", + "stroke-linecap", + "stroke-linejoin", + "stroke-opacity", + "stroke-width", + "transform", + "viewBox", + "width", + "x", + "x1", + "x2", + "y", + "y1", + "y2", + } +) +_SCALAR_TYPES: Final = frozenset({"boolean", "integer", "number", "string"}) +_NUMBER_TYPES: Final = frozenset({"integer", "number"}) +_JSON_TYPES: Final = frozenset({"array", "object"}) +_PNG_SIGNATURE: Final = b"\x89PNG\r\n\x1a\n" +_PNG_CHUNK_OVERHEAD: Final = 12 +_PNG_IHDR_BYTES: Final = 13 +_SAFE_PNG_CHUNKS: Final = frozenset( + {b"IHDR", b"PLTE", b"IDAT", b"IEND", b"tRNS"} +) + + +def validate_presentation_semantics( + presentation: dict[str, Any], + manifest: dict[str, Any], + message: manifest_pb2.ProviderPresentation, + *, + error_type: type[ValueError], +) -> None: + """Validate references, schema overlays and assets for presentation v1.""" + operations = cast(dict[str, dict[str, Any]], manifest["operations"]) + triggers = cast(dict[str, dict[str, Any]], manifest["triggers"]) + operation_views = cast( + dict[str, dict[str, Any]], presentation["operations"] + ) + trigger_views = cast(dict[str, dict[str, Any]], presentation["triggers"]) + + if not operation_views.keys() <= operations.keys(): + raise error_type( + "presentation: operation view does not name a declared operation" + ) + if not trigger_views.keys() <= triggers.keys(): + raise error_type( + "presentation: trigger view does not name a declared trigger" + ) + + group_ids = _validate_capability_groups(presentation, error_type) + for identifier, view in operation_views.items(): + _validate_group_reference(view, group_ids, error_type) + declaration = operations[identifier] + if "input" in view: + _validate_schema_view( + cast(dict[str, Any], view["input"]), + cast(dict[str, Any], declaration["inputSchema"]), + input_scope=True, + error_type=error_type, + ) + if "result" in view: + _validate_schema_view( + cast(dict[str, Any], view["result"]), + cast(dict[str, Any], declaration["resultSchema"]), + input_scope=False, + error_type=error_type, + ) + for identifier, view in trigger_views.items(): + _validate_group_reference(view, group_ids, error_type) + if "payload" in view: + declaration = triggers[identifier] + _validate_schema_view( + cast(dict[str, Any], view["payload"]), + cast(dict[str, Any], declaration["payloadSchema"]), + input_scope=False, + error_type=error_type, + ) + + _validate_assets(presentation, message, error_type) + + +def _validate_capability_groups( + presentation: dict[str, Any], error_type: type[ValueError] +) -> frozenset[str]: + provider = presentation.get("provider") + if provider is None: + return frozenset() + groups = cast(dict[str, Any], provider)["groups"] + identifiers = [cast(dict[str, Any], group)["id"] for group in groups] + if len(identifiers) != len(set(identifiers)): + raise error_type("presentation: capability group IDs must be unique") + return frozenset(cast(Iterable[str], identifiers)) + + +def _validate_group_reference( + view: dict[str, Any], + group_ids: frozenset[str], + error_type: type[ValueError], +) -> None: + group_id = view["groupId"] + if group_id and group_id not in group_ids: + raise error_type("presentation: capability group reference is missing") + + +def _validate_schema_view( + view: dict[str, Any], + schema: dict[str, Any], + *, + input_scope: bool, + error_type: type[ValueError], +) -> None: + pointers = list(cast(list[str], view["fieldOrder"])) + field_views = cast(dict[str, dict[str, Any]], view["fields"]) + pointers.extend(field_views) + grouped: list[str] = [] + group_ids: list[str] = [] + for group in cast(list[dict[str, Any]], view["groups"]): + group_ids.append(cast(str, group["id"])) + grouped.extend(cast(list[str], group["fields"])) + if len(group_ids) != len(set(group_ids)): + raise error_type("presentation: field group IDs must be unique") + if len(grouped) != len(set(grouped)): + raise error_type( + "presentation: a field may belong to at most one field group" + ) + pointers.extend(grouped) + + property_nodes = _property_schema_nodes(schema) + resolved: dict[str, dict[str, Any]] = {} + for pointer in set(pointers): + target = _resolve_json_pointer(schema, pointer, error_type) + if not isinstance(target, dict) or id(target) not in property_nodes: + raise error_type( + "presentation: JSON Pointer must name a schema field" + ) + resolved[pointer] = target + + for pointer, field_view in field_views.items(): + target = _follow_local_reference(resolved[pointer], schema, error_type) + _validate_field_preferences( + field_view, + target, + input_scope=input_scope, + error_type=error_type, + ) + + +def _property_schema_nodes(schema: dict[str, Any]) -> set[int]: + nodes: set[int] = set() + pending: list[object] = [schema] + seen: set[int] = set() + while pending: + current = pending.pop() + if isinstance(current, dict): + identity = id(current) + if identity in seen: + continue + seen.add(identity) + properties = current.get("properties") + if isinstance(properties, dict): + nodes.update( + id(value) + for value in properties.values() + if isinstance(value, dict) + ) + pending.extend(current.values()) + elif isinstance(current, list): + pending.extend(current) + return nodes + + +def _resolve_json_pointer( + document: object, pointer: str, error_type: type[ValueError] +) -> object: + current = document + for raw_token in pointer.split("/")[1:]: + token = raw_token.replace("~1", "/").replace("~0", "~") + if isinstance(current, dict) and token in current: + current = current[token] + elif isinstance(current, list) and token.isdigit(): + index = int(token) + if index >= len(current): + raise error_type("presentation: JSON Pointer does not resolve") + current = current[index] + else: + raise error_type("presentation: JSON Pointer does not resolve") + return current + + +def _follow_local_reference( + schema: dict[str, Any], + root: dict[str, Any], + error_type: type[ValueError], +) -> dict[str, Any]: + current = schema + seen: set[int] = set() + while "$ref" in current: + identity = id(current) + if identity in seen: + raise error_type("presentation: cyclic field schema reference") + seen.add(identity) + reference = current["$ref"] + if not isinstance(reference, str) or not reference.startswith("#"): + raise error_type("presentation: field schema reference is invalid") + fragment = unquote(reference[1:]) + target = ( + root + if not fragment + else _resolve_json_pointer(root, fragment, error_type) + ) + if not isinstance(target, dict): + raise error_type( + "presentation: field schema reference must name a schema" + ) + current = target + return current + + +def _validate_field_preferences( + view: dict[str, Any], + schema: dict[str, Any], + *, + input_scope: bool, + error_type: type[ValueError], +) -> None: + widget = cast(str, view["widget"]) + display = cast(str, view["display"]) + if not input_scope and ( + widget != "INPUT_WIDGET_UNSPECIFIED" or view["placeholder"] + ): + raise error_type( + "presentation: output fields cannot declare input preferences" + ) + types = _schema_types(schema) + _validate_widget(widget, schema, types, error_type) + _validate_display(display, schema, types, error_type) + + +def _validate_widget( + widget: str, + schema: dict[str, Any], + types: frozenset[str], + error_type: type[ValueError], +) -> None: + """Require one input widget to match its field schema.""" + if widget == "INPUT_WIDGET_UNSPECIFIED": + return + elif widget in {"INPUT_WIDGET_TEXT", "INPUT_WIDGET_MULTILINE"}: + _require_types(types, {"string"}, "input widget", error_type) + elif widget == "INPUT_WIDGET_SECRET": + _require_types(types, {"string"}, "input widget", error_type) + if schema.get("writeOnly") is not True: + raise error_type( + "presentation: secret widget requires a write-only field" + ) + elif widget == "INPUT_WIDGET_NUMBER": + _require_types(types, _NUMBER_TYPES, "input widget", error_type) + elif widget == "INPUT_WIDGET_SLIDER": + _require_types(types, _NUMBER_TYPES, "input widget", error_type) + if "minimum" not in schema or "maximum" not in schema: + raise error_type( + "presentation: slider requires schema minimum and maximum" + ) + elif widget == "INPUT_WIDGET_CHECKBOX": + _require_types(types, {"boolean"}, "input widget", error_type) + elif widget in {"INPUT_WIDGET_SELECT", "INPUT_WIDGET_RADIO"}: + if not isinstance(schema.get("enum"), list) or not schema["enum"]: + raise error_type( + "presentation: choice widget requires a nonempty schema enum" + ) + elif widget == "INPUT_WIDGET_DATE_TIME": + _require_date_time(schema, types, "input widget", error_type) + elif widget == "INPUT_WIDGET_JSON": + _require_types(types, _JSON_TYPES, "input widget", error_type) + + +def _validate_display( + display: str, + schema: dict[str, Any], + types: frozenset[str], + error_type: type[ValueError], +) -> None: + """Require one display style to match its field schema.""" + if display == "DISPLAY_STYLE_UNSPECIFIED": + return + if display == "DISPLAY_STYLE_TEXT": + _require_types(types, _SCALAR_TYPES, "display style", error_type) + elif display == "DISPLAY_STYLE_CODE": + _require_types(types, {"string"}, "display style", error_type) + elif display == "DISPLAY_STYLE_JSON": + _require_types(types, _JSON_TYPES, "display style", error_type) + elif display == "DISPLAY_STYLE_TABLE": + _require_types(types, {"array"}, "display style", error_type) + elif display == "DISPLAY_STYLE_BADGE": + _require_types(types, _SCALAR_TYPES, "display style", error_type) + elif display == "DISPLAY_STYLE_METRIC": + _require_types(types, _NUMBER_TYPES, "display style", error_type) + elif display == "DISPLAY_STYLE_DATE_TIME": + _require_date_time(schema, types, "display style", error_type) + + +def _schema_types(schema: dict[str, Any]) -> frozenset[str]: + declared = schema.get("type") + if isinstance(declared, str): + return frozenset({declared}) + if isinstance(declared, list) and all( + isinstance(value, str) for value in declared + ): + return frozenset(declared) - {"null"} + return frozenset() + + +def _require_types( + actual: frozenset[str], + permitted: Iterable[str], + preference: str, + error_type: type[ValueError], +) -> None: + allowed = frozenset(permitted) + if not actual or not actual <= allowed: + raise error_type( + f"presentation: {preference} is incompatible with schema type" + ) + + +def _require_date_time( + schema: dict[str, Any], + types: frozenset[str], + preference: str, + error_type: type[ValueError], +) -> None: + _require_types(types, {"string"}, preference, error_type) + if schema.get("format") not in {"date", "date-time", "time"}: + raise error_type( + f"presentation: {preference} requires a date or time format" + ) + + +def _validate_assets( + presentation: dict[str, Any], + message: manifest_pb2.ProviderPresentation, + error_type: type[ValueError], +) -> None: + assets = message.assets + total_bytes = sum(len(asset.content) for asset in assets.values()) + if total_bytes > contract.MAX_PRESENTATION_ASSET_TOTAL_BYTES: + raise error_type("presentation: aggregate asset limit exceeded") + for digest, asset in assets.items(): + if ( + not asset.content + or len(asset.content) > contract.MAX_PRESENTATION_ASSET_BYTES + ): + raise error_type("presentation: asset byte limit exceeded") + expected = "sha256:" + hashlib.sha256(asset.content).hexdigest() + if digest != expected: + raise error_type("presentation: asset digest mismatch") + _validate_asset_content(asset, error_type) + + references = _asset_references(presentation) + if not references <= assets.keys(): + raise error_type("presentation: asset reference is missing") + if assets.keys() - references: + raise error_type("presentation: unreferenced asset is not permitted") + + +def _asset_references(presentation: dict[str, Any]) -> set[str]: + references: set[str] = set() + provider = presentation.get("provider") + if isinstance(provider, dict): + _add_asset_reference(references, provider.get("iconAssetDigest")) + _add_asset_reference(references, provider.get("bannerAssetDigest")) + for group in cast(list[dict[str, Any]], provider["groups"]): + _add_asset_reference(references, group.get("iconAssetDigest")) + for collection in ("operations", "triggers"): + views = cast(dict[str, dict[str, Any]], presentation[collection]) + for view in views.values(): + _add_asset_reference(references, view.get("iconAssetDigest")) + return references + + +def _add_asset_reference(references: set[str], value: object) -> None: + if isinstance(value, str) and value: + references.add(value) + + +def _validate_asset_content( + asset: manifest_pb2.PresentationAsset, + error_type: type[ValueError], +) -> None: + if asset.media_type not in contract.ALLOWED_PRESENTATION_MEDIA_TYPES: + raise error_type("presentation: asset media type is not permitted") + if asset.media_type == "image/svg+xml": + _validate_svg(asset.content, error_type) + return + dimensions = _png_dimensions(asset.content, error_type) + if dimensions != (asset.width, asset.height): + raise error_type("presentation: asset dimensions do not match content") + + +def _validate_svg(content: bytes, error_type: type[ValueError]) -> None: + upper = content.upper() + if b" contract.MAX_SCHEMA_NODES: + raise error_type("presentation: SVG node limit exceeded") + namespace, tag = _split_name(element.tag) + if namespace not in {"", _SVG_NAMESPACE} or tag not in _SAFE_SVG_TAGS: + raise error_type("presentation: unsafe SVG element") + for attribute, value in element.attrib.items(): + attribute_namespace, name = _split_name(attribute) + if attribute_namespace or name not in _SAFE_SVG_ATTRIBUTES: + raise error_type("presentation: unsafe SVG attribute") + lowered = value.lower() + if "javascript:" in lowered or "data:" in lowered: + raise error_type("presentation: unsafe SVG reference") + if "url(" in lowered and not _LOCAL_ASSET_REFERENCE.fullmatch( + value + ): + raise error_type("presentation: unsafe SVG reference") + + +def _split_name(value: str) -> tuple[str, str]: + if value.startswith("{") and "}" in value: + namespace, name = value[1:].split("}", 1) + return namespace, name + return "", value + + +def _local_name(value: str) -> str: + return _split_name(value)[1] + + +def _png_dimensions( + content: bytes, + error_type: type[ValueError], +) -> tuple[int, int]: + """Validate a bounded, static PNG and return its declared dimensions.""" + if not content.startswith(_PNG_SIGNATURE): + _reject_png(error_type) + offset = len(_PNG_SIGNATURE) + dimensions: tuple[int, int] | None = None + saw_image_data = False + while offset + _PNG_CHUNK_OVERHEAD <= len(content): + length = struct.unpack(">I", content[offset : offset + 4])[0] + chunk_type = content[offset + 4 : offset + 8] + data_start = offset + 8 + data_end = data_start + length + chunk_end = data_end + 4 + if chunk_end > len(content) or chunk_type not in _SAFE_PNG_CHUNKS: + _reject_png(error_type) + expected_crc = struct.unpack(">I", content[data_end:chunk_end])[0] + actual_crc = zlib.crc32(chunk_type) + actual_crc = zlib.crc32(content[data_start:data_end], actual_crc) + if expected_crc != actual_crc & 0xFFFFFFFF: + _reject_png(error_type) + if dimensions is None: + if chunk_type != b"IHDR" or length != _PNG_IHDR_BYTES: + _reject_png(error_type) + width, height = struct.unpack( + ">II", content[data_start : data_start + 8] + ) + bit_depth = content[data_start + 8] + color_type = content[data_start + 9] + valid_depths = { + 0: {1, 2, 4, 8, 16}, + 2: {8, 16}, + 3: {1, 2, 4, 8}, + 4: {8, 16}, + 6: {8, 16}, + } + if ( + not width + or not height + or width > contract.MAX_PRESENTATION_ASSET_DIMENSION + or height > contract.MAX_PRESENTATION_ASSET_DIMENSION + or bit_depth not in valid_depths.get(color_type, set()) + or content[data_start + 10 : data_start + 12] != b"\x00\x00" + or content[data_start + 12] not in {0, 1} + ): + _reject_png(error_type) + dimensions = (width, height) + elif chunk_type == b"IHDR": + _reject_png(error_type) + if chunk_type == b"IDAT": + saw_image_data = True + if chunk_type == b"IEND": + if length or not saw_image_data or chunk_end != len(content): + _reject_png(error_type) + if dimensions is None: + _reject_png(error_type) + return dimensions + offset = chunk_end + _reject_png(error_type) + + +def _reject_png(error_type: type[ValueError]) -> Never: + raise error_type("presentation: invalid PNG content") diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index e174950..af563b2 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -16,6 +16,7 @@ # Canonicalization and embedded JSON limits enforced outside JSON Schema. MAX_CANONICAL_REVISION_PREIMAGE_BYTES: Final = 1 * 1024 * 1024 +MAX_PRESENTATION_REVISION_PREIMAGE_BYTES: Final = 2 * 1024 * 1024 MAX_EMBEDDED_JSON_DEPTH: Final = 64 MAX_JSON_NODES: Final = 100_000 MAX_SCHEMA_NODES: Final = 25_000 @@ -33,3 +34,28 @@ MAX_RUNTIME_REQUIREMENTS: Final = 1_024 MAX_PLATFORMS: Final = 256 MAX_PROFILE_CLAIMS_PER_OPERATION: Final = 64 + +# Optional presentation-overlay limits mirrored by the packaged schema. +PRESENTATION_SCHEMA_VERSION: Final = 1 +MAX_PRESENTATION_OPERATIONS: Final = MAX_OPERATIONS +MAX_PRESENTATION_TRIGGERS: Final = MAX_TRIGGERS +MAX_CAPABILITY_GROUPS: Final = 64 +MAX_FIELD_GROUPS_PER_SCHEMA: Final = 64 +MAX_FIELDS_PER_GROUP: Final = 256 +MAX_FIELD_ORDER_ENTRIES: Final = 1_024 +MAX_FIELD_VIEWS_PER_SCHEMA: Final = 1_024 +MAX_PRESENTATION_ASSETS: Final = 64 +MAX_PRESENTATION_ASSET_BYTES: Final = 256 * 1024 +MAX_PRESENTATION_ASSET_TOTAL_BYTES: Final = 1 * 1024 * 1024 +MAX_PRESENTATION_ASSET_DIMENSION: Final = 8_192 +MAX_PRESENTATION_LABEL_CODE_POINTS: Final = 255 +MAX_PRESENTATION_SUMMARY_CODE_POINTS: Final = 512 +MAX_PRESENTATION_DESCRIPTION_CODE_POINTS: Final = 4_096 +MAX_PRESENTATION_POINTER_CODE_POINTS: Final = 2_048 + +ALLOWED_PRESENTATION_MEDIA_TYPES: Final = frozenset( + { + "image/png", + "image/svg+xml", + } +) diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json b/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json index 3d92170..e221ec7 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json @@ -286,6 +286,426 @@ ], "additionalProperties": false }, + "presentationGroupId": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9_-]*(?![\\s\\S])" + }, + "jsonPointer": { + "type": "string", + "minLength": 1, + "maxLength": 2048, + "pattern": "^(/([^~/]|~0|~1)*)+$(?![\\s\\S])" + }, + "presentationText": { + "type": "string", + "minLength": 0, + "maxLength": 4096 + }, + "capabilityGroup": { + "type": "object", + "properties": { + "id": { + "$ref": "#/$defs/presentationGroupId" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 255 + }, + "description": { + "$ref": "#/$defs/presentationText" + }, + "iconAssetDigest": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/revision" + } + ] + } + }, + "required": [ + "id", + "label", + "description", + "iconAssetDigest" + ], + "additionalProperties": false + }, + "providerView": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "minLength": 0, + "maxLength": 512 + }, + "description": { + "$ref": "#/$defs/presentationText" + }, + "iconAssetDigest": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/revision" + } + ] + }, + "bannerAssetDigest": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/revision" + } + ] + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/$defs/capabilityGroup" + }, + "minItems": 0, + "maxItems": 64 + } + }, + "required": [ + "summary", + "description", + "iconAssetDigest", + "bannerAssetDigest", + "groups" + ], + "additionalProperties": false + }, + "fieldGroup": { + "type": "object", + "properties": { + "id": { + "$ref": "#/$defs/presentationGroupId" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 255 + }, + "description": { + "$ref": "#/$defs/presentationText" + }, + "fields": { + "type": "array", + "items": { + "$ref": "#/$defs/jsonPointer" + }, + "minItems": 1, + "maxItems": 256, + "uniqueItems": true + } + }, + "required": [ + "id", + "label", + "description", + "fields" + ], + "additionalProperties": false + }, + "fieldView": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 0, + "maxLength": 255 + }, + "helpText": { + "$ref": "#/$defs/presentationText" + }, + "placeholder": { + "type": "string", + "minLength": 0, + "maxLength": 512 + }, + "unit": { + "type": "string", + "minLength": 0, + "maxLength": 64 + }, + "widget": { + "enum": [ + "INPUT_WIDGET_UNSPECIFIED", + "INPUT_WIDGET_TEXT", + "INPUT_WIDGET_MULTILINE", + "INPUT_WIDGET_SECRET", + "INPUT_WIDGET_NUMBER", + "INPUT_WIDGET_SLIDER", + "INPUT_WIDGET_CHECKBOX", + "INPUT_WIDGET_SELECT", + "INPUT_WIDGET_RADIO", + "INPUT_WIDGET_DATE_TIME", + "INPUT_WIDGET_JSON" + ] + }, + "display": { + "enum": [ + "DISPLAY_STYLE_UNSPECIFIED", + "DISPLAY_STYLE_TEXT", + "DISPLAY_STYLE_CODE", + "DISPLAY_STYLE_JSON", + "DISPLAY_STYLE_TABLE", + "DISPLAY_STYLE_BADGE", + "DISPLAY_STYLE_METRIC", + "DISPLAY_STYLE_DATE_TIME" + ] + } + }, + "required": [ + "label", + "helpText", + "placeholder", + "unit", + "widget", + "display" + ], + "additionalProperties": false + }, + "schemaView": { + "type": "object", + "properties": { + "fieldOrder": { + "type": "array", + "items": { + "$ref": "#/$defs/jsonPointer" + }, + "minItems": 0, + "maxItems": 1024, + "uniqueItems": true + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/$defs/fieldGroup" + }, + "minItems": 0, + "maxItems": 64 + }, + "fields": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/jsonPointer" + }, + "additionalProperties": { + "$ref": "#/$defs/fieldView" + }, + "minProperties": 0, + "maxProperties": 1024 + } + }, + "required": [ + "fieldOrder", + "groups", + "fields" + ], + "additionalProperties": false + }, + "operationView": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 0, + "maxLength": 255 + }, + "summary": { + "type": "string", + "minLength": 0, + "maxLength": 512 + }, + "description": { + "$ref": "#/$defs/presentationText" + }, + "iconAssetDigest": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/revision" + } + ] + }, + "groupId": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/presentationGroupId" + } + ] + }, + "input": { + "$ref": "#/$defs/schemaView" + }, + "result": { + "$ref": "#/$defs/schemaView" + } + }, + "required": [ + "label", + "summary", + "description", + "iconAssetDigest", + "groupId" + ], + "additionalProperties": false + }, + "triggerView": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 0, + "maxLength": 255 + }, + "summary": { + "type": "string", + "minLength": 0, + "maxLength": 512 + }, + "description": { + "$ref": "#/$defs/presentationText" + }, + "iconAssetDigest": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/revision" + } + ] + }, + "groupId": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/presentationGroupId" + } + ] + }, + "payload": { + "$ref": "#/$defs/schemaView" + } + }, + "required": [ + "label", + "summary", + "description", + "iconAssetDigest", + "groupId" + ], + "additionalProperties": false + }, + "presentationAsset": { + "type": "object", + "properties": { + "mediaType": { + "enum": [ + "image/png", + "image/svg+xml" + ] + }, + "content": { + "type": "string", + "minLength": 4, + "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$(?![\\s\\S])" + }, + "width": { + "type": "integer", + "minimum": 1, + "maximum": 8192 + }, + "height": { + "type": "integer", + "minimum": 1, + "maximum": 8192 + }, + "altText": { + "type": "string", + "minLength": 1, + "maxLength": 512 + } + }, + "required": [ + "mediaType", + "content", + "width", + "height", + "altText" + ], + "additionalProperties": false + }, + "providerPresentation": { + "type": "object", + "properties": { + "presentationSchemaVersion": { + "const": 1 + }, + "provider": { + "$ref": "#/$defs/providerView" + }, + "operations": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/identifier" + }, + "additionalProperties": { + "$ref": "#/$defs/operationView" + }, + "minProperties": 0, + "maxProperties": 1024 + }, + "triggers": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/identifier" + }, + "additionalProperties": { + "$ref": "#/$defs/triggerView" + }, + "minProperties": 0, + "maxProperties": 1024 + }, + "assets": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/revision" + }, + "additionalProperties": { + "$ref": "#/$defs/presentationAsset" + }, + "minProperties": 0, + "maxProperties": 64 + } + }, + "required": [ + "presentationSchemaVersion", + "operations", + "triggers", + "assets" + ], + "additionalProperties": false + }, "providerManifest": { "type": "object", "properties": { @@ -410,6 +830,23 @@ }, "sessionId": { "$ref": "#/$defs/sessionId" + }, + "presentation": { + "type": "object", + "required": [ + "presentationSchemaVersion" + ], + "properties": { + "presentationSchemaVersion": { + "type": "integer", + "minimum": 1, + "maximum": 4294967295 + } + }, + "additionalProperties": true + }, + "presentationRevision": { + "$ref": "#/$defs/revision" } }, "required": [ @@ -418,9 +855,35 @@ "manifestSchemaVersion", "manifestRevision", "manifest", - "sessionId" + "sessionId" ], - "additionalProperties": false + "additionalProperties": false, + "allOf": [ + { + "if": { + "required": [ + "presentation" + ] + }, + "then": { + "required": [ + "presentationRevision" + ], + "properties": { + "presentationRevision": { + "$ref": "#/$defs/revision" + } + } + }, + "else": { + "not": { + "required": [ + "presentationRevision" + ] + } + } + } + ] }, "sessionId": { "type": "string", diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py index 8a02ecb..4e73b7b 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py @@ -25,7 +25,7 @@ from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 -DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2stateforge_protocol/sfp/manifest/v1/manifest.proto\x12\x1astateforge.sfp.manifest.v1\x1a\x1cgoogle/protobuf/struct.proto\"\x96\x02\n\x12GetManifestRequest\x12\x41\n\x1d\x65xpected_provider_instance_id\x18\x01 \x01(\tR\x1a\x65xpectedProviderInstanceId\x12@\n\x1c\x65xpected_endpoint_generation\x18\x02 \x01(\x04R\x1a\x65xpectedEndpointGeneration\x12K\n\"supported_manifest_schema_versions\x18\x03 \x03(\rR\x1fsupportedManifestSchemaVersions\x12.\n\x13\x65xpected_session_id\x18\x04 \x01(\tR\x11\x65xpectedSessionId\"\xc6\x02\n\x13GetManifestResponse\x12\x30\n\x14provider_instance_id\x18\x01 \x01(\tR\x12providerInstanceId\x12/\n\x13\x65ndpoint_generation\x18\x02 \x01(\x04R\x12\x65ndpointGeneration\x12\x36\n\x17manifest_schema_version\x18\x03 \x01(\rR\x15manifestSchemaVersion\x12+\n\x11manifest_revision\x18\x04 \x01(\tR\x10manifestRevision\x12H\n\x08manifest\x18\x05 \x01(\x0b\x32,.stateforge.sfp.manifest.v1.ProviderManifestR\x08manifest\x12\x1d\n\nsession_id\x18\x06 \x01(\tR\tsessionId\"\xbc\x07\n\x10ProviderManifest\x12+\n\x11provider_identity\x18\x01 \x01(\tR\x10providerIdentity\x12\x35\n\x16implementation_version\x18\x02 \x01(\tR\x15implementationVersion\x12!\n\x0c\x64isplay_name\x18\x03 \x01(\tR\x0b\x64isplayName\x12\\\n\noperations\x18\x04 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderManifest.OperationsEntryR\noperations\x12x\n\x14runtime_requirements\x18\x06 \x03(\x0b\x32\x45.stateforge.sfp.manifest.v1.ProviderManifest.RuntimeRequirementsEntryR\x13runtimeRequirements\x12O\n\tplatforms\x18\x07 \x03(\x0b\x32\x31.stateforge.sfp.manifest.v1.PlatformCompatibilityR\tplatforms\x12J\n\x14\x63onfiguration_schema\x18\x08 \x01(\x0b\x32\x17.google.protobuf.StructR\x13\x63onfigurationSchema\x12V\n\x08triggers\x18\t \x03(\x0b\x32:.stateforge.sfp.manifest.v1.ProviderManifest.TriggersEntryR\x08triggers\x1ao\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x46\n\x05value\x18\x02 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.OperationDeclarationR\x05value:\x02\x38\x01\x1av\n\x18RuntimeRequirementsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.RuntimeRequirementR\x05value:\x02\x38\x01\x1ak\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.TriggerDeclarationR\x05value:\x02\x38\x01\"\xb0\x01\n\x14OperationDeclaration\x12:\n\x0cinput_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\x0binputSchema\x12<\n\rresult_schema\x18\x02 \x01(\x0b\x32\x17.google.protobuf.StructR\x0cresultSchema\x12\x1e\n\nimplements\x18\x03 \x03(\tR\nimplements\"e\n\x12RuntimeRequirement\x12 \n\x0b\x64\x65scription\x18\x01 \x01(\tR\x0b\x64\x65scription\x12-\n\x12version_constraint\x18\x02 \x01(\tR\x11versionConstraint\"f\n\x15PlatformCompatibility\x12)\n\x10operating_system\x18\x01 \x01(\tR\x0foperatingSystem\x12\"\n\x0c\x61rchitecture\x18\x02 \x01(\tR\x0c\x61rchitecture\"T\n\x12TriggerDeclaration\x12>\n\x0epayload_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\rpayloadSchema2\x81\x01\n\x0fManifestService\x12n\n\x0bGetManifest\x12..stateforge.sfp.manifest.v1.GetManifestRequest\x1a/.stateforge.sfp.manifest.v1.GetManifestResponseb\x06proto3') +DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2stateforge_protocol/sfp/manifest/v1/manifest.proto\x12\x1astateforge.sfp.manifest.v1\x1a\x1cgoogle/protobuf/struct.proto\"\x96\x02\n\x12GetManifestRequest\x12\x41\n\x1d\x65xpected_provider_instance_id\x18\x01 \x01(\tR\x1a\x65xpectedProviderInstanceId\x12@\n\x1c\x65xpected_endpoint_generation\x18\x02 \x01(\x04R\x1a\x65xpectedEndpointGeneration\x12K\n\"supported_manifest_schema_versions\x18\x03 \x03(\rR\x1fsupportedManifestSchemaVersions\x12.\n\x13\x65xpected_session_id\x18\x04 \x01(\tR\x11\x65xpectedSessionId\"\xf0\x03\n\x13GetManifestResponse\x12\x30\n\x14provider_instance_id\x18\x01 \x01(\tR\x12providerInstanceId\x12/\n\x13\x65ndpoint_generation\x18\x02 \x01(\x04R\x12\x65ndpointGeneration\x12\x36\n\x17manifest_schema_version\x18\x03 \x01(\rR\x15manifestSchemaVersion\x12+\n\x11manifest_revision\x18\x04 \x01(\tR\x10manifestRevision\x12H\n\x08manifest\x18\x05 \x01(\x0b\x32,.stateforge.sfp.manifest.v1.ProviderManifestR\x08manifest\x12\x1d\n\nsession_id\x18\x06 \x01(\tR\tsessionId\x12T\n\x0cpresentation\x18\x07 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.ProviderPresentationR\x0cpresentation\x12\x38\n\x15presentation_revision\x18\x08 \x01(\tH\x00R\x14presentationRevision\x88\x01\x01\x42\x18\n\x16_presentation_revision\"\xbc\x07\n\x10ProviderManifest\x12+\n\x11provider_identity\x18\x01 \x01(\tR\x10providerIdentity\x12\x35\n\x16implementation_version\x18\x02 \x01(\tR\x15implementationVersion\x12!\n\x0c\x64isplay_name\x18\x03 \x01(\tR\x0b\x64isplayName\x12\\\n\noperations\x18\x04 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderManifest.OperationsEntryR\noperations\x12x\n\x14runtime_requirements\x18\x06 \x03(\x0b\x32\x45.stateforge.sfp.manifest.v1.ProviderManifest.RuntimeRequirementsEntryR\x13runtimeRequirements\x12O\n\tplatforms\x18\x07 \x03(\x0b\x32\x31.stateforge.sfp.manifest.v1.PlatformCompatibilityR\tplatforms\x12J\n\x14\x63onfiguration_schema\x18\x08 \x01(\x0b\x32\x17.google.protobuf.StructR\x13\x63onfigurationSchema\x12V\n\x08triggers\x18\t \x03(\x0b\x32:.stateforge.sfp.manifest.v1.ProviderManifest.TriggersEntryR\x08triggers\x1ao\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x46\n\x05value\x18\x02 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.OperationDeclarationR\x05value:\x02\x38\x01\x1av\n\x18RuntimeRequirementsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.RuntimeRequirementR\x05value:\x02\x38\x01\x1ak\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.TriggerDeclarationR\x05value:\x02\x38\x01\"\xb0\x01\n\x14OperationDeclaration\x12:\n\x0cinput_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\x0binputSchema\x12<\n\rresult_schema\x18\x02 \x01(\x0b\x32\x17.google.protobuf.StructR\x0cresultSchema\x12\x1e\n\nimplements\x18\x03 \x03(\tR\nimplements\"e\n\x12RuntimeRequirement\x12 \n\x0b\x64\x65scription\x18\x01 \x01(\tR\x0b\x64\x65scription\x12-\n\x12version_constraint\x18\x02 \x01(\tR\x11versionConstraint\"f\n\x15PlatformCompatibility\x12)\n\x10operating_system\x18\x01 \x01(\tR\x0foperatingSystem\x12\"\n\x0c\x61rchitecture\x18\x02 \x01(\tR\x0c\x61rchitecture\"T\n\x12TriggerDeclaration\x12>\n\x0epayload_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\rpayloadSchema\"\xea\x05\n\x14ProviderPresentation\x12>\n\x1bpresentation_schema_version\x18\x01 \x01(\rR\x19presentationSchemaVersion\x12\x44\n\x08provider\x18\x02 \x01(\x0b\x32(.stateforge.sfp.manifest.v1.ProviderViewR\x08provider\x12`\n\noperations\x18\x03 \x03(\x0b\x32@.stateforge.sfp.manifest.v1.ProviderPresentation.OperationsEntryR\noperations\x12Z\n\x08triggers\x18\x04 \x03(\x0b\x32>.stateforge.sfp.manifest.v1.ProviderPresentation.TriggersEntryR\x08triggers\x12T\n\x06\x61ssets\x18\x05 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderPresentation.AssetsEntryR\x06\x61ssets\x1ah\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12?\n\x05value\x18\x02 \x01(\x0b\x32).stateforge.sfp.manifest.v1.OperationViewR\x05value:\x02\x38\x01\x1a\x64\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12=\n\x05value\x18\x02 \x01(\x0b\x32\'.stateforge.sfp.manifest.v1.TriggerViewR\x05value:\x02\x38\x01\x1ah\n\x0b\x41ssetsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x43\n\x05value\x18\x02 \x01(\x0b\x32-.stateforge.sfp.manifest.v1.PresentationAssetR\x05value:\x02\x38\x01\"\xeb\x01\n\x0cProviderView\x12\x18\n\x07summary\x18\x01 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x02 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x03 \x01(\tR\x0ficonAssetDigest\x12.\n\x13\x62\x61nner_asset_digest\x18\x04 \x01(\tR\x11\x62\x61nnerAssetDigest\x12\x43\n\x06groups\x18\x05 \x03(\x0b\x32+.stateforge.sfp.manifest.v1.CapabilityGroupR\x06groups\"\x85\x01\n\x0f\x43\x61pabilityGroup\x12\x0e\n\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n\x05label\x18\x02 \x01(\tR\x05label\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\"\xa6\x02\n\rOperationView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x18\n\x07summary\x18\x02 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\x12\x19\n\x08group_id\x18\x05 \x01(\tR\x07groupId\x12<\n\x05input\x18\x06 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x05input\x12>\n\x06result\x18\x07 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x06result\"\xe8\x01\n\x0bTriggerView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x18\n\x07summary\x18\x02 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\x12\x19\n\x08group_id\x18\x05 \x01(\tR\x07groupId\x12@\n\x07payload\x18\x06 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x07payload\"\x9b\x02\n\nSchemaView\x12\x1f\n\x0b\x66ield_order\x18\x01 \x03(\tR\nfieldOrder\x12>\n\x06groups\x18\x02 \x03(\x0b\x32&.stateforge.sfp.manifest.v1.FieldGroupR\x06groups\x12J\n\x06\x66ields\x18\x03 \x03(\x0b\x32\x32.stateforge.sfp.manifest.v1.SchemaView.FieldsEntryR\x06\x66ields\x1a`\n\x0b\x46ieldsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12;\n\x05value\x18\x02 \x01(\x0b\x32%.stateforge.sfp.manifest.v1.FieldViewR\x05value:\x02\x38\x01\"l\n\nFieldGroup\x12\x0e\n\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n\x05label\x18\x02 \x01(\tR\x05label\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12\x16\n\x06\x66ields\x18\x04 \x03(\tR\x06\x66ields\"\xf9\x01\n\tFieldView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x1b\n\thelp_text\x18\x02 \x01(\tR\x08helpText\x12 \n\x0bplaceholder\x18\x03 \x01(\tR\x0bplaceholder\x12\x12\n\x04unit\x18\x04 \x01(\tR\x04unit\x12?\n\x06widget\x18\x05 \x01(\x0e\x32\'.stateforge.sfp.manifest.v1.InputWidgetR\x06widget\x12\x42\n\x07\x64isplay\x18\x06 \x01(\x0e\x32(.stateforge.sfp.manifest.v1.DisplayStyleR\x07\x64isplay\"\x95\x01\n\x11PresentationAsset\x12\x1d\n\nmedia_type\x18\x01 \x01(\tR\tmediaType\x12\x18\n\x07\x63ontent\x18\x02 \x01(\x0cR\x07\x63ontent\x12\x14\n\x05width\x18\x03 \x01(\rR\x05width\x12\x16\n\x06height\x18\x04 \x01(\rR\x06height\x12\x19\n\x08\x61lt_text\x18\x05 \x01(\tR\x07\x61ltText*\xa8\x02\n\x0bInputWidget\x12\x1c\n\x18INPUT_WIDGET_UNSPECIFIED\x10\x00\x12\x15\n\x11INPUT_WIDGET_TEXT\x10\x01\x12\x1a\n\x16INPUT_WIDGET_MULTILINE\x10\x02\x12\x17\n\x13INPUT_WIDGET_SECRET\x10\x03\x12\x17\n\x13INPUT_WIDGET_NUMBER\x10\x04\x12\x17\n\x13INPUT_WIDGET_SLIDER\x10\x05\x12\x19\n\x15INPUT_WIDGET_CHECKBOX\x10\x06\x12\x17\n\x13INPUT_WIDGET_SELECT\x10\x07\x12\x16\n\x12INPUT_WIDGET_RADIO\x10\x08\x12\x1a\n\x16INPUT_WIDGET_DATE_TIME\x10\t\x12\x15\n\x11INPUT_WIDGET_JSON\x10\n*\xde\x01\n\x0c\x44isplayStyle\x12\x1d\n\x19\x44ISPLAY_STYLE_UNSPECIFIED\x10\x00\x12\x16\n\x12\x44ISPLAY_STYLE_TEXT\x10\x01\x12\x16\n\x12\x44ISPLAY_STYLE_CODE\x10\x02\x12\x16\n\x12\x44ISPLAY_STYLE_JSON\x10\x03\x12\x17\n\x13\x44ISPLAY_STYLE_TABLE\x10\x04\x12\x17\n\x13\x44ISPLAY_STYLE_BADGE\x10\x05\x12\x18\n\x14\x44ISPLAY_STYLE_METRIC\x10\x06\x12\x1b\n\x17\x44ISPLAY_STYLE_DATE_TIME\x10\x07\x32\x81\x01\n\x0fManifestService\x12n\n\x0bGetManifest\x12..stateforge.sfp.manifest.v1.GetManifestRequest\x1a/.stateforge.sfp.manifest.v1.GetManifestResponseb\x06proto3') _globals = globals() _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals) @@ -38,26 +38,64 @@ _globals['_PROVIDERMANIFEST_RUNTIMEREQUIREMENTSENTRY']._serialized_options = b'8\001' _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._loaded_options = None _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._serialized_options = b'8\001' + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._loaded_options = None + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_options = b'8\001' + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._loaded_options = None + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_options = b'8\001' + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._loaded_options = None + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_options = b'8\001' + _globals['_SCHEMAVIEW_FIELDSENTRY']._loaded_options = None + _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_options = b'8\001' + _globals['_INPUTWIDGET']._serialized_start=4779 + _globals['_INPUTWIDGET']._serialized_end=5075 + _globals['_DISPLAYSTYLE']._serialized_start=5078 + _globals['_DISPLAYSTYLE']._serialized_end=5300 _globals['_GETMANIFESTREQUEST']._serialized_start=113 _globals['_GETMANIFESTREQUEST']._serialized_end=391 _globals['_GETMANIFESTRESPONSE']._serialized_start=394 - _globals['_GETMANIFESTRESPONSE']._serialized_end=720 - _globals['_PROVIDERMANIFEST']._serialized_start=723 - _globals['_PROVIDERMANIFEST']._serialized_end=1679 - _globals['_PROVIDERMANIFEST_OPERATIONSENTRY']._serialized_start=1339 - _globals['_PROVIDERMANIFEST_OPERATIONSENTRY']._serialized_end=1450 - _globals['_PROVIDERMANIFEST_RUNTIMEREQUIREMENTSENTRY']._serialized_start=1452 - _globals['_PROVIDERMANIFEST_RUNTIMEREQUIREMENTSENTRY']._serialized_end=1570 - _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._serialized_start=1572 - _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._serialized_end=1679 - _globals['_OPERATIONDECLARATION']._serialized_start=1682 - _globals['_OPERATIONDECLARATION']._serialized_end=1858 - _globals['_RUNTIMEREQUIREMENT']._serialized_start=1860 - _globals['_RUNTIMEREQUIREMENT']._serialized_end=1961 - _globals['_PLATFORMCOMPATIBILITY']._serialized_start=1963 - _globals['_PLATFORMCOMPATIBILITY']._serialized_end=2065 - _globals['_TRIGGERDECLARATION']._serialized_start=2067 - _globals['_TRIGGERDECLARATION']._serialized_end=2151 - _globals['_MANIFESTSERVICE']._serialized_start=2154 - _globals['_MANIFESTSERVICE']._serialized_end=2283 + _globals['_GETMANIFESTRESPONSE']._serialized_end=890 + _globals['_PROVIDERMANIFEST']._serialized_start=893 + _globals['_PROVIDERMANIFEST']._serialized_end=1849 + _globals['_PROVIDERMANIFEST_OPERATIONSENTRY']._serialized_start=1509 + _globals['_PROVIDERMANIFEST_OPERATIONSENTRY']._serialized_end=1620 + _globals['_PROVIDERMANIFEST_RUNTIMEREQUIREMENTSENTRY']._serialized_start=1622 + _globals['_PROVIDERMANIFEST_RUNTIMEREQUIREMENTSENTRY']._serialized_end=1740 + _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._serialized_start=1742 + _globals['_PROVIDERMANIFEST_TRIGGERSENTRY']._serialized_end=1849 + _globals['_OPERATIONDECLARATION']._serialized_start=1852 + _globals['_OPERATIONDECLARATION']._serialized_end=2028 + _globals['_RUNTIMEREQUIREMENT']._serialized_start=2030 + _globals['_RUNTIMEREQUIREMENT']._serialized_end=2131 + _globals['_PLATFORMCOMPATIBILITY']._serialized_start=2133 + _globals['_PLATFORMCOMPATIBILITY']._serialized_end=2235 + _globals['_TRIGGERDECLARATION']._serialized_start=2237 + _globals['_TRIGGERDECLARATION']._serialized_end=2321 + _globals['_PROVIDERPRESENTATION']._serialized_start=2324 + _globals['_PROVIDERPRESENTATION']._serialized_end=3070 + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_start=2758 + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_end=2862 + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_start=2864 + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_end=2964 + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_start=2966 + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_end=3070 + _globals['_PROVIDERVIEW']._serialized_start=3073 + _globals['_PROVIDERVIEW']._serialized_end=3308 + _globals['_CAPABILITYGROUP']._serialized_start=3311 + _globals['_CAPABILITYGROUP']._serialized_end=3444 + _globals['_OPERATIONVIEW']._serialized_start=3447 + _globals['_OPERATIONVIEW']._serialized_end=3741 + _globals['_TRIGGERVIEW']._serialized_start=3744 + _globals['_TRIGGERVIEW']._serialized_end=3976 + _globals['_SCHEMAVIEW']._serialized_start=3979 + _globals['_SCHEMAVIEW']._serialized_end=4262 + _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_start=4166 + _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_end=4262 + _globals['_FIELDGROUP']._serialized_start=4264 + _globals['_FIELDGROUP']._serialized_end=4372 + _globals['_FIELDVIEW']._serialized_start=4375 + _globals['_FIELDVIEW']._serialized_end=4624 + _globals['_PRESENTATIONASSET']._serialized_start=4627 + _globals['_PRESENTATIONASSET']._serialized_end=4776 + _globals['_MANIFESTSERVICE']._serialized_start=5303 + _globals['_MANIFESTSERVICE']._serialized_end=5432 # @@protoc_insertion_point(module_scope) diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi index 217b8ee..c778a2b 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi @@ -8,6 +8,7 @@ from google.protobuf import descriptor as _descriptor from google.protobuf import message as _message from google.protobuf import struct_pb2 as _struct_pb2 from google.protobuf.internal import containers as _containers +from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper import builtins as _builtins import sys import typing as _typing @@ -19,6 +20,72 @@ else: DESCRIPTOR: _descriptor.FileDescriptor +class _InputWidget: + ValueType = _typing.NewType("ValueType", _builtins.int) + V: _TypeAlias = ValueType # noqa: Y015 + +class _InputWidgetEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_InputWidget.ValueType], _builtins.type): + DESCRIPTOR: _descriptor.EnumDescriptor + INPUT_WIDGET_UNSPECIFIED: _InputWidget.ValueType # 0 + INPUT_WIDGET_TEXT: _InputWidget.ValueType # 1 + INPUT_WIDGET_MULTILINE: _InputWidget.ValueType # 2 + INPUT_WIDGET_SECRET: _InputWidget.ValueType # 3 + INPUT_WIDGET_NUMBER: _InputWidget.ValueType # 4 + INPUT_WIDGET_SLIDER: _InputWidget.ValueType # 5 + INPUT_WIDGET_CHECKBOX: _InputWidget.ValueType # 6 + INPUT_WIDGET_SELECT: _InputWidget.ValueType # 7 + INPUT_WIDGET_RADIO: _InputWidget.ValueType # 8 + INPUT_WIDGET_DATE_TIME: _InputWidget.ValueType # 9 + INPUT_WIDGET_JSON: _InputWidget.ValueType # 10 + +class InputWidget(_InputWidget, metaclass=_InputWidgetEnumTypeWrapper): + """InputWidget selects an optional input control compatible with a field's + authoritative JSON Schema. Unspecified delegates entirely to the renderer. + """ + +INPUT_WIDGET_UNSPECIFIED: InputWidget.ValueType # 0 +INPUT_WIDGET_TEXT: InputWidget.ValueType # 1 +INPUT_WIDGET_MULTILINE: InputWidget.ValueType # 2 +INPUT_WIDGET_SECRET: InputWidget.ValueType # 3 +INPUT_WIDGET_NUMBER: InputWidget.ValueType # 4 +INPUT_WIDGET_SLIDER: InputWidget.ValueType # 5 +INPUT_WIDGET_CHECKBOX: InputWidget.ValueType # 6 +INPUT_WIDGET_SELECT: InputWidget.ValueType # 7 +INPUT_WIDGET_RADIO: InputWidget.ValueType # 8 +INPUT_WIDGET_DATE_TIME: InputWidget.ValueType # 9 +INPUT_WIDGET_JSON: InputWidget.ValueType # 10 +Global___InputWidget: _TypeAlias = InputWidget # noqa: Y015 + +class _DisplayStyle: + ValueType = _typing.NewType("ValueType", _builtins.int) + V: _TypeAlias = ValueType # noqa: Y015 + +class _DisplayStyleEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_DisplayStyle.ValueType], _builtins.type): + DESCRIPTOR: _descriptor.EnumDescriptor + DISPLAY_STYLE_UNSPECIFIED: _DisplayStyle.ValueType # 0 + DISPLAY_STYLE_TEXT: _DisplayStyle.ValueType # 1 + DISPLAY_STYLE_CODE: _DisplayStyle.ValueType # 2 + DISPLAY_STYLE_JSON: _DisplayStyle.ValueType # 3 + DISPLAY_STYLE_TABLE: _DisplayStyle.ValueType # 4 + DISPLAY_STYLE_BADGE: _DisplayStyle.ValueType # 5 + DISPLAY_STYLE_METRIC: _DisplayStyle.ValueType # 6 + DISPLAY_STYLE_DATE_TIME: _DisplayStyle.ValueType # 7 + +class DisplayStyle(_DisplayStyle, metaclass=_DisplayStyleEnumTypeWrapper): + """DisplayStyle selects an optional read-only presentation compatible with a + field's authoritative JSON Schema. Unspecified delegates to the renderer. + """ + +DISPLAY_STYLE_UNSPECIFIED: DisplayStyle.ValueType # 0 +DISPLAY_STYLE_TEXT: DisplayStyle.ValueType # 1 +DISPLAY_STYLE_CODE: DisplayStyle.ValueType # 2 +DISPLAY_STYLE_JSON: DisplayStyle.ValueType # 3 +DISPLAY_STYLE_TABLE: DisplayStyle.ValueType # 4 +DISPLAY_STYLE_BADGE: DisplayStyle.ValueType # 5 +DISPLAY_STYLE_METRIC: DisplayStyle.ValueType # 6 +DISPLAY_STYLE_DATE_TIME: DisplayStyle.ValueType # 7 +Global___DisplayStyle: _TypeAlias = DisplayStyle # noqa: Y015 + @_typing.final class GetManifestRequest(_message.Message): """GetManifestRequest binds the read to the session confirmed by Handshake. @@ -77,6 +144,8 @@ class GetManifestResponse(_message.Message): MANIFEST_REVISION_FIELD_NUMBER: _builtins.int MANIFEST_FIELD_NUMBER: _builtins.int SESSION_ID_FIELD_NUMBER: _builtins.int + PRESENTATION_FIELD_NUMBER: _builtins.int + PRESENTATION_REVISION_FIELD_NUMBER: _builtins.int provider_instance_id: _builtins.str """Must equal the request's expected identity and the negotiated session.""" endpoint_generation: _builtins.int @@ -94,10 +163,23 @@ class GetManifestResponse(_message.Message): The Agent must match it to both the request and its current session before accepting or reusing a cached declaration. Not part of manifest_revision. """ + presentation_revision: _builtins.str + """Present exactly when presentation is present. "sha256:" plus 64 lowercase + hex digits over the canonical presentation preimage defined by this + package. Session ID and endpoint generation are excluded. + """ @_builtins.property def manifest(self) -> Global___ProviderManifest: """Required. At most 1 MiB of canonical JSON for the revision preimage.""" + @_builtins.property + def presentation(self) -> Global___ProviderPresentation: + """Optional declarative presentation snapshot. Operational JSON Schemas + remain sufficient to render every declared capability when this field is + absent, unsupported or rejected. Presentation never changes execution + semantics and is not part of manifest_revision. + """ + def __init__( self, *, @@ -107,12 +189,16 @@ class GetManifestResponse(_message.Message): manifest_revision: _builtins.str = ..., manifest: Global___ProviderManifest | None = ..., session_id: _builtins.str = ..., + presentation: Global___ProviderPresentation | None = ..., + presentation_revision: _builtins.str | None = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _typing.Literal["manifest", b"manifest"] # noqa: Y015 + _HasFieldArgType: _TypeAlias = _typing.Literal["_presentation_revision", b"_presentation_revision", "manifest", b"manifest", "presentation", b"presentation", "presentation_revision", b"presentation_revision"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["endpoint_generation", b"endpoint_generation", "manifest", b"manifest", "manifest_revision", b"manifest_revision", "manifest_schema_version", b"manifest_schema_version", "provider_instance_id", b"provider_instance_id", "session_id", b"session_id"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["_presentation_revision", b"_presentation_revision", "endpoint_generation", b"endpoint_generation", "manifest", b"manifest", "manifest_revision", b"manifest_revision", "manifest_schema_version", b"manifest_schema_version", "presentation", b"presentation", "presentation_revision", b"presentation_revision", "provider_instance_id", b"provider_instance_id", "session_id", b"session_id"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... - def WhichOneof(self, oneof_group: _Never) -> None: ... + _WhichOneofReturnType__presentation_revision: _TypeAlias = _typing.Literal["presentation_revision"] # noqa: Y015 + _WhichOneofArgType__presentation_revision: _TypeAlias = _typing.Literal["_presentation_revision", b"_presentation_revision"] # noqa: Y015 + def WhichOneof(self, oneof_group: _WhichOneofArgType__presentation_revision) -> _WhichOneofReturnType__presentation_revision | None: ... Global___GetManifestResponse: _TypeAlias = GetManifestResponse # noqa: Y015 @@ -373,3 +459,428 @@ class TriggerDeclaration(_message.Message): def WhichOneof(self, oneof_group: _Never) -> None: ... Global___TriggerDeclaration: _TypeAlias = TriggerDeclaration # noqa: Y015 + +@_typing.final +class ProviderPresentation(_message.Message): + """ProviderPresentation is an optional, independently revised visual overlay + on an accepted ProviderManifest. Maps use the exact operation and trigger + identifiers declared by that manifest. Presentation cannot add, remove or + redefine capabilities or their JSON Schemas. + """ + + DESCRIPTOR: _descriptor.Descriptor + + @_typing.final + class OperationsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___OperationView: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___OperationView | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + @_typing.final + class TriggersEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___TriggerView: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___TriggerView | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + @_typing.final + class AssetsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___PresentationAsset: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___PresentationAsset | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + PRESENTATION_SCHEMA_VERSION_FIELD_NUMBER: _builtins.int + PROVIDER_FIELD_NUMBER: _builtins.int + OPERATIONS_FIELD_NUMBER: _builtins.int + TRIGGERS_FIELD_NUMBER: _builtins.int + ASSETS_FIELD_NUMBER: _builtins.int + presentation_schema_version: _builtins.int + """Presentation document version. Version 1 is defined by this package.""" + @_builtins.property + def provider(self) -> Global___ProviderView: + """Optional Provider-level description, branding and visual groups.""" + + @_builtins.property + def operations(self) -> _containers.MessageMap[_builtins.str, Global___OperationView]: + """Optional overlays keyed by declared operation identifier.""" + + @_builtins.property + def triggers(self) -> _containers.MessageMap[_builtins.str, Global___TriggerView]: + """Optional overlays keyed by declared trigger identifier.""" + + @_builtins.property + def assets(self) -> _containers.MessageMap[_builtins.str, Global___PresentationAsset]: + """Embedded content-addressed visuals keyed by their sha256 digest.""" + + def __init__( + self, + *, + presentation_schema_version: _builtins.int = ..., + provider: Global___ProviderView | None = ..., + operations: _abc.Mapping[_builtins.str, Global___OperationView] | None = ..., + triggers: _abc.Mapping[_builtins.str, Global___TriggerView] | None = ..., + assets: _abc.Mapping[_builtins.str, Global___PresentationAsset] | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["provider", b"provider"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["assets", b"assets", "operations", b"operations", "presentation_schema_version", b"presentation_schema_version", "provider", b"provider", "triggers", b"triggers"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___ProviderPresentation: _TypeAlias = ProviderPresentation # noqa: Y015 + +@_typing.final +class ProviderView(_message.Message): + """ProviderView describes the Provider itself. Group order is declaration order; + operations and triggers opt into a group by ID, and ungrouped capabilities + remain visible through schema-derived rendering. + """ + + DESCRIPTOR: _descriptor.Descriptor + + SUMMARY_FIELD_NUMBER: _builtins.int + DESCRIPTION_FIELD_NUMBER: _builtins.int + ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int + BANNER_ASSET_DIGEST_FIELD_NUMBER: _builtins.int + GROUPS_FIELD_NUMBER: _builtins.int + summary: _builtins.str + description: _builtins.str + icon_asset_digest: _builtins.str + banner_asset_digest: _builtins.str + @_builtins.property + def groups(self) -> _containers.RepeatedCompositeFieldContainer[Global___CapabilityGroup]: ... + def __init__( + self, + *, + summary: _builtins.str = ..., + description: _builtins.str = ..., + icon_asset_digest: _builtins.str = ..., + banner_asset_digest: _builtins.str = ..., + groups: _abc.Iterable[Global___CapabilityGroup] | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["banner_asset_digest", b"banner_asset_digest", "description", b"description", "groups", b"groups", "icon_asset_digest", b"icon_asset_digest", "summary", b"summary"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___ProviderView: _TypeAlias = ProviderView # noqa: Y015 + +@_typing.final +class CapabilityGroup(_message.Message): + """CapabilityGroup supplies optional visual organization without duplicating + operation or trigger membership. + """ + + DESCRIPTOR: _descriptor.Descriptor + + ID_FIELD_NUMBER: _builtins.int + LABEL_FIELD_NUMBER: _builtins.int + DESCRIPTION_FIELD_NUMBER: _builtins.int + ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int + id: _builtins.str + label: _builtins.str + description: _builtins.str + icon_asset_digest: _builtins.str + def __init__( + self, + *, + id: _builtins.str = ..., + label: _builtins.str = ..., + description: _builtins.str = ..., + icon_asset_digest: _builtins.str = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "icon_asset_digest", b"icon_asset_digest", "id", b"id", "label", b"label"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___CapabilityGroup: _TypeAlias = CapabilityGroup # noqa: Y015 + +@_typing.final +class OperationView(_message.Message): + """OperationView supplies labels and schema-addressed overlays for one declared + operation. Empty group_id means that the operation is not grouped. + """ + + DESCRIPTOR: _descriptor.Descriptor + + LABEL_FIELD_NUMBER: _builtins.int + SUMMARY_FIELD_NUMBER: _builtins.int + DESCRIPTION_FIELD_NUMBER: _builtins.int + ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int + GROUP_ID_FIELD_NUMBER: _builtins.int + INPUT_FIELD_NUMBER: _builtins.int + RESULT_FIELD_NUMBER: _builtins.int + label: _builtins.str + summary: _builtins.str + description: _builtins.str + icon_asset_digest: _builtins.str + group_id: _builtins.str + @_builtins.property + def input(self) -> Global___SchemaView: ... + @_builtins.property + def result(self) -> Global___SchemaView: ... + def __init__( + self, + *, + label: _builtins.str = ..., + summary: _builtins.str = ..., + description: _builtins.str = ..., + icon_asset_digest: _builtins.str = ..., + group_id: _builtins.str = ..., + input: Global___SchemaView | None = ..., + result: Global___SchemaView | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["input", b"input", "result", b"result"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "group_id", b"group_id", "icon_asset_digest", b"icon_asset_digest", "input", b"input", "label", b"label", "result", b"result", "summary", b"summary"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___OperationView: _TypeAlias = OperationView # noqa: Y015 + +@_typing.final +class TriggerView(_message.Message): + """TriggerView supplies labels and a schema-addressed overlay for one declared + trigger. Empty group_id means that the trigger is not grouped. + """ + + DESCRIPTOR: _descriptor.Descriptor + + LABEL_FIELD_NUMBER: _builtins.int + SUMMARY_FIELD_NUMBER: _builtins.int + DESCRIPTION_FIELD_NUMBER: _builtins.int + ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int + GROUP_ID_FIELD_NUMBER: _builtins.int + PAYLOAD_FIELD_NUMBER: _builtins.int + label: _builtins.str + summary: _builtins.str + description: _builtins.str + icon_asset_digest: _builtins.str + group_id: _builtins.str + @_builtins.property + def payload(self) -> Global___SchemaView: ... + def __init__( + self, + *, + label: _builtins.str = ..., + summary: _builtins.str = ..., + description: _builtins.str = ..., + icon_asset_digest: _builtins.str = ..., + group_id: _builtins.str = ..., + payload: Global___SchemaView | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["payload", b"payload"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "group_id", b"group_id", "icon_asset_digest", b"icon_asset_digest", "label", b"label", "payload", b"payload", "summary", b"summary"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___TriggerView: _TypeAlias = TriggerView # noqa: Y015 + +@_typing.final +class SchemaView(_message.Message): + """SchemaView adds optional ordering, grouping and compatible render hints to a + JSON Schema. Every pointer addresses a field schema in the corresponding + operation input/result or trigger payload schema. Unmentioned fields remain + visible and retain their schema-defined semantics. + """ + + DESCRIPTOR: _descriptor.Descriptor + + @_typing.final + class FieldsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___FieldView: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___FieldView | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + FIELD_ORDER_FIELD_NUMBER: _builtins.int + GROUPS_FIELD_NUMBER: _builtins.int + FIELDS_FIELD_NUMBER: _builtins.int + @_builtins.property + def field_order(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]: ... + @_builtins.property + def groups(self) -> _containers.RepeatedCompositeFieldContainer[Global___FieldGroup]: ... + @_builtins.property + def fields(self) -> _containers.MessageMap[_builtins.str, Global___FieldView]: ... + def __init__( + self, + *, + field_order: _abc.Iterable[_builtins.str] | None = ..., + groups: _abc.Iterable[Global___FieldGroup] | None = ..., + fields: _abc.Mapping[_builtins.str, Global___FieldView] | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["field_order", b"field_order", "fields", b"fields", "groups", b"groups"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___SchemaView: _TypeAlias = SchemaView # noqa: Y015 + +@_typing.final +class FieldGroup(_message.Message): + """FieldGroup visually groups schema fields. Field pointers may appear in at + most one group and group order is declaration order. + """ + + DESCRIPTOR: _descriptor.Descriptor + + ID_FIELD_NUMBER: _builtins.int + LABEL_FIELD_NUMBER: _builtins.int + DESCRIPTION_FIELD_NUMBER: _builtins.int + FIELDS_FIELD_NUMBER: _builtins.int + id: _builtins.str + label: _builtins.str + description: _builtins.str + @_builtins.property + def fields(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]: ... + def __init__( + self, + *, + id: _builtins.str = ..., + label: _builtins.str = ..., + description: _builtins.str = ..., + fields: _abc.Iterable[_builtins.str] | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "fields", b"fields", "id", b"id", "label", b"label"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___FieldGroup: _TypeAlias = FieldGroup # noqa: Y015 + +@_typing.final +class FieldView(_message.Message): + """FieldView supplies optional text and compatible render preferences for one + schema field. It cannot change validation, requiredness or visibility. + """ + + DESCRIPTOR: _descriptor.Descriptor + + LABEL_FIELD_NUMBER: _builtins.int + HELP_TEXT_FIELD_NUMBER: _builtins.int + PLACEHOLDER_FIELD_NUMBER: _builtins.int + UNIT_FIELD_NUMBER: _builtins.int + WIDGET_FIELD_NUMBER: _builtins.int + DISPLAY_FIELD_NUMBER: _builtins.int + label: _builtins.str + help_text: _builtins.str + placeholder: _builtins.str + unit: _builtins.str + widget: Global___InputWidget.ValueType + display: Global___DisplayStyle.ValueType + def __init__( + self, + *, + label: _builtins.str = ..., + help_text: _builtins.str = ..., + placeholder: _builtins.str = ..., + unit: _builtins.str = ..., + widget: Global___InputWidget.ValueType = ..., + display: Global___DisplayStyle.ValueType = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["display", b"display", "help_text", b"help_text", "label", b"label", "placeholder", b"placeholder", "unit", b"unit", "widget", b"widget"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___FieldView: _TypeAlias = FieldView # noqa: Y015 + +@_typing.final +class PresentationAsset(_message.Message): + """PresentationAsset is embedded, content-addressed media. The map key is the + sha256 digest of content. Remote URLs and filesystem paths have no wire field. + """ + + DESCRIPTOR: _descriptor.Descriptor + + MEDIA_TYPE_FIELD_NUMBER: _builtins.int + CONTENT_FIELD_NUMBER: _builtins.int + WIDTH_FIELD_NUMBER: _builtins.int + HEIGHT_FIELD_NUMBER: _builtins.int + ALT_TEXT_FIELD_NUMBER: _builtins.int + media_type: _builtins.str + content: _builtins.bytes + width: _builtins.int + height: _builtins.int + alt_text: _builtins.str + def __init__( + self, + *, + media_type: _builtins.str = ..., + content: _builtins.bytes = ..., + width: _builtins.int = ..., + height: _builtins.int = ..., + alt_text: _builtins.str = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["alt_text", b"alt_text", "content", b"content", "height", b"height", "media_type", b"media_type", "width", b"width"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + +Global___PresentationAsset: _TypeAlias = PresentationAsset # noqa: Y015 diff --git a/src/stateforge_protocol/sfp/manifest/v1/validation.py b/src/stateforge_protocol/sfp/manifest/v1/validation.py index 7eddba4..c340178 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/validation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/validation.py @@ -4,11 +4,13 @@ import hashlib from dataclasses import dataclass +from enum import StrEnum from typing import TYPE_CHECKING, Any, Final, cast from uuid import UUID from stateforge_protocol.sfp import _validation from stateforge_protocol.sfp.manifest.v1 import ( + _presentation, _schema_inspection, contract, manifest_pb2, @@ -23,13 +25,21 @@ "ManifestRevisionKey", "ManifestValidationError", "ManifestValidationLimits", + "PresentationRevisionKey", + "PresentationValidationStatus", + "ValidatedManifestExchange", "bounded_json", "canonical_bytes", + "canonical_presentation_bytes", "compute_manifest_revision", + "compute_presentation_revision", "contract_validator", "validate_manifest_document", + "validate_manifest_exchange", "validate_manifest_key", "validate_manifest_response", + "validate_presentation_document", + "validate_presentation_key", "validate_schema", "validate_structure", ] @@ -86,6 +96,36 @@ class ManifestRevisionKey: revision: str +@dataclass(frozen=True, slots=True) +class PresentationRevisionKey: + """Identify one valid presentation bound to an operational manifest.""" + + provider_instance_id: UUID + manifest_revision: str + schema_version: int + revision: str + + +class PresentationValidationStatus(StrEnum): + """Describe how an optional presentation snapshot was handled.""" + + ABSENT = "absent" + ACCEPTED = "accepted" + UNSUPPORTED = "unsupported" + INVALID = "invalid" + + +@dataclass(frozen=True, slots=True) +class ValidatedManifestExchange: + """Retain independently validated operational and presentation data.""" + + manifest_key: ManifestRevisionKey + manifest_document: bytes + presentation_status: PresentationValidationStatus + presentation_key: PresentationRevisionKey | None = None + presentation_document: bytes | None = None + + def bounded_json( value: object, path: str, @@ -113,6 +153,16 @@ def canonical_bytes(value: dict[str, Any]) -> bytes: ) +def canonical_presentation_bytes(value: dict[str, Any]) -> bytes: + """Return bounded RFC 8785 bytes for a presentation document.""" + return _VALIDATION.canonicalize_json( + value, + maximum_bytes=contract.MAX_PRESENTATION_REVISION_PREIMAGE_BYTES, + limit_message="presentation: canonical preimage limit exceeded", + invalid_message="presentation: non-interoperable JSON value", + ) + + def contract_validator(definition: str) -> Draft202012Validator: """Load a validation projection from the installed Protocol package.""" return _SCHEMA.validator(definition) @@ -183,22 +233,100 @@ def compute_manifest_revision( return "sha256:" + hashlib.sha256(preimage).hexdigest() -def validate_manifest_response( - response: manifest_pb2.GetManifestResponse, +def compute_presentation_revision( + presentation: dict[str, Any], + manifest_revision: str, + provider_instance_id: str, +) -> str: + """Return the revision for presentation bound to one manifest.""" + validate_structure( + provider_instance_id, "instanceId", "providerInstanceId" + ) + if not _SCHEMA.is_valid(manifest_revision, "revision"): + raise ManifestValidationError( + "presentation: manifest revision is invalid" + ) + preimage = canonical_presentation_bytes( + { + "manifestRevision": manifest_revision, + "presentation": presentation, + "providerInstanceId": provider_instance_id, + } + ) + return "sha256:" + hashlib.sha256(preimage).hexdigest() + + +def validate_presentation_document( + presentation: manifest_pb2.ProviderPresentation, + manifest: dict[str, Any], *, limits: ManifestValidationLimits = DEFAULT_VALIDATION_LIMITS, ) -> bytes: - """Validate a response and return its canonical manifest bytes.""" + """Validate one complete presentation overlay and its references.""" + presentation = _VALIDATION.require_instance( + presentation, + manifest_pb2.ProviderPresentation, + "presentation: expected ProviderPresentation", + ) + document = cast( + dict[str, Any], + _VALIDATION.project_message(presentation, "presentation"), + ) + _VALIDATION.require_bounded_json( + document, + "presentation", + maximum_depth=contract.MAX_EMBEDDED_JSON_DEPTH + 4, + maximum_nodes=limits.max_json_nodes, + maximum_bytes=contract.MAX_PRESENTATION_REVISION_PREIMAGE_BYTES, + ) + validate_structure(document, "providerPresentation", "presentation") + _presentation.validate_presentation_semantics( + document, + manifest, + presentation, + error_type=ManifestValidationError, + ) + return canonical_presentation_bytes(document) + + +def validate_manifest_exchange( + response: manifest_pb2.GetManifestResponse, + *, + limits: ManifestValidationLimits = DEFAULT_VALIDATION_LIMITS, +) -> ValidatedManifestExchange: + """Validate a manifest and independently accept its presentation.""" + response = _VALIDATION.require_instance( + response, + manifest_pb2.GetManifestResponse, + "response: expected GetManifestResponse", + ) + _VALIDATION.require_serialized_size( + response, + maximum_bytes=contract.MAX_RESPONSE_BYTES, + path="response", + ) projected = _VALIDATION.project_message(response, "response") - bounded_json( + _VALIDATION.require_bounded_json( projected, "response", - depth_limit=contract.MAX_EMBEDDED_JSON_DEPTH + 4, - limits=limits, + maximum_depth=contract.MAX_EMBEDDED_JSON_DEPTH + 6, + maximum_nodes=limits.max_json_nodes, + maximum_bytes=contract.MAX_RESPONSE_BYTES * 2, ) - validate_structure(projected, "getManifestResponse", "response") + operational = { + key: projected[key] + for key in ( + "providerInstanceId", + "endpointGeneration", + "manifestSchemaVersion", + "manifestRevision", + "manifest", + "sessionId", + ) + } + validate_structure(operational, "getManifestResponse", "response") manifest = cast(dict[str, Any], projected["manifest"]) - document = validate_manifest_document(manifest, limits=limits) + manifest_document = validate_manifest_document(manifest, limits=limits) revision = compute_manifest_revision( manifest, response.manifest_schema_version, @@ -206,7 +334,89 @@ def validate_manifest_response( ) if revision != response.manifest_revision: raise ManifestValidationError("response: manifest revision mismatch") - return document + manifest_key = validate_manifest_key( + response.provider_instance_id, + response.manifest_schema_version, + response.manifest_revision, + ) + + if not response.HasField("presentation"): + status = ( + PresentationValidationStatus.ABSENT + if not response.HasField("presentation_revision") + else PresentationValidationStatus.INVALID + ) + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=status, + ) + if not _SCHEMA.is_valid(response.presentation_revision, "revision"): + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=PresentationValidationStatus.INVALID, + ) + presentation_schema_version = ( + response.presentation.presentation_schema_version + ) + if presentation_schema_version == 0: + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=PresentationValidationStatus.INVALID, + ) + if presentation_schema_version != contract.PRESENTATION_SCHEMA_VERSION: + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=PresentationValidationStatus.UNSUPPORTED, + ) + + presentation = cast(dict[str, Any], projected["presentation"]) + try: + presentation_document = validate_presentation_document( + response.presentation, + manifest, + limits=limits, + ) + expected_revision = compute_presentation_revision( + presentation, + response.manifest_revision, + response.provider_instance_id, + ) + if expected_revision != response.presentation_revision: + raise ManifestValidationError("presentation: revision mismatch") + presentation_key = validate_presentation_key( + response.provider_instance_id, + response.manifest_revision, + presentation_schema_version, + response.presentation_revision, + ) + except ManifestValidationError: + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=PresentationValidationStatus.INVALID, + ) + return ValidatedManifestExchange( + manifest_key=manifest_key, + manifest_document=manifest_document, + presentation_status=PresentationValidationStatus.ACCEPTED, + presentation_key=presentation_key, + presentation_document=presentation_document, + ) + + +def validate_manifest_response( + response: manifest_pb2.GetManifestResponse, + *, + limits: ManifestValidationLimits = DEFAULT_VALIDATION_LIMITS, +) -> bytes: + """Validate a response and return its canonical operational manifest.""" + return validate_manifest_exchange( + response, limits=limits + ).manifest_document def validate_manifest_key( @@ -229,6 +439,36 @@ def validate_manifest_key( ) +def validate_presentation_key( + provider_instance_id: str, + manifest_revision: str, + presentation_schema_version: int, + presentation_revision: str, +) -> PresentationRevisionKey: + """Validate the scalar key for an accepted presentation snapshot.""" + if not _SCHEMA.is_valid(provider_instance_id, "instanceId"): + raise ManifestValidationError( + "presentation: provider identity must be a canonical UUIDv4" + ) + if not _SCHEMA.is_valid(manifest_revision, "revision"): + raise ManifestValidationError( + "presentation: manifest revision is invalid" + ) + _VALIDATION.require_equal( + presentation_schema_version, + contract.PRESENTATION_SCHEMA_VERSION, + "presentation: schema version is unsupported", + ) + if not _SCHEMA.is_valid(presentation_revision, "revision"): + raise ManifestValidationError("presentation: revision is invalid") + return PresentationRevisionKey( + provider_instance_id=UUID(provider_instance_id), + manifest_revision=manifest_revision, + schema_version=presentation_schema_version, + revision=presentation_revision, + ) + + def _validate_embedded_schemas( manifest: dict[str, Any], *, diff --git a/tests/fixtures/manifest/presentation-response.json b/tests/fixtures/manifest/presentation-response.json new file mode 100644 index 0000000..4603056 --- /dev/null +++ b/tests/fixtures/manifest/presentation-response.json @@ -0,0 +1,242 @@ +{ + "providerInstanceId": "7f7db7d8-68b4-4f71-9769-065b5c4f941c", + "endpointGeneration": "4", + "manifestSchemaVersion": 1, + "manifest": { + "providerIdentity": "stateforge.git", + "implementationVersion": "1.0.0", + "displayName": "Git Provider", + "operations": { + "stateforge.git/reference.resolve@1": { + "inputSchema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "depth": { + "type": "integer", + "minimum": 1, + "maximum": 10 + }, + "token": { + "type": "string", + "writeOnly": true + } + }, + "required": [ + "repository" + ], + "additionalProperties": false + }, + "resultSchema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "commit": { + "type": "string" + }, + "changed": { + "type": "boolean" + } + }, + "required": [ + "commit" + ], + "additionalProperties": false + }, + "implements": [] + } + }, + "runtimeRequirements": { + "executable.git": { + "description": "Git executable available to the Provider", + "versionConstraint": ">=2.40" + } + }, + "platforms": [ + { + "operatingSystem": "linux", + "architecture": "x86_64" + } + ], + "configurationSchema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "token": { + "type": "string", + "writeOnly": true + } + }, + "required": [ + "repository" + ], + "additionalProperties": false + }, + "triggers": { + "stateforge.git/reference.changed@1": { + "payloadSchema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "reference": { + "type": "string" + }, + "previous": { + "type": "string" + } + }, + "required": [ + "reference" + ], + "additionalProperties": false + } + } + } + }, + "manifestRevision": "sha256:c836c97c8f170ea22b7c9002aa6075d84746dab7bbe3c822f628fd1176fd3c56", + "sessionId": "manifest-session-A", + "presentation": { + "presentationSchemaVersion": 1, + "provider": { + "summary": "Inspect and resolve Git references.", + "description": "A local Provider for Git repository state.", + "iconAssetDigest": "sha256:8c5dec37f2aba701bd79272fc7fe4d34292623e531df7fd23b95cb3c96034741", + "bannerAssetDigest": "", + "groups": [ + { + "id": "repository", + "label": "Repository", + "description": "Repository inspection and reference operations.", + "iconAssetDigest": "" + } + ] + }, + "operations": { + "stateforge.git/reference.resolve@1": { + "label": "Resolve reference", + "summary": "Resolve a Git reference to a commit.", + "description": "Reads a repository reference without changing it.", + "iconAssetDigest": "", + "groupId": "repository", + "input": { + "fieldOrder": [ + "/properties/repository", + "/properties/depth", + "/properties/token" + ], + "groups": [ + { + "id": "credentials", + "label": "Credentials", + "description": "Optional credentials for repository access.", + "fields": [ + "/properties/token" + ] + } + ], + "fields": { + "/properties/repository": { + "label": "Repository", + "helpText": "Repository path or canonical name.", + "placeholder": "owner/repository", + "unit": "", + "widget": "INPUT_WIDGET_TEXT", + "display": "DISPLAY_STYLE_UNSPECIFIED" + }, + "/properties/depth": { + "label": "Depth", + "helpText": "Maximum history depth.", + "placeholder": "", + "unit": "commits", + "widget": "INPUT_WIDGET_SLIDER", + "display": "DISPLAY_STYLE_METRIC" + }, + "/properties/token": { + "label": "Access token", + "helpText": "Used only for this request.", + "placeholder": "", + "unit": "", + "widget": "INPUT_WIDGET_SECRET", + "display": "DISPLAY_STYLE_UNSPECIFIED" + } + } + }, + "result": { + "fieldOrder": [ + "/properties/commit", + "/properties/changed" + ], + "groups": [], + "fields": { + "/properties/commit": { + "label": "Commit", + "helpText": "Resolved commit identifier.", + "placeholder": "", + "unit": "", + "widget": "INPUT_WIDGET_UNSPECIFIED", + "display": "DISPLAY_STYLE_CODE" + }, + "/properties/changed": { + "label": "Changed", + "helpText": "Whether the reference changed.", + "placeholder": "", + "unit": "", + "widget": "INPUT_WIDGET_UNSPECIFIED", + "display": "DISPLAY_STYLE_BADGE" + } + } + } + } + }, + "triggers": { + "stateforge.git/reference.changed@1": { + "label": "Reference changed", + "summary": "A repository reference moved.", + "description": "Published after a tracked reference changes.", + "iconAssetDigest": "", + "groupId": "repository", + "payload": { + "fieldOrder": [ + "/properties/reference", + "/properties/previous" + ], + "groups": [], + "fields": { + "/properties/reference": { + "label": "Reference", + "helpText": "Current reference value.", + "placeholder": "", + "unit": "", + "widget": "INPUT_WIDGET_UNSPECIFIED", + "display": "DISPLAY_STYLE_CODE" + }, + "/properties/previous": { + "label": "Previous", + "helpText": "Previous reference value.", + "placeholder": "", + "unit": "", + "widget": "INPUT_WIDGET_UNSPECIFIED", + "display": "DISPLAY_STYLE_CODE" + } + } + } + } + }, + "assets": { + "sha256:8c5dec37f2aba701bd79272fc7fe4d34292623e531df7fd23b95cb3c96034741": { + "mediaType": "image/svg+xml", + "content": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI+PHBhdGggZD0iTTIgMmgxMnYxMkgyeiIvPjwvc3ZnPg==", + "width": 16, + "height": 16, + "altText": "Git Provider mark" + } + } + }, + "presentationRevision": "sha256:1cbd5452404898672d31afa2f98172f08b4976edb6e7bfb4f576524d70beaf0c" +} diff --git a/tests/test_manifest_contract.py b/tests/test_manifest_contract.py index 7b8ff65..d3f46f8 100644 --- a/tests/test_manifest_contract.py +++ b/tests/test_manifest_contract.py @@ -15,6 +15,18 @@ from tests.documentation import annotated_json_example from stateforge_protocol.sfp.manifest.v1 import contract, manifest_pb2 +from stateforge_protocol.sfp.operation_admission.v1 import ( + operation_admission_pb2, +) +from stateforge_protocol.sfp.operation_admission.v1 import ( + validation as admission_validation, +) +from stateforge_protocol.sfp.trigger_publication.v1 import ( + trigger_publication_pb2, +) +from stateforge_protocol.sfp.trigger_publication.v1 import ( + validation as trigger_validation, +) _FIXTURES = Path(__file__).parent / "fixtures" / "manifest" _SCHEMA = json.loads( @@ -56,12 +68,19 @@ def test_versioned_contract_exposes_normative_limits() -> None: "MAX_REQUEST_BYTES": 8 * 1024, "MAX_RESPONSE_BYTES": 2 * 1024 * 1024, "MAX_CANONICAL_REVISION_PREIMAGE_BYTES": 1 * 1024 * 1024, + "MAX_PRESENTATION_REVISION_PREIMAGE_BYTES": 2 * 1024 * 1024, "MAX_EMBEDDED_JSON_DEPTH": 64, "MAX_OPERATIONS": 1_024, "MAX_TRIGGERS": 1_024, "MAX_RUNTIME_REQUIREMENTS": 1_024, "MAX_PLATFORMS": 256, "MAX_PROFILE_CLAIMS_PER_OPERATION": 64, + "PRESENTATION_SCHEMA_VERSION": 1, + "MAX_CAPABILITY_GROUPS": 64, + "MAX_PRESENTATION_ASSETS": 64, + "MAX_PRESENTATION_ASSET_BYTES": 256 * 1024, + "MAX_PRESENTATION_ASSET_TOTAL_BYTES": 1 * 1024 * 1024, + "MAX_PRESENTATION_ASSET_DIMENSION": 8_192, } assert {name: getattr(contract, name) for name in expected} == expected @@ -92,6 +111,33 @@ def test_versioned_contract_limits_match_packaged_schema() -> None: definitions["sessionId"]["maxLength"] == contract.MAX_SESSION_ID_CODE_POINTS ) + presentation = definitions["providerPresentation"]["properties"] + assert ( + presentation["presentationSchemaVersion"]["const"] + == contract.PRESENTATION_SCHEMA_VERSION + ) + assert ( + presentation["operations"]["maxProperties"] + == contract.MAX_PRESENTATION_OPERATIONS + ) + assert ( + presentation["triggers"]["maxProperties"] + == contract.MAX_PRESENTATION_TRIGGERS + ) + assert ( + presentation["assets"]["maxProperties"] + == contract.MAX_PRESENTATION_ASSETS + ) + assert ( + definitions["providerView"]["properties"]["groups"]["maxItems"] + == contract.MAX_CAPABILITY_GROUPS + ) + assert ( + set( + definitions["presentationAsset"]["properties"]["mediaType"]["enum"] + ) + == contract.ALLOWED_PRESENTATION_MEDIA_TYPES + ) def test_manifest_walkthrough_covers_every_documented_scenario() -> None: @@ -168,7 +214,7 @@ def test_documented_manifest_protojson_matches_conformance_fixtures() -> None: Draft202012Validator(_SCHEMA).validate(response) -def test_response_round_trip_preserves_canonical_representation( +def test_response_round_trip_matches_canonical_representation( response, validator ) -> None: validator.validate(response) @@ -194,6 +240,168 @@ def test_response_round_trip_preserves_canonical_representation( ) +def test_provider_presentation_fixture_validates_and_round_trips() -> None: + document = json.loads( + (_FIXTURES / "presentation-response.json").read_text() + ) + Draft202012Validator(_SCHEMA).validate(document) + Draft202012Validator( + { + "$ref": "#/$defs/providerPresentation", + "$defs": _SCHEMA["$defs"], + } + ).validate(document["presentation"]) + + message = json_format.ParseDict( + document, + manifest_pb2.GetManifestResponse(), + ) + projected = json_format.MessageToDict( + message, + always_print_fields_with_no_presence=True, + ) + + assert projected == document + + +def test_presentation_is_outside_the_operational_manifest() -> None: + manifest_fields = manifest_pb2.ProviderManifest.DESCRIPTOR.fields_by_name + operation_fields = ( + manifest_pb2.OperationDeclaration.DESCRIPTOR.fields_by_name + ) + trigger_fields = manifest_pb2.TriggerDeclaration.DESCRIPTOR.fields_by_name + + assert "presentation" not in manifest_fields + assert "view" not in operation_fields + assert "view" not in trigger_fields + assert { + field.name: field.number + for field in manifest_pb2.GetManifestResponse.DESCRIPTOR.fields + } == { + "provider_instance_id": 1, + "endpoint_generation": 2, + "manifest_schema_version": 3, + "manifest_revision": 4, + "manifest": 5, + "session_id": 6, + "presentation": 7, + "presentation_revision": 8, + } + + +def test_presentation_contract_cannot_hide_or_redefine_fields() -> None: + field_view = manifest_pb2.FieldView.DESCRIPTOR.fields_by_name + schema_view = manifest_pb2.SchemaView.DESCRIPTOR.fields_by_name + forbidden = { + "hidden", + "required", + "schema", + "default", + "value", + "html", + "css", + "javascript", + "url", + "path", + } + + assert not forbidden & set(field_view) + assert not forbidden & set(schema_view) + + +def test_presentation_is_not_part_of_operation_or_trigger_messages() -> None: + descriptors = ( + operation_admission_pb2.OperationInvocation.DESCRIPTOR, + operation_admission_pb2.StartOperationRequest.DESCRIPTOR, + trigger_publication_pb2.TriggerPublication.DESCRIPTOR, + trigger_publication_pb2.StreamTriggersResponse.DESCRIPTOR, + ) + + for descriptor in descriptors: + assert not { + "presentation", + "presentation_revision", + "view", + "asset", + } & set(descriptor.fields_by_name) + + +def test_presentation_changes_do_not_change_business_fingerprints() -> None: + operation = json_format.ParseDict( + json.loads( + ( + _FIXTURES.parent / "operation_admission" / "request.json" + ).read_text() + ), + operation_admission_pb2.StartOperationRequest(), + ).invocation + publication = json_format.ParseDict( + json.loads( + ( + _FIXTURES.parent / "trigger_publication" / "publication.json" + ).read_text() + ), + trigger_publication_pb2.StreamTriggersResponse(), + ).publication + operation_fingerprint = admission_validation.compute_request_fingerprint( + operation + ) + trigger_fingerprint = ( + trigger_validation.compute_publication_content_fingerprint(publication) + ) + + manifest_response = json_format.ParseDict( + json.loads((_FIXTURES / "presentation-response.json").read_text()), + manifest_pb2.GetManifestResponse(), + ) + manifest_response.presentation.provider.summary = "Changed presentation" + + assert ( + admission_validation.compute_request_fingerprint(operation) + == operation_fingerprint + ) + assert ( + trigger_validation.compute_publication_content_fingerprint(publication) + == trigger_fingerprint + ) + + +@pytest.mark.parametrize( + ("target", "field", "value"), + [ + ("field", "hidden", True), + ("field", "required", False), + ("field", "schema", {"type": "string"}), + ("field", "html", "unsafe"), + ("field", "javascript", "alert(1)"), + ("asset", "url", "https://example.invalid/icon.svg"), + ("asset", "path", "../../etc/passwd"), + ], +) +def test_presentation_protojson_rejects_executable_or_semantic_fields( + target: str, + field: str, + value: object, +) -> None: + document = json.loads( + (_FIXTURES / "presentation-response.json").read_text() + )["presentation"] + if target == "field": + view = next(iter(document["operations"].values())) + selected = next(iter(view["input"]["fields"].values())) + else: + selected = next(iter(document["assets"].values())) + selected[field] = value + + with pytest.raises(ValidationError): + Draft202012Validator( + { + "$ref": "#/$defs/providerPresentation", + "$defs": _SCHEMA["$defs"], + } + ).validate(document) + + def test_request_round_trip_and_offer_order() -> None: request = manifest_pb2.GetManifestRequest( expected_provider_instance_id="7f7db7d8-68b4-4f71-9769-065b5c4f941c", diff --git a/tests/test_manifest_session_contract.py b/tests/test_manifest_session_contract.py index ae4bb22..484b139 100644 --- a/tests/test_manifest_session_contract.py +++ b/tests/test_manifest_session_contract.py @@ -58,7 +58,7 @@ def _round_trip(document, definition): ) -def test_envelope_additions_preserve_existing_field_numbers(): +def test_manifest_envelope_field_layout_is_exact(): for message, expected in [ ( manifest_pb2.GetManifestRequest, @@ -78,6 +78,8 @@ def test_envelope_additions_preserve_existing_field_numbers(): "manifest_revision": 4, "manifest": 5, "session_id": 6, + "presentation": 7, + "presentation_revision": 8, }, ), ]: @@ -149,9 +151,7 @@ def test_invalid_session_shapes_are_rejected(definition, field, value): ("getManifestResponse", "sessionId"), ], ) -def test_missing_or_defaulted_session_is_not_a_legacy_bypass( - definition, field -): +def test_missing_or_defaulted_session_is_invalid(definition, field): document = _fixture(definition) del document[field] with pytest.raises(ValidationError, match="required property"): @@ -216,7 +216,7 @@ def test_agent_rejects_wrong_or_superseded_response_session(case): assert matches == case["accept"] -def test_session_changes_preserve_exact_canonical_preimage_and_golden(): +def test_session_changes_do_not_change_canonical_manifest_revision(): response = _fixture("getManifestResponse") for session_id in ("manifest-session-A", "manifest-session-B"): response["sessionId"] = session_id diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index b3af666..af0958e 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -1,22 +1,31 @@ """Executable semantic-validation evidence for Provider Manifest v1.""" import copy +import hashlib import json +import struct +import zlib from pathlib import Path import pytest -from google.protobuf.json_format import ParseDict +from google.protobuf.json_format import MessageToDict, ParseDict from stateforge_protocol.sfp.manifest.v1 import contract, manifest_pb2 from stateforge_protocol.sfp.manifest.v1.validation import ( ManifestValidationError, ManifestValidationLimits, + PresentationValidationStatus, bounded_json, canonical_bytes, + canonical_presentation_bytes, compute_manifest_revision, + compute_presentation_revision, contract_validator, + validate_manifest_exchange, validate_manifest_key, validate_manifest_response, + validate_presentation_document, + validate_presentation_key, validate_schema, ) @@ -31,6 +40,98 @@ def _response() -> manifest_pb2.GetManifestResponse: return ParseDict(document, manifest_pb2.GetManifestResponse()) +def _presentation_response() -> manifest_pb2.GetManifestResponse: + document = json.loads( + (_FIXTURES / "presentation-response.json").read_text() + ) + return ParseDict(document, manifest_pb2.GetManifestResponse()) + + +def _project(message) -> dict[str, object]: + return MessageToDict( + message, + always_print_fields_with_no_presence=True, + ) + + +def _refresh_presentation_revision( + response: manifest_pb2.GetManifestResponse, +) -> None: + response.presentation_revision = compute_presentation_revision( + _project(response.presentation), + response.manifest_revision, + response.provider_instance_id, + ) + + +def _refresh_manifest_revision( + response: manifest_pb2.GetManifestResponse, +) -> None: + response.manifest_revision = compute_manifest_revision( + _project(response.manifest), + response.manifest_schema_version, + response.provider_instance_id, + ) + + +def _validate_presentation( + response: manifest_pb2.GetManifestResponse, +) -> bytes: + return validate_presentation_document( + response.presentation, + _project(response.manifest), + ) + + +def _png_chunk(kind: bytes, content: bytes) -> bytes: + checksum = zlib.crc32(kind) + checksum = zlib.crc32(content, checksum) & 0xFFFFFFFF + return ( + struct.pack(">I", len(content)) + + kind + + content + + struct.pack(">I", checksum) + ) + + +def _png(width: int = 1, height: int = 1) -> bytes: + + header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0) + pixels = b"".join( + b"\x00" + (b"\x00\x00\x00\x00" * width) for _ in range(height) + ) + return ( + b"\x89PNG\r\n\x1a\n" + + _png_chunk(b"IHDR", header) + + _png_chunk(b"IDAT", zlib.compress(pixels)) + + _png_chunk(b"IEND", b"") + ) + + +def _replace_provider_icon( + response: manifest_pb2.GetManifestResponse, + *, + content: bytes, + media_type: str, + width: int, + height: int, +) -> str: + old_digest = response.presentation.provider.icon_asset_digest + del response.presentation.assets[old_digest] + digest = "sha256:" + hashlib.sha256(content).hexdigest() + response.presentation.assets[digest].CopyFrom( + manifest_pb2.PresentationAsset( + media_type=media_type, + content=content, + width=width, + height=height, + alt_text="Provider icon", + ) + ) + response.presentation.provider.icon_asset_digest = digest + return digest + + def _schema(**overrides): return { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -57,6 +158,754 @@ def test_validates_and_canonicalizes_the_cross_language_vector() -> None: ) +def test_accepts_complete_provider_presentation_snapshot() -> None: + response = _presentation_response() + + exchange = validate_manifest_exchange(response) + + expected = json.loads( + (_FIXTURES / "presentation-response.json").read_text() + ) + assert ( + exchange.presentation_status is PresentationValidationStatus.ACCEPTED + ) + assert json.loads(exchange.manifest_document) == expected["manifest"] + assert ( + json.loads(exchange.presentation_document or b"") + == expected["presentation"] + ) + assert exchange.presentation_key is not None + assert exchange.presentation_key.revision == response.presentation_revision + assert ( + exchange.presentation_key.manifest_revision + == response.manifest_revision + ) + + +def test_absent_presentation_uses_schema_derived_rendering() -> None: + exchange = validate_manifest_exchange(_response()) + + assert exchange.presentation_status is PresentationValidationStatus.ABSENT + assert exchange.presentation_key is None + assert exchange.presentation_document is None + + +def test_empty_presentation_overlay_is_valid() -> None: + response = _presentation_response() + response.presentation.ClearField("provider") + response.presentation.ClearField("operations") + response.presentation.ClearField("triggers") + response.presentation.ClearField("assets") + _refresh_presentation_revision(response) + + exchange = validate_manifest_exchange(response) + + assert ( + exchange.presentation_status is PresentationValidationStatus.ACCEPTED + ) + assert json.loads(exchange.presentation_document or b"") == { + "assets": {}, + "operations": {}, + "presentationSchemaVersion": 1, + "triggers": {}, + } + + +def test_invalid_presentation_falls_back_without_rejecting_manifest() -> None: + response = _presentation_response() + operation = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ] + operation.input.field_order[0] = "/properties/not-declared" + _refresh_presentation_revision(response) + + exchange = validate_manifest_exchange(response) + + assert exchange.presentation_status is PresentationValidationStatus.INVALID + assert exchange.presentation_document is None + assert exchange.presentation_key is None + assert exchange.manifest_document == validate_manifest_response(response) + + +@pytest.mark.parametrize( + ("schema_version", "status"), + [ + (0, PresentationValidationStatus.INVALID), + (2, PresentationValidationStatus.UNSUPPORTED), + ], +) +def test_unknown_or_invalid_presentation_versions_fall_back( + schema_version: int, + status: PresentationValidationStatus, +) -> None: + response = _presentation_response() + response.presentation.presentation_schema_version = schema_version + + exchange = validate_manifest_exchange(response) + + assert exchange.presentation_status is status + assert exchange.presentation_document is None + + +def test_presentation_and_revision_presence_must_agree() -> None: + absent = _response() + absent.presentation_revision = "sha256:" + ("a" * 64) + explicitly_empty = _response() + explicitly_empty.presentation_revision = "" + present = _presentation_response() + present.ClearField("presentation_revision") + + assert ( + validate_manifest_exchange(absent).presentation_status + is PresentationValidationStatus.INVALID + ) + assert ( + validate_manifest_exchange(explicitly_empty).presentation_status + is PresentationValidationStatus.INVALID + ) + assert ( + validate_manifest_exchange(present).presentation_status + is PresentationValidationStatus.INVALID + ) + + +def test_presentation_revision_mismatch_falls_back() -> None: + response = _presentation_response() + response.presentation_revision = "sha256:" + ("0" * 64) + + exchange = validate_manifest_exchange(response) + + assert exchange.presentation_status is PresentationValidationStatus.INVALID + + +def test_presentation_revision_is_isolated_and_bound_to_manifest() -> None: + response = _presentation_response() + original_manifest_revision = response.manifest_revision + original_presentation_revision = response.presentation_revision + + response.presentation.provider.summary = "A different summary." + _refresh_presentation_revision(response) + + assert response.manifest_revision == original_manifest_revision + assert response.presentation_revision != original_presentation_revision + assert ( + validate_manifest_exchange(response).presentation_status + is PresentationValidationStatus.ACCEPTED + ) + + presentation_revision = response.presentation_revision + response.manifest.display_name = "Renamed Git Provider" + _refresh_manifest_revision(response) + _refresh_presentation_revision(response) + + assert response.manifest_revision != original_manifest_revision + assert response.presentation_revision != presentation_revision + assert ( + validate_manifest_exchange(response).presentation_status + is PresentationValidationStatus.ACCEPTED + ) + + +def test_presentation_key_validates_the_complete_revision_identity() -> None: + response = _presentation_response() + + key = validate_presentation_key( + response.provider_instance_id, + response.manifest_revision, + response.presentation.presentation_schema_version, + response.presentation_revision, + ) + + assert str(key.provider_instance_id) == response.provider_instance_id + assert key.manifest_revision == response.manifest_revision + assert key.schema_version == contract.PRESENTATION_SCHEMA_VERSION + assert key.revision == response.presentation_revision + + +@pytest.mark.parametrize( + ("field", "value", "message"), + [ + ("provider", "not-a-uuid", "provider identity"), + ("manifest", "not-a-revision", "manifest revision"), + ("schema", 2, "schema version"), + ("presentation", "not-a-revision", "revision is invalid"), + ], +) +def test_presentation_key_rejects_invalid_identity_parts( + field: str, + value: str | int, + message: str, +) -> None: + response = _presentation_response() + arguments: dict[str, str | int] = { + "provider": response.provider_instance_id, + "manifest": response.manifest_revision, + "schema": response.presentation.presentation_schema_version, + "presentation": response.presentation_revision, + } + arguments[field] = value + + with pytest.raises(ManifestValidationError, match=message): + validate_presentation_key( + str(arguments["provider"]), + str(arguments["manifest"]), + int(arguments["schema"]), + str(arguments["presentation"]), + ) + + +def test_presentation_revision_requires_a_manifest_revision() -> None: + response = _presentation_response() + + with pytest.raises(ManifestValidationError, match="manifest revision"): + compute_presentation_revision( + _project(response.presentation), + "not-a-revision", + response.provider_instance_id, + ) + + +def test_public_presentation_validator_projects_its_own_message() -> None: + response = _presentation_response() + manifest = _project(response.manifest) + + document = validate_presentation_document( + response.presentation, + manifest, + ) + + assert document == canonical_presentation_bytes( + _project(response.presentation) + ) + + +def test_capability_groups_are_optional() -> None: + response = _presentation_response() + response.presentation.provider.ClearField("groups") + for view in response.presentation.operations.values(): + view.group_id = "" + for view in response.presentation.triggers.values(): + view.group_id = "" + _refresh_presentation_revision(response) + + exchange = validate_manifest_exchange(response) + + assert ( + exchange.presentation_status is PresentationValidationStatus.ACCEPTED + ) + + +@pytest.mark.parametrize("collection", ["operations", "triggers"]) +def test_views_cannot_name_undeclared_capabilities(collection: str) -> None: + response = _presentation_response() + views = getattr(response.presentation, collection) + declared_identifier = next(iter(views)) + views["example.invalid/not_declared@1"].CopyFrom( + views[declared_identifier] + ) + + with pytest.raises( + ManifestValidationError, + match=f"{collection[:-1]} view does not name a declared", + ): + _validate_presentation(response) + + +def test_view_group_reference_must_resolve() -> None: + response = _presentation_response() + response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].group_id = "missing" + + with pytest.raises(ManifestValidationError, match="group reference"): + _validate_presentation(response) + + +def test_capability_group_ids_must_be_unique() -> None: + response = _presentation_response() + duplicate = response.presentation.provider.groups.add() + duplicate.CopyFrom(response.presentation.provider.groups[0]) + + with pytest.raises(ManifestValidationError, match="group IDs"): + _validate_presentation(response) + + +def test_schema_view_pointer_must_resolve_in_its_own_schema() -> None: + response = _presentation_response() + operation = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ] + operation.input.field_order[0] = "/properties/commit" + + with pytest.raises(ManifestValidationError, match="does not resolve"): + _validate_presentation(response) + + +def test_schema_view_pointer_must_name_a_field() -> None: + response = _presentation_response() + operation = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ] + operation.input.field_order[0] = "/properties" + + with pytest.raises(ManifestValidationError, match="schema field"): + _validate_presentation(response) + + +def test_field_may_belong_to_only_one_visual_group() -> None: + response = _presentation_response() + groups = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].input.groups + duplicate = groups.add( + id="more-credentials", + label="More credentials", + description="Duplicate placement.", + ) + duplicate.fields.append("/properties/token") + + with pytest.raises(ManifestValidationError, match="at most one"): + _validate_presentation(response) + + +def test_field_group_ids_must_be_unique() -> None: + response = _presentation_response() + groups = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].input.groups + duplicate = groups.add( + id="credentials", + label="More credentials", + description="Duplicate identifier.", + ) + duplicate.fields.append("/properties/repository") + + with pytest.raises(ManifestValidationError, match="group IDs"): + _validate_presentation(response) + + +def test_schema_view_follows_a_local_field_reference() -> None: + response = _presentation_response() + schema = response.manifest.operations[ + "stateforge.git/reference.resolve@1" + ].input_schema + schema.update( + { + "$defs": {"repository": {"type": "string"}}, + "properties": { + "repository": {"$ref": "#/$defs/repository"}, + "depth": { + "type": "integer", + "minimum": 1, + "maximum": 10, + }, + "token": {"type": "string", "writeOnly": True}, + }, + } + ) + + _validate_presentation(response) + + +@pytest.mark.parametrize( + ("reference", "message"), + [ + ("https://example.invalid/schema", "reference is invalid"), + ("#/properties/repository", "cyclic field schema reference"), + ("#/$defs/not-a-schema", "must name a schema"), + ], +) +def test_schema_view_rejects_invalid_field_references( + reference: str, + message: str, +) -> None: + response = _presentation_response() + schema = response.manifest.operations[ + "stateforge.git/reference.resolve@1" + ].input_schema + schema.update( + { + "$defs": {"not-a-schema": "value"}, + "properties": { + "repository": {"$ref": reference}, + "depth": { + "type": "integer", + "minimum": 1, + "maximum": 10, + }, + "token": {"type": "string", "writeOnly": True}, + }, + } + ) + + with pytest.raises(ManifestValidationError, match=message): + _validate_presentation(response) + + +def test_schema_view_resolves_fields_nested_in_schema_arrays() -> None: + response = _presentation_response() + schema = response.manifest.operations[ + "stateforge.git/reference.resolve@1" + ].input_schema + schema.Clear() + schema.update( + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "allOf": [{"properties": {"repository": {"type": "string"}}}], + } + ) + view = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].input + field = manifest_pb2.FieldView() + field.CopyFrom(view.fields["/properties/repository"]) + view.ClearField("field_order") + view.field_order.append("/allOf/0/properties/repository") + view.ClearField("groups") + view.ClearField("fields") + view.fields["/allOf/0/properties/repository"].CopyFrom(field) + + _validate_presentation(response) + + +@pytest.mark.parametrize( + ("field", "widget", "message"), + [ + ("repository", manifest_pb2.INPUT_WIDGET_NUMBER, "schema type"), + ("repository", manifest_pb2.INPUT_WIDGET_SECRET, "write-only"), + ("repository", manifest_pb2.INPUT_WIDGET_SELECT, "schema enum"), + ("depth", manifest_pb2.INPUT_WIDGET_DATE_TIME, "schema type"), + ], +) +def test_input_widgets_must_match_authoritative_schema( + field: str, + widget: int, + message: str, +) -> None: + response = _presentation_response() + view = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].input.fields[f"/properties/{field}"] + view.widget = widget + + with pytest.raises(ManifestValidationError, match=message): + _validate_presentation(response) + + +def test_slider_requires_authoritative_bounds() -> None: + response = _presentation_response() + depth = ( + response.manifest.operations["stateforge.git/reference.resolve@1"] + .input_schema.fields["properties"] + .struct_value.fields["depth"] + .struct_value + ) + del depth.fields["minimum"] + + with pytest.raises(ManifestValidationError, match="minimum and maximum"): + _validate_presentation(response) + + +@pytest.mark.parametrize( + ("schema", "widget", "display"), + [ + ({"type": "boolean"}, manifest_pb2.INPUT_WIDGET_CHECKBOX, 0), + ( + {"type": "string", "enum": ["main", "develop"]}, + manifest_pb2.INPUT_WIDGET_SELECT, + 0, + ), + ( + {"type": "string", "enum": ["main", "develop"]}, + manifest_pb2.INPUT_WIDGET_RADIO, + 0, + ), + ( + {"type": "string", "format": "date-time"}, + manifest_pb2.INPUT_WIDGET_DATE_TIME, + manifest_pb2.DISPLAY_STYLE_DATE_TIME, + ), + ( + {"type": ["object", "null"]}, + manifest_pb2.INPUT_WIDGET_JSON, + manifest_pb2.DISPLAY_STYLE_JSON, + ), + ], +) +def test_supported_field_preferences_follow_the_schema( + schema: dict[str, object], + widget: int, + display: int, +) -> None: + response = _presentation_response() + field_schema = ( + response.manifest.operations["stateforge.git/reference.resolve@1"] + .input_schema.fields["properties"] + .struct_value.fields["repository"] + .struct_value + ) + field_schema.Clear() + field_schema.update(schema) + field_view = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].input.fields["/properties/repository"] + field_view.widget = widget + field_view.display = display + + _validate_presentation(response) + + +@pytest.mark.parametrize("preference", ["widget", "placeholder"]) +def test_output_fields_cannot_declare_input_preferences( + preference: str, +) -> None: + response = _presentation_response() + view = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].result.fields["/properties/commit"] + if preference == "widget": + view.widget = manifest_pb2.INPUT_WIDGET_TEXT + else: + view.placeholder = "not permitted" + + with pytest.raises(ManifestValidationError, match="output fields"): + _validate_presentation(response) + + +@pytest.mark.parametrize( + ("field", "display"), + [ + ("commit", manifest_pb2.DISPLAY_STYLE_METRIC), + ("changed", manifest_pb2.DISPLAY_STYLE_CODE), + ("changed", manifest_pb2.DISPLAY_STYLE_TABLE), + ], +) +def test_display_preferences_must_match_authoritative_schema( + field: str, + display: int, +) -> None: + response = _presentation_response() + view = response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].result.fields[f"/properties/{field}"] + view.display = display + + with pytest.raises(ManifestValidationError, match="schema type"): + _validate_presentation(response) + + +def test_bounded_static_png_asset_is_accepted() -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=_png(2, 3), + media_type="image/png", + width=2, + height=3, + ) + _refresh_presentation_revision(response) + + exchange = validate_manifest_exchange(response) + + assert ( + exchange.presentation_status is PresentationValidationStatus.ACCEPTED + ) + + +def test_asset_reference_must_resolve() -> None: + response = _presentation_response() + del response.presentation.assets[ + response.presentation.provider.icon_asset_digest + ] + + with pytest.raises(ManifestValidationError, match="reference is missing"): + _validate_presentation(response) + + +def test_unreferenced_assets_are_rejected() -> None: + response = _presentation_response() + response.presentation.provider.icon_asset_digest = "" + + with pytest.raises(ManifestValidationError, match="unreferenced asset"): + _validate_presentation(response) + + +def test_asset_digest_must_match_exact_bytes() -> None: + response = _presentation_response() + digest = response.presentation.provider.icon_asset_digest + response.presentation.assets[digest].content += b"changed" + + with pytest.raises(ManifestValidationError, match="digest mismatch"): + _validate_presentation(response) + + +def test_asset_size_limit_is_enforced() -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=b"x" * (contract.MAX_PRESENTATION_ASSET_BYTES + 1), + media_type="image/png", + width=1, + height=1, + ) + + with pytest.raises(ManifestValidationError, match="byte limit"): + _validate_presentation(response) + + +def test_aggregate_asset_size_limit_is_enforced() -> None: + response = _presentation_response() + response.presentation.ClearField("assets") + references: list[str] = [] + for index in range(5): + content = bytes([index]) + ( + b"x" * (contract.MAX_PRESENTATION_ASSET_BYTES - 1) + ) + digest = "sha256:" + hashlib.sha256(content).hexdigest() + response.presentation.assets[digest].CopyFrom( + manifest_pb2.PresentationAsset( + media_type="image/svg+xml", + content=content, + width=1, + height=1, + alt_text="Visual", + ) + ) + references.append(digest) + response.presentation.provider.icon_asset_digest = references[0] + response.presentation.provider.banner_asset_digest = references[1] + response.presentation.provider.groups[0].icon_asset_digest = references[2] + response.presentation.operations[ + "stateforge.git/reference.resolve@1" + ].icon_asset_digest = references[3] + response.presentation.triggers[ + "stateforge.git/reference.changed@1" + ].icon_asset_digest = references[4] + + with pytest.raises(ManifestValidationError, match="aggregate asset"): + _validate_presentation(response) + + +def test_raster_media_type_and_dimensions_must_match_content() -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=_png(), + media_type="image/png", + width=2, + height=1, + ) + + with pytest.raises(ManifestValidationError, match="dimensions"): + _validate_presentation(response) + + response = _presentation_response() + _replace_provider_icon( + response, + content=b"not a PNG", + media_type="image/png", + width=1, + height=1, + ) + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + +def test_png_crc_and_chunk_allowlist_are_enforced() -> None: + response = _presentation_response() + invalid_crc = bytearray(_png()) + invalid_crc[-1] ^= 0xFF + _replace_provider_icon( + response, + content=bytes(invalid_crc), + media_type="image/png", + width=1, + height=1, + ) + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + +@pytest.mark.parametrize( + "content", + [ + _png(0, 1), + _png()[:33] + _png()[8:33] + _png()[33:], + _png()[:33] + _png_chunk(b"IEND", b""), + _png()[:-12], + ], +) +def test_png_structure_is_enforced(content: bytes) -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=content, + media_type="image/png", + width=1, + height=1, + ) + + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + response = _presentation_response() + png = _png() + unsafe_chunk = b"\x00\x00\x00\x00tEXt" + struct.pack( + ">I", zlib.crc32(b"tEXt") & 0xFFFFFFFF + ) + content = png[:-12] + unsafe_chunk + png[-12:] + _replace_provider_icon( + response, + content=content, + media_type="image/png", + width=1, + height=1, + ) + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + +@pytest.mark.parametrize( + "content", + [ + b"", + b'', + b'', + b'', + b']>', + b'', + b'', + ], +) +def test_svg_executable_or_external_content_is_rejected_without_echo( + content: bytes, +) -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=content, + media_type="image/svg+xml", + width=1, + height=1, + ) + + with pytest.raises(ManifestValidationError) as error: + _validate_presentation(response) + + assert content.decode() not in str(error.value) + + +def test_media_allowlist_is_enforced() -> None: + response = _presentation_response() + digest = response.presentation.provider.icon_asset_digest + response.presentation.assets[digest].media_type = "text/html" + + with pytest.raises(ManifestValidationError, match="enum constraint"): + _validate_presentation(response) + + def test_public_contract_validator_uses_the_packaged_schema() -> None: validator = contract_validator("schemaDocument") From 4a0797395252cb02a16d1ea9443b40b0bb105b7c Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 15:21:54 +0200 Subject: [PATCH 2/8] docs: explain Provider presentation surfaces --- docs/v0.1.0/procedures/provider-manifest.md | 110 +------- .../procedures/provider-presentation.md | 240 ++++++++++++++++++ docs/v0.1.0/stylesheets/extra.css | 153 +++++++++++ mkdocs.yml | 4 +- tests/test_documentation_system.py | 54 ++++ 5 files changed, 459 insertions(+), 102 deletions(-) create mode 100644 docs/v0.1.0/procedures/provider-presentation.md diff --git a/docs/v0.1.0/procedures/provider-manifest.md b/docs/v0.1.0/procedures/provider-manifest.md index 9129c1c..96a156c 100644 --- a/docs/v0.1.0/procedures/provider-manifest.md +++ b/docs/v0.1.0/procedures/provider-manifest.md @@ -286,107 +286,15 @@ a correct default interface. Its JSON Schemas define fields, types, required values, validation, and secret-bearing inputs. The optional `presentation` snapshot improves that interface without changing any of those facts. -```mermaid -flowchart LR - Manifest["Operational manifest
capabilities + JSON Schemas"] --> Default["Complete schema-derived UI"] - Manifest --> Merge["Validated overlay merge"] - Presentation["Presentation snapshot
labels + layout + assets"] --> Merge - Merge --> Enhanced["Enhanced Provider UI"] - Presentation -. "absent, unsupported,
or invalid" .-> Default -``` - -
-
- PROVIDER -

Describe the integration

-

- A summary, longer description, embedded visuals, and optional visual - groups describe the Provider without creating capabilities. -

-
-
- CAPABILITIES -

Present operations and triggers

-

- Views add labels, explanations, grouping, field order, and compatible - render preferences to capabilities already declared by identifier. -

-
-
- ASSETS -

Ship Provider-owned visuals

-

- Bounded PNG and sanitized SVG assets travel inside the snapshot and are - addressed by the SHA-256 digest of their exact bytes. -

-
-
- -### The schema remains authoritative - -Every schema view points into exactly one authoritative schema using JSON -Pointer. Operation input hints resolve only against that operation's -`input_schema`; result hints resolve against `result_schema`; trigger hints -resolve against `payload_schema`. - -| Presentation can suggest | Presentation cannot change | -| --- | --- | -| Labels, help text, placeholders, units, field order, and visual groups | Field types, requiredness, defaults, validation, or secret semantics | -| A compatible input widget such as text, select, slider, or secret input | Operation input values or admission behavior | -| A compatible result display such as code, table, badge, or metric | Operation results or trigger payloads | -| Provider, operation, trigger, or group icons | Capability identifiers, membership, availability, or authorization | - -Groups are optional. An operation or trigger with an empty `group_id` remains -visible. A field omitted from `field_order`, `groups`, or `fields` also remains -visible through normal schema-derived rendering. There is no presentation -field that hides a capability or schema field. - -Widget and display preferences must agree with the referenced field schema. A -secret widget, for example, requires a string field marked `writeOnly`; a -slider requires a numeric field with explicit minimum and maximum; a table -requires an array. Input preferences are invalid on result and trigger payload -views. - -### Independent acceptance and revision - -The Agent validates the operational manifest first. It then handles the -presentation snapshot independently: - -| Presentation state | Result | -| --- | --- | -| Absent | Accept the manifest and render directly from its schemas. | -| Supported and valid | Accept both snapshots and merge the overlay into schema-derived rendering. | -| Unsupported schema version | Accept the manifest and ignore the presentation snapshot. | -| Invalid reference, preference, asset, or revision | Accept the manifest and ignore the presentation snapshot. | - -`manifest_revision` never includes presentation. Its value therefore remains -stable when only labels, layout, groups, or assets change. The separate -`presentation_revision` is SHA-256 over RFC 8785 canonical JSON of: - -```json -{ - "manifestRevision": "sha256:", - "presentation": {}, - "providerInstanceId": "" -} -``` - -Binding the presentation revision to `manifestRevision` prevents an overlay -from being reused with a different declaration. Session ID and endpoint -generation remain response fences and are excluded from both revisions. - -### Asset boundary - -Presentation assets are data, never executable extensions. A snapshot may -contain at most 64 assets, each no larger than 256 KiB and together no larger -than 1 MiB. Dimensions are positive and bounded to 8192 × 8192 pixels. Every -asset must be referenced, every reference must resolve, and each map key must -equal the SHA-256 digest of the exact content. - -Only validated PNG and sanitized SVG are accepted. SVG uses a closed element -and attribute allowlist and rejects scripts, event handlers, styles, external -references, data URLs, DTDs, and entities. The contract has no field for HTML, -CSS, JavaScript, a remote URL, or a filesystem path. +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 what each +view means, where it appears in a future Control Plane, how schema-derived +defaults and presentation hints compose, and how embedded assets remain safe. +The wire fields, validation pipeline, and limits remain defined on this page. ## Declaration model diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md new file mode 100644 index 0000000..bcc822b --- /dev/null +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -0,0 +1,240 @@ +# Provider presentation + +A Provider presentation is an optional visual overlay for an accepted +[Provider manifest](provider-manifest.md). It gives a Control Plane useful +labels, explanations, grouping, render preferences, and Provider-owned visuals +without replacing the operation and trigger schemas that define the real +contract. + +When a presentation is absent or rejected, the same manifest still produces a +complete schema-derived interface. Presentation improves that interface; it is +never required to understand or execute a capability. + +!!! note "Illustrative Control Plane surfaces" + + The previews on this page show how a Control Plane can apply the contract. + The Protocol defines the meaning of each view. The Control Plane and its + active skin decide exact layout, spacing, typography, and interaction. + +## From declaration to interface + +```mermaid +flowchart LR + Manifest["ProviderManifest
capabilities + JSON Schemas"] --> Model["Schema-derived
rendering model"] + Presentation["ProviderPresentation
labels + grouping + assets"] --> Validate{"Presentation
valid?"} + Validate -->|Yes| Model + Validate -.->|No| Default["Use schema defaults"] + Default --> Model + Skin["Control Plane skin
visual language"] --> Render["Rendered surfaces"] + Model --> Render + Render --> Provider["Provider page"] + Render --> Builder["Policy builder"] + Render --> Input["Operation input"] + Render --> Result["Results and events"] +``` + +The inputs have separate responsibilities: + +| Input | What it contributes | +| --- | --- | +| Operational manifest | Provider identity, capability identifiers, JSON Schemas, required fields, validation, and secret semantics | +| Provider presentation | Human-facing descriptions, grouping, field order, compatible widgets and displays, and embedded visuals | +| Control Plane skin | Colors, type, spacing, component styling, and the overall product experience | + +The presentation does not contain a page template. It supplies structured +meaning that any conforming Control Plane can render in its own visual system. + +## Views and their Control Plane surfaces + +| View | Primary Control Plane surface | What it contributes | +| --- | --- | --- | +| `ProviderView` | Provider detail page and capability browser | Summary, description, icon, banner, and optional capability groups | +| `CapabilityGroup` | Sections within the Provider's capability browser | Label, description, icon, and a stable group ID referenced by operations and triggers | +| `OperationView` | Operation cards, policy steps, input forms, and result panels | Operation text and icon plus separate input and result schema views | +| `TriggerView` | Trigger cards, policy conditions, and event inspection | Trigger text and icon plus a payload schema view | +| `SchemaView` | A form, result, or payload layout | Field order, optional field groups, and field-level presentation hints | +| `FieldGroup` | A labeled section within one schema-derived surface | A visual grouping of JSON Pointer-addressed fields | +| `FieldView` | One field in a form, result, or payload | Label, help, placeholder, unit, input widget, or read-only display style | +| `PresentationAsset` | Provider, group, operation, or trigger visuals | Embedded PNG or sanitized SVG content addressed by its SHA-256 digest | + +## Provider view + +`ProviderView` describes the integration as a whole. The Control Plane combines +it with `ProviderManifest.display_name` and the manifest's declared operations +and triggers. It does not create a second Provider identity or a custom page. + +
+
ILLUSTRATIVE PROVIDER PAGE
+
+ +
+ Git Provider +

Inspect and resolve Git references.

+
+
+
+ Repository +

Repository inspection and reference operations.

+
+
OPERATIONResolve reference
+
TRIGGERReference changed
+
+
+
+ +| Preview element | Contract source | +| --- | --- | +| `Git Provider` | `ProviderManifest.display_name` | +| Introductory copy | `ProviderView.summary` and `description` | +| Provider mark or banner | `icon_asset_digest` and `banner_asset_digest` | +| `Repository` section | One `CapabilityGroup` | +| Cards inside the section | Declared operations and triggers whose views reference the group's ID | + +Groups are optional. An operation or trigger with an empty `group_id` remains +visible as an ungrouped capability. A group never owns or duplicates the +capabilities placed inside it. + +## Operation view + +One `OperationView` follows an operation across the places where a user works +with it: + +1. its label, summary, description, and icon identify the operation in a + capability browser or policy builder; +2. its `input` view refines the schema-derived form used to configure an + invocation; and +3. its `result` view refines how a terminal result is read. + +
+
ONE OPERATION · THREE SURFACES
+
+
+ POLICY STEP +

Resolve reference

+

Resolve a Git reference to a commit.

+
+
+ INPUT + + +
Credentials
+ +
+
+ RESULT +
+
Commit
a83f0c1
+
Changed
Yes
+
+
+
+
+ +The operation's authoritative `input_schema` still decides that `repository` +is required, `depth` is numeric, and `token` is `writeOnly`. Presentation can +choose a text control, bounded slider, and secret input only because those +choices agree with the schema. The result view can render a commit as code and +`changed` as a badge, but it cannot change either result value or type. + +## Trigger view + +`TriggerView` identifies a declared trigger wherever it can be selected and +controls how an observed payload is presented. It does not define trigger +delivery, acknowledgement, filtering, or policy semantics. + +
+
TRIGGER SELECTION AND EVENT
+
+
+ POLICY CONDITION +

Reference changed

+

A repository reference moved.

+
+
+ EVENT PAYLOAD +
+
Reference
refs/heads/main
+
Previous
7da91b4
+
+
+
+
+ +The trigger's `payload_schema` remains authoritative. The payload `SchemaView` +may order, label, group, and format its fields; it cannot add trigger inputs or +alter the event. + +## Schema and field views + +Every `SchemaView` is scoped to exactly one operation input, operation result, +or trigger payload schema. It uses JSON Pointer to address fields in that +schema. + +```mermaid +flowchart LR + Schema["Authoritative JSON Schema"] --> Fields["All schema fields remain visible"] + Order["field_order"] --> Layout["Rendering model"] + Groups["FieldGroup entries"] --> Layout + Hints["FieldView entries"] --> Layout + Fields --> Layout + Layout --> Surface["Form, result, or payload"] +``` + +| Presentation value | Rendering effect | Contract boundary | +| --- | --- | --- | +| `field_order` | Establishes the preferred order for listed fields | Omitted fields still render from the schema | +| `FieldGroup` | Places fields into a labeled visual section | A field belongs to at most one group | +| `label` and `help_text` | Replaces generated copy with author-provided wording | Does not change the field's JSON name or meaning | +| `placeholder` | Adds an input prompt | Valid only on operation input fields | +| `unit` | Adds a human-readable unit beside a value | Does not transform or scale the value | +| `widget` | Suggests a compatible input control | Must agree with type, `enum`, format, bounds, and `writeOnly` semantics | +| `display` | Suggests a compatible read-only renderer | Must agree with the result or payload field type | + +There is no presentation field for hiding a schema field, changing +requiredness, supplying defaults, or redefining validation. + +## Assets and skins + +Presentation assets give a Provider ownership of its visual identity without +giving it executable access to the Control Plane. The snapshot can embed +bounded PNG and sanitized SVG assets. Every asset is content-addressed and +every reference must resolve. + +The asset supplies the visual content. The active Control Plane skin decides +how it is framed: size, spacing, background, border, and placement remain part +of the host experience. Presentation contains no HTML, CSS, JavaScript, remote +URL, or filesystem path. + +## Acceptance and fallback + +The Agent accepts the operational manifest before considering presentation. +It then evaluates the optional snapshot as a separate unit: + +| Presentation state | Rendering behavior | +| --- | --- | +| Absent | Build every surface from the manifest's JSON Schemas. | +| Supported and valid | Apply the complete presentation overlay to the schema-derived model. | +| Unsupported schema version | Ignore the presentation and use schema-derived rendering. | +| Invalid reference, preference, asset, or revision | Ignore the presentation and use schema-derived rendering. | + +An invalid field hint does not make an operation invalid. The complete +presentation snapshot is discarded, and the operational manifest remains +available. + +`manifest_revision` never includes presentation. The separate +`presentation_revision` is bound to the accepted manifest revision, so an +overlay cannot be reused with a different capability declaration. + +## How presentation reaches the Control Plane + +Within SFP, the Provider includes `ProviderPresentation` in the existing +`ManifestService.GetManifest` response. The Agent validates and caches the +accepted operational and presentation snapshots independently. + +The Agent-to-Control-Plane transport for that accepted snapshot will be +defined by SF-AOP. When a Control Plane receives the pair, it can reproduce the +same schema-derived model, apply the validated overlay, and render it through +its active skin. SFP does not introduce a second presentation RPC. + +For exact wire fields, revision construction, size limits, and public Python +validators, return to [Provider manifest exchange](provider-manifest.md). diff --git a/docs/v0.1.0/stylesheets/extra.css b/docs/v0.1.0/stylesheets/extra.css index baf7cd7..f59fee6 100644 --- a/docs/v0.1.0/stylesheets/extra.css +++ b/docs/v0.1.0/stylesheets/extra.css @@ -10,3 +10,156 @@ margin-inline: auto; max-width: 100%; } + +.md-typeset .sf-presentation-preview { + background: color-mix(in srgb, var(--md-default-bg-color) 94%, var(--md-accent-fg-color)); + border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 22%, transparent); + border-radius: 0.55rem; + margin: 1.2rem 0; + overflow: hidden; + padding: 1rem; +} + +.md-typeset .sf-presentation-preview__label, +.md-typeset .sf-presentation-preview small { + color: var(--md-accent-fg-color); + display: block; + font-size: 0.62rem; + font-weight: 700; + letter-spacing: 0.09em; + margin-bottom: 0.5rem; +} + +.md-typeset .sf-presentation-provider { + align-items: center; + display: flex; + gap: 0.8rem; + padding: 0.7rem 0; +} + +.md-typeset .sf-presentation-provider p, +.md-typeset .sf-presentation-section p, +.md-typeset .sf-presentation-columns p { + margin: 0.2rem 0 0; +} + +.md-typeset .sf-presentation-provider__icon { + align-items: center; + background: var(--md-accent-fg-color); + border-radius: 0.45rem; + color: var(--md-primary-bg-color); + display: flex; + flex: 0 0 2.6rem; + font-weight: 700; + height: 2.6rem; + justify-content: center; +} + +.md-typeset .sf-presentation-section, +.md-typeset .sf-presentation-columns > section { + background: color-mix(in srgb, var(--md-default-bg-color) 96%, var(--md-default-fg-color)); + border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 16%, transparent); + border-radius: 0.4rem; + padding: 0.8rem; +} + +.md-typeset .sf-presentation-section > span, +.md-typeset .sf-presentation-columns h3 { + font-weight: 700; +} + +.md-typeset .sf-presentation-capabilities, +.md-typeset .sf-presentation-columns { + display: grid; + gap: 0.65rem; + grid-template-columns: repeat(3, minmax(0, 1fr)); + margin-top: 0.8rem; +} + +.md-typeset .sf-presentation-capabilities { + grid-template-columns: repeat(2, minmax(0, 1fr)); +} + +.md-typeset .sf-presentation-capabilities > div { + border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); + border-radius: 0.35rem; + padding: 0.65rem; +} + +.md-typeset .sf-presentation-capabilities strong, +.md-typeset .sf-presentation-columns label { + display: block; +} + +.md-typeset .sf-presentation-columns--two { + grid-template-columns: repeat(2, minmax(0, 1fr)); +} + +.md-typeset .sf-presentation-columns section > :first-child { + margin-top: 0; +} + +.md-typeset .sf-presentation-columns section > :last-child { + margin-bottom: 0; +} + +.md-typeset .sf-presentation-columns label { + font-size: 0.72rem; + margin-top: 0.65rem; +} + +.md-typeset .sf-presentation-columns input, +.md-typeset .sf-presentation-meter { + background: var(--md-code-bg-color); + border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 20%, transparent); + border-radius: 0.3rem; + box-sizing: border-box; + color: var(--md-default-fg-color); + display: block; + font: inherit; + margin-top: 0.25rem; + padding: 0.35rem 0.45rem; + width: 100%; +} + +.md-typeset .sf-presentation-subsection { + border-top: 1px solid color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); + font-size: 0.7rem; + font-weight: 700; + margin-top: 0.8rem; + padding-top: 0.65rem; +} + +.md-typeset .sf-presentation-columns dl, +.md-typeset .sf-presentation-columns dl div { + margin: 0; +} + +.md-typeset .sf-presentation-columns dl div { + align-items: center; + border-bottom: 1px solid color-mix(in srgb, var(--md-default-fg-color) 12%, transparent); + display: flex; + justify-content: space-between; + padding: 0.55rem 0; +} + +.md-typeset .sf-presentation-columns dd { + margin: 0; +} + +.md-typeset .sf-presentation-badge { + background: color-mix(in srgb, var(--md-accent-fg-color) 16%, transparent); + border-radius: 999px; + color: var(--md-accent-fg-color); + font-size: 0.68rem; + font-weight: 700; + padding: 0.15rem 0.5rem; +} + +@media screen and (max-width: 52rem) { + .md-typeset .sf-presentation-columns, + .md-typeset .sf-presentation-columns--two, + .md-typeset .sf-presentation-capabilities { + grid-template-columns: 1fr; + } +} diff --git a/mkdocs.yml b/mkdocs.yml index 1e8a364..f73df75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,7 +23,9 @@ nav: - Procedure map: v0.1.0/procedures/index.md - Endpoint discovery and channel establishment: v0.1.0/procedures/endpoint-discovery.md - Handshake and version negotiation: v0.1.0/bootstrap.md - - Provider manifest exchange: v0.1.0/procedures/provider-manifest.md + - Provider manifest exchange: + - Contract and exchange: v0.1.0/procedures/provider-manifest.md + - Provider presentation: v0.1.0/procedures/provider-presentation.md - Health and availability monitoring: v0.1.0/procedures/health.md - Capability assessment: v0.1.0/procedures/capability-assessment.md - Trigger publication and acknowledgement: v0.1.0/procedures/triggers.md diff --git a/tests/test_documentation_system.py b/tests/test_documentation_system.py index 6635de6..1052857 100644 --- a/tests/test_documentation_system.py +++ b/tests/test_documentation_system.py @@ -47,6 +47,60 @@ def test_protocol_uses_the_shared_documentation_presentation() -> None: assert configuration.extra["annotate"]["json"] == [".s2"] +def test_provider_presentation_guide_maps_views_to_surfaces() -> None: + page = ( + ROOT / "docs/v0.1.0/procedures/provider-presentation.md" + ).read_text(encoding="utf-8") + configuration = load_config( + config_file=str(ROOT / "mkdocs.yml"), + strict=True, + ) + version_navigation = configuration.nav[0]["Protocol documentation"][1][ + "v0.1.0" + ] + procedure_navigation = next( + item["SFP procedures"] + for item in version_navigation + if isinstance(item, dict) and "SFP procedures" in item + ) + + assert { + "Provider manifest exchange": [ + { + "Contract and exchange": ( + "v0.1.0/procedures/provider-manifest.md" + ) + }, + { + "Provider presentation": ( + "v0.1.0/procedures/provider-presentation.md" + ) + }, + ] + } in procedure_navigation + for view in ( + "`ProviderView`", + "`CapabilityGroup`", + "`OperationView`", + "`TriggerView`", + "`SchemaView`", + "`FieldGroup`", + "`FieldView`", + "`PresentationAsset`", + ): + assert view in page + for surface in ( + "Provider page", + "Policy builder", + "Operation input", + "Results and events", + ): + assert surface in page + assert "schema-derived interface" in page + assert "active Control Plane skin" in page + assert "SF-AOP" in page + + def test_documentation_home_orients_readers_to_the_protocol() -> None: home = (ROOT / "docs/index.md").read_text(encoding="utf-8") From e3de8a4d9fe4d15d2cec062028df82f8607eafe7 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 16:43:54 +0200 Subject: [PATCH 3/8] feat(manifest): define extensible provider presentation trees --- docs/v0.1.0/procedures/operation-admission.md | 10 +- docs/v0.1.0/procedures/provider-manifest.md | 19 +- .../procedures/provider-presentation.md | 466 ++++++++------ docs/v0.1.0/procedures/triggers.md | 6 +- docs/v0.1.0/reference/conformance-coverage.md | 2 +- docs/v0.1.0/stylesheets/extra.css | 153 ----- .../sfp/manifest/v1/manifest.proto | 191 +++--- scripts/ci/verify_installed.py | 5 +- .../sfp/manifest/v1/_presentation.py | 589 ++++++++++-------- .../sfp/manifest/v1/contract.py | 154 ++++- .../sfp/manifest/v1/manifest.schema.json | 395 +++++------- .../sfp/manifest/v1/manifest_pb2.py | 78 ++- .../sfp/manifest/v1/manifest_pb2.pyi | 492 +++++++-------- .../manifest/presentation-response.json | 214 ++++--- tests/test_documentation_system.py | 32 +- tests/test_manifest_contract.py | 80 ++- tests/test_manifest_validation.py | 416 +++++-------- 17 files changed, 1618 insertions(+), 1684 deletions(-) diff --git a/docs/v0.1.0/procedures/operation-admission.md b/docs/v0.1.0/procedures/operation-admission.md index 4f41b21..8eb8e7a 100644 --- a/docs/v0.1.0/procedures/operation-admission.md +++ b/docs/v0.1.0/procedures/operation-admission.md @@ -148,11 +148,11 @@ 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. Labels, visual groups, field -order, widgets, displays, and assets 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. +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 diff --git a/docs/v0.1.0/procedures/provider-manifest.md b/docs/v0.1.0/procedures/provider-manifest.md index 96a156c..eb937a6 100644 --- a/docs/v0.1.0/procedures/provider-manifest.md +++ b/docs/v0.1.0/procedures/provider-manifest.md @@ -148,7 +148,7 @@ 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, trigger, field, group, and embedded-asset presentation overlay. | + | 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" @@ -281,20 +281,21 @@ apply. ## Presentation snapshot -The operational manifest already contains everything a renderer needs to build -a correct default interface. Its JSON Schemas define fields, types, required -values, validation, and secret-bearing inputs. The optional `presentation` -snapshot improves that interface without changing any of those facts. +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 what each -view means, where it appears in a future Control Plane, how schema-derived -defaults and presentation hints compose, and how embedded assets remain safe. -The wire fields, validation pipeline, and limits remain defined on this page. +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 diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index bcc822b..562a97c 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -1,240 +1,294 @@ # Provider presentation -A Provider presentation is an optional visual overlay for an accepted -[Provider manifest](provider-manifest.md). It gives a Control Plane useful -labels, explanations, grouping, render preferences, and Provider-owned visuals -without replacing the operation and trigger schemas that define the real -contract. +A Provider presentation is an optional, independently revised interface +declaration attached to an accepted [Provider manifest](provider-manifest.md). +It tells a Control Plane which surfaces a Provider offers and describes each +surface as a bounded tree of renderer components. -When a presentation is absent or rejected, the same manifest still produces a -complete schema-derived interface. Presentation improves that interface; it is -never required to understand or execute a capability. +Presentation does not change an operation, trigger, schema, authorization +decision, or runtime value. If it is absent, unsupported, or invalid, the +operational manifest remains usable and the Control Plane can render directly +from its JSON Schemas. -!!! note "Illustrative Control Plane surfaces" - - The previews on this page show how a Control Plane can apply the contract. - The Protocol defines the meaning of each view. The Control Plane and its - active skin decide exact layout, spacing, typography, and interaction. - -## From declaration to interface +## From manifest to interface ```mermaid flowchart LR - Manifest["ProviderManifest
capabilities + JSON Schemas"] --> Model["Schema-derived
rendering model"] - Presentation["ProviderPresentation
labels + grouping + assets"] --> Validate{"Presentation
valid?"} - Validate -->|Yes| Model - Validate -.->|No| Default["Use schema defaults"] - Default --> Model - Skin["Control Plane skin
visual language"] --> Render["Rendered surfaces"] - Model --> Render - Render --> Provider["Provider page"] - Render --> Builder["Policy builder"] - Render --> Input["Operation input"] - Render --> Result["Results and events"] + Manifest["ProviderManifest
capabilities + JSON Schemas"] --> Sources["Control Plane data sources"] + Presentation["ProviderPresentation
surfaces + component trees"] --> Validate{"SFP presentation
valid?"} + Validate -->|yes| Registry["Control Plane
renderer registry"] + Validate -.->|no| Defaults["Schema-derived interface"] + Sources --> Registry + Assets["Embedded PNG / SVG assets"] --> Registry + Extensions["Installed renderer extensions"] --> Registry + Registry --> Render["Rendered Provider, operation,
trigger, and evidence surfaces"] + Defaults --> Render ``` -The inputs have separate responsibilities: - -| Input | What it contributes | +| Layer | Owns | | --- | --- | -| Operational manifest | Provider identity, capability identifiers, JSON Schemas, required fields, validation, and secret semantics | -| Provider presentation | Human-facing descriptions, grouping, field order, compatible widgets and displays, and embedded visuals | -| Control Plane skin | Colors, type, spacing, component styling, and the overall product experience | +| Operational manifest | Capability identifiers, JSON Schemas, requirements, and execution semantics | +| SFP presentation contract | Surface identifiers, component-tree structure, bindings, conditions, repetition, extension metadata, safe assets, and limits | +| Control Plane renderer registry | The property schema and rendering behavior for each component identifier | +| Control Plane skin | Typography, color, spacing, framing, and product-wide visual language | + +SFP carries declarative data only. It never carries HTML, CSS, JavaScript, +executable renderer bytes, an installation command, or a remote asset URL. -The presentation does not contain a page template. It supplies structured -meaning that any conforming Control Plane can render in its own visual system. +## Presentation targets and surfaces -## Views and their Control Plane surfaces +A `ProviderPresentation` can attach a `PresentationTarget` to the Provider +itself and to any operation or trigger declared by the same manifest. Operation +and trigger map keys must match exact manifest identifiers. -| View | Primary Control Plane surface | What it contributes | +Each target contains one or more named surfaces: + +| Target | Surface identifier | Intended use | | --- | --- | --- | -| `ProviderView` | Provider detail page and capability browser | Summary, description, icon, banner, and optional capability groups | -| `CapabilityGroup` | Sections within the Provider's capability browser | Label, description, icon, and a stable group ID referenced by operations and triggers | -| `OperationView` | Operation cards, policy steps, input forms, and result panels | Operation text and icon plus separate input and result schema views | -| `TriggerView` | Trigger cards, policy conditions, and event inspection | Trigger text and icon plus a payload schema view | -| `SchemaView` | A form, result, or payload layout | Field order, optional field groups, and field-level presentation hints | -| `FieldGroup` | A labeled section within one schema-derived surface | A visual grouping of JSON Pointer-addressed fields | -| `FieldView` | One field in a form, result, or payload | Label, help, placeholder, unit, input widget, or read-only display style | -| `PresentationAsset` | Provider, group, operation, or trigger visuals | Embedded PNG or sanitized SVG content addressed by its SHA-256 digest | - -## Provider view - -`ProviderView` describes the integration as a whole. The Control Plane combines -it with `ProviderManifest.display_name` and the manifest's declared operations -and triggers. It does not create a second Provider identity or a custom page. - -
-
ILLUSTRATIVE PROVIDER PAGE
-
- -
- Git Provider -

Inspect and resolve Git references.

-
-
-
- Repository -

Repository inspection and reference operations.

-
-
OPERATIONResolve reference
-
TRIGGERReference changed
-
-
-
- -| Preview element | Contract source | -| --- | --- | -| `Git Provider` | `ProviderManifest.display_name` | -| Introductory copy | `ProviderView.summary` and `description` | -| Provider mark or banner | `icon_asset_digest` and `banner_asset_digest` | -| `Repository` section | One `CapabilityGroup` | -| Cards inside the section | Declared operations and triggers whose views reference the group's ID | - -Groups are optional. An operation or trigger with an empty `group_id` remains -visible as an ungrouped capability. A group never owns or duplicates the -capabilities placed inside it. - -## Operation view - -One `OperationView` follows an operation across the places where a user works -with it: - -1. its label, summary, description, and icon identify the operation in a - capability browser or policy builder; -2. its `input` view refines the schema-derived form used to configure an - invocation; and -3. its `result` view refines how a terminal result is read. - -
-
ONE OPERATION · THREE SURFACES
-
-
- POLICY STEP -

Resolve reference

-

Resolve a Git reference to a commit.

-
-
- INPUT - - -
Credentials
- -
-
- RESULT -
-
Commit
a83f0c1
-
Changed
Yes
-
-
-
-
- -The operation's authoritative `input_schema` still decides that `repository` -is required, `depth` is numeric, and `token` is `writeOnly`. Presentation can -choose a text control, bounded slider, and secret input only because those -choices agree with the schema. The result view can render a commit as code and -`changed` as a badge, but it cannot change either result value or type. - -## Trigger view - -`TriggerView` identifies a declared trigger wherever it can be selected and -controls how an observed payload is presented. It does not define trigger -delivery, acknowledgement, filtering, or policy semantics. - -
-
TRIGGER SELECTION AND EVENT
-
-
- POLICY CONDITION -

Reference changed

-

A repository reference moved.

-
-
- EVENT PAYLOAD -
-
Reference
refs/heads/main
-
Previous
7da91b4
-
-
-
-
- -The trigger's `payload_schema` remains authoritative. The payload `SchemaView` -may order, label, group, and format its fields; it cannot add trigger inputs or -alter the event. - -## Schema and field views - -Every `SchemaView` is scoped to exactly one operation input, operation result, -or trigger payload schema. It uses JSON Pointer to address fields in that -schema. +| Provider | `stateforge.ui/surface.provider.overview@1` | Provider identity, status, capabilities, and summary information | +| Operation | `stateforge.ui/surface.operation.request@1` | Construct and review an operation request | +| Operation | `stateforge.ui/surface.operation.run@1` | Follow an admitted operation while it runs | +| Operation | `stateforge.ui/surface.operation.result@1` | Inspect a terminal operation result | +| Trigger | `stateforge.ui/surface.trigger.policy@1` | Configure how a trigger participates in policy | +| Trigger | `stateforge.ui/surface.trigger.event@1` | Inspect one published trigger event | +| Operation or trigger | `stateforge.ui/surface.evidence@1` | Inspect evidence and audit material associated with that target | + +Groups are optional. A Provider author creates visual grouping with ordinary +layout components such as a section, grid, tabs, or steps; the Protocol does +not impose a separate grouping model. + +## The generic component tree + +Every `PresentationSurface` has one root `ComponentNode`. A node selects a +renderer by versioned string identifier and supplies only the data needed to +configure it. ```mermaid -flowchart LR - Schema["Authoritative JSON Schema"] --> Fields["All schema fields remain visible"] - Order["field_order"] --> Layout["Rendering model"] - Groups["FieldGroup entries"] --> Layout - Hints["FieldView entries"] --> Layout - Fields --> Layout - Layout --> Surface["Form, result, or payload"] +flowchart TD + Surface["PresentationSurface"] --> Root["ComponentNode root"] + Root --> ID["component_identifier"] + Root --> Props["properties"] + Root --> Bindings["bindings"] + Root --> Children["children"] + Root --> Assets["asset_bindings"] + Root -. optional .-> Condition["condition"] + Root -. optional .-> Repeat["repeat"] + Root -. custom only .-> Fallback["core fallback"] ``` -| Presentation value | Rendering effect | Contract boundary | -| --- | --- | --- | -| `field_order` | Establishes the preferred order for listed fields | Omitted fields still render from the schema | -| `FieldGroup` | Places fields into a labeled visual section | A field belongs to at most one group | -| `label` and `help_text` | Replaces generated copy with author-provided wording | Does not change the field's JSON name or meaning | -| `placeholder` | Adds an input prompt | Valid only on operation input fields | -| `unit` | Adds a human-readable unit beside a value | Does not transform or scale the value | -| `widget` | Suggests a compatible input control | Must agree with type, `enum`, format, bounds, and `writeOnly` semantics | -| `display` | Suggests a compatible read-only renderer | Must agree with the result or payload field type | +| Node field | Meaning | +| --- | --- | +| `component_identifier` | Versioned identifier resolved by the Control Plane renderer registry | +| `properties` | Renderer-specific static configuration; SFP treats it as inert JSON | +| `bindings` | Named inputs resolved from the data sources available to the current surface | +| `children` | Ordered child components | +| `asset_bindings` | Renderer slot names mapped to embedded asset digests | +| `condition` | Optional declarative existence or equality test controlling visibility | +| `repeat` | Optional bounded repetition over a collection binding | +| `fallback` | Required core-only tree used when a custom renderer is unavailable | + +The Protocol validates the identifier and tree, bounds the document, verifies +references, and constrains which data sources exist on each surface. It does +not interpret component properties. The Control Plane validates those +properties against the renderer definition registered for the component +identifier. + +## Core component catalog + +SFP 1.0 defines a compact core catalog that every conforming Control Plane can +render: + +| Category | Component identifiers | +| --- | --- | +| Layout | `layout.stack`, `layout.grid`, `layout.section`, `layout.tabs`, `layout.steps` | +| Input | `input.form`, `input.field`, `input.object`, `input.array`, `input.key_value`, `input.code` | +| Content and structured data | `content.text`, `content.markdown`, `data.key_value`, `data.table`, `data.tree`, `data.code`, `data.diff`, `data.log` | +| Status and visualization | `status.badge`, `status.progress`, `status.timeline`, `data.metric`, `data.chart`, `data.topology`, `data.artifacts` | +| Media and actions | `media.image`, `action.operation_submit`, `action.operation_cancel` | + +Each value above uses the `stateforge.ui` namespace and `@1` major version. +For example, the complete table identifier is +`stateforge.ui/data.table@1`. + +These are identifiers, not protobuf message types. Adding a renderer does not +require adding a new component-specific message or enum to SFP. -There is no presentation field for hiding a schema field, changing -requiredness, supplying defaults, or redefining validation. +## Data bindings -## Assets and skins +A `DataBinding` selects one Control Plane-provided source and optionally a +JSON Pointer within it. An empty pointer selects the complete source. The +sources available depend on the surface, preventing a Provider from referring +to data that does not exist in that rendering context. -Presentation assets give a Provider ownership of its visual identity without -giving it executable access to the Control Plane. The snapshot can embed -bounded PNG and sanitized SVG assets. Every asset is content-addressed and -every reference must resolve. +Examples include: -The asset supplies the visual content. The active Control Plane skin decides -how it is framed: size, spacing, background, border, and placement remain part -of the host experience. Presentation contains no HTML, CSS, JavaScript, remote -URL, or filesystem path. +| Surface | Representative binding sources | +| --- | --- | +| Provider overview | Provider manifest and Provider runtime state | +| Operation request | Request schema and current request value | +| Operation run | Admitted request and live operation state | +| Operation result | Request, result schema, result value, and operation evidence | +| Trigger policy | Trigger payload schema | +| Trigger event | Payload schema and published payload value | +| Evidence | Operation evidence or trigger value plus audit data | + +A repetition creates a named item scope. Descendants can bind to +`stateforge.binding/repetition.item@1` only by naming an active scope. Each +repetition also declares a positive `max_items` ceiling. + +Conditions support `EXISTS`, `NOT_EXISTS`, `EQUALS`, and `NOT_EQUALS`. +Existence conditions omit a comparison value; equality conditions require one, +including an explicitly supplied JSON `null`. + +## Core example + +The manifest fixture uses a core form for the operation request: + +```json +{ + "componentIdentifier": "stateforge.ui/input.form@1", + "properties": { + "submitLabel": "Resolve reference" + }, + "bindings": { + "schema": { + "sourceIdentifier": "stateforge.binding/operation.request.schema@1", + "pointer": "", + "scope": "" + }, + "value": { + "sourceIdentifier": "stateforge.binding/operation.request.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {} +} +``` + +The operation input JSON Schema remains authoritative. The renderer can produce +an appropriate form because the schema and current value arrive through +bindings; the presentation cannot relax validation, disclose a `writeOnly` +value, or manufacture an operation field. + +## Custom components and renderer extensions + +A Provider may use its own component identifier, such as +`stateforge.git/data.commit_graph@1`. A custom node has two additional +requirements: + +1. its namespace has one matching `RendererRequirement`; and +2. the node includes a fallback tree composed only of core + `stateforge.ui` components. + +```json +{ + "componentIdentifier": "stateforge.git/data.commit_graph@1", + "properties": {}, + "bindings": { + "result": { + "sourceIdentifier": "stateforge.binding/operation.result.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {}, + "fallback": { + "componentIdentifier": "stateforge.ui/data.tree@1", + "properties": {}, + "bindings": { + "value": { + "sourceIdentifier": "stateforge.binding/operation.result.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {} + } +} +``` + +The matching requirement carries identity and compatibility metadata: + +```json +{ + "stateforge.git": { + "extensionIdentifier": "stateforge.git/renderer@1", + "extensionVersion": "1.0.0", + "rendererApiVersion": "1.0.0", + "artifactDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "permissions": [] + } +} +``` + +The renderer artifact is distributed separately from SFP. The Control Plane +uses the metadata to locate an already trusted or separately acquired bundle, +checks compatibility and permissions in its extension host, and registers the +component identifiers exposed by that bundle. SFP never downloads or executes +it. + +If the extension is missing, incompatible, disabled, or rejected, the Control +Plane renders the core fallback. This preserves a functional interface without +limiting advanced Provider authors to the built-in catalog. -## Acceptance and fallback +## Embedded assets + +`PresentationAsset` carries bounded, content-addressed PNG or sanitized SVG +media. Nodes refer to assets through named `asset_bindings`. Every digest must +match the exact bytes, every reference must resolve, and unreferenced assets +are rejected. + +Assets provide Provider-owned icons and visuals. The active Control Plane skin +still controls their framing, size, background, and placement. + +## Validation and fallback The Agent accepts the operational manifest before considering presentation. -It then evaluates the optional snapshot as a separate unit: +The presentation is then evaluated independently: -| Presentation state | Rendering behavior | +| Presentation state | Result | | --- | --- | -| Absent | Build every surface from the manifest's JSON Schemas. | -| Supported and valid | Apply the complete presentation overlay to the schema-derived model. | -| Unsupported schema version | Ignore the presentation and use schema-derived rendering. | -| Invalid reference, preference, asset, or revision | Ignore the presentation and use schema-derived rendering. | +| Absent | Keep the manifest and render from its JSON Schemas. | +| Supported and valid | Cache the component tree and its independent revision. | +| Unsupported schema version | Keep the manifest and ignore presentation. | +| Invalid tree, source, extension metadata, asset, or revision | Keep the manifest and discard the complete presentation snapshot. | -An invalid field hint does not make an operation invalid. The complete -presentation snapshot is discarded, and the operational manifest remains -available. +The Protocol enforces limits for tree depth, total component count, children, +bindings, properties, repetition, extensions, permissions, assets, and +canonical bytes. Partial acceptance is not allowed. -`manifest_revision` never includes presentation. The separate -`presentation_revision` is bound to the accepted manifest revision, so an -overlay cannot be reused with a different capability declaration. +`manifest_revision` excludes presentation. `presentation_revision` hashes the +complete presentation and is bound to the accepted manifest revision, so a +presentation cannot be reused with a different capability declaration. -## How presentation reaches the Control Plane +## How it reaches the Control Plane -Within SFP, the Provider includes `ProviderPresentation` in the existing +The Provider returns `ProviderPresentation` through the existing `ManifestService.GetManifest` response. The Agent validates and caches the -accepted operational and presentation snapshots independently. +manifest and presentation independently. + +A future SF-AOP contract will transport the accepted snapshots to the Control +Plane. No second SFP presentation RPC is introduced. Once received, the +Control Plane resolves component identifiers through its renderer registry, +binds the current runtime data, applies its active skin, and renders the +surface. -The Agent-to-Control-Plane transport for that accepted snapshot will be -defined by SF-AOP. When a Control Plane receives the pair, it can reproduce the -same schema-derived model, apply the validated overlay, and render it through -its active skin. SFP does not introduce a second presentation RPC. +For the exact service envelope, revision construction, limits, and public +Python validators, return to +[Provider manifest exchange](provider-manifest.md). + +## Using the Python contract + +| Module | Responsibility | +| --- | --- | +| [`contract.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/contract.py) | Owns the supported surface identifiers, core component catalog, binding-source identifiers, renderer metadata limits, and component-tree bounds. | +| [`validation.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/validation.py) | Exposes complete Manifest Exchange validation, independent presentation acceptance, presentation revision calculation, and presentation fallback. | -For exact wire fields, revision construction, size limits, and public Python -validators, return to [Provider manifest exchange](provider-manifest.md). +Provider and Agent implementations should import these canonical definitions +instead of duplicating component identifiers, source identifiers, or limits. +Renderer-specific property schemas belong to the Control Plane renderer +registry and are deliberately not defined by these Protocol modules. diff --git a/docs/v0.1.0/procedures/triggers.md b/docs/v0.1.0/procedures/triggers.md index 31c8080..2b198d2 100644 --- a/docs/v0.1.0/procedures/triggers.md +++ b/docs/v0.1.0/procedures/triggers.md @@ -233,9 +233,9 @@ publication has no separate schema-version field and cannot negotiate a schema independently. Provider presentation does not participate in publication or acknowledgement. -Its labels, visual groups, field order, displays, and assets may improve how a -consumer renders a declared trigger, but the trigger identifier and -authoritative `payload_schema` remain the complete wire contract. +Trigger policy and event surfaces may improve how a consumer configures or +renders a declared trigger, but the trigger identifier and authoritative +`payload_schema` remain the complete wire contract. `presentation_revision` is not part of the stream binding or publication content fingerprint. diff --git a/docs/v0.1.0/reference/conformance-coverage.md b/docs/v0.1.0/reference/conformance-coverage.md index c3fac49..07ec9a5 100644 --- a/docs/v0.1.0/reference/conformance-coverage.md +++ b/docs/v0.1.0/reference/conformance-coverage.md @@ -68,7 +68,7 @@ documentation. | [`endpoint-discovery`](../procedures/endpoint-discovery.md) | `sfp.endpoint_discovery.v1.contract` | Descriptor parsing, canonical serialization, filename, identity, generation, socket path, permissions, and size limits | | [`bootstrap`](../bootstrap.md) | `sfp.bootstrap.v1.contract` and `validation` | Handshake request and response validity, identity correlation, version selection, generation fencing, and session bounds | | [`health`](../procedures/health.md) | `sfp.health_contract` with `grpc.health.v1` | Standard service identity, Provider-wide Watch key, lifecycle states, eligibility inputs, failure scenarios, and diagnostic bounds | -| [`manifest`](../procedures/provider-manifest.md) | `sfp.manifest.v1.contract` and `validation` | Declaration shape, embedded schemas, identifiers, session binding, independent manifest/presentation revisions, schema-addressed overlays, optional groups, safe assets, fallback, and invalid documents | +| [`manifest`](../procedures/provider-manifest.md) | `sfp.manifest.v1.contract` and `validation` | Declaration shape, embedded schemas, identifiers, session binding, independent revisions, bounded component trees, surface bindings, renderer requirements, core fallback, safe assets, and invalid documents | | [`capability-assessment`](../procedures/capability-assessment.md) | `sfp.capability_assessment.v1.contract` and `validation` | Request and response validity, session and manifest correlation, mixed support findings, invalid invariants, and requirement states | ### Exchange and recover diff --git a/docs/v0.1.0/stylesheets/extra.css b/docs/v0.1.0/stylesheets/extra.css index f59fee6..baf7cd7 100644 --- a/docs/v0.1.0/stylesheets/extra.css +++ b/docs/v0.1.0/stylesheets/extra.css @@ -10,156 +10,3 @@ margin-inline: auto; max-width: 100%; } - -.md-typeset .sf-presentation-preview { - background: color-mix(in srgb, var(--md-default-bg-color) 94%, var(--md-accent-fg-color)); - border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 22%, transparent); - border-radius: 0.55rem; - margin: 1.2rem 0; - overflow: hidden; - padding: 1rem; -} - -.md-typeset .sf-presentation-preview__label, -.md-typeset .sf-presentation-preview small { - color: var(--md-accent-fg-color); - display: block; - font-size: 0.62rem; - font-weight: 700; - letter-spacing: 0.09em; - margin-bottom: 0.5rem; -} - -.md-typeset .sf-presentation-provider { - align-items: center; - display: flex; - gap: 0.8rem; - padding: 0.7rem 0; -} - -.md-typeset .sf-presentation-provider p, -.md-typeset .sf-presentation-section p, -.md-typeset .sf-presentation-columns p { - margin: 0.2rem 0 0; -} - -.md-typeset .sf-presentation-provider__icon { - align-items: center; - background: var(--md-accent-fg-color); - border-radius: 0.45rem; - color: var(--md-primary-bg-color); - display: flex; - flex: 0 0 2.6rem; - font-weight: 700; - height: 2.6rem; - justify-content: center; -} - -.md-typeset .sf-presentation-section, -.md-typeset .sf-presentation-columns > section { - background: color-mix(in srgb, var(--md-default-bg-color) 96%, var(--md-default-fg-color)); - border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 16%, transparent); - border-radius: 0.4rem; - padding: 0.8rem; -} - -.md-typeset .sf-presentation-section > span, -.md-typeset .sf-presentation-columns h3 { - font-weight: 700; -} - -.md-typeset .sf-presentation-capabilities, -.md-typeset .sf-presentation-columns { - display: grid; - gap: 0.65rem; - grid-template-columns: repeat(3, minmax(0, 1fr)); - margin-top: 0.8rem; -} - -.md-typeset .sf-presentation-capabilities { - grid-template-columns: repeat(2, minmax(0, 1fr)); -} - -.md-typeset .sf-presentation-capabilities > div { - border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); - border-radius: 0.35rem; - padding: 0.65rem; -} - -.md-typeset .sf-presentation-capabilities strong, -.md-typeset .sf-presentation-columns label { - display: block; -} - -.md-typeset .sf-presentation-columns--two { - grid-template-columns: repeat(2, minmax(0, 1fr)); -} - -.md-typeset .sf-presentation-columns section > :first-child { - margin-top: 0; -} - -.md-typeset .sf-presentation-columns section > :last-child { - margin-bottom: 0; -} - -.md-typeset .sf-presentation-columns label { - font-size: 0.72rem; - margin-top: 0.65rem; -} - -.md-typeset .sf-presentation-columns input, -.md-typeset .sf-presentation-meter { - background: var(--md-code-bg-color); - border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 20%, transparent); - border-radius: 0.3rem; - box-sizing: border-box; - color: var(--md-default-fg-color); - display: block; - font: inherit; - margin-top: 0.25rem; - padding: 0.35rem 0.45rem; - width: 100%; -} - -.md-typeset .sf-presentation-subsection { - border-top: 1px solid color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); - font-size: 0.7rem; - font-weight: 700; - margin-top: 0.8rem; - padding-top: 0.65rem; -} - -.md-typeset .sf-presentation-columns dl, -.md-typeset .sf-presentation-columns dl div { - margin: 0; -} - -.md-typeset .sf-presentation-columns dl div { - align-items: center; - border-bottom: 1px solid color-mix(in srgb, var(--md-default-fg-color) 12%, transparent); - display: flex; - justify-content: space-between; - padding: 0.55rem 0; -} - -.md-typeset .sf-presentation-columns dd { - margin: 0; -} - -.md-typeset .sf-presentation-badge { - background: color-mix(in srgb, var(--md-accent-fg-color) 16%, transparent); - border-radius: 999px; - color: var(--md-accent-fg-color); - font-size: 0.68rem; - font-weight: 700; - padding: 0.15rem 0.5rem; -} - -@media screen and (max-width: 52rem) { - .md-typeset .sf-presentation-columns, - .md-typeset .sf-presentation-columns--two, - .md-typeset .sf-presentation-capabilities { - grid-template-columns: 1fr; - } -} diff --git a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto index 4d8b072..b300851 100644 --- a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto +++ b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto @@ -136,116 +136,91 @@ message TriggerDeclaration { message ProviderPresentation { // Presentation document version. Version 1 is defined by this package. uint32 presentation_schema_version = 1; - // Optional Provider-level description, branding and visual groups. - ProviderView provider = 2; - // Optional overlays keyed by declared operation identifier. - map operations = 3; - // Optional overlays keyed by declared trigger identifier. - map triggers = 4; + // Optional Provider-level surfaces. + PresentationTarget provider = 2; + // Optional surfaces keyed by declared operation identifier. + map operations = 3; + // Optional surfaces keyed by declared trigger identifier. + map triggers = 4; // Embedded content-addressed visuals keyed by their sha256 digest. map assets = 5; -} - -// ProviderView describes the Provider itself. Group order is declaration order; -// operations and triggers opt into a group by ID, and ungrouped capabilities -// remain visible through schema-derived rendering. -message ProviderView { - string summary = 1; - string description = 2; - string icon_asset_digest = 3; - string banner_asset_digest = 4; - repeated CapabilityGroup groups = 5; -} - -// CapabilityGroup supplies optional visual organization without duplicating -// operation or trigger membership. -message CapabilityGroup { - string id = 1; - string label = 2; - string description = 3; - string icon_asset_digest = 4; -} - -// OperationView supplies labels and schema-addressed overlays for one declared -// operation. Empty group_id means that the operation is not grouped. -message OperationView { - string label = 1; - string summary = 2; - string description = 3; - string icon_asset_digest = 4; - string group_id = 5; - SchemaView input = 6; - SchemaView result = 7; -} - -// TriggerView supplies labels and a schema-addressed overlay for one declared -// trigger. Empty group_id means that the trigger is not grouped. -message TriggerView { - string label = 1; - string summary = 2; - string description = 3; - string icon_asset_digest = 4; - string group_id = 5; - SchemaView payload = 6; -} - -// SchemaView adds optional ordering, grouping and compatible render hints to a -// JSON Schema. Every pointer addresses a field schema in the corresponding -// operation input/result or trigger payload schema. Unmentioned fields remain -// visible and retain their schema-defined semantics. -message SchemaView { - repeated string field_order = 1; - repeated FieldGroup groups = 2; - map fields = 3; -} - -// FieldGroup visually groups schema fields. Field pointers may appear in at -// most one group and group order is declaration order. -message FieldGroup { - string id = 1; - string label = 2; - string description = 3; - repeated string fields = 4; -} - -// FieldView supplies optional text and compatible render preferences for one -// schema field. It cannot change validation, requiredness or visibility. -message FieldView { - string label = 1; - string help_text = 2; - string placeholder = 3; - string unit = 4; - InputWidget widget = 5; - DisplayStyle display = 6; -} - -// InputWidget selects an optional input control compatible with a field's -// authoritative JSON Schema. Unspecified delegates entirely to the renderer. -enum InputWidget { - INPUT_WIDGET_UNSPECIFIED = 0; - INPUT_WIDGET_TEXT = 1; - INPUT_WIDGET_MULTILINE = 2; - INPUT_WIDGET_SECRET = 3; - INPUT_WIDGET_NUMBER = 4; - INPUT_WIDGET_SLIDER = 5; - INPUT_WIDGET_CHECKBOX = 6; - INPUT_WIDGET_SELECT = 7; - INPUT_WIDGET_RADIO = 8; - INPUT_WIDGET_DATE_TIME = 9; - INPUT_WIDGET_JSON = 10; -} - -// DisplayStyle selects an optional read-only presentation compatible with a -// field's authoritative JSON Schema. Unspecified delegates to the renderer. -enum DisplayStyle { - DISPLAY_STYLE_UNSPECIFIED = 0; - DISPLAY_STYLE_TEXT = 1; - DISPLAY_STYLE_CODE = 2; - DISPLAY_STYLE_JSON = 3; - DISPLAY_STYLE_TABLE = 4; - DISPLAY_STYLE_BADGE = 5; - DISPLAY_STYLE_METRIC = 6; - DISPLAY_STYLE_DATE_TIME = 7; + // Renderer metadata keyed by the custom component namespace it serves. + // Core stateforge.ui components never require an entry here. + map renderer_requirements = 6; +} + +// PresentationTarget owns the surfaces declared for one Provider, operation or +// trigger. Keys are versioned surface identifiers defined by this contract. +message PresentationTarget { + map surfaces = 1; +} + +// PresentationSurface is one bounded declarative component tree. +message PresentationSurface { + ComponentNode root = 1; +} + +// ComponentNode selects a renderer by identifier and supplies only declarative +// data. Properties are interpreted by the Control Plane renderer registry, not +// by SFP. Custom components require renderer metadata and a core-only fallback. +message ComponentNode { + string component_identifier = 1; + google.protobuf.Struct properties = 2; + map bindings = 3; + repeated ComponentNode children = 4; + ComponentNode fallback = 5; + Condition condition = 6; + Repetition repeat = 7; + // Renderer-defined slot name to embedded asset digest. + map asset_bindings = 8; +} + +// DataBinding points at immutable data supplied by the Control Plane for the +// current surface. Empty pointer selects the complete source document. Scope is +// empty except for bindings to a named repetition item. +message DataBinding { + string source_identifier = 1; + string pointer = 2; + string scope = 3; +} + +// ConditionOperator controls whether a node is rendered. Equality compares +// JSON values exactly after resolving the binding. +enum ConditionOperator { + CONDITION_OPERATOR_UNSPECIFIED = 0; + CONDITION_OPERATOR_EXISTS = 1; + CONDITION_OPERATOR_NOT_EXISTS = 2; + CONDITION_OPERATOR_EQUALS = 3; + CONDITION_OPERATOR_NOT_EQUALS = 4; +} + +// Condition is optional. EXISTS and NOT_EXISTS omit value; equality operators +// require value, including an explicitly supplied JSON null. +message Condition { + DataBinding binding = 1; + ConditionOperator operator = 2; + google.protobuf.Value value = 3; +} + +// Repetition renders a node once per item in one bound collection. max_items is +// a required positive safety ceiling; item_scope names the item for descendant +// bindings. +message Repetition { + DataBinding collection = 1; + string item_scope = 2; + uint32 max_items = 3; +} + +// RendererRequirement identifies a separately distributed renderer extension. +// SFP transports metadata only: no executable bytes, URL or install command is +// carried by this message. Permissions are versioned identifiers understood by +// the Control Plane extension host. +message RendererRequirement { + string extension_identifier = 1; + string extension_version = 2; + string renderer_api_version = 3; + string artifact_digest = 4; + repeated string permissions = 5; } // PresentationAsset is embedded, content-addressed media. The map key is the diff --git a/scripts/ci/verify_installed.py b/scripts/ci/verify_installed.py index d055abd..6ca8f19 100644 --- a/scripts/ci/verify_installed.py +++ b/scripts/ci/verify_installed.py @@ -30,6 +30,7 @@ from stateforge_protocol.sfp.endpoint_discovery.v1 import ( contract as endpoint_discovery_contract, ) +from stateforge_protocol.sfp.manifest.v1 import contract as manifest_contract from stateforge_protocol.sfp.manifest.v1 import manifest_pb2 from stateforge_protocol.sfp.manifest.v1 import ( validation as manifest_validation, @@ -228,7 +229,9 @@ def _verify_manifest_validation(fixture_root: Path) -> int: ): raise ValueError("Installed Provider presentation was not accepted") - presented.presentation.provider.summary = "Tampered presentation" + presented.presentation.provider.surfaces[ + manifest_contract.PROVIDER_OVERVIEW_SURFACE + ].root.properties.update({"tampered": True}) rejected = manifest_validation.validate_manifest_exchange(presented) if ( rejected.presentation_status diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py index 933f3fd..d695028 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -6,11 +6,11 @@ import re import struct import zlib -from collections.abc import Iterable from typing import Any, Final, Never, cast -from urllib.parse import unquote from xml.etree import ElementTree +import rfc8785 + from stateforge_protocol.sfp.manifest.v1 import contract, manifest_pb2 _LOCAL_ASSET_REFERENCE: Final = re.compile( @@ -80,9 +80,6 @@ "y2", } ) -_SCALAR_TYPES: Final = frozenset({"boolean", "integer", "number", "string"}) -_NUMBER_TYPES: Final = frozenset({"integer", "number"}) -_JSON_TYPES: Final = frozenset({"array", "object"}) _PNG_SIGNATURE: Final = b"\x89PNG\r\n\x1a\n" _PNG_CHUNK_OVERHEAD: Final = 12 _PNG_IHDR_BYTES: Final = 13 @@ -98,315 +95,376 @@ def validate_presentation_semantics( *, error_type: type[ValueError], ) -> None: - """Validate references, schema overlays and assets for presentation v1.""" + """Validate a bounded component tree and all of its references.""" operations = cast(dict[str, dict[str, Any]], manifest["operations"]) triggers = cast(dict[str, dict[str, Any]], manifest["triggers"]) - operation_views = cast( + operation_targets = cast( dict[str, dict[str, Any]], presentation["operations"] ) - trigger_views = cast(dict[str, dict[str, Any]], presentation["triggers"]) + trigger_targets = cast(dict[str, dict[str, Any]], presentation["triggers"]) + requirements = cast( + dict[str, dict[str, Any]], presentation["rendererRequirements"] + ) - if not operation_views.keys() <= operations.keys(): + if not operation_targets.keys() <= operations.keys(): + raise error_type( + "presentation: operation target does not name a declared operation" + ) + if not trigger_targets.keys() <= triggers.keys(): raise error_type( - "presentation: operation view does not name a declared operation" + "presentation: trigger target does not name a declared trigger" ) - if not trigger_views.keys() <= triggers.keys(): + if contract.CORE_COMPONENT_NAMESPACE in requirements: raise error_type( - "presentation: trigger view does not name a declared trigger" + "presentation: core components cannot require an extension" ) - group_ids = _validate_capability_groups(presentation, error_type) - for identifier, view in operation_views.items(): - _validate_group_reference(view, group_ids, error_type) - declaration = operations[identifier] - if "input" in view: - _validate_schema_view( - cast(dict[str, Any], view["input"]), - cast(dict[str, Any], declaration["inputSchema"]), - input_scope=True, - error_type=error_type, - ) - if "result" in view: - _validate_schema_view( - cast(dict[str, Any], view["result"]), - cast(dict[str, Any], declaration["resultSchema"]), - input_scope=False, - error_type=error_type, - ) - for identifier, view in trigger_views.items(): - _validate_group_reference(view, group_ids, error_type) - if "payload" in view: - declaration = triggers[identifier] - _validate_schema_view( - cast(dict[str, Any], view["payload"]), - cast(dict[str, Any], declaration["payloadSchema"]), - input_scope=False, - error_type=error_type, + state = _PresentationState() + provider = presentation.get("provider") + if isinstance(provider, dict): + _validate_target( + provider, + target_kind="provider", + permitted_surfaces=contract.PROVIDER_SURFACES, + state=state, + requirements=requirements, + error_type=error_type, + ) + for target in operation_targets.values(): + _validate_target( + target, + target_kind="operation", + permitted_surfaces=contract.OPERATION_SURFACES, + state=state, + requirements=requirements, + error_type=error_type, + ) + for target in trigger_targets.values(): + _validate_target( + target, + target_kind="trigger", + permitted_surfaces=contract.TRIGGER_SURFACES, + state=state, + requirements=requirements, + error_type=error_type, + ) + + if requirements.keys() != state.custom_namespaces: + raise error_type( + "presentation: renderer requirements must exactly match custom " + "component namespaces" + ) + for namespace, requirement in requirements.items(): + if ( + _namespace(cast(str, requirement["extensionIdentifier"])) + != namespace + ): + raise error_type( + "presentation: renderer extension namespace must match its " + "component namespace" ) - _validate_assets(presentation, message, error_type) + _validate_assets(message, state.asset_references, error_type) -def _validate_capability_groups( - presentation: dict[str, Any], error_type: type[ValueError] -) -> frozenset[str]: - provider = presentation.get("provider") - if provider is None: - return frozenset() - groups = cast(dict[str, Any], provider)["groups"] - identifiers = [cast(dict[str, Any], group)["id"] for group in groups] - if len(identifiers) != len(set(identifiers)): - raise error_type("presentation: capability group IDs must be unique") - return frozenset(cast(Iterable[str], identifiers)) - - -def _validate_group_reference( - view: dict[str, Any], - group_ids: frozenset[str], - error_type: type[ValueError], -) -> None: - group_id = view["groupId"] - if group_id and group_id not in group_ids: - raise error_type("presentation: capability group reference is missing") +class _PresentationState: + """Track document-wide component and reference budgets.""" + def __init__(self) -> None: + self.component_count = 0 + self.custom_namespaces: set[str] = set() + self.asset_references: set[str] = set() -def _validate_schema_view( - view: dict[str, Any], - schema: dict[str, Any], + +def _validate_target( + target: dict[str, Any], *, - input_scope: bool, + target_kind: str, + permitted_surfaces: frozenset[str], + state: _PresentationState, + requirements: dict[str, dict[str, Any]], error_type: type[ValueError], ) -> None: - pointers = list(cast(list[str], view["fieldOrder"])) - field_views = cast(dict[str, dict[str, Any]], view["fields"]) - pointers.extend(field_views) - grouped: list[str] = [] - group_ids: list[str] = [] - for group in cast(list[dict[str, Any]], view["groups"]): - group_ids.append(cast(str, group["id"])) - grouped.extend(cast(list[str], group["fields"])) - if len(group_ids) != len(set(group_ids)): - raise error_type("presentation: field group IDs must be unique") - if len(grouped) != len(set(grouped)): + surfaces = cast(dict[str, dict[str, Any]], target["surfaces"]) + unsupported = surfaces.keys() - permitted_surfaces + if unsupported: raise error_type( - "presentation: a field may belong to at most one field group" + f"presentation: surface is not valid for {target_kind} targets" + ) + for surface_identifier, surface in surfaces.items(): + _validate_component( + cast(dict[str, Any], surface["root"]), + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=frozenset(), + depth=1, + core_only=False, + state=state, + requirements=requirements, + error_type=error_type, ) - pointers.extend(grouped) - property_nodes = _property_schema_nodes(schema) - resolved: dict[str, dict[str, Any]] = {} - for pointer in set(pointers): - target = _resolve_json_pointer(schema, pointer, error_type) - if not isinstance(target, dict) or id(target) not in property_nodes: - raise error_type( - "presentation: JSON Pointer must name a schema field" - ) - resolved[pointer] = target - for pointer, field_view in field_views.items(): - target = _follow_local_reference(resolved[pointer], schema, error_type) - _validate_field_preferences( - field_view, - target, - input_scope=input_scope, +def _validate_component( + node: dict[str, Any], + *, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], + depth: int, + core_only: bool, + state: _PresentationState, + requirements: dict[str, dict[str, Any]], + error_type: type[ValueError], +) -> None: + if depth > contract.MAX_PRESENTATION_COMPONENT_DEPTH: + raise error_type("presentation: component depth limit exceeded") + state.component_count += 1 + if state.component_count > contract.MAX_PRESENTATION_COMPONENTS: + raise error_type("presentation: component count limit exceeded") + + _validate_component_identity( + node, + core_only=core_only, + state=state, + requirements=requirements, + error_type=error_type, + ) + + properties = cast(dict[str, Any], node["properties"]) + if ( + len(rfc8785.dumps(properties)) + > contract.MAX_COMPONENT_PROPERTIES_BYTES + ): + raise error_type("presentation: component properties limit exceeded") + + current_scopes = _extend_repetition_scopes( + node, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=scopes, + error_type=error_type, + ) + + for binding in cast(dict[str, dict[str, Any]], node["bindings"]).values(): + _validate_binding( + binding, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=current_scopes, error_type=error_type, ) + _validate_optional_condition( + node, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=current_scopes, + error_type=error_type, + ) + state.asset_references.update( + cast(dict[str, str], node["assetBindings"]).values() + ) + _validate_optional_fallback( + node, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=current_scopes, + depth=depth, + state=state, + requirements=requirements, + error_type=error_type, + ) + for child in cast(list[dict[str, Any]], node["children"]): + _validate_component( + child, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=current_scopes, + depth=depth + 1, + core_only=core_only, + state=state, + requirements=requirements, + error_type=error_type, + ) -def _property_schema_nodes(schema: dict[str, Any]) -> set[int]: - nodes: set[int] = set() - pending: list[object] = [schema] - seen: set[int] = set() - while pending: - current = pending.pop() - if isinstance(current, dict): - identity = id(current) - if identity in seen: - continue - seen.add(identity) - properties = current.get("properties") - if isinstance(properties, dict): - nodes.update( - id(value) - for value in properties.values() - if isinstance(value, dict) - ) - pending.extend(current.values()) - elif isinstance(current, list): - pending.extend(current) - return nodes - - -def _resolve_json_pointer( - document: object, pointer: str, error_type: type[ValueError] -) -> object: - current = document - for raw_token in pointer.split("/")[1:]: - token = raw_token.replace("~1", "/").replace("~0", "~") - if isinstance(current, dict) and token in current: - current = current[token] - elif isinstance(current, list) and token.isdigit(): - index = int(token) - if index >= len(current): - raise error_type("presentation: JSON Pointer does not resolve") - current = current[index] - else: - raise error_type("presentation: JSON Pointer does not resolve") - return current - - -def _follow_local_reference( - schema: dict[str, Any], - root: dict[str, Any], + +def _validate_component_identity( + node: dict[str, Any], + *, + core_only: bool, + state: _PresentationState, + requirements: dict[str, dict[str, Any]], error_type: type[ValueError], -) -> dict[str, Any]: - current = schema - seen: set[int] = set() - while "$ref" in current: - identity = id(current) - if identity in seen: - raise error_type("presentation: cyclic field schema reference") - seen.add(identity) - reference = current["$ref"] - if not isinstance(reference, str) or not reference.startswith("#"): - raise error_type("presentation: field schema reference is invalid") - fragment = unquote(reference[1:]) - target = ( - root - if not fragment - else _resolve_json_pointer(root, fragment, error_type) +) -> None: + identifier = cast(str, node["componentIdentifier"]) + namespace = _namespace(identifier) + is_core = namespace == contract.CORE_COMPONENT_NAMESPACE + if is_core and identifier not in contract.CORE_COMPONENT_IDENTIFIERS: + raise error_type("presentation: unknown core component identifier") + if core_only and not is_core: + raise error_type( + "presentation: custom component fallback must use core components" ) - if not isinstance(target, dict): + if not is_core: + if namespace not in requirements: + raise error_type( + "presentation: custom component has no renderer requirement" + ) + if "fallback" not in node: raise error_type( - "presentation: field schema reference must name a schema" + "presentation: custom component requires a core fallback" ) - current = target - return current + state.custom_namespaces.add(namespace) -def _validate_field_preferences( - view: dict[str, Any], - schema: dict[str, Any], +def _extend_repetition_scopes( + node: dict[str, Any], *, - input_scope: bool, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], error_type: type[ValueError], -) -> None: - widget = cast(str, view["widget"]) - display = cast(str, view["display"]) - if not input_scope and ( - widget != "INPUT_WIDGET_UNSPECIFIED" or view["placeholder"] - ): - raise error_type( - "presentation: output fields cannot declare input preferences" - ) - types = _schema_types(schema) - _validate_widget(widget, schema, types, error_type) - _validate_display(display, schema, types, error_type) +) -> frozenset[str]: + repeat = node.get("repeat") + if not isinstance(repeat, dict): + return scopes + _validate_binding( + cast(dict[str, Any], repeat["collection"]), + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=scopes, + error_type=error_type, + ) + item_scope = cast(str, repeat["itemScope"]) + if item_scope in scopes: + raise error_type("presentation: repetition scopes must be unique") + return scopes | {item_scope} -def _validate_widget( - widget: str, - schema: dict[str, Any], - types: frozenset[str], +def _validate_optional_condition( + node: dict[str, Any], + *, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], error_type: type[ValueError], ) -> None: - """Require one input widget to match its field schema.""" - if widget == "INPUT_WIDGET_UNSPECIFIED": - return - elif widget in {"INPUT_WIDGET_TEXT", "INPUT_WIDGET_MULTILINE"}: - _require_types(types, {"string"}, "input widget", error_type) - elif widget == "INPUT_WIDGET_SECRET": - _require_types(types, {"string"}, "input widget", error_type) - if schema.get("writeOnly") is not True: - raise error_type( - "presentation: secret widget requires a write-only field" - ) - elif widget == "INPUT_WIDGET_NUMBER": - _require_types(types, _NUMBER_TYPES, "input widget", error_type) - elif widget == "INPUT_WIDGET_SLIDER": - _require_types(types, _NUMBER_TYPES, "input widget", error_type) - if "minimum" not in schema or "maximum" not in schema: - raise error_type( - "presentation: slider requires schema minimum and maximum" - ) - elif widget == "INPUT_WIDGET_CHECKBOX": - _require_types(types, {"boolean"}, "input widget", error_type) - elif widget in {"INPUT_WIDGET_SELECT", "INPUT_WIDGET_RADIO"}: - if not isinstance(schema.get("enum"), list) or not schema["enum"]: - raise error_type( - "presentation: choice widget requires a nonempty schema enum" - ) - elif widget == "INPUT_WIDGET_DATE_TIME": - _require_date_time(schema, types, "input widget", error_type) - elif widget == "INPUT_WIDGET_JSON": - _require_types(types, _JSON_TYPES, "input widget", error_type) + condition = node.get("condition") + if isinstance(condition, dict): + _validate_condition( + condition, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=scopes, + error_type=error_type, + ) -def _validate_display( - display: str, - schema: dict[str, Any], - types: frozenset[str], +def _validate_optional_fallback( + node: dict[str, Any], + *, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], + depth: int, + state: _PresentationState, + requirements: dict[str, dict[str, Any]], error_type: type[ValueError], ) -> None: - """Require one display style to match its field schema.""" - if display == "DISPLAY_STYLE_UNSPECIFIED": - return - if display == "DISPLAY_STYLE_TEXT": - _require_types(types, _SCALAR_TYPES, "display style", error_type) - elif display == "DISPLAY_STYLE_CODE": - _require_types(types, {"string"}, "display style", error_type) - elif display == "DISPLAY_STYLE_JSON": - _require_types(types, _JSON_TYPES, "display style", error_type) - elif display == "DISPLAY_STYLE_TABLE": - _require_types(types, {"array"}, "display style", error_type) - elif display == "DISPLAY_STYLE_BADGE": - _require_types(types, _SCALAR_TYPES, "display style", error_type) - elif display == "DISPLAY_STYLE_METRIC": - _require_types(types, _NUMBER_TYPES, "display style", error_type) - elif display == "DISPLAY_STYLE_DATE_TIME": - _require_date_time(schema, types, "display style", error_type) - - -def _schema_types(schema: dict[str, Any]) -> frozenset[str]: - declared = schema.get("type") - if isinstance(declared, str): - return frozenset({declared}) - if isinstance(declared, list) and all( - isinstance(value, str) for value in declared - ): - return frozenset(declared) - {"null"} - return frozenset() + fallback = node.get("fallback") + if isinstance(fallback, dict): + _validate_component( + fallback, + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=scopes, + depth=depth + 1, + core_only=True, + state=state, + requirements=requirements, + error_type=error_type, + ) -def _require_types( - actual: frozenset[str], - permitted: Iterable[str], - preference: str, +def _validate_condition( + condition: dict[str, Any], + *, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], error_type: type[ValueError], ) -> None: - allowed = frozenset(permitted) - if not actual or not actual <= allowed: + _validate_binding( + cast(dict[str, Any], condition["binding"]), + surface_identifier=surface_identifier, + target_kind=target_kind, + scopes=scopes, + error_type=error_type, + ) + operator = cast(str, condition["operator"]) + has_value = "value" in condition + if ( + operator + in { + "CONDITION_OPERATOR_EXISTS", + "CONDITION_OPERATOR_NOT_EXISTS", + } + and has_value + ): raise error_type( - f"presentation: {preference} is incompatible with schema type" + "presentation: existence condition cannot declare a value" ) + if ( + operator + in { + "CONDITION_OPERATOR_EQUALS", + "CONDITION_OPERATOR_NOT_EQUALS", + } + and not has_value + ): + raise error_type("presentation: equality condition requires a value") -def _require_date_time( - schema: dict[str, Any], - types: frozenset[str], - preference: str, +def _validate_binding( + binding: dict[str, Any], + *, + surface_identifier: str, + target_kind: str, + scopes: frozenset[str], error_type: type[ValueError], ) -> None: - _require_types(types, {"string"}, preference, error_type) - if schema.get("format") not in {"date", "date-time", "time"}: + source = cast(str, binding["sourceIdentifier"]) + scope = cast(str, binding["scope"]) + if source == contract.REPETITION_ITEM_BINDING: + if not scope or scope not in scopes: + raise error_type( + "presentation: repetition item binding has no active scope" + ) + return + if scope: + raise error_type( + "presentation: only repetition item bindings may name a scope" + ) + allowed = set(contract.SURFACE_BINDING_SOURCES[surface_identifier]) + if surface_identifier == contract.EVIDENCE_SURFACE: + if target_kind == "operation": + allowed.discard(contract.TRIGGER_PAYLOAD_VALUE_BINDING) + elif target_kind == "trigger": + allowed.discard(contract.OPERATION_EVIDENCE_BINDING) + if source not in allowed: raise error_type( - f"presentation: {preference} requires a date or time format" + "presentation: binding source is unavailable on this surface" ) +def _namespace(identifier: str) -> str: + return identifier.split("/", 1)[0] + + def _validate_assets( - presentation: dict[str, Any], message: manifest_pb2.ProviderPresentation, + references: set[str], error_type: type[ValueError], ) -> None: assets = message.assets @@ -424,33 +482,12 @@ def _validate_assets( raise error_type("presentation: asset digest mismatch") _validate_asset_content(asset, error_type) - references = _asset_references(presentation) if not references <= assets.keys(): raise error_type("presentation: asset reference is missing") if assets.keys() - references: raise error_type("presentation: unreferenced asset is not permitted") -def _asset_references(presentation: dict[str, Any]) -> set[str]: - references: set[str] = set() - provider = presentation.get("provider") - if isinstance(provider, dict): - _add_asset_reference(references, provider.get("iconAssetDigest")) - _add_asset_reference(references, provider.get("bannerAssetDigest")) - for group in cast(list[dict[str, Any]], provider["groups"]): - _add_asset_reference(references, group.get("iconAssetDigest")) - for collection in ("operations", "triggers"): - views = cast(dict[str, dict[str, Any]], presentation[collection]) - for view in views.values(): - _add_asset_reference(references, view.get("iconAssetDigest")) - return references - - -def _add_asset_reference(references: set[str], value: object) -> None: - if isinstance(value, str) and value: - references.add(value) - - def _validate_asset_content( asset: manifest_pb2.PresentationAsset, error_type: type[ValueError], diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index af563b2..69e765a 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -35,23 +35,159 @@ MAX_PLATFORMS: Final = 256 MAX_PROFILE_CLAIMS_PER_OPERATION: Final = 64 -# Optional presentation-overlay limits mirrored by the packaged schema. +# Optional presentation-tree limits mirrored by the packaged schema. PRESENTATION_SCHEMA_VERSION: Final = 1 MAX_PRESENTATION_OPERATIONS: Final = MAX_OPERATIONS MAX_PRESENTATION_TRIGGERS: Final = MAX_TRIGGERS -MAX_CAPABILITY_GROUPS: Final = 64 -MAX_FIELD_GROUPS_PER_SCHEMA: Final = 64 -MAX_FIELDS_PER_GROUP: Final = 256 -MAX_FIELD_ORDER_ENTRIES: Final = 1_024 -MAX_FIELD_VIEWS_PER_SCHEMA: Final = 1_024 +MAX_PRESENTATION_SURFACES_PER_TARGET: Final = 8 +MAX_PRESENTATION_COMPONENTS: Final = 4_096 +MAX_PRESENTATION_COMPONENT_DEPTH: Final = 16 +MAX_COMPONENT_CHILDREN: Final = 256 +MAX_COMPONENT_BINDINGS: Final = 64 +MAX_COMPONENT_ASSET_BINDINGS: Final = 32 +MAX_COMPONENT_PROPERTIES_BYTES: Final = 64 * 1024 +MAX_RENDERER_REQUIREMENTS: Final = 64 +MAX_RENDERER_PERMISSIONS: Final = 32 +MAX_REPETITION_ITEMS: Final = 1_024 MAX_PRESENTATION_ASSETS: Final = 64 MAX_PRESENTATION_ASSET_BYTES: Final = 256 * 1024 MAX_PRESENTATION_ASSET_TOTAL_BYTES: Final = 1 * 1024 * 1024 MAX_PRESENTATION_ASSET_DIMENSION: Final = 8_192 -MAX_PRESENTATION_LABEL_CODE_POINTS: Final = 255 -MAX_PRESENTATION_SUMMARY_CODE_POINTS: Final = 512 -MAX_PRESENTATION_DESCRIPTION_CODE_POINTS: Final = 4_096 MAX_PRESENTATION_POINTER_CODE_POINTS: Final = 2_048 +MAX_PRESENTATION_SCOPE_CODE_POINTS: Final = 64 + +CORE_COMPONENT_NAMESPACE: Final = "stateforge.ui" + +PROVIDER_OVERVIEW_SURFACE: Final = "stateforge.ui/surface.provider.overview@1" +OPERATION_REQUEST_SURFACE: Final = "stateforge.ui/surface.operation.request@1" +OPERATION_RUN_SURFACE: Final = "stateforge.ui/surface.operation.run@1" +OPERATION_RESULT_SURFACE: Final = "stateforge.ui/surface.operation.result@1" +TRIGGER_POLICY_SURFACE: Final = "stateforge.ui/surface.trigger.policy@1" +TRIGGER_EVENT_SURFACE: Final = "stateforge.ui/surface.trigger.event@1" +EVIDENCE_SURFACE: Final = "stateforge.ui/surface.evidence@1" + +PROVIDER_SURFACES: Final = frozenset({PROVIDER_OVERVIEW_SURFACE}) +OPERATION_SURFACES: Final = frozenset( + { + OPERATION_REQUEST_SURFACE, + OPERATION_RUN_SURFACE, + OPERATION_RESULT_SURFACE, + EVIDENCE_SURFACE, + } +) +TRIGGER_SURFACES: Final = frozenset( + { + TRIGGER_POLICY_SURFACE, + TRIGGER_EVENT_SURFACE, + EVIDENCE_SURFACE, + } +) + +PROVIDER_MANIFEST_BINDING: Final = "stateforge.binding/provider.manifest@1" +PROVIDER_RUNTIME_BINDING: Final = "stateforge.binding/provider.runtime@1" +OPERATION_REQUEST_SCHEMA_BINDING: Final = ( + "stateforge.binding/operation.request.schema@1" +) +OPERATION_REQUEST_VALUE_BINDING: Final = ( + "stateforge.binding/operation.request.value@1" +) +OPERATION_RUN_BINDING: Final = "stateforge.binding/operation.run@1" +OPERATION_RESULT_SCHEMA_BINDING: Final = ( + "stateforge.binding/operation.result.schema@1" +) +OPERATION_RESULT_VALUE_BINDING: Final = ( + "stateforge.binding/operation.result.value@1" +) +OPERATION_EVIDENCE_BINDING: Final = "stateforge.binding/operation.evidence@1" +TRIGGER_PAYLOAD_SCHEMA_BINDING: Final = ( + "stateforge.binding/trigger.payload.schema@1" +) +TRIGGER_PAYLOAD_VALUE_BINDING: Final = ( + "stateforge.binding/trigger.payload.value@1" +) +AUDIT_BINDING: Final = "stateforge.binding/audit@1" +REPETITION_ITEM_BINDING: Final = "stateforge.binding/repetition.item@1" + +SURFACE_BINDING_SOURCES: Final = { + PROVIDER_OVERVIEW_SURFACE: frozenset( + {PROVIDER_MANIFEST_BINDING, PROVIDER_RUNTIME_BINDING} + ), + OPERATION_REQUEST_SURFACE: frozenset( + { + PROVIDER_MANIFEST_BINDING, + OPERATION_REQUEST_SCHEMA_BINDING, + OPERATION_REQUEST_VALUE_BINDING, + } + ), + OPERATION_RUN_SURFACE: frozenset( + { + PROVIDER_MANIFEST_BINDING, + OPERATION_REQUEST_VALUE_BINDING, + OPERATION_RUN_BINDING, + } + ), + OPERATION_RESULT_SURFACE: frozenset( + { + PROVIDER_MANIFEST_BINDING, + OPERATION_REQUEST_VALUE_BINDING, + OPERATION_RESULT_SCHEMA_BINDING, + OPERATION_RESULT_VALUE_BINDING, + OPERATION_EVIDENCE_BINDING, + } + ), + TRIGGER_POLICY_SURFACE: frozenset( + {PROVIDER_MANIFEST_BINDING, TRIGGER_PAYLOAD_SCHEMA_BINDING} + ), + TRIGGER_EVENT_SURFACE: frozenset( + { + PROVIDER_MANIFEST_BINDING, + TRIGGER_PAYLOAD_SCHEMA_BINDING, + TRIGGER_PAYLOAD_VALUE_BINDING, + } + ), + EVIDENCE_SURFACE: frozenset( + { + PROVIDER_MANIFEST_BINDING, + OPERATION_EVIDENCE_BINDING, + TRIGGER_PAYLOAD_VALUE_BINDING, + AUDIT_BINDING, + } + ), +} + +CORE_COMPONENT_IDENTIFIERS: Final = frozenset( + { + "stateforge.ui/layout.stack@1", + "stateforge.ui/layout.grid@1", + "stateforge.ui/layout.section@1", + "stateforge.ui/layout.tabs@1", + "stateforge.ui/layout.steps@1", + "stateforge.ui/input.form@1", + "stateforge.ui/input.field@1", + "stateforge.ui/input.object@1", + "stateforge.ui/input.array@1", + "stateforge.ui/input.key_value@1", + "stateforge.ui/input.code@1", + "stateforge.ui/content.text@1", + "stateforge.ui/content.markdown@1", + "stateforge.ui/data.key_value@1", + "stateforge.ui/data.table@1", + "stateforge.ui/data.tree@1", + "stateforge.ui/data.code@1", + "stateforge.ui/data.diff@1", + "stateforge.ui/data.log@1", + "stateforge.ui/status.badge@1", + "stateforge.ui/status.progress@1", + "stateforge.ui/status.timeline@1", + "stateforge.ui/data.metric@1", + "stateforge.ui/data.chart@1", + "stateforge.ui/data.topology@1", + "stateforge.ui/data.artifacts@1", + "stateforge.ui/media.image@1", + "stateforge.ui/action.operation_submit@1", + "stateforge.ui/action.operation_cancel@1", + } +) ALLOWED_PRESENTATION_MEDIA_TYPES: Final = frozenset( { diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json b/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json index e221ec7..db488f1 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest.schema.json @@ -242,7 +242,7 @@ }, "versionConstraint": { "type": "string", - "minLength": 0, + "minItems": 0, "maxLength": 255 } }, @@ -286,333 +286,220 @@ ], "additionalProperties": false }, - "presentationGroupId": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "pattern": "^[a-z][a-z0-9_-]*(?![\\s\\S])" - }, "jsonPointer": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^(/([^~/]|~0|~1)*)+$(?![\\s\\S])" }, - "presentationText": { + "bindingPointer": { + "oneOf": [ + { + "const": "" + }, + { + "$ref": "#/$defs/jsonPointer" + } + ] + }, + "presentationScope": { "type": "string", - "minLength": 0, - "maxLength": 4096 + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9_]*(?![\\s\\S])" }, - "capabilityGroup": { + "dataBinding": { "type": "object", "properties": { - "id": { - "$ref": "#/$defs/presentationGroupId" - }, - "label": { - "type": "string", - "minLength": 1, - "maxLength": 255 + "sourceIdentifier": { + "$ref": "#/$defs/identifier" }, - "description": { - "$ref": "#/$defs/presentationText" + "pointer": { + "$ref": "#/$defs/bindingPointer" }, - "iconAssetDigest": { + "scope": { "oneOf": [ { "const": "" }, { - "$ref": "#/$defs/revision" + "$ref": "#/$defs/presentationScope" } ] } }, "required": [ - "id", - "label", - "description", - "iconAssetDigest" + "sourceIdentifier", + "pointer", + "scope" ], "additionalProperties": false }, - "providerView": { + "condition": { "type": "object", "properties": { - "summary": { - "type": "string", - "minLength": 0, - "maxLength": 512 + "binding": { + "$ref": "#/$defs/dataBinding" }, - "description": { - "$ref": "#/$defs/presentationText" - }, - "iconAssetDigest": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/revision" - } - ] - }, - "bannerAssetDigest": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/revision" - } + "operator": { + "enum": [ + "CONDITION_OPERATOR_EXISTS", + "CONDITION_OPERATOR_NOT_EXISTS", + "CONDITION_OPERATOR_EQUALS", + "CONDITION_OPERATOR_NOT_EQUALS" ] }, - "groups": { - "type": "array", - "items": { - "$ref": "#/$defs/capabilityGroup" - }, - "minItems": 0, - "maxItems": 64 - } + "value": true }, "required": [ - "summary", - "description", - "iconAssetDigest", - "bannerAssetDigest", - "groups" + "binding", + "operator" ], "additionalProperties": false }, - "fieldGroup": { + "repetition": { "type": "object", "properties": { - "id": { - "$ref": "#/$defs/presentationGroupId" + "collection": { + "$ref": "#/$defs/dataBinding" }, - "label": { - "type": "string", - "minLength": 1, - "maxLength": 255 - }, - "description": { - "$ref": "#/$defs/presentationText" + "itemScope": { + "$ref": "#/$defs/presentationScope" }, - "fields": { - "type": "array", - "items": { - "$ref": "#/$defs/jsonPointer" - }, - "minItems": 1, - "maxItems": 256, - "uniqueItems": true + "maxItems": { + "type": "integer", + "minimum": 1, + "maximum": 1024 } }, "required": [ - "id", - "label", - "description", - "fields" + "collection", + "itemScope", + "maxItems" ], "additionalProperties": false }, - "fieldView": { + "componentNode": { "type": "object", "properties": { - "label": { - "type": "string", - "minLength": 0, - "maxLength": 255 - }, - "helpText": { - "$ref": "#/$defs/presentationText" - }, - "placeholder": { - "type": "string", - "minLength": 0, - "maxLength": 512 - }, - "unit": { - "type": "string", - "minLength": 0, - "maxLength": 64 + "componentIdentifier": { + "$ref": "#/$defs/identifier" }, - "widget": { - "enum": [ - "INPUT_WIDGET_UNSPECIFIED", - "INPUT_WIDGET_TEXT", - "INPUT_WIDGET_MULTILINE", - "INPUT_WIDGET_SECRET", - "INPUT_WIDGET_NUMBER", - "INPUT_WIDGET_SLIDER", - "INPUT_WIDGET_CHECKBOX", - "INPUT_WIDGET_SELECT", - "INPUT_WIDGET_RADIO", - "INPUT_WIDGET_DATE_TIME", - "INPUT_WIDGET_JSON" - ] + "properties": { + "type": "object" }, - "display": { - "enum": [ - "DISPLAY_STYLE_UNSPECIFIED", - "DISPLAY_STYLE_TEXT", - "DISPLAY_STYLE_CODE", - "DISPLAY_STYLE_JSON", - "DISPLAY_STYLE_TABLE", - "DISPLAY_STYLE_BADGE", - "DISPLAY_STYLE_METRIC", - "DISPLAY_STYLE_DATE_TIME" - ] - } - }, - "required": [ - "label", - "helpText", - "placeholder", - "unit", - "widget", - "display" - ], - "additionalProperties": false - }, - "schemaView": { - "type": "object", - "properties": { - "fieldOrder": { - "type": "array", - "items": { - "$ref": "#/$defs/jsonPointer" + "bindings": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/presentationScope" }, - "minItems": 0, - "maxItems": 1024, - "uniqueItems": true + "additionalProperties": { + "$ref": "#/$defs/dataBinding" + }, + "minProperties": 0, + "maxProperties": 64 }, - "groups": { + "children": { "type": "array", "items": { - "$ref": "#/$defs/fieldGroup" + "$ref": "#/$defs/componentNode" }, - "minItems": 0, - "maxItems": 64 + "minLength": 0, + "maxItems": 256 + }, + "fallback": { + "$ref": "#/$defs/componentNode" + }, + "condition": { + "$ref": "#/$defs/condition" + }, + "repeat": { + "$ref": "#/$defs/repetition" }, - "fields": { + "assetBindings": { "type": "object", "propertyNames": { - "$ref": "#/$defs/jsonPointer" + "$ref": "#/$defs/presentationScope" }, "additionalProperties": { - "$ref": "#/$defs/fieldView" + "$ref": "#/$defs/revision" }, "minProperties": 0, - "maxProperties": 1024 + "maxProperties": 32 } }, "required": [ - "fieldOrder", - "groups", - "fields" + "componentIdentifier", + "properties", + "bindings", + "children", + "assetBindings" ], "additionalProperties": false }, - "operationView": { + "presentationSurface": { "type": "object", "properties": { - "label": { - "type": "string", - "minLength": 0, - "maxLength": 255 - }, - "summary": { - "type": "string", - "minLength": 0, - "maxLength": 512 - }, - "description": { - "$ref": "#/$defs/presentationText" - }, - "iconAssetDigest": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/revision" - } - ] - }, - "groupId": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/presentationGroupId" - } - ] - }, - "input": { - "$ref": "#/$defs/schemaView" - }, - "result": { - "$ref": "#/$defs/schemaView" + "root": { + "$ref": "#/$defs/componentNode" } }, "required": [ - "label", - "summary", - "description", - "iconAssetDigest", - "groupId" + "root" ], "additionalProperties": false }, - "triggerView": { + "presentationTarget": { "type": "object", "properties": { - "label": { - "type": "string", - "minLength": 0, - "maxLength": 255 - }, - "summary": { - "type": "string", - "minLength": 0, - "maxLength": 512 + "surfaces": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/identifier" + }, + "additionalProperties": { + "$ref": "#/$defs/presentationSurface" + }, + "minProperties": 1, + "maxProperties": 8 + } + }, + "required": [ + "surfaces" + ], + "additionalProperties": false + }, + "rendererRequirement": { + "type": "object", + "properties": { + "extensionIdentifier": { + "$ref": "#/$defs/identifier" }, - "description": { - "$ref": "#/$defs/presentationText" + "extensionVersion": { + "$ref": "#/$defs/semver" }, - "iconAssetDigest": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/revision" - } - ] + "rendererApiVersion": { + "$ref": "#/$defs/semver" }, - "groupId": { - "oneOf": [ - { - "const": "" - }, - { - "$ref": "#/$defs/presentationGroupId" - } - ] + "artifactDigest": { + "$ref": "#/$defs/revision" }, - "payload": { - "$ref": "#/$defs/schemaView" + "permissions": { + "type": "array", + "items": { + "$ref": "#/$defs/identifier" + }, + "minItems": 0, + "maxItems": 32, + "uniqueItems": true } }, "required": [ - "label", - "summary", - "description", - "iconAssetDigest", - "groupId" + "extensionIdentifier", + "extensionVersion", + "rendererApiVersion", + "artifactDigest", + "permissions" ], "additionalProperties": false }, @@ -662,7 +549,7 @@ "const": 1 }, "provider": { - "$ref": "#/$defs/providerView" + "$ref": "#/$defs/presentationTarget" }, "operations": { "type": "object", @@ -670,7 +557,7 @@ "$ref": "#/$defs/identifier" }, "additionalProperties": { - "$ref": "#/$defs/operationView" + "$ref": "#/$defs/presentationTarget" }, "minProperties": 0, "maxProperties": 1024 @@ -681,7 +568,7 @@ "$ref": "#/$defs/identifier" }, "additionalProperties": { - "$ref": "#/$defs/triggerView" + "$ref": "#/$defs/presentationTarget" }, "minProperties": 0, "maxProperties": 1024 @@ -696,13 +583,25 @@ }, "minProperties": 0, "maxProperties": 64 + }, + "rendererRequirements": { + "type": "object", + "propertyNames": { + "$ref": "#/$defs/dottedIdentifier" + }, + "additionalProperties": { + "$ref": "#/$defs/rendererRequirement" + }, + "minProperties": 0, + "maxProperties": 64 } }, "required": [ "presentationSchemaVersion", "operations", "triggers", - "assets" + "assets", + "rendererRequirements" ], "additionalProperties": false }, diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py index 4e73b7b..5949287 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.py @@ -25,7 +25,7 @@ from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 -DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2stateforge_protocol/sfp/manifest/v1/manifest.proto\x12\x1astateforge.sfp.manifest.v1\x1a\x1cgoogle/protobuf/struct.proto\"\x96\x02\n\x12GetManifestRequest\x12\x41\n\x1d\x65xpected_provider_instance_id\x18\x01 \x01(\tR\x1a\x65xpectedProviderInstanceId\x12@\n\x1c\x65xpected_endpoint_generation\x18\x02 \x01(\x04R\x1a\x65xpectedEndpointGeneration\x12K\n\"supported_manifest_schema_versions\x18\x03 \x03(\rR\x1fsupportedManifestSchemaVersions\x12.\n\x13\x65xpected_session_id\x18\x04 \x01(\tR\x11\x65xpectedSessionId\"\xf0\x03\n\x13GetManifestResponse\x12\x30\n\x14provider_instance_id\x18\x01 \x01(\tR\x12providerInstanceId\x12/\n\x13\x65ndpoint_generation\x18\x02 \x01(\x04R\x12\x65ndpointGeneration\x12\x36\n\x17manifest_schema_version\x18\x03 \x01(\rR\x15manifestSchemaVersion\x12+\n\x11manifest_revision\x18\x04 \x01(\tR\x10manifestRevision\x12H\n\x08manifest\x18\x05 \x01(\x0b\x32,.stateforge.sfp.manifest.v1.ProviderManifestR\x08manifest\x12\x1d\n\nsession_id\x18\x06 \x01(\tR\tsessionId\x12T\n\x0cpresentation\x18\x07 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.ProviderPresentationR\x0cpresentation\x12\x38\n\x15presentation_revision\x18\x08 \x01(\tH\x00R\x14presentationRevision\x88\x01\x01\x42\x18\n\x16_presentation_revision\"\xbc\x07\n\x10ProviderManifest\x12+\n\x11provider_identity\x18\x01 \x01(\tR\x10providerIdentity\x12\x35\n\x16implementation_version\x18\x02 \x01(\tR\x15implementationVersion\x12!\n\x0c\x64isplay_name\x18\x03 \x01(\tR\x0b\x64isplayName\x12\\\n\noperations\x18\x04 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderManifest.OperationsEntryR\noperations\x12x\n\x14runtime_requirements\x18\x06 \x03(\x0b\x32\x45.stateforge.sfp.manifest.v1.ProviderManifest.RuntimeRequirementsEntryR\x13runtimeRequirements\x12O\n\tplatforms\x18\x07 \x03(\x0b\x32\x31.stateforge.sfp.manifest.v1.PlatformCompatibilityR\tplatforms\x12J\n\x14\x63onfiguration_schema\x18\x08 \x01(\x0b\x32\x17.google.protobuf.StructR\x13\x63onfigurationSchema\x12V\n\x08triggers\x18\t \x03(\x0b\x32:.stateforge.sfp.manifest.v1.ProviderManifest.TriggersEntryR\x08triggers\x1ao\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x46\n\x05value\x18\x02 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.OperationDeclarationR\x05value:\x02\x38\x01\x1av\n\x18RuntimeRequirementsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.RuntimeRequirementR\x05value:\x02\x38\x01\x1ak\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.TriggerDeclarationR\x05value:\x02\x38\x01\"\xb0\x01\n\x14OperationDeclaration\x12:\n\x0cinput_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\x0binputSchema\x12<\n\rresult_schema\x18\x02 \x01(\x0b\x32\x17.google.protobuf.StructR\x0cresultSchema\x12\x1e\n\nimplements\x18\x03 \x03(\tR\nimplements\"e\n\x12RuntimeRequirement\x12 \n\x0b\x64\x65scription\x18\x01 \x01(\tR\x0b\x64\x65scription\x12-\n\x12version_constraint\x18\x02 \x01(\tR\x11versionConstraint\"f\n\x15PlatformCompatibility\x12)\n\x10operating_system\x18\x01 \x01(\tR\x0foperatingSystem\x12\"\n\x0c\x61rchitecture\x18\x02 \x01(\tR\x0c\x61rchitecture\"T\n\x12TriggerDeclaration\x12>\n\x0epayload_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\rpayloadSchema\"\xea\x05\n\x14ProviderPresentation\x12>\n\x1bpresentation_schema_version\x18\x01 \x01(\rR\x19presentationSchemaVersion\x12\x44\n\x08provider\x18\x02 \x01(\x0b\x32(.stateforge.sfp.manifest.v1.ProviderViewR\x08provider\x12`\n\noperations\x18\x03 \x03(\x0b\x32@.stateforge.sfp.manifest.v1.ProviderPresentation.OperationsEntryR\noperations\x12Z\n\x08triggers\x18\x04 \x03(\x0b\x32>.stateforge.sfp.manifest.v1.ProviderPresentation.TriggersEntryR\x08triggers\x12T\n\x06\x61ssets\x18\x05 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderPresentation.AssetsEntryR\x06\x61ssets\x1ah\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12?\n\x05value\x18\x02 \x01(\x0b\x32).stateforge.sfp.manifest.v1.OperationViewR\x05value:\x02\x38\x01\x1a\x64\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12=\n\x05value\x18\x02 \x01(\x0b\x32\'.stateforge.sfp.manifest.v1.TriggerViewR\x05value:\x02\x38\x01\x1ah\n\x0b\x41ssetsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x43\n\x05value\x18\x02 \x01(\x0b\x32-.stateforge.sfp.manifest.v1.PresentationAssetR\x05value:\x02\x38\x01\"\xeb\x01\n\x0cProviderView\x12\x18\n\x07summary\x18\x01 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x02 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x03 \x01(\tR\x0ficonAssetDigest\x12.\n\x13\x62\x61nner_asset_digest\x18\x04 \x01(\tR\x11\x62\x61nnerAssetDigest\x12\x43\n\x06groups\x18\x05 \x03(\x0b\x32+.stateforge.sfp.manifest.v1.CapabilityGroupR\x06groups\"\x85\x01\n\x0f\x43\x61pabilityGroup\x12\x0e\n\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n\x05label\x18\x02 \x01(\tR\x05label\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\"\xa6\x02\n\rOperationView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x18\n\x07summary\x18\x02 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\x12\x19\n\x08group_id\x18\x05 \x01(\tR\x07groupId\x12<\n\x05input\x18\x06 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x05input\x12>\n\x06result\x18\x07 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x06result\"\xe8\x01\n\x0bTriggerView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x18\n\x07summary\x18\x02 \x01(\tR\x07summary\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12*\n\x11icon_asset_digest\x18\x04 \x01(\tR\x0ficonAssetDigest\x12\x19\n\x08group_id\x18\x05 \x01(\tR\x07groupId\x12@\n\x07payload\x18\x06 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.SchemaViewR\x07payload\"\x9b\x02\n\nSchemaView\x12\x1f\n\x0b\x66ield_order\x18\x01 \x03(\tR\nfieldOrder\x12>\n\x06groups\x18\x02 \x03(\x0b\x32&.stateforge.sfp.manifest.v1.FieldGroupR\x06groups\x12J\n\x06\x66ields\x18\x03 \x03(\x0b\x32\x32.stateforge.sfp.manifest.v1.SchemaView.FieldsEntryR\x06\x66ields\x1a`\n\x0b\x46ieldsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12;\n\x05value\x18\x02 \x01(\x0b\x32%.stateforge.sfp.manifest.v1.FieldViewR\x05value:\x02\x38\x01\"l\n\nFieldGroup\x12\x0e\n\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n\x05label\x18\x02 \x01(\tR\x05label\x12 \n\x0b\x64\x65scription\x18\x03 \x01(\tR\x0b\x64\x65scription\x12\x16\n\x06\x66ields\x18\x04 \x03(\tR\x06\x66ields\"\xf9\x01\n\tFieldView\x12\x14\n\x05label\x18\x01 \x01(\tR\x05label\x12\x1b\n\thelp_text\x18\x02 \x01(\tR\x08helpText\x12 \n\x0bplaceholder\x18\x03 \x01(\tR\x0bplaceholder\x12\x12\n\x04unit\x18\x04 \x01(\tR\x04unit\x12?\n\x06widget\x18\x05 \x01(\x0e\x32\'.stateforge.sfp.manifest.v1.InputWidgetR\x06widget\x12\x42\n\x07\x64isplay\x18\x06 \x01(\x0e\x32(.stateforge.sfp.manifest.v1.DisplayStyleR\x07\x64isplay\"\x95\x01\n\x11PresentationAsset\x12\x1d\n\nmedia_type\x18\x01 \x01(\tR\tmediaType\x12\x18\n\x07\x63ontent\x18\x02 \x01(\x0cR\x07\x63ontent\x12\x14\n\x05width\x18\x03 \x01(\rR\x05width\x12\x16\n\x06height\x18\x04 \x01(\rR\x06height\x12\x19\n\x08\x61lt_text\x18\x05 \x01(\tR\x07\x61ltText*\xa8\x02\n\x0bInputWidget\x12\x1c\n\x18INPUT_WIDGET_UNSPECIFIED\x10\x00\x12\x15\n\x11INPUT_WIDGET_TEXT\x10\x01\x12\x1a\n\x16INPUT_WIDGET_MULTILINE\x10\x02\x12\x17\n\x13INPUT_WIDGET_SECRET\x10\x03\x12\x17\n\x13INPUT_WIDGET_NUMBER\x10\x04\x12\x17\n\x13INPUT_WIDGET_SLIDER\x10\x05\x12\x19\n\x15INPUT_WIDGET_CHECKBOX\x10\x06\x12\x17\n\x13INPUT_WIDGET_SELECT\x10\x07\x12\x16\n\x12INPUT_WIDGET_RADIO\x10\x08\x12\x1a\n\x16INPUT_WIDGET_DATE_TIME\x10\t\x12\x15\n\x11INPUT_WIDGET_JSON\x10\n*\xde\x01\n\x0c\x44isplayStyle\x12\x1d\n\x19\x44ISPLAY_STYLE_UNSPECIFIED\x10\x00\x12\x16\n\x12\x44ISPLAY_STYLE_TEXT\x10\x01\x12\x16\n\x12\x44ISPLAY_STYLE_CODE\x10\x02\x12\x16\n\x12\x44ISPLAY_STYLE_JSON\x10\x03\x12\x17\n\x13\x44ISPLAY_STYLE_TABLE\x10\x04\x12\x17\n\x13\x44ISPLAY_STYLE_BADGE\x10\x05\x12\x18\n\x14\x44ISPLAY_STYLE_METRIC\x10\x06\x12\x1b\n\x17\x44ISPLAY_STYLE_DATE_TIME\x10\x07\x32\x81\x01\n\x0fManifestService\x12n\n\x0bGetManifest\x12..stateforge.sfp.manifest.v1.GetManifestRequest\x1a/.stateforge.sfp.manifest.v1.GetManifestResponseb\x06proto3') +DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2stateforge_protocol/sfp/manifest/v1/manifest.proto\x12\x1astateforge.sfp.manifest.v1\x1a\x1cgoogle/protobuf/struct.proto\"\x96\x02\n\x12GetManifestRequest\x12\x41\n\x1d\x65xpected_provider_instance_id\x18\x01 \x01(\tR\x1a\x65xpectedProviderInstanceId\x12@\n\x1c\x65xpected_endpoint_generation\x18\x02 \x01(\x04R\x1a\x65xpectedEndpointGeneration\x12K\n\"supported_manifest_schema_versions\x18\x03 \x03(\rR\x1fsupportedManifestSchemaVersions\x12.\n\x13\x65xpected_session_id\x18\x04 \x01(\tR\x11\x65xpectedSessionId\"\xf0\x03\n\x13GetManifestResponse\x12\x30\n\x14provider_instance_id\x18\x01 \x01(\tR\x12providerInstanceId\x12/\n\x13\x65ndpoint_generation\x18\x02 \x01(\x04R\x12\x65ndpointGeneration\x12\x36\n\x17manifest_schema_version\x18\x03 \x01(\rR\x15manifestSchemaVersion\x12+\n\x11manifest_revision\x18\x04 \x01(\tR\x10manifestRevision\x12H\n\x08manifest\x18\x05 \x01(\x0b\x32,.stateforge.sfp.manifest.v1.ProviderManifestR\x08manifest\x12\x1d\n\nsession_id\x18\x06 \x01(\tR\tsessionId\x12T\n\x0cpresentation\x18\x07 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.ProviderPresentationR\x0cpresentation\x12\x38\n\x15presentation_revision\x18\x08 \x01(\tH\x00R\x14presentationRevision\x88\x01\x01\x42\x18\n\x16_presentation_revision\"\xbc\x07\n\x10ProviderManifest\x12+\n\x11provider_identity\x18\x01 \x01(\tR\x10providerIdentity\x12\x35\n\x16implementation_version\x18\x02 \x01(\tR\x15implementationVersion\x12!\n\x0c\x64isplay_name\x18\x03 \x01(\tR\x0b\x64isplayName\x12\\\n\noperations\x18\x04 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderManifest.OperationsEntryR\noperations\x12x\n\x14runtime_requirements\x18\x06 \x03(\x0b\x32\x45.stateforge.sfp.manifest.v1.ProviderManifest.RuntimeRequirementsEntryR\x13runtimeRequirements\x12O\n\tplatforms\x18\x07 \x03(\x0b\x32\x31.stateforge.sfp.manifest.v1.PlatformCompatibilityR\tplatforms\x12J\n\x14\x63onfiguration_schema\x18\x08 \x01(\x0b\x32\x17.google.protobuf.StructR\x13\x63onfigurationSchema\x12V\n\x08triggers\x18\t \x03(\x0b\x32:.stateforge.sfp.manifest.v1.ProviderManifest.TriggersEntryR\x08triggers\x1ao\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x46\n\x05value\x18\x02 \x01(\x0b\x32\x30.stateforge.sfp.manifest.v1.OperationDeclarationR\x05value:\x02\x38\x01\x1av\n\x18RuntimeRequirementsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.RuntimeRequirementR\x05value:\x02\x38\x01\x1ak\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.TriggerDeclarationR\x05value:\x02\x38\x01\"\xb0\x01\n\x14OperationDeclaration\x12:\n\x0cinput_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\x0binputSchema\x12<\n\rresult_schema\x18\x02 \x01(\x0b\x32\x17.google.protobuf.StructR\x0cresultSchema\x12\x1e\n\nimplements\x18\x03 \x03(\tR\nimplements\"e\n\x12RuntimeRequirement\x12 \n\x0b\x64\x65scription\x18\x01 \x01(\tR\x0b\x64\x65scription\x12-\n\x12version_constraint\x18\x02 \x01(\tR\x11versionConstraint\"f\n\x15PlatformCompatibility\x12)\n\x10operating_system\x18\x01 \x01(\tR\x0foperatingSystem\x12\"\n\x0c\x61rchitecture\x18\x02 \x01(\tR\x0c\x61rchitecture\"T\n\x12TriggerDeclaration\x12>\n\x0epayload_schema\x18\x01 \x01(\x0b\x32\x17.google.protobuf.StructR\rpayloadSchema\"\xf7\x07\n\x14ProviderPresentation\x12>\n\x1bpresentation_schema_version\x18\x01 \x01(\rR\x19presentationSchemaVersion\x12J\n\x08provider\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.PresentationTargetR\x08provider\x12`\n\noperations\x18\x03 \x03(\x0b\x32@.stateforge.sfp.manifest.v1.ProviderPresentation.OperationsEntryR\noperations\x12Z\n\x08triggers\x18\x04 \x03(\x0b\x32>.stateforge.sfp.manifest.v1.ProviderPresentation.TriggersEntryR\x08triggers\x12T\n\x06\x61ssets\x18\x05 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ProviderPresentation.AssetsEntryR\x06\x61ssets\x12\x7f\n\x15renderer_requirements\x18\x06 \x03(\x0b\x32J.stateforge.sfp.manifest.v1.ProviderPresentation.RendererRequirementsEntryR\x14rendererRequirements\x1am\n\x0fOperationsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.PresentationTargetR\x05value:\x02\x38\x01\x1ak\n\rTriggersEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x44\n\x05value\x18\x02 \x01(\x0b\x32..stateforge.sfp.manifest.v1.PresentationTargetR\x05value:\x02\x38\x01\x1ah\n\x0b\x41ssetsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x43\n\x05value\x18\x02 \x01(\x0b\x32-.stateforge.sfp.manifest.v1.PresentationAssetR\x05value:\x02\x38\x01\x1ax\n\x19RendererRequirementsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x45\n\x05value\x18\x02 \x01(\x0b\x32/.stateforge.sfp.manifest.v1.RendererRequirementR\x05value:\x02\x38\x01\"\xdc\x01\n\x12PresentationTarget\x12X\n\x08surfaces\x18\x01 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.PresentationTarget.SurfacesEntryR\x08surfaces\x1al\n\rSurfacesEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x45\n\x05value\x18\x02 \x01(\x0b\x32/.stateforge.sfp.manifest.v1.PresentationSurfaceR\x05value:\x02\x38\x01\"T\n\x13PresentationSurface\x12=\n\x04root\x18\x01 \x01(\x0b\x32).stateforge.sfp.manifest.v1.ComponentNodeR\x04root\"\xf0\x05\n\rComponentNode\x12\x31\n\x14\x63omponent_identifier\x18\x01 \x01(\tR\x13\x63omponentIdentifier\x12\x37\n\nproperties\x18\x02 \x01(\x0b\x32\x17.google.protobuf.StructR\nproperties\x12S\n\x08\x62indings\x18\x03 \x03(\x0b\x32\x37.stateforge.sfp.manifest.v1.ComponentNode.BindingsEntryR\x08\x62indings\x12\x45\n\x08\x63hildren\x18\x04 \x03(\x0b\x32).stateforge.sfp.manifest.v1.ComponentNodeR\x08\x63hildren\x12\x45\n\x08\x66\x61llback\x18\x05 \x01(\x0b\x32).stateforge.sfp.manifest.v1.ComponentNodeR\x08\x66\x61llback\x12\x43\n\tcondition\x18\x06 \x01(\x0b\x32%.stateforge.sfp.manifest.v1.ConditionR\tcondition\x12>\n\x06repeat\x18\x07 \x01(\x0b\x32&.stateforge.sfp.manifest.v1.RepetitionR\x06repeat\x12\x63\n\x0e\x61sset_bindings\x18\x08 \x03(\x0b\x32<.stateforge.sfp.manifest.v1.ComponentNode.AssetBindingsEntryR\rassetBindings\x1a\x64\n\rBindingsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12=\n\x05value\x18\x02 \x01(\x0b\x32\'.stateforge.sfp.manifest.v1.DataBindingR\x05value:\x02\x38\x01\x1a@\n\x12\x41ssetBindingsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\tR\x05value:\x02\x38\x01\"j\n\x0b\x44\x61taBinding\x12+\n\x11source_identifier\x18\x01 \x01(\tR\x10sourceIdentifier\x12\x18\n\x07pointer\x18\x02 \x01(\tR\x07pointer\x12\x14\n\x05scope\x18\x03 \x01(\tR\x05scope\"\xc7\x01\n\tCondition\x12\x41\n\x07\x62inding\x18\x01 \x01(\x0b\x32\'.stateforge.sfp.manifest.v1.DataBindingR\x07\x62inding\x12I\n\x08operator\x18\x02 \x01(\x0e\x32-.stateforge.sfp.manifest.v1.ConditionOperatorR\x08operator\x12,\n\x05value\x18\x03 \x01(\x0b\x32\x16.google.protobuf.ValueR\x05value\"\x91\x01\n\nRepetition\x12G\n\ncollection\x18\x01 \x01(\x0b\x32\'.stateforge.sfp.manifest.v1.DataBindingR\ncollection\x12\x1d\n\nitem_scope\x18\x02 \x01(\tR\titemScope\x12\x1b\n\tmax_items\x18\x03 \x01(\rR\x08maxItems\"\xf2\x01\n\x13RendererRequirement\x12\x31\n\x14\x65xtension_identifier\x18\x01 \x01(\tR\x13\x65xtensionIdentifier\x12+\n\x11\x65xtension_version\x18\x02 \x01(\tR\x10\x65xtensionVersion\x12\x30\n\x14renderer_api_version\x18\x03 \x01(\tR\x12rendererApiVersion\x12\'\n\x0f\x61rtifact_digest\x18\x04 \x01(\tR\x0e\x61rtifactDigest\x12 \n\x0bpermissions\x18\x05 \x03(\tR\x0bpermissions\"\x95\x01\n\x11PresentationAsset\x12\x1d\n\nmedia_type\x18\x01 \x01(\tR\tmediaType\x12\x18\n\x07\x63ontent\x18\x02 \x01(\x0cR\x07\x63ontent\x12\x14\n\x05width\x18\x03 \x01(\rR\x05width\x12\x16\n\x06height\x18\x04 \x01(\rR\x06height\x12\x19\n\x08\x61lt_text\x18\x05 \x01(\tR\x07\x61ltText*\xbb\x01\n\x11\x43onditionOperator\x12\"\n\x1e\x43ONDITION_OPERATOR_UNSPECIFIED\x10\x00\x12\x1d\n\x19\x43ONDITION_OPERATOR_EXISTS\x10\x01\x12!\n\x1d\x43ONDITION_OPERATOR_NOT_EXISTS\x10\x02\x12\x1d\n\x19\x43ONDITION_OPERATOR_EQUALS\x10\x03\x12!\n\x1d\x43ONDITION_OPERATOR_NOT_EQUALS\x10\x04\x32\x81\x01\n\x0fManifestService\x12n\n\x0bGetManifest\x12..stateforge.sfp.manifest.v1.GetManifestRequest\x1a/.stateforge.sfp.manifest.v1.GetManifestResponseb\x06proto3') _globals = globals() _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals) @@ -44,12 +44,16 @@ _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_options = b'8\001' _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._loaded_options = None _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_options = b'8\001' - _globals['_SCHEMAVIEW_FIELDSENTRY']._loaded_options = None - _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_options = b'8\001' - _globals['_INPUTWIDGET']._serialized_start=4779 - _globals['_INPUTWIDGET']._serialized_end=5075 - _globals['_DISPLAYSTYLE']._serialized_start=5078 - _globals['_DISPLAYSTYLE']._serialized_end=5300 + _globals['_PROVIDERPRESENTATION_RENDERERREQUIREMENTSENTRY']._loaded_options = None + _globals['_PROVIDERPRESENTATION_RENDERERREQUIREMENTSENTRY']._serialized_options = b'8\001' + _globals['_PRESENTATIONTARGET_SURFACESENTRY']._loaded_options = None + _globals['_PRESENTATIONTARGET_SURFACESENTRY']._serialized_options = b'8\001' + _globals['_COMPONENTNODE_BINDINGSENTRY']._loaded_options = None + _globals['_COMPONENTNODE_BINDINGSENTRY']._serialized_options = b'8\001' + _globals['_COMPONENTNODE_ASSETBINDINGSENTRY']._loaded_options = None + _globals['_COMPONENTNODE_ASSETBINDINGSENTRY']._serialized_options = b'8\001' + _globals['_CONDITIONOPERATOR']._serialized_start=5261 + _globals['_CONDITIONOPERATOR']._serialized_end=5448 _globals['_GETMANIFESTREQUEST']._serialized_start=113 _globals['_GETMANIFESTREQUEST']._serialized_end=391 _globals['_GETMANIFESTRESPONSE']._serialized_start=394 @@ -71,31 +75,37 @@ _globals['_TRIGGERDECLARATION']._serialized_start=2237 _globals['_TRIGGERDECLARATION']._serialized_end=2321 _globals['_PROVIDERPRESENTATION']._serialized_start=2324 - _globals['_PROVIDERPRESENTATION']._serialized_end=3070 - _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_start=2758 - _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_end=2862 - _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_start=2864 - _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_end=2964 - _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_start=2966 - _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_end=3070 - _globals['_PROVIDERVIEW']._serialized_start=3073 - _globals['_PROVIDERVIEW']._serialized_end=3308 - _globals['_CAPABILITYGROUP']._serialized_start=3311 - _globals['_CAPABILITYGROUP']._serialized_end=3444 - _globals['_OPERATIONVIEW']._serialized_start=3447 - _globals['_OPERATIONVIEW']._serialized_end=3741 - _globals['_TRIGGERVIEW']._serialized_start=3744 - _globals['_TRIGGERVIEW']._serialized_end=3976 - _globals['_SCHEMAVIEW']._serialized_start=3979 - _globals['_SCHEMAVIEW']._serialized_end=4262 - _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_start=4166 - _globals['_SCHEMAVIEW_FIELDSENTRY']._serialized_end=4262 - _globals['_FIELDGROUP']._serialized_start=4264 - _globals['_FIELDGROUP']._serialized_end=4372 - _globals['_FIELDVIEW']._serialized_start=4375 - _globals['_FIELDVIEW']._serialized_end=4624 - _globals['_PRESENTATIONASSET']._serialized_start=4627 - _globals['_PRESENTATIONASSET']._serialized_end=4776 - _globals['_MANIFESTSERVICE']._serialized_start=5303 - _globals['_MANIFESTSERVICE']._serialized_end=5432 + _globals['_PROVIDERPRESENTATION']._serialized_end=3339 + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_start=2893 + _globals['_PROVIDERPRESENTATION_OPERATIONSENTRY']._serialized_end=3002 + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_start=3004 + _globals['_PROVIDERPRESENTATION_TRIGGERSENTRY']._serialized_end=3111 + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_start=3113 + _globals['_PROVIDERPRESENTATION_ASSETSENTRY']._serialized_end=3217 + _globals['_PROVIDERPRESENTATION_RENDERERREQUIREMENTSENTRY']._serialized_start=3219 + _globals['_PROVIDERPRESENTATION_RENDERERREQUIREMENTSENTRY']._serialized_end=3339 + _globals['_PRESENTATIONTARGET']._serialized_start=3342 + _globals['_PRESENTATIONTARGET']._serialized_end=3562 + _globals['_PRESENTATIONTARGET_SURFACESENTRY']._serialized_start=3454 + _globals['_PRESENTATIONTARGET_SURFACESENTRY']._serialized_end=3562 + _globals['_PRESENTATIONSURFACE']._serialized_start=3564 + _globals['_PRESENTATIONSURFACE']._serialized_end=3648 + _globals['_COMPONENTNODE']._serialized_start=3651 + _globals['_COMPONENTNODE']._serialized_end=4403 + _globals['_COMPONENTNODE_BINDINGSENTRY']._serialized_start=4237 + _globals['_COMPONENTNODE_BINDINGSENTRY']._serialized_end=4337 + _globals['_COMPONENTNODE_ASSETBINDINGSENTRY']._serialized_start=4339 + _globals['_COMPONENTNODE_ASSETBINDINGSENTRY']._serialized_end=4403 + _globals['_DATABINDING']._serialized_start=4405 + _globals['_DATABINDING']._serialized_end=4511 + _globals['_CONDITION']._serialized_start=4514 + _globals['_CONDITION']._serialized_end=4713 + _globals['_REPETITION']._serialized_start=4716 + _globals['_REPETITION']._serialized_end=4861 + _globals['_RENDERERREQUIREMENT']._serialized_start=4864 + _globals['_RENDERERREQUIREMENT']._serialized_end=5106 + _globals['_PRESENTATIONASSET']._serialized_start=5109 + _globals['_PRESENTATIONASSET']._serialized_end=5258 + _globals['_MANIFESTSERVICE']._serialized_start=5451 + _globals['_MANIFESTSERVICE']._serialized_end=5580 # @@protoc_insertion_point(module_scope) diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi index c778a2b..c816f03 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi @@ -20,71 +20,29 @@ else: DESCRIPTOR: _descriptor.FileDescriptor -class _InputWidget: +class _ConditionOperator: ValueType = _typing.NewType("ValueType", _builtins.int) V: _TypeAlias = ValueType # noqa: Y015 -class _InputWidgetEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_InputWidget.ValueType], _builtins.type): +class _ConditionOperatorEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_ConditionOperator.ValueType], _builtins.type): DESCRIPTOR: _descriptor.EnumDescriptor - INPUT_WIDGET_UNSPECIFIED: _InputWidget.ValueType # 0 - INPUT_WIDGET_TEXT: _InputWidget.ValueType # 1 - INPUT_WIDGET_MULTILINE: _InputWidget.ValueType # 2 - INPUT_WIDGET_SECRET: _InputWidget.ValueType # 3 - INPUT_WIDGET_NUMBER: _InputWidget.ValueType # 4 - INPUT_WIDGET_SLIDER: _InputWidget.ValueType # 5 - INPUT_WIDGET_CHECKBOX: _InputWidget.ValueType # 6 - INPUT_WIDGET_SELECT: _InputWidget.ValueType # 7 - INPUT_WIDGET_RADIO: _InputWidget.ValueType # 8 - INPUT_WIDGET_DATE_TIME: _InputWidget.ValueType # 9 - INPUT_WIDGET_JSON: _InputWidget.ValueType # 10 - -class InputWidget(_InputWidget, metaclass=_InputWidgetEnumTypeWrapper): - """InputWidget selects an optional input control compatible with a field's - authoritative JSON Schema. Unspecified delegates entirely to the renderer. + CONDITION_OPERATOR_UNSPECIFIED: _ConditionOperator.ValueType # 0 + CONDITION_OPERATOR_EXISTS: _ConditionOperator.ValueType # 1 + CONDITION_OPERATOR_NOT_EXISTS: _ConditionOperator.ValueType # 2 + CONDITION_OPERATOR_EQUALS: _ConditionOperator.ValueType # 3 + CONDITION_OPERATOR_NOT_EQUALS: _ConditionOperator.ValueType # 4 + +class ConditionOperator(_ConditionOperator, metaclass=_ConditionOperatorEnumTypeWrapper): + """ConditionOperator controls whether a node is rendered. Equality compares + JSON values exactly after resolving the binding. """ -INPUT_WIDGET_UNSPECIFIED: InputWidget.ValueType # 0 -INPUT_WIDGET_TEXT: InputWidget.ValueType # 1 -INPUT_WIDGET_MULTILINE: InputWidget.ValueType # 2 -INPUT_WIDGET_SECRET: InputWidget.ValueType # 3 -INPUT_WIDGET_NUMBER: InputWidget.ValueType # 4 -INPUT_WIDGET_SLIDER: InputWidget.ValueType # 5 -INPUT_WIDGET_CHECKBOX: InputWidget.ValueType # 6 -INPUT_WIDGET_SELECT: InputWidget.ValueType # 7 -INPUT_WIDGET_RADIO: InputWidget.ValueType # 8 -INPUT_WIDGET_DATE_TIME: InputWidget.ValueType # 9 -INPUT_WIDGET_JSON: InputWidget.ValueType # 10 -Global___InputWidget: _TypeAlias = InputWidget # noqa: Y015 - -class _DisplayStyle: - ValueType = _typing.NewType("ValueType", _builtins.int) - V: _TypeAlias = ValueType # noqa: Y015 - -class _DisplayStyleEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_DisplayStyle.ValueType], _builtins.type): - DESCRIPTOR: _descriptor.EnumDescriptor - DISPLAY_STYLE_UNSPECIFIED: _DisplayStyle.ValueType # 0 - DISPLAY_STYLE_TEXT: _DisplayStyle.ValueType # 1 - DISPLAY_STYLE_CODE: _DisplayStyle.ValueType # 2 - DISPLAY_STYLE_JSON: _DisplayStyle.ValueType # 3 - DISPLAY_STYLE_TABLE: _DisplayStyle.ValueType # 4 - DISPLAY_STYLE_BADGE: _DisplayStyle.ValueType # 5 - DISPLAY_STYLE_METRIC: _DisplayStyle.ValueType # 6 - DISPLAY_STYLE_DATE_TIME: _DisplayStyle.ValueType # 7 - -class DisplayStyle(_DisplayStyle, metaclass=_DisplayStyleEnumTypeWrapper): - """DisplayStyle selects an optional read-only presentation compatible with a - field's authoritative JSON Schema. Unspecified delegates to the renderer. - """ - -DISPLAY_STYLE_UNSPECIFIED: DisplayStyle.ValueType # 0 -DISPLAY_STYLE_TEXT: DisplayStyle.ValueType # 1 -DISPLAY_STYLE_CODE: DisplayStyle.ValueType # 2 -DISPLAY_STYLE_JSON: DisplayStyle.ValueType # 3 -DISPLAY_STYLE_TABLE: DisplayStyle.ValueType # 4 -DISPLAY_STYLE_BADGE: DisplayStyle.ValueType # 5 -DISPLAY_STYLE_METRIC: DisplayStyle.ValueType # 6 -DISPLAY_STYLE_DATE_TIME: DisplayStyle.ValueType # 7 -Global___DisplayStyle: _TypeAlias = DisplayStyle # noqa: Y015 +CONDITION_OPERATOR_UNSPECIFIED: ConditionOperator.ValueType # 0 +CONDITION_OPERATOR_EXISTS: ConditionOperator.ValueType # 1 +CONDITION_OPERATOR_NOT_EXISTS: ConditionOperator.ValueType # 2 +CONDITION_OPERATOR_EQUALS: ConditionOperator.ValueType # 3 +CONDITION_OPERATOR_NOT_EQUALS: ConditionOperator.ValueType # 4 +Global___ConditionOperator: _TypeAlias = ConditionOperator # noqa: Y015 @_typing.final class GetManifestRequest(_message.Message): @@ -478,12 +436,12 @@ class ProviderPresentation(_message.Message): VALUE_FIELD_NUMBER: _builtins.int key: _builtins.str @_builtins.property - def value(self) -> Global___OperationView: ... + def value(self) -> Global___PresentationTarget: ... def __init__( self, *, key: _builtins.str = ..., - value: Global___OperationView | None = ..., + value: Global___PresentationTarget | None = ..., ) -> None: ... _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... @@ -499,12 +457,12 @@ class ProviderPresentation(_message.Message): VALUE_FIELD_NUMBER: _builtins.int key: _builtins.str @_builtins.property - def value(self) -> Global___TriggerView: ... + def value(self) -> Global___PresentationTarget: ... def __init__( self, *, key: _builtins.str = ..., - value: Global___TriggerView | None = ..., + value: Global___PresentationTarget | None = ..., ) -> None: ... _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... @@ -533,322 +491,366 @@ class ProviderPresentation(_message.Message): def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... + @_typing.final + class RendererRequirementsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___RendererRequirement: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___RendererRequirement | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + PRESENTATION_SCHEMA_VERSION_FIELD_NUMBER: _builtins.int PROVIDER_FIELD_NUMBER: _builtins.int OPERATIONS_FIELD_NUMBER: _builtins.int TRIGGERS_FIELD_NUMBER: _builtins.int ASSETS_FIELD_NUMBER: _builtins.int + RENDERER_REQUIREMENTS_FIELD_NUMBER: _builtins.int presentation_schema_version: _builtins.int """Presentation document version. Version 1 is defined by this package.""" @_builtins.property - def provider(self) -> Global___ProviderView: - """Optional Provider-level description, branding and visual groups.""" + def provider(self) -> Global___PresentationTarget: + """Optional Provider-level surfaces.""" @_builtins.property - def operations(self) -> _containers.MessageMap[_builtins.str, Global___OperationView]: - """Optional overlays keyed by declared operation identifier.""" + def operations(self) -> _containers.MessageMap[_builtins.str, Global___PresentationTarget]: + """Optional surfaces keyed by declared operation identifier.""" @_builtins.property - def triggers(self) -> _containers.MessageMap[_builtins.str, Global___TriggerView]: - """Optional overlays keyed by declared trigger identifier.""" + def triggers(self) -> _containers.MessageMap[_builtins.str, Global___PresentationTarget]: + """Optional surfaces keyed by declared trigger identifier.""" @_builtins.property def assets(self) -> _containers.MessageMap[_builtins.str, Global___PresentationAsset]: """Embedded content-addressed visuals keyed by their sha256 digest.""" + @_builtins.property + def renderer_requirements(self) -> _containers.MessageMap[_builtins.str, Global___RendererRequirement]: + """Renderer metadata keyed by the custom component namespace it serves. + Core stateforge.ui components never require an entry here. + """ + def __init__( self, *, presentation_schema_version: _builtins.int = ..., - provider: Global___ProviderView | None = ..., - operations: _abc.Mapping[_builtins.str, Global___OperationView] | None = ..., - triggers: _abc.Mapping[_builtins.str, Global___TriggerView] | None = ..., + provider: Global___PresentationTarget | None = ..., + operations: _abc.Mapping[_builtins.str, Global___PresentationTarget] | None = ..., + triggers: _abc.Mapping[_builtins.str, Global___PresentationTarget] | None = ..., assets: _abc.Mapping[_builtins.str, Global___PresentationAsset] | None = ..., + renderer_requirements: _abc.Mapping[_builtins.str, Global___RendererRequirement] | None = ..., ) -> None: ... _HasFieldArgType: _TypeAlias = _typing.Literal["provider", b"provider"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["assets", b"assets", "operations", b"operations", "presentation_schema_version", b"presentation_schema_version", "provider", b"provider", "triggers", b"triggers"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["assets", b"assets", "operations", b"operations", "presentation_schema_version", b"presentation_schema_version", "provider", b"provider", "renderer_requirements", b"renderer_requirements", "triggers", b"triggers"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... Global___ProviderPresentation: _TypeAlias = ProviderPresentation # noqa: Y015 @_typing.final -class ProviderView(_message.Message): - """ProviderView describes the Provider itself. Group order is declaration order; - operations and triggers opt into a group by ID, and ungrouped capabilities - remain visible through schema-derived rendering. +class PresentationTarget(_message.Message): + """PresentationTarget owns the surfaces declared for one Provider, operation or + trigger. Keys are versioned surface identifiers defined by this contract. """ DESCRIPTOR: _descriptor.Descriptor - SUMMARY_FIELD_NUMBER: _builtins.int - DESCRIPTION_FIELD_NUMBER: _builtins.int - ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int - BANNER_ASSET_DIGEST_FIELD_NUMBER: _builtins.int - GROUPS_FIELD_NUMBER: _builtins.int - summary: _builtins.str - description: _builtins.str - icon_asset_digest: _builtins.str - banner_asset_digest: _builtins.str + @_typing.final + class SurfacesEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___PresentationSurface: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___PresentationSurface | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + SURFACES_FIELD_NUMBER: _builtins.int @_builtins.property - def groups(self) -> _containers.RepeatedCompositeFieldContainer[Global___CapabilityGroup]: ... + def surfaces(self) -> _containers.MessageMap[_builtins.str, Global___PresentationSurface]: ... def __init__( self, *, - summary: _builtins.str = ..., - description: _builtins.str = ..., - icon_asset_digest: _builtins.str = ..., - banner_asset_digest: _builtins.str = ..., - groups: _abc.Iterable[Global___CapabilityGroup] | None = ..., + surfaces: _abc.Mapping[_builtins.str, Global___PresentationSurface] | None = ..., ) -> None: ... _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["banner_asset_digest", b"banner_asset_digest", "description", b"description", "groups", b"groups", "icon_asset_digest", b"icon_asset_digest", "summary", b"summary"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["surfaces", b"surfaces"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___ProviderView: _TypeAlias = ProviderView # noqa: Y015 +Global___PresentationTarget: _TypeAlias = PresentationTarget # noqa: Y015 @_typing.final -class CapabilityGroup(_message.Message): - """CapabilityGroup supplies optional visual organization without duplicating - operation or trigger membership. - """ +class PresentationSurface(_message.Message): + """PresentationSurface is one bounded declarative component tree.""" DESCRIPTOR: _descriptor.Descriptor - ID_FIELD_NUMBER: _builtins.int - LABEL_FIELD_NUMBER: _builtins.int - DESCRIPTION_FIELD_NUMBER: _builtins.int - ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int - id: _builtins.str - label: _builtins.str - description: _builtins.str - icon_asset_digest: _builtins.str + ROOT_FIELD_NUMBER: _builtins.int + @_builtins.property + def root(self) -> Global___ComponentNode: ... def __init__( self, *, - id: _builtins.str = ..., - label: _builtins.str = ..., - description: _builtins.str = ..., - icon_asset_digest: _builtins.str = ..., + root: Global___ComponentNode | None = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + _HasFieldArgType: _TypeAlias = _typing.Literal["root", b"root"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "icon_asset_digest", b"icon_asset_digest", "id", b"id", "label", b"label"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["root", b"root"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___CapabilityGroup: _TypeAlias = CapabilityGroup # noqa: Y015 +Global___PresentationSurface: _TypeAlias = PresentationSurface # noqa: Y015 @_typing.final -class OperationView(_message.Message): - """OperationView supplies labels and schema-addressed overlays for one declared - operation. Empty group_id means that the operation is not grouped. +class ComponentNode(_message.Message): + """ComponentNode selects a renderer by identifier and supplies only declarative + data. Properties are interpreted by the Control Plane renderer registry, not + by SFP. Custom components require renderer metadata and a core-only fallback. """ DESCRIPTOR: _descriptor.Descriptor - LABEL_FIELD_NUMBER: _builtins.int - SUMMARY_FIELD_NUMBER: _builtins.int - DESCRIPTION_FIELD_NUMBER: _builtins.int - ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int - GROUP_ID_FIELD_NUMBER: _builtins.int - INPUT_FIELD_NUMBER: _builtins.int - RESULT_FIELD_NUMBER: _builtins.int - label: _builtins.str - summary: _builtins.str - description: _builtins.str - icon_asset_digest: _builtins.str - group_id: _builtins.str + @_typing.final + class BindingsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + @_builtins.property + def value(self) -> Global___DataBinding: ... + def __init__( + self, + *, + key: _builtins.str = ..., + value: Global___DataBinding | None = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + @_typing.final + class AssetBindingsEntry(_message.Message): + DESCRIPTOR: _descriptor.Descriptor + + KEY_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + key: _builtins.str + value: _builtins.str + def __init__( + self, + *, + key: _builtins.str = ..., + value: _builtins.str = ..., + ) -> None: ... + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... + _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 + def ClearField(self, field_name: _ClearFieldArgType) -> None: ... + def WhichOneof(self, oneof_group: _Never) -> None: ... + + COMPONENT_IDENTIFIER_FIELD_NUMBER: _builtins.int + PROPERTIES_FIELD_NUMBER: _builtins.int + BINDINGS_FIELD_NUMBER: _builtins.int + CHILDREN_FIELD_NUMBER: _builtins.int + FALLBACK_FIELD_NUMBER: _builtins.int + CONDITION_FIELD_NUMBER: _builtins.int + REPEAT_FIELD_NUMBER: _builtins.int + ASSET_BINDINGS_FIELD_NUMBER: _builtins.int + component_identifier: _builtins.str + @_builtins.property + def properties(self) -> _struct_pb2.Struct: ... + @_builtins.property + def bindings(self) -> _containers.MessageMap[_builtins.str, Global___DataBinding]: ... @_builtins.property - def input(self) -> Global___SchemaView: ... + def children(self) -> _containers.RepeatedCompositeFieldContainer[Global___ComponentNode]: ... @_builtins.property - def result(self) -> Global___SchemaView: ... + def fallback(self) -> Global___ComponentNode: ... + @_builtins.property + def condition(self) -> Global___Condition: ... + @_builtins.property + def repeat(self) -> Global___Repetition: ... + @_builtins.property + def asset_bindings(self) -> _containers.ScalarMap[_builtins.str, _builtins.str]: + """Renderer-defined slot name to embedded asset digest.""" + def __init__( self, *, - label: _builtins.str = ..., - summary: _builtins.str = ..., - description: _builtins.str = ..., - icon_asset_digest: _builtins.str = ..., - group_id: _builtins.str = ..., - input: Global___SchemaView | None = ..., - result: Global___SchemaView | None = ..., + component_identifier: _builtins.str = ..., + properties: _struct_pb2.Struct | None = ..., + bindings: _abc.Mapping[_builtins.str, Global___DataBinding] | None = ..., + children: _abc.Iterable[Global___ComponentNode] | None = ..., + fallback: Global___ComponentNode | None = ..., + condition: Global___Condition | None = ..., + repeat: Global___Repetition | None = ..., + asset_bindings: _abc.Mapping[_builtins.str, _builtins.str] | None = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _typing.Literal["input", b"input", "result", b"result"] # noqa: Y015 + _HasFieldArgType: _TypeAlias = _typing.Literal["condition", b"condition", "fallback", b"fallback", "properties", b"properties", "repeat", b"repeat"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "group_id", b"group_id", "icon_asset_digest", b"icon_asset_digest", "input", b"input", "label", b"label", "result", b"result", "summary", b"summary"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["asset_bindings", b"asset_bindings", "bindings", b"bindings", "children", b"children", "component_identifier", b"component_identifier", "condition", b"condition", "fallback", b"fallback", "properties", b"properties", "repeat", b"repeat"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___OperationView: _TypeAlias = OperationView # noqa: Y015 +Global___ComponentNode: _TypeAlias = ComponentNode # noqa: Y015 @_typing.final -class TriggerView(_message.Message): - """TriggerView supplies labels and a schema-addressed overlay for one declared - trigger. Empty group_id means that the trigger is not grouped. +class DataBinding(_message.Message): + """DataBinding points at immutable data supplied by the Control Plane for the + current surface. Empty pointer selects the complete source document. Scope is + empty except for bindings to a named repetition item. """ DESCRIPTOR: _descriptor.Descriptor - LABEL_FIELD_NUMBER: _builtins.int - SUMMARY_FIELD_NUMBER: _builtins.int - DESCRIPTION_FIELD_NUMBER: _builtins.int - ICON_ASSET_DIGEST_FIELD_NUMBER: _builtins.int - GROUP_ID_FIELD_NUMBER: _builtins.int - PAYLOAD_FIELD_NUMBER: _builtins.int - label: _builtins.str - summary: _builtins.str - description: _builtins.str - icon_asset_digest: _builtins.str - group_id: _builtins.str - @_builtins.property - def payload(self) -> Global___SchemaView: ... + SOURCE_IDENTIFIER_FIELD_NUMBER: _builtins.int + POINTER_FIELD_NUMBER: _builtins.int + SCOPE_FIELD_NUMBER: _builtins.int + source_identifier: _builtins.str + pointer: _builtins.str + scope: _builtins.str def __init__( self, *, - label: _builtins.str = ..., - summary: _builtins.str = ..., - description: _builtins.str = ..., - icon_asset_digest: _builtins.str = ..., - group_id: _builtins.str = ..., - payload: Global___SchemaView | None = ..., + source_identifier: _builtins.str = ..., + pointer: _builtins.str = ..., + scope: _builtins.str = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _typing.Literal["payload", b"payload"] # noqa: Y015 + _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "group_id", b"group_id", "icon_asset_digest", b"icon_asset_digest", "label", b"label", "payload", b"payload", "summary", b"summary"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["pointer", b"pointer", "scope", b"scope", "source_identifier", b"source_identifier"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___TriggerView: _TypeAlias = TriggerView # noqa: Y015 +Global___DataBinding: _TypeAlias = DataBinding # noqa: Y015 @_typing.final -class SchemaView(_message.Message): - """SchemaView adds optional ordering, grouping and compatible render hints to a - JSON Schema. Every pointer addresses a field schema in the corresponding - operation input/result or trigger payload schema. Unmentioned fields remain - visible and retain their schema-defined semantics. +class Condition(_message.Message): + """Condition is optional. EXISTS and NOT_EXISTS omit value; equality operators + require value, including an explicitly supplied JSON null. """ DESCRIPTOR: _descriptor.Descriptor - @_typing.final - class FieldsEntry(_message.Message): - DESCRIPTOR: _descriptor.Descriptor - - KEY_FIELD_NUMBER: _builtins.int - VALUE_FIELD_NUMBER: _builtins.int - key: _builtins.str - @_builtins.property - def value(self) -> Global___FieldView: ... - def __init__( - self, - *, - key: _builtins.str = ..., - value: Global___FieldView | None = ..., - ) -> None: ... - _HasFieldArgType: _TypeAlias = _typing.Literal["value", b"value"] # noqa: Y015 - def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["key", b"key", "value", b"value"] # noqa: Y015 - def ClearField(self, field_name: _ClearFieldArgType) -> None: ... - def WhichOneof(self, oneof_group: _Never) -> None: ... - - FIELD_ORDER_FIELD_NUMBER: _builtins.int - GROUPS_FIELD_NUMBER: _builtins.int - FIELDS_FIELD_NUMBER: _builtins.int + BINDING_FIELD_NUMBER: _builtins.int + OPERATOR_FIELD_NUMBER: _builtins.int + VALUE_FIELD_NUMBER: _builtins.int + operator: Global___ConditionOperator.ValueType @_builtins.property - def field_order(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]: ... + def binding(self) -> Global___DataBinding: ... @_builtins.property - def groups(self) -> _containers.RepeatedCompositeFieldContainer[Global___FieldGroup]: ... - @_builtins.property - def fields(self) -> _containers.MessageMap[_builtins.str, Global___FieldView]: ... + def value(self) -> _struct_pb2.Value: ... def __init__( self, *, - field_order: _abc.Iterable[_builtins.str] | None = ..., - groups: _abc.Iterable[Global___FieldGroup] | None = ..., - fields: _abc.Mapping[_builtins.str, Global___FieldView] | None = ..., + binding: Global___DataBinding | None = ..., + operator: Global___ConditionOperator.ValueType = ..., + value: _struct_pb2.Value | None = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + _HasFieldArgType: _TypeAlias = _typing.Literal["binding", b"binding", "value", b"value"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["field_order", b"field_order", "fields", b"fields", "groups", b"groups"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["binding", b"binding", "operator", b"operator", "value", b"value"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___SchemaView: _TypeAlias = SchemaView # noqa: Y015 +Global___Condition: _TypeAlias = Condition # noqa: Y015 @_typing.final -class FieldGroup(_message.Message): - """FieldGroup visually groups schema fields. Field pointers may appear in at - most one group and group order is declaration order. +class Repetition(_message.Message): + """Repetition renders a node once per item in one bound collection. max_items is + a required positive safety ceiling; item_scope names the item for descendant + bindings. """ DESCRIPTOR: _descriptor.Descriptor - ID_FIELD_NUMBER: _builtins.int - LABEL_FIELD_NUMBER: _builtins.int - DESCRIPTION_FIELD_NUMBER: _builtins.int - FIELDS_FIELD_NUMBER: _builtins.int - id: _builtins.str - label: _builtins.str - description: _builtins.str + COLLECTION_FIELD_NUMBER: _builtins.int + ITEM_SCOPE_FIELD_NUMBER: _builtins.int + MAX_ITEMS_FIELD_NUMBER: _builtins.int + item_scope: _builtins.str + max_items: _builtins.int @_builtins.property - def fields(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]: ... + def collection(self) -> Global___DataBinding: ... def __init__( self, *, - id: _builtins.str = ..., - label: _builtins.str = ..., - description: _builtins.str = ..., - fields: _abc.Iterable[_builtins.str] | None = ..., + collection: Global___DataBinding | None = ..., + item_scope: _builtins.str = ..., + max_items: _builtins.int = ..., ) -> None: ... - _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 + _HasFieldArgType: _TypeAlias = _typing.Literal["collection", b"collection"] # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["description", b"description", "fields", b"fields", "id", b"id", "label", b"label"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["collection", b"collection", "item_scope", b"item_scope", "max_items", b"max_items"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___FieldGroup: _TypeAlias = FieldGroup # noqa: Y015 +Global___Repetition: _TypeAlias = Repetition # noqa: Y015 @_typing.final -class FieldView(_message.Message): - """FieldView supplies optional text and compatible render preferences for one - schema field. It cannot change validation, requiredness or visibility. +class RendererRequirement(_message.Message): + """RendererRequirement identifies a separately distributed renderer extension. + SFP transports metadata only: no executable bytes, URL or install command is + carried by this message. Permissions are versioned identifiers understood by + the Control Plane extension host. """ DESCRIPTOR: _descriptor.Descriptor - LABEL_FIELD_NUMBER: _builtins.int - HELP_TEXT_FIELD_NUMBER: _builtins.int - PLACEHOLDER_FIELD_NUMBER: _builtins.int - UNIT_FIELD_NUMBER: _builtins.int - WIDGET_FIELD_NUMBER: _builtins.int - DISPLAY_FIELD_NUMBER: _builtins.int - label: _builtins.str - help_text: _builtins.str - placeholder: _builtins.str - unit: _builtins.str - widget: Global___InputWidget.ValueType - display: Global___DisplayStyle.ValueType + EXTENSION_IDENTIFIER_FIELD_NUMBER: _builtins.int + EXTENSION_VERSION_FIELD_NUMBER: _builtins.int + RENDERER_API_VERSION_FIELD_NUMBER: _builtins.int + ARTIFACT_DIGEST_FIELD_NUMBER: _builtins.int + PERMISSIONS_FIELD_NUMBER: _builtins.int + extension_identifier: _builtins.str + extension_version: _builtins.str + renderer_api_version: _builtins.str + artifact_digest: _builtins.str + @_builtins.property + def permissions(self) -> _containers.RepeatedScalarFieldContainer[_builtins.str]: ... def __init__( self, *, - label: _builtins.str = ..., - help_text: _builtins.str = ..., - placeholder: _builtins.str = ..., - unit: _builtins.str = ..., - widget: Global___InputWidget.ValueType = ..., - display: Global___DisplayStyle.ValueType = ..., + extension_identifier: _builtins.str = ..., + extension_version: _builtins.str = ..., + renderer_api_version: _builtins.str = ..., + artifact_digest: _builtins.str = ..., + permissions: _abc.Iterable[_builtins.str] | None = ..., ) -> None: ... _HasFieldArgType: _TypeAlias = _Never # noqa: Y015 def HasField(self, field_name: _HasFieldArgType) -> _builtins.bool: ... - _ClearFieldArgType: _TypeAlias = _typing.Literal["display", b"display", "help_text", b"help_text", "label", b"label", "placeholder", b"placeholder", "unit", b"unit", "widget", b"widget"] # noqa: Y015 + _ClearFieldArgType: _TypeAlias = _typing.Literal["artifact_digest", b"artifact_digest", "extension_identifier", b"extension_identifier", "extension_version", b"extension_version", "permissions", b"permissions", "renderer_api_version", b"renderer_api_version"] # noqa: Y015 def ClearField(self, field_name: _ClearFieldArgType) -> None: ... def WhichOneof(self, oneof_group: _Never) -> None: ... -Global___FieldView: _TypeAlias = FieldView # noqa: Y015 +Global___RendererRequirement: _TypeAlias = RendererRequirement # noqa: Y015 @_typing.final class PresentationAsset(_message.Message): diff --git a/tests/fixtures/manifest/presentation-response.json b/tests/fixtures/manifest/presentation-response.json index 4603056..a6449bb 100644 --- a/tests/fixtures/manifest/presentation-response.json +++ b/tests/fixtures/manifest/presentation-response.json @@ -104,91 +104,93 @@ "presentation": { "presentationSchemaVersion": 1, "provider": { - "summary": "Inspect and resolve Git references.", - "description": "A local Provider for Git repository state.", - "iconAssetDigest": "sha256:8c5dec37f2aba701bd79272fc7fe4d34292623e531df7fd23b95cb3c96034741", - "bannerAssetDigest": "", - "groups": [ - { - "id": "repository", - "label": "Repository", - "description": "Repository inspection and reference operations.", - "iconAssetDigest": "" + "surfaces": { + "stateforge.ui/surface.provider.overview@1": { + "root": { + "componentIdentifier": "stateforge.ui/layout.stack@1", + "properties": { + "gap": "large" + }, + "bindings": {}, + "children": [ + { + "componentIdentifier": "stateforge.ui/media.image@1", + "properties": { + "fit": "contain" + }, + "bindings": {}, + "children": [], + "assetBindings": { + "source": "sha256:8c5dec37f2aba701bd79272fc7fe4d34292623e531df7fd23b95cb3c96034741" + } + }, + { + "componentIdentifier": "stateforge.ui/content.text@1", + "properties": { + "title": "Git Provider", + "body": "Inspect and resolve Git references." + }, + "bindings": {}, + "children": [], + "assetBindings": {} + } + ], + "assetBindings": {} + } } - ] + } }, "operations": { "stateforge.git/reference.resolve@1": { - "label": "Resolve reference", - "summary": "Resolve a Git reference to a commit.", - "description": "Reads a repository reference without changing it.", - "iconAssetDigest": "", - "groupId": "repository", - "input": { - "fieldOrder": [ - "/properties/repository", - "/properties/depth", - "/properties/token" - ], - "groups": [ - { - "id": "credentials", - "label": "Credentials", - "description": "Optional credentials for repository access.", - "fields": [ - "/properties/token" - ] + "surfaces": { + "stateforge.ui/surface.operation.request@1": { + "root": { + "componentIdentifier": "stateforge.ui/input.form@1", + "properties": { + "submitLabel": "Resolve reference" + }, + "bindings": { + "schema": { + "sourceIdentifier": "stateforge.binding/operation.request.schema@1", + "pointer": "", + "scope": "" + }, + "value": { + "sourceIdentifier": "stateforge.binding/operation.request.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {} } - ], - "fields": { - "/properties/repository": { - "label": "Repository", - "helpText": "Repository path or canonical name.", - "placeholder": "owner/repository", - "unit": "", - "widget": "INPUT_WIDGET_TEXT", - "display": "DISPLAY_STYLE_UNSPECIFIED" - }, - "/properties/depth": { - "label": "Depth", - "helpText": "Maximum history depth.", - "placeholder": "", - "unit": "commits", - "widget": "INPUT_WIDGET_SLIDER", - "display": "DISPLAY_STYLE_METRIC" - }, - "/properties/token": { - "label": "Access token", - "helpText": "Used only for this request.", - "placeholder": "", - "unit": "", - "widget": "INPUT_WIDGET_SECRET", - "display": "DISPLAY_STYLE_UNSPECIFIED" - } - } - }, - "result": { - "fieldOrder": [ - "/properties/commit", - "/properties/changed" - ], - "groups": [], - "fields": { - "/properties/commit": { - "label": "Commit", - "helpText": "Resolved commit identifier.", - "placeholder": "", - "unit": "", - "widget": "INPUT_WIDGET_UNSPECIFIED", - "display": "DISPLAY_STYLE_CODE" - }, - "/properties/changed": { - "label": "Changed", - "helpText": "Whether the reference changed.", - "placeholder": "", - "unit": "", - "widget": "INPUT_WIDGET_UNSPECIFIED", - "display": "DISPLAY_STYLE_BADGE" + }, + "stateforge.ui/surface.operation.result@1": { + "root": { + "componentIdentifier": "stateforge.git/data.commit_graph@1", + "properties": {}, + "bindings": { + "result": { + "sourceIdentifier": "stateforge.binding/operation.result.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {}, + "fallback": { + "componentIdentifier": "stateforge.ui/data.tree@1", + "properties": {}, + "bindings": { + "value": { + "sourceIdentifier": "stateforge.binding/operation.result.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {} + } } } } @@ -196,33 +198,20 @@ }, "triggers": { "stateforge.git/reference.changed@1": { - "label": "Reference changed", - "summary": "A repository reference moved.", - "description": "Published after a tracked reference changes.", - "iconAssetDigest": "", - "groupId": "repository", - "payload": { - "fieldOrder": [ - "/properties/reference", - "/properties/previous" - ], - "groups": [], - "fields": { - "/properties/reference": { - "label": "Reference", - "helpText": "Current reference value.", - "placeholder": "", - "unit": "", - "widget": "INPUT_WIDGET_UNSPECIFIED", - "display": "DISPLAY_STYLE_CODE" - }, - "/properties/previous": { - "label": "Previous", - "helpText": "Previous reference value.", - "placeholder": "", - "unit": "", - "widget": "INPUT_WIDGET_UNSPECIFIED", - "display": "DISPLAY_STYLE_CODE" + "surfaces": { + "stateforge.ui/surface.trigger.event@1": { + "root": { + "componentIdentifier": "stateforge.ui/data.key_value@1", + "properties": {}, + "bindings": { + "value": { + "sourceIdentifier": "stateforge.binding/trigger.payload.value@1", + "pointer": "", + "scope": "" + } + }, + "children": [], + "assetBindings": {} } } } @@ -236,7 +225,16 @@ "height": 16, "altText": "Git Provider mark" } + }, + "rendererRequirements": { + "stateforge.git": { + "extensionIdentifier": "stateforge.git/renderer@1", + "extensionVersion": "1.0.0", + "rendererApiVersion": "1.0.0", + "artifactDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "permissions": [] + } } }, - "presentationRevision": "sha256:1cbd5452404898672d31afa2f98172f08b4976edb6e7bfb4f576524d70beaf0c" + "presentationRevision": "sha256:d8064d4842d3210e5750618cdccaaa7c71140ba029819add565d9fa06a0e8e55" } diff --git a/tests/test_documentation_system.py b/tests/test_documentation_system.py index 1052857..6a05480 100644 --- a/tests/test_documentation_system.py +++ b/tests/test_documentation_system.py @@ -47,7 +47,7 @@ def test_protocol_uses_the_shared_documentation_presentation() -> None: assert configuration.extra["annotate"]["json"] == [".s2"] -def test_provider_presentation_guide_maps_views_to_surfaces() -> None: +def test_provider_presentation_guide_maps_components_to_surfaces() -> None: page = ( ROOT / "docs/v0.1.0/procedures/provider-presentation.md" ).read_text(encoding="utf-8") @@ -78,26 +78,28 @@ def test_provider_presentation_guide_maps_views_to_surfaces() -> None: }, ] } in procedure_navigation - for view in ( - "`ProviderView`", - "`CapabilityGroup`", - "`OperationView`", - "`TriggerView`", - "`SchemaView`", - "`FieldGroup`", - "`FieldView`", + for contract_type in ( + "`PresentationTarget`", + "`PresentationSurface`", + "`ComponentNode`", + "`DataBinding`", + "`RendererRequirement`", "`PresentationAsset`", ): - assert view in page + assert contract_type in page for surface in ( - "Provider page", - "Policy builder", - "Operation input", - "Results and events", + "surface.provider.overview@1", + "surface.operation.request@1", + "surface.operation.run@1", + "surface.operation.result@1", + "surface.trigger.policy@1", + "surface.trigger.event@1", + "surface.evidence@1", ): assert surface in page - assert "schema-derived interface" in page + assert "schema-derived interface" in page.lower() assert "active Control Plane skin" in page + assert "No second SFP presentation RPC" in page assert "SF-AOP" in page diff --git a/tests/test_manifest_contract.py b/tests/test_manifest_contract.py index d3f46f8..af1341c 100644 --- a/tests/test_manifest_contract.py +++ b/tests/test_manifest_contract.py @@ -76,7 +76,15 @@ def test_versioned_contract_exposes_normative_limits() -> None: "MAX_PLATFORMS": 256, "MAX_PROFILE_CLAIMS_PER_OPERATION": 64, "PRESENTATION_SCHEMA_VERSION": 1, - "MAX_CAPABILITY_GROUPS": 64, + "MAX_PRESENTATION_SURFACES_PER_TARGET": 8, + "MAX_PRESENTATION_COMPONENTS": 4_096, + "MAX_PRESENTATION_COMPONENT_DEPTH": 16, + "MAX_COMPONENT_CHILDREN": 256, + "MAX_COMPONENT_BINDINGS": 64, + "MAX_COMPONENT_ASSET_BINDINGS": 32, + "MAX_RENDERER_REQUIREMENTS": 64, + "MAX_RENDERER_PERMISSIONS": 32, + "MAX_REPETITION_ITEMS": 1_024, "MAX_PRESENTATION_ASSETS": 64, "MAX_PRESENTATION_ASSET_BYTES": 256 * 1024, "MAX_PRESENTATION_ASSET_TOTAL_BYTES": 1 * 1024 * 1024, @@ -129,8 +137,30 @@ def test_versioned_contract_limits_match_packaged_schema() -> None: == contract.MAX_PRESENTATION_ASSETS ) assert ( - definitions["providerView"]["properties"]["groups"]["maxItems"] - == contract.MAX_CAPABILITY_GROUPS + definitions["presentationTarget"]["properties"]["surfaces"][ + "maxProperties" + ] + == contract.MAX_PRESENTATION_SURFACES_PER_TARGET + ) + component = definitions["componentNode"]["properties"] + assert component["children"]["maxItems"] == contract.MAX_COMPONENT_CHILDREN + assert ( + component["bindings"]["maxProperties"] + == contract.MAX_COMPONENT_BINDINGS + ) + assert ( + component["assetBindings"]["maxProperties"] + == contract.MAX_COMPONENT_ASSET_BINDINGS + ) + assert ( + presentation["rendererRequirements"]["maxProperties"] + == contract.MAX_RENDERER_REQUIREMENTS + ) + assert ( + definitions["rendererRequirement"]["properties"]["permissions"][ + "maxItems" + ] + == contract.MAX_RENDERER_PERMISSIONS ) assert ( set( @@ -290,23 +320,34 @@ def test_presentation_is_outside_the_operational_manifest() -> None: def test_presentation_contract_cannot_hide_or_redefine_fields() -> None: - field_view = manifest_pb2.FieldView.DESCRIPTOR.fields_by_name - schema_view = manifest_pb2.SchemaView.DESCRIPTOR.fields_by_name + component = manifest_pb2.ComponentNode.DESCRIPTOR.fields_by_name + renderer = manifest_pb2.RendererRequirement.DESCRIPTOR.fields_by_name forbidden = { "hidden", "required", "schema", "default", - "value", "html", "css", "javascript", "url", "path", + "executable", + "install_command", } - assert not forbidden & set(field_view) - assert not forbidden & set(schema_view) + assert set(component) == { + "component_identifier", + "properties", + "bindings", + "children", + "fallback", + "condition", + "repeat", + "asset_bindings", + } + assert not forbidden & set(component) + assert not forbidden & set(renderer) def test_presentation_is_not_part_of_operation_or_trigger_messages() -> None: @@ -354,7 +395,9 @@ def test_presentation_changes_do_not_change_business_fingerprints() -> None: json.loads((_FIXTURES / "presentation-response.json").read_text()), manifest_pb2.GetManifestResponse(), ) - manifest_response.presentation.provider.summary = "Changed presentation" + manifest_response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root.properties.update({"gap": "changed"}) assert ( admission_validation.compute_request_fingerprint(operation) @@ -369,11 +412,10 @@ def test_presentation_changes_do_not_change_business_fingerprints() -> None: @pytest.mark.parametrize( ("target", "field", "value"), [ - ("field", "hidden", True), - ("field", "required", False), - ("field", "schema", {"type": "string"}), - ("field", "html", "unsafe"), - ("field", "javascript", "alert(1)"), + ("component", "hidden", True), + ("component", "javascript", "alert(1)"), + ("renderer", "url", "https://example.invalid/renderer"), + ("renderer", "executable", "payload"), ("asset", "url", "https://example.invalid/icon.svg"), ("asset", "path", "../../etc/passwd"), ], @@ -386,9 +428,13 @@ def test_presentation_protojson_rejects_executable_or_semantic_fields( document = json.loads( (_FIXTURES / "presentation-response.json").read_text() )["presentation"] - if target == "field": - view = next(iter(document["operations"].values())) - selected = next(iter(view["input"]["fields"].values())) + if target == "component": + operation = next(iter(document["operations"].values())) + selected = operation["surfaces"][contract.OPERATION_RESULT_SURFACE][ + "root" + ] + elif target == "renderer": + selected = next(iter(document["rendererRequirements"].values())) else: selected = next(iter(document["assets"].values())) selected[field] = value diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index af0958e..7a8163c 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -116,7 +116,8 @@ def _replace_provider_icon( width: int, height: int, ) -> str: - old_digest = response.presentation.provider.icon_asset_digest + image = _provider_image(response) + old_digest = image.asset_bindings["source"] del response.presentation.assets[old_digest] digest = "sha256:" + hashlib.sha256(content).hexdigest() response.presentation.assets[digest].CopyFrom( @@ -128,10 +129,29 @@ def _replace_provider_icon( alt_text="Provider icon", ) ) - response.presentation.provider.icon_asset_digest = digest + image.asset_bindings["source"] = digest return digest +def _provider_image( + response: manifest_pb2.GetManifestResponse, +) -> manifest_pb2.ComponentNode: + return response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root.children[0] + + +def _operation_root( + response: manifest_pb2.GetManifestResponse, + surface: str, +) -> manifest_pb2.ComponentNode: + return ( + response.presentation.operations["stateforge.git/reference.resolve@1"] + .surfaces[surface] + .root + ) + + def _schema(**overrides): return { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -196,6 +216,7 @@ def test_empty_presentation_overlay_is_valid() -> None: response.presentation.ClearField("operations") response.presentation.ClearField("triggers") response.presentation.ClearField("assets") + response.presentation.ClearField("renderer_requirements") _refresh_presentation_revision(response) exchange = validate_manifest_exchange(response) @@ -207,16 +228,16 @@ def test_empty_presentation_overlay_is_valid() -> None: "assets": {}, "operations": {}, "presentationSchemaVersion": 1, + "rendererRequirements": {}, "triggers": {}, } def test_invalid_presentation_falls_back_without_rejecting_manifest() -> None: response = _presentation_response() - operation = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ] - operation.input.field_order[0] = "/properties/not-declared" + _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + "schema" + ].source_identifier = contract.PROVIDER_RUNTIME_BINDING _refresh_presentation_revision(response) exchange = validate_manifest_exchange(response) @@ -283,7 +304,9 @@ def test_presentation_revision_is_isolated_and_bound_to_manifest() -> None: original_manifest_revision = response.manifest_revision original_presentation_revision = response.presentation_revision - response.presentation.provider.summary = "A different summary." + response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root.properties.update({"gap": "compact"}) _refresh_presentation_revision(response) assert response.manifest_revision == original_manifest_revision @@ -379,319 +402,219 @@ def test_public_presentation_validator_projects_its_own_message() -> None: ) -def test_capability_groups_are_optional() -> None: - response = _presentation_response() - response.presentation.provider.ClearField("groups") - for view in response.presentation.operations.values(): - view.group_id = "" - for view in response.presentation.triggers.values(): - view.group_id = "" - _refresh_presentation_revision(response) - - exchange = validate_manifest_exchange(response) - - assert ( - exchange.presentation_status is PresentationValidationStatus.ACCEPTED - ) - - @pytest.mark.parametrize("collection", ["operations", "triggers"]) -def test_views_cannot_name_undeclared_capabilities(collection: str) -> None: +def test_targets_cannot_name_undeclared_capabilities(collection: str) -> None: response = _presentation_response() - views = getattr(response.presentation, collection) - declared_identifier = next(iter(views)) - views["example.invalid/not_declared@1"].CopyFrom( - views[declared_identifier] + targets = getattr(response.presentation, collection) + declared_identifier = next(iter(targets)) + targets["example.invalid/not_declared@1"].CopyFrom( + targets[declared_identifier] ) with pytest.raises( ManifestValidationError, - match=f"{collection[:-1]} view does not name a declared", + match=f"{collection[:-1]} target does not name a declared", ): _validate_presentation(response) -def test_view_group_reference_must_resolve() -> None: +def test_surface_must_belong_to_its_target_kind() -> None: response = _presentation_response() - response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].group_id = "missing" + target = response.presentation.provider + target.surfaces[contract.OPERATION_REQUEST_SURFACE].CopyFrom( + target.surfaces[contract.PROVIDER_OVERVIEW_SURFACE] + ) - with pytest.raises(ManifestValidationError, match="group reference"): + with pytest.raises(ManifestValidationError, match="provider targets"): _validate_presentation(response) -def test_capability_group_ids_must_be_unique() -> None: +def test_surface_binding_source_must_be_available() -> None: response = _presentation_response() - duplicate = response.presentation.provider.groups.add() - duplicate.CopyFrom(response.presentation.provider.groups[0]) + _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + "schema" + ].source_identifier = contract.OPERATION_RESULT_VALUE_BINDING - with pytest.raises(ManifestValidationError, match="group IDs"): + with pytest.raises(ManifestValidationError, match="unavailable"): _validate_presentation(response) -def test_schema_view_pointer_must_resolve_in_its_own_schema() -> None: +def test_core_component_catalog_is_explicit() -> None: response = _presentation_response() - operation = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ] - operation.input.field_order[0] = "/properties/commit" + response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root.component_identifier = "stateforge.ui/layout.unknown@1" - with pytest.raises(ManifestValidationError, match="does not resolve"): + with pytest.raises(ManifestValidationError, match="unknown core"): _validate_presentation(response) -def test_schema_view_pointer_must_name_a_field() -> None: +def test_custom_component_requires_renderer_metadata() -> None: response = _presentation_response() - operation = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ] - operation.input.field_order[0] = "/properties" + del response.presentation.renderer_requirements["stateforge.git"] - with pytest.raises(ManifestValidationError, match="schema field"): + with pytest.raises(ManifestValidationError, match="renderer requirement"): _validate_presentation(response) -def test_field_may_belong_to_only_one_visual_group() -> None: +def test_custom_component_requires_core_fallback() -> None: response = _presentation_response() - groups = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].input.groups - duplicate = groups.add( - id="more-credentials", - label="More credentials", - description="Duplicate placement.", + _operation_root(response, contract.OPERATION_RESULT_SURFACE).ClearField( + "fallback" ) - duplicate.fields.append("/properties/token") - with pytest.raises(ManifestValidationError, match="at most one"): + with pytest.raises(ManifestValidationError, match="core fallback"): _validate_presentation(response) -def test_field_group_ids_must_be_unique() -> None: +def test_custom_component_fallback_cannot_require_an_extension() -> None: response = _presentation_response() - groups = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].input.groups - duplicate = groups.add( - id="credentials", - label="More credentials", - description="Duplicate identifier.", - ) - duplicate.fields.append("/properties/repository") + _operation_root( + response, contract.OPERATION_RESULT_SURFACE + ).fallback.component_identifier = "stateforge.git/data.commit_graph@1" - with pytest.raises(ManifestValidationError, match="group IDs"): + with pytest.raises(ManifestValidationError, match="core components"): _validate_presentation(response) -def test_schema_view_follows_a_local_field_reference() -> None: +def test_renderer_requirements_cannot_be_unreferenced() -> None: response = _presentation_response() - schema = response.manifest.operations[ - "stateforge.git/reference.resolve@1" - ].input_schema - schema.update( - { - "$defs": {"repository": {"type": "string"}}, - "properties": { - "repository": {"$ref": "#/$defs/repository"}, - "depth": { - "type": "integer", - "minimum": 1, - "maximum": 10, - }, - "token": {"type": "string", "writeOnly": True}, - }, - } + response.presentation.renderer_requirements["example.widget"].CopyFrom( + response.presentation.renderer_requirements["stateforge.git"] ) + requirement = response.presentation.renderer_requirements["example.widget"] + requirement.extension_identifier = "example.widget/renderer@1" - _validate_presentation(response) + with pytest.raises(ManifestValidationError, match="exactly match"): + _validate_presentation(response) -@pytest.mark.parametrize( - ("reference", "message"), - [ - ("https://example.invalid/schema", "reference is invalid"), - ("#/properties/repository", "cyclic field schema reference"), - ("#/$defs/not-a-schema", "must name a schema"), - ], -) -def test_schema_view_rejects_invalid_field_references( - reference: str, - message: str, -) -> None: +def test_renderer_extension_must_share_component_namespace() -> None: response = _presentation_response() - schema = response.manifest.operations[ - "stateforge.git/reference.resolve@1" - ].input_schema - schema.update( - { - "$defs": {"not-a-schema": "value"}, - "properties": { - "repository": {"$ref": reference}, - "depth": { - "type": "integer", - "minimum": 1, - "maximum": 10, - }, - "token": {"type": "string", "writeOnly": True}, - }, - } - ) + response.presentation.renderer_requirements[ + "stateforge.git" + ].extension_identifier = "example.widget/renderer@1" - with pytest.raises(ManifestValidationError, match=message): + with pytest.raises(ManifestValidationError, match="namespace"): _validate_presentation(response) -def test_schema_view_resolves_fields_nested_in_schema_arrays() -> None: +def test_repetition_scope_is_available_to_component_bindings() -> None: response = _presentation_response() - schema = response.manifest.operations[ - "stateforge.git/reference.resolve@1" - ].input_schema - schema.Clear() - schema.update( - { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "type": "object", - "allOf": [{"properties": {"repository": {"type": "string"}}}], - } + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + repeated = root.children.add( + component_identifier="stateforge.ui/data.table@1" + ) + repeated.properties.update({"title": "Runtime items"}) + repeated.repeat.collection.CopyFrom( + manifest_pb2.DataBinding( + source_identifier=contract.PROVIDER_RUNTIME_BINDING, + pointer="/items", + ) + ) + repeated.repeat.item_scope = "row" + repeated.repeat.max_items = 100 + repeated.bindings["item"].CopyFrom( + manifest_pb2.DataBinding( + source_identifier=contract.REPETITION_ITEM_BINDING, + pointer="/name", + scope="row", + ) ) - view = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].input - field = manifest_pb2.FieldView() - field.CopyFrom(view.fields["/properties/repository"]) - view.ClearField("field_order") - view.field_order.append("/allOf/0/properties/repository") - view.ClearField("groups") - view.ClearField("fields") - view.fields["/allOf/0/properties/repository"].CopyFrom(field) _validate_presentation(response) -@pytest.mark.parametrize( - ("field", "widget", "message"), - [ - ("repository", manifest_pb2.INPUT_WIDGET_NUMBER, "schema type"), - ("repository", manifest_pb2.INPUT_WIDGET_SECRET, "write-only"), - ("repository", manifest_pb2.INPUT_WIDGET_SELECT, "schema enum"), - ("depth", manifest_pb2.INPUT_WIDGET_DATE_TIME, "schema type"), - ], -) -def test_input_widgets_must_match_authoritative_schema( - field: str, - widget: int, - message: str, -) -> None: +def test_repetition_item_binding_requires_an_active_scope() -> None: response = _presentation_response() - view = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].input.fields[f"/properties/{field}"] - view.widget = widget + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + root.bindings["item"].CopyFrom( + manifest_pb2.DataBinding( + source_identifier=contract.REPETITION_ITEM_BINDING, + scope="missing", + ) + ) - with pytest.raises(ManifestValidationError, match=message): + with pytest.raises(ManifestValidationError, match="active scope"): _validate_presentation(response) -def test_slider_requires_authoritative_bounds() -> None: +def test_non_repetition_binding_cannot_claim_a_scope() -> None: response = _presentation_response() - depth = ( - response.manifest.operations["stateforge.git/reference.resolve@1"] - .input_schema.fields["properties"] - .struct_value.fields["depth"] - .struct_value - ) - del depth.fields["minimum"] + _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + "schema" + ].scope = "row" - with pytest.raises(ManifestValidationError, match="minimum and maximum"): + with pytest.raises(ManifestValidationError, match="may name a scope"): _validate_presentation(response) @pytest.mark.parametrize( - ("schema", "widget", "display"), + ("operator", "with_value", "message"), [ - ({"type": "boolean"}, manifest_pb2.INPUT_WIDGET_CHECKBOX, 0), - ( - {"type": "string", "enum": ["main", "develop"]}, - manifest_pb2.INPUT_WIDGET_SELECT, - 0, - ), ( - {"type": "string", "enum": ["main", "develop"]}, - manifest_pb2.INPUT_WIDGET_RADIO, - 0, + manifest_pb2.CONDITION_OPERATOR_EXISTS, + True, + "cannot declare a value", ), ( - {"type": "string", "format": "date-time"}, - manifest_pb2.INPUT_WIDGET_DATE_TIME, - manifest_pb2.DISPLAY_STYLE_DATE_TIME, - ), - ( - {"type": ["object", "null"]}, - manifest_pb2.INPUT_WIDGET_JSON, - manifest_pb2.DISPLAY_STYLE_JSON, + manifest_pb2.CONDITION_OPERATOR_EQUALS, + False, + "requires a value", ), ], ) -def test_supported_field_preferences_follow_the_schema( - schema: dict[str, object], - widget: int, - display: int, +def test_condition_value_presence_matches_operator( + operator: int, + with_value: bool, + message: str, ) -> None: response = _presentation_response() - field_schema = ( - response.manifest.operations["stateforge.git/reference.resolve@1"] - .input_schema.fields["properties"] - .struct_value.fields["repository"] - .struct_value + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + root.condition.binding.CopyFrom( + manifest_pb2.DataBinding( + source_identifier=contract.PROVIDER_RUNTIME_BINDING, + pointer="/available", + ) ) - field_schema.Clear() - field_schema.update(schema) - field_view = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].input.fields["/properties/repository"] - field_view.widget = widget - field_view.display = display + root.condition.operator = operator + if with_value: + root.condition.value.bool_value = True - _validate_presentation(response) + with pytest.raises(ManifestValidationError, match=message): + _validate_presentation(response) -@pytest.mark.parametrize("preference", ["widget", "placeholder"]) -def test_output_fields_cannot_declare_input_preferences( - preference: str, -) -> None: +def test_component_properties_have_an_independent_byte_limit() -> None: response = _presentation_response() - view = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].result.fields["/properties/commit"] - if preference == "widget": - view.widget = manifest_pb2.INPUT_WIDGET_TEXT - else: - view.placeholder = "not permitted" - - with pytest.raises(ManifestValidationError, match="output fields"): + response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root.properties.update( + {"content": "x" * contract.MAX_COMPONENT_PROPERTIES_BYTES} + ) + + with pytest.raises(ManifestValidationError, match="properties limit"): _validate_presentation(response) -@pytest.mark.parametrize( - ("field", "display"), - [ - ("commit", manifest_pb2.DISPLAY_STYLE_METRIC), - ("changed", manifest_pb2.DISPLAY_STYLE_CODE), - ("changed", manifest_pb2.DISPLAY_STYLE_TABLE), - ], -) -def test_display_preferences_must_match_authoritative_schema( - field: str, - display: int, -) -> None: +def test_component_tree_depth_is_bounded() -> None: response = _presentation_response() - view = response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].result.fields[f"/properties/{field}"] - view.display = display + node = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + for depth in range(contract.MAX_PRESENTATION_COMPONENT_DEPTH): + node = node.children.add( + component_identifier="stateforge.ui/layout.section@1" + ) + node.properties.update({"depth": depth}) - with pytest.raises(ManifestValidationError, match="schema type"): + with pytest.raises(ManifestValidationError, match="depth limit"): _validate_presentation(response) @@ -716,7 +639,7 @@ def test_bounded_static_png_asset_is_accepted() -> None: def test_asset_reference_must_resolve() -> None: response = _presentation_response() del response.presentation.assets[ - response.presentation.provider.icon_asset_digest + _provider_image(response).asset_bindings["source"] ] with pytest.raises(ManifestValidationError, match="reference is missing"): @@ -725,7 +648,7 @@ def test_asset_reference_must_resolve() -> None: def test_unreferenced_assets_are_rejected() -> None: response = _presentation_response() - response.presentation.provider.icon_asset_digest = "" + _provider_image(response).ClearField("asset_bindings") with pytest.raises(ManifestValidationError, match="unreferenced asset"): _validate_presentation(response) @@ -733,7 +656,7 @@ def test_unreferenced_assets_are_rejected() -> None: def test_asset_digest_must_match_exact_bytes() -> None: response = _presentation_response() - digest = response.presentation.provider.icon_asset_digest + digest = _provider_image(response).asset_bindings["source"] response.presentation.assets[digest].content += b"changed" with pytest.raises(ManifestValidationError, match="digest mismatch"): @@ -773,15 +696,16 @@ def test_aggregate_asset_size_limit_is_enforced() -> None: ) ) references.append(digest) - response.presentation.provider.icon_asset_digest = references[0] - response.presentation.provider.banner_asset_digest = references[1] - response.presentation.provider.groups[0].icon_asset_digest = references[2] - response.presentation.operations[ - "stateforge.git/reference.resolve@1" - ].icon_asset_digest = references[3] - response.presentation.triggers[ - "stateforge.git/reference.changed@1" - ].icon_asset_digest = references[4] + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + root.ClearField("children") + for index, digest in enumerate(references): + image = root.children.add( + component_identifier="stateforge.ui/media.image@1" + ) + image.properties.update({"index": index}) + image.asset_bindings["source"] = digest with pytest.raises(ManifestValidationError, match="aggregate asset"): _validate_presentation(response) @@ -899,7 +823,7 @@ def test_svg_executable_or_external_content_is_rejected_without_echo( def test_media_allowlist_is_enforced() -> None: response = _presentation_response() - digest = response.presentation.provider.icon_asset_digest + digest = _provider_image(response).asset_bindings["source"] response.presentation.assets[digest].media_type = "text/html" with pytest.raises(ManifestValidationError, match="enum constraint"): From 546aed35324b013d8f11dfe503bf2ff598446412 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 17:05:02 +0200 Subject: [PATCH 4/8] fix(manifest): keep secret request values out of views --- .../procedures/provider-presentation.md | 23 +++++++++----- .../sfp/manifest/v1/contract.py | 13 ++++---- .../manifest/presentation-response.json | 4 +-- tests/test_documentation_system.py | 2 ++ tests/test_manifest_validation.py | 30 +++++++++++++++++++ 5 files changed, 58 insertions(+), 14 deletions(-) diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index 562a97c..a2e63a1 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -125,9 +125,9 @@ Examples include: | Surface | Representative binding sources | | --- | --- | | Provider overview | Provider manifest and Provider runtime state | -| Operation request | Request schema and current request value | -| Operation run | Admitted request and live operation state | -| Operation result | Request, result schema, result value, and operation evidence | +| Operation request | Request schema and the public request draft | +| Operation run | Public admitted-request projection and live operation state | +| Operation result | Public request projection, result schema, result value, and operation evidence | | Trigger policy | Trigger payload schema | | Trigger event | Payload schema and published payload value | | Evidence | Operation evidence or trigger value plus audit data | @@ -140,6 +140,14 @@ Conditions support `EXISTS`, `NOT_EXISTS`, `EQUALS`, and `NOT_EQUALS`. Existence conditions omit a comparison value; equality conditions require one, including an explicitly supplied JSON `null`. +The request-value source is +`stateforge.binding/operation.request.public_value@1`. It is a safe projection, +not the submitted request: every value whose applicable input schema marks it +`writeOnly` is omitted. If an implementation cannot prove that a value is +public, it must omit that value. Secret-entry state remains private to the form +renderer and is never addressable by a presentation binding. The raw request +has no presentation binding identifier. + ## Core example The manifest fixture uses a core form for the operation request: @@ -157,7 +165,7 @@ The manifest fixture uses a core form for the operation request: "scope": "" }, "value": { - "sourceIdentifier": "stateforge.binding/operation.request.value@1", + "sourceIdentifier": "stateforge.binding/operation.request.public_value@1", "pointer": "", "scope": "" } @@ -168,9 +176,10 @@ The manifest fixture uses a core form for the operation request: ``` The operation input JSON Schema remains authoritative. The renderer can produce -an appropriate form because the schema and current value arrive through -bindings; the presentation cannot relax validation, disclose a `writeOnly` -value, or manufacture an operation field. +an appropriate form because the schema and public draft arrive through +bindings. Secret fields keep their values in private form state, so the +presentation cannot bind or display them. Presentation also cannot relax +validation or manufacture an operation field. ## Custom components and renderer extensions diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index 69e765a..ec7269e 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -88,8 +88,11 @@ OPERATION_REQUEST_SCHEMA_BINDING: Final = ( "stateforge.binding/operation.request.schema@1" ) -OPERATION_REQUEST_VALUE_BINDING: Final = ( - "stateforge.binding/operation.request.value@1" +# Presentation-safe projection only. The data-source owner must recursively +# omit every value whose applicable input schema marks it writeOnly. Secret +# form state is never exposed through a presentation binding. +OPERATION_REQUEST_PUBLIC_VALUE_BINDING: Final = ( + "stateforge.binding/operation.request.public_value@1" ) OPERATION_RUN_BINDING: Final = "stateforge.binding/operation.run@1" OPERATION_RESULT_SCHEMA_BINDING: Final = ( @@ -116,20 +119,20 @@ { PROVIDER_MANIFEST_BINDING, OPERATION_REQUEST_SCHEMA_BINDING, - OPERATION_REQUEST_VALUE_BINDING, + OPERATION_REQUEST_PUBLIC_VALUE_BINDING, } ), OPERATION_RUN_SURFACE: frozenset( { PROVIDER_MANIFEST_BINDING, - OPERATION_REQUEST_VALUE_BINDING, + OPERATION_REQUEST_PUBLIC_VALUE_BINDING, OPERATION_RUN_BINDING, } ), OPERATION_RESULT_SURFACE: frozenset( { PROVIDER_MANIFEST_BINDING, - OPERATION_REQUEST_VALUE_BINDING, + OPERATION_REQUEST_PUBLIC_VALUE_BINDING, OPERATION_RESULT_SCHEMA_BINDING, OPERATION_RESULT_VALUE_BINDING, OPERATION_EVIDENCE_BINDING, diff --git a/tests/fixtures/manifest/presentation-response.json b/tests/fixtures/manifest/presentation-response.json index a6449bb..9303a52 100644 --- a/tests/fixtures/manifest/presentation-response.json +++ b/tests/fixtures/manifest/presentation-response.json @@ -156,7 +156,7 @@ "scope": "" }, "value": { - "sourceIdentifier": "stateforge.binding/operation.request.value@1", + "sourceIdentifier": "stateforge.binding/operation.request.public_value@1", "pointer": "", "scope": "" } @@ -236,5 +236,5 @@ } } }, - "presentationRevision": "sha256:d8064d4842d3210e5750618cdccaaa7c71140ba029819add565d9fa06a0e8e55" + "presentationRevision": "sha256:2eabed9abfbb8736d5cbe1f9bb788ff5283e18bdc1d7bb58b455719a6feeed3e" } diff --git a/tests/test_documentation_system.py b/tests/test_documentation_system.py index 6a05480..2416302 100644 --- a/tests/test_documentation_system.py +++ b/tests/test_documentation_system.py @@ -99,6 +99,8 @@ def test_provider_presentation_guide_maps_components_to_surfaces() -> None: assert surface in page assert "schema-derived interface" in page.lower() assert "active Control Plane skin" in page + assert "operation.request.public_value@1" in page + assert "has no presentation binding identifier" in page assert "No second SFP presentation RPC" in page assert "SF-AOP" in page diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index 7a8163c..8cfcf7e 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -439,6 +439,36 @@ def test_surface_binding_source_must_be_available() -> None: _validate_presentation(response) +def test_raw_operation_request_values_are_not_presentation_sources() -> None: + response = _presentation_response() + result = _operation_root( + response, contract.OPERATION_RESULT_SURFACE + ).fallback + result.bindings[ + "secret" + ].source_identifier = "stateforge.binding/operation.request.value@1" + result.bindings["secret"].pointer = "/token" + + with pytest.raises(ManifestValidationError, match="unavailable"): + _validate_presentation(response) + + +def test_public_request_projection_is_available_across_lifecycle() -> None: + expected = contract.OPERATION_REQUEST_PUBLIC_VALUE_BINDING + + for surface in ( + contract.OPERATION_REQUEST_SURFACE, + contract.OPERATION_RUN_SURFACE, + contract.OPERATION_RESULT_SURFACE, + ): + assert expected in contract.SURFACE_BINDING_SOURCES[surface] + + assert all( + "stateforge.binding/operation.request.value@1" not in sources + for sources in contract.SURFACE_BINDING_SOURCES.values() + ) + + def test_core_component_catalog_is_explicit() -> None: response = _presentation_response() response.presentation.provider.surfaces[ From 7c6031aab24f904a94ed476953a99e60d499e93f Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 17:13:58 +0200 Subject: [PATCH 5/8] fix(manifest): enforce core component contracts --- .../procedures/provider-presentation.md | 29 ++- .../sfp/manifest/v1/_presentation.py | 88 ++++++++- .../sfp/manifest/v1/contract.py | 178 ++++++++++++++---- tests/test_documentation_system.py | 2 + tests/test_manifest_validation.py | 117 +++++++++++- 5 files changed, 374 insertions(+), 40 deletions(-) diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index a2e63a1..72a5754 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -101,7 +101,7 @@ render: | Category | Component identifiers | | --- | --- | | Layout | `layout.stack`, `layout.grid`, `layout.section`, `layout.tabs`, `layout.steps` | -| Input | `input.form`, `input.field`, `input.object`, `input.array`, `input.key_value`, `input.code` | +| Input | `input.form`, `input.field`, `input.object`, `input.array`, `input.key_value`, `input.code`, `input.secret` | | Content and structured data | `content.text`, `content.markdown`, `data.key_value`, `data.table`, `data.tree`, `data.code`, `data.diff`, `data.log` | | Status and visualization | `status.badge`, `status.progress`, `status.timeline`, `data.metric`, `data.chart`, `data.topology`, `data.artifacts` | | Media and actions | `media.image`, `action.operation_submit`, `action.operation_cancel` | @@ -113,6 +113,33 @@ For example, the complete table identifier is These are identifiers, not protobuf message types. Adding a renderer does not require adding a new component-specific message or enum to SFP. +### Portable core structure + +Core identifiers also carry a small Protocol-owned structural contract. This +does not define styling or renderer properties; it guarantees that an accepted +core tree—including a custom component's fallback—can be interpreted the same +way by every conforming Control Plane. + +| Core family | Surfaces | Children | Binding and asset slots | +| --- | --- | --- | --- | +| Layout | All | One or more | No bindings or assets | +| Form, object, array | Operation request or trigger policy | Optional nested controls | Required `schema`; optional public `value` | +| Field, key/value, code input | Operation request or trigger policy | None | Required `schema`; optional public `value` | +| Secret input | Operation request or trigger policy | None | Required `schema`; secret value remains private host state | +| Text and Markdown | All | None | Optional `value` | +| Key/value, tree, code, badge, progress, and metric | All | None | Required `value` | +| Table, log, timeline, chart, and artifacts | All | None | Required `rows`, `entries`, `events`, `series`, or `items` respectively | +| Diff | All | None | Required `before` and `after` | +| Topology | All | None | Required `nodes` and `edges` | +| Image | All | None | Required `source` asset | +| Submit action | Operation request | None | Host-controlled action; no binding or asset | +| Cancel action | Operation run | None | Host-controlled action; no binding or asset | + +A core component cannot declare a fallback. Custom components must declare a +core-only fallback, and every node in that fallback is checked against this +same structural registry. Renderer-specific `properties` remain owned by the +Control Plane registry. + ## Data bindings A `DataBinding` selects one Control Plane-provided source and optionally a diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py index d695028..f1c0c51 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -223,14 +223,13 @@ def _validate_component( if state.component_count > contract.MAX_PRESENTATION_COMPONENTS: raise error_type("presentation: component count limit exceeded") - _validate_component_identity( + core_contract = _validate_component_identity( node, core_only=core_only, state=state, requirements=requirements, error_type=error_type, ) - properties = cast(dict[str, Any], node["properties"]) if ( len(rfc8785.dumps(properties)) @@ -264,6 +263,13 @@ def _validate_component( state.asset_references.update( cast(dict[str, str], node["assetBindings"]).values() ) + if core_contract is not None: + _validate_core_component_contract( + node, + surface_identifier=surface_identifier, + component_contract=core_contract, + error_type=error_type, + ) _validate_optional_fallback( node, @@ -296,12 +302,22 @@ def _validate_component_identity( state: _PresentationState, requirements: dict[str, dict[str, Any]], error_type: type[ValueError], -) -> None: +) -> contract.CoreComponentContract | None: identifier = cast(str, node["componentIdentifier"]) namespace = _namespace(identifier) is_core = namespace == contract.CORE_COMPONENT_NAMESPACE - if is_core and identifier not in contract.CORE_COMPONENT_IDENTIFIERS: - raise error_type("presentation: unknown core component identifier") + if is_core: + try: + component_contract = contract.CORE_COMPONENT_CONTRACTS[identifier] + except KeyError: + raise error_type( + "presentation: unknown core component identifier" + ) from None + if "fallback" in node: + raise error_type( + "presentation: core component cannot declare a fallback" + ) + return component_contract if core_only and not is_core: raise error_type( "presentation: custom component fallback must use core components" @@ -316,6 +332,68 @@ def _validate_component_identity( "presentation: custom component requires a core fallback" ) state.custom_namespaces.add(namespace) + return None + + +def _validate_core_component_contract( + node: dict[str, Any], + *, + surface_identifier: str, + component_contract: contract.CoreComponentContract, + error_type: type[ValueError], +) -> None: + if surface_identifier not in component_contract.permitted_surfaces: + raise error_type( + "presentation: core component is unavailable on this surface" + ) + + child_count = len(cast(list[dict[str, Any]], node["children"])) + if not ( + component_contract.minimum_children + <= child_count + <= component_contract.maximum_children + ): + raise error_type( + "presentation: core component child contract is violated" + ) + + bindings = cast(dict[str, dict[str, Any]], node["bindings"]) + binding_names = set(bindings) + permitted_bindings = ( + component_contract.required_bindings + | component_contract.optional_bindings + ) + if not component_contract.required_bindings <= binding_names: + raise error_type( + "presentation: core component is missing a required binding" + ) + if not binding_names <= permitted_bindings: + raise error_type( + "presentation: core component binding slot is not permitted" + ) + for slot, permitted_sources in component_contract.binding_source_rules: + binding = bindings.get(slot) + if binding is not None and binding["sourceIdentifier"] not in ( + permitted_sources + ): + raise error_type( + "presentation: binding source is invalid for core " + "component slot" + ) + + asset_bindings = cast(dict[str, str], node["assetBindings"]) + asset_names = set(asset_bindings) + permitted_assets = ( + component_contract.required_assets | component_contract.optional_assets + ) + if not component_contract.required_assets <= asset_names: + raise error_type( + "presentation: core component is missing a required asset" + ) + if not asset_names <= permitted_assets: + raise error_type( + "presentation: core component asset slot is not permitted" + ) def _extend_repetition_scopes( diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index ec7269e..1cb3d9b 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -1,5 +1,6 @@ """Expose the normative SFP Provider Manifest v1 wire contract.""" +from dataclasses import dataclass from typing import Final from stateforge_protocol.sfp import primitives @@ -82,6 +83,12 @@ EVIDENCE_SURFACE, } ) +ALL_PRESENTATION_SURFACES: Final = ( + PROVIDER_SURFACES | OPERATION_SURFACES | TRIGGER_SURFACES +) +INPUT_PRESENTATION_SURFACES: Final = frozenset( + {OPERATION_REQUEST_SURFACE, TRIGGER_POLICY_SURFACE} +) PROVIDER_MANIFEST_BINDING: Final = "stateforge.binding/provider.manifest@1" PROVIDER_RUNTIME_BINDING: Final = "stateforge.binding/provider.runtime@1" @@ -158,39 +165,146 @@ ), } -CORE_COMPONENT_IDENTIFIERS: Final = frozenset( - { - "stateforge.ui/layout.stack@1", - "stateforge.ui/layout.grid@1", - "stateforge.ui/layout.section@1", - "stateforge.ui/layout.tabs@1", - "stateforge.ui/layout.steps@1", - "stateforge.ui/input.form@1", - "stateforge.ui/input.field@1", - "stateforge.ui/input.object@1", - "stateforge.ui/input.array@1", - "stateforge.ui/input.key_value@1", - "stateforge.ui/input.code@1", - "stateforge.ui/content.text@1", - "stateforge.ui/content.markdown@1", - "stateforge.ui/data.key_value@1", - "stateforge.ui/data.table@1", - "stateforge.ui/data.tree@1", - "stateforge.ui/data.code@1", - "stateforge.ui/data.diff@1", - "stateforge.ui/data.log@1", - "stateforge.ui/status.badge@1", - "stateforge.ui/status.progress@1", - "stateforge.ui/status.timeline@1", - "stateforge.ui/data.metric@1", - "stateforge.ui/data.chart@1", - "stateforge.ui/data.topology@1", - "stateforge.ui/data.artifacts@1", - "stateforge.ui/media.image@1", - "stateforge.ui/action.operation_submit@1", - "stateforge.ui/action.operation_cancel@1", - } + +@dataclass(frozen=True, slots=True) +class CoreComponentContract: + """Define Protocol-owned structure for one portable core component.""" + + permitted_surfaces: frozenset[str] + minimum_children: int = 0 + maximum_children: int = 0 + required_bindings: frozenset[str] = frozenset() + optional_bindings: frozenset[str] = frozenset() + binding_source_rules: tuple[tuple[str, frozenset[str]], ...] = () + required_assets: frozenset[str] = frozenset() + optional_assets: frozenset[str] = frozenset() + + +_LAYOUT_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + minimum_children=1, + maximum_children=MAX_COMPONENT_CHILDREN, +) +_INPUT_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=INPUT_PRESENTATION_SURFACES, + required_bindings=frozenset({"schema"}), + optional_bindings=frozenset({"value"}), + binding_source_rules=( + ( + "schema", + frozenset( + { + OPERATION_REQUEST_SCHEMA_BINDING, + TRIGGER_PAYLOAD_SCHEMA_BINDING, + } + ), + ), + ("value", frozenset({OPERATION_REQUEST_PUBLIC_VALUE_BINDING})), + ), +) +_INPUT_CONTAINER_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=INPUT_PRESENTATION_SURFACES, + maximum_children=MAX_COMPONENT_CHILDREN, + required_bindings=_INPUT_COMPONENT.required_bindings, + optional_bindings=_INPUT_COMPONENT.optional_bindings, + binding_source_rules=_INPUT_COMPONENT.binding_source_rules, +) +_SECRET_INPUT_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=INPUT_PRESENTATION_SURFACES, + required_bindings=frozenset({"schema"}), + binding_source_rules=( + ( + "schema", + frozenset( + { + OPERATION_REQUEST_SCHEMA_BINDING, + TRIGGER_PAYLOAD_SCHEMA_BINDING, + } + ), + ), + ), +) +_STATIC_CONTENT_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + optional_bindings=frozenset({"value"}), ) +_BOUND_VALUE_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"value"}), +) +_TABLE_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"rows"}), +) +_DIFF_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"before", "after"}), +) +_LOG_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"entries"}), +) +_TIMELINE_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"events"}), +) +_CHART_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"series"}), +) +_TOPOLOGY_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"nodes", "edges"}), +) +_ARTIFACTS_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_bindings=frozenset({"items"}), +) +_IMAGE_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=ALL_PRESENTATION_SURFACES, + required_assets=frozenset({"source"}), +) +_SUBMIT_ACTION_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=frozenset({OPERATION_REQUEST_SURFACE}), +) +_CANCEL_ACTION_COMPONENT: Final = CoreComponentContract( + permitted_surfaces=frozenset({OPERATION_RUN_SURFACE}), +) + +CORE_COMPONENT_CONTRACTS: Final = { + "stateforge.ui/layout.stack@1": _LAYOUT_COMPONENT, + "stateforge.ui/layout.grid@1": _LAYOUT_COMPONENT, + "stateforge.ui/layout.section@1": _LAYOUT_COMPONENT, + "stateforge.ui/layout.tabs@1": _LAYOUT_COMPONENT, + "stateforge.ui/layout.steps@1": _LAYOUT_COMPONENT, + "stateforge.ui/input.form@1": _INPUT_CONTAINER_COMPONENT, + "stateforge.ui/input.field@1": _INPUT_COMPONENT, + "stateforge.ui/input.object@1": _INPUT_CONTAINER_COMPONENT, + "stateforge.ui/input.array@1": _INPUT_CONTAINER_COMPONENT, + "stateforge.ui/input.key_value@1": _INPUT_COMPONENT, + "stateforge.ui/input.code@1": _INPUT_COMPONENT, + "stateforge.ui/input.secret@1": _SECRET_INPUT_COMPONENT, + "stateforge.ui/content.text@1": _STATIC_CONTENT_COMPONENT, + "stateforge.ui/content.markdown@1": _STATIC_CONTENT_COMPONENT, + "stateforge.ui/data.key_value@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/data.table@1": _TABLE_COMPONENT, + "stateforge.ui/data.tree@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/data.code@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/data.diff@1": _DIFF_COMPONENT, + "stateforge.ui/data.log@1": _LOG_COMPONENT, + "stateforge.ui/status.badge@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/status.progress@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/status.timeline@1": _TIMELINE_COMPONENT, + "stateforge.ui/data.metric@1": _BOUND_VALUE_COMPONENT, + "stateforge.ui/data.chart@1": _CHART_COMPONENT, + "stateforge.ui/data.topology@1": _TOPOLOGY_COMPONENT, + "stateforge.ui/data.artifacts@1": _ARTIFACTS_COMPONENT, + "stateforge.ui/media.image@1": _IMAGE_COMPONENT, + "stateforge.ui/action.operation_submit@1": _SUBMIT_ACTION_COMPONENT, + "stateforge.ui/action.operation_cancel@1": _CANCEL_ACTION_COMPONENT, +} + +CORE_COMPONENT_IDENTIFIERS: Final = frozenset(CORE_COMPONENT_CONTRACTS) ALLOWED_PRESENTATION_MEDIA_TYPES: Final = frozenset( { diff --git a/tests/test_documentation_system.py b/tests/test_documentation_system.py index 2416302..44d620b 100644 --- a/tests/test_documentation_system.py +++ b/tests/test_documentation_system.py @@ -101,6 +101,8 @@ def test_provider_presentation_guide_maps_components_to_surfaces() -> None: assert "active Control Plane skin" in page assert "operation.request.public_value@1" in page assert "has no presentation binding identifier" in page + assert "input.secret" in page + assert "Portable core structure" in page assert "No second SFP presentation RPC" in page assert "SF-AOP" in page diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index 8cfcf7e..4f7c5af 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -8,6 +8,7 @@ from pathlib import Path import pytest +from google.protobuf import struct_pb2 from google.protobuf.json_format import MessageToDict, ParseDict from stateforge_protocol.sfp.manifest.v1 import contract, manifest_pb2 @@ -479,6 +480,108 @@ def test_core_component_catalog_is_explicit() -> None: _validate_presentation(response) +def test_core_action_is_rejected_outside_its_operation_surface() -> None: + response = _presentation_response() + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + root.component_identifier = "stateforge.ui/action.operation_submit@1" + + with pytest.raises(ManifestValidationError, match="unavailable"): + _validate_presentation(response) + + +def test_core_leaf_component_rejects_children() -> None: + response = _presentation_response() + image = _provider_image(response) + child = image.children.add( + component_identifier="stateforge.ui/content.text@1" + ) + child.properties.CopyFrom(struct_pb2.Struct()) + + with pytest.raises(ManifestValidationError, match="child contract"): + _validate_presentation(response) + + +def test_core_component_requires_its_binding_slots() -> None: + response = _presentation_response() + event = next(iter(response.presentation.triggers.values())) + event.surfaces[contract.TRIGGER_EVENT_SURFACE].root.ClearField("bindings") + + with pytest.raises(ManifestValidationError, match="required binding"): + _validate_presentation(response) + + +def test_core_component_rejects_unknown_binding_slots() -> None: + response = _presentation_response() + image = _provider_image(response) + image.bindings[ + "value" + ].source_identifier = contract.PROVIDER_MANIFEST_BINDING + + with pytest.raises(ManifestValidationError, match="binding slot"): + _validate_presentation(response) + + +def test_core_input_schema_slot_rejects_value_sources() -> None: + response = _presentation_response() + request = _operation_root(response, contract.OPERATION_REQUEST_SURFACE) + request.bindings[ + "schema" + ].source_identifier = contract.OPERATION_REQUEST_PUBLIC_VALUE_BINDING + + with pytest.raises(ManifestValidationError, match="component slot"): + _validate_presentation(response) + + +def test_core_media_component_requires_its_asset_slot() -> None: + response = _presentation_response() + _provider_image(response).ClearField("asset_bindings") + + with pytest.raises(ManifestValidationError, match="required asset"): + _validate_presentation(response) + + +def test_core_component_cannot_declare_a_fallback() -> None: + response = _presentation_response() + root = response.presentation.provider.surfaces[ + contract.PROVIDER_OVERVIEW_SURFACE + ].root + root.fallback.component_identifier = "stateforge.ui/content.text@1" + root.fallback.properties.CopyFrom(struct_pb2.Struct()) + + with pytest.raises(ManifestValidationError, match="cannot declare"): + _validate_presentation(response) + + +def test_secret_input_is_part_of_the_portable_core_catalog() -> None: + secret = contract.CORE_COMPONENT_CONTRACTS["stateforge.ui/input.secret@1"] + + assert secret.required_bindings == frozenset({"schema"}) + assert "value" not in secret.optional_bindings + + +@pytest.mark.parametrize( + ("identifier", "required_bindings"), + [ + ("stateforge.ui/data.table@1", {"rows"}), + ("stateforge.ui/data.diff@1", {"before", "after"}), + ("stateforge.ui/data.log@1", {"entries"}), + ("stateforge.ui/status.timeline@1", {"events"}), + ("stateforge.ui/data.chart@1", {"series"}), + ("stateforge.ui/data.topology@1", {"nodes", "edges"}), + ("stateforge.ui/data.artifacts@1", {"items"}), + ], +) +def test_core_data_components_have_semantic_binding_slots( + identifier: str, + required_bindings: set[str], +) -> None: + component = contract.CORE_COMPONENT_CONTRACTS[identifier] + + assert component.required_bindings == frozenset(required_bindings) + + def test_custom_component_requires_renderer_metadata() -> None: response = _presentation_response() del response.presentation.renderer_requirements["stateforge.git"] @@ -546,7 +649,7 @@ def test_repetition_scope_is_available_to_component_bindings() -> None: ) repeated.repeat.item_scope = "row" repeated.repeat.max_items = 100 - repeated.bindings["item"].CopyFrom( + repeated.bindings["rows"].CopyFrom( manifest_pb2.DataBinding( source_identifier=contract.REPETITION_ITEM_BINDING, pointer="/name", @@ -678,7 +781,17 @@ def test_asset_reference_must_resolve() -> None: def test_unreferenced_assets_are_rejected() -> None: response = _presentation_response() - _provider_image(response).ClearField("asset_bindings") + content = _png() + digest = "sha256:" + hashlib.sha256(content).hexdigest() + response.presentation.assets[digest].CopyFrom( + manifest_pb2.PresentationAsset( + media_type="image/png", + content=content, + width=1, + height=1, + alt_text="Unreferenced image", + ) + ) with pytest.raises(ManifestValidationError, match="unreferenced asset"): _validate_presentation(response) From 99ae1f3ebbc235b874b656ac975be8a9889f2026 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 17:20:49 +0200 Subject: [PATCH 6/8] fix(manifest): reserve StateForge view namespaces --- .../procedures/provider-presentation.md | 13 ++++-- .../sfp/manifest/v1/manifest.proto | 2 +- .../sfp/manifest/v1/_presentation.py | 17 +++++++- .../sfp/manifest/v1/contract.py | 1 + .../sfp/manifest/v1/manifest_pb2.pyi | 2 +- .../manifest/presentation-response.json | 8 ++-- tests/test_manifest_validation.py | 40 +++++++++++++++++-- 7 files changed, 67 insertions(+), 16 deletions(-) diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index 72a5754..6249d1a 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -211,7 +211,7 @@ validation or manufacture an operation field. ## Custom components and renderer extensions A Provider may use its own component identifier, such as -`stateforge.git/data.commit_graph@1`. A custom node has two additional +`example.git/data.commit_graph@1`. A custom node has two additional requirements: 1. its namespace has one matching `RendererRequirement`; and @@ -220,7 +220,7 @@ requirements: ```json { - "componentIdentifier": "stateforge.git/data.commit_graph@1", + "componentIdentifier": "example.git/data.commit_graph@1", "properties": {}, "bindings": { "result": { @@ -251,8 +251,8 @@ The matching requirement carries identity and compatibility metadata: ```json { - "stateforge.git": { - "extensionIdentifier": "stateforge.git/renderer@1", + "example.git": { + "extensionIdentifier": "example.git/renderer@1", "extensionVersion": "1.0.0", "rendererApiVersion": "1.0.0", "artifactDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", @@ -261,6 +261,11 @@ The matching requirement carries identity and compatibility metadata: } ``` +Every namespace beginning with `stateforge.` is reserved for identifiers +defined by StateForge contracts. A Provider-owned renderer must use a namespace +it owns; it cannot introduce custom components or renderer requirements under +`stateforge.ui`, `stateforge.ui.*`, or another `stateforge.*` namespace. + The renderer artifact is distributed separately from SFP. The Control Plane uses the metadata to locate an already trusted or separately acquired bundle, checks compatibility and permissions in its extension host, and registers the diff --git a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto index b300851..df79273 100644 --- a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto +++ b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto @@ -145,7 +145,7 @@ message ProviderPresentation { // Embedded content-addressed visuals keyed by their sha256 digest. map assets = 5; // Renderer metadata keyed by the custom component namespace it serves. - // Core stateforge.ui components never require an entry here. + // Every stateforge.* namespace is reserved and cannot require an extension. map renderer_requirements = 6; } diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py index f1c0c51..b2778a4 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -114,9 +114,10 @@ def validate_presentation_semantics( raise error_type( "presentation: trigger target does not name a declared trigger" ) - if contract.CORE_COMPONENT_NAMESPACE in requirements: + if any(_is_stateforge_owned(namespace) for namespace in requirements): raise error_type( - "presentation: core components cannot require an extension" + "presentation: renderer requirements cannot use a " + "StateForge-owned namespace" ) state = _PresentationState() @@ -318,6 +319,11 @@ def _validate_component_identity( "presentation: core component cannot declare a fallback" ) return component_contract + if _is_stateforge_owned(namespace): + raise error_type( + "presentation: custom component cannot use a StateForge-owned " + "namespace" + ) if core_only and not is_core: raise error_type( "presentation: custom component fallback must use core components" @@ -540,6 +546,13 @@ def _namespace(identifier: str) -> str: return identifier.split("/", 1)[0] +def _is_stateforge_owned(namespace: str) -> bool: + return ( + namespace == contract.STATEFORGE_NAMESPACE_ROOT + or namespace.startswith(f"{contract.STATEFORGE_NAMESPACE_ROOT}.") + ) + + def _validate_assets( message: manifest_pb2.ProviderPresentation, references: set[str], diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index 1cb3d9b..30a2dbf 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -57,6 +57,7 @@ MAX_PRESENTATION_POINTER_CODE_POINTS: Final = 2_048 MAX_PRESENTATION_SCOPE_CODE_POINTS: Final = 64 +STATEFORGE_NAMESPACE_ROOT: Final = "stateforge" CORE_COMPONENT_NAMESPACE: Final = "stateforge.ui" PROVIDER_OVERVIEW_SURFACE: Final = "stateforge.ui/surface.provider.overview@1" diff --git a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi index c816f03..ee2d24a 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi @@ -539,7 +539,7 @@ class ProviderPresentation(_message.Message): @_builtins.property def renderer_requirements(self) -> _containers.MessageMap[_builtins.str, Global___RendererRequirement]: """Renderer metadata keyed by the custom component namespace it serves. - Core stateforge.ui components never require an entry here. + Every stateforge.* namespace is reserved and cannot require an extension. """ def __init__( diff --git a/tests/fixtures/manifest/presentation-response.json b/tests/fixtures/manifest/presentation-response.json index 9303a52..37f40c1 100644 --- a/tests/fixtures/manifest/presentation-response.json +++ b/tests/fixtures/manifest/presentation-response.json @@ -167,7 +167,7 @@ }, "stateforge.ui/surface.operation.result@1": { "root": { - "componentIdentifier": "stateforge.git/data.commit_graph@1", + "componentIdentifier": "example.git/data.commit_graph@1", "properties": {}, "bindings": { "result": { @@ -227,8 +227,8 @@ } }, "rendererRequirements": { - "stateforge.git": { - "extensionIdentifier": "stateforge.git/renderer@1", + "example.git": { + "extensionIdentifier": "example.git/renderer@1", "extensionVersion": "1.0.0", "rendererApiVersion": "1.0.0", "artifactDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", @@ -236,5 +236,5 @@ } } }, - "presentationRevision": "sha256:2eabed9abfbb8736d5cbe1f9bb788ff5283e18bdc1d7bb58b455719a6feeed3e" + "presentationRevision": "sha256:df215c63eb41659f8d38649cf84bd9f9e7696aa9d08b88219f219361d1bc8d2d" } diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index 4f7c5af..fd1f1e6 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -584,7 +584,7 @@ def test_core_data_components_have_semantic_binding_slots( def test_custom_component_requires_renderer_metadata() -> None: response = _presentation_response() - del response.presentation.renderer_requirements["stateforge.git"] + del response.presentation.renderer_requirements["example.git"] with pytest.raises(ManifestValidationError, match="renderer requirement"): _validate_presentation(response) @@ -604,7 +604,7 @@ def test_custom_component_fallback_cannot_require_an_extension() -> None: response = _presentation_response() _operation_root( response, contract.OPERATION_RESULT_SURFACE - ).fallback.component_identifier = "stateforge.git/data.commit_graph@1" + ).fallback.component_identifier = "example.git/data.commit_graph@1" with pytest.raises(ManifestValidationError, match="core components"): _validate_presentation(response) @@ -613,7 +613,7 @@ def test_custom_component_fallback_cannot_require_an_extension() -> None: def test_renderer_requirements_cannot_be_unreferenced() -> None: response = _presentation_response() response.presentation.renderer_requirements["example.widget"].CopyFrom( - response.presentation.renderer_requirements["stateforge.git"] + response.presentation.renderer_requirements["example.git"] ) requirement = response.presentation.renderer_requirements["example.widget"] requirement.extension_identifier = "example.widget/renderer@1" @@ -625,13 +625,45 @@ def test_renderer_requirements_cannot_be_unreferenced() -> None: def test_renderer_extension_must_share_component_namespace() -> None: response = _presentation_response() response.presentation.renderer_requirements[ - "stateforge.git" + "example.git" ].extension_identifier = "example.widget/renderer@1" with pytest.raises(ManifestValidationError, match="namespace"): _validate_presentation(response) +@pytest.mark.parametrize( + "identifier", + [ + "stateforge.git/data.commit_graph@1", + "stateforge.ui.custom/data.commit_graph@1", + ], +) +def test_custom_components_cannot_claim_stateforge_namespaces( + identifier: str, +) -> None: + response = _presentation_response() + _operation_root( + response, contract.OPERATION_RESULT_SURFACE + ).component_identifier = identifier + + with pytest.raises(ManifestValidationError, match="StateForge-owned"): + _validate_presentation(response) + + +def test_renderer_requirements_cannot_claim_stateforge_namespaces() -> None: + response = _presentation_response() + reserved = response.presentation.renderer_requirements["stateforge.git"] + reserved.CopyFrom( + response.presentation.renderer_requirements["example.git"] + ) + reserved.extension_identifier = "stateforge.git/renderer@1" + del response.presentation.renderer_requirements["example.git"] + + with pytest.raises(ManifestValidationError, match="StateForge-owned"): + _validate_presentation(response) + + def test_repetition_scope_is_available_to_component_bindings() -> None: response = _presentation_response() root = response.presentation.provider.surfaces[ From e839b5be1ceb680a1611fba83127f18ce9dfba00 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 17:27:01 +0200 Subject: [PATCH 7/8] fix(manifest): validate complete PNG image data --- .../procedures/provider-presentation.md | 4 +- .../sfp/manifest/v1/_presentation.py | 197 +++++++++++++++--- .../sfp/manifest/v1/contract.py | 1 + tests/test_manifest_validation.py | 111 +++++++++- 4 files changed, 281 insertions(+), 32 deletions(-) diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index 6249d1a..69c8bd6 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -281,7 +281,9 @@ limiting advanced Provider authors to the built-in catalog. `PresentationAsset` carries bounded, content-addressed PNG or sanitized SVG media. Nodes refer to assets through named `asset_bindings`. Every digest must match the exact bytes, every reference must resolve, and unreferenced assets -are rejected. +are rejected. PNG validation also verifies the complete compressed stream, +decoded scanline layout and filter bytes under a decoded-size ceiling; valid +chunk framing and CRCs alone are not sufficient. Assets provide Provider-owned icons and visuals. The active Control Plane skin still controls their framing, size, background, and placement. diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py index b2778a4..b1bca07 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -83,6 +83,8 @@ _PNG_SIGNATURE: Final = b"\x89PNG\r\n\x1a\n" _PNG_CHUNK_OVERHEAD: Final = 12 _PNG_IHDR_BYTES: Final = 13 +_PNG_DECODE_CHUNK_BYTES: Final = 64 * 1024 +_PNG_MAX_FILTER_TYPE: Final = 4 _SAFE_PNG_CHUNKS: Final = frozenset( {b"IHDR", b"PLTE", b"IDAT", b"IEND", b"tRNS"} ) @@ -644,6 +646,10 @@ def _png_dimensions( _reject_png(error_type) offset = len(_PNG_SIGNATURE) dimensions: tuple[int, int] | None = None + bit_depth: int | None = None + color_type: int | None = None + interlace_method: int | None = None + image_data: list[bytes] = [] saw_image_data = False while offset + _PNG_CHUNK_OVERHEAD <= len(content): length = struct.unpack(">I", content[offset : offset + 4])[0] @@ -659,44 +665,185 @@ def _png_dimensions( if expected_crc != actual_crc & 0xFFFFFFFF: _reject_png(error_type) if dimensions is None: - if chunk_type != b"IHDR" or length != _PNG_IHDR_BYTES: - _reject_png(error_type) - width, height = struct.unpack( - ">II", content[data_start : data_start + 8] + ( + dimensions, + bit_depth, + color_type, + interlace_method, + ) = _read_png_header( + chunk_type, + content[data_start:data_end], + error_type, ) - bit_depth = content[data_start + 8] - color_type = content[data_start + 9] - valid_depths = { - 0: {1, 2, 4, 8, 16}, - 2: {8, 16}, - 3: {1, 2, 4, 8}, - 4: {8, 16}, - 6: {8, 16}, - } - if ( - not width - or not height - or width > contract.MAX_PRESENTATION_ASSET_DIMENSION - or height > contract.MAX_PRESENTATION_ASSET_DIMENSION - or bit_depth not in valid_depths.get(color_type, set()) - or content[data_start + 10 : data_start + 12] != b"\x00\x00" - or content[data_start + 12] not in {0, 1} - ): - _reject_png(error_type) - dimensions = (width, height) elif chunk_type == b"IHDR": _reject_png(error_type) if chunk_type == b"IDAT": saw_image_data = True + image_data.append(content[data_start:data_end]) + elif saw_image_data and chunk_type != b"IEND": + _reject_png(error_type) if chunk_type == b"IEND": if length or not saw_image_data or chunk_end != len(content): _reject_png(error_type) - if dimensions is None: + if ( + dimensions is None + or bit_depth is None + or color_type is None + or interlace_method is None + ): _reject_png(error_type) + _validate_png_image_data( + b"".join(image_data), + width=dimensions[0], + height=dimensions[1], + bit_depth=bit_depth, + color_type=color_type, + interlace_method=interlace_method, + error_type=error_type, + ) return dimensions offset = chunk_end _reject_png(error_type) +def _read_png_header( + chunk_type: bytes, + data: bytes, + error_type: type[ValueError], +) -> tuple[tuple[int, int], int, int, int]: + if chunk_type != b"IHDR" or len(data) != _PNG_IHDR_BYTES: + _reject_png(error_type) + width, height = struct.unpack(">II", data[:8]) + bit_depth = data[8] + color_type = data[9] + interlace_method = data[12] + valid_depths = { + 0: {1, 2, 4, 8, 16}, + 2: {8, 16}, + 3: {1, 2, 4, 8}, + 4: {8, 16}, + 6: {8, 16}, + } + if ( + not width + or not height + or width > contract.MAX_PRESENTATION_ASSET_DIMENSION + or height > contract.MAX_PRESENTATION_ASSET_DIMENSION + or bit_depth not in valid_depths.get(color_type, set()) + or data[10:12] != b"\x00\x00" + or interlace_method not in {0, 1} + ): + _reject_png(error_type) + return (width, height), bit_depth, color_type, interlace_method + + +def _validate_png_image_data( + compressed: bytes, + *, + width: int, + height: int, + bit_depth: int, + color_type: int, + interlace_method: int, + error_type: type[ValueError], +) -> None: + """Decode bounded IDAT data and validate its complete scanline framing.""" + scanline_lengths = _png_scanline_lengths( + width, + height, + bit_depth, + color_type, + interlace_method, + ) + decoded_bytes = sum(length + 1 for length in scanline_lengths) + if decoded_bytes > contract.MAX_PRESENTATION_PNG_DECODED_BYTES: + _reject_png(error_type) + + decoder = zlib.decompressobj() + pending = compressed + row_index = 0 + row_remaining = 0 + try: + while True: + pending_bytes = len(pending) + decoded = decoder.decompress(pending, _PNG_DECODE_CHUNK_BYTES) + pending = decoder.unconsumed_tail + row_index, row_remaining = _consume_png_scanlines( + decoded, + scanline_lengths=scanline_lengths, + row_index=row_index, + row_remaining=row_remaining, + error_type=error_type, + ) + if decoder.eof: + if pending or decoder.unused_data: + _reject_png(error_type) + break + if (not pending and not decoded) or ( + not decoded and len(pending) == pending_bytes + ): + _reject_png(error_type) + except zlib.error: + _reject_png(error_type) + + if row_index != len(scanline_lengths) or row_remaining: + _reject_png(error_type) + + +def _consume_png_scanlines( + decoded: bytes, + *, + scanline_lengths: tuple[int, ...], + row_index: int, + row_remaining: int, + error_type: type[ValueError], +) -> tuple[int, int]: + for value in decoded: + if not row_remaining: + if ( + row_index >= len(scanline_lengths) + or value > _PNG_MAX_FILTER_TYPE + ): + _reject_png(error_type) + row_remaining = scanline_lengths[row_index] + row_index += 1 + else: + row_remaining -= 1 + return row_index, row_remaining + + +def _png_scanline_lengths( + width: int, + height: int, + bit_depth: int, + color_type: int, + interlace_method: int, +) -> tuple[int, ...]: + channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}[color_type] + bits_per_pixel = channels * bit_depth + if not interlace_method: + row_bytes = (width * bits_per_pixel + 7) // 8 + return (row_bytes,) * height + + passes = ( + (0, 0, 8, 8), + (4, 0, 8, 8), + (0, 4, 4, 8), + (2, 0, 4, 4), + (0, 2, 2, 4), + (1, 0, 2, 2), + (0, 1, 1, 2), + ) + rows: list[int] = [] + for x_start, y_start, x_step, y_step in passes: + if width <= x_start or height <= y_start: + continue + pass_width = (width - x_start + x_step - 1) // x_step + pass_height = (height - y_start + y_step - 1) // y_step + row_bytes = (pass_width * bits_per_pixel + 7) // 8 + rows.extend((row_bytes,) * pass_height) + return tuple(rows) + + def _reject_png(error_type: type[ValueError]) -> Never: raise error_type("presentation: invalid PNG content") diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index 30a2dbf..ccf9a67 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -54,6 +54,7 @@ MAX_PRESENTATION_ASSET_BYTES: Final = 256 * 1024 MAX_PRESENTATION_ASSET_TOTAL_BYTES: Final = 1 * 1024 * 1024 MAX_PRESENTATION_ASSET_DIMENSION: Final = 8_192 +MAX_PRESENTATION_PNG_DECODED_BYTES: Final = 64 * 1024 * 1024 MAX_PRESENTATION_POINTER_CODE_POINTS: Final = 2_048 MAX_PRESENTATION_SCOPE_CODE_POINTS: Final = 64 diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index fd1f1e6..ee1fadb 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -95,20 +95,42 @@ def _png_chunk(kind: bytes, content: bytes) -> bytes: ) -def _png(width: int = 1, height: int = 1) -> bytes: - +def _png_with_image_data( + image_data: bytes, + *, + width: int = 1, + height: int = 1, + interlace_method: int = 0, + split_at: int | None = None, +) -> bytes: header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0) - pixels = b"".join( - b"\x00" + (b"\x00\x00\x00\x00" * width) for _ in range(height) - ) + header = header[:-1] + bytes([interlace_method]) + if split_at is None: + data_chunks = (_png_chunk(b"IDAT", image_data),) + else: + data_chunks = ( + _png_chunk(b"IDAT", image_data[:split_at]), + _png_chunk(b"IDAT", image_data[split_at:]), + ) return ( b"\x89PNG\r\n\x1a\n" + _png_chunk(b"IHDR", header) - + _png_chunk(b"IDAT", zlib.compress(pixels)) + + b"".join(data_chunks) + _png_chunk(b"IEND", b"") ) +def _png(width: int = 1, height: int = 1) -> bytes: + pixels = b"".join( + b"\x00" + (b"\x00\x00\x00\x00" * width) for _ in range(height) + ) + return _png_with_image_data( + zlib.compress(pixels), + width=width, + height=height, + ) + + def _replace_provider_icon( response: manifest_pb2.GetManifestResponse, *, @@ -926,6 +948,83 @@ def test_png_crc_and_chunk_allowlist_are_enforced() -> None: _validate_presentation(response) +@pytest.mark.parametrize( + "image_data", + [ + b"not a zlib stream", + zlib.compress(b"\x00\x00\x00\x00\x00")[:-1], + zlib.compress(b"\x00\x00\x00\x00\x00") + b"trailing", + zlib.compress(b"\x00\x00\x00\x00\x00\x00"), + zlib.compress(b"\x05\x00\x00\x00\x00"), + ], +) +def test_png_image_data_must_decode_to_exact_scanlines( + image_data: bytes, +) -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=_png_with_image_data(image_data), + media_type="image/png", + width=1, + height=1, + ) + + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + +def test_png_consecutive_idat_chunks_form_one_valid_stream() -> None: + response = _presentation_response() + image_data = zlib.compress(b"\x00\x00\x00\x00\x00") + _replace_provider_icon( + response, + content=_png_with_image_data( + image_data, + split_at=len(image_data) // 2, + ), + media_type="image/png", + width=1, + height=1, + ) + + _validate_presentation(response) + + +def test_png_adam7_scanline_layout_is_accepted() -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=_png_with_image_data( + zlib.compress(b"\x00\x00\x00\x00\x00"), + interlace_method=1, + ), + media_type="image/png", + width=1, + height=1, + ) + + _validate_presentation(response) + + +def test_png_decoded_size_is_bounded_before_decompression() -> None: + response = _presentation_response() + _replace_provider_icon( + response, + content=_png_with_image_data( + zlib.compress(b""), + width=contract.MAX_PRESENTATION_ASSET_DIMENSION, + height=contract.MAX_PRESENTATION_ASSET_DIMENSION, + ), + media_type="image/png", + width=contract.MAX_PRESENTATION_ASSET_DIMENSION, + height=contract.MAX_PRESENTATION_ASSET_DIMENSION, + ) + + with pytest.raises(ManifestValidationError, match="invalid PNG"): + _validate_presentation(response) + + @pytest.mark.parametrize( "content", [ From 91a457850ffb7450eaa3c5777e46835115f72b16 Mon Sep 17 00:00:00 2001 From: Noam Alum Date: Tue, 27 Oct 2026 17:30:56 +0200 Subject: [PATCH 8/8] =?UTF-8?q?Removed=20ugly=20=E2=80=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/v0.1.0/getting-started.md | 4 ++-- docs/v0.1.0/procedures/provider-manifest.md | 14 +++++++------- docs/v0.1.0/procedures/provider-presentation.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/v0.1.0/getting-started.md b/docs/v0.1.0/getting-started.md index b9ba9a9..ab1dd5d 100644 --- a/docs/v0.1.0/getting-started.md +++ b/docs/v0.1.0/getting-started.md @@ -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 \ @@ -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 \ diff --git a/docs/v0.1.0/procedures/provider-manifest.md b/docs/v0.1.0/procedures/provider-manifest.md index eb937a6..387e80b 100644 --- a/docs/v0.1.0/procedures/provider-manifest.md +++ b/docs/v0.1.0/procedures/provider-manifest.md @@ -548,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 diff --git a/docs/v0.1.0/procedures/provider-presentation.md b/docs/v0.1.0/procedures/provider-presentation.md index 69c8bd6..165abcb 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -117,7 +117,7 @@ require adding a new component-specific message or enum to SFP. Core identifiers also carry a small Protocol-owned structural contract. This does not define styling or renderer properties; it guarantees that an accepted -core tree—including a custom component's fallback—can be interpreted the same +core tree, including a custom component's fallback, can be interpreted the same way by every conforming Control Plane. | Core family | Surfaces | Children | Binding and asset slots |