patchbay_host library
Patchbay 的 host implementer 入口（PB-060-02 / DG-060-02）。
内容是默认 consumer 清单的严格超集：package:patchbay/patchbay.dart 的全部符号，
再加 PatchbayServiceHost、audit sink/event、invocation 与 cancellation 的宿主侧
lifecycle、admission/rejection，以及响应与执行证据的 validation。组合根只需要这一个
import，不必再叠加默认入口。
它同样受 tool/check_api_closure.dart 的自足约束，所以清单里能看到
PatchbayFeature（PatchbayServiceHost 三个 factory 的形参）这类原本按命名会归到
protocol 的类型。
这里不 re-export 整个 protocol 面：既要实现 host 又要直接读写 raw wire 的高级
使用者显式再 import package:patchbay/patchbay_protocol.dart。
普通 widget / 业务 adapter 不应该 import 本 library —— 它能看见 host lifecycle， 而那正是默认面刻意收窄掉的部分。
Classes
- PatchbayArtifactService
- Explicitly injected log/blob command module shared by core and Flutter.
- PatchbayAuditDrainResult
- Immutable accounting for the audit events accepted before the drain gate.
- PatchbayAuditEvent
- One redacted command audit fact retained by PatchbayServiceHost.
- PatchbayAuditExecutionDetails
- Host-only, additive projection of confirmed execution facts for one accepted command. PB-050-26 / DG-060-04.
- PatchbayAuditRevealExecutionDetails
-
stepsand the driven container node ids for one acceptedui.revealcall. PB-050-26 / DG-060-04. - PatchbayBlobChunkWire
-
Strict wire representation of
PatchbayBlobChunkWire. - PatchbayBlobMetadataWire
-
Strict wire representation of
PatchbayBlobMetadataWire. - PatchbayCancellationSignal
- PatchbayCatalogProvider
- A catalog source with an explicit, cheap commands invalidation signal.
- PatchbayCatalogSample
- A complete catalog observation bound to the commands revision it describes.
- PatchbayCliEqualsCondition
- PatchbayCliSyntax
- One CLI spelling derived from a protocol-owned command descriptor.
- PatchbayCommandDescriptor
- Consumer-neutral catalog entry. Business namespaces remain consumer-owned.
-
PatchbayCommandRegistration<
T> - One indivisible protocol-owned command registration.
- PatchbayCommandRegistry
- Transport-neutral catalog and dispatch table for protocol-owned commands.
- PatchbayDestinationDescriptor
- Runtime catalog row for one consumer-owned destination.
- PatchbayDestinationDescriptorWire
-
Strict wire representation of
PatchbayDestinationDescriptorWire. - PatchbayExecutionContract
-
Descriptor-owned policy used to interpret a payload's
executionobject. - PatchbayExecutionValidationResult
- PatchbayGateDecision
- Stable decision returned by the host base gate or a consumer gate.
- PatchbayGateEvaluator
- Runs the non-optional host gate before descriptor-declared consumer gates.
- PatchbayGateRejection
- PatchbayHostInvocationHandle
- A response may freeze before the underlying invocation lifecycle releases.
- PatchbayInvocation
- Admission envelope. It deliberately does not claim domain execution.
- PatchbayInvocationCancellationResult
- Immutable control-plane answer. It never includes the owner token.
- PatchbayInvocationCancellationSignal
- Read-only cancellation signal exposed to a context-aware consumer.
- PatchbayInvocationContext
- Additive per-invocation context for cooperative consumers.
- PatchbayInvocationDeadline
- A host-local deadline view. It never exposes wall-clock time.
- PatchbayInvocationDrainResult
- Frozen terminal accounting for invocations present when drain began.
- PatchbayJobEvent
- PatchbayJobRegistry
- In-isolate job ledger for operations whose completion cannot be represented honestly by the admission response.
- PatchbayJobSnapshot
- PatchbayJobWaitResult
- PatchbayLogPage
- Consumer-owned query result. Patchbay applies its own response bounds after the source returns and never subscribes to or takes ownership of the source.
- PatchbayLogQuery
- PatchbayLogRecordWire
-
Strict wire representation of
PatchbayLogRecordWire. - PatchbayLogSource
- Consumer injection seam for already-redacted structured records.
- PatchbayMemoryBlobStore
- Bounded, process-local storage for binary artifacts.
- A consumer-observed, settled navigation state.
- PatchbayOutputArtifactProjection
-
The
artifacthalf of a declaration: at most one artifact per command. - PatchbayOutputBriefProjection
-
The
briefhalf of a declaration: a stable id plus a deny-list. - PatchbayOutputProjection
- One command's whole machine-output declaration.
- PatchbayOutputProjectionPath
-
A parsed restricted path:
$followed by one or more.field, where any non-final field may carry[]to traverse the maps of a list. - PatchbayOutputProjectionPathSegment
-
One
.field(optionally[]) step of a restricted projection path. - PatchbayParameterDescriptor
- Machine-readable argument declaration used by both validation and CLI help.
- PatchbayRedactedLogRecord
- A log record whose public constructor enforces Patchbay's defensive redaction boundary before a consumer source can return it.
- PatchbayRejection
- Stable rejection attached only when a request was not admitted.
- PatchbayResponseSchema
- Accepted and job-terminal payload declarations for one command.
- PatchbayResponseValidationIssue
- One value-free validation issue safe to return to an untrusted caller.
- PatchbayResponseValueSchema
- One recursively declared response value.
- PatchbayRetryPolicy
- Bounded retry contract for one consumer-owned external command.
- PatchbayServiceHost
- Generic VM Service extension host. It has no Flutter or consumer imports.
- PatchbaySnapshotRetentionLimits
- The three budgets a host applies to snapshot revision retention.
- PatchbaySnapshotSample
- One snapshot observation bound to the content revision the App reports.
- PatchbayUiTargetDeclaration
-
Consumer declaration stored by a
PatchbayKeywithout Widget callbacks. - PatchbayUiTargetDescriptor
- Runtime catalog entry. Operations are the declaration/runtime intersection.
Enums
- PatchbayAdmission
- PatchbayAuditDrainOutcome
- The terminal outcome of one host audit-delivery drain.
- PatchbayBlobFailureCode
- PatchbayBlobSourceWire
-
Strict wire representation of
PatchbayBlobSourceWire. - PatchbayCliArtifactDisposition
- PatchbayCliInputMode
- PatchbayCommandMode
- PatchbayExecutionClassification
- PatchbayFactSource
- Closed vocabulary for the strength and origin of a Patchbay fact.
- PatchbayFactSourceWire
-
Strict wire representation of
PatchbayFactSourceWire. - PatchbayFeature
- A protocol capability a host declares on the identity plane.
- PatchbayInteractionModel
- Closed catalog-wire classification distinguishing an explicit consumer automation surface from an action that must still satisfy user-like reachability (DG-060-05, "交互模型进入 catalog").
- PatchbayInvocationCancellationOutcome
- Stable result of the protocol-owned cancel operation.
- PatchbayInvocationCancellationReason
- The first transport or host fact that asked one invocation to stop.
- PatchbayInvocationConfirmationState
- Why a requested cancellation was not confirmed inside its observation budget.
- PatchbayInvocationDrainOutcome
- PatchbayJobCancelOutcome
- What a cancellation attempt actually achieved for one job.
- PatchbayJobPhase
- PatchbayJobWaitOutcome
- PatchbayLogDirectionWire
-
Strict wire representation of
PatchbayLogDirectionWire. - PatchbayLogLevelWire
-
Strict wire representation of
PatchbayLogLevelWire. - PatchbayLogPageState
- PatchbayLogRedactionWire
-
Strict wire representation of
PatchbayLogRedactionWire. - Stable navigation verbs exposed without leaking a consumer route path.
-
Strict wire representation of
PatchbayNavigationOperationWire. - PatchbayOutputArtifactEncoding
- How a PatchbayOutputArtifactKind.renderedMember member becomes bytes.
- PatchbayOutputArtifactKind
- Where an artifact's bytes come from. A closed set: a declaration may not name a path, a template, a formatter or a second artifact.
- PatchbayParameterType
- PatchbayPlane
- PatchbayResponseType
- Closed JSON value kinds supported by command response schemas.
- PatchbaySensitivePolicy
- PatchbaySideEffect
- PatchbayUiOperation
- PatchbayUiTargetKind
Constants
-
patchbayAuditAdmissionStages
→ const Set<
String> - The stage an invocation's admission pipeline stopped or completed at.
-
patchbayAuditExecutionDetailsDefectReasons
→ const Set<
String> - Closed reasons PatchbayAuditExecutionDetailsProjectionDefect reports.
-
patchbayAuditGateDispositions
→ const Set<
String> - How the invocation stood relative to consumer declared gates and dynamic operation policy.
- patchbayAuditLegacyUnknown → const String
- What a new audit reader must assume when an old host omits the new keys.
- patchbayConfirmationBudgetMaxMs → const int
- patchbayOutputProjectionJsonExtension → const String
- File extension paired with PatchbayOutputArtifactEncoding.json.
- patchbayOutputProjectionJsonMediaType → const String
- Media type paired with PatchbayOutputArtifactEncoding.json.
- patchbayOutputProjectionMaxIdLength → const int
- Maximum length of a brief projection id.
- patchbayOutputProjectionMaxOmitRules → const int
-
Maximum number of
omitrules one brief declaration may carry. - patchbayOutputProjectionMaxPathBytes → const int
- Maximum bytes one restricted path literal may occupy.
- patchbayOutputProjectionReservedRootPrefix → const String
- Root-level prefix the CLI reserves for the facts it appends itself.
- patchbayOutputProjectionTextExtension → const String
- File extension paired with PatchbayOutputArtifactEncoding.utf8Text.
- patchbayOutputProjectionTextMediaType → const String
- Media type paired with PatchbayOutputArtifactEncoding.utf8Text.
- patchbayPackageVersion → const String
-
The
patchbaypackage version the host was compiled from. - patchbayResponseSchemaMaxDepth → const int
- patchbayResponseSchemaMaxFields → const int
- patchbayResponseValidationMaxIssues → const int
- patchbaySnapshotDefaultMaxRetainedBytes → const int
- Default total retained canonical UTF-8 budget (DG-050-01).
- patchbaySnapshotDefaultMaxSnapshotBytes → const int
- Default per-snapshot canonical UTF-8 budget (DG-050-01).
- patchbaySnapshotDiffMaxChanges → const int
- Maximum number of path changes returned by one diff.
- patchbaySnapshotDiffMaxEncodedBytes → const int
- Maximum encoded bytes returned by one diff.
- patchbaySnapshotMinSnapshotBytes → const int
- Smallest per-snapshot canonical UTF-8 budget a host may be configured with.
- patchbaySnapshotPollInterval → const Duration
- How often the host re-reads the consumer snapshot while waiting.
- patchbaySnapshotRetainedByteCeiling → const int
- Largest total retained canonical UTF-8 budget a host may be configured with.
- patchbaySnapshotRevisionRetention → const int
- Revisions retained per App instance for bounded snapshot diffing.
- patchbaySnapshotRevisionRetentionCeiling → const int
- Largest retained-revision count a host may be configured with.
- patchbaySnapshotSnapshotByteCeiling → const int
- Largest per-snapshot canonical UTF-8 budget a host may be configured with.
- patchbaySnapshotWaitCeiling → const Duration
-
Longest wait the host will accept, matching the
ui.waitfamily. - patchbayUnchangedEvidenceMaxAgeMs → const int
Functions
-
patchbayAuditExecutionClassification(
Map< String, Object?> response) → String? - The stable execution classification projected by both host audit and CLI trace consumers from one invocation response.
-
patchbayGenerateOwnerToken(
) → String -
patchbayProjectAuditEvent(
{required String command, required String requestId, required Map< String, Object?> arguments, required String gateResult, required Map<String, Object?> response, String? admissionStage, String? gateDisposition, PatchbayAuditExecutionDetailsDefectHandler? onExecutionDetailsDefect}) → PatchbayAuditEvent - Builds the redacted audit projection from a command fact.
-
validatePatchbayExecutionContract(
PatchbayExecutionContract contract) → void -
validatePatchbayExecutionEvidence(
PatchbayExecutionContract contract, Object? payload, {String path = r'$.payload', String? terminalPhase, required int nowMs}) → PatchbayExecutionValidationResult -
validatePatchbayResponsePayload(
PatchbayResponseValueSchema schema, Object? payload, {String path = r'$.payload'}) → List< PatchbayResponseValidationIssue> -
validatePatchbayResponseSchema(
PatchbayResponseSchema schema) → void -
validatePatchbayTerminalPayload(
PatchbayResponseSchema schema, Object? payload) → List< PatchbayResponseValidationIssue> - Validates the terminal event carried by a completed job-wait payload.
Typedefs
- PatchbayAuditExecutionDetailsDefectHandler = void Function(String reason)
-
Signature for patchbayProjectAuditEvent's
onExecutionDetailsDefectcallback: fired with one of patchbayAuditExecutionDetailsDefectReasons when a recognisably reveal-shaped accepted response violates a closed DG-060-04 bound. The projected event always omitsexecutionDetailsin that case regardless of whether a callback is supplied. -
PatchbayAuditSink
= FutureOr<
void> Function(PatchbayAuditEvent event) - PatchbayAuditSinkErrorHandler = void Function(Object error, StackTrace stackTrace, PatchbayAuditEvent event)
-
PatchbayBaseGate
= FutureOr<
PatchbayGateDecision> Function() -
PatchbayCancellationConfirmation
= Future<
void> Function(PatchbayInvocationCancellationReason reason) - Consumer proof that cancellation has stopped the underlying operation.
-
PatchbayCatalogSource
= Future<
Map< Function()String, Object?> > -
PatchbayCommandDecoder<
T> = T Function(Map< String, Object?> arguments) -
PatchbayCommandFailureHandler
= Map<
String, Object?> Function(Object failure, Map<String, Object?> arguments, String requestId, PatchbayCommandDescriptor descriptor) -
PatchbayCommandGate<
T> = FutureOr< Map< Function(T request, String requestId)String, Object?> ?> -
PatchbayCommandHandler<
T> = FutureOr< Map< Function(T request, String requestId)String, Object?> > -
PatchbayConsumerGate
= FutureOr<
PatchbayGateDecision> Function(String gateId) -
PatchbayContextCommandHandler<
T> = FutureOr< Map< Function(T request, String requestId, PatchbayInvocationContext context)String, Object?> > -
PatchbayContextInvocationSource
= Future<
Map< Function(String command, Map<String, Object?> >String, Object?> arguments, String requestId, PatchbayInvocationContext context) - PatchbayExtensionRegistrar = void Function(String method, ServiceExtensionHandler handler)
-
PatchbayInvocationSource
= Future<
Map< Function(String command, Map<String, Object?> >String, Object?> arguments, String requestId) -
PatchbayJobBody
= Future<
Map< Function()String, Object?> > -
PatchbayJobCancellation
= FutureOr<
void> Function() - Confirms that the underlying operation has stopped after cancellation.
- PatchbayMonotonicClock = Duration Function()
- Host-local monotonic time source used by invocation deadlines.
-
PatchbaySnapshotSource
= Future<
Map< Function()String, Object?> > -
PatchbayVersionedSnapshotSource
= Future<
PatchbaySnapshotSample> Function() - A snapshot source with an explicit, cheap content invalidation signal.
Exceptions / Errors
- PatchbayAuditDeliveryClosed
- Reports a ledger event recorded after audit delivery was closed.
- PatchbayAuditDeliveryOverflow
- Reports one complete burst of audit events dropped by bounded delivery.
- PatchbayAuditExecutionDetailsProjectionDefect
-
Reports that an accepted
ui.revealresponse could not be safely projected into PatchbayAuditEvent.executionDetails. - PatchbayBlobFailure
- PatchbayJobCancellationSignal
- A consumer-observed domain cancellation whose payload is already redacted.
- PatchbayJobCapacityExceeded
- Thrown synchronously when a registry has reached its running-job budget.
- PatchbayJobFailure
- A consumer-observed domain failure whose payload is already redacted.
- PatchbayLogRecordTooLarge
- PatchbayLogRedactionFailure
- PatchbayLogSourceContractFailure