ReviewOS

zig-utils/zig-js

ABI: implement exact SQL object structures and offset writes

#411
Closed chris opened this 9 days ago ·
9 days ago

Parent: #140 Profiles: #163, #164 Roadmap: #134 Pinned consumer: oven-sh/bun@4982b91e3702094330f3be3883354c52b8c01323 Pinned implementation reference: src/jsc/bindings/SQLClient.cpp:441-503

Implement the private JavaScriptCore structure pipeline used by Bun/Home SQL row materialization. The declared JSC__createStructure symbol must return a VM-affine opaque structure cell, not an ordinary JavaScript object or a compatibility no-op. Include the paired private consumers from the same pinned source so the returned descriptor can construct and populate real realm objects.

Acceptance:

  • Mirror the pinned ExternColumnIdentifier ABI exactly (tag, natural padding, u32 index / 24-byte BunString union; 32-byte size and 8-byte alignment on 64-bit).
  • Implement JSC__createStructure: named-column decoding and order, duplicate/index accounting, exact JSFinalObject::maxInlineCapacity cutoff, owner/VM write-barrier semantics, and an opaque VM-affine result.
  • Implement the paired JSC__createEmptyObjectWithStructure consumer with %Object.prototype%, shared engine shapes, all declared named slots initialized, and foreign/stale/invalid structure rejection.
  • Implement the paired JSC__putDirectOffset consumer with bounds checks, owner-aware GC barriers, exact slot writes, and invalid/foreign object/value rejection.
  • Cover named/indexed/duplicate mixtures, repeated named columns, cutoff behavior, UTF-16/BunString input, null owner, sibling realm acceptance, foreign VM rejection, precise GC relocation, and teardown lifetime.
  • Add independently compiled private-ABI fixture coverage plus focused engine tests in Debug, ReleaseSafe, and TSan.
  • Promote JSC__createStructure in both pinned inventories with zero unclassified entries and update ABI docs/README without changing benchmark or conformance scores.
  • Reconcile exact main CI before closure.
9 days ago

Implemented and pushed in 9db5d4f5 plus deterministic audit/CI wiring in f44eda19.

Local evidence:

  • Home compiled consumer: 392/392 symbols, Debug and ReleaseSafe runtime matrices pass.
  • Bun exact SQL fixture: 4/4 symbols, Debug, ReleaseSafe, and TSan pass.
  • Home inventory: 441/471 implemented, 30 pending, 0 unclassified.
  • Bun inventory: 432/461 implemented, 29 pending, 0 unclassified.
  • tools/test_home_private_abi.py: 4/4 pass.
  • README/API/Home integration and the pinned machine-readable #411 contract are current; benchmark and conformance scores are unchanged because this private-ABI slice does not invalidate those runs.

Exact main CI is running at https://github.com/zig-utils/zig-js/actions/runs/29790727875; the final checkbox and closure wait for that evidence.

9 days ago

Exact run 29791895246 exposed one real publication gap: verify-c-api.py rejected the two C++-declared SQL descriptor consumers as unclassified private exports. 1e0b814c adds the narrow #411-owned classification and refreshes the already-stale documented extension total from 23 to 26. zig build c-api-audit now passes with 117/117 public declarations and 457 classified private-profile exports.

Replacement exact main run: https://github.com/zig-utils/zig-js/actions/runs/29792663816

9 days ago

Complete. Exact SQL structure/object/offset behavior and both pinned consumer fixtures are implemented. Exact main run 29801586207 passed all 43 jobs; the private ABI boundary includes the SQL Debug, ReleaseSafe, and TSan matrix.

Sign in to comment on this issue.