mock
library
Classes
$$Params
$CreateParams <T >
Parameters for creating a new entity of type T.
$Credentials
$DeleteParams <I >
Parameters for deleting an entity of type I.
$InitializationParams
Parameters for initializing a repository or data source.
$ListQueryParams <T >
Parameters for querying a list of entities.
$QueryParams <T >
Parameters for querying a single entity by a field (usually ID or slug).
$Settings
$ToggleParams <I , F >
Parameters for toggling a boolean field of an entity.
$UpdateParams <I , P >
Parameters for updating an entity.
ActionRouter
Interface the UiRenderTool uses to deliver routed SemanticAction s
back to the agent (FR-004). Implementations translate to whatever the
agent runtime supports (tool result, steering message, etc.).
ActiveMissionInfo
Info about one active coalescing group.
AdapterSpec <T >
Configuration that specifies the generation of a TypeAdapter
AgentDirective
Typed directive consumed by zuraffa's AgentPlugin.
AgentExclude
Marks an entity or usecase so it never becomes an MCP tool.
AgentInternal
Sugar for @AgentRisk(AgentRiskTier.admin).
AgentKernel
The agent kernel — coordinates mission coalescing, cancellation, and
partial-salvage (issue #388).
AgentParamDirective
Per-parameter metadata within an AgentDirective .
AgentRisk
Declares the risk tier for an agent-exposed entity or usecase.
AgentRuntimePlugin
The runtime module plugin that assembles the tool registry, wires
the kernel, and manages the agent lifecycle (issue #386).
AgentState
Per-mission session state (FR-009).
AgentTool
Override the generated MCP tool identity for an entity or usecase.
AgentToolDirective
Tool identity information within an AgentDirective .
AgentToolParam
Provides a description for a field when it appears as a tool parameter
in the MCP inputSchema.
AlwaysMatch <TEntity >
A filter that always evaluates to true.
And <TEntity >
Logical AND combining multiple filters
AnnotatedElement
ApiEndpoint
Immutable metadata for a single registered UseCase VM Service extension.
AppendExecutor
AppendRequest
AppendResult
AppendStrategy
AppLocale
A BCP-47-ish locale tag (language-region).
AppRestartCachePolicy
App restart cache policy.
AppUpdatePort
The app-update contract.
AppUpdateService
App-facing update facade: check, gate, and launch.
ArgumentHasher
Hashes tool-call arguments (FR-008).
ArgumentSpec
ArtifactContext
Rich context passed to every ArtifactHook when an artifact is published.
ArtifactHook
Base class for artifact hooks.
ArtifactPublisher
Global singleton manager for artifact hooks.
ArtifactReference
A compact reference to an externally stored large result (FR-010).
AstHelper
AstModifier
AstParseResult
ASTScanner
Scans a Dart project for all decorator annotations and produces
ScanResult s containing MethodAST + DecoratorAST pairs.
Attribute
A representation of a single piece of metadata attached to trace span.
AuthDDAPlugin
DDA plugin that processes @RequiresAuth annotations on UseCase
classes or methods and generates security interceptor logic.
AuthGenerator
Generates lib/src/middleware/zfa_auth.g.dart from collected
@RequiresAuth annotation metadata.
BackgroundTaskContext <Params >
Context passed to the background task.
BackgroundUseCase <T , Params >
A UseCase that executes expensive operations on a separate isolate.
Baseline
A historical benchmark result kept for comparison (FR-009).
BaselineStore
Persistent storage for historical benchmark results (FR-009).
BenchmarkComparison
The result of comparing current metrics against a baseline (AC-10).
BenchmarkContract
The contract between benchmark scenarios and the benchmark framework
(FR-001, FR-015).
BenchmarkDryRunResult
The outcome of a dry run (FR-012): validation only, no execution.
BenchmarkRegistry
Central registry for discovering and managing registered scenarios
(FR-002).
BenchmarkRegistryError
A registry failure: machine-readable code plus a human message.
BenchmarkResult
Structured output of one benchmark scenario execution (FR-004).
BenchmarkRunner
Orchestrates execution of benchmarks, collects metrics, evaluates
thresholds (FR-004).
BenchmarkRunnerConfig
Runner-level configuration.
BenchmarkScenario
Convenience base class for scenarios (SC-001 ergonomics).
BenchmarkSuiteResult
Aggregate outcome of a benchmark suite run (FR-008).
BidirectionalSyncStrategy <T >
Bidirectional synchronization strategy.
BinaryReader
The BinaryReader is used to bring data back from the binary format on the
disk.
BinaryWriter
The BinaryWriter is used to encode data to the binary format.
BiometricsPort
The biometrics contract.
BiometricsService
App-facing biometrics facade with a permission-free safety net.
BoundInvocation
The invocation passed to a DiBinding.boundHandler (FR-007).
Box <E >
Boxes contain all of your data. In the browser, each box has its own
IndexedDB database. On all other platforms, each Box is stored in a
separate file in the Hive home directory.
BoxBase <E >
Boxes contain all of your data. In the browser, each box has its own
IndexedDB database. On all other platforms, each Box is stored in a
seperate file in the Hive home directory.
BoxCollection
TODO: Document this!
BoxEvent
A event representing a change in a box.
BudgetBreach
Typed budget-exceeded event (FR-006).
BudgetTracker
Tracks current usage against a MissionBudget and detects breaches.
BuildPipeline
Orchestrates the complete zfa build DDA pipeline.
BuildResult
BuiltInSessionPresets
Built-in session presets, instantiable with zero configuration
(spec FR-002 / SC-006): anonymous, authentication token, cookie,
header, OAuth, and API key.
Cacheable
Marks a repository or datasource method for auto-generated caching.
CacheBindingConfig
Configuration for cache binding generation.
CacheBindingPlugin
DDA plugin that detects @Cacheable on UseCase return types
and generates cache observer bindings in DomainState.
CacheDDAPlugin
DDA plugin that processes @Cacheable and @CacheInvalidate
annotations on repository/datasource methods and generates
caching wrapper logic.
CachedSchema
A cached schema artifact set: the introspection data, the parsed schema,
and the file locations it was loaded from.
CacheGenerator
Generates lib/src/cache/zfa_cache.g.dart from collected
@Cacheable and @CacheInvalidate annotation metadata.
CacheInvalidate
Marks a method as a cache invalidator.
CacheObserver
An observable cache that emits updates when entities change.
CachePolicy
Cache policy abstraction for determining cache validity.
CallbackObserver <T >
A simple Observer implementation using callbacks.
CancellationResult
Result of a cancellation sweep.
CancelToken
A token for cooperative cancellation of asynchronous operations.
CapturingActionRouter
In-memory ActionRouter capturing delivered actions for test inspection.
CliApp
The standardized entry point for a Zuraffa CLI app (FR-001).
CliContract
The standardized CLI contract for Zuraffa apps.
CliExitCodes
The exit-code vocabulary for the standard CLI contract (FR-002, FR-009).
CliGlobalFlag
A global flag specification (FR-002).
CliGlobalFlags
The standard set of global flags every Zuraffa CLI app recognizes (FR-002).
CliInvocation
A parsed command invocation — what the handler receives (FR-003).
ClipboardPort
The clipboard contract.
ClipboardService
App-facing clipboard facade.
CliPlugin
Metadata for the native, built-in standard CLI plugin (FR-010).
CliProgressReporter
CoalescingGroup
A coalescing group: one executing Mission + its subscribers (FR-002).
CodeBuilderFactory
CollectionBox <V >
represents a Box being part of a BoxCollection
CommandArgument
A positional argument declaration.
CommandFlag
A named flag declaration.
CommandRegistry
The shared command registry (FR-004, FR-005, FR-006).
CommandResult
The result of running a command (FR-001, FR-008).
CommonPatterns
CompletableUseCase <Params >
A UseCase that doesn't return a value.
CompositeScaffolder
CompositeScaffoldResult
ConflictDetector
ConsoleExporter
Console exporter for development/debugging.
ConstructorParam
Contains <TEntity , TValue >
Contains filter (e.g., for strings or lists)
Context
ContextKey
A key used to set and get values from a Context .
ContextStore
ControlledWidgetDetector
Detects usage of the legacy ControlledWidget base class.
CreateParams <T >
CreateParamsFields <T >
Field descriptors for CreateParams query construction
CreateParamsPatch
Credentials
CredentialsFields
Field descriptors for Credentials query construction
CredentialsPatch
CrossAppInvoker
Invokes another app's registered command by name through the registry
(FR-005).
DailyCachePolicy
Daily cache expiration policy.
DartTypeNamer
Datasource
Marks a class as a datasource implementation.
DatasourceGenerator
Generates fully implemented remote datasource classes.
DecoratorAST
Represents a parsed decorator annotation found on a class, method,
or field declaration.
DecoratorDispatcher
Dispatches scanned decorator annotations to their registered plugins
and accumulates generated code into GenerationResult s.
DefaultBenchmarkRunner
The built-in BenchmarkRunner .
DefaultFileSystem
DeleteParams <I >
DeleteParamsFields <I >
Field descriptors for DeleteParams query construction
DeleteParamsPatch
DependencyOverridesDetector
Detects dependency_overrides in pubspec.yaml that are v5-specific.
DependencyRequest
A request for a dependency, declared by a command's handler (FR-007).
DetectorResult
Result of running a single migration detector.
DeviceInfo
Immutable device/environment snapshot.
DevicePort
The device contract.
DeviceService
App-facing device facade.
DeviceStatus
Live connectivity + power reading.
DiBinding
Binds a SharedCommand 's handler to a host app's DiContainer (FR-007).
DiContainer
The DI container abstraction — apps implement this for their DI of choice
(GetIt, Provider, injectable, hand-rolled). The standard CLI plugin only
depends on this abstraction, never on a specific DI package.
DIGenerator
Generates lib/src/di/zuraffa_injection.g.dart from collected
@Datasource and @Repository metadata.
DiGenerator
Generates DI registration code for datasources and repositories.
DIPlugin
DDA plugin that processes @Datasource and @Repository annotations
and accumulates DI registration metadata.
DiRegistration
A single DI registration for a generated datasource + repository pair.
DisabledCachePolicy
A cache policy decorator that completely disables caching.
Disposable
If objects that are registered inside GetIt implements Disposable the
onDispose method will be called whenever that Object is unregistered,
reset or its enclosing Scope is popped
DocumentBuilder
Builds GraphQL query/mutation/subscription documents from schema metadata.
DocumentsDartGenerator
Generates documents.dart — a file with parsed DocumentNode constants
for every .graphql file in a directory.
DomainState
Base class for auto-generated DomainState .
DtoGenerator
Generates DTO classes from GraphQL INPUT_OBJECT types.
DualLayerPresenter
A presenter that strictly separates DomainState (auto-generated,
immutable, regenerated) from ViewState (developer-editable, preserved).
DurationConverter
EntityGenerator
Generates zorphy entity classes from GraphQL OBJECT types.
EntitySpec
Specification for an entity derived from a GraphQL object type.
EnumSpec
Specification for an enum derived from a GraphQL enum type.
Eq <TEntity , TValue >
Equality filter (e.g., field == value)
ErrorMappingConfig
Configuration for mapping GraphQL union error variants to
Zuraffa's AppFailure taxonomy.
ErrorResult
Failed command execution.
ExponentialBackoffRetryPolicy
Exponential backoff retry policy — the OpenTelemetry standard convention.
ExportAppendStrategy
Failure <S , F >
Failure case of Result
FailureContext
@deprecated Use ArtifactContext directly.
FailureHook
@deprecated Extend ArtifactHook instead.
FailureHookManager
@deprecated Use ArtifactPublisher.instance instead.
FailureReport
A single failure report with context.
FailureReporter
Abstract contract for reporting failures to external systems.
FailureReporterRegistry
Global singleton registry for failure reporters.
FailureReportQueue
In-memory bounded queue that batches failure reports for delivery.
FailureReportStore
Persists failure reports to a JSON file on disk.
FallbackLLMClient
Default LLM client wired by AgentRuntimePlugin (FR-007). Mirrors
dart_agent_core's FallbackLLMClient: tries the primary client; on
failure, falls back to the secondary.
FeatureJournal
The whole canonical stream for one feature — everything JournalReader
hands a tool, so the tool never opens a journal file itself.
FetchStrategy <Input , Output >
Strategy interface for pluggable data-fetching pipelines.
Field <TEntity , TValue >
Represents a field in a Zorphy entity TEntity with value type TValue.
Used for type-safe query construction and runtime evaluation.
FieldSpec
Specification for a single field in an entity.
FileGeneratorPlugin
A plugin that generates files.
FileOperation
FileParser
FileStateStorage
Persistence interface for AgentState (FR-009).
FileSystem
Filter <TEntity >
Base class for all filters
FilterConverter
Converter for Filter type.
FixedIntervalRetryPolicy
Fixed interval retry policy.
GenerateAdapters
Annotation to generate TypeAdapters for the given specs
GenerationContext
Encapsulates state and dependencies for a single generation session.
GenerationResult
Aggregated generation result for a single source file.
GenerationTransaction
Manages atomic file operations during generation.
GetIt
Very simple and easy to use service locator
You register your object creation factory or an instance of an object with registerFactory ,
registerSingleton or registerLazySingleton
And retrieve the desired object using get or call your locator as function as its a
callable class
Additionally GetIt offers asynchronous creation functions as well as functions to synchronize
the async initialization of multiple Singletons
GqlArgument
Represents a GraphQL field argument.
GqlConstStringDetector
Detects v5-style const-string GraphQL documents in Dart source files.
GqlEnumValue
Represents a GraphQL enum value.
GqlField
Represents a GraphQL field.
GqlFilePreserver
Preserves existing .graphql files that are still valid against the schema.
GqlMigrator
GqlSchema
Represents a complete GraphQL schema from introspection.
GqlTypeDef
Represents a GraphQL type definition.
GqlTypeRef
Represents a GraphQL type reference, which can be nested for NON_NULL/LIST wrappers.
GraphQLClientBuildResult
Result of building a GraphQLClient with optional WebSocketLink.
GraphQLClientConfig
Configuration for assembling a GraphQLClient.
GraphQLClientFactory
Factory that assembles a GraphQLClient from GraphQLClientConfig .
GraphQLClientProvider
Singleton provider for the configured GraphQLClient.
GraphqlCommand
CLI command: zfa graphql group.
GraphQLDocumentBuilder
Builds real .graphql files using package:gql AST nodes.
GraphQLEntityEmitter
Emits Dart entity and enum files from GraphQL schema specifications.
GraphQLEnumType
Enum type.
GraphQLField
Field on an object/interface type.
GraphqlGenerateCommand
CLI command: zfa graphql generate
GraphQLInputField
Input field (for input objects and field arguments).
GraphQLInputObjectType
Input object type (e.g. ProductListOptions).
GraphQLInterfaceType
Interface type.
GraphQLIntrospectionService
Service for fetching GraphQL schema via introspection.
GraphQLListType
List wrapper type.
GraphQLNonNullType
Non-null wrapper type.
GraphQLObjectType
Object type (e.g. Product, Order).
GraphQLScalarType
Scalar type (String, Int, Float, Boolean, ID, or custom).
GraphQLSchema
Parsed GraphQL schema with type lookup.
GraphQLSchemaTranslator
Translates GraphQL schema types to Dart-friendly specifications.
GraphQLType
Base class for all GraphQL types in the schema.
GraphQLUnionType
Union type (e.g. AddItemToOrderResult).
GraphQLValidator
Validates a GraphQL document AST against the cached schema.
Gt <TEntity , TValue >
Greater than filter
Gte <TEntity , TValue >
Greater than or equal filter
Has <TEntity , TElement >
List-contains-element filter (e.g., List
HiveAesCipher
Default encryption algorithm. Uses AES256 CBC with PKCS7 padding.
HiveCipher
Abstract cipher can be implemented to customize encryption.
HiveCollection <E extends HiveObjectMixin >
List containing HiveObjectMixin s.
HiveField
Annotate all fields you want to persist with HiveField .
HiveInterface
The main API interface of Hive. Available through the Hive constant.
HiveList <E extends HiveObjectMixin >
Allows defining references to other HiveObjectMixin s.
HiveObject
TODO: Document this!
HiveType
Annotate classes with HiveType to generate a TypeAdapter.
Hook
Base class for all Zuraffa hooks.
HookContext
Immutable context passed to every hook during UseCase execution.
HookDecision
Outcome of a tool call evaluation.
HookDecisionAllow
HookDecisionCancelMission
HookDecisionDeny
HookDecisionNeedsConfirmation
HookRegistry
Global singleton registry for all hooks.
I18nPort
The localization contract.
I18nService
App-facing localization facade.
IdempotencyCache
A TTL-bounded idempotency cache (FR-007).
IdGenerator
Generator capable of creating OTel compliant IDs.
Immutable
Annotation on an immutable class.
InitDependency
Data structure used to identify a dependency by type and instanceName
InitializationParams
InitializationParamsFields
Field descriptors for InitializationParams query construction
InitializationParamsPatch
InList <TEntity , TValue >
In list filter
InMemoryAppUpdateAdapter
Pure-Dart default adapter: scripted check results.
InMemoryBenchmarkRegistry
In-memory BenchmarkRegistry implementation.
InMemoryBiometricsAdapter
Pure-Dart default adapter (test/dev): scripted outcomes.
InMemoryClipboardAdapter
Pure-Dart default adapter (test/dev): holds one string.
InMemoryDeviceAdapter
Pure-Dart default adapter (test/dev): scriptable status + lifecycle.
InMemoryFileStateStorage
In-memory FileStateStorage used for tests and as a no-op fallback
when no real storage is configured.
InMemoryI18n
Pure-Dart I18nPort implementation: an in-memory table-backed
translator with locale fallback chains and live switching.
InMemorySecureStorage
Pure-Dart default backend (test/dev): an in-memory map with an
optional corruption seam.
InMemorySessionPersistence
Volatile in-memory persistence — the default backend.
InMemoryShareAdapter
Pure-Dart default adapter: records every share for assertions.
InstrumentationLibrary
Represents versioning metadata for this library within applications
which use multiple implementations of OpenTelemetry.
Introspection
Provides introspection endpoints for the kernel.
IntrospectionClient
IntrospectionHttpResponse
One HTTP round-trip result of an introspection POST.
IntrospectionSnapshot
Snapshot of the kernel's current state for operator introspection
(FR-008).
IsolateBenchmarkRunner
A BenchmarkRunner that executes every scenario in its own isolate.
IsolatedBox <E >
Isolated version of Box
IsolatedBoxBase <E >
Isolated version of BoxBase
IsolatedHiveInterface
Interface for IsolatedHive
IsolatedLazyBox <E >
Isolated version of LazyBox
IsolateNameServer
An abstraction of the IsolateNameServer
JournalBehavior
One registered behavior the journal tools reason about: the registry
record's id + the two files a prove fingerprints.
JournalEntry
One journal entry — one cycle's record (the issue's nine fields plus
the additive extras downstream tooling reads).
JournalReader
The ONE canonical read API (issue #1113 requirement 2): any tool —
theater, status, prove, simulate — reads the journal stream through
here, not N file-format parsers.
JournalSchema
The JSON Schema generator + entry validator for the unified journal.
JournalVerdict
The derived one-line verdict zfa tdd status prints from the
journal (issue #1113's shape):
JournalWriter
Appends entries to specs/<feature>/tdd/journal.json — the one
writer every cycle (engine/skin/meta, via the shared driver core, the
commands' gate refusals, and prove) funnels through. Atomic
(tmp + rename), and tdd/journal.schema.json lands beside the
journal on first append.
JsonBaselineStore
Filesystem-backed BaselineStore using one JSON file per scenario
(research.md decision: human-readable, git-friendly).
JsonConverter <T , S >
Implement this class to provide custom converters for a specific Type .
JsonEnum
Allows configuration of how enum elements are treated as JSON.
JsonKey
An annotation used to specify how a field is serialized.
JsonLiteral
An annotation used to generate a private field containing the contents of a
JSON file.
JsonSerializable
An annotation used to specify a class to generate code for.
JsonValue
An annotation used to specify how a enum value is serialized.
KernelConfig
Configuration for the AgentKernel (FR-010 — configurable coalescing
window; FR-009 — single-isolate documentation).
KernelStatus
Structured kernel status report (FR-011).
LazyBox <E >
LazyBox es don't keep the values in memory like normal boxes. Each time a
value is read, it is loaded from the backend.
List_E <E >
Enhanced List type for Zorphy with additional functionality
ListQueryParams <T >
ListQueryParamsFields <T >
Field descriptors for ListQueryParams query construction
ListQueryParamsPatch
LlmClient
LLM client interface (FR-007). Real implementations delegate to
dart_agent_core's FallbackLLMClient.
LoadingResult <S , F >
A loading/ pending result state.
Log
The facade root: zuraffa.log.info('hi', {'user': 'ada'}).
LogEntry
One structured log record (what handlers receive).
Lt <TEntity , TValue >
Less than filter
Lte <TEntity , TValue >
Less than or equal filter
ManualDiDetector
Detects manual get_it registration patterns that should use
@Datasource / @Repository annotations in v6.
McpServerPlugin
Runtime ZuraffaPlugin that exposes the host app's McpTool s
over the Model Context Protocol.
McpSseServer
SSE transport for the runtime MCP server.
McpStdioServer
stdio JSON-RPC 2.0 server that dispatches to a McpToolRegistry .
McpTool
A runtime MCP tool exposed by a Zuraffa app.
McpToolContext
Context passed to McpToolProvider.buildTools (FR-001). Acts as a
DI accessor so providers can resolve dependencies they were registered
with.
McpToolProvider
SPI interface implemented by device packages to declare their available
MCP tools under a namespace (FR-001, FR-002).
McpToolRegistry
In-process registry of McpTool s exposed by a Zuraffa app.
McpToolResult
Result returned by an McpTool.call invocation.
MethodAppendStrategy
Appends or replaces methods inside a class declaration.
MethodAST
Metadata about the annotated element.
MetricChange
The change of a single metric between baseline and current (FR-010).
MetricCollector
Extensible interface for capturing custom metrics during benchmark
execution (FR-006).
MetricContext
The context handed to a MetricCollector at each lifecycle point.
MigrationAction
A migration action that was applied (or would be applied in dry-run).
MigrationDetector
Base class for all v5 pattern detectors.
MigrationFinding
A single finding from a v5 pattern scan.
MigrationFixer
Base class for migration fixers.
MigrationReport
Aggregated report for zfa doctor or zfa migrate.
MigrationResult
Result of running a migration fixer.
MinIOArtifactHook
Artifact hook that uploads artifacts to MinIO/S3-compatible storage.
MinioClient
A lightweight S3-compatible client for MinIO operations.
MinIOUploadHook
@deprecated Use MinIOArtifactHook instead.
Mission
The kernel's structured input (FR-008).
MissionBudget
Per-mission budget across four dimensions (FR-005).
MissionBudgetHook
Policy hook that enforces four-dimension mission budgets (FR-005,
FR-006). On breach, emits a typed BudgetBreach event via
onBreach and cancels the mission by returning a
HookDecisionCancelMission .
MissionEvent
Typed events streamed by AgentKernel.runMission (FR-008).
MissionEventAssistantMessage
MissionEventCancelled
Mission was cancelled; partials salvaged as cancelled_partial.
MissionEventCompleted
MissionEventFailed
MissionEventPartial
Partial result emitted mid-execution.
MissionEventProgress
Progress tick — non-result status update.
MissionEventStarted
MissionEventToolCallResult
MissionEventToolCallStart
MissionKey
Composite key identifying a coalescable mission (FR-001).
MissionOutcome
Terminal outcome of a mission (one of completed, cancelled_partial,
failed, cached_served).
MissionTrace
The mission trace (FR-007).
MissionTraceEntry
One recorded entry in a mission's render trace.
MissionTraceRecorder
Records the mission trace (FR-007, FR-008, FR-009).
MutationConfig
Configuration for a generated mutation method.
NamingUtils
Pure-static utility class for GraphQL codegen naming.
Neq <TEntity , TValue >
Not equal filter (e.g., field != value)
Nested <TEntity , TValue >
Nested object or collection filter
NodeFinder
NodeRegistry
The authoritative node registry (spec Key Entities).
NonViewTargetInfo
A @Route annotation the scanner collected but could not accept as a
route (non-View class, method target, missing path, malformed redirect).
NoopSpan
No-op span returned when telemetry is disabled or trace is unsampled.
NoParams
A sentinel class for UseCases that don't require parameters.
NoRetryPolicy
No retry policy — fire once, drop on failure.
Not <TEntity >
Logical NOT negating a filter
NullProgressReporter
ObjectRegistration <T extends Object >
Observer <T >
Observer for StreamUseCase callback-based listening.
OperationSpec
Opt <T >
Optional type wrapper for Zorphy
Or <TEntity >
Logical OR combining multiple filters
OsBackgroundTask
A use-case abstraction for OS-scheduled background tasks wrapping
workmanager (iOS / Android / macOS).
OsBackgroundTaskDescriptor
Descriptor for registering an OsBackgroundTask with the OS scheduler.
OsBackgroundTaskSchedule
Scheduling configuration for an OsBackgroundTask .
OsBackgroundTaskUseCase <T >
Abstract base class for OS-scheduled background task use cases.
OtelFailureReporter
OpenTelemetry failure reporter — shipped opinionated with Zuraffa.
OtelLogExporter
Exports LogRecords to an OpenTelemetry collector via OTLP/HTTP.
OtelTracer
Thin singleton for creating and managing application-level OTel traces.
OutcomeCachedServed
OutcomeCancelledPartial
OutcomeCompleted
OutcomeFailed
OutputFormat
The output format renderer for the standard CLI contract (FR-008).
OversizedResultGuard
Intercepts tool results exceeding threshold bytes and replaces them
with an ArtifactReference before they enter model context (FR-010).
PackageAgentTools
Namespaced agent-tool bridge for Zuraffa-native packages (spec 025,
FR-008/FR-009).
PackageCompatibility
Parses the constraint forms the package SDK itself emits and compares
them against a concrete running version.
PackageCompatibilityResult
Result of PackageCompatibility.check .
PackageMode
Package-mode marker detection for the v6 package SDK (spec 025,
FR-010/FR-011).
PackageModule
Runtime module contract for Zuraffa-native packages (spec 025,
FR-006/FR-007).
PackageUseCaseTool <T extends Object >
A ready-made McpTool adapter that resolves a usecase from a DI
container and invokes it (spec 025, FR-008).
ParameterInfo
Params
ParamsFields
Field descriptors for Params query construction
ParamsPatch
PartialSalvager
Salvages partial results from a cancelled mission into the mission
record with a cancelled_partial outcome (FR-005).
Patch <T >
Patch interface for Zorphy code generation
PatchBase <TEntity , TEnum extends Enum >
PermissionRegistry
Registry mapping tool name patterns to RiskLevel s (FR-001).
PersistenceTestHarness
Per-test Hive CE temp-box harness (bug #833, remediation 1).
PluginDiscovery
Discovers and loads ZorphyDecoratorPlugin s from packages listed in
pubspec.yaml under the zuraffa_decorators key.
PluginRegistry
Registry for managing the lifecycle of generation plugins.
PolicyDecision
A pending policy decision for one SemanticAction .
PolicyGate
Intercepts confirm-tier actions and gates them behind user approval
(spec FR-006).
PolicyHook
A composable policy hook that intercepts the agent loop (FR-011).
PolicyShell
Composes policy hooks in registration order (FR-011).
ProgressReport
ProgressReporter
PushOnlySyncStrategy <T >
Default push-only synchronization strategy.
QueryConfig
Configuration for a generated query method.
QueryParams <T >
QueryParamsFields <T >
Field descriptors for QueryParams query construction
QueryParamsPatch
ReadonlySignal <T >
A read-only view of a Signal .
RecordUse
Annotation on a statically resolved member or class whose usages will be
recorded.
RedirectRuleInfo
Public snapshot of one collected redirect rule.
RegisteredCommand
A registered command, with its owner app and registration metadata.
RegistryKey
The composite key for the registry: (ownerApp, name).
RemoteMcpServer
A remote MCP server registered with the runtime plugin.
RenderedView
A live, interactive UI instance produced by the agent (spec Key Entities).
RepoMethod
Configuration for a generated repository method.
ReportRetryPolicy
Abstract retry strategy for failure report delivery.
Repository
Marks a class as a repository implementation.
RepositoryFactory
RepositoryGenerator
Generates repository interfaces and implementations.
RepositoryMethodSpec
RepositoryPatterns
RepositoryPlugin
RepositorySpecConfig
Required
Annotation on a required named parameter.
RequiresAuth
Marks a UseCase class or method as requiring authentication/authorization.
ResolvedMessage
A resolved translation with its substitutions already applied.
ResourceAttributes
Common OpenTelemetry attribute keys for resource information.
ResourceHandle
A disposable resource handle that participates in cancellation
(FR-004, FR-006). Examples: webview pool entry, network request,
open stream.
Result <S , F >
Result type for Clean Architecture
Retry
Marks a UseCase or datasource method for automatic retry on failure.
RetryDDAPlugin
DDA plugin that processes @Retry annotations on UseCase
or datasource methods and generates retry wrapper logic.
RetryGenerator
Generates lib/src/middleware/zfa_retry.g.dart from collected
@Retry annotation metadata.
Role
Role hierarchy for authorization checks.
RouteBuildResult
Outcome of one route build stage run.
RouteBuildStage
The zfa build route stage (spec 033, FR-002): scans a project's lib/
for @Route / @ZfaRoute annotations, validates the collected
configuration (FR-006), and compiles everything into the single generated
router file lib/src/routing/zfa_router.g.dart.
RouteDDAPlugin
DDA plugin that processes @ZfaRoute (and @Route) annotations and
collects route metadata for GoRouter configuration generation.
RouteEntryInfo
Public snapshot of one collected route (what the validator and generator
operate on).
RouteFactory
RouteGenerator
Generates lib/src/routing/zfa_router.g.dart from collected
@ZfaRoute annotation metadata.
RouteParams
Base class for generated route parameter classes.
RouteSpecConfig
RouteValidationError
A single actionable validation failure.
RouteValidator
Validates collected route metadata. Pure: data in, errors out.
ScanResult
ScenarioValidation
Metadata validation shared by the registry and the dry-run path (AC-2).
SchemaCache
Caches and loads GraphQL introspection schemas.
SchemaChange
A single detected difference between two schema versions.
SchemaDiff
The result of diffing two schemas.
SchemaDiffer
SchemaParser
Parses a GraphQL introspection JSON response into a GraphQLSchema .
SdlPrinter
SecretStore
App-facing convenience over SecureStoragePort : typed accessors for
the two shapes every caller stores — tokens (String) and arbitrary
JSON maps — plus raw map access.
SecureStorageCodec
JSON-string codec for SecureStoragePort entries — the wire form a
platform adapter stores inside its native vault (Keychain/Keystore/
encrypted file).
SecureStoragePort
The secure-storage contract: typed JSON value storage at rest.
SemanticAction
A user interaction captured from a rendered view (spec Key Entities).
SemanticAttributes
Common OpenTelemetry attribute keys for non-resource information.
Session
A single unit of session state: a type (preset name), a unique id ,
a caller-chosen key inside its scope, and a schema-free payload .
SessionContainer
A generic, platform-agnostic session container (spec FR-001/FR-005/
FR-006/FR-007).
SessionMetadata
Bookkeeping attached to a Session .
SessionPersistence
A persistence backend for serialized session envelopes.
SessionPreset
A named, reusable template for a common session kind (spec FR-002).
SessionPresetRegistry
Registry of known session presets: the built-ins plus any custom
presets applications register (spec FR-003).
Settings
SettingsFields
Field descriptors for Settings query construction
SettingsPatch
ShadowChangeHandlers
If an object implements the ShadowChangeHandler if will get notified if
an Object with the same registration type and name is registered on a
higher scope which will shadow it.
It also will get notified if the shadowing object is removed from GetIt
SharedCommand
A StandardCommand published for cross-app reuse (FR-006).
SharePort
The share contract.
ShareRequest
One share request as the platform received it.
ShareService
App-facing share facade with empty-payload validation.
Signal <T >
A zero-cost reactive signal primitive for zuraffa.
SignalResult <T >
A reactive wrapper around Result<T, AppFailure> backed by a Signal .
SignalSlice <T >
A fine-grained reactive slice that wraps a SignalResult<T> .
SignalSubscription
Lightweight subscription handle. Call cancel to unsubscribe.
SliceOrchestrator
Orchestrates the full-stack code generation for a GraphQL schema slice.
SlicePresenter
A presenter that manages multiple SignalSlice s — one per UseCase.
Sort <TEntity >
Represents a sort operation on a field
SortConverter
Converter for Sort type.
SourceLocation
Location within a source file for precise error reporting.
Span
A representation of a single operation within a trace.
SpanContext
Representation of the context of an individual span.
SpanEvent
A representation of a collection of metadata attached to a trace span.
SpanException
SpanExporter
SpanId
Class representing an ID for a single api.Span .
See https://www.w3.org/TR/trace-context/#parent-id for full specification.
SpanLink
SpanProcessor
SpecLibrary
StandardCommand
A declarative CLI command (FR-003).
StandardMetricCollector
The built-in collector producing the six standard metrics (FR-004, AC-5).
StandardMetrics
The standard metric vocabulary and shared statistics.
StateDetector
Detects v5-style mixed state classes that lack the v6 DomainState/ViewState split.
StatefulAgent
SPI for dart_agent_core's StatefulAgent (FR-005, FR-013).
StateGenerator
Generates dual-layer state files:
StateMigrator
StrategyPlugin
Generates FetchStrategy skeletons for pluggable data-fetching pipelines.
StrategySelector <Input , Output >
Selects a FetchStrategy for a given Input at runtime.
StreamToSignalResultAdapter <T >
Adapter for migrating v5 Stream<Result<T, AppFailure>> use cases to v6.
StreamUseCase <T , Params >
A UseCase for streaming/reactive operations.
StructuredLogger
A structured logger: named, hierarchical, with typed fields.
StubStatefulAgent
A stub StatefulAgent that emits a start + completed event pair.
Used in tests and as a fallback when dart_agent_core is not on the
path.
SubscriptionConfig
Configuration for a generated subscription method.
SubscriptionStream <T >
Converts a GraphQL subscription Stream into a SignalResult -compatible
stream for use with StreamToSignalResultAdapter .
Success <S , F >
Success case of Result
SuccessResult
Successful command execution.
SyncConfig
Configuration for sync behavior.
SyncMetadata
Metadata record tracking the sync state of a single entity instance.
SyncMetadataStore
Hive-backed persistence layer for SyncMetadata records.
SyncStrategy <T >
Strategy interface for offline-first synchronization.
SyncUseCase <T , Params >
Base class for synchronous UseCases that return immediately without async.
SystemPromptComposer
Composes the system prompt from playbook text + tool manifests (FR-006).
TelemetryExporter
TelemetryHook
Automatically wraps every UseCase execution in an OpenTelemetry span.
TelemetryMesh
Global telemetry coordinator for zuraffa.
TestClock
Injectable clock for persistence assertions (bug #833, remediation 2).
TestObserver <T >
Test utilities for zuraffa.
TextMapGetter <C >
Interface that allows a api.TextMapPropagator to read propagated fields from a carrier.
TextMapPropagator <C >
A class responsible for performing the injection and extraction of a
cross-cutting concern value as string key/values pairs into carriers that
travel across process boundaries.
TextMapSetter <C >
Class that allows a api.TextMapPropagator to set propagated fields into a carrier.
ThresholdConfig
Whether a threshold violation fails the benchmark or only warns (FR-005).
Pass/fail criteria for a single metric (FR-005).
ThresholdViolation
A threshold that was exceeded during benchmark execution (FR-005).
ToggleParams <I , F >
ToggleParamsFields <I , F >
Field descriptors for ToggleParams query construction
ToggleParamsPatch
ToolCallContext
Context for a tool call passed to AgentHook.beforeToolCall.
ToolCallRecord
A single tool-call record in the mission trace (FR-007).
ToolDecision
Decision returned by AgentHook.beforeToolCall to short-circuit a
tool call.
ToolDecisionAllow
ToolDecisionDeny
ToolGatingHook
Policy hook that gates tool calls based on the PermissionRegistry
(FR-001, FR-002, FR-003, FR-004, FR-012).
ToolResult
Result returned by a tool.
TraceFlags
A class which controls tracing flags for sampling, trace level, and so forth.
See https://www.w3.org/TR/trace-context/#trace-flags for full specification.
TraceId
Class representing an ID for a single Trace.
See https://www.w3.org/TR/trace-context/#trace-id for full specification.
Tracer
An interface for creating api.Span s and propagating context in-process.
TracerProvider
A registry for creating named api.Tracer s.
TraceState
Representation of the state of a trace.
TrackEvent
Marks a UseCase method for automatic telemetry event tracking.
TrackEventDDAPlugin
DDA plugin that processes @TrackEvent annotations on UseCase
methods and generates telemetry injection logic.
TrackEventGenerator
Generates lib/src/middleware/zfa_events.g.dart from collected
@TrackEvent annotation metadata.
TransactionResult
Represents the outcome of a GenerationTransaction .
TtlCachePolicy
Time-to-live (TTL) cache policy.
TypeAdapter <T >
Type adapters can be implemented to support non primitive values.
TypeMapper
Maps GraphQL types to Dart types for code generation.
TypeRegistry
TypeRegistries contain the TypeAdapter s associated with a typeId.
UiChildrenConstraint
Children constraint of a node definition.
UiEventChannel
A broadcast stream of UiRenderEvent s.
UiNode
A node in an agent-authored component tree.
UiNodeDefinition
A node definition in the vocabulary.
UiPayloadError
One diagnostic: category + actionable message + tree path.
UiPayloadValidationResult
UiPayloadValidator
UiPropDefinition
One property of a node definition.
UiRenderEvent
A single event on the UI render stream.
UiRenderEventDone
The render stream is complete (no more partials coming).
UiRenderEventError
An error during render / validation. Carries the typed exception so the
host UI / agent can branch on the error kind (FR-002).
UiRenderEventInteraction
A user interaction has been captured on a rendered tree (FR-004).
UiRenderEventPolicy
A policy decision has been made for a confirm-tier action (FR-006).
UiRenderEventRender
A tree (or partial tree) has been rendered and is ready for the host UI to
paint (FR-001, FR-003).
UiRenderEventReplace
A previous view has been replaced by a new tree (FR-001 acceptance 2).
UiRenderInputSchema
Derives the agent ui.render tool input schema directly from an
exported vocabulary artifact (SC-004 — "consumed as-is ... with no
manual transformation").
UiRenderTool
The agent-facing ui.render tool (spec FR-001).
UiVocabularyExportCapability
MCP-discoverable capability exposing the UI vocabulary schema export
(spec 024 FR-006).
UiVocabularySchema
The canonical UI Vocabulary Schema (spec Key Entities).
UnionGenerator
Generates sealed class hierarchies from GraphQL UNION types.
UnionResultHandler
Generates the union-result handling code emitted into generated
datasources, mapping error variants to AppFailure and success variants
to the sealed union object.
UpdateInfo
The outcome of an update check.
UpdateParams <I , P >
UpdateParamsFields <I , P >
Field descriptors for UpdateParams query construction
UpdateParamsPatch
UseCase <T , Params >
Base UseCase class for Clean Architecture.
UseCaseBinding
Metadata for a UseCase → slice binding.
UseCaseFactory
UseCasePatterns
UseCasePlugin
Manages use case generation for the domain layer.
UseCaseSpecConfig
UseResult
Annotation on function or property whose value must not be ignored.
ValidationError
A validation error with precise location and severity.
ValidationResult
ViewState
Base class for developer-extended ViewState .
ViewStateField
Metadata for a ViewState transient field.
ViewTemplateGenerator
Generates zfa make-style view templates using ControlledWidget,
FragmentBuilder, and SignalBuilder.
VocabularyNarrowingConfig
Per-mission-type vocabulary configurations. Production apps declare these
via configuration, not code (spec Assumptions).
VocabularySchemaExporter
VpcFactory
VpcPatterns
VpcSpecConfig
W3CTraceContextPropagator
WarningResult
Successful but with a warning the user should see (exit code 0, but the
output's outcome is 'warning' so a pipeline can detect it).
WillSignalReady
If your singleton that you register wants to use the manually signalling
of its ready state, it can implement this interface class instead of using
the signalsReady parameter of the registration functions
(you don't really have to implement much ;-) )
ZfaRoute
Marks a View class as a route with the given path .
Zorphy
Zorphy2
Deprecated alias of Zorphy . Behaves identically since zorphy 2.0;
will be removed in a later major release.
ZorphyContext
Context passed to each ZorphyDecoratorPlugin during code generation.
ZorphyDecoratorPlugin
Abstract base class for all DDA (Decorator-Driven Architecture) plugins.
ZorphyNamedConstructor
Annotation to declare a named constructor with a custom body on the
generated concrete class.
ZorphyPluginRegistry
Registry of all active decorator plugins.
ZorphyX
Zuraffa
Global configuration and utilities for Zuraffa.
ZuraffaApiBridge
VM Service extension bridge for Zuraffa.
ZuraffaContainer
Lightweight dependency-injection container for zuraffa.
ZuraffaContext
Lightweight correlation context carrier flowing from UI → UseCase → Data.
ZuraffaDIContainer
A lightweight dependency-injection container that wraps GetIt .
ZuraffaEngine
Central engine that discovers, wires, and initialises
ZuraffaPlugin instances.
ZuraffaPlugin
Abstract contract that every Zuraffa micro-frontend plugin must
implement.
ZuraffaRouteGuard
Base class for route guard / middleware implementations.
ZuraffaRouteState
Pure-Dart route state passed to ZuraffaRouteGuard callbacks.
ZuraffaSpan
A single operation span within a trace.
ZuraffaTrace
A complete trace — a tree of spans sharing a traceId.
ZuraffaUseCase <In , Out >
Base contract for all zuraffa use cases (v6).
Mixins
CacheMutator <T >
Mixin for UseCases that update the cache after mutation.
DisposableUseCase <In , Out >
Mixin for use cases that need manual disposal of internal signals.
FailureHandler
Mixin that provides failure handling capabilities to a class.
HiveObjectMixin
Extend HiveObject to add useful methods to the objects you want to store
in Hive
Loggable
Mixin that provides a Logger instance to a class.
Extensions
CacheBinding SignalSlice <T >
Binds a SignalSlice<T> to the CacheObserver for automatic
cross-view state synchronization.
CancelTokenFutureExtension Future <T >
Extension methods for using CancelToken with Future
CancelTokenStreamExtension Stream <T >
Extension methods for using CancelToken with Stream
CollectionFieldOps Field <TEntity , List <TElement >
CreateParamsCompareE CreateParams
CreateParamsPropertyHelpers CreateParams <T >
CreateParamsSerialization CreateParams <T >
CredentialsCompareE Credentials
CredentialsSerialization Credentials
DeleteParamsCompareE DeleteParams
DeleteParamsPropertyHelpers DeleteParams <I >
DeleteParamsSerialization DeleteParams <I >
ErrorToFailure Error
Extension to convert errors to failures
ExceptionToFailure Exception
Extension to convert exceptions to failures
FieldOps Field <TEntity , TValue >
Extension methods for easier filter creation
FieldSortOps Field <TEntity , TValue >
Extension methods for sorting on fields
FilterListToListQueryExtension Iterable <Filter <T >
Extension methods for converting a list of Filter s to a single Filter or ListQueryParams .
FilterListToQueryExtension Iterable <Filter <T >
Extension methods for converting a list of Filter s to a single Filter or QueryParams .
FilterOps Filter <TEntity >
FilterToListQueryExtension Filter <T >
Extension methods for converting Filter to ListQueryParams .
FilterToQueryExtension Filter <T >
Extension methods for converting Filter to QueryParams .
FutureNullableExtension Future <T? >
Extension for handling nullable futures.
FutureResultExtension Future <Result <S , F >
Extension methods for Future<Result> .
FutureResultExtensions Future <Result <S , F >
Extension methods for Future<Result>
FutureResultListExtension Iterable <Future <Result <S , F >
Extension for combining multiple Result futures.
FutureToResultExtension Future <T >
Extension methods for converting Future to Result .
GraphQLClientSubscription
Extension for easy subscription-to-SignalResult conversion.
InitializationParamsCompareE InitializationParams
InitializationParamsPropertyHelpers InitializationParams
InitializationParamsSerialization InitializationParams
ListQueryParamsCompareE ListQueryParams
ListQueryParamsExtension ListQueryParams
ListQueryParamsPropertyHelpers ListQueryParams <T >
ListQueryParamsSerialization ListQueryParams <T >
NestedFilterToQueryExtension Field <TEntity , TValue >
Extension to support nested filtering with QueryParams and ListQueryParams .
NestedIterableFilterToQueryExtension Field <TEntity , List <TElement >
Extension to support nested filtering for Iterable fields.
NestedNullableIterableFilterToQueryExtension Field <TEntity , List <TElement > ?
Extension to support nested filtering for nullable Iterable fields.
NullableStringFieldOps Field <TEntity , String ?
ObserverStreamExtension Stream <Result <T , AppFailure
Extension to use Observer with StreamUseCase .
OptExtension
Extension to allow calling opt() on any value
ParamsCompareE Params
ParamsPropertyHelpers Params
QueryParamsCompareE QueryParams
QueryParamsExtension Iterable <T >
Extension to query a single entity from an iterable using QueryParams.
QueryParamsPropertyHelpers QueryParams <T >
QueryParamsSerialization QueryParams <T >
ReadonlySignalExtension Signal <T >
ResultAsyncExtensions Result <S , F >
Extension methods for Result with async operations
ResultFailureHooks Result <S , F >
Extension on Result for triggering failure hooks on failure.
SessionContainerPersistence SessionContainer
SettingsCompareE Settings
SettingsSerialization Settings
StreamUseCaseExtensions StreamUseCase <T , Params >
Extension methods for convenient StreamUseCase operations
StringFieldOps Field <TEntity , String
ToggleParamsCompareE ToggleParams
ToggleParamsPropertyHelpers ToggleParams <I , F >
ToggleParamsSerialization ToggleParams <I , F >
UpdateParamsCompareE UpdateParams
UpdateParamsPropertyHelpers UpdateParams <I , P >
UpdateParamsSerialization UpdateParams <I , P >
ZorphyQueryIterableExt Iterable <T >
Extension methods for in-memory querying of iterables
Constants
alwaysThrows → const Object
Annotation marking a function as always throwing.
awaitNotRequired → const Object
Annotation on asynchronous function whose Future can be ignored.
checked → const Object
Annotation that no longer has any effect.
doNotStore → const Object
Annotation on function or property whose value must not be stored.
doNotSubmit → const Object
Annotation marking declaration that should be removed before publishing.
experimental → const Object
Annotation marking declaration as experimental and subject to change.
factory → const Object
Annotation on a function that creates new objects.
immutable → const Immutable
Annotation on an immutable class.
internal → const Object
Annotation on declaration that should not be used outside of its package.
isTest → const Object
Annotation on a test framework function that introduces a single test.
isTestGroup → const Object
Annotation on a test framework function that introduces a group of tests.
kSessionEnvelopeVersion → const int
The serialized wire format's schema version. Bumped on breaking
envelope changes; readers reject envelopes from the future with a
recoverable ZuraffaSessionException .
literal → const Object
Annotation on constructor that must be invoked with const if possible.
mustBeConst → const Object
Annotation on a parameter whose arguments must be constants.
mustBeOverridden → const Object
Annotation on instance members that must be overridden by subclasses.
mustCallSuper → const Object
Annotation on instance member that overriding members must call.
nonVirtual → const Object
Annotation on instance member that must not be overridden.
optionalTypeArgs → const Object
Annotation on type arguments that can safely be omitted.
protected → const Object
Annotation on instance member that should only be used by subclasses.
redeclare → const Object
Annotation on extension type members which redeclare superinterface members.
reopen → const Object
Annotation on declaration with less access restrictions than superinterface.
required → const Required
Annotation on named parameter that should always have an argument supplied.
sealed → const Object
Annotation on class that must not be subclassed outside of its package.
useResult → const UseResult
Annotation on function or property whose value must not be ignored.
version → const String
virtual → const Object
Annotation which no longer has any effect.
visibleForOverriding → const Object
Annotation on declaration that should not be used outside of its package.
visibleForTesting → const Object
Annotation on a public declaration that should only be used in tests.
zorphy → const Zorphy
normal class; prepend class with a single dollar & make abstract
zorphy2 → const Zorphy2
Deprecated alias of zorphy .
zuraffaMockLibrary → const bool
Detectable marker: this project uses zuraffa-native mocking.
ZValueObject → const Zorphy
Annotation alias for a value object: @ZValueObject expands to
@Zorphy(kind: ZorphyKind.valueObject).
Functions
$checkedConvert <T > (Map map , String key , T castFunc (dynamic Object ?readValue (Map String → T
Helper function used in generated code when
JsonSerializableGenerator.checked is true.
$checkedCreate <T > (String className , Map map , T constructor (S S >(String S Object ?Object ?readValue (Map String Map <String String fieldKeyMap = const {} → T
Helper function used in generated code when
JsonSerializableGenerator.checked is true.
$checkedNew <T > (String className , Map map , T constructor (), {Map <String String ?fieldKeyMap → T
Helper function used in generated code when
JsonSerializableGenerator.checked is true.
$checkKeys (Map map , {List <String ?allowedKeys , List <String ?requiredKeys , List <String ?disallowNullValues → void
Helper function used in generated fromJson code when
JsonSerializable.disallowUnrecognizedKeys is true for an annotated type or
JsonKey.required is true for any annotated fields.
$enumDecode <K extends Enum , V > (Map <K , V > enumValues , Object ?source , {K? unknownValue → K
Returns the key associated with value source from enumValues, if one
exists.
$enumDecodeNullable <K extends Enum , V > (Map <K , V > enumValues , Object ?source , {Enum ?unknownValue → K?
Returns the key associated with value source from enumValues, if one
exists.
buildStatus (McpToolRegistry registry , {Map <String String providers = const <String, String>{} , Map <String String remoteServerHealth = const <String, String>{} → KernelStatus
Builds KernelStatus from a McpToolRegistry + remote server map.
compareBaselines (Baseline baseline , Map <String num current , {num tolerancePercent = 10 , Map <String bool ?lowerIsBetterOverride → BenchmarkComparison
Compares current metrics against baseline (FR-010, AC-10, AC-11).
computeContentHash (UiNode tree → String
Computes a stable content hash for a UiNode tree (FR-008).
contextWithSpan (Context parent , Span span → Context
contextWithSpanContext (Context parent , SpanContext spanContext → Context
delayedFailure <T > (AppFailure failure , {Duration delay = const Duration(milliseconds: 100) → Future <Result <T , AppFailure
Create a delayed Future that completes with a Result.failure .
delayedSuccess <T > (T value , {Duration delay = const Duration(milliseconds: 100) → Future <Result <T , AppFailure
Create a delayed Future that completes with a Result.success .
failureFuture <T > (AppFailure failure → Future <Result <T , AppFailure
Create a Future that completes with a Result.failure .
failureResult <T > (AppFailure failure → Result <T , AppFailure
Create a Result.failure for testing.
getFromJsonToGenericFn (Map <List <String dynamic Function(Map <String dynamic > > fns , Map <String dynamic > json , List <String genericType → dynamic
Resolves the matching fromJson function for the provided generic type ids.
getGenericToJsonFn (Map <Type Object ? Function(Never fns , Type type → Object ? Function(Never
Resolves a generic toJson function for the provided type.
hashObjects (Iterable objects → int
Generates a hash code for multiple objects.
isResultFailure <S , F > (Result <S , F > result → bool
Check if a Result is a Failure
isResultFailureOfType <F extends AppFailure > (Result <dynamic , AppFailure result → bool
Check if a Result is a Failure of a specific type
isResultSuccess <S , F > (Result <S , F > result → bool
Check if a Result is a Success
journalFileFingerprint (String ?path → Future <String ?
sha256 of path's bytes; null when the file does not exist — the
prove baseline's fingerprint primitive (a file appearing or
disappearing is a change).
pluralCategoryFor (int count , AppLocale locale → PluralCategory
Recovers the CLDR cardinal plural category for count in locale.
registerAppUpdateDependencies (GetIt getIt , {AppUpdatePort ?port , String currentVersion = '0.0.0' → void
Registers the app-update stack onto getIt.
registerBiometricsDependencies (GetIt getIt , {BiometricsPort ?port → void
Registers the biometrics stack onto getIt.
registerClipboardDependencies (GetIt getIt , {ClipboardPort ?port → void
Registers the clipboard stack onto getIt.
registerDeviceDependencies (GetIt getIt , {DevicePort ?port → void
Registers the device stack onto getIt.
registerGlobalContextManager (ContextManager contextManager → void
registerGlobalTextMapPropagator (TextMapPropagator textMapPropagator → void
registerGlobalTracerProvider (TracerProvider tracerProvider → void
registerI18nDependencies (GetIt getIt , {required TranslationTable tableFor (), AppLocale ?initialLocale → void
Registers the i18n stack onto getIt with a table built by
tableFor (apps load their own translations; the loader decides the
source — assets, files, network).
registerSecureStorageDependencies (GetIt getIt , {SecureStoragePort ?storage → void
Registers the secure-storage stack onto getIt.
registerShareDependencies (GetIt getIt , {SharePort ?port → void
Registers the share stack onto getIt.
resultFailureContains (Result <dynamic , AppFailure result , String substring → bool
Check if a Result failure message contains a substring
runCancellation (CancelToken token , List <ResourceHandle handles → Future <CancellationResult
Runs the cancellation protocol against handles using token.
Returns a CancellationResult once the grace period completes.
spanContextFromContext (Context context → SpanContext
spanFromContext (Context context → Span
successFuture <T > (T value → Future <Result <T , AppFailure
Create a Future that completes with a Result.success .
successResult <T > (T value → Result <T , AppFailure
Create a Result.success for testing.
throwIf (bool condition , Object error → void
Two handy functions that help me to express my intention clearer and shorter to check for runtime
errors
throwIfNot (bool condition , Object error → void
trace <T > (String name , Future <T > fn (), {Context ?context , Tracer ?tracer , bool newRoot = false , List <Attribute spanAttributes = const [] , SpanKind spanKind = api.SpanKind.internal , List <SpanLink spanLinks = const [] → Future <T >
Records a span of the given name for the given function with a given
api.Tracer and marks the span as errored if an exception occurs.
traceContext <T > (String name , Future <T > fn (Context Context ?context , Tracer ?tracer , bool newRoot = false , SpanKind spanKind = api.SpanKind.internal , List <SpanLink spanLinks = const [] → Future <T >
Records a span of the given name for the given function with a given
api.Tracer and marks the span as errored if an exception occurs.
traceContextSync <T > (String name , T fn (Context Context ?context , Tracer ?tracer , bool newRoot = false , SpanKind spanKind = api.SpanKind.internal , List <SpanLink spanLinks = const [] → T
Use traceContextSync instead of traceContext when fn is not an async
function.
traceSync <T > (String name , T fn (), {Context ?context , Tracer ?tracer , bool newRoot = false , List <Attribute spanAttributes = const [] , SpanKind spanKind = api.SpanKind.internal , List <SpanLink spanLinks = const [] → T
Use traceSync instead of trace when fn is not an async function.
vocabularyNarrowing (String ?missionType , UiVocabularySchema baseSchema , {VocabularyNarrowingConfig config = VocabularyNarrowingConfig.empty → UiVocabularySchema
Resolve the active schema for a mission type (FR-005). Returns the narrowed
schema if one is declared, otherwise returns the base schema.
zone ([Context ?context → Zone
Returns a new Zone such that the given context will be automatically
attached and detached for any function that runs within the zone.
Typedefs
ApprovalCallback
= Future <bool Function(String prompt
Approval callback signature for confirm-tier tools (FR-002).
BackgroundTask Params >
= FutureOr <void > Function(BackgroundTaskContext <Params > context
Function signature for the task executed in the isolate.
BudgetBreachCallback
= void Function(BudgetBreach breach
Callback fired when a budget breach is detected (FR-006).
BudgetDegradeCallback
= void Function(BudgetBreach breach
Budget-degrade integration point (FR-013).
CompactionStrategy
= bool Function(int entries , int deletedEntries
A function which decides when to compact a box.
DisposingFunc T >
= FutureOr Function(T param
Signature for disposing function
because closures like (x){} have a return type of Null we don't use FutureOr<void>
FactoryFunc T >
= T Function()
Signature of the factory function used by non async factories
FactoryFuncAsync T >
= Future <T > Function()
Signature of the factory function used by async factories
FactoryFuncParam T , P1 , P2 >
= T Function(P1 param1 , P2 param2
For Factories that expect up to two parameters if you need only one use void for the one
you don't use
FactoryFuncParamAsync T , P1 , P2 >
= Future <T > Function(P1 param1 , P2 param2
For async Factories that expect up to two parameters if you need only one use void for the one
you don't use
FieldResolver T >
= Field <T , dynamic > ? Function(String fieldName
HiveLogger
Hive's logger
HiveLoggerLevel
Hive's logger level
IntrospectionTransport
= Future <IntrospectionHttpResponse Function(Uri endpoint , String query
Performs the introspection POST for endpoint.
KeyComparator
= int Function(dynamic key1 , dynamic key2
MissionExecutor
= Future <MissionOutcome Function(Mission mission , CoalescingGroup group , CancelToken cancelToken
Signature of the executor that runs a single mission to completion.
Returns the terminal MissionOutcome .
OsBackgroundTaskHandler
= Future <void > Function()
Callback type for OS background task handlers.
PackageUseCaseInvoker T >
= Future <Object ? Function(T usecase , Map <String dynamic > arguments
Invokes a resolved usecase with the tool's arguments.
Partial T >
= Map <String dynamic >
A type alias for partial entity data.
Route ZfaRoute
Backward-compatible alias for ZfaRoute .
ScopeDisposeFunc
= FutureOr Function()
Signature for disposing function on scope level
ToolInvoker
= Future <Object ? Function(String canonicalName , Map <String Object ? args
Invokes a registry tool by canonical name ("$namespace.$toolName").
TranslationTable Map <String Map <String String
The message table shape: locale tag → (key → message).
VoidCallback
= void Function()
ZuraffaPluginFactory
= ZuraffaPlugin Function()
ZuraffaRouteHandler
= Object ? Function(Object ?args
Route handler callback type (platform-agnostic).
Exceptions / Errors
AmbiguousCommandException
Two or more owner apps have registered a command with the same name, and
the caller invoked by name only (without specifying an owner app) (FR-009
edge case 2: ambiguous / conflicting command names).
AppFailure
Failure types for Clean Architecture
AppUpdateException
Recoverable, typed app-update error.
BadKeyException
A base class for exceptions thrown when decoding JSON.
BindingException
Raised by DiBinding.bind when a handler's declared dependency is not
registered in the host app's DI container.
BiometricsException
Recoverable, typed biometrics error.
CacheFailure
Cache-related failures
CancellationFailure
Cancellation failures
CancelledException
Exception thrown when an operation is cancelled
CheckedFromJsonException
Exception thrown if there is a runtime exception in fromJson
code generated when JsonSerializableGenerator.checked is true
CircularReferenceException
A cross-app invocation chain detected a cycle (FR-009 edge case 4:
circular command references).
CliEdgeCaseException
Base class for all standard-CLI edge-case exceptions.
CliUsageException
A usage error raised internally by CliApp when args fail to parse or
a required positional arg is missing. Carries no edge-case metadata; the
exit code is CliExitCodes.usage .
CommandAlreadyRegistered
Raised by CommandRegistry.register when an app tries to register a
command whose (ownerApp, name) key is already registered.
CompositeScaffoldException
ConflictFailure
Conflict failures (409 HTTP errors)
CorruptionDrillFailure
Raised by PersistenceTestHarness.openWithRecovery when the corruption
drill's recovery contract is violated (bug #833, remediation 3).
DecoratorParseError
Error thrown when decorator parsing fails.
DisallowedNullValueException
Exception thrown if there are keys with disallowed null values in a JSON
map that was provided during deserialization.
ForbiddenFailure
Forbidden failures (403 HTTP errors)
HiveError
An error related to Hive.
I18nException
Recoverable, typed i18n error.
IntrospectionException
Raised for every introspection failure mode with a human-actionable
message. Carries the HTTP status (when transport-level) and the raw
GraphQL error objects (when the server reported errors).
JournalException
Raised when a journal that EXISTS cannot be read (corrupt JSON, wrong
shape): honest failure, never a silent empty stream. A journal that
does not exist is NOT an error — it is honest pending state (the
feature has not been driven by a journal-writing cycle yet).
MissingRequiredKeysException
Exception thrown if there are missing required keys in a JSON map that was
provided during deserialization.
NamespaceCollisionException
Thrown when two tool sources register the same canonical name (FR-012).
NetworkFailure
Network-related failures
NoActiveMissionException
Thrown when ui.render is called with no active mission (spec Edge Cases).
NodeRegistryException
Raised when a composite registration cannot be loaded.
NonInteractiveContextException
A command requires interaction with the user, but stdout is piped or
stdin is not a TTY (FR-009 edge case 6: non-CLI / non-interactive context).
NotFoundFailure
Not found failures (404 HTTP errors)
PlatformFailure
Platform failures
PluginDiscoveryError
ReferencedAppMissingException
The owner app referenced by a cross-app invocation is not registered (FR-009
edge case 3: referenced command or app missing).
RegistrarGateError
Raised by PersistenceTestHarness.bootstrap when the init-time adapter
registration fails (bug #833, remediation 4 — the registrar gate).
SchemaCacheError
SchemaParseError
SecureStorageException
Recoverable, typed secure-storage error.
ServerFailure
Server-related failures (5xx HTTP errors)
ShareException
Recoverable, typed share error.
StateFailure
State failures
TimeoutFailure
Timeout failures
ToolDeniedException
Thrown by AgentKernel.invokeTool when an AgentHook denies a tool
call via ToolDecisionDeny (FR-010).
TypeFailure
Type failures
UiPayloadParseException
Raised when the payload file cannot be parsed (Edge Cases).
UiRenderValidationException
Typed exception thrown by UiRenderTool.render when validation fails.
UnauthorizedFailure
Unauthorized failures (401 HTTP errors)
UnimplementedFailure
Unimplemented failures
UnknownCommandException
The requested command is not registered under any owner app (FR-009
edge case 1: unknown / mistyped command).
UnknownFailure
Unknown/generic failures
UnrecognizedKeysException
Exception thrown if there are unrecognized keys in a JSON map that was
provided during deserialization.
UnsupportedFailure
Unsupported failures
ValidationException
Exception thrown when validation fails.
ValidationFailure
Validation failures
VersionMismatchException
A shared command was requested at a minimum version, but the published
version is below that minimum (FR-009 edge case 5: version mismatch
between sharing apps).
ViewNotFoundException
Thrown when replaceViewId references a view that does not exist
(spec Edge Cases).
WaitingTimeOutException
ZuraffaMissingPluginException
Missing-plugin exception replacement (mirrors flutter/services.dart).
ZuraffaPlatformException
Platform-native exception replacement (mirrors flutter/services.dart).
ZuraffaSessionException
A typed, recoverable session-layer error.
