execution

package
v1.0.217 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package execution implements the PR-11 guarded Model-A execution path — the runtime.ExecutionProvider that turns the decision-only Gateway into a bounded, rollout-mode-gated executor. It is wired ONLY for the Gateway capability and ONLY when rollout distribution arms it (disabled by default). It composes the existing engines without weakening any of them: rollout (mode/scope/hard-failure), the PR-6 policy decision (already computed), PR-7 inspection/DLP for the response, the PR-4 credential broker (materialization with no token passthrough), the PR-8 events manager (commit-before-side-effect), and the PR-11 upstream client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// State is the capability-local rollout state (Gateway). Required.
	State *rollout.State
	// Broker materializes the approved-server credential (nil ⇒ no credential is
	// attached; the upstream call carries no Authorization).
	Broker *broker.Broker
	// Events is the PR-8 durable-event manager. Required for the commit-before-
	// side-effect guarantee; a nil Events fails every execution closed.
	Events *events.Manager
	// Upstream is the bounded upstream MCP client. Required.
	Upstream UpstreamCaller
	// ResponseProfile is the PR-7 inspection profile used to inspect + DLP the
	// upstream response before returning it to the client.
	ResponseProfile inspection.Profile
	// Metrics is the optional rollout telemetry sink.
	Metrics Metrics
	// Clock is injected for tests; nil ⇒ time.Now.
	Clock func() time.Time
	// Actor labels events emitted by this executor.
	Actor string
}

Config wires an Executor for the Gateway capability.

type Discovery

type Discovery struct {
	Registry *registry.Registry
	Catalog  *catalog.Catalog
	Upstream UpstreamCaller
}

Discovery performs a real upstream tools/list against a registered server and feeds the result through the PR-2 catalog ingestion path (fingerprints → drift classification → quarantine of unknown/expanded tools). It reuses the PR-1 kernel on the upstream leg (via the upstream client's strict decode) and never auto-approves a new or changed fingerprint. A discovery failure returns a classified error and leaves the previous known-good catalog snapshot UNCHANGED.

func NewDiscovery

func NewDiscovery(reg *registry.Registry, cat *catalog.Catalog, up UpstreamCaller) (*Discovery, error)

NewDiscovery constructs a Discovery. It fails closed on missing collaborators.

func (*Discovery) Discover

func (d *Discovery) Discover(ctx context.Context, serverID string) (*catalog.Report, error)

Discover runs the ordered discovery sequence for one registered server:

  1. resolve + validate the server registration + trusted identity;
  2. fetch a bounded tools/list via the upstream client (strict shared-kernel decode of the response);
  3. feed the exact result bytes into the PR-2 catalog ingestion path;
  4. drift classification + quarantine happen inside Ingest (unknown/expanded fingerprints land Quarantined and never auto-clear);
  5. on ANY failure, the previous catalog snapshot is retained unchanged.

It returns the ingestion Report (safe drift/quarantine evidence) on success.

type Executor

type Executor struct {
	// contains filtered or unexported fields
}

Executor implements runtime.ExecutionProvider.

func New

func New(cfg Config) (*Executor, error)

New constructs an Executor. It fails closed if the required collaborators are missing.

func (*Executor) Execute

Execute is the runtime.ExecutionProvider entry. It resolves the effective rollout disposition and dispatches record-only / block / execute.

type Metrics

type Metrics interface {
	ObserveResolution(capability string, res rollout.Resolution)
	ObserveBlock(capability string, reason mcperr.Reason)
	ObserveExecution(capability string, ok bool)
	ObserveUpstream(capability string, outcome string)
	ObserveDLPBlock(capability string, response bool)
	// ObserveOutcomeEvidenceLoss records that a post-execution outcome event could
	// not be committed. The side effect already happened, so this is the archive
	// losing its record of it — best-effort must mean "does not block the response",
	// never "fails invisibly".
	ObserveOutcomeEvidenceLoss(capability string)
}

Metrics is the optional bounded, low-cardinality rollout telemetry sink. All labels are bounded enums (capability, disposition, reason code, hard class) — never a tenant, subject, tool argument, URL, or token.

type UpstreamCaller

type UpstreamCaller interface {
	Call(ctx context.Context, target upstreamclient.Target, method string, params json.RawMessage, opts upstreamclient.CallOptions) (*upstreamclient.Response, error)
}

UpstreamCaller is the injected upstream client (interface for testability).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL