Skip to content

v3.0.2 patch release prep: correct globals docblock href round-trip contract - #9

Merged
acebytes merged 1 commit into
mainfrom
fix/globals-docblock-href-roundtrip
Aug 14, 2026
Merged

v3.0.2 patch release prep: correct globals docblock href round-trip contract#9
acebytes merged 1 commit into
mainfrom
fix/globals-docblock-href-roundtrip

Conversation

@acebytes

Copy link
Copy Markdown
Contributor

What

Fixes a codex epic-completion-review P1 for fn-182: packages/plugin-types/src/globals.ts (and the plugin-types README) taught the %3A → %253A percent-encoding double-encode as a pinned href round-trip divergence of the host URL shim.

That claim was disproven during fn-182.5's review: the shim parses with URL(string:) and serializes with absoluteString, and on that path pre-encoded query values round-trip verbatim — Desktop pins this via JSCURLCoherenceTests.testPreEncodedQueryRoundTripComputedRow (computed equality against Foundation on both first parse and href round-trip). The double-encode reproduces only via Foundation's URLComponents.queryItems construction path (the lapcatsoftware report), which the shim never uses. The corrected epic contract explicitly forbids teaching it as shim behavior.

Changes

  • globals.ts href accessor docblock: double-encode claim replaced with the verbatim round-trip statement
  • globals.ts constructor-level pinned-divergence list: double-encode bullet removed; a "NOT a divergence" note after the list explains that the %3A → %253A artifact is URLComponents.queryItems-only and does not apply to this API
  • packages/plugin-types/README.md divergence bullet aligned to the same contract
  • Swept the rest of the repo (docs-site, fixtures) — no other site repeats the claim
  • Pre-staged lockstep 3.0.2 bump exactly as the 3.0.1 release-prep did (npm version 3.0.2 --workspaces --include-workspace-root --no-git-tag-version --allow-same-version); release.sh detects the pre-staged bump and skips the empty bump commit

Validation

  • npm run build — clean across all three workspaces
  • npm test — exit 0; the 4-fixture globals gate passes (jsc-with-globals, jsc-types-array, jsc-without-globals, webview-dom)
  • docs-site npm run check-drift — green (drift-gate inputs are permissions.ts/core.ts/schemas; globals subpath is excluded from the TypeDoc program per 0487daf)

Publish

NOT published by this PR. Publish remains user-authorized: ./release.sh 3.0.2 post-merge (builds, tests, tags v3.0.2, publishes all workspaces). The dev-plugin mirror refresh happens after 3.0.2 publishes.

…s round-trip verbatim on href

The globals subpath docblock (and the plugin-types README) taught the
%3A → %253A percent-encoding double-encode as a pinned href round-trip
divergence of the host URL shim. That was disproven during fn-182.5's
review: the shim's URL(string:) → absoluteString href path preserves
pre-encoded query values VERBATIM (Desktop pins this via
JSCURLCoherenceTests.testPreEncodedQueryRoundTripComputedRow); the
double-encode reproduces only via Foundation's URLComponents.queryItems
construction path, which the shim never uses. The corrected epic
contract forbids teaching it as shim behavior.

- href accessor docblock: verbatim round-trip statement replaces the
  double-encode claim
- constructor divergence list: double-encode bullet removed; explicit
  "NOT a divergence" note explains the queryItems-only artifact
- README divergence bullet aligned

Also pre-stages the lockstep 3.0.2 bump (npm version 3.0.2 --workspaces
--include-workspace-root --no-git-tag-version --allow-same-version),
matching the 3.0.1 release-prep pattern; release.sh tolerates the
pre-staged bump. Publish remains user-authorized (./release.sh 3.0.2
post-merge).
@acebytes
acebytes merged commit 79de912 into main Aug 14, 2026
2 checks passed
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