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
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ This repository contains authoritative Protocol Buffer sources and generated
language contracts. It contains no Agent client behavior, Provider server
runtime, third-party integration, BackupEngine, or Control Plane logic.

Operations are namespaced string identifiers rather than a closed enum. Backup
and disaster recovery are predefined compliance profiles constructed on the
generic operation model. Contracts must leave room for custom operations.
Operations are namespaced string identifiers rather than a closed enum.
Profiles and Contracts are managed by the Control Plane using concrete
operation and trigger schemas. SFP carries no Provider-owned Profile claims.

Edit `.proto` sources first. Never hand-edit generated `_pb2.py`, `_pb2.pyi`,
`_pb2_grpc.py`, or `_pb2_grpc.pyi` files. Regenerate them with the checked-in
Expand Down
2 changes: 1 addition & 1 deletion docs/v0.1.0/procedures/capability-assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ payload.
"providerInstanceId": "550e8400-e29b-41d4-a716-446655440000",
"endpointGeneration": "4",
"sessionId": "session-3d19b6d2-4b7b-4f4a-9c9a-2f3f4f0c9a1b (2)",
"manifestRevision": "sha256:dd58cd0518f631e370a095e6ba0c97476b028c8c65fac1f4b8da28d130c94cb7",
"manifestRevision": "sha256:4ad60e2cc41a8e180190739cf07acdd511d8236aedf585820897fdbd61d404c9",
"assessmentId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8 (3)",
"assessmentTimestamp": "2026-09-16T07:30:00Z",
"findings": [
Expand Down
36 changes: 13 additions & 23 deletions docs/v0.1.0/procedures/operation-admission.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ scenario: first-admission

Agent->>Service: StartOperation(request)
Service->>Service: Validate structure and live fences
Service->>Service: Validate declaration, roles, and payload
Service->>Service: Validate declaration and payload
Service->>Service: Fingerprint immutable invocation
Service->>Registry: Look up operation_id

Expand Down Expand Up @@ -189,11 +189,7 @@ invocation from fields needed to validate the current call.
},
"executionDeadline": "2026-09-20T12:00:00Z",
"contract": {
"manifestRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa (4)",
"requiredImplementationRoles": [
"stateforge.operation.v1.safe",
"stateforge.operation.v1.audited"
]
"manifestRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa (4)"
},
"executionContext": {
"authority": "policy-run-123",
Expand Down Expand Up @@ -236,15 +232,13 @@ fingerprint.
| `payload` | Required JSON object validated against the selected operation's manifest `input_schema` before admission. An operation that acts on a resource identifies it here, using its own schema; an operation with no resource needs no placeholder. Provider-level `configuration_schema` does not validate operation input. JSON Schema defaults are annotations and are not silently inserted. |
| `execution_deadline` | Absolute Agent-selected deadline for the business attempt. It is distinct from the gRPC call deadline and is immutable. |
| `contract.manifest_revision` | Exact accepted manifest revision. It pins the operation declaration and its input/result schemas. |
| `contract.required_implementation_roles` | Zero or more distinct profile claims from the selected operation's manifest `implements` list that this invocation relies on. This may be a subset of all declared claims. Empty means this invocation requires no profile claim. These are not permissions. |
| `execution_context` | Required bounded JSON object containing already-approved, non-secret execution metadata. SFP transports context; it does not make the policy or authorization decision. |

### Comparison and safety rules

| Concern | Rule |
| --- | --- |
| JSON values | Object-member order is irrelevant. Adding, removing, or changing a value changes the invocation. Schema defaults are not inserted automatically. |
| Required roles | Roles form an unordered, duplicate-free set. Every requested role must appear in the operation declaration; membership is not authorization or proof of compliance. |
| Secrets | Values declared `writeOnly` must not appear in responses, errors, diagnostics, fixtures, or logs. |

The request fingerprint correlates retries. It is not authentication and must
Expand All @@ -258,8 +252,7 @@ invocation**. It is not a hash of the complete RPC request.
```mermaid
flowchart LR
A[OperationInvocation] --> B[ProtoJSON projection]
B --> C[Sort required roles only]
C --> D[RFC 8785 canonical JSON]
B --> D[RFC 8785 canonical JSON]
D --> E[SHA-256]
E --> F[sha256: lowercase hex]
```
Expand All @@ -269,18 +262,16 @@ flowchart LR
| Operation ID and operation identifier | Current Provider, generation, and session binding |
| Complete payload and execution context | Admission mode |
| Execution deadline | gRPC call deadline |
| Manifest revision and required roles | Transport metadata |
| Manifest revision | Transport metadata |

The Provider computes the fingerprint before looking up `operation_id`:

1. Parse and structurally validate `StartOperationRequest`.
2. Project only `OperationInvocation` to ProtoJSON using lowerCamelCase field
names and emitting all non-presence defaults.
3. Sort `contract.requiredImplementationRoles` lexicographically by Unicode
code point. Do not sort any other array.
4. Canonicalize the projected JSON with RFC 8785 (JCS).
5. Compute SHA-256 over the canonical UTF-8 bytes.
6. Encode the fingerprint as `sha256:` plus 64 lowercase hexadecimal digits.
3. Canonicalize the projected JSON with RFC 8785 (JCS).
4. Compute SHA-256 over the canonical UTF-8 bytes.
5. Encode the fingerprint as `sha256:` plus 64 lowercase hexadecimal digits.

A reconnect or switch to resolve-only therefore preserves the fingerprint.
Changing any immutable operation field while retaining the same operation ID
Expand Down Expand Up @@ -314,7 +305,7 @@ silently redispatch work:
```mermaid
flowchart TD
A[Bound and decode request] --> B[Validate structure and active session]
B --> C[Validate manifest, operation, roles, and payload]
B --> C[Validate manifest, operation, and payload]
C --> D[Compute invocation fingerprint]
D --> E{Retained state for operation ID?}
E -->|Matching record| F[RESOLVED_EXISTING]
Expand All @@ -333,7 +324,7 @@ flowchart TD
`admission_mode`.
3. Validate the active handshake session, Provider identity, and generation.
4. Match `contract.manifest_revision` to the Agent-accepted active manifest.
Confirm the operation is declared, every required role is present, and the
Confirm the operation is declared and the
complete payload satisfies the selected operation's accepted input schema.
5. Compute the canonical invocation fingerprint.
6. Look up `operation_id` before testing a new-admission deadline or capacity:
Expand All @@ -356,7 +347,7 @@ has since passed. The lifecycle contract determines what the operation did,
not a new admission attempt.

Capability assessment is point-in-time evidence, not authorization. Admission
revalidates the current session, manifest, declaration, roles, schemas,
revalidates the current session, manifest, declaration, schemas,
readiness, and any current prerequisites instead of trusting an earlier
Capability Assessment result.

Expand All @@ -383,7 +374,7 @@ invalid.
"disposition": "ADMISSION_DISPOSITION_ACCEPTED_NEW (1)",
"record": {
"operationId": "22222222-2222-4222-8222-222222222222",
"requestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df (2)",
"requestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df (2)",
"admittedAt": "2026-09-19T12:00:00Z",
"recordExpiresAt": "2026-09-20T12:00:00Z",
"admittedEndpointGeneration": "42"
Expand All @@ -406,7 +397,7 @@ invalid.
"disposition": "ADMISSION_DISPOSITION_RESOLVED_EXISTING (2)",
"record": {
"operationId": "22222222-2222-4222-8222-222222222222",
"requestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df",
"requestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df",
"admittedAt": "2026-09-19T12:00:00Z",
"recordExpiresAt": "2026-09-20T12:00:00Z",
"admittedEndpointGeneration": "42 (3)"
Expand Down Expand Up @@ -447,7 +438,7 @@ delay, and sanitized explanation.
| --- | --- | --- | --- |
| Malformed fields, invalid identifiers, invalid bounds, or schema-invalid payload | `INVALID_ARGUMENT` | `INVALID_OPERATION_REQUEST` | Correct the request. Reusing the same ID is permitted only because the Provider explicitly rejected before admission. |
| Operation absent from the accepted manifest | `UNIMPLEMENTED` | `OPERATION_NOT_DECLARED` | Refresh declarations or choose declared work; do not reinterpret the identifier. |
| Selected operation schema or required profile role is incompatible | `FAILED_PRECONDITION` | `OPERATION_INCOMPATIBLE` | Obtain a compatible declaration or profile and use a new operation ID if semantic content changes. |
| Selected operation schema is incompatible | `FAILED_PRECONDITION` | `OPERATION_INCOMPATIBLE` | Obtain a compatible declaration and use a new operation ID if semantic content changes. |
| Session, generation, manifest, health, or current prerequisite is stale | `FAILED_PRECONDITION` | `OPERATION_PRECONDITION_FAILED` | Re-establish prerequisites. Reuse the ID only with identical invocation content. |
| Admission capacity temporarily exhausted | `RESOURCE_EXHAUSTED` | `PROVIDER_CAPACITY_EXHAUSTED` | Retry the identical request with bounded backoff; honor `retry_after` when present. |
| Whole Provider service temporarily unavailable | `UNAVAILABLE` | `PROVIDER_UNAVAILABLE` | Reconnect and revalidate before a bounded retry. |
Expand Down Expand Up @@ -522,7 +513,6 @@ generation zero, and `UNSPECIFIED` enums are invalid.
| Entries per JSON object or array | 256 |
| JSON property name | 128 Unicode code points |
| JSON string value | 65,536 Unicode code points |
| Required implementation roles | 16 unique entries |
| Versioned identifier or role identifier | 255 Unicode code points |
| Session ID | 255 Unicode code points |
| Sanitized error explanation | 1,024 Unicode code points |
Expand Down
4 changes: 2 additions & 2 deletions docs/v0.1.0/procedures/operation-admission.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ scenarios:

- id: validate-request
title: Validate the current contract
detail: The Admission Service validates message shape, the active session, the accepted manifest revision, the operation declaration, roles, payload schema, and current prerequisites.
detail: The Admission Service validates message shape, the active session, the accepted manifest revision, the operation declaration, payload schema, and current prerequisites.
phase: Validation
active: [admission]
fields: [active session, manifest revision, input schema, prerequisites]
Expand All @@ -96,7 +96,7 @@ scenarios:

- id: compute-fingerprint
title: Fingerprint the immutable invocation
detail: The Admission Service projects only OperationInvocation, sorts required implementation roles, canonicalizes it with RFC 8785, and hashes the bytes with SHA-256.
detail: The Admission Service projects only OperationInvocation, canonicalizes it with RFC 8785, and hashes the bytes with SHA-256.
phase: Canonical identity
active: [admission]
fields: [OperationInvocation, RFC 8785, SHA-256]
Expand Down
8 changes: 4 additions & 4 deletions docs/v0.1.0/procedures/progress-results-cancellation.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ carries the last validated sequence.
"expectedSessionId": "session-admission-42"
},
"operationId": "22222222-2222-4222-8222-222222222222 (2)",
"expectedRequestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df (3)",
"expectedRequestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df (3)",
"afterSequence": "0 (4)"
}
```
Expand All @@ -202,7 +202,7 @@ carries the last validated sequence.
"expectedSessionId": "session-admission-42"
},
"operationId": "22222222-2222-4222-8222-222222222222",
"expectedRequestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df"
"expectedRequestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df"
}
```

Expand Down Expand Up @@ -293,7 +293,7 @@ current state and any terminal outcome.
"snapshot": {
"admissionRecord": {
"operationId": "22222222-2222-4222-8222-222222222222",
"requestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df",
"requestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df",
"admittedAt": "2026-09-19T12:00:00Z",
"recordExpiresAt": "2026-09-20T12:00:00Z",
"admittedEndpointGeneration": "42"
Expand Down Expand Up @@ -390,7 +390,7 @@ All four dispositions are successful gRPC responses.
"snapshot": {
"admissionRecord": {
"operationId": "22222222-2222-4222-8222-222222222222",
"requestFingerprint": "sha256:9d52f77a7f678fda81dcee97df7b3bc5e4877ee570285f6aa5741b83d4c731df",
"requestFingerprint": "sha256:6f555da004a09c3aba919883a19ede8de6cd424d59e1696954fb10aec2f416df",
"admittedAt": "2026-09-19T12:00:00Z",
"recordExpiresAt": "2026-09-20T12:00:00Z",
"admittedEndpointGeneration": "42"
Expand Down
Loading
Loading