design: define initial C FFI and generated binding contract

[vycdev2]

Summary

Define the first implementable contract for generated C bindings before adding jett bind, so the generator, parser/checker, and future native backend share one canonical representation for foreign declarations, ABI details, ownership, effects, and unsupported C constructs.

Source documentation

• docs/design.md — Rule Set 20: C Interop (Pre-Generated Bindings)
• docs/design.md — Open Questions: C binding file format
• docs/architecture.md — C Binding Generator (jett_bind)
• docs/progress.md — Phase J: Cross-Platform and Interop

Current state

The design sketches generated .jett wrappers and the architecture proposes a preserved # foreign: symbol_name comment, but the language has no decided foreign-declaration syntax or ABI/layout contract. The parser AST has no foreign metadata on function declarations, the CLI has no bind subcommand, the workspace has no jett_bind crate or libclang dependency, and jett build currently stops after type checking without HIR, MIR, native code generation, or linking.

Scope

This issue includes:

• choosing one canonical source representation for foreign functions, symbols, calling conventions, target/layout facts, and opaque handles instead of relying on an undecided comment sketch;
• defining the initial supported C declaration/type subset and deterministic diagnostics for unsupported headers or declarations;
• deciding which ownership, capability/effect, and error semantics are explicit in generated source versus inferred heuristically by jett bind;
• defining generated-file namespace, visibility, naming, declaration-order, reproducibility, and target metadata rules;
• splitting implementation into independently verifiable parser/checker, generator/CLI, and future lowering/linking stages with clear dependencies on design: define initial HIR and monomorphization boundary #20 and design: define initial MIR CFG and ownership boundary #22.

This issue does not include implementing libclang ingestion, HIR/MIR/native code generation, a runtime/linker, C++ interop, or broad support for every C construct.

Acceptance criteria

• The generated binding-file syntax and foreign-declaration metadata are specified with at least one canonical example that the current declaration-order and namespace rules can represent.
• The initial supported C type/declaration matrix, target/ABI inputs, and unsupported-case diagnostics are documented.
• Ownership, capability/effect, fallibility, and error-wrapping behavior are explicit enough that the generator does not silently invent unsafe semantics.
• The implementation is divided into dependency-ordered, independently testable slices for parser/checker, jett_bind/CLI, and future backend/link/runtime work.
• docs/design.md, docs/architecture.md, and docs/progress.md are aligned with the decision.

Dependencies / open questions

Native execution depends on the checked-program/HIR boundary in #20 and the MIR/ownership boundary in #22. The design should still identify a parser/checker and deterministic generation slice that can be tested before native code generation exists.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.