Skip to content

feat(vnext): add bounded browser parser executor - #181

Merged
Light2Dark merged 7 commits into
dev-refactorfrom
codex/vnext-parser-executor
Jul 24, 2026
Merged

feat(vnext): add bounded browser parser executor#181
Light2Dark merged 7 commits into
dev-refactorfrom
codex/vnext-parser-executor

Conversation

@Light2Dark

@Light2Dark Light2Dark commented Jul 24, 2026

Copy link
Copy Markdown
Member

Summary

Adds the private main-realm executor for the isolated parser worker selected in
ADR 0004.

  • Lazily creates at most one authoritative worker generation.
  • Serializes requests through a bounded FIFO queue with independent request-count
    and retained UTF-16 text limits.
  • Enforces startup, queue-wait, and posted-execution safety deadlines.
  • Settles caller cancellation promptly while draining already-posted work.
  • Retires crashed, timed-out, malformed, or poisoned generations without
    replaying posted work.
  • Preserves never-posted queued work across eligible generation replacement.
  • Rejects reused worker identities and serializes retirement across hostile
    cleanup/settlement reentrancy.
  • Keeps the worker factory, executor, protocol, and implementation types private;
    there is no root or /vnext public API change.

Risk classification

Medium: concurrency, cancellation, worker lifecycle, resource accounting, and
packaging boundaries.

The principal risks are double settlement, stale-generation authority, physical
worker overlap, posted-work replay, unbounded retention, and browser bundler
regressions. The implementation mutates ownership before every external cleanup
or settlement boundary, uses an iterative pump trampoline, and tests hostile
synchronous callbacks at each boundary.

Evidence

  • Full Node suite: 1,246 passed, 1 expected failure.
  • Focused deterministic executor suite: 84 passed.
  • Chromium: 4 files / 7 tests, including real worker, crash, silent-worker
    deadline, recovery, and default static Worker URL behavior.
  • Changed executor coverage:
    • Statements: 95.51%
    • Branches: 95.37%
    • Functions: 100%
    • Lines: 95.49%
  • All TypeScript project checks, oxlint, test-integrity, and diff checks pass.
  • Packed-package smoke test passes and asserts the executor artifact.
  • The post-rebase executor patch ID exactly matches the twice-reviewed pre-rebase
    patch.

Adversarial review ledger

The review loop found and fixed:

  • cancellation and FIFO reentrancy during promotion;
  • preventDefault running before generation retirement;
  • listener installation continuing after synchronous retirement;
  • recursive synchronous worker responses overflowing the stack;
  • startup-failure queue transfer and ready-failure ownership errors;
  • postMessage accessor disposal/forged-response races;
  • a P1 physical-worker overlap during cleanup-triggered nested submission; and
  • same-worker identity reuse after termination.

Two independent reviewers approved the corrected pre-rebase patch. Two fresh
independent audits also approved the exact rebased head after rerunning Node,
Chromium, package, coverage, type, lint, integrity, placement, and demo gates.

API and rollout

This is implementation infrastructure only. It is not wired to sessions,
completion, diagnostics, or other public features. No compatibility or migration
work is required in this slice. The next consuming coordinator must preserve the
same bounded ownership and no-replay rules.


Summary by cubic

Adds a private, single-lane browser executor for the isolated SQL parser worker with bounded queueing, strict deadlines, and safe lifecycle handling. Internal only; no public or /vnext API changes. Hardened to fail closed on retirement errors with explicit terminal states.

  • New Features

    • Lazily creates at most one worker generation; posts one request at a time.
    • Bounded FIFO queue with request-count and UTF‑16 text limits; startup/queue/execution deadlines and prompt caller cancellation.
    • Retires crashed/timed-out/poisoned generations without replay; preserves never-posted queued work across replacement.
    • Rejects reused worker identities; retirement is serialized and atomic to avoid reentrancy races.
    • Executor, worker factory, protocol, and types remain private; docs updated and scripts/package-smoke.mjs asserts executor artifacts.
  • Bug Fixes

    • Fails closed if worker retirement throws to prevent accepting new work in an unsafe state.
    • Makes terminal states explicit to avoid resurrection and double settlement.

Written for commit 1cb7105. Summary will update on new commits.

Review in cubic

@github-actions

github-actions Bot commented Jul 24, 2026

Copy link
Copy Markdown

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 97.72% (🎯 91%) 386 / 395
🔵 Statements 97.73% (🎯 91%) 389 / 398
🔵 Functions 100% (🎯 90%) 62 / 62
🔵 Branches 96.52% (🎯 85%) 222 / 230
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
src/vnext/node-sql-parser-browser-executor.ts 97.73% 96.52% 100% 97.72% 473, 558, 655, 681, 914, 960-964, 1068
Generated in workflow #703 for commit 1cb7105 by the Vitest Coverage Report Action

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a package-private, browser/main-realm executor that serializes SQL parse requests through a bounded FIFO and manages isolated parser worker generations (deadlines, cancellation, retirement, and no-replay semantics) as groundwork for the /vnext isolated execution ADR.

Changes:

  • Introduces createNodeSqlParserBrowserExecutor with bounded queueing (count + UTF-16 units) and startup/queue/execution deadlines, plus robust worker generation lifecycle management.
  • Adds extensive Node (deterministic) and Chromium browser tests, including hostile/reentrant boundary cases and real-worker smoke coverage.
  • Updates packaging smoke checks and documentation/ADR text to reflect the new private executor infrastructure.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/vnext/node-sql-parser-browser-executor.ts Implements the bounded FIFO executor and worker generation lifecycle (deadlines, cancellation, retirement/no-replay).
src/vnext/browser_tests/node-sql-parser-browser-executor.test.ts Browser-level integration tests covering production worker path and recovery from silent/crash workers.
src/vnext/browser_tests/fixtures/node-sql-parser-silent-worker.js Fixture worker that becomes ready but never responds to parse requests (deadline coverage).
src/vnext/browser_tests/fixtures/node-sql-parser-crash-worker.js Fixture worker that crashes on message handling (retirement/recovery coverage).
src/vnext/tests/node-sql-parser-browser-executor.test.ts Large deterministic Node test suite validating edge cases, reentrancy, hostile workers, and deadline behavior.
scripts/package-smoke.mjs Ensures the new executor artifacts are present in the packed dist/vnext output.
docs/vnext/node-sql-parser-adapter.md Updates vnext adapter documentation to describe the new private executor responsibilities and guarantees.
docs/adr/0004-isolated-parser-execution.md Aligns ADR 0004 language with the new private bounded executor and no-replay/generation rules.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 8 files

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread src/vnext/node-sql-parser-browser-executor.ts
@Light2Dark
Light2Dark merged commit 873c926 into dev-refactor Jul 24, 2026
9 checks passed
@Light2Dark
Light2Dark deleted the codex/vnext-parser-executor branch July 24, 2026 21:01
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.

2 participants