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
10 changes: 0 additions & 10 deletions .github/actions/agent/assert-operation-admission/assert.py
Original file line number Diff line number Diff line change
Expand Up @@ -193,16 +193,6 @@ async def _require_local_rejections(
execution_deadline=datetime.now(UTC) + timedelta(minutes=5),
execution_context={"scenario": "installed-agent"},
),
OperationAdmissionRequest(
provider_instance_id=provider_instance_id,
operation_identifier=_OPERATION,
payload={"value": "rejected"},
execution_deadline=datetime.now(UTC) + timedelta(minutes=5),
execution_context={"scenario": "installed-agent"},
required_implementation_roles=(
"stateforge.test.profile.v1.not_declared",
),
),
)
for request in requests:
try:
Expand Down
14 changes: 14 additions & 0 deletions .github/actions/agent/assert-operation-lifecycle/assert.py
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,19 @@ async def _run( # noqa: C901, PLR0912, PLR0915 - scenario assertions
if failed.cleanup != "CLEANUP_STATE_INCOMPLETE":
raise AssertionError("Partial cleanup evidence was lost")

invalid_id = await _admit(manager, provider_id, "invalid-result")
seen_ids.append(invalid_id)
invalid = await _wait_status(
manager, provider_id, invalid_id, _TERMINAL
)
if (
invalid.state != "OPERATION_STATE_FAILED"
or invalid.failure_code != ("stateforge.operation.invalid_result")
):
raise AssertionError(
"Invalid typed result was accepted as success"
)

unsupported_id = await _admit(
manager, provider_id, "unsupported", identifier=_UNCANCELLABLE
)
Expand Down Expand Up @@ -284,6 +297,7 @@ async def _run( # noqa: C901, PLR0912, PLR0915 - scenario assertions
"typed_success_and_progress": True,
"requested_then_confirmed_cancelled": True,
"partial_failure_evidence": True,
"invalid_result_rejected": True,
"unsupported_and_already_terminal": True,
"no_redispatch": True,
}
Expand Down
5 changes: 3 additions & 2 deletions .github/actions/provider/create-fixture/fixtures/manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -209,11 +209,10 @@ async def inspect(self, request: FixtureInput) -> FixtureResult:

@operation(
"stateforge.test/snapshot@1",
implements=("stateforge.backup.v1.prepare",),
requires=("runtime.target.readable", "runtime.pending"),
)
async def snapshot(self, request: FixtureInput) -> FixtureResult:
"""Declare a profile-related operation with an unmet prerequisite."""
"""Declare an operation with an unmet runtime prerequisite."""
self._record("operation:snapshot")
return FixtureResult(value=request.value)

Expand Down Expand Up @@ -256,6 +255,8 @@ async def lifecycle(
explanation="Temporary fixture state was removed.",
)
)
elif request.value == "invalid-result":
return FixtureResult.model_construct(value=7)
elif request.value == "failure":
raise OperationFailedError(
code="stateforge.test.fixture_failure",
Expand Down
23 changes: 17 additions & 6 deletions docs/sfp-operation-admission.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ sequenceDiagram
participant P as Provider

C->>A: admit_operation(request)
A->>A: Check manifest, schema, profiles, and A3 evidence
A->>A: Check manifest, schema, and A3 evidence
A->>J: Persist immutable intent and fingerprint
J-->>A: Durable operation identity
A->>P: StartOperation(ADMIT_OR_RESOLVE)
Expand All @@ -39,18 +39,16 @@ sequenceDiagram
- the Provider installation identity;
- the manifest-declared operation identifier;
- the exact JSON payload and execution context;
- a finite execution deadline; and
- optional required implementation profiles.
- a finite execution deadline.

The Agent allocates the operation UUID, binds it to the immutable request
fingerprint, and persists that intent before contacting the Provider. The
caller never supplies or reuses an arbitrary operation UUID.

Admission requires the exact current Provider session to be available. The
operation must be declared in the accepted manifest, its payload must satisfy
the declared Draft 2020-12 schema, every requested implementation profile must
be claimed by the operation, and the current Capability Assessment must cover
the same operation and execution context with an admissible support state.
the declared Draft 2020-12 schema, and the current Capability Assessment must
cover the same operation and execution context with an admissible support state.

## Uncertain outcomes

Expand Down Expand Up @@ -111,3 +109,16 @@ The scenario proves that:
- accepted and unresolved records survive an Agent service restart; and
- journals and retained CI evidence contain identifiers and hashes, never
sensitive operation payload values.

## Profile ownership

Providers declare concrete operation input/result schemas and trigger payload
schemas. The Agent retains these declarations for execution validation and a
future SF-AOP handoff to the Control Plane; that connection is not implemented.
Profile definitions, automatic or assisted schema matching, field mappings,
partial-match discovery, and Contract fulfillment belong in the Control Plane.
Compatible types and constraints can support mappings even when field names
differ. Extra outputs and optional or supplied extra inputs do not by themselves
disqualify a capability; additional mandatory inputs must be supplied before
execution. A JSON Schema `default` annotation does not materialize a value.
Schema compatibility does not prove behavioral compliance.
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ environments = ["python_version == '3.13'"]


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


[tool.hatch.build.targets.wheel]
Expand Down
10 changes: 2 additions & 8 deletions src/stateforge_agent/_sfp/_services/manifest/declaration.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ class ManifestOperationDeclaration:

input_schema: Mapping[str, Any]
result_schema: Mapping[str, Any]
implements: frozenset[str]


@dataclass(frozen=True, slots=True)
Expand Down Expand Up @@ -91,18 +90,13 @@ def operation_declarations(
raise RuntimeError("Validated manifest cache entry is corrupt")
input_schema = declaration.get("inputSchema")
result_schema = declaration.get("resultSchema")
implements = declaration.get("implements")
if (
not isinstance(input_schema, dict)
or not isinstance(result_schema, dict)
or not isinstance(implements, list)
or any(not isinstance(item, str) for item in implements)
if not isinstance(input_schema, dict) or not isinstance(
result_schema, dict
):
raise RuntimeError("Validated manifest cache entry is corrupt")
declarations[identifier] = ManifestOperationDeclaration(
input_schema=MappingProxyType(input_schema),
result_schema=MappingProxyType(result_schema),
implements=frozenset(implements),
)
return MappingProxyType(declarations)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -432,9 +432,6 @@ def _invocation(
execution_deadline=deadline,
contract=operation_admission_pb2.OperationContractContext(
manifest_revision=lease.manifest_revision,
required_implementation_roles=sorted(
request.required_implementation_roles
),
),
execution_context=execution_context,
)
Expand Down Expand Up @@ -476,12 +473,6 @@ def _preflight(
raise OperationAdmissionPreconditionError(
"Operation payload does not match its declared schema"
) from error
if not set(request.required_implementation_roles).issubset(
declaration.implements
):
raise OperationAdmissionPreconditionError(
"Operation requires an undeclared implementation profile"
)
_validate_assessment(lease, invocation, assessment)


Expand All @@ -498,9 +489,7 @@ def _preflight_existing(
declaration = lease.operation_declarations.get(
invocation.operation_identifier
)
if declaration is None or not set(
invocation.contract.required_implementation_roles
).issubset(declaration.implements):
if declaration is None:
raise OperationAdmissionPreconditionError(
"Operation Admission declaration is no longer compatible"
)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,6 @@ class OperationAdmissionRequest:
payload: Mapping[str, JsonValue]
execution_deadline: datetime
execution_context: Mapping[str, JsonValue]
required_implementation_roles: tuple[str, ...] = ()


@dataclass(frozen=True, slots=True)
Expand Down
18 changes: 8 additions & 10 deletions tests/test_capability_assessment.py
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,14 @@
_ASSESSMENT_ID = UUID("1d40d0d5-ff2a-4780-bc3d-c4a7c55fc3a2")
_MANIFEST_REVISION = "sha256:" + ("0" * 64)
_GENERIC_OPERATION = "stateforge.test/configure@1"
_PROFILE_OPERATION = "stateforge.test/snapshot@1"
_BLOCKED_OPERATION = "stateforge.test/snapshot@1"
_UNSUPPORTED_OPERATION = "stateforge.test/unsupported@1"
_INDETERMINATE_OPERATION = "stateforge.test/inspect@1"
_EXPECTED_RETRY_CALLS = 2
_SENSITIVE_DETAILS = "credential-that-must-not-cross-the-boundary"
_OPERATIONS = (
_GENERIC_OPERATION,
_PROFILE_OPERATION,
_BLOCKED_OPERATION,
_UNSUPPORTED_OPERATION,
_INDETERMINATE_OPERATION,
)
Expand Down Expand Up @@ -126,18 +126,18 @@ def _response(
)
],
),
_PROFILE_OPERATION: capability_assessment_pb2.CapabilityFinding(
operation_identifier=_PROFILE_OPERATION,
_BLOCKED_OPERATION: capability_assessment_pb2.CapabilityFinding(
operation_identifier=_BLOCKED_OPERATION,
support_state=(
capability_assessment_pb2.SUPPORT_STATE_SUPPORTED_WITH_REQUIREMENTS
),
requirement_findings=[
capability_assessment_pb2.RequirementFinding(
requirement_id="runtime.profile.pending",
requirement_id="runtime.prerequisite.pending",
state=(
capability_assessment_pb2.REQUIREMENT_STATE_UNSATISFIED
),
description="Profile prerequisite is pending",
description="Runtime prerequisite is pending",
version_constraint=">=1",
)
],
Expand Down Expand Up @@ -549,10 +549,8 @@ def _manifest(
) -> ManifestDeclaration:
document = {
"operations": {
_GENERIC_OPERATION: {"implements": []},
_PROFILE_OPERATION: {
"implements": ["stateforge.profile.snapshot@1"]
},
_GENERIC_OPERATION: {},
_BLOCKED_OPERATION: {},
}
}
return ManifestDeclaration(
Expand Down
35 changes: 33 additions & 2 deletions tests/test_manifest_exchange.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
_SFP_VERSION = SfpVersion(major=1, minor=0)
_SESSION_ID = "manifest-session-A"
_GOLDEN_REVISION = (
"sha256:6bfdf3aedc2d4e45d77d4787cc0e744a488208b2510d81788291f51d24a623e8"
"sha256:aa27f0fddaa13df211bd3e4e4e4230cdda42d9188d4b480d196c2e0de2d20cdb"
)
_EXPECTED_RETRY_CALLS = 3

Expand All @@ -57,7 +57,6 @@
"properties": {},
"additionalProperties": False,
},
"implements": [],
}
},
"runtimeRequirements": {
Expand Down Expand Up @@ -194,6 +193,38 @@ def test_validates_the_protocol_conformance_revision() -> None:
assert declaration.as_dict() == _MANIFEST


def test_retains_concrete_operation_and_trigger_schemas() -> None:
manifest = deepcopy(_MANIFEST)
operation = manifest["operations"]["stateforge.git/reference.resolve@1"]
operation["inputSchema"]["properties"] = {
"vendor_request": {"type": "string"},
"extra_input": {"type": "integer"},
}
operation["resultSchema"]["properties"] = {
"vendor_result": {"type": "string"},
"extra_output": {"type": "boolean"},
}
payload_schema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {"event": {"type": "string"}},
}
manifest["triggers"] = {
"stateforge.git/reference.changed@1": {"payloadSchema": payload_schema}
}
declaration = ManifestDeclaration.validate(
_response(manifest=manifest), sfp_version=_SFP_VERSION
)
accepted = declaration.operation_declarations[
"stateforge.git/reference.resolve@1"
]
assert dict(accepted.input_schema) == operation["inputSchema"]
assert dict(accepted.result_schema) == operation["resultSchema"]
assert declaration.trigger_schemas == {
"stateforge.git/reference.changed@1": payload_schema
}


def test_installation_identity_contributes_to_revision() -> None:
first = _response()
second = _response(provider_instance_id=_OTHER_PROVIDER_INSTANCE_ID)
Expand Down
20 changes: 12 additions & 8 deletions tests/test_operation_admission.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,6 @@
_PROVIDER_ID = UUID("7f7db7d8-68b4-4f71-9769-065b5c4f941c")
_MANIFEST_REVISION = "sha256:" + ("a" * 64)
_OPERATION = "stateforge.test/restart@1"
_PROFILE = "stateforge.test.profile.v1.safe_restart"
_LOST_RESPONSE_CALL_COUNT = 2
_OVERSIZED_RESPONSE_LENGTH = contract.MAX_RESPONSE_BYTES + 1
_INPUT_SCHEMA = {
Expand Down Expand Up @@ -138,7 +137,6 @@ def _lease(*, generation: int = 1) -> OperationAdmissionLease:
_OPERATION: ManifestOperationDeclaration(
input_schema=_INPUT_SCHEMA,
result_schema=_RESULT_SCHEMA,
implements=frozenset({_PROFILE}),
)
},
channel=cast(grpc.aio.Channel, object()),
Expand All @@ -149,18 +147,26 @@ def _lease(*, generation: int = 1) -> OperationAdmissionLease:
def _request(
*,
unit: str = "nginx.service",
roles: tuple[str, ...] = (_PROFILE,),
) -> OperationAdmissionRequest:
return OperationAdmissionRequest(
provider_instance_id=_PROVIDER_ID,
operation_identifier=_OPERATION,
payload={"unit": unit},
execution_deadline=datetime.now(UTC) + timedelta(minutes=5),
execution_context={"requester": "test"},
required_implementation_roles=roles,
)


def test_removed_request_roles_are_rejected() -> None:
with pytest.raises(TypeError, match="required_implementation_roles"):
replace(_request(), required_implementation_roles=("obsolete",))


def test_removed_declaration_claims_are_rejected() -> None:
with pytest.raises(TypeError, match="implements"):
replace(_lease().operation_declarations[_OPERATION], implements=())


def _assessment(lease: OperationAdmissionLease) -> CapabilityAssessment:
context = operation_admission_pb2.OperationInvocation()
ParseDict({"requester": "test"}, context.execution_context)
Expand Down Expand Up @@ -205,7 +211,6 @@ def _wire_request() -> operation_admission_pb2.StartOperationRequest:
),
contract=operation_admission_pb2.OperationContractContext(
manifest_revision=_MANIFEST_REVISION,
required_implementation_roles=[_PROFILE],
),
)
ParseDict({"unit": "nginx.service"}, invocation.payload)
Expand Down Expand Up @@ -459,10 +464,10 @@ async def create_intent(self, *args, **kwargs):
"admission_request",
[
_request(unit=""),
_request(roles=("stateforge.test.profile.v1.undeclared",)),
_request(unit=7),
],
)
async def test_preflight_rejects_invalid_payload_or_profile(
async def test_preflight_rejects_invalid_payload(
tmp_path: Path,
admission_request: OperationAdmissionRequest,
) -> None:
Expand All @@ -481,7 +486,6 @@ async def test_preflight_rejects_invalid_payload_or_profile(
},
},
result_schema=_RESULT_SCHEMA,
implements=frozenset({_PROFILE}),
)
},
)
Expand Down
11 changes: 10 additions & 1 deletion tests/test_operation_lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -282,10 +282,19 @@ async def test_watch_retains_typed_terminal_and_does_not_dispatch(


@pytest.mark.asyncio
@pytest.mark.parametrize("restart", [False, True])
async def test_invalid_terminal_result_is_not_recorded(
tmp_path: Path,
restart: bool,
) -> None:
journal, store, admitted = await _accepted(tmp_path / "agent.db")
path = tmp_path / "agent.db"
journal, store, admitted = await _accepted(path)
if restart:
await journal.close()
journal = SqliteJournal(path)
await journal.open()
store = journal.operation_admissions(maximum_unresolved_attempts=16)
await store.initialize()
invalid = _snapshot(
admitted,
operation_lifecycle_pb2.OPERATION_STATE_SUCCEEDED,
Expand Down
Loading
Loading