Skip to content

refactor(element,tools): B2.13 cleanup — #1273 O1/O2 + dead v0.43 residue audit gate - #1310

Merged
SisyphusZheng merged 3 commits into
devfrom
v044/b2.13-1273-v043-residue-cleanup
Sep 4, 2026
Merged

refactor(element,tools): B2.13 cleanup — #1273 O1/O2 + dead v0.43 residue audit gate#1310
SisyphusZheng merged 3 commits into
devfrom
v044/b2.13-1273-v043-residue-cleanup

Conversation

@SisyphusZheng

Copy link
Copy Markdown
Member

Problem

Issue #1273 records two observations from the v0.44 hostile admission audit
(docs/evidence/2026-09-03-v044-hostile-admission-audit.md):

  • O1: route-manifest.ts documented the catch-all file convention as
    /products/* while the tested behavior is the Hono named-regex parameter
    /products/:slug{.+} (route-manifest.test.ts:144).
  • O2 (D13): the legacy marker-hydration constants (data-signal*,
    data-eid, oe-branch:, oe-for-item:) and the public DATA_SSR_PROPS
    re-export outlive their removed channel — the compiled model claims through
    oe:pN program anchors, and app/preact.ts already documents the
    data-ssr-props channel as gone.

Stage risk #8 on #1288 additionally asks: what do the published v0.44 package
artifacts ship that the v0.44 execution/authoring model no longer consumes?
Every package publishes src/**, so any dead source module goes straight to
npm.

Owner

Single-owner cleanup: @openelement/element internal protocol/core modules
plus one adapter doc comment. No architectural ownership moves.

Before

  • Catch-all doc comment described /products/* (never the tested semantics).
  • DATA_SSR_PROPS publicly exported from @openelement/element root,
    classed internal-importable, zero consumers repo-wide.
  • Five proven-dead modules shipped in the packed @openelement/element
    tarball (see audit table).
  • No gate stopped dead v0.43 modules/markers from re-entering published
    artifacts.

After

  • Doc comment matches the tested /products/:slug{.+} semantics.
  • DATA_SSR_PROPS re-export removed; the five dead modules deleted;
    hydration-markers.ts slimmed to the one live marker (DATA_OE_LIGHT,
    ADR-0142) with a corrected contract header; render.ts slimmed to its live
    types (public RenderOutput/SsrAdmissionDecision shapes unchanged).
  • check-package-artifacts.ts (already ci+release tier, runs on the packed
    tarballs) now rejects the deleted paths and the removed marker-channel
    strings in packed sources.

Why-not-second-owner

No second implementation or owner exists: the audit's D13 classified the
markers as an observation, not a live duplicate. The compiled Part Program
runtime (internal/compiled/*) is the single reactive/SSR path; nothing here
creates or moves an owner.

Residue audit (stage #1288 risk #8)

Method: import-graph reachability from every deno.json exports entrypoint
and CLI/bin entry of all five published packages, plus repo-wide symbol
search (rg) over packages/, www/, tools/, examples/, e2e/
including all test dirs; cross-checked against the packed tarball file list
(pack:dry-run), the public-interface snapshot, and PACKAGE_SURFACE.md.
Hits in e2e/starter-smoke/work/deps/ are stale copies of an old published
package, not consumers.

Candidate Verdict Proof
element/src/types.ts (ElementDefinition, render(): VNode) deleted zero importers repo-wide; not in any exports map, snapshot, or surface class list; legacy runtime-renderer typing
element/src/internal/protocol/vnode.ts (VNode & friends) deleted only importers were types.ts (deleted) and render.ts's DsdComponent (removed); no other consumer
element/src/internal/protocol/prop.ts (PropDecl*, PropsFrom) deleted zero importers repo-wide; superseded by compiler __compiledProperties metadata
element/src/internal/core/dom-utils.ts (clearChildren) deleted zero importers incl. tests; call sites use replaceChildren() directly
element/src/internal/core/dsd-shadow-root.ts (hasPopulatedShadowRoot) deleted zero importers incl. tests
hydration-markers.ts legacy constants + parseSignalAttrSpec deleted zero importers; the marker literals (data-eid, data-signal*, oe-branch:, oe-for-item:) are already forbidden in built artifacts by check-v044-legacy-absence.ts; claim uses oe:pN anchors
DATA_SSR_PROPS public re-export (index.ts, public-runtime.ts) deleted zero importers repo-wide; channel documented gone (app/preact.ts:14); classed internal-importable, not stable; snapshot + surface + content-graph regenerated (only delta: this symbol)
render.ts: RenderPhase, RenderInput, RenderHooks, DsdOptions, RenderErrorCode, DsdComponentConstructor, DsdComponent deleted zero consumers repo-wide; live renderDsd carries its own RenderDsdOptions in public-runtime.ts; remaining public shapes byte-identical in the snapshot
hydration-markers.ts DATA_OE_LIGHT kept live ADR-0142 light-mode SSR marker; consumed as a string literal across the generated-code boundary by design (compiled server/runtime, adapter toolchain); module is the chartered name source (same pattern as ssr-registry-markers.ts)
element/src/internal/protocol/ssr-registry-markers.ts kept chartered #965 SSR-registry stub marker contract; no import edge by design (writer is generated code); stale reader list in its header corrected (define-element.ts no longer exists)
adapter-vite: enhance-client.ts, form-enhance.ts, morph-align.ts, morph-focus-restore.ts, morph-scroll-restore.ts, morph-webkit-fix.ts, island-lifecycle.ts, island-scheduler.ts kept not statically reachable from exports because they are bundled browser runtimes: dev-island-client.ts:69-72 and cli/build-client.ts:534-537 resolve them by file path via virtual:open-client-runtime (#868); form-enhance.ts/morph-* are additionally ADR-0122 frozen
render.ts live types (RenderError, RenderOutput, HydrationHint, DsdRenderMetrics, SsrAdmissionDecision) kept publicly re-exported (RenderOutput, SsrAdmissionDecision) or imported by the error protocol (RenderError); snapshot-pinned
app/ui/create packages no residue found reachability from exports covers 100% of their shipped src/** files

Anti-regression gate

tools/check-package-artifacts.ts (runs pack:dry-run, then scans the
extracted tarballs; gated at ci+release tiers in tools/autoflow/policy.ts,
triggered by any packages/** change):

  • FORBIDDEN_LEGACY_PATHS — the five deleted modules fail the gate if they
    reappear in a packed artifact.
  • FORBIDDEN_LEGACY_SOURCE_PATTERNSDATA_SSR_PROPS, data-eid/
    data-signal* attribute strings and oe-branch:/oe-for-item: comment
    markers are rejected in comment-stripped packed sources, extending the
    check-v044-legacy-absence.ts dist contract to the published src/**
    payload.

Unit tests cover both rules plus comment/other-package false-positive guards
(tools/check-package-artifacts.test.ts, 3 new tests).

Evidence

All at branch tip on macOS arm64, Deno 2.x:

  • deno task test → exit 0 (ok | 1870 passed (105 steps) | 0 failed | 1 ignored; supabase starter suite 150 passed | 0 failed)
  • deno task interface:snapshot → exit 0 (regenerated; sole delta is the
    DATA_SSR_PROPS symbol removal)
  • deno task package-surface:check → exit 0
  • deno task content-graph:check / api-reference:check → exit 0
    (byte-identical regeneration)
  • deno task graph:check / export-files:check → exit 0
  • deno task freeze:semantics:check → no frozen path touched by this change
    (verified against FROZEN_PATHS; no ADR-0151 citation required)
  • deno task package-artifacts:check (includes pack:dry-run, publint,
    attw) → exit 0 for all 5 packages
  • deno lint / deno fmt --check on all touched files → clean

Packed-artifact diff (intentional, recorded): @openelement/element
tarball loses exactly src/types.ts, src/internal/protocol/vnode.ts,
src/internal/protocol/prop.ts, src/internal/core/dom-utils.ts,
src/internal/core/dsd-shadow-root.ts; src/internal/protocol/render.ts,
src/internal/protocol/hydration-markers.ts, src/index.ts,
src/public-runtime.ts shrink. Verified via tar -tzf on the dry-run
tarball (118 entries; none of the deleted paths present). Other four
packages: no content change (adapter-vite ships the corrected comment only).

Scope

In: #1273 O1/O2, B2.13 residue audit + gate. Out: no compiler/Part
Program/runtime/public-architecture redesign; no ADR-0122 frozen path
touched; adapter browser runtimes and charter modules kept with documented
proof.

Risk

Low. Every deletion is backed by zero-consumer proof across the repo and the
packed artifact; the public-surface delta is one internal-importable symbol
whose channel is already documented as removed. External deep imports of
deleted modules are not part of the supported surface (not in any exports
map). If a downstream pin relied on DATA_SSR_PROPS, the constant's value
was the string 'data-ssr-props' from a channel that no runtime reads.

Closes #1273. Stage #1288 risk #8.

DevBot added 3 commits September 4, 2026 19:43
…e doc (#1273 O1)

The module doc documented routes/products/[...slug].tsx as /products/*,
but scanRoutes (#556) converts a catch-all segment to the Hono named-regex
parameter :slug{.+} matching across '/'. Pinned by
__tests__/route-manifest.test.ts ('catch-all [...slug].tsx →
/products/:slug{.+}'). Comment only; no behavior change.

Refs #1273
…O2, B2.13)

Dead-code proof (import graph from every deno.json exports entrypoint +
CLI/bin entries, plus repo-wide symbol search incl. tests, www, tools,
examples): zero consumers for each removal. All five deleted modules were
shipped to npm because every package publishes src/**.

Deleted:
- src/types.ts (ElementDefinition render()->VNode typing of the removed
  runtime renderer)
- src/internal/protocol/vnode.ts (VNode/ComponentFn/ComponentCtor/RenderFn)
- src/internal/protocol/prop.ts (ADR-0052 static prop-decl typing,
  superseded by compiler __compiledProperties)
- src/internal/core/dom-utils.ts (clearChildren, unused since #902-era
  renderer removal)
- src/internal/core/dsd-shadow-root.ts (hasPopulatedShadowRoot, unused)

Slimmed:
- internal/protocol/render.ts: dropped the legacy DSD-pipeline interfaces
  (RenderPhase, RenderInput, RenderHooks, DsdOptions, RenderErrorCode,
  DsdComponentConstructor, DsdComponent) and the VNode import; kept the
  live RenderError/RenderOutput/HydrationHint/DsdRenderMetrics/
  SsrAdmissionDecision contract unchanged (snapshot shapes identical).
- internal/protocol/hydration-markers.ts: removed the v0.43 marker
  constants (DATA_SIGNAL*, DATA_EID, DATA_SSR_PROPS, BRANCH_MARKER_PREFIX,
  FOR_ITEM_PREFIX, FOR_END_PREFIX) and parseSignalAttrSpec. The compiled
  model claims through oe:pN program anchors; the marker literals are
  already forbidden in built artifacts by check-v044-legacy-absence.ts.
  DATA_OE_LIGHT stays: it is the live ADR-0142 light-mode marker, consumed
  via literals across the generated-code boundary by design.

Public surface: DATA_SSR_PROPS re-export removed from src/index.ts and
src/public-runtime.ts. The data-ssr-props channel was already documented
as gone (app/preact.ts); the export was classed internal-importable, had
no consumer anywhere in the repo, and is deleted rather than deprecated
per the B2.13 removal authority. Interface snapshot, package-surface
class map and content graph regenerated; the only snapshot delta is the
DATA_SSR_PROPS symbol removal.

Also fixes the stale reader list in ssr-registry-markers.ts (element's
define-element.ts no longer exists; the SSR stub marker is read by
app/preact.ts).

Refs #1273. Stage #1288 risk #8.
…, B2.13)

check-package-artifacts.ts scans the packed npm tarballs (which ship
src/**), so it is the cheapest honest place to keep the B2.13 deletions
from silently reappearing in a release:

- FORBIDDEN_LEGACY_PATHS: the five proven-dead @openelement/element
  modules removed in the B2.13 audit fail the gate if they ever re-enter
  the packed artifact.
- FORBIDDEN_LEGACY_SOURCE_PATTERNS: the removed marker-hydration channel
  (DATA_SSR_PROPS export, data-eid/data-signal* attributes,
  oe-branch:/oe-for-item: comment markers) is rejected in comment-stripped
  packed sources, extending the check-v044-legacy-absence.ts dist contract
  to the published src payload.

The gate is already wired at ci+release tiers in tools/autoflow/policy.ts
(package-artifacts:check) and runs before consumer:packaged. Unit tests
cover both rules plus comment/other-package false-positive guards.

Refs #1273. Stage #1288 risk #8.
@SisyphusZheng
SisyphusZheng merged commit aa3dd70 into dev Sep 4, 2026
11 checks passed
@SisyphusZheng
SisyphusZheng deleted the v044/b2.13-1273-v043-residue-cleanup branch September 4, 2026 12:05
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