Operation
The atom: one operation defined once — schema of inputs + handler + metadata — that the family projects to N surfaces (CLI, MCP, HTTP, web, TUI). A `SurfaceProjector` turns this into each surface's native shape; the operation is written once and surfaced wherever it is enabled. `readonly` (not `final`) so that the deprecated `Milpa\Runtime\CommandDefinition` can remain a subclass during the transition — a readonly class may only be extended by a readonly class.
Operation::__construct()
public function __construct(string $name, string $description, ?mixed $handler, ?array $inputSchema = null, bool $mutating = false, bool $requiresConfirmation = false, array $scopes = [], ?array $outputSchema = null, ?string $version = null, ?string $path = null, ?array $surfaces = null, ?string $permission = null, ?string $namedTarget = null, ?Milpa\Command\Effect\EffectProfile $effects = null):Parameters
| Name | Type | Description |
|---|---|---|
| $name | string | |
| $description | string | |
| $handler | (callable | array{0: class-string, 1: string}) | A plain PHP callable, or a `[class-string, method]` pair a host resolves through DI. Typed `mixed` because PHP forbids the native `callable` type on a property. Called with the coerced `array<string,mixed> $input`; returns domain data. |
| $inputSchema | (array<string, mixed> | null) | JSON-Schema-shaped input definition; null = no typed inputs. |
| $mutating | bool | |
| $requiresConfirmation | bool | |
| $scopes | list<string> | Auth scopes enforced by a policy gate on surfaces that have one wired — MCP via tool-runtime's PolicyGate, and HTTP via the HttpProjector's scope gate: a non-empty `$scopes` makes the projector attach a per-route RequireScope middleware and build the `ToolContext::web()` the same PolicyGate reads, so HTTP now enforces scopes instead of ignoring them. |
| $outputSchema | (array<string, mixed> | null) | JSON-Schema-shaped output definition. |
| $version | ?string | |
| $path | (string | null) | HTTP path; declared here, or (null) derived from `$name`. |
| $surfaces | (list<string> | null) | Surfaces this operation opts into; null = all. |
| $permission | (string | null) | The semantic permission key (`{namespace}.{resource}:{action}`) a permission-aware surface enforces; mutually exclusive with `$scopes`. |
| $namedTarget | ?string | |
| $effects | ?Milpa\Command\Effect\EffectProfile |
Operation::effectCeiling()
public function effectCeiling(): Milpa\Command\Effect\EffectProfileThe effect ceiling of this operation — never `null`. An operation that declared nothing gets `unclassified()`, which is every dimension at its maximum. Callers therefore never have to write `?? something-safe`, and cannot accidentally write `?? readOnly()` — which is precisely the permissive default GOV-13 forbids and the shape a tired reviewer would wave through.
Operation::ceilingForCall()
public function ceilingForCall(array $arguments, ?Milpa\Command\Effect\AuthorityPolicy $policy = null, ?Milpa\Command\Effect\ContextFacts $facts = null): Milpa\Command\Effect\EffectProfileThe ceiling THIS CALL carries, with the handler that is about to run named. The operation is the only place holding both the handler and its declared effects, so it is the only honest place to join them: a caller computing the digest itself would either hand out descents nobody watched or refuse ones that were earned. The policy and the facts travel when the caller has them (greenhouse decisions/0054): the authority axis is judged live by its own producer, and a caller with nothing to offer simply gets no authority descent — fail-closed, not an error.
Parameters
| Name | Type | Description |
|---|---|---|
| $arguments | array<string, mixed> | |
| $policy | ?Milpa\Command\Effect\AuthorityPolicy | |
| $facts | ?Milpa\Command\Effect\ContextFacts |
Operation::handlerDigest()
public function handlerDigest(): ?stringThe digest of the handler body, which is what a descent certificate is bound to. ITS LIMIT IS PART OF THE CONTRACT, not an oversight: this hashes the CODE OF THE HANDLER ITSELF. A handler that delegates changes behaviour without changing this digest, so a certificate stays valid across a change it never watched. Saying so is half the value — greenhouse decisions/0050 `F-3` exists to be paid, and hiding it would turn currency into a promise. `null` when the handler cannot be read, and `null` buys nothing: a descent whose certificate cannot be compared does not lower anything.
Operation::supportsSurface()
public function supportsSurface(string $surface): boolWhether this operation is projected to the given surface. `null` $surfaces means every surface; a list is an explicit opt-in.
Parameters
| Name | Type | Description |
|---|---|---|
| $surface | string |