extensions

func BuildDecisionContext ¶

func BuildDecisionContext(views execctx.Views, stage, providerID string, opts DecisionContextOptions) policydecision.Context

BuildDecisionContext assembles a safe, request-scoped policydecision.Context from the trusted execution views attached to an accepted request, plus stage/provider metadata, output-committed state, and the evaluation timeout budget (requirements 2.1-2.6, 7.5).

Safety properties:

• Authoritative scope comes from views.Scope (safe-by-construction: no raw credentials, headers, resume tokens, or unvetted claims). It is carried separately from the legacy views.Principal projection (requirement 2.6).
• Internal/auxiliary origin and parent trace attribution are preserved through views.Scope.Origin and views.Scope.ParentTraceID (requirement 2.4).
• Unknown optional scope fields are preserved as unknown rather than inferred from client payloads (requirement 2.2).
• The returned context is defensively cloned: mutating its maps, slices, or embedded scope cannot affect the caller's views (requirement 7.7).

The builder does not synthesize unsafe annotation entries or pull in raw request payloads; only the views' existing annotations are carried through.

func BuildSecretDecisionEvent ¶

func BuildSecretDecisionEvent(
	meta secretguard.Meta,
	call *lipapi.Call,
	guardID string,
	decision secretguard.Decision,
	quarantineResult string,
	backendDispatched bool,
	accessMode string,
	configVersion string,
	turnID string,
	now time.Time,
) secretguard.DecisionEvent

func CanonicalStageMetricLabels ¶

func CanonicalStageMetricLabels(stage, outcome string) (string, string)

CanonicalStageMetricLabels collapses unbounded/sensitive stage or outcome label values to unknown so metric cardinality stays bounded (samples are kept under unknown, not dropped).

func CompletionGateBufferExceeded ¶

func CompletionGateBufferExceeded(limits completion.BufferLimits, n int) bool

CompletionGateBufferExceeded reports whether buffering should fail open to live passthrough (R8).

func CompletionGatesFromContext ¶

func CompletionGatesFromContext(ctx context.Context, fallback CompletionGatesView) []completion.Gate

CompletionGatesFromContext returns completion gates from the request snapshot on ctx when present, otherwise from fallback. Semantics match the former [runtime.retryRecvStream.completionGatesFromContext] resolution order: context snapshot first, then executor snapshot. An empty result is always a non-nil slice so callers that iterate or serialize never see nil.

func EmitSecretGuardAudit ¶

func EmitSecretGuardAudit(ctx context.Context, audit *SecretGuardAudit, meta secretguard.Meta, call *lipapi.Call, guardID string, decision secretguard.Decision, quarantineResult string, backendDispatched bool) error

func FailurePolicyLabel ¶

func FailurePolicyLabel(p FailurePolicy) string

FailurePolicyLabel returns a stable JSON label for inventory/diagnostics.

func HandleControlTool ¶

func HandleControlTool(ctx context.Context, in ControlToolHandleRequest) (controltool.Outcome, error)

HandleControlTool invokes the pinned control provider at most once for one completed, bounded call and returns a normalized, content-free outcome.

The provider call runs behind the extension safety boundary, so a panic becomes a bounded isolated-panic error rather than an attempt-level crash. Every returned outcome is re-checked with the pure SDK validator before it leaves this stage: OutcomeInvalid must carry a bounded content-free reason and no result, OutcomeComplete must carry bounded non-empty UTF-8 result text, and an unknown kind is rejected. A provider error, an invalid outcome, and an unknown kind all collapse into ErrControlHandleFailed, so no provider text, argument byte, call ID, or result byte can reach a caller, a log, or a metric.

An already-canceled context is reported as cancellation before the provider is invoked. The caller's own context is passed through unchanged: this stage adds no goroutine, no deadline, and no new timeout budget.

func IsContextCancellation ¶

func IsContextCancellation(ctx context.Context, err error) bool

IsContextCancellation reports whether err is the parent request context being canceled or expired. The policy error conversion helpers must preserve parent cancellation as cancellation and never convert it into policy denial, failure, or malformed errors (requirement 6.4).

A bare context.DeadlineExceeded is only treated as parent cancellation when the supplied parent context has actually expired, so a child evaluation-deadline error is not misclassified as parent cancellation while the parent remains active.

func LegalPipelineStageNames ¶

func LegalPipelineStageNames() []string

LegalPipelineStageNames returns the core-owned ordered list of legal extension stages (R2). Each call allocates a fresh slice; see feature.LegalPipelineStageIDs.

func LegalStageDescriptors ¶

func LegalStageDescriptors() []feature.StageDescriptor

LegalStageDescriptors returns the SDK canonical stage descriptor table (read-only).

func NewSubmitEvidenceFunc ¶

func NewSubmitEvidenceFunc(ev *DecisionEvidence) hooks.SubmitEvidenceFunc

NewSubmitEvidenceFunc returns a hooks.SubmitEvidenceFunc that projects each submit-hook outcome into shared policy decision evidence and emits it through the seam's emitter (requirements 3.5, 4.6, 9.1, 9.5).

The returned func is intended to be attached to the request context via hooks.WithSubmitEvidence so hooks.Bus.RunSubmit can invoke it per hook without importing the extensions package. A nil seam (or nil emitter) yields a func that emits nothing, preserving the no-observer/non-interference default (requirements 7.6, 10.5).

Submit hooks may mutate the canonical call, but [sdk.SubmitDecision] does not report mutation, so the projector only emits compatible evidence for representable outcomes: reject (deny/none), annotation (allow/annotate), and provider failure (error/none). A no-op hook (no reject, no error, no added annotations) has no representable policy semantics and emits nothing; runtime behavior is still preserved (requirements 9.5, 10.5).

func NewToolReactorEvidenceFunc ¶

func NewToolReactorEvidenceFunc(ev *DecisionEvidence) hooks.ToolReactorEvidenceFunc

NewToolReactorEvidenceFunc returns a hooks.ToolReactorEvidenceFunc that projects each tool-reactor decision into shared policy decision evidence and emits it through the seam's emitter (requirements 3.3, 4.3, 9.1, 9.5).

The returned func is intended to be attached to the request context via hooks.WithToolReactorEvidence so hooks.Bus.ApplyToolReactors can invoke it per reactor without importing the extensions package. A nil seam yields a func that emits nothing.

Frontend-specific tool syntax is kept out of evidence semantics: only the canonical sdkhooks.ToolDecision enum, the reactor's error, and the runner's validation error are projected. Provider failures (err != nil) project as OutcomeError/EffectNone with ReasonToolReactorFailure. Invalid rewrite/replace output (validationErr != nil) projects as OutcomeError/EffectNone with ReasonToolReactorMalformed, so a rejected mutation is never recorded as a successful allow/mutate or allow/replace. The reactor's failure behavior is left to the caller's error policy (the runner preserves existing fail-open/fail-closed behavior; evidence is a side effect).

func PolicyErrorFromFailClosed ¶

func PolicyErrorFromFailClosed(stage, providerID, reasonCode, clientMessage string) error

PolicyErrorFromFailClosed converts an explicit fail-closed outcome into a stable policy denial error (requirements 6.1, 6.6). reasonCode and clientMessage must be client-safe bounded values.

func PolicyErrorFromMalformed ¶

func PolicyErrorFromMalformed(stage, providerID string, cause error) error

PolicyErrorFromMalformed converts a malformed-decision validation error into a stable lipapi.PolicyDecisionError of kind malformed (requirements 1.5, 6.6). cause is preserved for diagnostics only.

func PolicyErrorFromProviderFailure ¶

func PolicyErrorFromProviderFailure(stage, providerID string, behavior policydecision.FailureBehavior, cause error) error

PolicyErrorFromProviderFailure converts a provider failure into a stable policy failure error when the configured failure behavior is fail-closed (requirements 6.1, 6.5). Parent context cancellation is never converted here; the caller must check cancellation first and pass a non-cancellation cause.

func PolicyErrorFromTimeout ¶

func PolicyErrorFromTimeout(stage, providerID string, behavior policydecision.FailureBehavior) error

PolicyErrorFromTimeout converts a provider evaluation timeout into a stable policy failure error when the configured failure behavior is fail-closed (requirements 6.1, 6.3). Fail-open timeouts return nil so the caller records a skipped record instead of surfacing a denial.

func ProjectAttemptObservation ¶

func ProjectAttemptObservation(ctx policydecision.Context, providerID string, err error) (policydecision.Record, bool)

ProjectAttemptObservation projects an attempt-lifecycle observation into a shared policy decision record (requirements 1.7, 4.5, 4.6, 9.1, 9.5). Attempt lifecycle records are observational; ok=false when the attempt succeeded with no error, since a successful observation has no policy semantics to represent. The attempt stage runs after backend attempt is committed, so BackendAttempted is true.

func ProjectCompletionOutcome ¶

func ProjectCompletionOutcome(ctx policydecision.Context, providerID string, outcome completion.Outcome) policydecision.Record

ProjectCompletionOutcome projects a completion-gate outcome into a shared policy decision record (requirements 1.7, 3.4, 4.6, 9.1, 9.5). When output is already committed, a replacement outcome is ignored at runtime (completion_run.go), so the projection records skip/none with a post-output reason rather than fabricating a replace effect. Replay is unaffected by output-committed state. The completion gate runs after backend attempt is committed, so BackendAttempted is true.

func ProjectPreRequestDecision ¶

func ProjectPreRequestDecision(ctx policydecision.Context, providerID string, decision prerequest.Decision) policydecision.Record

ProjectPreRequestDecision projects a pre-request admission handler decision into a shared policy decision record (requirements 1.7, 3.1, 4.6, 9.1, 9.5). The projection is lossy-but-compatible: allow/annotate/deny map directly to the legality table for the pre-request stage. Provider failure, timeout, skip, and no-backend-attempt denial evidence are emitted by Phase 4 runtime integration through the error and timeout helpers; this helper only projects the Decision outcome.

func ProjectRequestTransformResult ¶

func ProjectRequestTransformResult(ctx policydecision.Context, providerID string, mutated bool, err error) policydecision.Record

ProjectRequestTransformResult projects a request-wide transform outcome into a shared policy decision record (requirements 1.7, 3.2, 4.6, 9.1, 9.5). mutated reports whether the transform changed the canonical call; err is the transform's returned error. Timeout and fail-open skip evidence are emitted by Phase 4 runtime integration; this helper projects pass-through, mutation, and provider failure.

func ProjectRouteHintOutcome ¶

func ProjectRouteHintOutcome(ctx policydecision.Context, providerID string, changed bool, err error) (policydecision.Record, bool)

ProjectRouteHintOutcome projects a route-hint provider outcome into a shared policy decision record (requirements 1.7, 4.5, 4.6, 9.1, 9.5). Route hints remain advisory through existing route preference contracts; the policy record does not directly mutate route plans. ok=false when the provider returned no preferred candidates and no error: an empty advisory opinion has no policy semantics to represent.

func ProjectSecretGuardDecision ¶

func ProjectSecretGuardDecision(ctx policydecision.Context, providerID string, decision secretguard.Decision) policydecision.Record

ProjectSecretGuardDecision projects a secret-guard Evaluate decision into a shared policy decision record. Findings, FailureReason, and any secret material must never appear in ClientMessage or ReasonCode (D8/D9). BackendAttempted is always false.

func ProjectSubmitOutcome ¶

func ProjectSubmitOutcome(ctx policydecision.Context, providerID string, rejected bool, annotations map[string]string, err error) (policydecision.Record, bool)

ProjectSubmitOutcome projects a submit-hook outcome into a shared policy decision record (requirements 1.7, 4.6, 9.1, 9.5). The second return value is ok=false when the outcome has no observable policy semantics to represent without inventing new submit semantics: a submit hook that neither rejected, errored, nor annotated did not produce a policy decision the shared vocabulary can describe. Runtime behavior is still preserved; callers simply skip emission when ok is false.

func ProjectToolCatalogOutcome ¶

func ProjectToolCatalogOutcome(ctx policydecision.Context, providerID string, mutated bool, err error) (policydecision.Record, bool)

ProjectToolCatalogOutcome projects a tool-catalog filter outcome into a shared policy decision record (requirements 1.7, 4.6, 9.1, 9.5). ok=false when the filter neither mutated the advertised tool list nor errored: a pure no-op filter has no policy semantics to represent. Advertised-tool mutation behavior is unchanged; the helper only records compatible evidence.

func ProjectToolPolicyDecision ¶

func ProjectToolPolicyDecision(ctx policydecision.Context, providerID string, decision toolpolicy.Decision) policydecision.Record

ProjectToolPolicyDecision projects a canonical tool-call policy decision into a shared policy decision record (requirements 1.7, 3.3, 4.6, 9.1, 9.5). The tool policy stage runs after backend attempt is committed, so BackendAttempted is true.

func ProjectToolReactorDecision ¶

func ProjectToolReactorDecision(ctx policydecision.Context, providerID string, decision sdkhooks.ToolDecision) policydecision.Record

ProjectToolReactorDecision projects a tool reactor outcome into a shared policy decision record (requirements 1.7, 3.3, 4.6, 9.1, 9.5). Frontend-specific tool syntax is kept out of evidence semantics: only the canonical ToolDecision enum is projected. Tool reactor runs after backend attempt is committed, so BackendAttempted is true.

func RecordStageObservation ¶

func RecordStageObservation(obs StageMetrics, stage, outcome string, seconds float64, count, bytes int64)

RecordStageObservation records duration and optional safe counts/bytes with bounded labels. count<=0 and bytes<=0 are ignored so sinks never receive non-positive counter adds.

func RunCompactionPreserverAfterResponseRelease ¶

func RunCompactionPreserverAfterResponseRelease(
	ctx context.Context,
	log *slog.Logger,
	obs StageMetrics,
	preservers []compaction.Preserver,
	ev lipapi.Event,
	meta compaction.PreservationMeta,
	services compaction.Services,
) error

RunCompactionPreserverAfterResponseRelease invokes the optional final release-commit callback in registration order. A deep-isolated canonical event is supplied so the notification cannot mutate the event already committed by the detector and released to the client.

func RunCompactionPreserverBeforeRequest ¶

func RunCompactionPreserverBeforeRequest(
	ctx context.Context,
	log *slog.Logger,
	obs StageMetrics,
	preservers []compaction.Preserver,
	call *lipapi.Call,
	preview compaction.RequestPreview,
	meta compaction.PreservationMeta,
	services compaction.Services,
) error

RunCompactionPreserverBeforeRequest invokes ordered preservation callbacks before the primary request opens. Each callback gets its own bounded clone baseline. Callback errors, panics, and invalid mutations roll back only that callback and are isolated from primary traffic; later preservers continue.

func RunCompactionPreserverBeforeResponseRelease ¶

func RunCompactionPreserverBeforeResponseRelease(
	ctx context.Context,
	log *slog.Logger,
	obs StageMetrics,
	preservers []compaction.Preserver,
	ev *lipapi.Event,
	preview compaction.ResponsePreview,
	meta compaction.PreservationMeta,
	services compaction.Services,
) error

RunCompactionPreserverBeforeResponseRelease invokes ordered final-response preservation callbacks. Each callback is transactional against the exact pre-callback event. A failed, panicking, or invalid callback is rolled back and the committed detector can therefore observe the restored final event.

func RunCompactionPreserverRequestOpenFailed ¶

func RunCompactionPreserverRequestOpenFailed(
	ctx context.Context,
	log *slog.Logger,
	obs StageMetrics,
	preservers []compaction.Preserver,
	meta compaction.PreservationMeta,
	services compaction.Services,
) error

RunCompactionPreserverRequestOpenFailed invokes the optional failed-open lifecycle callback in registration order. Only preservers implementing the additive RequestOpenFailedPreserver interface participate; errors and panics are isolated so primary open/error authority remains in core.

func RunCompactionPreserverRequestOpened ¶

func RunCompactionPreserverRequestOpened(
	ctx context.Context,
	log *slog.Logger,
	obs StageMetrics,
	preservers []compaction.Preserver,
	call lipapi.Call,
	events []compaction.Event,
	meta compaction.PreservationMeta,
	services compaction.Services,
) error

RunCompactionPreserverRequestOpened invokes preservation callbacks after the primary request has opened. The content arguments are deep-copied per callback, so callback-local mutation cannot alter primary traffic or another callback. Errors and panics are feature-local fail-open outcomes.

func RunFinalStreamObservationStage ¶

func RunFinalStreamObservationStage(ctx context.Context, log *slog.Logger, obs StageMetrics, session *FinalStreamObservationSession, ev lipapi.Event, committed bool) error

func RunPreRequestStage ¶

func RunPreRequestStage(ctx context.Context, log *slog.Logger, obs StageMetrics, handlers []prerequest.Handler, call *lipapi.Call, meta prerequest.Meta, svc prerequest.Services) (err error)

RunPreRequestStage runs admission handlers in stable order after request shaping and before route planning.

func RunRequestTransformStage ¶

func RunRequestTransformStage(ctx context.Context, log *slog.Logger, obs StageMetrics, transforms []request.Transform, call *lipapi.Call, meta request.RequestMeta, svc request.Services) (err error)

RunRequestTransformStage runs request-wide transforms in stable order (design §5, §17). Errors from handlers with FailOpen are logged and skipped; FailClosed stops the chain. The call is re-validated after the chain completes.

func RunRouteHintStage ¶

func RunRouteHintStage(ctx context.Context, log *slog.Logger, providers []routehint.Provider, call *lipapi.Call, meta routehint.Input) ([]string, error)

RunRouteHintStage invokes route hint providers with fail-open semantics (design §17 route_hinting).

func RunSessionClassificationStage ¶

func RunSessionClassificationStage(ctx context.Context, log *slog.Logger, classifier sessionclassification.Classifier, in sessionclassification.Input) session.Classification

RunSessionClassificationStage evaluates the optional SDK classifier and returns a validated projection. An existing positive classification is immutable.

func RunSessionOpenStage ¶

func RunSessionOpenStage(ctx context.Context, log *slog.Logger, obs StageMetrics, openers []session.Opener, in session.OpenInput) session.OpenResult

RunSessionOpenStage invokes session openers in registration order with fail-open semantics (design §17 session_open default).

func RunToolCatalogFilterStage ¶

func RunToolCatalogFilterStage(ctx context.Context, log *slog.Logger, obs StageMetrics, filters []toolcatalog.Filter, call *lipapi.Call, meta toolcatalog.CatalogMeta, svc toolcatalog.Services) (err error)

RunToolCatalogFilterStage runs tool catalog filters in stable order (design §4, §17). After the chain, lipapi.ReconcileToolChoiceAfterToolListChange runs once, then the call is validated.

func RunToolPolicyStage ¶

func RunToolPolicyStage(in ToolPolicyStageInput) (err error)

RunToolPolicyStage runs provider-neutral tool-call policies before tool reactors. in.Policies must already be in execution order (as produced by toolpolicy.MaterializeSorted or by RequestRuntimeSnapshot.ToolCallPoliciesExecution); the stage does not re-sort.

func SafeCallReasoningObserveBytes ¶

func SafeCallReasoningObserveBytes(call *lipapi.Call) int64

SafeCallReasoningObserveBytes returns aggregate reasoning payload byte lengths for a call.

func SafeEventObserveBytes ¶

func SafeEventObserveBytes(ev lipapi.Event) int64

SafeEventObserveBytes returns content-safe byte totals for an observed stream event.

func StageDescriptorByID ¶

func StageDescriptorByID(id string) (feature.StageDescriptor, bool)

StageDescriptorByID returns the descriptor for a legal stage id.

func StreamFinished ¶

func StreamFinished(events []lipapi.Event) bool

StreamFinished reports whether the canonical stream reached a terminal completion marker.

func ValidateDecisionRecord ¶

func ValidateDecisionRecord(record policydecision.Record) error

ValidateDecisionRecord is a thin compatibility wrapper that delegates to policydecision.ValidateRecord. It is retained because existing tests and runtime integration call it directly; new callers should use the SDK validator (requirements 1.5, 3.6, 4.4, 6.6).

func ValidateStageID ¶

func ValidateStageID(id string) bool

ValidateStageID reports whether id is a legal pipeline stage.

func WithAttemptEvidence ¶

func WithAttemptEvidence(ctx context.Context, fn AttemptEvidenceFunc) context.Context

WithAttemptEvidence attaches fn to ctx so the runtime attempt-record boundary can emit per-attempt policy decision evidence. A nil fn means no evidence is emitted.

func WithDecisionEvidence ¶

func WithDecisionEvidence(ctx context.Context, ev *DecisionEvidence) context.Context

WithDecisionEvidence attaches ev to ctx so stage runners can project and emit per-provider policy decision evidence. A nil ev means no evidence is emitted.

func WithRequestRuntimeSnapshot ¶

func WithRequestRuntimeSnapshot(ctx context.Context, snap *RequestRuntimeSnapshot) context.Context

WithRequestRuntimeSnapshot attaches snap to ctx for the remainder of the request lifetime. snap must remain valid and unchanged for the lifetime of ctx (see RequestRuntimeSnapshot).