Expand description
Product-neutral contracts for safe infrastructure operations.
soma-ops defines stable operation identities, typed request envelopes,
catalog metadata, authorization evidence, deterministic plans, bounded
progress, terminal results, verification, and lifecycle events. It does not
know about Soma principals, Synapse scopes, MCP elicitation, CLI prompts,
Docker, Incus, SSH, databases, or product configuration.
Product applications translate their own identity and policy into these
contracts. Concrete engines such as soma-infra implement operation
definitions over these types.
Structs§
- Actor
Ref - Stable reference to the product or agent that requested an operation.
- Artifact
Ref - Reference to a protected or durable operation artifact.
- Authorization
Evidence - Opaque, time-bounded authorization evidence issued by a product layer.
- Authorization
Id - Opaque identity for authorization evidence issued by a product policy layer.
- Authorization
Scope - Exact operation and target scope approved by product policy.
- Correlation
Id - Identity shared by operations participating in one workflow or incident.
- Diagnostic
- Correctable diagnostic returned by an operation engine.
- Diagnostic
Code - Stable machine-readable diagnostic code such as
target.not_found. - Diagnostic
Code Error - Invalid stable diagnostic code.
- EventId
- Unique identity for one operation lifecycle event.
- Evidence
Ref - Reference to evidence captured by an operation.
- Execution
Metadata - Timing, mutation-send, and retry metadata for terminal execution.
- Idempotency
Key - Caller-provided key that makes a supported mutation safely repeatable.
- Idempotency
KeyError - Error returned for an invalid idempotency key.
- Noop
Progress Sink - Progress sink that intentionally discards events.
- Operation
Context - Traceable execution context supplied by the calling product.
- Operation
Event Envelope - Common envelope for operation lifecycle events.
- Operation
Id - Unique identity for one operation execution.
- Operation
Name - Stable dotted operation identity such as
container.restart. - Operation
Name Error - Error returned for an invalid canonical operation name.
- Operation
Plan - Immutable authorization-relevant operation plan.
- Operation
Request - Typed request envelope for one concrete operation definition.
- Operation
Result - Terminal result for one operation execution.
- Operation
Spec - Product-neutral catalog record for one operation.
- Parameter
Group - One complete set of parameter names required together.
- Plan
Fingerprint - SHA-256 fingerprint of the complete authorization-relevant plan material.
- Plan
Step - One ordered execution step within a plan.
- Planned
Change - One intended resource change described before execution.
- Producer
Ref - Identity and version of the component that emitted an operation event.
- Progress
Event - One bounded monotonic progress update for an operation.
- Redaction
Metadata - Description of fields or artifacts removed from a result.
- Schema
Id - Stable identity for a versioned operation parameter or result schema.
- Target
Ref - Stable, serializable reference to an operation target.
- Timestamp
- Milliseconds from the Unix epoch used in cross-process operation contracts.
- Trace
Context - W3C trace context safe to propagate across operation boundaries.
- Verification
Result - Independent runtime-state verification result.
- Verification
Strategy - Operation used to verify actual runtime state after execution.
Enums§
- Access
Class - Whether an operation only observes state or may mutate it.
- Authorization
Error - Authorization evidence validation failure.
- Capability
Support - Whether an implementation supports a lifecycle capability.
- Diagnostic
Severity - Severity of one structured diagnostic.
- Event
Error - Invalid lifecycle event envelope.
- Evidence
Kind - Kind of evidence an operation can return for audit or verification.
- Identity
Error - Validation failures for opaque identities and cross-product references.
- Mutation
Send State - Whether a failed operation may already have reached the target.
- Operation
Event Payload - Lifecycle-specific operation event payload.
- Operation
Event Type - Canonical operation lifecycle event type.
- Operation
Status - Terminal operation status before independent verification.
- Plan
Error - Invalid operation plan or plan fingerprint.
- Progress
Error - Invalid progress event.
- Request
Error - Request validation failure.
- Result
Error - Invalid operation result or result metadata.
- Retry
Class - Whether a failed call may be retried automatically.
- Reversibility
- Expected ability to reverse an operation’s effect.
- Risk
Class - Operational risk independent of product-specific authorization policy.
- Schema
IdError - Invalid operation schema identity.
- Spec
Error - Invalid operation catalog metadata.
- Target
Kind - Typed category of a resource targeted by an operation.
- Target
RefError - Validation failure for a target reference.
- Verification
Status - Independent verification outcome after execution completes.
Traits§
- Event
Sink - Sink for operation lifecycle events, implemented by embedded or remote adapters.
- Operation
Definition - Typed definition implemented by a concrete infrastructure operation.
- Progress
Sink - Consumer of operation progress events.
Type Aliases§
- Operation
Event - Backward-compatible short name for the canonical event envelope.