diff --git a/docs/v0.1.0/procedures/provider-manifest.md b/docs/v0.1.0/procedures/provider-manifest.md index 387e80b..844e732 100644 --- a/docs/v0.1.0/procedures/provider-manifest.md +++ b/docs/v0.1.0/procedures/provider-manifest.md @@ -293,8 +293,8 @@ absent or rejected. A valid presentation is revised independently and bound to the accepted `manifest_revision`. The [Provider presentation guide](provider-presentation.md) explains surfaces, -the generic component tree, core renderers, custom renderer metadata and -fallback, data bindings, and embedded assets. The wire fields, validation +the generic component tree, the Control Plane-owned renderer catalog, 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 165abcb..6ec3977 100644 --- a/docs/v0.1.0/procedures/provider-presentation.md +++ b/docs/v0.1.0/procedures/provider-presentation.md @@ -15,21 +15,22 @@ from its JSON Schemas. ```mermaid flowchart LR 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"] + Presentation["ProviderPresentation
opaque identifiers + bounded tree"] --> Validate{"SFP generic
structure valid?"} + Validate -->|yes| Registry["Control Plane-owned
catalog + 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"] + Registry -->|supported| Render["Rendered surfaces"] + Registry -.->|unsupported| Defaults Defaults --> Render ``` | Layer | Owns | | --- | --- | | 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 | +| SFP presentation contract | Generic bounded component-tree structure, bindings, conditions, repetition, asset bytes, and transport limits | +| Control Plane catalog and renderer registry | Surface and component applicability, property schemas, data-source resolution, renderer availability, and rendering behavior | | Control Plane skin | Typography, color, spacing, framing, and product-wide visual language | SFP carries declarative data only. It never carries HTML, CSS, JavaScript, @@ -41,17 +42,11 @@ 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. -Each target contains one or more named surfaces: - -| Target | Surface identifier | Intended use | -| --- | --- | --- | -| 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 | +Each target contains a map of named surfaces. The Control Plane catalog owns +surface identifiers and their applicability to Provider, operation, and trigger +targets. SFP accepts any well-formed surface identifier on any target; it does +not maintain the surface list or decide which target type or Control Plane +supports a surface. Groups are optional. A Provider author creates visual grouping with ordinary layout components such as a section, grid, tabs, or steps; the Protocol does @@ -73,7 +68,7 @@ flowchart TD Root --> Assets["asset_bindings"] Root -. optional .-> Condition["condition"] Root -. optional .-> Repeat["repeat"] - Root -. custom only .-> Fallback["core fallback"] + Root -. optional .-> Fallback["fallback tree"] ``` | Node field | Meaning | @@ -85,99 +80,52 @@ flowchart TD | `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`, `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` | - -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. - -### 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. +| `fallback` | Optional declarative tree that the Control Plane may use according to its own policy | + +The Protocol checks generic identifier syntax and bounded tree structure; +component identifiers, surface identifiers, binding slot names, asset slot +names, and property meanings are opaque to SFP. It does not maintain the +Provider Views catalog or decide whether a component is supported on a +surface. The Control Plane owns the catalog and renderer registry, validates +properties and applicability, resolves data sources, and decides how to handle +unknown or unsupported identifiers. A Control Plane is not required to render +every catalog component. +Component applicability is not decided by SFP. + +The catalog's 30 component identifiers are maintained by the Control Plane. +Those names are ordinary versioned identifiers in this wire format—not +Protocol enums, component-specific protobuf messages, or a Protocol allowlist. +A catalog or renderer change does not require changing the SFP message schema. ## Data bindings -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. - -Examples include: - -| Surface | Representative binding sources | -| --- | --- | -| Provider overview | Provider manifest and Provider runtime state | -| 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 | +A `DataBinding` names a Control Plane-provided source and optionally a JSON +Pointer within it. An empty pointer selects the complete source. SFP treats +source identifiers and their availability as opaque; the Control Plane owns +the source catalog and decides which sources a given target and surface may +resolve. It must not resolve a source the active rendering context does not +provide. 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. +repetition also declares a positive `max_items` ceiling. These are generic +tree and resource invariants; component-specific repetition behavior belongs +to the Control Plane catalog. 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. +`stateforge.binding/operation.request.public_value@1` denotes a safe +projection, not the submitted request: every value whose applicable input +schema marks it `writeOnly` is omitted. If the data-source owner cannot prove a +value is public, it must omit it. Secret-entry state remains private to the +Control Plane and is never addressable by a presentation binding. The raw +operation request binding identifier is forbidden by SFP. -## Core example +## Example presentation -The manifest fixture uses a core form for the operation request: +The manifest fixture uses a form component identifier for the operation request: ```json { @@ -211,12 +159,11 @@ validation or manufacture an operation field. ## Custom components and renderer extensions A Provider may use its own component identifier, such as -`example.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. +`example.git/data.commit_graph@1`. A node may include a fallback tree and +`RendererRequirement` metadata. SFP transports these fields as bounded declarative data; it +does not require an identifier to be listed in a Protocol registry, require a +renderer requirement for a node, or restrict fallback nodes to a Protocol +catalog. ```json { @@ -247,7 +194,8 @@ requirements: } ``` -The matching requirement carries identity and compatibility metadata: +Renderer metadata may carry identity and compatibility information for a +separately installed renderer: ```json { @@ -261,20 +209,17 @@ 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. +Renderer requirements cannot claim a `stateforge.*` namespace. Component +identifier support and ownership are resolved by the Control Plane catalog; +SFP does not use a namespace to classify components as built-in or custom. 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. +decides whether to trust, acquire, enable, and register it. SFP transports the +metadata as bounded data and never downloads or executes renderer code. 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. +Plane applies its own fallback policy. Fallback availability and use are not +determined by SFP. ## Embedded assets @@ -296,13 +241,15 @@ The presentation is then evaluated independently: | Presentation state | Result | | --- | --- | | Absent | Keep the manifest and render from its JSON Schemas. | -| Supported and valid | Cache the component tree and its independent revision. | +| Structurally valid | Cache the component tree and its independent revision; renderer support is not decided here. | | 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. | +| Invalid generic structure, forbidden raw request binding, asset, or revision | Keep the manifest and discard the complete presentation snapshot. | -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. +The Protocol enforces generic limits for tree depth, total component count, +children, bindings, properties, repetition, renderer metadata, permissions, +assets, and canonical bytes. It does not reject a presentation because a +component, surface, property, slot, or data source is unknown to SFP. Partial +acceptance is not allowed for structural or safety failures. `manifest_revision` excludes presentation. `presentation_revision` hashes the complete presentation and is bound to the accepted manifest revision, so a @@ -314,11 +261,10 @@ The Provider returns `ProviderPresentation` through the existing `ManifestService.GetManifest` response. The Agent validates and caches the 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. +SF-AOP transports the accepted snapshots to the Control Plane; SFP introduces +no separate presentation RPC. The Control Plane resolves component +identifiers through its renderer registry, binds the current runtime data, +applies its active skin, and renders the surface. For the exact service envelope, revision construction, limits, and public Python validators, return to @@ -328,10 +274,10 @@ Python validators, return to | 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. | +| [`contract.py`](https://github.com/stateforge-org/stateforge-protocol/blob/mvp/implementation/src/stateforge_protocol/sfp/manifest/v1/contract.py) | Owns generic wire limits, repetition safety identifiers, renderer-metadata bounds, and component-tree bounds—not the Control Plane renderer catalog. | | [`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. | -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. +Provider and Agent implementations should use these generic Protocol +definitions for wire validation and resource limits. The Control Plane owns +the renderer catalog, component and surface applicability, source availability, +property schemas, fallback behavior, and rendering semantics. diff --git a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto index df79273..9a6492e 100644 --- a/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto +++ b/proto/stateforge_protocol/sfp/manifest/v1/manifest.proto @@ -162,7 +162,8 @@ message PresentationSurface { // 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. +// by SFP. Component and surface applicability are decided by the Control Plane. +// Fallback trees are optional and are interpreted by the Control Plane. message ComponentNode { string component_identifier = 1; google.protobuf.Struct properties = 2; diff --git a/scripts/ci/verify_installed.py b/scripts/ci/verify_installed.py index 6ca8f19..e2cbc7b 100644 --- a/scripts/ci/verify_installed.py +++ b/scripts/ci/verify_installed.py @@ -30,7 +30,6 @@ 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, @@ -230,7 +229,7 @@ def _verify_manifest_validation(fixture_root: Path) -> int: raise ValueError("Installed Provider presentation was not accepted") presented.presentation.provider.surfaces[ - manifest_contract.PROVIDER_OVERVIEW_SURFACE + "stateforge.ui/surface.provider.overview@1" ].root.properties.update({"tampered": True}) rejected = manifest_validation.validate_manifest_exchange(presented) if ( diff --git a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py index b1bca07..266bb98 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/_presentation.py +++ b/src/stateforge_protocol/sfp/manifest/v1/_presentation.py @@ -123,48 +123,15 @@ def validate_presentation_semantics( ) 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" + targets = [presentation.get("provider")] + targets.extend(operation_targets.values()) + targets.extend(trigger_targets.values()) + for target in targets: + if isinstance(target, dict): + _validate_target( + target, + state=state, + error_type=error_type, ) _validate_assets(message, state.asset_references, error_type) @@ -175,35 +142,22 @@ class _PresentationState: def __init__(self) -> None: self.component_count = 0 - self.custom_namespaces: set[str] = set() self.asset_references: set[str] = set() def _validate_target( target: dict[str, Any], *, - target_kind: str, - permitted_surfaces: frozenset[str], state: _PresentationState, - requirements: dict[str, dict[str, Any]], error_type: type[ValueError], ) -> None: surfaces = cast(dict[str, dict[str, Any]], target["surfaces"]) - unsupported = surfaces.keys() - permitted_surfaces - if unsupported: - raise error_type( - f"presentation: surface is not valid for {target_kind} targets" - ) - for surface_identifier, surface in surfaces.items(): + for surface in surfaces.values(): _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, ) @@ -211,13 +165,9 @@ def _validate_target( 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: @@ -226,13 +176,6 @@ def _validate_component( if state.component_count > contract.MAX_PRESENTATION_COMPONENTS: raise error_type("presentation: component count limit exceeded") - 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)) @@ -242,8 +185,6 @@ def _validate_component( current_scopes = _extend_repetition_scopes( node, - surface_identifier=surface_identifier, - target_kind=target_kind, scopes=scopes, error_type=error_type, ) @@ -251,164 +192,37 @@ def _validate_component( 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() ) - 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, - 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 _validate_component_identity( - node: dict[str, Any], - *, - core_only: bool, - state: _PresentationState, - requirements: dict[str, dict[str, Any]], - error_type: type[ValueError], -) -> contract.CoreComponentContract | None: - identifier = cast(str, node["componentIdentifier"]) - namespace = _namespace(identifier) - is_core = namespace == contract.CORE_COMPONENT_NAMESPACE - 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 _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" - ) - 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: 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( node: dict[str, Any], *, - surface_identifier: str, - target_kind: str, scopes: frozenset[str], error_type: type[ValueError], ) -> frozenset[str]: @@ -417,8 +231,6 @@ def _extend_repetition_scopes( return scopes _validate_binding( cast(dict[str, Any], repeat["collection"]), - surface_identifier=surface_identifier, - target_kind=target_kind, scopes=scopes, error_type=error_type, ) @@ -431,8 +243,6 @@ def _extend_repetition_scopes( def _validate_optional_condition( node: dict[str, Any], *, - surface_identifier: str, - target_kind: str, scopes: frozenset[str], error_type: type[ValueError], ) -> None: @@ -440,8 +250,6 @@ def _validate_optional_condition( if isinstance(condition, dict): _validate_condition( condition, - surface_identifier=surface_identifier, - target_kind=target_kind, scopes=scopes, error_type=error_type, ) @@ -450,25 +258,18 @@ def _validate_optional_condition( 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: 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, ) @@ -476,15 +277,11 @@ def _validate_optional_fallback( def _validate_condition( condition: dict[str, Any], *, - surface_identifier: str, - target_kind: str, scopes: frozenset[str], error_type: type[ValueError], ) -> None: _validate_binding( cast(dict[str, Any], condition["binding"]), - surface_identifier=surface_identifier, - target_kind=target_kind, scopes=scopes, error_type=error_type, ) @@ -515,13 +312,15 @@ def _validate_condition( def _validate_binding( binding: dict[str, Any], *, - surface_identifier: str, - target_kind: str, scopes: frozenset[str], error_type: type[ValueError], ) -> None: source = cast(str, binding["sourceIdentifier"]) scope = cast(str, binding["scope"]) + if source == contract.RAW_OPERATION_REQUEST_BINDING: + raise error_type( + "presentation: raw operation request values cannot be bound" + ) if source == contract.REPETITION_ITEM_BINDING: if not scope or scope not in scopes: raise error_type( @@ -532,16 +331,6 @@ def _validate_binding( 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( - "presentation: binding source is unavailable on this surface" - ) def _namespace(identifier: str) -> str: diff --git a/src/stateforge_protocol/sfp/manifest/v1/contract.py b/src/stateforge_protocol/sfp/manifest/v1/contract.py index ccf9a67..b858d5b 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/contract.py +++ b/src/stateforge_protocol/sfp/manifest/v1/contract.py @@ -1,6 +1,5 @@ """Expose the normative SFP Provider Manifest v1 wire contract.""" -from dataclasses import dataclass from typing import Final from stateforge_protocol.sfp import primitives @@ -59,254 +58,11 @@ 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" -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, - } -) -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" -OPERATION_REQUEST_SCHEMA_BINDING: Final = ( - "stateforge.binding/operation.request.schema@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 = ( - "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_PUBLIC_VALUE_BINDING, - } - ), - OPERATION_RUN_SURFACE: frozenset( - { - PROVIDER_MANIFEST_BINDING, - OPERATION_REQUEST_PUBLIC_VALUE_BINDING, - OPERATION_RUN_BINDING, - } - ), - OPERATION_RESULT_SURFACE: frozenset( - { - PROVIDER_MANIFEST_BINDING, - OPERATION_REQUEST_PUBLIC_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, - } - ), -} - - -@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"}), +RAW_OPERATION_REQUEST_BINDING: Final = ( + "stateforge.binding/operation.request.value@1" ) -_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/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi index ee2d24a..6f4a2a6 100644 --- a/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi +++ b/src/stateforge_protocol/sfp/manifest/v1/manifest_pb2.pyi @@ -631,7 +631,8 @@ Global___PresentationSurface: _TypeAlias = PresentationSurface # noqa: Y015 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. + by SFP. Component and surface applicability are decided by the Control Plane. + Fallback trees are optional and are interpreted by the Control Plane. """ DESCRIPTOR: _descriptor.Descriptor diff --git a/tests/test_documentation_system.py b/tests/test_documentation_system.py index 44d620b..e348d92 100644 --- a/tests/test_documentation_system.py +++ b/tests/test_documentation_system.py @@ -87,23 +87,18 @@ def test_provider_presentation_guide_maps_components_to_surfaces() -> None: "`PresentationAsset`", ): assert contract_type in page - for surface in ( - "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.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 "input.secret" in page - assert "Portable core structure" in page - assert "No second SFP presentation RPC" in page + assert "operation request binding identifier is forbidden by SFP" in page + assert "Control Plane owns the catalog and renderer registry" in page + assert "surface identifiers and their applicability" in page + assert "SFP accepts any well-formed surface identifier" in page + assert ( + "The catalog's 30 component identifiers are " + "maintained by the Control Plane" in page + ) + assert "SFP introduces" in page + assert "no separate presentation RPC" in page assert "SF-AOP" in page diff --git a/tests/test_manifest_contract.py b/tests/test_manifest_contract.py index af1341c..0621d3a 100644 --- a/tests/test_manifest_contract.py +++ b/tests/test_manifest_contract.py @@ -29,6 +29,8 @@ ) _FIXTURES = Path(__file__).parent / "fixtures" / "manifest" +PROVIDER_OVERVIEW_SURFACE = "stateforge.ui/surface.provider.overview@1" +OPERATION_RESULT_SURFACE = "stateforge.ui/surface.operation.result@1" _SCHEMA = json.loads( files("stateforge_protocol.sfp.manifest.v1") .joinpath("manifest.schema.json") @@ -396,7 +398,7 @@ def test_presentation_changes_do_not_change_business_fingerprints() -> None: manifest_pb2.GetManifestResponse(), ) manifest_response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root.properties.update({"gap": "changed"}) assert ( @@ -430,9 +432,7 @@ def test_presentation_protojson_rejects_executable_or_semantic_fields( )["presentation"] if target == "component": operation = next(iter(document["operations"].values())) - selected = operation["surfaces"][contract.OPERATION_RESULT_SURFACE][ - "root" - ] + selected = operation["surfaces"][OPERATION_RESULT_SURFACE]["root"] elif target == "renderer": selected = next(iter(document["rendererRequirements"].values())) else: diff --git a/tests/test_manifest_validation.py b/tests/test_manifest_validation.py index ee1fadb..8b97cf8 100644 --- a/tests/test_manifest_validation.py +++ b/tests/test_manifest_validation.py @@ -31,6 +31,11 @@ ) _FIXTURES = Path(__file__).parent / "fixtures" / "manifest" +PROVIDER_OVERVIEW_SURFACE = "stateforge.ui/surface.provider.overview@1" +OPERATION_REQUEST_SURFACE = "stateforge.ui/surface.operation.request@1" +OPERATION_RESULT_SURFACE = "stateforge.ui/surface.operation.result@1" +TRIGGER_EVENT_SURFACE = "stateforge.ui/surface.trigger.event@1" +PROVIDER_RUNTIME_BINDING = "stateforge.binding/provider.runtime@1" _GOLDEN_REVISION = ( "sha256:6bfdf3aedc2d4e45d77d4787cc0e744a488208b2510d81788291f51d24a623e8" ) @@ -160,7 +165,7 @@ def _provider_image( response: manifest_pb2.GetManifestResponse, ) -> manifest_pb2.ComponentNode: return response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root.children[0] @@ -256,18 +261,20 @@ def test_empty_presentation_overlay_is_valid() -> None: } -def test_invalid_presentation_falls_back_without_rejecting_manifest() -> None: +def test_renderer_specific_binding_mismatch_is_not_a_protocol_error() -> None: response = _presentation_response() - _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + _operation_root(response, OPERATION_REQUEST_SURFACE).bindings[ "schema" - ].source_identifier = contract.PROVIDER_RUNTIME_BINDING + ].source_identifier = PROVIDER_RUNTIME_BINDING _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.presentation_status is PresentationValidationStatus.ACCEPTED + ) + assert exchange.presentation_document is not None + assert exchange.presentation_key is not None assert exchange.manifest_document == validate_manifest_response(response) @@ -328,7 +335,7 @@ def test_presentation_revision_is_isolated_and_bound_to_manifest() -> None: original_presentation_revision = response.presentation_revision response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root.properties.update({"gap": "compact"}) _refresh_presentation_revision(response) @@ -441,236 +448,123 @@ def test_targets_cannot_name_undeclared_capabilities(collection: str) -> None: _validate_presentation(response) -def test_surface_must_belong_to_its_target_kind() -> None: +def test_surface_applicability_is_owned_by_the_control_plane() -> None: response = _presentation_response() target = response.presentation.provider - target.surfaces[contract.OPERATION_REQUEST_SURFACE].CopyFrom( - target.surfaces[contract.PROVIDER_OVERVIEW_SURFACE] + target.surfaces["example.ui/surface.operation.request@1"].CopyFrom( + target.surfaces[PROVIDER_OVERVIEW_SURFACE] ) - with pytest.raises(ManifestValidationError, match="provider targets"): - _validate_presentation(response) + _validate_presentation(response) -def test_surface_binding_source_must_be_available() -> None: +def test_binding_source_applicability_is_owned_by_the_control_plane() -> None: response = _presentation_response() - _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + _operation_root(response, OPERATION_REQUEST_SURFACE).bindings[ "schema" - ].source_identifier = contract.OPERATION_RESULT_VALUE_BINDING + ].source_identifier = "example.control/operation.private_context@1" - with pytest.raises(ManifestValidationError, match="unavailable"): - _validate_presentation(response) + _validate_presentation(response) -def test_raw_operation_request_values_are_not_presentation_sources() -> None: +def test_raw_operation_request_values_remain_forbidden() -> None: response = _presentation_response() - result = _operation_root( - response, contract.OPERATION_RESULT_SURFACE - ).fallback - result.bindings[ + request = _operation_root(response, OPERATION_REQUEST_SURFACE) + request.bindings[ "secret" - ].source_identifier = "stateforge.binding/operation.request.value@1" - result.bindings["secret"].pointer = "/token" + ].source_identifier = contract.RAW_OPERATION_REQUEST_BINDING + request.bindings["secret"].pointer = "/token" - with pytest.raises(ManifestValidationError, match="unavailable"): + with pytest.raises(ManifestValidationError, match="raw operation request"): _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: +def test_component_catalog_is_not_a_protocol_allowlist() -> None: response = _presentation_response() - response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE - ].root.component_identifier = "stateforge.ui/layout.unknown@1" + node = response.presentation.provider.surfaces[ + PROVIDER_OVERVIEW_SURFACE + ].root + node.component_identifier = "stateforge.ui/layout.unknown@1" + node.properties.update({"catalogOwned": True}) + node.bindings[ + "catalog_defined_slot" + ].source_identifier = "example.control/provider.summary@1" - with pytest.raises(ManifestValidationError, match="unknown core"): - _validate_presentation(response) + _validate_presentation(response) -def test_core_action_is_rejected_outside_its_operation_surface() -> None: +def test_component_applicability_is_owned_by_the_control_plane() -> None: response = _presentation_response() root = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root root.component_identifier = "stateforge.ui/action.operation_submit@1" - with pytest.raises(ManifestValidationError, match="unavailable"): - _validate_presentation(response) + _validate_presentation(response) -def test_core_leaf_component_rejects_children() -> None: +def test_component_child_contract_is_owned_by_the_control_plane() -> None: response = _presentation_response() image = _provider_image(response) child = image.children.add( - component_identifier="stateforge.ui/content.text@1" + component_identifier="example.vendor/content.caption@1" ) child.properties.CopyFrom(struct_pb2.Struct()) - with pytest.raises(ManifestValidationError, match="child contract"): - _validate_presentation(response) + _validate_presentation(response) -def test_core_component_requires_its_binding_slots() -> None: +def test_component_binding_slots_are_owned_by_the_control_plane() -> None: response = _presentation_response() event = next(iter(response.presentation.triggers.values())) - event.surfaces[contract.TRIGGER_EVENT_SURFACE].root.ClearField("bindings") + event.surfaces[TRIGGER_EVENT_SURFACE].root.ClearField("bindings") - with pytest.raises(ManifestValidationError, match="required binding"): - _validate_presentation(response) + _validate_presentation(response) -def test_core_component_rejects_unknown_binding_slots() -> None: +def test_component_asset_slots_are_owned_by_the_control_plane() -> 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["example.git"] + image.asset_bindings["catalog_defined_slot"] = image.asset_bindings[ + "source" + ] + del image.asset_bindings["source"] - with pytest.raises(ManifestValidationError, match="renderer requirement"): - _validate_presentation(response) + _validate_presentation(response) -def test_custom_component_requires_core_fallback() -> None: +def test_custom_fallback_is_not_limited_to_protocol_core_components() -> None: response = _presentation_response() - _operation_root(response, contract.OPERATION_RESULT_SURFACE).ClearField( - "fallback" + custom = _operation_root(response, OPERATION_RESULT_SURFACE) + custom.fallback.CopyFrom( + manifest_pb2.ComponentNode( + component_identifier="example.vendor/fallback.tree@1", + properties=struct_pb2.Struct(), + ) ) - - with pytest.raises(ManifestValidationError, match="core fallback"): - _validate_presentation(response) - - -def test_custom_component_fallback_cannot_require_an_extension() -> None: - response = _presentation_response() - _operation_root( - response, contract.OPERATION_RESULT_SURFACE - ).fallback.component_identifier = "example.git/data.commit_graph@1" - - with pytest.raises(ManifestValidationError, match="core components"): - _validate_presentation(response) - - -def test_renderer_requirements_cannot_be_unreferenced() -> None: - response = _presentation_response() - response.presentation.renderer_requirements["example.widget"].CopyFrom( - response.presentation.renderer_requirements["example.git"] + custom.fallback.fallback.CopyFrom( + manifest_pb2.ComponentNode( + component_identifier="stateforge.ui/future.fallback@2", + properties=struct_pb2.Struct(), + ) ) - requirement = response.presentation.renderer_requirements["example.widget"] - requirement.extension_identifier = "example.widget/renderer@1" - with pytest.raises(ManifestValidationError, match="exactly match"): - _validate_presentation(response) - - -def test_renderer_extension_must_share_component_namespace() -> None: - response = _presentation_response() - response.presentation.renderer_requirements[ - "example.git" - ].extension_identifier = "example.widget/renderer@1" - - with pytest.raises(ManifestValidationError, match="namespace"): - _validate_presentation(response) + _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: +def test_renderer_requirements_are_not_a_component_registry() -> None: response = _presentation_response() - _operation_root( - response, contract.OPERATION_RESULT_SURFACE - ).component_identifier = identifier + del response.presentation.renderer_requirements["example.git"] + response.presentation.renderer_requirements["example.unused"].CopyFrom( + manifest_pb2.RendererRequirement( + extension_identifier="example.unused/renderer@1", + extension_version="1.0.0", + renderer_api_version="1.0.0", + artifact_digest="sha256:" + "a" * 64, + ) + ) - with pytest.raises(ManifestValidationError, match="StateForge-owned"): - _validate_presentation(response) + _validate_presentation(response) def test_renderer_requirements_cannot_claim_stateforge_namespaces() -> None: @@ -689,7 +583,7 @@ def test_renderer_requirements_cannot_claim_stateforge_namespaces() -> None: def test_repetition_scope_is_available_to_component_bindings() -> None: response = _presentation_response() root = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root repeated = root.children.add( component_identifier="stateforge.ui/data.table@1" @@ -697,7 +591,7 @@ def test_repetition_scope_is_available_to_component_bindings() -> None: repeated.properties.update({"title": "Runtime items"}) repeated.repeat.collection.CopyFrom( manifest_pb2.DataBinding( - source_identifier=contract.PROVIDER_RUNTIME_BINDING, + source_identifier=PROVIDER_RUNTIME_BINDING, pointer="/items", ) ) @@ -717,7 +611,7 @@ def test_repetition_scope_is_available_to_component_bindings() -> None: def test_repetition_item_binding_requires_an_active_scope() -> None: response = _presentation_response() root = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root root.bindings["item"].CopyFrom( manifest_pb2.DataBinding( @@ -732,7 +626,7 @@ def test_repetition_item_binding_requires_an_active_scope() -> None: def test_non_repetition_binding_cannot_claim_a_scope() -> None: response = _presentation_response() - _operation_root(response, contract.OPERATION_REQUEST_SURFACE).bindings[ + _operation_root(response, OPERATION_REQUEST_SURFACE).bindings[ "schema" ].scope = "row" @@ -762,11 +656,11 @@ def test_condition_value_presence_matches_operator( ) -> None: response = _presentation_response() root = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root root.condition.binding.CopyFrom( manifest_pb2.DataBinding( - source_identifier=contract.PROVIDER_RUNTIME_BINDING, + source_identifier=PROVIDER_RUNTIME_BINDING, pointer="/available", ) ) @@ -781,7 +675,7 @@ def test_condition_value_presence_matches_operator( def test_component_properties_have_an_independent_byte_limit() -> None: response = _presentation_response() response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root.properties.update( {"content": "x" * contract.MAX_COMPONENT_PROPERTIES_BYTES} ) @@ -793,7 +687,7 @@ def test_component_properties_have_an_independent_byte_limit() -> None: def test_component_tree_depth_is_bounded() -> None: response = _presentation_response() node = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root for depth in range(contract.MAX_PRESENTATION_COMPONENT_DEPTH): node = node.children.add( @@ -894,7 +788,7 @@ def test_aggregate_asset_size_limit_is_enforced() -> None: ) references.append(digest) root = response.presentation.provider.surfaces[ - contract.PROVIDER_OVERVIEW_SURFACE + PROVIDER_OVERVIEW_SURFACE ].root root.ClearField("children") for index, digest in enumerate(references):