Skip to content

fix(webapi): correct native binding contracts [Codex] - #399

Draft
jderochervlk wants to merge 13 commits into
agent/alpha-tooling-releasefrom
agent/alpha-binding-contracts
Draft

jderochervlk wants to merge 13 commits into
agent/alpha-tooling-releasefrom
agent/alpha-binding-contracts

Conversation

@jderochervlk

@jderochervlk jderochervlk commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

This stacked batch corrects native API representations, receiver dispatch, callback arity, and nullable/empty result contracts for #386–#392. The changes preserve native throws and rejections and avoid implicit copies: byte readers and stream chunks use Uint8Array, Web Audio and matrix APIs use native typed arrays, and native output methods write into the buffers supplied by callers.

The batch also corrects ResizeObserver argument shape; WebCrypto’s fixed results and public typed workflows; CustomElementRegistry constructor, broad closest, and HTML/SVG className contracts; and the empty, nullable, static, and operation-specific result cases.

For WebCrypto, generic algorithm-dependent generation/export is honestly unknown; the supported precise helpers fix HMAC key generation and ECDSA key-pair generation by algorithm, and split binary and JWK export by disjoint format types. Positive packed-consumer compilation and native Chromium workflows cover generate/sign/verify/digest-to-byte-view/export and key-pair signing without unsafe casts. Negative packed consumers reject wrong algorithm/format assumptions.

The native regressions now use only local fixtures: WebSocket text/ArrayBuffer/Blob sends reach a real loopback echo server; Worker Request fetch runs in a real worker against a local HTTP server that checks the forwarded POST method, header, and body; ResizeObserver observes an actual resize and disconnects; Blob stream chunks, SafeFetch bytes/identity, offline audio buffers and filters, non-identity DOMMatrix conversions, custom elements/closest/SVG, and the issue #392 native edge cases are asserted.

This PR is stacked on foundation PR #397 and uses its agent/alpha-tooling-release branch at 6fa3016a58700c1986acc705f7ff851efc54709e. It intentionally does not duplicate harness, packaging, workflow, or documentation foundation changes. The documentation PR #398 is downstream and remains docs-only. SharedWorkerScope and ServiceWorkerScope Request-fetch inherited bindings are compile-checked; the native Request-fetch run uses the base Worker scope.

Refs #386, #387, #388, #389, #390, #391, #392

@jderochervlk

Copy link
Copy Markdown
Collaborator Author

Independent review of 5ce03b4, against 1a6aceb (#397 foundation). Not acceptance-complete; no approval/merge performed. All seven requested checks pass, but the following P2 regression/evidence defects need attention:

  1. The closest negative tests nullability, not narrowing. ClosestCannotNarrow.res:1–2 assigns Null.t<…> directly to a nonnullable input. In an isolated package copy, restoring the old Null.t<'e> signature still produces the expected diagnostic. Change the target to Null.t<WebAPI.HTMLInputElement.t> (or unwrap first) and match the element-type diagnostic. The corrected nullable fixture compiles with the old signature and rejects at this head.
  2. Worker initializer forwarding is not asserted. worker-fetch.mjs:5–7 reads a static file from a method-insensitive server. Browser interception that drops {method: "POST"} leaves the entire binding fixture passing. Assert the method/headers/body received by a local endpoint and cover omitted init separately.
  3. Biquad assertions do not establish any output write. BindingContracts__test.res:144–153 starts with zero-filled outputs and only checks types/lengths/!isNaN(0). Removing getFrequencyResponse through browser interception still passes the complete fixture. Use sentinels and assert meaningful magnitude/phase values in both caller-owned buffers.
  4. The WebSocket test does not exercise a native local connection. websocket-bindings.spec.mjs:6–8 uses routeWebSocket without connecting to a server; Playwright replaces WebSocket with its mock. Add the local native WebSocket endpoint required by Fix receiver dispatch for WebSocket sends and worker Request fetches #386.

Additional acceptance gaps beyond the draft's acknowledged stream-chunk, shared/service-worker runtime, IIR call, and permission-value gaps:

  • ResizeObserver only observes the initial element; no resize-triggered callback is tested.
  • Matrix evidence uses identity input and does not exercise DOMMatrixReadOnly.fromFloat32Array; strengthen nonidentity round trips. Float analyser runtime evidence is absent.
  • Correct WebCrypto result types and verify key workflows #390 lacks registered negative tests for former JSON/key-result assumptions and cross-format exports, and no positive Crypto-only packed workflow is registered. I independently compiled/ran public-only packed HMAC + ECDSA generate/sign/verify, digest-to-byte-view, and raw/JWK export successfully; wrong-format exports both reject. The generators hard-code HMAC/ECDSA, so their successful result shapes are sound.
  • Correct DOM constructor, narrowing, and SVG className contracts #391 lacks HTML className/browser coverage, a broad-selector string-access negative, and migration documentation.
  • Represent native empty, nullable, and operation-specific results accurately #392's generic raw predicates do not enforce callback nullability or delete-result types; add typed/negative fixtures for these, empty enums, and the removed Notification instance field.

Checks executed successfully: npm run build, npm test, npm run check:features, npm run format:check, npm run test:negative, npm run test:browser (3 tests), npm run check:consumer. Mutation experiments used only scratch package copies/browser interception; repository sources were not edited.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant