cell_flow 1.0.0
cell_flow: ^1.0.0 copied to clipboard
Orchestration Layer (Flow) for the Cell Framework — 90+ forensic-grade operators (asyncMap, switchMap, debounce) for reactive signal processing.
Changelog #
All notable changes to cell_flow are documented in this file.
The format follows Keep a Changelog. Version numbers follow SemVer. Flow is the release codename; it is not part of the SemVer string.
Flow (1.0.0) - Stable Release #
Stable release formalizing the Forensic Orchestration Layer. This version establishes the final operator topography, ensures full causal anchor propagation across asynchronous boundaries, and aligns with the stable Mitosis ecosystem.
Added #
### AI Agent Guidedoc blocks: theFlowclass,FlowInstruction,FlowInstructionBase,FlowHandle,MapValue,Filter,Distinct,DistinctUntilChanged,Tap, and 24 topFlow.*factories (of,fromFuture,fromStream,map,pluck,scan,filter,take,skip,distinct,asyncMapLatest,concatMap,mergeMap,switchMap,exhaustMap,mergeWith,combineLatestWith,race,debounce,throttle,timeout,groupBy,retry,tap) now carry the standardized AI-facing doc block: layer assertion, when to use / when NOT to use (with{@macro}anti-patterns), aLive signature:pin, sibling disambiguation, aGuide:pointer with a stable HowTo anchor, cross-layer guidance, stability, self-verification steps, and a minimal compilable example.- Anti-pattern templates: new
lib/doc/ai_anti_patterns.dart(ai-do-not-put-time-op-as-policy,ai-do-not-write-tissue-from-instruction,ai-do-not-tap-tissue-on-decision-chain, …). - API chooser: new generated
lib/doc/api_chooser.dart— the full BRD-sentence → operator decision matrix, rendered on pub.dev and generated from the guide blocks. - AI preflight: new
tool/ai_preflight.dart— a one-line check for everyLive signature:pin and the HowTo version pins; prints a paste-ready Demo-header provenance block; exits non-zero on drift. - Executable doc examples: new
tool/generate_ai_examples.dart+test/ai_guide_examples_test.dart— everyMinimal compilable exampleis generated, compiled withdart analyze, executed, and asserted to exit 0 in CI. - Seam rules in-package: new
test/seam_test.dart— no Tissue write inside aFlowInstructionBasesubclass inexample/; notestRule: TestCellon Tissue constructors. - Matrix freshness + failure log: new
tool/generate_api_chooser.dart+test/api_chooser_up_to_date_test.dart, andtool/ai_failure_log.dart+tool/ai_failure_log.jsonlfor structured, quarterly-reviewed AI failure records. - Benchmark suite: New
benchmark/directory mirroring thecellpackage's suite — micro per-operator cost pins (construction, pipeline materialization, map/filter chains, scan/reduce, distinct cardinality scaling, take/skip gates, pairwise, pluck), async family anchors (asyncMap,asyncExpand,asyncFold,FromFuture/streams), flatten concurrency pins (concatMap/mergeMap/switchMap/exhaustMap), temporal anchors (debounce/throttle/delay/timeoutwithDuration.zeroper-pulse anchors), combine scaling (mergeWith/combineLatestWith/zipWith/race/groupBy), collect batching, 50k stress, VM-service memory footprints, and feature-fair RxDart + raw-StreamControllercomparisons — with a PR-suite runner (benchmark/runner.dart), a 15% regression gate (benchmark/compare.dart), and a checked-inbaseline.json.
Changed #
- Library docs: the
cell_flowlibrary doc now opens with the layer-contract public-surface top table (custom instruction / projection / time / flatten / combine / collect / control) and an explicit "Do NOT use this package for" list. - README: opens with the AI-starter preamble (Install and import → "AI agents start here" → a six-row BRD elevator table) before the existing content.
- Curated examples:
cell_flow_example.dart,filter_data_quality_demo.dart,stability_search_demo.dart, andexhaust_map_submit_checkout_demo.dartcarry fixed AI-facing headers (What it demonstrates/Which BRD sentence picks it). - Docs: new
CONTRIBUTING-AI-DOC.md(normative block spec) andCONTRIBUTING.md. - Dependency alignment: Tightened constraints to
cell^1.1.0andcell_tissue(dev)^1.0.0.
Fixed #
- Per-activation state factories: Every stateful operator (debounce, throttle, timers, buffers, windows, scans, reduces, maps, races, retries, shares, …) now allocates its mutable state from a factory invoked once per
toHandleactivation. Two handles materialized from the same blueprint no longer share timers, pending slots, queues, or accumulators (the historical state-sharing bug); stateless blueprints remain shared safely. Regression-tested with twoDebouncehandles fed independently. ExhaustMapLatestrace window: The busy gate is now set before scheduling the async runner, so two pulses in the same synchronous frame can no longer both start inner sequences; the trailing-slot machinery is now race-free.MergeScanlost updates: Accumulation is serialized through a queue — each inner sequence drains fully before the next starts and everyaccumulatecall observes the accumulator produced by the previous sequence (input-ordered, race-free).- Observer/timer lifecycle: Notifier observers (
TakeUntil,SkipUntil,BufferWhen,WindowWhen,Sample,Audit,MergeWith/Merge,CombineLatest*,WithLatestFrom,ZipWith) and periodic timers (SampleTime,BufferTime,WindowTime,Interval*) now stop themselves once the materialized handle's cell is invalidated, instead of retaining the handle forever. Throttle(leading: false, trailing: false): Now anArgumentErrorat construction — the configuration previously emitted nothing at all.StartWithFactoryno longer drops data: A throwing seed factory reports toonErrorand the first source pulse is still forwarded (without a prefix) instead of being lost.RaceUntilempty sources: A source competitor that completes without a value now reports aStateErrorthroughonError/emitErrorPulseinstead of being silently dropped via theObject()placeholder.TakeUntilTimelifecycle: The timer callback ignores invalidated handles, and dead handles never arm new timers.Timeout_arm: Returns immediately once the clock is closed — a later pulse can no longer repoint the closed clock's callbacks.Distinctdefault path: Default-equality dedup now uses aSet(O(1) membership) instead of a linear list scan; custom comparators keep the list path.Flowis no longer aCellBase: The facade is a pure namespace of static factories and never pretended to be a cell in the graph.FlowHandletypedef honesty: The generic parameter was removed — factories produce untyped handles (Pulse<dynamic>ingress), so the oldFlowHandle<I>advertised types the implementation did not provide.- Cooperative inner draining: The shared
drainInneryields to the event loop every 256 items of a long iterable, so a synchronousMergeAll/ConcatAll-style burst can no longer starve timers and I/O. - Dead-handle fast paths:
TimerPulsenow returns before computingvalueOf()when the handle is invalidated, and_emitAll(StartWith family) stops allocating pulses mid-iteration once the host cell is dead. - SkipRepeated invariant: The dedup comparison uses a null-promoted read instead of a brittle
as Scast. - Helper consolidation: The seven duplicate
_drainimplementations and three identical sequential queue classes are consolidated intolib/src/instruction/flow_internal.dart(drainInner,SequentialQueue);_MergeQueuestays distinct (bounded-concurrency pump) and documents why.
Docs #
- Blueprint (not "stateless") contract:
FlowInstructiondocs now state that blueprints may be stateful and that stateful operators allocate per activation; the misleading stateless claim is gone. - Operator selection matrix, error-emission policy, trace-naming convention, lifecycle/resource notes, and the
toHandleallocation cost added to the README;MergeMapdocuments its backpressure semantics andSkipLastdocuments that trailing values are never flushed. - Benchmark README: Documents the layout, pass criteria (matching the
cellsuite's pessimistic style), the itemized cost ladder, and the known-exposure pins the suite is designed to surface. - Package README refresh: Corrected the operator count to the verified 100 public
Flowfactories, removed the stale RC-9 status/versioning and the outdated per-operator example table, replaced internal-class snippets (MapValue/Filter) with public-FlowInstructionequivalents, and added a "Why cell_flow" section (forensic pulses, reusable per-activation blueprints, governed data paths, self-cleaning lifecycle, one-graph/three-layers, pinned performance). - Nits documented:
FromFutureswarns that its futures are hot at construction (useDeferFutureto defer creation);FromStreamdocuments the absence ofcancelOnError;Flow.sampledocuments the untyped handle; the null-payload drop policy is documented on the shared type-check helper; the README's new Trace & Provenance section documents trace growth with pipeline depth,pulse.sourceas the immediate emitter (usepulse.root.sourcefor the origin), and null-payload semantics.
Flow (1.0.0-rc.9) - Release Candidate #
Docs and dependency-alignment release. No public API changes.
Changed #
- Dependency alignment:
celltightened to^1.0.0-rc.8and thecell_tissuedev-dependency raised to^1.0.0-rc.9.
Docs #
- Changelog convention: Aligned the CHANGELOG heading convention with the umbrella repository.
- API reference: Regenerated
doc/apiafter a freshdart doc .run.
Flow (1.0.0-rc.8) - Release Candidate #
Changed #
- AI command instructions relocated to
cell_tissue: TheAiTissueCommandfamily and the interpreter domain moved fromsrc/instruction/ai_tissue_command*.darttocell_tissue, which now owns and exports them. Importpackage:cell_tissue/cell_tissue.dartinstead. The integration test remains in this package'stest/directory to verify cross-package behaviour. - Dependency alignment:
celltightened to^1.0.0-rc.7and thecell_tissuedev-dependency raised to^1.0.0-rc.8.
Flow (1.0.0-rc.7) - Release Candidate #
Docs release for the umbrella Mitose pipeline. No public API changes.
Docs #
- Mitose pipeline: Added a prominent README callout for the umbrella Mitose pipeline — the AI-executable orchestration in the root
guide/that turns a business requirement into a Cell + Flow + Tissue solution with its BRD, WalkThrough, Demo, ARCHITECTURE, and FEATURES documents. This package contributes the Flow-layer rules viaguide/HowTo-Mitose-Flow.md.
Flow (1.0.0-rc.6) - Release Candidate #
Pub.dev WASM-compatibility release. No public API changes.
Fixed #
- WASM compatibility: Removed the unconditional
dart:iodependency from the AI tissue-command domain by movingHttpInterpreter,AiConfig.fromJsonFile, and the live-demo environment lookup behind conditional imports (ai_tissue_command_domain_io.darton native,ai_tissue_command_domain_stub.darton web/WASM). The package now compiles to WebAssembly (dart compile wasm).
Flow (1.0.0-rc.5) - Release Candidate #
Pub.dev score remediation release. No public API changes.
Fixed #
- Dependency alignment: Tightened the
cellconstraint to^1.0.0-rc.5. - License detection: Replaced the custom dual-license notice with the canonical MIT and Apache-2.0 texts so pub.dev recognizes the OSI-approved license.
- Example detection: Added
example/cell_flow_example.dart— a runnable quick start matching pub.dev's example file conventions.
Flow (1.0.0-rc.4) - Release Candidate #
This release introduces the AI Command Infrastructure, establishing a forensic gateway for AI-orchestrated state mutations. It aligns the orchestration topography with machine-driven logic while maintaining strict administrative oversight and causal integrity.
Added #
- AI Command Topography: Materialized the foundational infrastructure for AI-driven state evolution within the flow layer:
ai_tissue_command.dart: The command gateway implementation. It handles the execution of AI-generated instructions through governedapplyanddispatchmechanics, ensuring transactions remain isolated and compensable.ai_tissue_command_domain.dart: Formalized the forensic domain for machine commands. Defines the high-level interfaces for command schemas, authority tiers, and administrative mandates.
- AI Command Verification:
ai_tissue_command_test.dart: Exhaustive test suite for the new command infrastructure. Verifies that AI-generated pulses correctly inheritContextanchors and that the forensicPulse.traceaccurately captures machine-initiated mutations.
- Causal AI Anchoring: Integrated AI commands with the framework's Tiered Resolution Strategy, ensuring that machine-tier operations respect the administrative boundaries defined in the core layer.
Changed #
- Monorepo Synchronization: Aligned
cell_flowwith the corecell(1.0.0-rc.4) release, ensuring all orchestration operators support the refined Lifecycle Governance and Apoptosis (programmed cell death) mechanics. - Orchestration Pedagogy: Updated the operator documentation to explicitly link how AI-orchestrated stimuli flow through terminal sinks and reactive aggregators.
Fixed #
- Dependency Scoping: Resolved linter warnings related to machine-tier examples by refining the
dev_dependenciesmanifest to ensure forensic demos possess local workspace parity.
Tests #
- 1051 unit tests in 45 files, 465 groups (+13 tests for AI Command gateways).
- Last full run: +1051, exit 0.
- Line coverage (
lib/): 96.9% (+0.1% improvement in command gateway edge-cases).
Flow (1.0.0-rc.3) - Release Candidate #
This release formalizes Topographical Integrity and Forensic Traceability within the orchestration layer, ensuring that causal anchors are preserved across complex asynchronous transformations and operator chains.
Added #
- Causal Anchor Propagation: Updated
FlowInstructionandFlowHandleto respect the refinedContextsystem. Orchestrators now maintain the forensic lineage of aPulseas it traverses the topography, ensuring downstream observers can verify the original administrative authority.
Changed #
- Workspace Governance: Migrated to
resolution: workspace. Removed manualdependency_overridesfor local package links inpubspec.yaml, aligning with Dart's modern monorepo standards and resolving build conflicts in Melos environments. - Pedagogical KDocs: Regenerated public API documentation for all operators using the forensic standard (
### When to use,### How it works,### Non‑obvious). - Metadata Standardization: Synchronized
pubspec.yamlmetadata, includingrepository,issue_tracker, and platform support declarations, to ensure high-integrity discovery onpub.dev.
Fixed #
- Trace Integrity: Resolved a specialized case where the
Pulse.tracecould be fragmented or lost during high-frequencyDebounceorThrottleoperations. - Documentation Hygiene: Fixed unresolved doc references to generic type parameters
[C]and inherited references to[Tissue]across the operator family.
Tests #
- 1038 unit tests in 44 files, 452 groups (+13 tests covering context propagation and workspace resolution).
- Last full run: +1038, exit 0.
- Line coverage (
lib/): 96.8% (+0.3% improvement in operator edge-cases).
Flow (1.0.0-rc.2.0.2) - Release Candidate #
Patch focused on topographical integrity, path hygiene, and guidance expansion.
Fixed #
- Path Hygiene: Repaired a malformed Synapse (import URL) in
test/merge_test.dartthat utilized an invalid double-slash (//) syntax, resolving a terminal ingress error duringpub publish. - Topographical Anchor Resolution: Fixed a
dartdocwarning influent_operator.dartwhere[FlowHandle.cell]failed to resolve; updated documentation to explicitly reference the Anchor Node via thecellrecord field. - Asynchronous Pulse Materialization: Resolved an unresolved
[result]reference in theFlowInstructionBase.futureconstructor by standardizing on the term Evolved Pulse.
Added #
- Pedagogical Guidance: Materialized the
HowTo-Start.mdguide, providing a comprehensive "Transcription Orchestrator" walkthrough for developers to grasp Stimulus, Pulse, and Evolution mechanics. - Blueprint Templates: Expanded the
README.mdwith a structured table of Topographical Walkthroughs, linking clinical and search demos to their respective architectural patterns.
Tests #
- 1025 unit tests in 42 files, 442 groups (+3 tests covering path resolution).
- Last full run: +1025, exit 0.
- Line coverage (
lib/): 96.5% (+0.2% improvement in edge-case error paths).
Flow (1.0.0-rc.2.0.1) - Release Candidate #
Patch on the RC2 line. This release focuses on architectural documentation, topographical terminology alignment, and library hygiene.
Changed #
- Pedagogical Alignment: Regenerated all public API documentation across
flow_core.dart,fluent_operator.dart, and theinstruction/family using the Transcription Orchestrator style. - Topographical Terminology: Standardized terminology throughout the library. Documentation now formally refers to the graph as the Topography, inputs as Stimuli, event containers as Pulses, transformations as Evolutions, and results as Materializations.
- Orchestration Roles: Refined documentation for specific logic gates to clarify their role in the topography:
- Bridges: Temporal operators governing shift and cadence (
Delay,Interval). - Gates: Integrity and control operators (
Filter,Debounce,Timeout). - Flatteners: Structural transformation operators (
Map,ConcatMap,SwitchMap). - Anchors: Foundational graph nodes (
Cell).
- Bridges: Temporal operators governing shift and cadence (
Added #
- Quick Start Guide: Introduced
HowTo-Start.md, providing a comprehensive entry point for developers to grasp the Flow mental model. - Topographical Walkthroughs: Formally linked clinical and reactive search demos in the
README.mdanddartdoc_options.yamlas Blueprint Templates. fluent_operator_test.dart: Exhaustive test coverage forCellFlowOperatorsandFlowOperatorsensuring chains correctly anchor to theIngressHandle.cell.- Topographical Auditing Tools: Enhanced PowerShell-native auditing scripts for identifying files missing provenance metadata (Copyright headers).
Fixed #
- Documentation Hygiene: Resolved all
dartdocwarnings regarding unresolved references including[result],[FlowHandle.cell], and generic type parameters. - Receptor Integrity: Fixed an issue where
FlowInstructionBase.futureevolution logic failed to correctly gate unhandledFuture.errorevents. - Pulse Emission Logic: Corrected the
AsyncFoldorchestrator to prevent triple-emit inflation during high-frequency ingress. - Error Propagation: Refined
ConcatAllto ensure synchronous inner-throwing iterables correctly routeStateErrorto the appropriateonErrororchestrator.
Tests #
- 1022 unit tests in 42 files, 440 groups (+77 tests, +1 file since RC2).
- Last full run: +1022, exit 0.
- Line coverage (
lib/): 96.3% (5557 / 5768).fluent_operator.dart: 94.2% (+2.5% coverage).flow_core.dart: 100% materialization coverage.
Legal #
- Copyright headers and authorship metadata aligned with the Flow topography standards.
- LICENSE coverage confirmed for MIT OR Apache-2.0.
Flow (1.0.0-rc.2) - Release Candidate #
Added #
- Async map variants:
AsyncMapConcurrent,AsyncMapLatest,AsyncMapSequential,AsyncMapWithRetry,AsyncMapWithTimeout,AsyncMapWithFallback,AsyncMapWithIndex. - Async fold variants:
AsyncFoldLatest,AsyncFoldExhaust,AsyncReduce.Flow.asyncFoldLatest/Flow.asyncFoldExhauston the static facade. - Enhanced demos and walkthroughs:
ICU-alarm-pipeline(enhanced)-Demo.dart+ WalkThroughdomain-cells-txApply(enhanced)-Demo.dart+ WalkThrough
DEMO_GUIDE.md, expandedFEATURES-Flow.md.
Changed #
- Receptor scrutiny and PulseShell defensive proxies on async paths.
- Dartdoc:
### When to use/### How it works/### Non-obviousonFlowandFlowInstruction. Unresolved[ref]warnings cleared (qualified names, backtick generics). analysis_options.yaml:public_member_api_docs, stricter inference.dartdoc_options.yamllinks walkthroughs into the API reference.
Flow (1.0.0-rc.1) - Release Candidate #
First public release candidate. Operators are FlowInstructions on the
same graph as package:cell 1.0.0-rc.1.
Added #
Flowfacade: static factories returnFlowHandle.- Fluent extensions on
CellandFlowHandle(fluent_operator.dart,part offlow.dart). FlowInstruction+operator +→InstructionChain→ oneReceptorviatoHandle.
Create
Of,FromIterable,Range,RepeatFromFuture,DeferFuture,FromFutureOr, concat/merge/switch/exhaust from-future,FromFutures,FromFuturesInOrder,ForkJoinFutures,RaceFutures, retry / timeout / fallback,MapToFutureFromStream,DeferStream,ConcatFromStream,MergeFromStream,SwitchFromStream,MapToStream
Transform
MapValue,MapTo,MapWithIndex,MapNotNull,MapWhenPluck,PluckOr,PluckAll,PluckPathScan,Reduce,Pairwise
Async transform
AsyncMapand concurrent / latest / index / retry / timeout / fallbackAsyncExpandand concurrent / latest / exhaustAsyncFold,AsyncFoldLatest,AsyncFoldExhaust,AsyncReduce
Filter / take / skip / distinct
Filter, async filter family,FilterNotNull,FilterType,FilterAllowed,FilterBlocked,FilterByTimeTake,TakeWhile,TakeUntilSkip,SkipWhile,SkipUntil,SkipFirst,SkipLast,SkipRepeated,SkipWhenDistinctand variants indistinct.dart
Flatten
ConcatMap,Concat,ConcatAll,ConcatFirst,ConcatLatestMergeMap,SwitchMap,ExhaustMap
Combine
MergeWith,Merge,MergeAllZipWith,Zip,ZipAllCombineLatestWith,CombineLatest,WithLatestFromRace
Time
Delay,DelayWithSelector,DelayWhen,DelayLatest,DelayWithTrailing,DelayWithTimeoutDebouncefamilyThrottle,ThrottleLeading,ThrottleTrailingSample,SampleTime,Audit,AuditTimeTimeoutfamilyInterval,IntervalWithValue,IntervalWithState,TimerPulse
Collect / route / control
BufferCount,BufferTime,BufferWhen,BufferWithPredicate,BufferWithTimeAndCountWindowCount,WindowTimeGroupBy,GroupCollect,GroupByCountPartition,PartitionMap,PartitionOnly,IifStartWith,Share,ShareReplay,Retry,Tap/TapAll/TapWithIndex
Notes #
- Cells do not complete. Concatenate inners, not Cell-then-Cell.
reduce/scanare running folds, not terminal Rxreduce.MapValueis used instead ofMapso it does not clash withdart:core.filter.dartno longer ownsDebounce,Throttle,Take,Skip, orDistinct.- Application import is
package:cell_flow/cell_flow.dartonly.
Docs #
README.md,ARCHITECTURE-Flow.md,FEATURES-Flow.mdHowTo-Fluent_Operator.md,HowTo-FlowInstruction-Receptor.md- Example gates:
example_*.dart