fix(v0.44): bind page-route SSR tags to the compiled Part Program; gate workspace qualification in CI (#1276) (#1277)

Touches ADR-0122 frozen path entry-codegen.ts; amendment authority ADR-0151.

B1.3 qualification blocker B1.3-F1: entry codegen registered and rendered
definePage routes under the path-derived fileToTagName tag while the page
element's compiled Part Program carries its @element(...) tag; the 0.44
serializer fails closed on the mismatch (OE_PROGRAM_MISSING, phase ssr),
producing request-time HTTP 500 on /workspace-records, /magic-link and
/reset-password under both Node 24 serve.mjs and Wrangler workerd.

Repair per the thinker ruling: the route->program binding follows the
element's declared tag — the compiled program is the one canonical source.
The generated entry now resolves every page route's SSR tag at module
evaluation via __resolvePageTag(routeModule, fallbackTag), which reads the
route module's default-exported compiled class's __partProgram.tag and
keeps the path-derived tag only as the fallback for classes without a
compiled program (renderDsd still fails closed on those, exactly as
before). One canonical binding covers SSR registration, the page and 404
handlers, and the SSG routeInfo; .mdx pages are unaffected because their
compiled tag is path-derived by construction. The route file-convention
grammar (route-scanner.ts) keeps owning the ROUTE; it never owned the
element's identity, and static tag extraction there would need the
cross-file module analysis ADR-0148 excludes from the semantic core.

The B1.3 qualification also exposed a tooling drift it had masked: the
v0.44 fixture migration (c16b8dd) moved pagination from an
<a id="next-page" href> anchor to a GET form whose hidden inputs ride
compiled property Parts (dynamic intrinsic attributes are outside the SSR
part schema in grammar v1), so tools/qualify-workspace-runtime.ts now
reproduces the browser's GET form submission instead of scraping an
anchor.

Regression gate: fullstack:workspace-qualification is a required
autoflow-ci job, and the PR full-CI evidence set
(tools/autoflow/loop-evidence.ts REQUIRED_PR_CI_JOBS) is extended to
match — the provenance verifier fails closed on unregistered run jobs, so
the workflow change and the allow-list must move together.

entry-codegen.ts is an ADR-0122 frozen path; this repair is authorized
under the ADR-0151 Beta.1 framework-qualification boundary and changes no
public API (package surface and public interface snapshot unchanged).

Part of #1276. Part of #1224, #1150, #1155.

Co-authored-by: DevBot <devbot@openelement.dev>

Author: SisyphusZheng

.github/workflows/autoflow-ci.yml

@@ -112,6 +112,29 @@ jobs:
             grep -q 'requires a runtime with WHATWG URLPattern' serve-error.log
           fi
 
+  # #1276 (B1.3-F1): the definePage route SSR tag-mismatch defect shipped
+  # because the workspace runtime qualification was not CI-gated. Run the full
+  # qualification leg (starter build -> Node 24 standalone + Wrangler workerd,
+  # byte-identical HTML across both) as a required CI job so this defect class
+  # cannot regress silently. Needs real Node 24 (the serve.mjs runtime floor,
+  # #969) — the autoflow-ci job itself has no Node setup.
+  workspace-qualification:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          # #1156 R11: same exact-SHA expression as every required job.
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: ./.github/actions/setup-deno-workspace
+      # v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: '24'
+      - name: Workspace runtime qualification (Node 24 + workerd)
+        run: deno task fullstack:workspace-qualification
+
   # #1156 (ADR-0146): one deterministic exact-SHA PR full-CI evidence artifact.
   # This job runs only for pull requests and only after every required
   # full-matrix job succeeded (default needs gating — no `if: always()`), so a
@@ -122,7 +145,7 @@ jobs:
   pr-full-ci-evidence:
     name: pr-full-ci-evidence
     if: github.event_name == 'pull_request'
-    needs: [dependency-review, autoflow-ci, node-serve-smoke]
+    needs: [dependency-review, autoflow-ci, node-serve-smoke, workspace-qualification]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:

packages/adapter-vite/__tests__/entry-descriptor.test.ts

@@ -445,7 +445,7 @@ Deno.test('buildEntryDescriptor: plain element route keeps its tagName export (#
   assertEquals(desc.pageRoutes[0].defaultTagName, 'index-page');
 });
 
-Deno.test('renderEntry: definePage route registers and renders under the fallback tag (#960)', () => {
+Deno.test('renderEntry: definePage route binds its tag through the compiled program, never the tagName export (#960, #1276)', () => {
   const routes: RouteEntry[] = [
     {
       path: '/',
@@ -458,21 +458,29 @@ Deno.test('renderEntry: definePage route registers and renders under the fallbac
   ];
   const code = renderEntry(buildEntryDescriptor(routes));
 
-  // Registration and the page handler's jsx root both use the fallback tag —
-  // the exported content-element tag never appears in the registration call,
-  // so a module-self-registered content element can no longer shadow the
-  // definePage render (the issue's original failure mode).
-  assertStringIncludes(code, '__registerSsrComponent("index-page"');
+  // Registration and the page handler resolve the tag from the route module's
+  // compiled Part Program at entry evaluation (#1276); the path-derived
+  // fallback tag is the resolver's fallback argument only, and the exported
+  // content-element tag never appears — a module-self-registered content
+  // element can no longer shadow the definePage render (the #960 failure
+  // mode).
+  assertStringIncludes(
+    code,
+    '__registerSsrComponent(__resolvePageTag($pageIndex, "index-page")',
+  );
   assertEquals(code.includes('__registerSsrComponent("home-page"'), false);
-  assertStringIncludes(code, 'let __tag = "index-page"');
+  assertEquals(code.includes('__resolvePageTag($pageIndex, "home-page"'), false);
+  assertStringIncludes(code, 'let __tag = __resolvePageTag($pageIndex, "index-page")');
 });
 
-Deno.test('renderEntry: plain element route still registers under its tagName export', () => {
+Deno.test('renderEntry: plain element route binds its tag through the compiled program too (#1276)', () => {
   const routes: RouteEntry[] = [
     { path: '/', filePath: 'index.tsx', type: 'page', varName: 'pageIndex', tagName: 'home-page' },
   ];
   const code = renderEntry(buildEntryDescriptor(routes));
 
-  assertStringIncludes(code, '__registerSsrComponent("home-page"');
-  assertStringIncludes(code, 'let __tag = "home-page"');
+  // One canonical binding for every page route: the scanner's tagName export
+  // is the fallback argument; the compiled program tag wins at evaluation.
+  assertStringIncludes(code, '__registerSsrComponent(__resolvePageTag($pageIndex, "home-page")');
+  assertStringIncludes(code, 'let __tag = __resolvePageTag($pageIndex, "home-page")');
 });

packages/adapter-vite/__tests__/entry-render-ssg.test.ts

@@ -51,6 +51,10 @@ const $boom_route = {
   default: class BoomPage {},
 };
 function __pageDefinition(m) { return m?.default?.openElementPage || {}; }
+function __resolvePageTag(routeModule, fallback) {
+  const program = routeModule && routeModule.default && routeModule.default.__partProgram;
+  return program && typeof program.tag === "string" && program.tag.includes("-") ? program.tag : fallback;
+}
 function __routeMeta() { return {}; }
 function __isOpenElementRedirect(e) { return e && e.__openRedirect === true; }
 function __isOpenElementNotFound(e) { return e && e.__openNotFound === true; }

packages/adapter-vite/__tests__/page-route-tag-resolution.test.ts

@@ -0,0 +1,137 @@
+/**
+ * #1276 (B1.3-F1): definePage route SSR tag-mismatch repair.
+ *
+ * The route→program tag binding follows the element's declared tag — the
+ * compiled Part Program is the one canonical source. The route FILE name
+ * derives the ROUTE (path/fallback wiring), never the element's identity:
+ * entry codegen resolves the SSR registration/render tag from the route
+ * module's compiled program (`default.__partProgram.tag`) at generated-entry
+ * evaluation time, with the path-derived tag kept only as the fallback for
+ * classes that carry no compiled program (renderDsd still fails closed on
+ * those, exactly as before).
+ *
+ * Pre-fix, definePage routes registered/rendered under the bare path-derived
+ * tag, so a page element whose @element tag differed from the file-derived
+ * tag (e.g. routes/workspace-records.tsx -> @element('workspace-records-page'))
+ * failed closed at REQUEST time: renderDsd tag "workspace-records" does not
+ * match the compiled program tag "workspace-records-page" (OE_PROGRAM_MISSING)
+ * → HTTP 500. Proven by `deno task fullstack:workspace-qualification`.
+ */
+import { assertEquals, assertStringIncludes } from '@std/assert';
+import { buildEntryDescriptor, renderEntry } from '../src/internal/ssg/index.ts';
+import { renderRuntimeHelpers } from '../src/internal/ssg/entry-render-runtime.ts';
+import type { RouteEntry } from '../src/internal/protocol/framework.ts';
+
+const definePageRoutes: RouteEntry[] = [
+  {
+    path: '/workspace-records',
+    filePath: 'workspace-records.tsx',
+    type: 'page',
+    varName: 'pageWorkspaceRecords',
+    definePage: true,
+  },
+];
+
+const RESOLUTION_EXPR = '__resolvePageTag($pageWorkspaceRecords, "workspace-records")';
+
+Deno.test('renderEntry: definePage route registers through the compiled-program tag resolution (#1276)', () => {
+  const code = renderEntry(buildEntryDescriptor(definePageRoutes));
+
+  // Registration resolves the tag from the route module's compiled program;
+  // the path-derived tag survives only as the resolver's fallback argument.
+  assertStringIncludes(
+    code,
+    `__registerSsrComponent(${RESOLUTION_EXPR}, $pageWorkspaceRecords.default)`,
+  );
+});
+
+Deno.test('renderEntry: definePage route handler renders through the compiled-program tag resolution (#1276)', () => {
+  const code = renderEntry(buildEntryDescriptor(definePageRoutes));
+
+  assertStringIncludes(code, `let __tag = ${RESOLUTION_EXPR}`);
+});
+
+Deno.test('renderEntry: SSG routeInfo resolves the tag from the compiled program (#1276)', () => {
+  const code = renderEntry(buildEntryDescriptor(definePageRoutes, { ssg: true }));
+
+  assertStringIncludes(code, `tagName: ${RESOLUTION_EXPR},`);
+});
+
+Deno.test('renderEntry: styled 404 route renders through the compiled-program tag resolution (#1276)', () => {
+  const routes: RouteEntry[] = [
+    ...definePageRoutes,
+    {
+      path: '/404',
+      filePath: '404.tsx',
+      type: 'page',
+      varName: 'pageNotFound',
+      definePage: true,
+    },
+  ];
+  const code = renderEntry(buildEntryDescriptor(routes));
+
+  assertStringIncludes(code, 'let __tag = __resolvePageTag($pageNotFound, "el-404");');
+});
+
+interface ResolvePageTagHarness {
+  resolvePageTag(routeModule: unknown, fallback: string): string;
+}
+
+async function loadHarness(): Promise<ResolvePageTagHarness> {
+  const helpers = renderRuntimeHelpers({ default: false, layouts: {} }, []);
+  const harness = `
+const customElements = { get() { return undefined; } };
+const escapeHtml = (value) => String(value);
+const __locales = ["en"];
+const __getDefaultLocale = () => "en";
+const __navSections = [];
+const __headerNav = [];
+function renderDsd() { return { html: "" }; }
+${helpers}
+export function resolvePageTag(routeModule, fallback) { return __resolvePageTag(routeModule, fallback); }
+`;
+  const mod = await import('data:text/javascript;charset=utf-8,' + encodeURIComponent(harness));
+  return mod as ResolvePageTagHarness;
+}
+
+Deno.test('__resolvePageTag: compiled program tag wins over the path-derived fallback (#1276)', async () => {
+  const harness = await loadHarness();
+  // The definePage route module default-exports the compiled page class
+  // (definePage returns the class), whose __partProgram.tag is the @element
+  // tag — this is the mismatch shape from the B1.3 qualification.
+  const routeModule = { default: { __partProgram: { tag: 'workspace-records-page' } } };
+  assertEquals(harness.resolvePageTag(routeModule, 'workspace-records'), 'workspace-records-page');
+});
+
+Deno.test('__resolvePageTag: matching program and fallback tags resolve identically', async () => {
+  const harness = await loadHarness();
+  const routeModule = { default: { __partProgram: { tag: 'login' } } };
+  assertEquals(harness.resolvePageTag(routeModule, 'login'), 'login');
+});
+
+Deno.test('__resolvePageTag: no compiled program keeps the path-derived fallback (#1276)', async () => {
+  const harness = await loadHarness();
+  assertEquals(
+    harness.resolvePageTag({ default: class {} }, 'workspace-records'),
+    'workspace-records',
+  );
+  assertEquals(
+    harness.resolvePageTag({ default: undefined }, 'workspace-records'),
+    'workspace-records',
+  );
+  assertEquals(harness.resolvePageTag(undefined, 'workspace-records'), 'workspace-records');
+});
+
+Deno.test('__resolvePageTag: malformed program tags keep the path-derived fallback (#1276)', async () => {
+  const harness = await loadHarness();
+  // Not a custom-element tag (no hyphen) or not a string at all: never let a
+  // malformed program tag reach the registration/render call sites.
+  assertEquals(
+    harness.resolvePageTag({ default: { __partProgram: { tag: 'nohyphen' } } }, 'x-page'),
+    'x-page',
+  );
+  assertEquals(
+    harness.resolvePageTag({ default: { __partProgram: { tag: 42 } } }, 'x-page'),
+    'x-page',
+  );
+});

packages/adapter-vite/src/internal/ssg/entry-codegen.ts

@@ -14,9 +14,9 @@ import { quoteGeneratedJavaScriptValue } from './codegen-literals.ts';
 import {
   documentWrapOptionsLines,
   pageDefinitionExpr,
+  pageRouteTagExpr,
   rendererScopeMatches,
   routeMetaExpr,
-  routeTagNameExpr,
 } from './entry-route-helpers.ts';
 
 /**
@@ -336,7 +336,7 @@ export function renderRouteHandler(
     matchingRenderers: renderers.filter((r) => rendererScopeMatches(route.path, r.scope)),
     docConfig,
     pathLiteral: quoteGeneratedJavaScriptValue(route.path),
-    tagNameExpr: routeTagNameExpr(route.tagName),
+    tagNameExpr: pageRouteTagExpr(route.varName, route.tagName),
     pageDefExpr: pageDefinitionExpr(route.varName),
     routeMeta: routeMetaExpr(route.varName),
     routeContext: `{ path: ${quoteGeneratedJavaScriptValue(route.path)}, filePath: ${

packages/adapter-vite/src/internal/ssg/entry-descriptor.ts

@@ -221,11 +221,13 @@ export function buildEntryDescriptor(
         varName: `$${r.varName}`,
         filePath: r.filePath,
         defaultTagName: fallbackTagName,
-        // #960 (registration decoupling, Option 2): a definePage route always
-        // registers its page class under the path-derived fallback tag, so the
-        // definePage render always runs — its tagName export only names a
-        // content element and never drives registration. Plain element routes
-        // keep the exported tagName as their registration tag.
+        // #960 (registration decoupling, Option 2) + #1276 (B1.3-F1): a
+        // definePage route's tagName export only names a content element and
+        // never drives registration. For every page route the generated entry
+        // resolves the SSR tag from the route module's compiled Part Program
+        // at evaluation time (__resolvePageTag); the tag here is the
+        // resolver's path-derived fallback, used only when the class carries
+        // no compiled program.
         tagName: r.definePage === true ? fallbackTagName : (r.tagName || fallbackTagName),
         importPath: `/${routesDir}/${r.filePath}`,
         isDynamic,

packages/adapter-vite/src/internal/ssg/entry-not-found-codegen.ts

@@ -4,9 +4,9 @@ import { quoteGeneratedJavaScriptValue } from './codegen-literals.ts';
 import {
   documentWrapOptionsLines,
   pageDefinitionExpr,
+  pageRouteTagExpr,
   rendererScopeMatches,
   routeMetaExpr,
-  routeTagNameExpr,
 } from './entry-route-helpers.ts';
 
 interface RouteHandlerDocConfig {
@@ -30,7 +30,7 @@ export function renderNotFoundRoute(
   lines.push('app.notFound(async (c) => {');
   lines.push(`  const __responseHeaders = new Headers();`);
   lines.push(`  return __mergeChannelHeaders(await (async () => {`);
-  lines.push(`  let __tag = ${routeTagNameExpr(route.tagName)};`);
+  lines.push(`  let __tag = ${pageRouteTagExpr(route.varName, route.tagName)};`);
   lines.push(`  let __page = ${pageDefinitionExpr(route.varName)};`);
   lines.push(`  let __params = {};`);
   lines.push(`  let __routeMetaValue = ${routeMetaExpr(route.varName)};`);

packages/adapter-vite/src/internal/ssg/entry-orchestrator.ts

@@ -32,7 +32,7 @@ import type { EntryDescriptor } from '../protocol/ssg.ts';
 import { validateIslandModuleSpecifier } from './entry-generators.ts';
 import { renderActionRoute, renderPageRoute } from './entry-codegen.ts';
 import { renderNotFoundRoute } from './entry-not-found-codegen.ts';
-import { renderImport, routeTagNameExpr } from './entry-route-helpers.ts';
+import { pageRouteTagExpr, renderImport } from './entry-route-helpers.ts';
 import { renderApiRoute, renderMiddleware } from './entry-server-codegen.ts';
 import { renderRuntimeHelpers } from './entry-render-runtime.ts';
 import { renderActionRuntime } from './entry-action-runtime.ts';
@@ -186,8 +186,11 @@ export function renderEntry(desc: EntryDescriptor): string {
     lines.push('};');
     lines.push('');
     // #952: entry-side registration ownership tracking. Since #960
-    // (registration decoupling) a definePage route's page class registers
-    // under the path-derived fallback tag; v0.44 compiled modules never
+    // (registration decoupling) a definePage route's page class registration
+    // is decoupled from the module's tagName export; since #1276 (B1.3-F1) the
+    // registered tag resolves from the compiled Part Program
+    // (__resolvePageTag), with the path-derived tag as fallback. v0.44
+    // compiled modules never
     // self-register, so the entry owns every registration. The ownership
     // guard still covers dev re-evaluation — overwriting a fresh
     // self-registered class with the entry's page class would recurse when
@@ -211,7 +214,7 @@ export function renderEntry(desc: EntryDescriptor): string {
     lines.push('');
   }
   for (const route of desc.pageRoutes) {
-    const tagNameExpr = routeTagNameExpr(route.varName, route.tagName);
+    const tagNameExpr = pageRouteTagExpr(route.varName, route.tagName);
     lines.push(
       `try { __registerSsrComponent(${tagNameExpr}, ${route.varName}.default); } catch (err) { console.error('[ssg] Failed to register route custom element ${tagNameExpr}:', err); throw err; }`,
     );

packages/adapter-vite/src/internal/ssg/entry-render-runtime.ts

@@ -78,6 +78,28 @@ export function renderRuntimeHelpers(
   lines.push('}');
   lines.push('');
 
+  // #1276 (B1.3-F1): the compiled program is the one canonical source for the
+  // route→program tag binding. A definePage route module default-exports the
+  // compiled page class (definePage returns the class), whose
+  // __partProgram.tag carries the @element(...) decorator tag; the route FILE
+  // name derives the ROUTE, not the element's identity, so the bare
+  // path-derived tag must never reach renderDsd when the program declares a
+  // different one (request-time OE_PROGRAM_MISSING 500, B1.3 qualification).
+  // The path-derived fallback remains for classes without a compiled program —
+  // renderDsd fails closed on those exactly as before. Called at module
+  // evaluation (route registration, routeInfo), so this must stay a hoisted
+  // function declaration.
+  lines.push('function __resolvePageTag(routeModule, fallbackTag) {');
+  lines.push(
+    '  const program = routeModule && routeModule.default && routeModule.default.__partProgram;',
+  );
+  lines.push(
+    '  if (program && typeof program.tag === "string" && program.tag.includes("-")) return program.tag;',
+  );
+  lines.push('  return fallbackTag;');
+  lines.push('}');
+  lines.push('');
+
   lines.push('function __localizeShellHref(href, locale, defaultLocale) {');
   lines.push(
     '  if (typeof href !== "string" || locale === defaultLocale || !href.startsWith("/") || href.startsWith("//")) return href',

packages/adapter-vite/src/internal/ssg/entry-render-ssg.ts

@@ -10,8 +10,8 @@ import type { EntryDescriptor } from '../protocol/ssg.ts';
 import { quoteGeneratedJavaScriptValue } from './codegen-literals.ts';
 import {
   documentWrapOptionsLines,
+  pageRouteTagExpr,
   renderMatchingRenderersFn,
-  routeTagNameExpr,
 } from './entry-route-helpers.ts';
 
 /**
@@ -39,7 +39,7 @@ export function renderSsgSection(desc: EntryDescriptor): string {
   // --- routeInfo: structured route metadata ---
   lines.push('export const routeInfo = [');
   for (const r of desc.pageRoutes) {
-    const tagNameExpr = routeTagNameExpr(r.tagName);
+    const tagNameExpr = pageRouteTagExpr(r.varName, r.tagName);
     lines.push(
       `  { path: ${quoteGeneratedJavaScriptValue(r.path)}, filePath: ${
         quoteGeneratedJavaScriptValue(r.filePath)