Skip to main content

cell_flow 1.0.0 copy "cell_flow: ^1.0.0" to clipboard
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 Guide doc blocks: the Flow class, FlowInstruction, FlowInstructionBase, FlowHandle, MapValue, Filter, Distinct, DistinctUntilChanged, Tap, and 24 top Flow.* 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), a Live signature: pin, sibling disambiguation, a Guide: 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 every Live 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 — every Minimal compilable example is generated, compiled with dart analyze, executed, and asserted to exit 0 in CI.
  • Seam rules in-package: new test/seam_test.dart — no Tissue write inside a FlowInstructionBase subclass in example/; no testRule: TestCell on Tissue constructors.
  • Matrix freshness + failure log: new tool/generate_api_chooser.dart + test/api_chooser_up_to_date_test.dart, and tool/ai_failure_log.dart + tool/ai_failure_log.jsonl for structured, quarterly-reviewed AI failure records.
  • Benchmark suite: New benchmark/ directory mirroring the cell package'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/timeout with Duration.zero per-pulse anchors), combine scaling (mergeWith/combineLatestWith/zipWith/race/groupBy), collect batching, 50k stress, VM-service memory footprints, and feature-fair RxDart + raw-StreamController comparisons — with a PR-suite runner (benchmark/runner.dart), a 15% regression gate (benchmark/compare.dart), and a checked-in baseline.json.

Changed #

  • Library docs: the cell_flow library 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, and exhaust_map_submit_checkout_demo.dart carry fixed AI-facing headers (What it demonstrates / Which BRD sentence picks it).
  • Docs: new CONTRIBUTING-AI-DOC.md (normative block spec) and CONTRIBUTING.md.
  • Dependency alignment: Tightened constraints to cell ^1.1.0 and cell_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 toHandle activation. 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 two Debounce handles fed independently.
  • ExhaustMapLatest race 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.
  • MergeScan lost updates: Accumulation is serialized through a queue — each inner sequence drains fully before the next starts and every accumulate call 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 an ArgumentError at construction — the configuration previously emitted nothing at all.
  • StartWithFactory no longer drops data: A throwing seed factory reports to onError and the first source pulse is still forwarded (without a prefix) instead of being lost.
  • RaceUntil empty sources: A source competitor that completes without a value now reports a StateError through onError/emitErrorPulse instead of being silently dropped via the Object() placeholder.
  • TakeUntilTime lifecycle: 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.
  • Distinct default path: Default-equality dedup now uses a Set (O(1) membership) instead of a linear list scan; custom comparators keep the list path.
  • Flow is no longer a CellBase: The facade is a pure namespace of static factories and never pretended to be a cell in the graph.
  • FlowHandle typedef honesty: The generic parameter was removed — factories produce untyped handles (Pulse<dynamic> ingress), so the old FlowHandle<I> advertised types the implementation did not provide.
  • Cooperative inner draining: The shared drainInner yields to the event loop every 256 items of a long iterable, so a synchronous MergeAll/ConcatAll-style burst can no longer starve timers and I/O.
  • Dead-handle fast paths: TimerPulse now returns before computing valueOf() 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 S cast.
  • Helper consolidation: The seven duplicate _drain implementations and three identical sequential queue classes are consolidated into lib/src/instruction/flow_internal.dart (drainInner, SequentialQueue); _MergeQueue stays distinct (bounded-concurrency pump) and documents why.

Docs #

  • Blueprint (not "stateless") contract: FlowInstruction docs 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 toHandle allocation cost added to the README; MergeMap documents its backpressure semantics and SkipLast documents that trailing values are never flushed.
  • Benchmark README: Documents the layout, pass criteria (matching the cell suite'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 Flow factories, removed the stale RC-9 status/versioning and the outdated per-operator example table, replaced internal-class snippets (MapValue/Filter) with public-FlowInstruction equivalents, 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: FromFutures warns that its futures are hot at construction (use DeferFuture to defer creation); FromStream documents the absence of cancelOnError; Flow.sample documents 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.source as the immediate emitter (use pulse.root.source for 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: cell tightened to ^1.0.0-rc.8 and the cell_tissue dev-dependency raised to ^1.0.0-rc.9.

Docs #

  • Changelog convention: Aligned the CHANGELOG heading convention with the umbrella repository.
  • API reference: Regenerated doc/api after a fresh dart doc . run.

Flow (1.0.0-rc.8) - Release Candidate #

Changed #

  • AI command instructions relocated to cell_tissue: The AiTissueCommand family and the interpreter domain moved from src/instruction/ai_tissue_command*.dart to cell_tissue, which now owns and exports them. Import package:cell_tissue/cell_tissue.dart instead. The integration test remains in this package's test/ directory to verify cross-package behaviour.
  • Dependency alignment: cell tightened to ^1.0.0-rc.7 and the cell_tissue dev-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 via guide/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:io dependency from the AI tissue-command domain by moving HttpInterpreter, AiConfig.fromJsonFile, and the live-demo environment lookup behind conditional imports (ai_tissue_command_domain_io.dart on native, ai_tissue_command_domain_stub.dart on 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 cell constraint 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 governed apply and dispatch mechanics, 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 inherit Context anchors and that the forensic Pulse.trace accurately 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_flow with the core cell (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_dependencies manifest 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 FlowInstruction and FlowHandle to respect the refined Context system. Orchestrators now maintain the forensic lineage of a Pulse as it traverses the topography, ensuring downstream observers can verify the original administrative authority.

Changed #

  • Workspace Governance: Migrated to resolution: workspace. Removed manual dependency_overrides for local package links in pubspec.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.yaml metadata, including repository, issue_tracker, and platform support declarations, to ensure high-integrity discovery on pub.dev.

Fixed #

  • Trace Integrity: Resolved a specialized case where the Pulse.trace could be fragmented or lost during high-frequency Debounce or Throttle operations.
  • 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.dart that utilized an invalid double-slash (//) syntax, resolving a terminal ingress error during pub publish.
  • Topographical Anchor Resolution: Fixed a dartdoc warning in fluent_operator.dart where [FlowHandle.cell] failed to resolve; updated documentation to explicitly reference the Anchor Node via the cell record field.
  • Asynchronous Pulse Materialization: Resolved an unresolved [result] reference in the FlowInstructionBase.future constructor by standardizing on the term Evolved Pulse.

Added #

  • Pedagogical Guidance: Materialized the HowTo-Start.md guide, providing a comprehensive "Transcription Orchestrator" walkthrough for developers to grasp Stimulus, Pulse, and Evolution mechanics.
  • Blueprint Templates: Expanded the README.md with 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 the instruction/ 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).

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.md and dartdoc_options.yaml as Blueprint Templates.
  • fluent_operator_test.dart: Exhaustive test coverage for CellFlowOperators and FlowOperators ensuring chains correctly anchor to the IngressHandle.cell.
  • Topographical Auditing Tools: Enhanced PowerShell-native auditing scripts for identifying files missing provenance metadata (Copyright headers).

Fixed #

  • Documentation Hygiene: Resolved all dartdoc warnings regarding unresolved references including [result], [FlowHandle.cell], and generic type parameters.
  • Receptor Integrity: Fixed an issue where FlowInstructionBase.future evolution logic failed to correctly gate unhandled Future.error events.
  • Pulse Emission Logic: Corrected the AsyncFold orchestrator to prevent triple-emit inflation during high-frequency ingress.
  • Error Propagation: Refined ConcatAll to ensure synchronous inner-throwing iterables correctly route StateError to the appropriate onError orchestrator.

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.
  • 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.asyncFoldExhaust on the static facade.
  • Enhanced demos and walkthroughs:
    • ICU-alarm-pipeline(enhanced)-Demo.dart + WalkThrough
    • domain-cells-txApply(enhanced)-Demo.dart + WalkThrough
  • DEMO_GUIDE.md, expanded FEATURES-Flow.md.

Changed #

  • Receptor scrutiny and PulseShell defensive proxies on async paths.
  • Dartdoc: ### When to use / ### How it works / ### Non-obvious on Flow and FlowInstruction. Unresolved [ref] warnings cleared (qualified names, backtick generics).
  • analysis_options.yaml: public_member_api_docs, stricter inference.
  • dartdoc_options.yaml links 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 #

  • Flow facade: static factories return FlowHandle.
  • Fluent extensions on Cell and FlowHandle (fluent_operator.dart, part of flow.dart).
  • FlowInstruction + operator + → InstructionChain → one Receptor via toHandle.

Create

  • Of, FromIterable, Range, Repeat
  • FromFuture, DeferFuture, FromFutureOr, concat/merge/switch/exhaust from-future, FromFutures, FromFuturesInOrder, ForkJoinFutures, RaceFutures, retry / timeout / fallback, MapToFuture
  • FromStream, DeferStream, ConcatFromStream, MergeFromStream, SwitchFromStream, MapToStream

Transform

  • MapValue, MapTo, MapWithIndex, MapNotNull, MapWhen
  • Pluck, PluckOr, PluckAll, PluckPath
  • Scan, Reduce, Pairwise

Async transform

  • AsyncMap and concurrent / latest / index / retry / timeout / fallback
  • AsyncExpand and concurrent / latest / exhaust
  • AsyncFold, AsyncFoldLatest, AsyncFoldExhaust, AsyncReduce

Filter / take / skip / distinct

  • Filter, async filter family, FilterNotNull, FilterType, FilterAllowed, FilterBlocked, FilterByTime
  • Take, TakeWhile, TakeUntil
  • Skip, SkipWhile, SkipUntil, SkipFirst, SkipLast, SkipRepeated, SkipWhen
  • Distinct and variants in distinct.dart

Flatten

  • ConcatMap, Concat, ConcatAll, ConcatFirst, ConcatLatest
  • MergeMap, SwitchMap, ExhaustMap

Combine

  • MergeWith, Merge, MergeAll
  • ZipWith, Zip, ZipAll
  • CombineLatestWith, CombineLatest, WithLatestFrom
  • Race

Time

  • Delay, DelayWithSelector, DelayWhen, DelayLatest, DelayWithTrailing, DelayWithTimeout
  • Debounce family
  • Throttle, ThrottleLeading, ThrottleTrailing
  • Sample, SampleTime, Audit, AuditTime
  • Timeout family
  • Interval, IntervalWithValue, IntervalWithState, TimerPulse

Collect / route / control

  • BufferCount, BufferTime, BufferWhen, BufferWithPredicate, BufferWithTimeAndCount
  • WindowCount, WindowTime
  • GroupBy, GroupCollect, GroupByCount
  • Partition, PartitionMap, PartitionOnly, Iif
  • StartWith, Share, ShareReplay, Retry, Tap / TapAll / TapWithIndex

Notes #

  • Cells do not complete. Concatenate inners, not Cell-then-Cell.
  • reduce / scan are running folds, not terminal Rx reduce.
  • MapValue is used instead of Map so it does not clash with dart:core.
  • filter.dart no longer owns Debounce, Throttle, Take, Skip, or Distinct.
  • Application import is package:cell_flow/cell_flow.dart only.

Docs #

  • README.md, ARCHITECTURE-Flow.md, FEATURES-Flow.md
  • HowTo-Fluent_Operator.md, HowTo-FlowInstruction-Receptor.md
  • Example gates: example_*.dart
0
likes
160
points
1.13k
downloads

Documentation

Documentation
API reference

Publisher

verified publisheropencell.dev

Weekly Downloads

Orchestration Layer (Flow) for the Cell Framework — 90+ forensic-grade operators (asyncMap, switchMap, debounce) for reactive signal processing.

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#reactive #streams #forensic-traceability #state-management #async-orchestration

License

Apache-2.0, MIT (license)

Dependencies

cell

More

Packages that depend on cell_flow