docs: roadmap Tracking links + Zig C-ABI FFI patterns doc (bindings #19)#474
Draft
hyperpolymath wants to merge 3 commits into
Draft
docs: roadmap Tracking links + Zig C-ABI FFI patterns doc (bindings #19)#474hyperpolymath wants to merge 3 commits into
hyperpolymath wants to merge 3 commits into
Conversation
…s (refs #446) The Tracking section carried two '(TBD — opened alongside this PR)' placeholders for the umbrella tracker and per-tier child issues. Those issues now exist, so the placeholders were stale per the doc's own 'do not let the table drift' rule: - Umbrella tracker: #446 - Per-tier child issues: #450 (Tier 1) .. #454 (Tier 5) - Shipped kickoff: #455 (WASM-exports calling pattern, via PR #467) Completes the canonical-tracking-link portion of the #446 umbrella's STEP 1 deliverable.
…la links Both sibling roadmap docs carried the same stale '(TBD — opened alongside this PR)' placeholders for umbrella tracker and per-tier/track child issues. Those umbrellas now exist, so the placeholders were stale per each doc's 'do not let the table drift' rule: - stdlib-roadmap.adoc -> umbrella #412; lazy child model (stdlib #N); filed so far: #415 (stdlib #5, cross-file use; closed) - alib-roadmap.adoc -> umbrella #413; lazy child model (alib #N); filed so far: #416 (alib #10, alib.affine module; closed) Reflects each campaign's actual lazy child-issue model (open issues as work starts; do not seed all up front), distinct from the newer bindings campaign (#446) which pre-files per-tier issues.
hyperpolymath
changed the title
Adds docs/specs/zig-ffi-patterns.adoc — the canonical, task-oriented recipe for binding a Zig C-ABI export to an AffineScript extern fn, the deliverable for bindings #19 in docs/bindings-roadmap.adoc. Scoped to avoid DOC-DEDUP overlap: SPEC §2.10 owns the grammar, STDLIB-EXTERN-AUDIT owns the inventory, codegen-environment owns the wasm codegen mechanics; this doc is the authoring recipe + per-backend host contract that ties them together. Grounded in the actual codegen: - wasm: every extern fn -> (import "env" "<name>") (lib/codegen.ml) - Deno-ESM: deno_builtins intrinsics emit a self-contained __as_* helper; declared externs lower to a same-named host symbol (mangle is identity except JS reserved words) (lib/codegen_deno.ml) Worked example uses the existing hpm-json-rsr binding in stdlib/json.affine. Bumps the #19 row in bindings-roadmap.adoc from a partial-scaffold status to usable per the doc's own 'update the row in the same PR' rule. Unblocks the RSR rewires #11 / #12 / #16.
hyperpolymath
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related docs-layer changes for the roadmap-campaign family (kept on one
branch per the session's branch policy).
1 — Roadmap Tracking-section fixes
Replaces the stale
(TBD — opened alongside this PR)placeholders in theTracking section of all three satellite roadmap docs (all landed in #410)
with the umbrellas + child issues that now exist:
bindings-roadmap.adocstdlib-roadmap.adocstdlib #N, opened as work startsalib-roadmap.adocalib #N, opened as work startsEach doc carries a "do not let the table drift" rule; these placeholders
were the one stale spot left after umbrella setup. Status columns were already
current. Refs #446, #412, #413.
2 — Zig C-ABI FFI binding patterns doc (bindings #19)
Adds
docs/specs/zig-ffi-patterns.adoc— the deliverable for bindings #19(Zig FFI canonical patterns), and bumps that roadmap row
◐ → ●.It's a task-oriented authoring recipe (how to bind a Zig C-ABI export to an
extern fn), scoped to avoidDOC-DEDUPoverlap:SPEC.adoc §2.10owns the grammar;STDLIB-EXTERN-AUDIT.adocowns theinventory;
codegen-environment.adocowns the wasm codegen mechanics.together — the gap refactor(manhattan-recovery): scope recovery + complete grammar refactor + rip dependent-type creep #19 names ("idiomatic patterns exist" but uncanonicalised).
Grounded in the actual codegen, not paraphrase:
extern fn→(import "env" "<name>")(lib/codegen.ml:2331)deno_builtinsintrinsics emit a self-contained__as_*helper;declared externs lower to a same-named host symbol (
mangleis identityexcept JS reserved words) (
lib/codegen_deno.ml:620,667)hpm-json-rsrbinding instdlib/json.affine.Unblocks the RSR-convergence rewires #11 / #12 / #16.
Note for maintainer (no action needed)
The bindings campaign has two umbrellas — #411 (closed) and #446 (open). Already
reconciled: #411's closing comment cross-links #446 as canonical. Recorded for
traceability.
https://claude.ai/code/session_01DbDFzJZue7mMnKudvXSK4T