@teamscala/service-boot 0.23.523 → 0.23.525

package/src/build-client-assets/source-candidates.ts

@@ -1,32 +1,12 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Tailwind source-candidate scanning for the client CSS build.
- *
- * Split out of build-client-assets.ts (1221 lines, six concerns). Owns ONE
- * concern: turning the resolved `@source` directories into the candidate token
- * set Tailwind's `build()` consumes.
- *
- * Why it exists at all, preserved from the original: Tailwind v4's low-level
- * `compile()` does NOT scan content, and @tailwindcss/oxide's native Scanner is
- * not a dependency of the bare `tailwindcss` lib — only of the integration
- * packages. So the tokens are extracted here. Over-extraction is safe, because
- * `build()` ignores any token that is not a valid utility. Dropping this scan is
- * what shipped an unstyled page to the operator's tablet on 2026-06-13; it is
- * enforced by `css-build-scans-source-candidates`.
- *
- * Byte-for-byte move — imports adjusted, nothing else.
  */
 
 import { resolve } from "node:path";
 import { stat } from "node:fs/promises";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 
-// Directory-capable existence probe. Bun.file().exists() answers false for
-// directories, so the @source roots (directories by construction) were all
-// "absent" and the candidate scan returned nothing.
 async function existsStat(path: string): Promise<boolean> {
 	try {
 		await stat(path);
@@ -36,16 +16,6 @@ async function existsStat(path: string): Promise<boolean> {
 	}
 }
 
-// Tailwind v4's low-level `compile()` does NOT scan content — `compiler.build( candidates)` only emits utilities for the candidate class names it is GIVEN.
-// `build([])` therefore emits ZERO content-driven utilities (only the static theme/base + @utility/@layer + imported package CSS). The workspace's own
-// blocks mostly use inline styles + hand-written `blk-*` package classes (no-tailwind-in-blocks / layout-properties-inline), so the missing utility
-// layer was invisible — until the Plate document editor (third-party shadcn components using raw `flex`/`p-1`/`bg-background/95`) rendered completely
-// unstyled (operator's tablet, 2026-06-13). The CLI we replaced (`b29e369` "in-process Bun compile") scanned content; the replacement dropped
-// the scan. This restores it: glob every resolved `@source` dir, extract candidate tokens, and feed them to `build()`. @tailwindcss/oxide's native
-// Scanner is NOT a dependency of the bare `tailwindcss` lib (only of the
-// integration packages), so we tokenize ourselves — over-extraction is safe
-// (build() ignores any token that isn't a valid utility). Enforced by
-// `css-build-scans-source-candidates`.
 const SCAN_EXTS = new Set([
 	".ts",
 	".tsx",
@@ -57,9 +27,6 @@ const SCAN_EXTS = new Set([
 	".md",
 	".mdx",
 ]);
-// Class-name candidate chars: identifiers, variant `:`, opacity `/`, arbitrary
-// values `[]()`, decimals `.`, important `!`, plus `#%,&-` seen in arbitrary
-// values and modifiers. Deliberately broad — invalid tokens are dropped by build().
 const CANDIDATE_RE = /[A-Za-z0-9_:/[\].%#!,&-]+/g;
 
 export async function scanSourceCandidates(
@@ -75,23 +42,7 @@ export async function scanSourceCandidates(
 		} catch {
 			continue;
 		}
-		// A resolved @source root absent on disk is benign: a published block
-		// package ships compiled output, not its src/ tree, so an `@source` into
-		// that package resolves to a non-existent dir. Skip silently rather than
-		// warn on every UI-service boot (the log-flood class — the ENOENT whose
-		// path rendered with a trailing null byte). Real errors below still warn.
-		// The probe MUST be a stat, never Bun.file(root).exists(): root is a
-		// DIRECTORY and Bun.file() on a directory reports exists() === false
-		// (the same defect discover-blocks.ts measured 2026-09-01). That probe
-		// skipped EVERY source, collapsed the candidate set to zero, and
-		// `build([])` stripped every Tailwind utility from every kind:ui
-		// service's stylesheet at once — the operator's "the css is totally
-		// fucked" with a stylesheet that loads and 15k package rules intact.
 		if (!await existsStat(root)) continue;
-		// A root INSIDE node_modules is an explicit `@source` into an installed
-		// block package (the app-css transform emits one per package) — scan it
-		// fully. A root OUTSIDE node_modules is the service's own tree — scan it
-		// but never descend into node_modules (the entire dependency graph).
 		const rootInNodeModules = root.includes("/node_modules/");
 		try {
 			const glob = new Bun.Glob("**/*");
@@ -114,8 +65,6 @@ export async function scanSourceCandidates(
 				if (matched) for (const t of matched) candidates.add(t);
 			}
 		} catch (err) {
-			// A bad source dir never aborts the whole CSS build (the other
-			// sources still contribute their utilities).
 			log.warn(
 				`[build-client-assets] candidate scan skipped ${root}: ${
 					err instanceof Error ? err.message : String(err)

package/src/build-client-assets/sourcemaps-upload.ts

@@ -1,44 +1,8 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
- * flow, then RETAIN the maps outside the served root so a failed upload is
- * retryable on a later boot.
- *
- * Split out of build-client-assets.ts (962 lines) alongside its build
- * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
- * else.
  */
 
-/**
- * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
- * flow (the documented first-class mechanism — `sourcemaps inject` then
- * `sourcemaps upload --release`; see telemetry.md `client-errors-report-to-glitchtip`
- * + https://glitchtip.com/documentation/cli). Debug IDs injected into the served
- * bundles + uploaded maps are the matching mechanism — robust vs URL-prefix
- * guessing.
- *
- * THE MAPS OUTLIVE THE UPLOAD ATTEMPT: `.map` files are MOVED out of the
- * served root (`dist/client/` — /assets/* would serve source publicly) into
- * the retained cache `dist/sourcemaps/<release>/` BEFORE anything else, and
- * the upload runs from the cache. A failed or skipped upload therefore
- * leaves the maps on disk for the next boot's retry (the fingerprint-skip
- * path in build-client-assets.ts re-runs the upload whenever the manifest
- * does not record `uploaded`) instead of destroying the only copy of a
- * release's maps on an unverified claim (`a-component-may-not-report-a-
- * state-it-has-not-verified`; measured: the pre-2026-09 flow deleted the
- * maps after an upload whose responses were never checked, so a missing
- * token or a 4xx permanently lost a release's maps while the boot log kept
- * saying "uploaded").
- *
- * Every upstream response is verified: the release-create call must return
- * 2xx/208 and each file upload must return 2xx, else the failure is named
- * (status + body head) in the result. Best-effort at the SERVICE level — a
- * failed upload never blocks boot — but never at the CLAIM level: the
- * result says what actually happened and the manifest records it.
- */
 
 import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
@@ -50,35 +14,22 @@ export type SourceMapUploadStatus = "uploaded" | "failed" | "skipped";
 
 export interface SourceMapUploadResult {
 	status: SourceMapUploadStatus;
-	/** Maps verified accepted by GlitchTip (2xx), never assumed. */
 	uploaded: number;
-	/** Maps present for this upload pass (moved to the retained cache). */
 	total: number;
-	/** One named failure per non-accepted upload (status + body head). */
 	failures: string[];
 	at: string;
 }
 
 const UPLOAD_TIMEOUT_MS = 30_000;
 
-/** The retained, never-served home of a release's source maps. */
 export function sourceMapsCacheDir(cwd: string, release: string): string {
 	return join(cwd, "dist", "sourcemaps", release);
 }
 
-/** The release (bare content hash) a manifest's hydratePath names. */
 export function releaseFromHydratePath(hydratePath: string): string | null {
 	return /hydrate-([a-z0-9]+)\.js/.exec(hydratePath)?.[1] ?? null;
 }
 
-/**
- * Move every `.map` in `outDir` whose base filename is in `currentOutputs`
- * into the retained cache for `release`, then DELETE every other `.map` left
- * in `outDir` (stale maps from an older build whose release cache should
- * already hold a copy — or, on Railway ephemeral disk, was lost; either
- * way the served root must never hold one). Returns the names that were
- * moved into THIS release's cache.
- */
 async function moveMapsToCache(
 	cwd: string,
 	outDir: string,
@@ -121,7 +72,6 @@ function authEnv(): { token: string; url: string } | null {
 	return { token, url };
 }
 
-/** Upload the maps ALREADY RETAINED in the cache for `release`. */
 export async function uploadCachedSourceMaps(
 	cwd: string,
 	release: string,
@@ -153,7 +103,6 @@ export async function uploadCachedSourceMaps(
 	return uploadMapsFromCache(cacheDir, names, release, auth, log, at);
 }
 
-/** Upload source maps for the bundle just built into `outDir`. */
 export async function uploadSourceMaps(
 	cwd: string,
 	outDir: string,

package/src/build-client-assets/styles-build.ts

@@ -1,26 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The Tailwind stylesheet unit of the client-asset build: Bun-native
- * stylesheet resolution returning RAW content, stripping of remote
- * (CSP-forbidden) @imports, and the content-hashed styles-<hash>.css
- * build.
- *
- * NESTED @IMPORTS ARE THE SUPPLIER'S JOB: tailwind 4.3.3's compile()
- * re-invokes loadStylesheet for every @import INSIDE loaded content and
- * splices the loaded nodes into the tree (verified in the installed
- * dist source — the dr() recursion, depth-capped at 100), so a present
- * nested leaf is inlined by the supplier and a missing one throws at
- * compile; the suite pins both. The 2026-07-05 dropped-leaf outage was
- * guarded by an in-process flattener here; with the supplier recursion
- * verified the flattener is a second owner of the same fact and is
- * deleted.
- *
- * Split out of build-client-assets.ts (962 lines) alongside its build
- * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
- * else.
  */
 
 import { dirname, join, resolve } from "node:path";
@@ -42,9 +22,6 @@ export async function bunResolveStylesheet(
 		return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 	}
 	if (id.startsWith(".")) {
-		// Relative import: resolve against the importing file's directory and
-		// REQUIRE existence — a missing leaf is a build-breaking error naming
-		// the specifier, never a silently-dropped subtree.
 		const p = resolve(base, id);
 		if (!(await Bun.file(p).exists())) {
 			throw new Error(
@@ -53,28 +30,11 @@ export async function bunResolveStylesheet(
 		}
 		return { path: p, base: dirname(p), content: await Bun.file(p).text() };
 	}
-	// A BARE SPECIFIER IS A PACKAGE NAME PLUS AN OPTIONAL SUBPATH, and the two
-	// must be separated before anything is looked up. `@teamscala/ui-foundation`
-	// is a package; `@teamscala/ui-foundation/theme/styles.css` is that same
-	// package plus an explicit file inside it. Treating the whole string as a
-	// package name looks for node_modules/@teamscala/ui-foundation/theme/
-	// styles.css/package.json, which cannot exist — so EVERY subpath import
-	// fails and the styles bundle dies, taking the theme layer with it.
-	//
-	// A scoped name is the FIRST TWO segments (@scope/name); an unscoped name
-	// is the first. Everything after that is a path inside the package and is
-	// resolved directly — it names a file, so there is nothing to negotiate and
-	// no style entry to consult.
 	const segments = id.split("/");
 	const nameLength = id.startsWith("@") ? 2 : 1;
 	const packageName = segments.slice(0, nameLength).join("/");
 	const subpath = segments.slice(nameLength).join("/");
 
-	// Find node_modules/<packageName>/package.json by walking upward from the
-	// importing file's dir then cwd. Bun.resolve is not used: it hands back
-	// whatever the package's main is — for a normal JS package a .js entry,
-	// not the declared stylesheet — and an `exports` allow-list blocks the
-	// package.json subpath on exactly the CSS-only packages this must serve.
 	const tried: string[] = [];
 	for (const root of [base, cwd]) {
 		let dir = root;
@@ -84,13 +44,6 @@ export async function bunResolveStylesheet(
 				const pkgDir = dirname(pkgPath);
 				const pkg = await Bun.file(pkgPath).json();
 				if (subpath) {
-					// THE EXPORTS MAP IS THE AUTHORITY ON WHERE A SUBPATH LIVES,
-					// and it commonly REMAPS. `@teamscala/ui-foundation` publishes
-					// "./theme/styles.css" -> "./src/theme/styles.css", so resolving
-					// the subpath literally against the package root looks for a
-					// file that has never existed there. Consult exports first and
-					// fall back to the literal path only for a package that
-					// declares none.
 					const exported = pkg.exports?.[`./${subpath}`];
 					const mapped: string | undefined =
 						typeof exported === "string"
@@ -107,7 +60,6 @@ export async function bunResolveStylesheet(
 					}
 					return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 				}
-				// No subpath: the package itself must declare its stylesheet.
 				const entry: string | undefined = pkg.exports?.["."]?.style ?? pkg.style;
 				if (!entry) {
 					throw new Error(
@@ -128,16 +80,6 @@ export async function bunResolveStylesheet(
 	);
 }
 
-// The app owns its fonts via an explicit, CSP-allowlisted <link> in index.html (Google Fonts — `style-src ... fonts.googleapis.com`, `font-src ...
-// fonts.gstatic.com`). Third-party package CSS MUST NOT inject its own remote `@import url(http…)`: @puckeditor/core/dist/index.css opens with
-// `@import "https://rsms.me/inter/inter.css"`, an arbitrary CDN our CSP does NOT allow. The Tailwind compile inlines that mid-output, where it was either
-// silently dropped (CSS spec: @import must precede all rules) OR — once hoisted —
-// blocked by CSP, leaving a console error on every page; either way the font
-// never loaded and the site fell back to a system font (scala-docs 2026-06-13).
-// So every remote @import is STRIPPED from the compiled bundle: a package can
-// never inject a CDN font/stylesheet, and the only font source is the app-owned
-// index.html link. Fixed once at the single CSS chokepoint; guarded by
-// `css-build-strips-remote-imports`.
 const REMOTE_IMPORT_RE =
 	/^[ \t]*@import\s+(?:url\(\s*)?["']https?:\/\/[^"')]+["']\s*\)?[^;]*;[ \t]*\n?/gm;
 
@@ -164,16 +106,6 @@ export async function buildTailwindCss(
 	await mkdir(outDir, { recursive: true });
 
 	const cssSource = await Bun.file(entry).text();
-	// base MUST be the ENTRY FILE's directory (src/), never the service root.
-	// The generated app.css authors its @source dirs relative to itself
-	// ("../node_modules/@teamscala/<pkg>/src"); Tailwind 4.3 resolves @source
-	// against THIS base, so passing the service root aimed every scan one
-	// level too high (workspace/node_modules — empty) and the candidate set
-	// collapsed to zero: build([]) strips every Tailwind utility and every
-	// kind:ui service renders with naked buttons/controls while the
-	// stylesheet still loads with its full package-rule payload (measured
-	// 2026-09-05, operator-visible fleet-wide). Package-specifier @imports are
-	// unaffected — they resolve through loadStylesheet's Bun.resolve walk.
 	const compiler = await compile(cssSource, {
 		base: join(cwd, "src"),
 		async loadStylesheet(id, base) {
@@ -186,8 +118,6 @@ export async function buildTailwindCss(
 		},
 	});
 
-	// Scan every resolved @source for candidate class names — WITHOUT this the
-	// build emits no content-driven utilities (the unstyled-editor bug above).
 	const candidates = await scanSourceCandidates(compiler.sources, log);
 	const cssOutput = stripRemoteImports(compiler.build(candidates));
 	log.info(

package/src/build-client-assets.ts

@@ -1,35 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Builds the per-service client bundle and stylesheet into `dist/client/`
- * at UI-service boot time. Outputs are content-hashed so deployments
- * naturally cache-bust:
- *
- *   src/entry-client.ts  ──bun build──>  dist/client/hydrate-<hash>.js
- *   src/app.css          ──tailwindcss──>  dist/client/styles-<hash>.css
- *   (and)                                  dist/client/asset-manifest.json
- *
- * The HTML template references `{{stylesPath}}` / `{{hydratePath}}` —
- * read-html-template.ts substitutes from the manifest at template-read
- * time. Bytes-level changes → new hash → new URL → browser refetch.
- * Without this, `cache-control: immutable` on a fixed filename means
- * returning visitors keep their stale copy forever.
- *
- * This module is the ORCHESTRATION unit: host-wide lock → parallel
- * hydrate/CSS builds → manifest write (or failure tombstone). The
- * build runs on EVERY boot: the content-fingerprint skip cache and its
- * closure-walking hashers (input-fingerprint.ts, input-hashing.ts) are
- * deleted. A skip is the only path that can serve a stale bundle, and
- * it has done so twice (the mtime skip that baked stale bundles until
- * the fingerprint replaced it, 2026-06-14) — no skip is the one shape
- * that cannot skip wrongly, at the cost of a bounded per-boot build
- * serialised by the host-wide lock below. The individual concerns live
- * as siblings under ./build-client-assets/
- * (source-candidates, manifest, hashed-output, hydrate-bundle,
- * sourcemaps-upload, styles-build, build-lock)
- * — split when the parent held them all at 962 lines.
  */
 
 	// Each build is wrapped in its own catch so a JS bundle failure (e.g. transient cross-package export drift) doesn't take down the service

package/src/capability-slug.ts

@@ -1,59 +1,15 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Deployable slug -> capability slug.
- *
- * A DEPLOYABLE is named `<capability>-<language>-<tier>`
- * (`deployables-carry-language-and-tier`, as amended by the operator ruling of
- * 2026-09-08: "so actually the apps are ts, not bun" — the language segment
- * spells the LANGUAGE, so Bun-launched services are `ts`): `scala-projects-ts-dev`
- * and `scala-projects-ts-prod` are two DEPLOYMENTS of one APPLICATION. The
- * ecosystem generator derives that name per lane, so one service arrives here
- * under a DIFFERENT identity in each lane.
- *
- * A `page_route` row describes the APPLICATION url space, which is the same
- * in both lanes, so it carries the CAPABILITY name and there is exactly one
- * row per route rather than one per lane. Joining the two by raw string
- * equality therefore matches at most one lane, and does so SILENTLY:
- * measured 2026-09-11, 8 of 10 dev UI services registered ZERO page routes
- * and served 404 on every path -- including `/sign-in` -- while booting
- * clean and reporting healthy, because the dev lane ran as
- * `scala-projects-bun-dev` while every page_route row said `scala-projects`.
- *
- * Both sides normalize through this one function, so the join is
- * tier-agnostic by construction and a row may name either form.
- *
- * The suffix grammar is a CLOSED SET defined by doctrine and emitted by the
- * generator, so this is a parse of a documented contract rather than a
- * pattern heuristic. A slug that does not end in one is already a capability
- * name and is returned unchanged.
- *
- * `bun` REMAINS IN THE SET AS RETIRED SPELLING TOLERANCE, mirroring the
- * generator side (`ecosystem/deployable_identity.rs capability_of` strips
- * `-ts`, `-bun` and `-rust`): the fleet was renamed under `-bun` and rows or
- * supervised names still carrying it must converge to the same capability
- * rather than fail the join during the migration window.
  */
 
-/** Language segment of a deployable name. `bun` is the retired spelling. */
 const LANGUAGES = ["ts", "bun", "rust"] as const;
 
-/** Tier segment of a deployable name. */
 const TIERS = ["dev", "prod"] as const;
 
 type Language = (typeof LANGUAGES)[number];
 type Tier = (typeof TIERS)[number];
 
-/**
- * The capability half of a deployable slug.
- *
- * `scala-projects-ts-dev`   -> `scala-projects`
- * `scala-projects-ts-prod`  -> `scala-projects`
- * `scala-projects-bun-dev`  -> `scala-projects` (retired spelling)
- * `scala-projects`          -> `scala-projects` (already a capability name)
- */
 export function toCapabilitySlug(slug: string): string {
 	const parts = slug.split("-");
 	if (parts.length < 3) return slug;

package/src/compose-page-title.ts

@@ -1,47 +1,14 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The single canonical page-title composer. Every SSR page handler routes
- * through this (portal/region-shell, public shell, single-page resource). A
- * page title is DERIVED from data that already exists — the website name +
- * the page/entity name — with `builda_pages.meta_title` as an explicit
- * per-page OVERRIDE only, never the primary source.
- *
- * Mirrors the brand-is-org-owned-full-scheme precedent: a value that should
- * be DERIVED was instead hand-set per row, and when unset it silently fell
- * back to something wrong. For themes the wrong fallback was the generic
- * light palette; for titles it was the bare org name — the `default`
- * page_meta_template `titleTemplate: "{org.name}"` produced "GBG Indo" with
- * no site or page context, and per-row `meta_title` carried stale product
- * literals like "Dashboard | scala Hub". The fix is identical in shape:
- * derive by default, override explicitly.
- *
- * Canonical format: `<website.name>: <subject>` (subject = entity title or
- * page name), site-first so a browser tab reads the surface then the page.
- * A resource surface (forms/quiz/gpt) may supply a curated `templateTitle`
- * (e.g. "{agent.name} — {org.name}"); it wins over the default derivation
- * but NOT over an explicit per-page override. The composer NEVER returns a
- * bare org name — that is the regression this closes, and the
- * `page-title-not-bare-org` guard backstops it at the template layer.
  */
 
 export interface TitleContext {
-	/** Per-page override (builda_pages.meta_title). Wins outright when set. */
 	pageMetaTitle?: string | null;
-	/** Resolved resource-template string (forms/quiz/gpt). Curated per-surface shape. */
 	templateTitle?: string | null;
-	/** builda_websites.name — the surface, the legacy site context (orgPrefix off). */
 	websiteName?: string | null;
-	/** The OWNING ORG's display name (brand.companyName, resolved from the
-	 * org the page's brand_org_path names). The title prefix when orgPrefix is
-	 * on — operator ruling 2026-08-17: a client-facing document's tab carries
-	 * the org's name, never the internal website label ("Public Pages"). */
 	organisationName?: string | null;
-	/** builda_pages.name — the page (e.g. "Dashboard"). */
 	pageName?: string | null;
-	/** Resource entity title (proposal/form/quiz/agent name) — preferred subject. */
 	entityTitle?: string | null;
 }
 

package/src/content-gate/access.ts

@@ -1,14 +1,6 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The content-gate ACCESS endpoint mounter. One generic POST handler for every
- * gate: a plain <form> posts {<recordIdField>, email}; on a match against the
- * resource's authorized set it sets the signed access cookie and redirects back,
- * so the page loader's gate then releases the content. No bespoke endpoint per
- * type — each gate is one AccessConfig. Mounted BEFORE the auth gate so it is
- * publicly reachable.
  */
 
 import type { Hono } from "hono";
@@ -38,36 +30,17 @@ export async function attachContentGateAccess(
 		let email = "";
 		let name = "";
 		let phone = "";
-		// Optional prospect segmentation a capture gate's composed form may post
-		// (the quiz identity screen: company, LinkedIn, website, team size). Every
-		// field is optional and every reader treats absence as "" — a gate that
-		// never collects them (the GPT) is unaffected, and a form that collects
-		// only some carries the rest as absent. Field names follow the response
-		// columns the segmentation lands in (linkedin_url / team_size, snake case)
-		// because the composed form posts exactly what its FormField rows name.
 		let company = "";
 		let linkedinUrl = "";
 		let website = "";
 		let teamSize = "";
 		let bodyFailed = false;
-		// The resource id may ride on the URL instead of the body. A gate whose
-		// form is COMPOSED FROM BLOCKS has no place to put a hidden field — the
-		// generic submit action collects the visible inputs and adds only the
-		// static fields its row declares, and a row is shared by every page so it
-		// cannot carry a per-page id. The gate therefore publishes its own access
-		// URL with the id already on it (see quiz-gate onUnauthorized), which
-		// keeps the id single-sourced from the resolved graph. A body field still
-		// wins where one is posted (proposals, agreements, the GPT).
 		const queryResourceId = String(c.req.query(config.recordIdField) ?? "").trim();
 		try {
 			const form = await c.req.parseBody();
 			resourceId = String(form[config.recordIdField] ?? "").trim() || queryResourceId;
 			email = String(form.email ?? "").trim().toLowerCase();
-			// Optional captured display name (open-capture gates carry it in the
-			// token; allow-list gates ignore it via signToken).
 			name = String(form.name ?? "").trim();
-			// Captured alongside the email by an open-capture gate's composed
-			// form. It rides in the signed token rather than any client store.
 			phone = String(form.phone ?? "").trim();
 			company = String(form.company ?? "").trim();
 			linkedinUrl = String(form.linkedin_url ?? "").trim();
@@ -82,9 +55,6 @@ export async function attachContentGateAccess(
 
 		let matched = false;
 		if (config.openCapture) {
-			// Open lead-capture gate (the public GPT): any non-empty email is a
-			// valid visitor — there is no allow-list to authorize against. We
-			// already required a non-empty email above, so this is a match.
 			matched = true;
 		} else {
 			try {
@@ -120,10 +90,6 @@ export async function attachContentGateAccess(
 				`${config.cookieName}=${encodeURIComponent(token)}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
 			);
 			if (config.entryCookieName) {
-				// The ENTRY MARKER: it authorizes exactly the redirect this sets it
-				// on — the gate requires it and the render it consumed clears it.
-				// Max-Age matches the token only as a safety net; consumption is
-				// what ends its life, never the clock.
 				c.header(
 					"Set-Cookie",
 					`${config.entryCookieName}=1; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,

package/src/content-gate/catalog.ts

@@ -1,58 +1,9 @@
 /**
  * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * THE CATALOG OF GATED CONTENT TYPES — the one place a gate is registered.
- *
- * The gate ENGINE (gate.ts) and the access MOUNTER (access.ts) were already
- * generic and config-driven, but the SEQUENCE was not: `register-registry-page-
- * route.ts` named proposalGateConfig + agreementGateConfig + gptGateConfig in a
- * hand-written array, and `two-phase-boot.ts` named the same three AccessConfigs
- * in a second hand-written array. Two lists, one fact, and adding a fourth gated
- * resource meant editing both — the same drift as the assistant, one layer down
- * (`information-exists-in-one-location`).
- *
- * Now both call sites iterate THIS. A gate is registered once, as a pair, and
- * the SSR gate and its public access endpoint cannot disagree about which gates
- * exist — the shape doctrine asks for when behaviour genuinely is code:
- * `business-logic-is-rows-plus-executors`, "extend the executor catalog".
- *
- * WHY A CATALOG AND NOT A REGISTRY ROW. A gate is not data — `verifyToken`,
- * `resolveAuthorizedEmails` and the withholding rules are executable behaviour,
- * which the rule places in a typed executor, never in a row. What belongs in a
- * row is the SELECTION: which gate governs a given page. That is a `page_route`
- * field, and a row can only select from a catalog, so this file is the thing it
- * will select from — not a step on the way to it.
  */
 
-/**
- * Registered gates, in evaluation order.
- *
- * ORDER IS LOAD-BEARING AND SO IT IS DECLARED, NOT INCIDENTAL. Proposals run
- * before agreements: an authorized proposal viewer has their gate block removed
- * from the resolved graph, after which the agreement gate finds no resource and
- * no-ops. Reversing these two changes behaviour on a page carrying both.
- *
- * Each gate still self-selects — `getResourceId` returns "" when the page is not
- * its kind — so listing a gate here never makes it apply to a page it does not
- * govern.
- */
 
-/**
- * Does this gate WITHHOLD content, or only identify the visitor?
- *
- * DERIVED FROM THE ACCESS CONFIG, NEVER DECLARED TWICE. `openCapture` already
- * states that any email is a valid visitor, which is precisely the case where
- * nothing is being withheld — the GPT page body is public and only its identity
- * is gated (see gptGateConfig.onUnauthorized, a documented no-op). A separate
- * `withholdsContent` flag would be a second copy of that fact, free to drift
- * from the one the access endpoint actually enforces (`offered-is-derived`).
- *
- * The distinction matters to the assistant: a seed-only gate must not count as
- * "governing" this page, or an anonymous visitor to a public GPT page would be
- * read as an unauthorized viewer and lose an assistant they are entitled to.
- */
 
 import type { AccessConfig, ContentGateConfig } from "./config-types.ts";
 import { agreementAccessConfig, agreementGateConfig } from "../agreement-gate.ts";
@@ -60,9 +11,7 @@ import { gptAccessConfig, gptGateConfig } from "../gpt-gate.ts";
 import { proposalAccessConfig, proposalGateConfig } from "../proposal-gate.ts";
 import { quizAccessConfig, quizGateConfig } from "../quiz-gate.ts";
 
-/** One gated content type: its SSR gate and its public access endpoint. */
 export interface ContentGateEntry {
-	/** Stable identity for this gate — what a `page_route` will name to select it. */
 	slug: string;
 	gate: ContentGateConfig;
 	access: AccessConfig;
@@ -79,7 +28,6 @@ export function withholdsContent(entry: ContentGateEntry): boolean {
 	return entry.access.openCapture !== true;
 }
 
-/** The gates that can withhold content, in order — the assistant's authority. */
 export function contentWithholdingGates(): ContentGateEntry[] {
 	return CONTENT_GATES.filter(withholdsContent);
 }