8000 One firing rule for all ports; the control-stream completeness fix; ExtractField error leg by bergie · Pull Request #1094 · noflo/noflo · GitHub
[go: up one dir, main page]

Skip to content

One firing rule for all ports; the control-stream completeness fix; ExtractField error leg - #1094

Merged
bergie merged 9 commits into
masterfrom
control-gate-semantics
Oct 17, 2026
Merged

bergie merged 9 commits into
masterfrom
control-gate-semantics

Conversation

@bergie
@bergie bergie commented Oct 17, 2026 •
Copy link
Copy Markdown
Member

Summary

The firing model — one rule for all ports — plus the adapter contracts from the noflo-jekyll burst investigation (work documents #35/#36) and the firing-model removal (#47). Base note: the jekyll parity suite went green on alpha.9; this PR hardens the platform for the residual order-dependent shapes and fixes the contracts the investigation surfaced.

1. One firing rule for all ports (dc3fe19e, 005b67fc)

An arrival on any port re-fires the process once per scope that holds unprocessed input on any port, with the arriving IP — stamped to the firing scope — as the activation's context. This delivers the semantics the Process API's originator (trustmaster / Vladimir Sibirov) articulated in the #607 discussion and the maintainer agreed on; the machinery landed in October as an opt-in (triggering: false) that nothing declared, leaving default control ports on scopeless firing — the shape that stranded burst messages behind late-arriving configuration.

  • The firing predicate is any buffered IP in the scope — data and brackets both (a closeBracket completing a hasStream wait is a firing edge; openBracket arrivals engage auto-ordering)
  • Control ports keep their buffering semantics (non-consuming reads, the standing stream) and lose their firing role — their buffers are standing state, never pending work; a control arrival with nothing pending buffers silently
  • Forwarding inports are exempt (their brackets are owned by the forwarding machinery)
  • Addressable and IIP buffers joined the walk's scan (both were previously invisible to it)
  • The triggering port option is retired: accepted and ignored during the alpha window, removed from the accepted set at 2.0.0

The determinism contract, pinned by spec/FiringModel.js: activation schedules are arrival-dependent; activation results and final states are not. The spec drives every permutation of multi-port arrival orders (data × data × control, scoped and unscoped, streams interleaved with plain legs at every order-preserving position, two standing configs) asserting identical outputs and drained final state.

2. The control-stream completeness fix (005b67fc)

InPort.has's control-port wrapper destroyed the bracket-stack walk — bracket IPs were filtered out of the validator, so the stream-framing tracking never saw them, making hasStream on a control port return true for any partially open stream. A collector gating on a standing control stream fired early, baking incomplete results downstream (the shape behind the noflo-jekyll footer-include race). hasStream now takes the framing-aware check on control ports: the buffered stream's framing decides completeness, and the closeBracket completing a stream with data inside is the completion moment. Plain has() keeps the data-presence semantics — buffered brackets alone do not satisfy it.

3. ExtractField: missing fields error on the 8000 error leg (94636bed)

A message lacking the mapped field is malformed for the adapter: the absence surfaces on the extractor's new error outport — wired into the collector's error accumulation by the generated graphs — so the message completes on the error leg with the failure recorded, instead of a silent undefined delivery the inner component crashes on. null present as a value delivers. CollectFields' docs state the error contract normatively: the inner's error port is the message's terminal event for its scope, and pairing is per scope via the scope-aware checks.

4. Control gates as the predecessor step (dc3fe19e)

The control-port gate semantics (arrivals re-fire pending work per scope) are subsumed by the one firing rule and remain true under it; no migration-guide churn between the two.

5. Documentation (0a4de602, 51fdbeeb)

Behavior change note

Control arrivals no longer produce scopeless activations — standing configuration arriving after scoped messages now re-fires the waiting processes. Components whose control arrival should itself be the trigger carry data, not configuration — those are regular firing ports. The triggering option is inert. Measured compat surface: two test fixtures (both rewritten within this PR); 15/15 workspaces green, four Deno suites green, lint and types clean.

Test plan

  • spec/FiringModel.js: the determinism property test (every permutation), the per-scope pairing matrix, the pump, the bracket-completion edge, the framing-aware control-stream gate, the legacy option's inertness
  • The matrix earned its keep on its first run, catching: the control-stream completeness bug above, two read-then-decline deadlocks in its own scenario code, and the standing-stream completion semantics
  • The noflo assumes all control ports are populated before non-control ports when triggering process function #607 fixtures rewritten to the component-declares-pattern shape (observable assertions, not engine internals)
  • Full monorepo green: 15/15 workspaces, 0 failures under Node; Deno suites green (noflo 36, runtime 35, nodejs 8, assembly 10)

Work documents: #47 (the firing model), #35/#36 (the investigation and the adapter contracts), #607 (the origin — trustmaster's direction).

The firing model follows the port's role. A control port is a gate —
a standing, non-consumingly-read value whose arrival re-fires the
process once per scope that holds data on the component's other ports,
with the control value readable in that firing and left buffered.
Regular firing ports fire directly per arrival; regular non-triggering
ports share the gate machinery (work document #1 #607, whose machinery
was previously reachable only through an explicit triggering:false
declaration no shipped component made).

Previously a control arrival fired one scopeless activation: the
arriving IP's context carried no scope, so the process could not see
scoped buffers and declined — standing configuration arriving after
scoped messages silently failed to re-fire the waiting processes. That
shape stranded burst messages behind late-arriving configuration in
wrapped-adapter pipelines (the noflo-jekyll burst investigation, work
documents #35/#36), and forced the workaround of declaring
configuration ports as firing ports.

The leak-persistence fixture moves to its honest data-triggered shape:
a control arrival no longer opens an activation at all, so the
read-then-decline leak via a control arrival is now impossible; the
data-triggered shape (read the standing control value inside a
data-fired activation, then decline) still leaks, still warns, and is
still deliberately not auto-closed
A message lacking the mapped field is malformed for the adapter: the
absence surfaces on the extractor's new error outport — which the
generated adapter graphs wire into the collector's error accumulation —
so the message completes on the error leg with the failure recorded,
instead of a silent undefined delivery the inner component would crash
on (the noflo-jekyll includes-port crash shape, work document #35
update #13 question (b)). A field present with a null value is a value
and delivers.

asAssembly wires each extractor's error port into the collector's
error accumulation, and the collector node moves ahead of the
extractors so the error legs can wire to it.

CollectFields' docs state the error contract normatively: the inner's
error port is the message's terminal event for its scope — the
collector fires with the errors and whatever fields delivered; inner
data arriving after the error for the same scope has no collector
waiting and surfaces in the shutdown diagnostics. Pairing is per scope
via the scope-aware has-checks (work document #35 update #13 question
(c)).

Specs: ExtractField's missing-field and null-is-a-value units, and the
end-to-end malformed-message case through a wrapped adapter — both
messages complete scope-isolated, and closing the boundary runs the
full closedown cascade through the adapter
The control-port entry states the gate model cleanly: standing
configuration, non-consuming reads, arrivals that re-fire pending work
per scope — never a scopeless activation on their own. The
arrival-order question disappears (configuration arriving after scoped
messages re-fires the waiting processes). The command-shaped exception
is named: an arrival that should itself be the trigger is a regular
firing port, not a control port
The firing model follows work document #47 and delivers the semantics
trustmaster (Vladimir Sibirov, the Process API's originator)
articulated in the #607 discussion, agreed with the
maintainer: an arrival on any port re-fires the process once per scope
that holds unprocessed input on any port, with the arriving IP —
stamped to the firing scope — as the activation's context.

- handleIP routes all non-forwarding arrivals through the per-scope
  walk. The firing predicate is any buffered IP in the scope — data
  and brackets both, since a closeBracket completing a hasStream wait
  is a firing edge and openBracket arrivals engage auto-ordering.
  Forwarding inports are exempt (their brackets are owned by the
  forwarding machinery). Control ports lose their firing role
  entirely: their buffers are standing state — the walk skips them,
  so a control arrival with nothing pending buffers silently.
  Addressable and IIP buffers join the walk's scan (the IIP buffer
  was previously invisible to the walk, and addressable pending work
  was never re-offered).
- The 1.x triggering port option is accepted and ignored during the
  alpha window (removed from the accepted set at 2.0.0). A port
  declaring it behaves identically to one that does not.
- The #607 fixtures rewritten to the component-declares-pattern shape:
  the firing pattern lives in the has-checks; the engine's job is the
  wakeup. Assertions are observable (what was consumed and produced),
  not engine internals (which ports fired).

The determinism contract is pinned by spec/FiringModel.js: every
permutation of multi-port arrival orders (scoped and unscoped, spread
across edges) produces identical outputs and final state. The matrix
earned its keep immediately, catching three genuine defects on its
first run:

- the control-port hasStream wrapper destroyed the bracket-stack walk,
  so a control stream's completeness gate fired on any partially open
  stream — the corpus-gate-early shape behind the jekyll footer race;
  hasStream now takes the framing-aware check on control ports while
  plain has() keeps the data-presence semantics
- the multi-value-config scenario's completion semantics: values
  arriving after a stream's close do not join an already-fired
  activation
- two read-then-decline deadlocks in the matrix's own scenario code
  (gate on everything before any consuming read)
…bly docs, and the changelog

- The migration guide's control-port entry gains the one-rule statement:
  an arrival on any port re-fires the process once per scope holding
  unprocessed input on any port; arrival order changes when activations
  run, never what they see; the triggering option is retired
- The assembly docs' control-port convention corrected to the gate model
- The adapter-graph description gains the extractor error wiring, the
  missing-field semantics, and the scope-correlation contract
- The noflo changelog: the one-rule Changed entry and the hasStream
  completeness fix as a Fixed entry
@bergie bergie changed the title Control ports are gates; ExtractField missing-field error leg One firing rule for all ports; the control-stream completeness fix; ExtractField error leg Oct 17, 2026
- The determinism test's load assertion was vacuous (InternalSocket has
  no component property): wire() returns the component and the
  assertion reads it directly
- The framing state is per walk: ProcessInput.hasStream builds the
  bracket-walk validator through a factory, and InPort.hasStream walks
  each buffer (regular, IIP) with fresh state — a partially open
  regular stream no longer poisons the IIP-buffer check
- The forwarding-inport exemption stays intentional (the forwarding
  machinery owns the brackets and the scenario-C interaction), now
  documented in the one-rule statement; the matrix's non-coverage is
  noted in work document #47
- ExtractField guards a non-object message envelope with a kind error
  instead of a framework TypeError
- A debug warning for stream-completeness gating on addressable control
  ports (the data-presence path cannot see the framing)
- CHANGELOG: Changed before Fixed; the one-rule statement precise about
  control buffers and the forwarding exemption; triggering is removed,
  not deprecated-ignored
- Migration guide: the jammed reference unwound, the one-rule sentence
  precise
…ggering coverage restored

- The determinism test's load assertion collapsed to the formatter's
  shape (the CI lint error)
- The scoped permutation test gains the final-state check the unscoped
  one has (no activation left pending)
- The retired triggering option: the wording softened to the runtime
  truth — removed from the typed and documented option set, passing
  through as an unknown key that does nothing — and the coverage
  restored: a port declaring the legacy option participates in firing
  like any data port, the opposite of its 1.x meaning
@bergie
bergie marked this pull request as ready for review October 17, 2026 20:55
@bergie
bergie merged commit 92116c1 into master Oct 17, 2026
8 checks passed
@bergie
bergie deleted the control-gate-semantics branch October 17, 2026 20:58
bergie added a commit to noflo/noflo-jekyll that referenced this pull request Oct 17, 2026
The 2.0.0-alpha.10 platform set carries the control-port gate semantics
(noflo/noflo#1094) and the one-firing-rule retirement of the triggering
property (work document #47). With the gate semantics, the corpus-race
strand that dropped the collection-order post — and, under CI timing,
the remaining posts — is gone: repeated fixture builds produce one
output tree (verified plain and under Flowtrace recording), and the
four root posts join the strict Jekyll-reference comparison again.

The parity gap set now covers only the unimplemented features: the
nested _posts discovery and the nested front-matter pages. The four
posts' todo converts into the strict comparison.

DocumentBuilder's config port keeps its firing-port declaration, now
with the reasoning recorded: the drain's work lives in the per-scope
state store, which the gate machinery cannot see; the port reverts to
control when the builder returns to buffer-waiting under the
one-firing-rule pump (work document #35 update #23).
bergie added a commit that referenced this pull request Oct 19, 2026
…ession pin (work document #48)

Distills the noflo-jekyll document leg (work document #35 updates
#14-#22) to its engine shape and runs it through the actual wrapAssembly
machinery: a gate-model render component — standing bracket-framed
config on a scoped:false control port read non-consumingly, per-message
scoped data on two ports gated on both — wrapped as an assembly adapter
(Fork, field extractors, CollectFields), driven with bracket-framed
scoped message envelopes whose arrival order races the config and
stagger with async jitter inside open activations, then driven to EOT
with the closedown cascade asserted.

The negative result this suite pins: on the current engine (post-#1094
control gates, #1092 drain-based closing, #1099 drain pump), roughly
1300 randomized runs across staggered, burst, bounded-edge, multi-
registration-config, and deep-overlap variants delivered every message
and closed down — the intermittent drop class the testbed documented
did not reproduce. Three randomized variants run in CI; the full matrix
rides the WD48_* env knobs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0