fix(reliability): preflight clipboard size and traversal budget

[cursor]

Scope

Closes #163 and #327. This remains the canonical Inkspan writer for SafeClipboard resource preflight: reject obviously oversized HTML before UTF-8 allocation and enforce the queued-node budget before child materialization. It also now owns the narrow customer-guidance presentation contract for the rejection codes it already emits.

No transport, auth, tenancy, persistence, credentials, deployment, retention, durable audit, model policy, or release authority is added. Draft #351 remains the earlier dedicated writer for hostile thrown-value containment (#349); do not fold that boundary into this branch. Draft #164 remains superseded and must stay unmerged.

Live boundary

• Protected shipped truth: main@128a239f8b71ca16add4b9e15e21752d1ad63ff0.
• Exact current Draft head: 47032a59c2cd2fc040c00793dcf819f44577acd3 on cursor/bc-9fd6356f-8539-49e9-9129-02a28cd4a490-7e7b.
• Fresh comparison to protected main is diverged: merge base 3b38ead2d00f44eb578d0689087b9293b3dabe1e, ahead 9 / behind 156. This is therefore not Ready or merge evidence; synchronization must preserve fix(security): fail closed on hostile clipboard throw values #351/fix(reliability): preflight clipboard size and traversal budget #359 ownership order and must not be destructive.
• Current-head workflow evidence is presently absent and therefore non-passing. Predecessor successful runs do not transfer.

Test-first lineage

Resource preflight:

• RED 51f9edfdff7de9072cafa8cebaf068dc39f92208: oversized ASCII still reached TextEncoder, and a three-child fragment exceeded the traversal budget only after excess NodeList.item() reads.
• GREEN 71654a8e59eecd72f2a23ebec173e4e537c927d9: short-circuit obvious size overflow before encoding and enforce visited + queued + enqueueable <= maxNodes before materialization.
• Doctoring convergence 58f004e5053e2a9b686814b4b9c724ab389a83ec documents the bounded operational contract.

Customer guidance:

• RED contract 37105d712c774b7ef638315d7d691311fd52c1ad: SafeClipboardCustomerGuidance.test.ts requires actionable, privacy-safe messages for input_too_large, node_limit_exceeded, depth_limit_exceeded, and invalid_html; the source at that commit still emitted implementation-oriented messages. No hosted run exists for that test-only head, so the source/test contradiction is the RED evidence.
• GREEN source d0255ecb05e77b3c98f365c51fc3a15c630c736a: preserves stable machine-readable codes while replacing those four customer-facing messages with next-action guidance.
• Compatibility-contract updates 4cfa7eff674c8d66dd1e10b61beba6324ca307a7, 8185d86a413c216335b4f9a10521ef5beead8d3f, and current head 47032a59c2cd2fc040c00793dcf819f44577acd3 align the existing exact-message tests with that contract. Redaction remains intact: messages contain no pasted source content, credentials, tenant identifiers, or host internals.

Integration boundary

Keep this PR Draft/unmerged until it is reconciled with the then-live protected main and the earlier #351 SafeClipboard owner without racing or destructive rebasing. After any synchronization, refetch exact head/base, formal reviews/threads, rulesets, and every applicable CI/security/coverage/SAST/package/release job including actual checkout SHAs. Pending, absent, skipped, stale, predecessor, aggregate-only, or synthetic-merge-only evidence is non-passing.

#118 remains the canonical v0.6.0 release/publication authority.

[cursor]

Assessment

This is a current-main successor for clipboard UTF-8 and maxNodes preflight (#163 / #327). The production change is the right shape:

• sourceHtml.length > maxHtmlBytes short-circuits before TextEncoder.prototype.encode.
• assertTraversalCapacity(visited + queued + enqueueable) runs before NodeList.item().
• Closed-details uses the same queue invariant.
• Redacted codes/messages are unchanged.
• Doctoring uses APA 7th citations (Unicode 16.0 §3.9, ECMA-262 string length, WHATWG DOM, CWE-770, Clipboard API WD) and tells the host to raise only the matching ceiling.

Writer conflict

Issue #327 still names Draft #164 as the sole SafeClipboard writer. #164’s live base is stale (50ac98c, not current main@e8109ec) and also carries hostile-throw branding plus release-workflow convergence. Draft #351 remains the current-main writer for clipboard throw-value containment (#349).

Prefer this PR for the resource-preflight product change on current main. Keep #164 unmerged. Do not fold throw-value or release-workflow work into this branch.

Next action

1. Keep Draft/unmerged while #118 owns v0.6.0.
2. Re-verify exact-head CI/Security/SAST on the unchanged head before any Ready decision.
3. If a paste is rejected with input_too_large or node_limit_exceeded, measure a trusted source and raise only that ceiling.

  

_{Sent by Cursor Automation: Fix Issues}

[seonghobae]

Exact-head local validation for 9ab6980: seven clipboard preflight, guidance, adapter, and documentation contract files reached 28/30 tests passed. Two failures are stale expectations in SafeClipboardPreflightSize.test.ts and SafeClipboardTraversalBudget.test.ts: the implementation returns the current actionable messages for input_too_large and node_limit_exceeded, while those tests still expect the former generic messages. The PR is dirty and this validation did not modify its branch.

[seonghobae]

Restacked onto exact parent #351 head d7f83fc8ffb7b086e027f116e0965bbd2753214b; exact head is d7a8a3212421c7990cb4e4e8f580e651742d8cf6. The PR base is now the parent branch so ownership and review evidence follow the actual SafeClipboard dependency order.

Integration repair:

• preserved both parent security hardening and child resource-preflight/customer-guidance behavior
• aligned four stale exact-message assertions with the child public guidance contract while preserving stable codes and redaction

Fresh verification:

• focused SafeClipboard stack: 9 files / 34 tests passed
• TypeScript typecheck: passed
• full Vitest suite: 162 files / 892 tests passed
• coverage: 100% statements, branches, functions, and lines
• Python support contract: 4 passed
• unresolved review threads: 0

This remains draft and dependency-gated by #351/#118.

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.