Skip to content

docs: ADR-0016 cross-language reference resolver + stack-graphs in landscape#369

Merged
jamestexas merged 1 commit into
mainfrom
docs/cross-lang-refs-adr
May 10, 2026
Merged

docs: ADR-0016 cross-language reference resolver + stack-graphs in landscape#369
jamestexas merged 1 commit into
mainfrom
docs/cross-lang-refs-adr

Conversation

@jamestexas

Copy link
Copy Markdown
Contributor

Summary

Sets the formal model for cross-language references in mache (the work tracked under bead mache-q43l). Drafted by a math-friend / paradigm-assessor / code-architect subagent review of the existing one-arm `mod:` resolver and the original bead framing.

What landed

docs/adr/0016-cross-language-reference-resolver.md — new ADR. Three corrections vs. the original proposal:

  1. Three orthogonal axes — naming, resolution, fidelity. The original collapsed them into one `scheme:value` string; separating gives independent extension axes without combinatorial blowup.
  2. Resolution is a Kleisli arrow into an effects monad `T = Maybe ∘ Fetching ∘ Forbidden ∘ StaleAt(σ)`, not `Address → Graph`. The pure signature couldn't express in-flight fetches, capability denials, or arena-clock staleness — the single-arm resolver was hiding these.
  3. Categorical model is a Grothendieck fibration `p: GraphMounts → Σ`, not a sheaf. Sheaf gluing requires strict overlap equality which doesn't hold under lazy fetches; honest framing is separated presheaf on a coverage, sheafified by ADR-0014's `current_root` advance. Today's `CompositeGraph` prefix-mount is the colimit of fibers — a coproduct — and the fibration adds the morphisms between fibers, which is what cross-scheme refs actually are.

Fidelity extension — cross-language refs carry fidelity at both endpoints; product poset `L_src × L_tgt` extends ADR-0013's chain mechanically. `v_defs` / `v_refs` schemas gain `target_lang` and split `fidelity` into src/tgt components. L₂ saturates at L₁ across language boundaries until a cross-language SSA / runtime-trace producer exists.

Pitch corrections (in the ADR's § Decision — Pitch and scope honesty):

  • Drop "we project, we don't index" from the public pitch. Real at the algebra/coalgebra layer; identical at the runtime-cost layer. Keep as a technical remark only.
  • "Monorepo = polyrepo with different URI schemes" is true at the naming layer only. False at the resolution / refactor / atomicity layers. Pitch unqualified obscures the eventual-consistency engineering the fibration model exists to make honest.

Implementation strategy — 5-bead sequence already filed under epic `mache-q43l`:

```
mache-bd97d9 (internal/resolve/ — Resolver iface + Registry)
├── mache-bdcd2b (LocalPathResolver)
│ └── mache-be0b9f (wire resolve_ref → mount in CompositeGraph) ← Terraform E2E milestone
│ └── mache-be3da9 (callers/ virtual entries)
└── mache-be650a (second scheme — npm or git remote-hint)
```

V1 keeps the resolver codomain as `(graph.Graph, error)`. The full effects monad surface lands when the first consumer needs more than `Now` / `Missing` — additive, not breaking.

`docs/competitive-landscape-2026.md` — added section 10. stack-graphs (GitHub). Both the math-friend (closest published categorical model for intra-language scope composition) and the paradigm-assessor (closest unmentioned competitor — declarative scope rules, polyglot composition, graph-composable) independently flagged stack-graphs as the most important omission. Deliberately not added to the 11-column matrix; the matrix categories don't capture what makes stack-graphs different (formal scope-graph model, intra-source polyglot). Pre-cites ADR-0016 so readers can follow the positioning argument.

`docs/ARCHITECTURE.md` — ADR table de-duplicated (the renumbered 0015 entry was sitting in the old 0006 slot AND in numerical order after 0014; collapsed to one) and ADR-0016 row added.

Subagent reports (for archival)

The fibration / product-poset / Kleisli-arrow framing came from a theoretical-foundations-analyst review of the original bead. The scope-honesty corrections came from a paradigm-assessor red-team of the "polyglot reference resolver" pitch. The 5-bead sequence came from a code-architect review that read the actual stub in `cmd/serve_resolve_ref.go` and proposed the minimal extension path. Synthesis comment lives on bead `mache-q43l`.

Test plan

  • `task docs:lint` passes (0 fail, 0 warn)
  • ADR-0016 cross-references resolve (ADR-0013, ADR-0014, ADR-0015 links work)
  • competitive-landscape section 10 renders cleanly in GitHub
  • ADR table in ARCHITECTURE.md has no duplicate 0015 row

…ndscape

ADR-0016 sets the formal model for the cross-language refs work tracked
under bead mache-q43l. Three corrections vs. the original bead framing,
all driven by a math-friend + paradigm-assessor review of the existing
proposal and the one-arm `mod:` resolver in cmd/serve_resolve_ref.go:

  1. Three orthogonal axes — naming, resolution, fidelity. The original
     proposal collapsed them into one `scheme:value` string. Separating
     gives independent extension without combinatorial blowup.

  2. Resolution is a Kleisli arrow into an effects monad
     `T = Maybe ∘ Fetching ∘ Forbidden ∘ StaleAt(σ)`, not `Address → Graph`.
     A pure signature cannot express in-flight fetches, capability denials,
     or arena-clock staleness — the single-arm resolver was hiding these.

  3. The categorical model is a Grothendieck fibration `p: GraphMounts → Σ`
     over the scheme category, not a sheaf — sheaf gluing requires strict
     overlap equality which doesn't hold under lazy fetches. The honest
     framing is a separated presheaf on a coverage, sheafified by
     ADR-0014's `current_root` advance. Today's `CompositeGraph`
     prefix-mount is the colimit of fibers (a coproduct); the fibration
     adds the morphisms between fibers, which is what cross-scheme refs
     actually are.

Fidelity extension: cross-language refs carry fidelity at both endpoints.
The product poset `L_src × L_tgt` extends ADR-0013's chain mechanically;
v_defs / v_refs gain `target_lang` and split `fidelity` into src/tgt
components. L₂ (reachability) saturates at L₁ across language
boundaries until a cross-language SSA / runtime-trace producer exists.

Pitch corrections:
  - Drop "we project, we don't index" as a public claim. Real at the
    algebra/coalgebra layer; identical at the runtime-cost layer. Keep
    as a technical remark.
  - "Monorepo = polyrepo with different URI schemes" is true at the
    naming layer only. False at the resolution / refactor / atomicity
    layers. Pitch unqualified obscures the eventual-consistency
    engineering the fibration model exists to make honest.

Implementation strategy: 5-bead sequence already filed under epic
mache-q43l (bd97d9 -> bdcd2b -> be0b9f for the critical path; be3da9
and be650a parallelizable). V1 keeps the resolver codomain as
`(graph.Graph, error)` — the full effects monad lands when the first
consumer needs more than `Now` / `Missing`.

competitive-landscape: add stack-graphs (GitHub) as section 10. Both
the math-friend (closest published categorical model for intra-language
scope composition) and the paradigm-assessor (closest unmentioned
competitor — declarative scope rules, polyglot composition,
graph-composable) independently flagged it. Deliberately not added to
the 11-column matrix; the matrix categories don't capture what makes
stack-graphs different. Pre-cites ADR-0016 so readers can follow the
positioning argument.

ARCHITECTURE.md: ADR table gets the 0015 row de-duplicated (the
renumbered entry was sitting in the old 0006 slot AND in numerical
order after 0014; collapse to one) and the new 0016 row.
@jamestexas jamestexas merged commit aef3862 into main May 10, 2026
8 checks passed
@jamestexas jamestexas deleted the docs/cross-lang-refs-adr branch May 10, 2026 21:53
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