docs: capture fork-gather research and verification plan
This commit is contained in:
@@ -10,6 +10,12 @@ gathers rendezvous compatible activation tokens, merge their lineage-local
|
||||
state patches, and create one continuation. This preserves topology-only edges
|
||||
without making multiple matching edges silently mean broadcast.
|
||||
|
||||
The [draft design contract](../superpowers/specs/2026-09-06-fork-gather-design.md)
|
||||
records the current requirements, open decisions, and verification gates.
|
||||
The [research archive](../historical/research/2026-09-06-fork-gather/README.md)
|
||||
preserves supporting evidence and known reference-model defects. This ADR is
|
||||
architectural direction, not an executable implementation plan.
|
||||
|
||||
## Context
|
||||
|
||||
The scheduler, ready queue, blocked frames, lineage-local state views, and
|
||||
@@ -83,8 +89,25 @@ most one deepest shared lineage: the lowest common ancestor is the deterministic
|
||||
merge base. Different scopes or no shared ancestor fail before state mutation.
|
||||
A partial gather creates its intermediate lineage under that merge base and
|
||||
retains multi-input provenance in activation-token metadata. A final gather can
|
||||
merge that lineage with remaining siblings and resume the blocked parent
|
||||
continuation.
|
||||
merge that lineage with remaining siblings and create a continuation token.
|
||||
Completion ownership survives token/frame replacement; foreach and subgraph
|
||||
parents still wait for the corresponding item or call to finish.
|
||||
|
||||
The lineage tree is not sufficient to deduplicate shared pending history after
|
||||
re-forking, cross-gathering, and reconvergence. Supporting that topology requires
|
||||
stable original contribution identities or an equivalent demonstrated scheme;
|
||||
otherwise the topology must be explicitly rejected. New node executions create
|
||||
new contributions even when node and token identities are unchanged. Merging
|
||||
existing contributions preserves their identities.
|
||||
|
||||
Control obligations also need two distinct ancestry queries. Referenced fork
|
||||
visits cover any component of a claim and govern unresolved re-entry checks.
|
||||
Enclosing visits cover every component and govern gather correlation. For a
|
||||
mixed claim `{k.x, r.c}` with `k` nested under `r`, only `r` encloses the whole
|
||||
claim. The proposed V1 matches a compiled anchor to that enclosing dynamic
|
||||
visit, without requiring an authored originating-fork field. One gather may
|
||||
fire at most once per owner/gather/anchor occurrence. Validation must account
|
||||
for past firings as well as currently parked arrivals.
|
||||
|
||||
The first gather merge policy is fail-closed:
|
||||
|
||||
@@ -98,9 +121,12 @@ merges. The gather policy determines what happens when patches cannot be
|
||||
merged; the initial behavior is to fail rather than choose a last writer.
|
||||
|
||||
Gather slots have declaration order, and that order is the canonical reducer
|
||||
replay order. After choosing the merge base, the runtime applies each selected
|
||||
lineage's writes after that base in declared-slot order, never arrival,
|
||||
scheduler, or frame-id order. A bucket accepts exactly one token for each slot;
|
||||
replay order for independent histories, never arrival, scheduler, or frame-id
|
||||
order. Whether an earlier partial gather's serialization becomes a permanent
|
||||
ordering constraint at later reconvergence remains open. Opposite histories
|
||||
`[A,B]` and `[B,A]` can arise in legitimate authored graphs; treating their
|
||||
combination as a merge-order conflict is a policy choice, not a corruption
|
||||
check. A bucket accepts exactly one token for each slot;
|
||||
a second token for the same activation and slot fails the activation instead of
|
||||
making an alternative-path race decide the result. Order-sensitive reducers
|
||||
such as append are therefore deterministic in synchronous and asynchronous
|
||||
@@ -155,9 +181,10 @@ their local rendezvous contract, not one producer.
|
||||
such as `d OR e` would require mutually exclusive arrivals. Named slots provide
|
||||
AND across slots and OR within a slot.
|
||||
|
||||
**Lineage becomes a multi-parent DAG.** Not currently required. Merge provenance
|
||||
belongs to activation tokens; an intermediate merged worldview can remain a
|
||||
child of the compatible inputs' common lineage parent.
|
||||
**Lineage becomes a multi-parent DAG.** Not currently required. An intermediate
|
||||
merged worldview can remain a child of the inputs' common lineage parent, but
|
||||
control provenance alone is not proof of state-write uniqueness. Shared-write
|
||||
identity and ordering require the separate contract described above.
|
||||
|
||||
**Store scope and parent-lineage identity on every frame.** Rejected because
|
||||
those relationships are canonical on the lineage and duplicated frame fields
|
||||
@@ -178,10 +205,13 @@ the node was a pass-through marker with no barrier contract.
|
||||
gather; ordinary edge semantics stay unchanged.
|
||||
- Workflow validation must require every gather-target edge to name exactly one
|
||||
declared slot, reject missing or unknown gather slots, prove that every slot
|
||||
has an incoming edge, reject slots on non-gather targets, and preserve one
|
||||
successor per ordinary `(node, outcome)` pair.
|
||||
has an incoming edge, preserve but ignore ports on ordinary targets, and keep
|
||||
one successor per ordinary `(node, outcome)` pair.
|
||||
- Checkpoints must persist pending gather arrivals and activation provenance so
|
||||
interruption/resume cannot mix loop iterations or subgraph invocations.
|
||||
- Supported checkpoints must not expose partially applied transitions, including
|
||||
when an exception produces a failed stopped run. This does not require a
|
||||
durable transition journal or promise exactly-once external effects.
|
||||
- Runtime operations should resolve a frame, its lineage, and its scope through
|
||||
one internal interface instead of accepting several independently supplied
|
||||
identifiers.
|
||||
@@ -199,11 +229,12 @@ the node was a pass-through marker with no barrier contract.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- The exact serialized edge field and authoring name for a gather slot.
|
||||
- The minimal activation-correlation and provenance representation that
|
||||
supports loops, nested forks, subgraphs, partial gathers, and cross-merges.
|
||||
- Whether a gather resumes an existing blocked frame or creates a dedicated
|
||||
continuation frame in each topology shape.
|
||||
- The supported correlation grammar and production validation algorithm for
|
||||
loops, nested forks, partial gathers, and cross-merges. Destination edges use
|
||||
`target_port`; ordinary destinations ignore that metadata.
|
||||
- Whether prior gather ordering is permanent history or a local state view.
|
||||
- The concrete owner/occurrence representation and integration with blocked
|
||||
foreach and subgraph completion, including failure and checkpoint handling.
|
||||
- The trace representation for waiting and merging without excessive internal
|
||||
scheduler noise.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user