Binding npm-dependency surface: keep `requires { }` in .bynk, or move deps to the .ts binding's own manifest? (packaging track)

[accuser]

Deferred from the keyword-hygiene batch (#548, §3.3). The review recommended renaming the binding-level requires { … } (the adapter npm-dependency map, ADR 0013) to disambiguate it from the function-precondition requires. That rename was not done in the batch, for two reasons:

1. It collides with the packaging track. design/tracks/packaging.md §2 (Non-goals) explicitly keeps binding requires as-is and reuses packages / [package] vocabulary at the manifest level — so renaming binding requires→packages now would pre-empt the track's chosen terms.
2. The real question is deeper than a rename. Should the npm dependency + pinned range even live in .bynk source, or move to the .ts binding's own package.json manifest?

The question

Today (ADR 0013):

adapter tokens {
  binding "./tokens.binding.ts" requires { "jose": "^5" }
  …
}

The pinned range lives in .bynk because (a) a TS import "jose" carries no version range, and (b) the Bynk compiler owns package.json generation and the supply-chain trust surface (still-Open ADR 0020).

The alternative — give each binding its own real package.json and have the compiler read that instead of a requires clause — is a redesign of the binding-as-package model, which is squarely the packaging track's remit (it owns the dependency surface and closes ADR 0020).

Disposition

To be resolved by the packaging track when it reaches the dependency surface. Forks to weigh:

• A — keep requires { } in .bynk (status quo, ADR 0013). Possibly rename the keyword to avoid the function-requires pun if the track's packages/[package] vocabulary leaves room.
• B — move deps to the .ts binding's own manifest and have the compiler read it. Closes the pun by removing the surface; changes the binding model.

Provenance: #548 (Bynk Language Design Review 2026-07-05, §8 Language P1 #9). Relates: ADR 0013, ADR 0020, design/tracks/packaging.md.

[accuser]

Thinking about this more widely before the packaging track picks it up — I don't think the fork is actually binary. There's a third option that's distinct from B and, I think, stronger.

Fork C — a binding manifest (sidecar), not the binding's own package.json

B as written gives the .ts binding its own real package.json and has the compiler read it. That's heavy: it makes each binding a self-contained npm package (own node_modules? whose manifest wins at generation? the trust surface dilutes into "npm-resolve this JSON") — the "redesign of the binding-as-package model" this issue flags.

C is a declared sidecar manifest next to the binding (tokens.binding.ts + tokens.binding.pkg.*), from which the compiler generates package.json exactly as it does today from the clause. It threads between A and B:

• Kills the requires pun for free. The packaging vocabulary leaves the grammar entirely — there's no keyword left to disambiguate from function-precondition requires. That was this issue's original trigger (Keyword hygiene batch (stub / rename binding requires / one conjunction / protocol casing) #548 §3.3).
• Keeps ADR 0013's model. The compiler still owns generation and pinning; it just reads a manifest instead of an AST node. Still pinned, still greppable — it's a file, not a clause.
• Degrades gracefully (the load-bearing point). requires { } only ever expresses dependencies — no devDeps, peerDeps, engines, exports map. The moment an adapter needs more than "name → range," A forces us either to grow a package-manager sublanguage inside .bynk grammar or spill packaging into a second place anyway. A manifest has nowhere to grow but sideways, off the language.
• Gives ADR 0020 a concrete artefact. The trust/allow-list/confirmation policy hangs on a supply-chain file you diff in review, rather than on a grammar clause.

The question it turns on

ADR 0013 placed requires in .bynk on the premise that the npm surface is contract-adjacent. By three tests it's actually binding implementation: the range has no bearing on type-checking the .bynk (only tsc --strict on the binding cares), no bearing on the capability contract consumers see, and it grows on the binding's axis (more libs, dev tooling), not the contract's.

The honest counter-argument

The cost of C is co-location — today one .bynk line carries the whole trust surface; a sidecar splits it. For the 1-dep common case (every current fixture carries just jose) the clause is genuinely nicer, and a well-formed library adapter arguably should wrap one library. So the noise concern is partly forward-looking. The real trade — one-surface review + co-location (0013/0020) vs. grammar cleanliness + graceful growth — is decided by ADR 0020, which is the thing actually still open. C and 0020 are the same question.

Disposition

Recommend folding C into the fork set the packaging track weighs (A / B / C), and treating this as a settle-up-front surface decision per ADR 0076 rather than a later retrofit — it closes 0020 in the same motion. Leaning C if the track expects rich manifests (devDeps/engines/per-dep trust metadata); A-with-rename if the posture stays "one library, one or two pinned deps, trust surface in the file you already read."

---

Generated by Claude Code