state-hub/docs/forge-dependency-edge-receiving.md

Forge dependency-edge receiving (STATE-WP-0094-T05)

Status: source implementation landed 2026-10-04; not deployed. Deployment and any receiving schedule need separate founder authorization.

Problem

docs/owner-return-handoff.md ("T05 graph freshness assessment") records that normal Forge receiving (api/services/forge_projection.py) did not derive depends_on edges or reconcile workplan_dependencies. Only C-20 created edges, from a workstation checkout, and nothing ever removed an edge whose declaration disappeared. Adding a projection that "replaces every dependency row" would delete externally authored relations, so receiving needs an explicit ownership contract first.

Contract

1. Source. Edges are derived only from the immutable commit that receiving already pins (expected_commit = derived commit), from the same files as the rest of the projection:
   • workplan frontmatter depends_on, depends_on_workplans, depends_on_tasks - split like C-20: ids ending -T\d{2,3} are task targets (starts_after), all others workplan targets (blocks);
   • task-block depends_on - the waiting task is the from side (from_task_id). As in C-20, task-block edges of closed workplans (finished/archived) and closed tasks (done/cancel) are history and not desired.
   • A bare T## target is qualified with the declaring workplan id.
   • Bound historical workplans (historical_preservation) declare no edges.
   • A declaration that is a mapping or nested list refuses the whole derive (ForgeDeriveError); it is never dropped.
2. Ownership. A row is source-owned iff workplan_dependencies.source_owner = 'forge:<repo-slug>' (additive, nullable column, migration b3c4d5e6f7a8) and its from-workplan belongs to that repository. source_commit records the commit that introduced it. Receiving creates rows only with that owner and removes only rows with that owner. Rows with NULL or any other owner (API, MCP, C-20 fix path, other tools) are externally authored and are never modified or removed.
3. Already present externally. When a declared edge already exists as an external row (same from workplan, from task, target and relationship), it is preserved, not adopted, and reported in external_edges. Adoption is a deliberate future decision (see risks).
4. Target resolution (cross-repository). Fleet-wide, excluding projection-retired workplans and their tasks: workplans by ADR-007 derived UUID or record-id slug; tasks by derived UUID or record_id. Exactly one candidate resolves. Targets created in the same receipt resolve, because resolution runs after the workplan/task writes are flushed.
5. Missing / ambiguous / invalid targets. Zero candidates = missing, more than one = ambiguous (candidates listed; no winner chosen), a self edge = self, a waiting task the hub lacks = from-task-missing. Each is recorded in unresolved_edges; nothing is silently dropped. The receipt itself still applies (a target in a not-yet-received repository must not block the source repository's workplan projection).
6. Removal. Only source-owned rows whose key is no longer declared are removed - including rows of workplans retired in the same acknowledged receipt. If the from side (workplan or waiting task) has any unresolved declaration, its owned rows are retained and a note is emitted, because the unresolved target may be one of them.
7. Transactional failure. Edge reconciliation runs inside the same session as the workplan/task projection and flushes at the end. Any error propagates and the endpoint commits nothing; a refused receipt returns before edges are touched.
8. Repeat noop. Owned rows are not rewritten when unchanged, so the same commit received twice reports status: noop with zero created/removed edges. (unresolved_edges is still reported every time.)

Outcome schema additions (state-hub.projection-reset.v1): created_edges, removed_edges, unresolved_edges, external_edges lists and their counts.

Dry-run preview

diff_against_hub(..., hub_edges=[...], edge_targets={...}) previews edges with the same pure planner receiving uses (plan_source_edges + classify_source_edges). hub_edges are the rows whose from-workplan belongs to the repository (with source_owner); edge_targets maps a target record id to its fleet-wide non-retired candidate ids. A target the hub lacks but this projection declares resolves to the id the receipt would create. The diff gains edges (create, remove, retain, unresolved, external) and edge_counts; only create/remove make it non-clean. Without hub_edges the output is unchanged (no edges key).

Duplicate keys: several rows may share one edge key (an owned row plus an API-authored duplicate). The classifier works on the row list, so an external duplicate can neither hide an owned row from removal nor turn a satisfied declaration into an external report (fixed 2026-10-04; the first implementation keyed rows by edge key and let the last row win).

Coexistence with C-20

C-20 keys existence on (from task, target, relationship) regardless of owner, so it does not duplicate a source-owned edge; edges its fix path creates are external to receiving. Existing hub edges therefore stay external until an explicit adoption decision.

Open risks

• Pre-existing C-20/API edges are never adopted, so a removed declaration does not remove an edge C-20 created earlier; adoption needs its own decision.
• Ambiguity by slug for workplans is mostly prevented by the global slug index; task record_id ambiguity across workplans is the realistic case.
• Not deployed; no evidence of scheduled freshness. T05 stays in progress.