docs: define C FFI binding contract

[vycdev2]

Summary

• define first-class generated foreign blocks with semantic source, digest, target, ABI, symbol, and opaque-pointer metadata
• require explicit Foreign capability, ownership/fallibility policy, deterministic sidecar registration, and conservative unsupported-case diagnostics
• split parser/checker, generator/CLI, checked lowering, and native linker work into independently testable stages
• align the design, architecture, progress tracker, and docs index with the selected contract

Verification

• cargo fmt --check — passed
• cargo build — passed
• cargo test -q — passed (workspace suite)
• git diff --check — passed

Risk

• low: documentation-only change; parser, generator, and native backend support remain explicitly unimplemented

Closes #53

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

[vycdev]

The owned-handle contract does not currently prevent leaks. Lines 193–204 require every returned owned handle to have a release function and appeal to Jett's linear-consumption rule, but the current ownership checker explicitly allows owned linear values to leave scope without a diagnostic (owned_linear_value_can_exit_scope_without_warning). A generated wrapper can therefore acquire a C handle and return early or fall through without calling release.

Before treating this as the initial safety contract, please choose and specify either path-complete explicit consumption checking or compiler-inserted cleanup, including early return, error handling, and cancellation behavior, and add that checker/lowering work and conformance tests to the implementation slices.

[vycdev]

A second contract mismatch: lines 161–163 say actors/tasks receive Foreign only through clone, but Jett's established structured-concurrency examples pass capabilities to run tasks by view and keep the owner borrowed until join (for example the run http.get(view net, ...) examples and the ownership rule for run process(view items)). Actors need clone handoff because they outlive the caller; structured tasks currently borrow.

Please restrict the clone requirement to actors, or explicitly define and justify why Foreign diverges from other capabilities for tasks and update the general task/capability rules accordingly.