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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 13 additions & 30 deletions .claude/PROVIDER_AUTHORING_VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,42 +187,25 @@ The runtime owns deadlines, cancellation, session and manifest fencing,
readiness checks, deterministic result ordering, and final response
validation.

## Backup and disaster-recovery compliance
## Profile matching ownership

Backup and disaster recovery are predefined compliance profiles over generic
operations, not special transport commands. Compliance is always explicit.
Providers expose concrete operations and triggers with schemas derived from
their typed models. They do not declare Profile claims or maintain a Profile
registry. The Control Plane owns Profiles, schema-based compatibility, field
mappings, Contracts, and fulfillment once schemas arrive through SF-AOP.
Compatibility depends on types and constraints rather than identical property
names. Matching names can map automatically, differing names can receive
suggested mappings, extra fields do not automatically disqualify compatibility,
and partial matches remain discoverable.

```python
@operation(
"git.create_backup_reference",
implements="stateforge.backup.v1.prepare",
)
async def create_backup_reference(...):
...
```

```python
@operation(
"git.reconstruct_repository",
implements="stateforge.disaster_recovery.v1.reconstruct",
)
async def reconstruct_repository(...):
...
```

The runtime validates the claimed profile and publishes it in the Provider
manifest. It must never infer compliance from a method name.

BackupEngine remains an Agent-side tool. A compliant Provider prepares staged
data or returns a supported Provider reference. During disaster recovery, the
Agent restores stored data into an Agent-managed staging workspace and asks
the Provider to reconstruct and verify the third-party component. The Provider
does not receive a generic restore command.
The Provider runtime validates actual inputs, successful results, and trigger
events against the declared concrete schemas. Schema defaults remain
annotations and do not materialize missing request values.

## Manifest ownership

Provider authors declare metadata, operations, trigger types, model schemas,
static or dynamically checked runtime requirements, and compliance roles
static or dynamically checked runtime requirements
through the public Python API. They do not construct the wire manifest
manually. Operation-to-check associations stay private to the Provider
runtime; schema-1 manifests publish only the existing static requirement
Expand Down
15 changes: 0 additions & 15 deletions .github/actions/scenarios/operation/admission/verify.py
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,6 @@ async def ready(self) -> RequirementCheckResult:
@operation(
"stateforge.test/execute@1",
requires=("runtime.ready",),
implements=("stateforge.test.v1.audited",),
)
async def execute(
self,
Expand Down Expand Up @@ -149,7 +148,6 @@ def _request(
value: int = 1,
secret: str | None = None,
generation: int | None = None,
roles: tuple[str, ...] = ("stateforge.test.v1.audited",),
payload_fields: dict[str, str | int | bool | None] | None = None,
mode: operation_admission_pb2.AdmissionMode.ValueType = (
operation_admission_pb2.ADMISSION_MODE_ADMIT_OR_RESOLVE
Expand Down Expand Up @@ -189,7 +187,6 @@ def _request(
),
contract=operation_admission_pb2.OperationContractContext(
manifest_revision=manifest.manifest_revision,
required_implementation_roles=roles,
),
execution_context=execution_context,
),
Expand Down Expand Up @@ -703,17 +700,6 @@ async def _run( # noqa: PLR0912, PLR0915
grpc.StatusCode.FAILED_PRECONDITION,
operation_admission_pb2.ADMISSION_ERROR_REASON_OPERATION_PRECONDITION_FAILED,
)
role_status = await _expect_error(
admission,
_request(
handshake,
manifest,
operation_id=str(uuid4()),
roles=("stateforge.test.v1.missing",),
),
grpc.StatusCode.FAILED_PRECONDITION,
operation_admission_pb2.ADMISSION_ERROR_REASON_OPERATION_INCOMPATIBLE,
)
provider.requirement_satisfied = False
requirement_status = await _expect_error(
admission,
Expand Down Expand Up @@ -814,7 +800,6 @@ async def _run( # noqa: PLR0912, PLR0915
"resolved_existing": len(responses) - accepted_new,
"author_dispatches": provider.dispatches,
"stale_fence_status": stale_status,
"missing_role_status": role_status,
"requirement_status": requirement_status,
"idempotency_conflict_status": conflict_status,
"immutable_context": True,
Expand Down
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,9 +90,9 @@ construction, dispatch, and error translation belong to the runtime. Do not
make authors pass or manipulate those internal values through the normal
public API.

Backup and disaster-recovery support remains an explicit compliance claim over
generic decorated operations. Never infer compliance from method names and
never move BackupEngine behavior into a Provider.
Provider authors expose concrete operation and trigger schemas. The Control
Plane owns schema-based Profile matching and fulfillment; Providers publish
no Profile claims. Never infer compliance from method names.

## Provider runtime invariants

Expand Down
5 changes: 2 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,15 @@ if __name__ == "__main__":
```

See [Manifest declarations](manifest-authoring.md) for typed operation models,
triggers, configuration schemas, requirements, and explicit compliance roles.
triggers, configuration schemas, and runtime requirements.
See [Health and readiness](health-reporting.md) for fail-closed lifecycle
states and event-driven health updates.
See [Trigger publication](trigger-publication.md) for continuous decorated
sources, callback-driven events, acknowledgement receipts, and retry behavior.
An application that already owns an event loop calls
`await GitProvider().serve()` instead. See
`.claude/PROVIDER_AUTHORING_VISION.md` for the complete intended author
experience, including operation execution and compliance profiles, which land
incrementally as their SFP procedures do.
experience and the Control Plane’s ownership of Profile matching.

See [Process lifecycle and exit behavior](process-lifecycle.md) for the
standard `run()` process contract, graceful signal handling, embedded
Expand Down
38 changes: 16 additions & 22 deletions docs/manifest-authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ at module scope or declared on the Provider class.
Operation and trigger identifiers use `namespace/name@major`, with at
least two lowercase dotted namespace segments and a positive major version.
An incompatible input/result contract requires a new identifier version.
Use tuples for platforms, requirements, triggers, and roles.
Use tuples for platforms, requirements, and triggers.
Plain `runtime_requirements` declarations are descriptive. Requirements
declared by `@requirement_check` add an author-owned, dynamic inspection while
publishing the same static metadata through the schema-1
Expand Down Expand Up @@ -178,29 +178,23 @@ duplicated, metadata exceeds Protocol bounds, the method is not async with an
exact `(self)` signature and result annotation, or an operation has a missing,
duplicate, or oversized requirement reference set.

## Compliance claims
## Profile matching ownership

Supply roles explicitly on the decorated operation:
Providers publish concrete operation input/result schemas and trigger payload
schemas derived from their typed models. Operation declarations contain only
`inputSchema` and `resultSchema`; Providers declare no Profile claims.

```python
@operation(
"example.reference/prepare@1",
implements=("stateforge.backup.v1.prepare",),
)
async def prepare(self, request: PrepareInput) -> PrepareResult: ...
```

This illustrates claim syntax: `PrepareInput` and `PrepareResult` must come
from the exact versioned profile when that profile lands. P1 transports and
structurally validates role claims; it does not define the later P6/P7 profile
schemas. R1 consequently cannot certify backup or DR compliance. Unknown
dotted roles are transported as claims too. A consumer must validate known
roles against the matching profile before using them as compliance evidence.
The Control Plane will assess Profile compatibility from these schemas once
SF-AOP supplies them. Matching uses types and constraints, without requiring
property names to equal Profile names. Matching names can be mapped
automatically; differing names can receive suggested field mappings. Extra
inputs or outputs do not automatically disqualify an operation when the
required Profile types are present, and partial matches remain discoverable.
Providers do not implement matching, mappings, or Contract fulfillment.

Names, method bodies, docstrings, and schema payloads never imply compliance.
Every operation has only input schema, result schema, and `implements` roles.
There is no separate backup source mode, BackupEngine configuration, or
storage routing declaration.
Schema defaults remain annotations. They do not materialize omitted request
values or bypass requiredness and validation of actual inputs, successful
results, or trigger events.

## Schema safety and limits

Expand All @@ -222,7 +216,7 @@ numbers, and integers outside RFC 8785's exact integer range fail validation.

P1 limits are 8 KiB per wire request, 2 MiB per wire response, 1 MiB per
canonical revision preimage, 1,024 entries per operation/trigger/requirement
map, 256 platform pairs, 64 roles per operation, and 64 containers of embedded
map, 256 platform pairs, and 64 containers of embedded
nesting. This runtime additionally caps JSON at 65,536
nodes per checked document, embedded schemas at 4,096 schema nodes each, and
combined generated schema bytes at 1 MiB. It applies these bounds before
Expand Down
1 change: 0 additions & 1 deletion docs/operation-admission.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@ class ServiceProvider(Provider):
@operation(
"example.systemd/restart@1",
requires=("runtime.systemd.control",),
implements=("example.service.v1.restart",),
cancellable=True,
progress=OperationProgressPolicy.determinate(),
)
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/provider.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ evidence only: it neither executes nor authorizes an operation.

`Provider` also registers the private P4 Operation Admission service. The
runtime validates the exact endpoint, session, accepted manifest, operation
declaration, payload schema, requested implementation roles, current Health,
declaration, payload schema, current Health,
execution deadline, and fresh requirement-check results. It atomically records
the canonical request fingerprint before scheduling author code, so concurrent
identical retries dispatch exactly once and changed content is rejected.
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ environments = ["python_version == '3.13'"]


[tool.uv.sources]
stateforge-protocol = { git = "https://github.com/stateforge-org/stateforge-protocol.git", rev = "64514b35dabfe88d49aabfb63d756e98a97fe5dc" }
stateforge-protocol = { git = "https://github.com/stateforge-org/stateforge-protocol.git", rev = "0dab0576d884ae10f3bef0135b641168234b18b6" }


[tool.hatch.build.targets.wheel]
Expand Down
15 changes: 1 addition & 14 deletions src/stateforge_provider/_services/manifest/declaration.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@ class OperationDeclaration:
method_name: str
request_model: type[ProviderModel]
result_model: type[ProviderModel]
implements: tuple[str, ...]
requires: tuple[str, ...]
accepts_context: bool
cancellable: bool
Expand Down Expand Up @@ -100,7 +99,7 @@ def _sequence(owner: type, name: str, limit: int) -> tuple[Any, ...]:


# Keep discovery and its rejection rules adjacent.
def _operations( # noqa: PLR0912
def _operations(
owner: type,
limits: ProviderRuntimeLimits,
) -> tuple[dict[str, Any], tuple[OperationDeclaration, ...]]:
Expand Down Expand Up @@ -171,16 +170,6 @@ def _operations( # noqa: PLR0912
f"{path}: cancellation and progress policies require "
"OperationContext"
)
roles = metadata.implements
if (
not isinstance(roles, tuple)
or len(roles) > manifest_contract.MAX_PROFILE_CLAIMS_PER_OPERATION
):
raise ManifestError(f"{path}.implements: must be a bounded tuple")
for role in roles:
validate_structure(role, "dottedIdentifier", f"{path}.implements")
if len(set(roles)) != len(roles):
raise ManifestError(f"{path}.implements: duplicate role")
input_schema = _model_schema(
request_model,
f"{path}.input",
Expand All @@ -196,15 +185,13 @@ def _operations( # noqa: PLR0912
declarations[metadata.identifier] = {
"inputSchema": input_schema,
"resultSchema": result_schema,
"implements": sorted(roles),
}
runtime_declarations.append(
OperationDeclaration(
identifier=metadata.identifier,
method_name=method_name,
request_model=request_model,
result_model=result_model,
implements=tuple(sorted(roles)),
requires=metadata.requires,
accepts_context=accepts_context,
cancellable=metadata.cancellable,
Expand Down
18 changes: 0 additions & 18 deletions src/stateforge_provider/_services/operation_admission/service.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,6 @@ async def StartOperation( # noqa: N802, PLR0912
),
)
try:
self._validate_contract(invocation, operation)
payload = self._validate_payload(invocation, operation)
except AdmissionFailureError as failure:
await self._reject(context, failure)
Expand Down Expand Up @@ -277,23 +276,6 @@ async def _validate_fences(
)
return session

def _validate_contract(
self,
invocation: operation_admission_pb2.OperationInvocation,
operation: BoundOperation,
) -> None:
"""Validate requested profile claims against the accepted manifest."""
if any(
role not in operation.declaration.implements
for role in invocation.contract.required_implementation_roles
):
raise AdmissionFailureError(
grpc.StatusCode.FAILED_PRECONDITION,
operation_admission_pb2.ADMISSION_ERROR_REASON_OPERATION_INCOMPATIBLE,
"Operation requires an undeclared implementation role",
invocation.operation_id,
)

def _validate_payload(
self,
invocation: operation_admission_pb2.OperationInvocation,
Expand Down
7 changes: 0 additions & 7 deletions src/stateforge_provider/declarations.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,6 @@ class Trigger:
@dataclass(frozen=True, slots=True)
class _Operation:
identifier: str
implements: tuple[str, ...]
requires: tuple[str, ...]
cancellable: bool
progress: OperationProgressPolicy | None
Expand Down Expand Up @@ -106,7 +105,6 @@ def _effective_methods(
def operation(
identifier: str,
*,
implements: tuple[str, ...] = (),
requires: tuple[str, ...] = (),
cancellable: bool = False,
progress: OperationProgressPolicy | None = None,
Expand All @@ -116,10 +114,6 @@ def operation(
Annotate ``request`` and the return value with ProviderModel subclasses.
The runtime derives the manifest schemas from those annotations and invokes
the method only after canonical Operation Admission succeeds.
``implements`` contains versioned semantic/compliance profile claims. Each
claim says the operation conforms to that profile's required schemas and
behavior. Claims are not permissions or Control Plane contract identifiers
and are never inferred from a method or model name.
``requires`` contains stable IDs declared by :func:`requirement_check`.
The runtime evaluates each distinct check once per assessment or admission
attempt.
Expand All @@ -144,7 +138,6 @@ def decorate(handler: _Handler) -> _Handler:
"__stateforge_operation__",
_Operation(
identifier,
implements,
requires,
cancellable,
progress,
Expand Down
5 changes: 2 additions & 3 deletions tests/fixtures/manifest/response.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@
"type": "object",
"properties": {},
"additionalProperties": false
},
"implements": []
}
}
},
"runtimeRequirements": {
Expand Down Expand Up @@ -54,6 +53,6 @@
},
"triggers": {}
},
"manifestRevision": "sha256:6bfdf3aedc2d4e45d77d4787cc0e744a488208b2510d81788291f51d24a623e8",
"manifestRevision": "sha256:aa27f0fddaa13df211bd3e4e4e4230cdda42d9188d4b480d196c2e0de2d20cdb",
"sessionId": "manifest-session-A"
}
2 changes: 1 addition & 1 deletion tests/fixtures/manifest/revision-preimage.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"manifest":{"configurationSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"repository":{"type":"string"},"token":{"type":"string","writeOnly":true}},"required":["repository"],"type":"object"},"displayName":"Git Provider","implementationVersion":"1.0.0","operations":{"stateforge.git/reference.resolve@1":{"implements":[],"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{},"type":"object"},"resultSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{},"type":"object"}}},"platforms":[{"architecture":"x86_64","operatingSystem":"linux"}],"providerIdentity":"stateforge.git","runtimeRequirements":{"executable.git":{"description":"Git executable available to the Provider","versionConstraint":">=2.40"}},"triggers":{}},"manifestSchemaVersion":1,"providerInstanceId":"7f7db7d8-68b4-4f71-9769-065b5c4f941c"}
{"manifest":{"configurationSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{"repository":{"type":"string"},"token":{"type":"string","writeOnly":true}},"required":["repository"],"type":"object"},"displayName":"Git Provider","implementationVersion":"1.0.0","operations":{"stateforge.git/reference.resolve@1":{"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{},"type":"object"},"resultSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"properties":{},"type":"object"}}},"platforms":[{"architecture":"x86_64","operatingSystem":"linux"}],"providerIdentity":"stateforge.git","runtimeRequirements":{"executable.git":{"description":"Git executable available to the Provider","versionConstraint":">=2.40"}},"triggers":{}},"manifestSchemaVersion":1,"providerInstanceId":"7f7db7d8-68b4-4f71-9769-065b5c4f941c"}
1 change: 0 additions & 1 deletion tests/test_ci_automation.py
Original file line number Diff line number Diff line change
Expand Up @@ -382,7 +382,6 @@ def test_operation_admission_keeps_the_focused_protocol_peer() -> None:
"resolved_existing",
"author_dispatches",
"stale_fence_status",
"missing_role_status",
"requirement_status",
"idempotency_conflict_status",
"immutable_context",
Expand Down
Loading
Loading