Skip to content

proven: binding-tier-1 detachable-harness template — Chapel pilot + replication #129

@hyperpolymath

Description

@hyperpolymath

Goal

Stand up strict, detachable CI for every promoted language binding under
bindings/<lang>/. Each binding must:

  • link against libproven.so (verified by nm -D vs symbol-manifest),
  • typecheck every Chapel/Crystal/Nim/... source module under src/,
  • pass a smoke target that exercises the documented C ABI,
  • pass per-module assertion-based tests,
  • be extractable to a standalone proven-<lang> repo by copying ONLY
    bindings/<lang>/, bindings/c/include/proven.h, and the workflow.

Pattern — detachable-harness template

Documented in docs/adr/0001-binding-ci-template.adoc (landed via the
Chapel pilot PR). Summary:

  • bindings/<lang>/Justfile — env-driven (PROVEN_LIB_PATH,
    PROVEN_INCLUDE_PATH), no reach into root tooling
  • bindings/<lang>/symbol-manifest.txt — WIRED extern manifest
  • bindings/<lang>/scripts/symbol-audit.sh — fast nm gate
  • .github/workflows/<lang>-ci.yml — 6 strict jobs (detachability-guard,
    build, symbol-audit, smoke, tests, detachable-build), all
    SHA-pinned, all path-triggered on only bindings/<lang>/**,
    ffi/zig/**, bindings/c/include/proven.h, self
  • Root Justfile exposes <lang>-{check,build,test,clean} as ONE-LINE
    thin forwarders — no -specific logic at root

The detachability contract is enforced by the <lang>-detachable-build
CI job: sparse-checkout of the detachable set + just test must pass.

Status

  • Chapel — pilot landed in the accompanying PR. WIRED subset is
    5 symbols; the remainder is GATED on proven#88. See
    docs/adr/0002-chapel-binding-standup.adoc and
    audits/chapel-symbol-audit-2026-05-30.md.
  • Crystal — replicate next; sub-issue filed.
  • Nim — replicate 3rd; sub-issue filed.
  • OCaml — replicate 4th; sub-issue filed.
  • Haskell — replicate 5th; sub-issue filed.
  • Lua — replicate 6th; sub-issue filed.
  • Long tail (~110 bindings) — applied in waves once the top-6 prove
    the template generalises.

Prerequisite ramp (proven#88)

Until proven#88 ramps the Zig FFI exports, every binding-tier-1 PR
ships with the same trimmed WIRED quintet
(proven_path_has_traversal, proven_header_has_crlf,
proven_free_string, proven_version, proven_build_info). That is
still a real net gain — credible CI today — but the per-binding
coverage matrix grows in lockstep with proven#88.

References

  • Pilot ADR: docs/adr/0002-chapel-binding-standup.adoc
  • Template ADR: docs/adr/0001-binding-ci-template.adoc
  • proven#88 — missing Zig FFI exports, blocks linking

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions