docs: capture fork-gather research and verification plan

This commit is contained in:
lda
2026-09-07 01:34:28 +07:00 Verified
parent e36e462fd6
commit bb361b7f89
16 changed files with 8892 additions and 15 deletions
@@ -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.