@teamscala/service-boot 0.23.329 → 0.23.331

package/src/agreement-gate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The AGREEMENT content gate, expressed as config for the content-gate primitive
+ * (content-gate/). The agreement-specific bits: which resource (the placed
+ * SignIn gate block's id), who's authorized (the signer roster), what to seed
+ * (the verified signer's signing session into every SignatureField), and how to
+ * withhold (strip the gate region to gate-only + strip {{agreement.*}} chrome).
+ * The engine handles cookie/token/verify/orchestration.
+ *
+ * The signing logic (buildSigningSession, seedSigningBlocks, roster expansion,
+ * placeholder strip) is preserved verbatim from the former gate-agreement-
+ * content.ts — only the cookie/token orchestration moved into the shared engine.
+ */
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+export declare const agreementGateConfig: ContentGateConfig;
+export declare const agreementAccessConfig: AccessConfig;

package/src/asset-cache-key.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ETag derivation for the asset proxy that incorporates the negotiated
+ * image format so per-Accept variants cache independently.
+ */
+export type TargetFormat = "webp" | "avif" | "jpeg" | "png" | "gif" | "svg" | "ico" | "original";
+export declare function negotiateFormat(acceptHeader: string | null, storedContentType: string): TargetFormat;
+export declare function buildEtag(baseEtag: string, format: TargetFormat): string;

package/src/asset-optimize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * On-the-fly image optimisation for the asset proxy. Converts stored
+ * PNG/JPEG to WebP or AVIF when the browser signals support, using
+ * @teamscala/image-optimizer's compressImage primitive. Returns null
+ * on failure so the caller can fall back to the original stream.
+ */
+import type { TargetFormat } from "./asset-cache-key.ts";
+export interface OptimizeResult {
+    data: Buffer;
+    format: string;
+    processedSize: number;
+}
+export declare function optimizeImage(buffer: Buffer, targetFormat: TargetFormat): Promise<OptimizeResult | null>;

package/src/asset-proxy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Same-origin S3 asset proxy with on-the-fly image optimisation.
+ * Streams objects from the configured S3 bucket, converting PNG/JPEG
+ * to WebP/AVIF when the browser declares support via Accept header.
+ * Returns 404 for missing keys, 502 for S3 failures. Never redirects.
+ */
+export declare function handleAssetProxy(req: Request): Promise<Response>;

package/src/asset-social-card.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Dynamic-import wrapper around image-optimizer's in-process sharp
+ * social-card op. Mirrors asset-optimize.ts's optional-dependency shape:
+ * services without image-optimizer installed transparently get null and
+ * fall back to the raw asset stream. In-process (not HTTP) because the
+ * og:image transform is a cold path per shared link — no auth handshake,
+ * no per-consumer service config.
+ */
+export interface SocialCardOutcome {
+    data: Buffer;
+    processedSize: number;
+}
+export declare function renderSocialCard(buffer: Buffer): Promise<SocialCardOutcome | null>;

package/src/attach-agreement-magic.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The agreement MAGIC-LINK endpoint. A recipient who clicks an emailed
+ * "Review & sign" link — which carries a pre-authorised, signed ag_token for
+ * THEIR party — lands here: the token is verified for the agreement, the
+ * ag_token cookie is set on the shared parent domain, and the browser is
+ * 302-redirected straight into the signing page. No email-entry gate, no OTP —
+ * "came from our email" IS the proof of identity, exactly like the
+ * proposal-accept hand-off (attach-proposal-accept.ts).
+ *
+ * The token is the same HMAC ag_token the gate verifies (30-min TTL, scoped to
+ * {agreementId, email}); an invalid/expired/forged token sets no cookie and the
+ * destination page simply shows the normal email gate. GET so it is a plain
+ * clickable link in an email.
+ */
+import type { Hono } from "hono";
+export declare function attachAgreementMagic(app: Hono, serviceSlug: string): Promise<void>;

package/src/attach-portal-members.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Portal-secured member directory endpoint. Resolves members of an org via a
+ * parameterized raw join over better_auth_member + "user" — NOT the typed
+ * `member` ORPC model, which is deliberately omitted from the portal's
+ * service_schema (security: the raw table is not exposed as a typed CRUD
+ * surface). Mirrors the agreement-gate.ts:109-150 precedent.
+ *
+ * The portal's auth middleware (better-auth-cookie) gates the endpoint — only
+ * authenticated users can call it. The orgId comes from the caller's context
+ * (the portal resolves it from the session + passes it).
+ *
+ * Endpoint: GET /api/portal/members?orgId=<uuid>
+ *   - orgId omitted: super-admin all-orgs mode (returns every member across
+ *     all orgs, strictly gated to super-admin via getSession; used by the
+ *     "View As" impersonation dropdown).
+ * Response: { members: Array<{ id, user_id, organization_id, role, email, name, image }> }
+ */
+import type { Hono } from "hono";
+export declare function attachPortalMembers(app: Hono): Promise<void>;

package/src/attach-proposal-accept.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The proposal ACCEPT endpoint. A viewer who has passed the proposal gate (holds
+ * a valid prop_token) POSTs {proposalId} here to accept; the server generates a
+ * signing document from the proposal (createAgreementFromProposal) and
+ * 302-redirects them straight into signing it on the sign site. This replaces
+ * the old mailto CTA. Mounted BEFORE the auth gate so it is publicly reachable —
+ * the prop_token (not a login) is the proof of identity, exactly like the
+ * content-gate access endpoint.
+ *
+ * Single sign-on across the journey: the viewer already proved their email at
+ * the proposal gate (prop_token), so we MUST NOT make them re-enter it on the
+ * sign site. Before redirecting, we mint the agreement's ag_token for that same
+ * verified email and set it on the SHARED parent domain (Domain=.scala.business)
+ * so the browser carries it from proposals.scala.business to sign.scala.business
+ * — the agreement gate then auto-reveals + seeds the signing session with zero
+ * extra prompts. This requires both hosts to resolve the SAME token secret
+ * (AUTH_SECRET→ENCRYPTION_KEY→DATABASE_URL): scala-sign must carry ENCRYPTION_KEY
+ * (also required to decrypt the org's Stripe key on full sign), so both hosts
+ * land on ENCRYPTION_KEY and the carried token verifies.
+ */
+import type { Hono } from "hono";
+export declare function attachProposalAccept(app: Hono, serviceSlug: string): Promise<void>;

package/src/attach-proposal-magic.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The proposal MAGIC-LINK endpoint — the proposal twin of attach-agreement-magic.
+ * A recipient who clicks an emailed "View your proposal" link (carrying a signed,
+ * per-recipient prop_token) lands here: the token is verified for the proposal,
+ * the prop_token cookie is set, and the browser is 302-redirected straight into
+ * the proposal page. No email-entry gate, no OTP. An invalid/expired token sets
+ * no cookie and the page falls through to the normal email gate.
+ *
+ * The prop_token is host-scoped (proposals are served on the proposals host only),
+ * unlike the agreement ag_token which spans .scala.business for the proposal→sign
+ * hand-off. GET so it is a plain clickable link in an email.
+ */
+import type { Hono } from "hono";
+export declare function attachProposalMagic(app: Hono, serviceSlug: string): Promise<void>;

package/src/attach-transfers-upload.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Authenticated asset upload — POST /api/transfers/upload. Restores the
+ * handler deleted with @teamscala/server-files (commit ca5643ef); avatar/logo
+ * upload had 404'd on every service since. Writes to S3 via
+ * @teamscala/object-storage/create/write-ops and returns the STORED-form URL
+ * (`/api/files/<key>`) the client persists into avatar_url/logo_url — the
+ * display path rewrites it to the public `/api/assets/<encoded-key>` proxy
+ * via `toAssetPath` (@teamscala/formatters/asset-url). Self-authenticates
+ * (getSession) so it mounts BEFORE the auth gate.
+ *
+ * Key scheme is USER-scoped (`users/<userId>/<type>/<file>-<ts>.<ext>`) per
+ * the operator ruling: a profile picture belongs to the individual, not any
+ * org (the prior handler's org-scoped `<orgId>/avatars/...` encoded the
+ * uploading org into a personal asset). Spec + history:
+ * `reference/asset-upload-system.md`.
+ *
+ * `thumbUrl` mirrors `url` — the full image is served for both; a separate
+ * generated thumbnail is a future refinement (the prior handler generated
+ * one, but the image-resize dependency is not wired here yet and a missing
+ * thumb must not block the upload restoring).
+ */
+import type { Hono } from "hono";
+export declare function attachTransfersUpload(app: Hono): Promise<void>;

package/src/auth-gate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Auth middleware factory. Three modes, same BetterAuth email-OTP mechanism:
+ *
+ *   service_install.auth values:
+ *   - omitted | "none"            → no gate, no handler (scala-public, scala-sign)
+ *   - "better-auth-cookie"        → full session auth: mount handler + session gate
+ *   - "email-otp-only"            → mount handler (OTP send/verify), no session gate
+ *
+ *   The sign-in block determines the UX per mode:
+ *   - "full"         → email → OTP → session → portal selection (portal, agents, docs, gpt)
+ *   - "email-gate"   → email → OTP → verify-only, no session (forms, proposals, quiz)
+ *   - "capture-only" → email field only, no OTP (sign)
+ *
+ *   There is NO localhost bypass: 127.0.0.1 is gated identically to the tunnel
+ *   (no session → /sign-in). Tools needing an authed view sign in
+ *   (getSuperAdminSessionCookie); the dev OTP is DB-readable.
+ *
+ *   When SCALA_OTP_URL is set, /api/auth/* forwards to the centralised
+ *   scala-otp service (per otp-centralised-via-otp-service). Otherwise
+ *   the local better-auth handler is used (dev-host fallback).
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { Hono } from "hono";
+export declare function attachAuthGate(app: Hono, config: ServiceInstallConfig, serviceSlug: string): Promise<void>;

package/src/auth-gate.ts

@@ -43,61 +43,6 @@ const SIGN_IN_PATHS = new Set([
 	"/magic-link",
 ]);
 
-/// A STATIC ASSET IS NEVER A PROTECTED RESOURCE, so it is decided by EXTENSION
-/// rather than by remembering to list it.
-///
-/// The allowlist below enumerates PREFIXES, and every path outside it is gated.
-/// That makes a new public asset directory private BY DEFAULT, and the failure
-/// lands exactly where it hurts most: on the SIGNED-OUT screen, which is the one
-/// page guaranteed to need branding. `/assets/` was listed; `/logos/` never was,
-/// so `/logos/cropped.png` answered 302 → /sign-in and the browser rendered a
-/// blank logo under a "starting up" splash. Favicons are on the list ONE FILE AT
-/// A TIME, which is the same defect already visible.
-///
-/// This is why the operator reports it "keeps regressing": nothing is broken by
-/// a code change, the allowlist simply never covered the path, and any build that
-/// moves images re-creates it. Enumerating what is public is `prevention-over-
-/// detection` inverted — the cure is a predicate, not a longer list.
-///
-/// Redirecting an <img> to a login page is never useful behaviour either: the
-/// browser cannot act on the redirect, so it silently paints nothing. Failing
-/// closed on a page is protection; failing closed on an image is just a blank.
-const STATIC_ASSET_EXTENSIONS = [
-	".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".bmp",
-	".woff", ".woff2", ".ttf", ".otf", ".eot",
-	".css", ".js", ".mjs", ".map",
-];
-
-/**
- * Point the event-log primitive at the process's Prisma singleton.
- *
- * Driver-agnostic `write` callback backed by the Prisma singleton
- * (`one-db-surface` — no second postgres). Lazy, and it takes precedence over
- * any `prisma:` configure, so this writer is authoritative for authed services.
- * The previous form passed the ORPC server client (`getServerClient()`) cast
- * `as never` as `prisma:` — that client has no `$executeRaw`, so `recordEvent`
- * silently failed. Routing it through ORPC would reintroduce exactly that.
- * Retention is owned by the event-log-sweep pg-boss job.
- *
- * EXTRACTED so its name states what it is. This is a `configured-primitives`
- * INJECTION — handing a client to a primitive's configure() — not a query, and
- * `no-direct-prisma-outside-orpc` cannot tell the two apart by AST. It exempts
- * initialization, which is precisely what this is; buried inside
- * `attachAuthGate` the call read as an arbitrary getPrisma() and blocked every
- * unrelated edit to this file. Naming the boot step honestly is the fix. The
- * registry refused a path exemption for it, correctly — `guard-exemptions-to-zero`.
- */
-function initGateDependencies(): { prisma: ReturnType<typeof getPrisma> } {
-	const prisma = getPrisma();
-	configureEventLog({ prisma });
-	return { prisma };
-}
-
-export function isStaticAssetPath(pathname: string): boolean {
-	const lower = pathname.toLowerCase();
-	return STATIC_ASSET_EXTENSIONS.some((ext) => lower.endsWith(ext));
-}
-
 const PUBLIC_INFRA_PREFIXES = [
 	"/assets/",
 	"/api/assets/",
@@ -169,11 +114,12 @@ const PUBLIC_INFRA_PATHS = new Set([
 	// the other dev-host infra reads.
 	"/api/fleet/claude-sessions",
 	// /api/fleet/ingest-event receives parsed lane-action events
-	// (message.part.updated etc.) from the cli-session transcript-tail — a
+	// (message.part.updated etc.) from the cli-session Claude transcript-tail — a
 	// dev-host INTERNAL machine caller that POSTs with no session cookie, exactly
 	// like the lane-event hook. Without this exemption the page auth-gate 302s
 	// every POST and the lane's tool/text action stream never reaches the
-	// ingestEvent pipeline. A first-class
+	// ingestEvent pipeline (fleet_run_events stays empty → the dashboard console
+	// shows only lifecycle lines, never the per-tab action feed). A first-class
 	// api_route (sibling to lane-event); security is the handler's loopback gate
 	// on the platform's x-caller-remote-address (set by register-api-routes).
 	"/api/fleet/ingest-event",
@@ -218,10 +164,7 @@ export async function attachAuthGate(
 	// The previous form passed the ORPC server client (`getServerClient()`) cast
 	// `as never` as `prisma:` — no `$executeRaw`, so recordEvent silently failed.
 	// Retention is owned by the event-log-sweep pg-boss job.
-	// Resolved ONCE at boot and closed over by the request path below.
-	// `configured-primitives`: config arrives at startup and is injected downward,
-	// never pulled from a singleton inside a per-request handler.
-	const { prisma: gatePrisma } = initGateDependencies();
+	configureEventLog({ prisma: getPrisma() });
 	const { registerAuthFactory, getAuth } = await import(
 		"@teamscala/auth/auth-registry.ts"
 	);
@@ -353,12 +296,7 @@ export async function attachAuthGate(
 		const url = new URL(c.req.url);
 		const isInfra =
 			PUBLIC_INFRA_PATHS.has(url.pathname) ||
-			PUBLIC_INFRA_PREFIXES.some((p) => url.pathname.startsWith(p)) ||
-				// Decided by EXTENSION so a new asset directory cannot be private by
-				// default. The enumerated prefix list is what left /logos/*.png gated,
-				// redirecting an <img> to /sign-in and painting a blank logo on the one
-				// screen guaranteed to need branding.
-				isStaticAssetPath(url.pathname);
+			PUBLIC_INFRA_PREFIXES.some((p) => url.pathname.startsWith(p));
 		if (isInfra) return next();
 
 		// NO localhost bypass: a 127.0.0.1 page request is gated EXACTLY like a
@@ -422,7 +360,7 @@ export async function attachAuthGate(
 				// caller of the single permission decision point (unified permission system
 				// foundation, work_items 019f7d6b) — replaces the bespoke inline query.
 				const decision = await resolveAccess({
-					prisma: gatePrisma as never,
+					prisma: getPrisma() as never,
 					userId: session.user.id,
 					allowedOrganisationIds: allowed,
 				});

package/src/bind-page-handler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Calls a createPageHandler() handler with the per-request extras the
+ * SSR pipeline needs: the resolved userId/orgId (from localhost-bypass
+ * or better-auth-cookie), and the htmlTemplate. Shared by the regions
+ * and page_slug shell variants.
+ */
+import type { Context } from "hono";
+type PageHandler = (req: Request, extras: Record<string, unknown>) => Promise<{
+    body: unknown;
+    status: number;
+    headers: HeadersInit;
+}>;
+export declare function bindPageHandler(c: Context, handler: PageHandler, authMode: string, serviceSlug: string, label: string, resourceOrgId?: string): Promise<Response>;
+export {};

package/src/build-client-assets/input-hashing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Input hashing for the client-asset build fingerprint.
+ *
+ * Split out of build-client-assets.ts, which had grown to 1221 lines holding
+ * six distinct concerns (lock + status, manifest, hydrate bundle, source maps,
+ * stylesheet/tailwind, and this). `single-purpose-file` did not catch it: that
+ * rule flags a file whose top-level exports share no common name root, which
+ * measures export-NAME cohesion rather than how many concerns a file holds — so
+ * a large file with few tidily-named exports stays invisible to it.
+ *
+ * This module owns ONE concern: turning the build's real inputs into a stable
+ * hash. `computeInputFingerprint` (still in the parent, and still the only
+ * exported entry point) composes the two functions exported here; everything
+ * else is module-private because nothing outside needs it.
+ *
+ * Byte-for-byte move — imports adjusted, nothing else. No renames, no type
+ * changes (`migrations-copy-not-rewrite`).
+ */
+import { createHash } from "node:crypto";
+export declare function hashResolvedPackageStylesheets(cwd: string, h: ReturnType<typeof createHash>): Promise<void>;
+export declare function hashTeamgbgJsGraph(cwd: string, h: ReturnType<typeof createHash>): Promise<void>;

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

@@ -0,0 +1,27 @@
+/**
+ * @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 { getAppLogger } from "@teamscala/logger/app-loggers";
+export declare function scanSourceCandidates(sources: Array<{
+    base: string;
+    pattern: string;
+    negated?: boolean;
+}>, log: ReturnType<typeof getAppLogger>): Promise<string[]>;

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

@@ -0,0 +1,50 @@
+/**
+ * @system server-handlers
+ * @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.
+ *
+ * Content-fingerprint cache: the CLIENT-BUNDLE DEPENDENCY CLOSURE (source
+ * entrypoints + every @teamscala/* module/stylesheet the bundle reaches + the
+ * resolved versions of the third-party deps the closure imports) is hashed by
+ * CONTENT and stored in the manifest; the rebuild is skipped only when the
+ * current closure hashes to the same fingerprint (cache-key-hashes-source-
+ * inputs-only — never mtime; see computeInputFingerprint for why mtime silently
+ * served stale bundles on Railway). bun.lock is deliberately NOT hashed — it
+ * encodes every @teamscala/* version including backend packages outside this
+ * service's client bundle, so folding it in would rebuild on every publish
+ * (the publish→rebuild storm; `no-uncontrolled-repetition-or-cascade`). First
+ * pm2 restart after a real closure change pays the full build cost; unchanged
+ * restarts skip. Stale hashed outputs from a prior build are removed in the
+ * same pass so dist/client/ doesn't accumulate dead files.
+ */
+/**
+ * Read ONLY the tombstone state of the current manifest — the runtime
+ * (read-html-template, ui-service) calls this to decide whether to surface a
+ * build-failure signal. Returns null when the manifest is fresh (no
+ * `buildFailed`). Decoupled from the full AssetManifest read so the runtime
+ * never depends on the build internals.
+ */
+export declare function readClientBuildStatus(cwd?: string): Promise<{
+    failed: true;
+    reason?: string;
+    at?: string;
+} | {
+    failed: false;
+}>;
+export declare function stripRemoteImports(css: string): string;
+export declare function computeInputFingerprint(cwd: string): Promise<string>;
+export declare function buildClientAssets(serviceSlug: string): Promise<void>;

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

@@ -167,7 +167,7 @@ describe("computeInputFingerprint", () => {
 	});
 
 	// Regression guard for the 2026-07-12 scala-agents stale-bundle bug. A boot
-	// that builds MID-INSTALL (dep-sync restarts after writing the new
+	// that builds MID-INSTALL (package-poller restarts after writing the new
 	// bun.lock but before node_modules extraction finishes) bakes OLD @teamscala/*
 	// JS while the lock-derived fingerprint records "current" — so every later
 	// restart recomputes the same fingerprint, skips the rebuild, and serves the

package/src/build-client-assets.ts

@@ -84,7 +84,7 @@ export async function readClientBuildStatus(
 
 // Single shared host lock serialising the heavy boot-time client build across
 // ALL kind:ui services (client-asset-builds-serialize-via-lock). A publish of a
-// widely-consumed package makes the dep-sync restart every consumer at
+// widely-consumed package makes the package-poller restart every consumer at
 // once; without this lock each one rebuilds its hydrate bundle + Tailwind CSS
 // simultaneously and N concurrent builds saturate the host (load 36, each ~15s
 // build starved to ~10min, services offline — 2026-06-13). The build sibling of

package/src/compose-page-title.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @system ui-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 primary site context. */
+    websiteName?: 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;
+}
+export declare function composePageTitle(ctx: TitleContext): string;

package/src/content-gate/access.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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";
+import type { AccessConfig } from "./config-types.ts";
+export declare function attachContentGateAccess(app: Hono, serviceSlug: string, config: AccessConfig): Promise<void>;

package/src/content-gate/config-types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The config contracts that PROGRAM a content gate. Each gated content type
+ * (agreement, proposal, …) is one ContentGateConfig + one AccessConfig — no
+ * bespoke gate functions per type; the engine (gate.ts) and the access mounter
+ * (access.ts) are the single shared primitive driven by these.
+ */
+type Resolved = Record<string, unknown>;
+/** Drives the SSR-time gate (gate.ts / runContentGate). */
+export interface ContentGateConfig {
+    /** Cookie that carries this gate's access token (e.g. "ag_token"). */
+    cookieName: string;
+    /**
+     * The gated resource id from the resolved graph, or "" when this gate does
+     * not apply to the current page (the engine then no-ops). This is also how a
+     * gate detects "is this my kind of page". Async to allow DB-backed resolution
+     * (e.g. agreement gate resolving the UUID from the page→agreement association
+     * when no pre-placed gate block exists).
+     */
+    getResourceId(resolved: Resolved): string | Promise<string>;
+    /**
+     * Verify the cookie's token for this resource → the verified identity
+     * ({email, optional display name}), or null. Token-agnostic by design:
+     * proposals use the shared content-gate token; agreements keep their existing
+     * token (also minted by the signing ORPC), so the engine never assumes one
+     * token format. Allow-list gates return just {email}; the GPT lead-capture
+     * gate also returns the captured name (carried in its token).
+     */
+    verifyToken(token: string | undefined, resourceId: string, nowMs: number): {
+        email: string;
+        name?: string;
+    } | null;
+    /**
+     * BAKED-IN unified auth. When a gate provides this resolver, the engine
+     * AUTOMATICALLY releases a logged-in viewer whose session email is in the
+     * authorized set — with no valid token and no per-gate code. This is the
+     * platform default for EVERY gated resource: any application surface with
+     * authentication gets "a signed-in, authorized viewer is never re-asked for
+     * their email/OTP" for free, just by exposing its authorized-email set (the
+     * same resolver its AccessConfig uses). Not called when the session is
+     * anonymous. Omit only for open-capture gates that have no authorized set.
+     */
+    resolveAuthorizedEmails?(resourceId: string): Promise<Set<string>>;
+    /**
+     * OPTIONAL OVERRIDE of the baked-in session check above — for the rare gate
+     * whose session→identity rule isn't simply "session email ∈ authorized set".
+     * When present it wins; otherwise the engine uses `resolveAuthorizedEmails`.
+     * Called only when no valid access token is present.
+     */
+    sessionAuthorize?(resolved: Resolved, resourceId: string): {
+        email: string;
+        name?: string;
+    } | null | Promise<{
+        email: string;
+        name?: string;
+    } | null>;
+    /** Reveal + seed the verified viewer's identity/session (token was valid). */
+    onAuthorized(resolved: Resolved, resourceId: string, identity: {
+        email: string;
+        name?: string;
+    }): void | Promise<void>;
+    /** Withhold content (strip/inject the gate) — token absent/invalid. Async-
+     *  capable so a gate can load its display/behaviour settings from a registry
+     *  row (DB-driven, not hardcoded); sync implementations remain valid. */
+    onUnauthorized(resolved: Resolved, resourceId: string): void | Promise<void>;
+}
+/** Drives the public access endpoint (access.ts / attachContentGateAccess). */
+export interface AccessConfig {
+    /** Route to mount, e.g. "/api/proposal-access". */
+    path: string;
+    /** Cookie to set on a match. */
+    cookieName: string;
+    /** Cookie lifetime in ms (Max-Age). */
+    ttlMs: number;
+    /** Form field carrying the resource id, e.g. "proposalId". */
+    recordIdField: string;
+    /**
+     * Open lead-capture gate: ANY non-empty email is accepted (no allow-list).
+     * For surfaces whose "gate" captures a visitor rather than authorizing one
+     * against a fixed set (the public GPT). When true, `resolveAuthorizedEmails`
+     * is not called. Default/omitted = allow-list mode (proposals, agreements).
+     */
+    openCapture?: boolean;
+    /**
+     * The authorized email set for a resource (lowercased), checked server-side.
+     * Not called when `openCapture` is true.
+     */
+    resolveAuthorizedEmails(resourceId: string): Promise<Set<string>>;
+    /**
+     * Mint the access token for a matched email (token-agnostic per gate).
+     * `name` is the optional captured display name (open-capture gates carry it
+     * in the token; allow-list gates ignore it).
+     */
+    signToken(resourceId: string, email: string, nowMs: number, name?: string): string | null;
+}
+export {};