chore: sync the frontend template from ebea300 to af3d8e6
Carries 359 template commits, tag v0.2.0 plus one documentation commit: the generator-built feature index with its app, bounded-context and feature declarations, the src/platform kernel and scale tooling, the 2026-09-24 src review fixes, and the 2026-09-25 maturity review round with its CHANGELOG [보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them merged with product changes; 127 are not carried. Product identity is unchanged: name, version 0.1.0, routes, design and the TechLog domain. Three decisions worth naming. TechLog stays composed directly, as the last two syncs recorded; its directory carries a NOT_INSTALLED marker that says so, and every installed-* composer takes the template's projection with TechLog added on top. The reference sample is no longer installed: the template now installs a feature only through feature-module.ts and context-routes.ts, which load the screens this product deleted, so its three operations, six schemas and one topic leave the registries, recorded as registry change evidence. And AppRouter mounts the platform and TechLog routes only; the template's bounded-context route gateway waits for a generator-installed feature. Required fixes: readSubject on the BFF session owner (without it every HTTP Studio session would close as integration-failed), zod through the facade in nine TechLog files, noUnusedLocals, and public/config.json written out to match the local profile. Derived baselines were recomputed after reproducing both sides' values: CI contract 101 commands / 106 references / 141 artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime config schema baseline equals the schema at8210d48. Verified here: types, lint, architecture, adapter inventory, CI contract, i18n, design system, diagnostics, browser security, dev release manifest, TechLog contract and build pass; 220 component, 155 integration, 15 contract, 418 TechLog, 43 reference-feature, 18 recipe and 46 release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at8210d48first and unchanged: check:registries (byte-identical), test:runtime-schema, verify:documentation. Brought by the template and escalated rather than suppressed: check:request-fanout on TechLog's cursor pagination, check:remediation-ledger (fails upstream too), the shared-chunk hash test, and the registry-dependent sample removal and second-feature tests. Playwright suites were not run. Full record, the five open questions and the follow-ups in docs/operations/template-sync-2026-09-29.md. (cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
import { createBrowserStorageAdapter } from "../adapters/storage/index.ts";
|
||||
import {
|
||||
createReleaseMismatchRecovery,
|
||||
type RecoveryMarkerStore,
|
||||
type ReleaseMismatchDecision,
|
||||
} from "../platform/release/release-mismatch-recovery.ts";
|
||||
import { BootConfigError } from "./load-runtime-config.ts";
|
||||
import { ReleaseManifestError } from "./load-release-manifest.ts";
|
||||
|
||||
/**
|
||||
* Boot-time release-mismatch recovery (spec §45). The reload-once marker is
|
||||
* the registered session key `RELEASE_MISMATCH_RECOVERY`, reached only through
|
||||
* the approved browser storage adapter. Without a working session store the
|
||||
* adapter refuses to persist (`no-persist`), so recovery fails closed.
|
||||
*/
|
||||
const RECOVERY_KEY = "RELEASE_MISMATCH_RECOVERY";
|
||||
|
||||
const RELEASE_MISMATCH_KINDS: ReadonlySet<string> = new Set([
|
||||
"BUILD_MISMATCH",
|
||||
"PROTOCOL_PAIR_MISMATCH",
|
||||
"CONFIG_MISMATCH",
|
||||
"API_CONTRACT_MISMATCH",
|
||||
"RELEASE_MISMATCH",
|
||||
"ASSET_MISMATCH",
|
||||
"CONTRACT_SET_MISMATCH",
|
||||
]);
|
||||
|
||||
/** A stable key for a boot failure that is a release mismatch, else null. */
|
||||
export function releaseMismatchKey(error: unknown): string | null {
|
||||
if (error instanceof ReleaseManifestError && RELEASE_MISMATCH_KINDS.has(error.kind)) {
|
||||
return `${error.safe.buildId}:${error.code}:${error.safe.releaseId ?? "-"}`;
|
||||
}
|
||||
if (error instanceof BootConfigError && error.code === "CONFIG_BUILD_MISMATCH") {
|
||||
return `${error.safe.buildId}:${error.code}:${error.safe.releaseId ?? "-"}`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function sessionStorageOf(host: Record<string, unknown>): Storage | undefined {
|
||||
try {
|
||||
const candidate = Reflect.get(host, "sessionStorage") as unknown;
|
||||
if (!candidate || typeof candidate !== "object") return undefined;
|
||||
return ["getItem", "setItem", "removeItem"].every(
|
||||
(method) => typeof Reflect.get(candidate, method) === "function",
|
||||
)
|
||||
? (candidate as Storage)
|
||||
: undefined;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
export function createBootReleaseRecovery(
|
||||
host: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
|
||||
) {
|
||||
const sessionStorage = sessionStorageOf(host);
|
||||
const storage = createBrowserStorageAdapter(
|
||||
sessionStorage === undefined ? {} : { sessionStorage },
|
||||
);
|
||||
const store: RecoveryMarkerStore = Object.freeze({
|
||||
read() {
|
||||
const result = storage.read(RECOVERY_KEY);
|
||||
return result.ok && typeof result.value === "string" ? result.value : null;
|
||||
},
|
||||
write(value: string) {
|
||||
if (!storage.write(RECOVERY_KEY, value).ok) {
|
||||
throw new Error("release recovery marker was not persisted");
|
||||
}
|
||||
},
|
||||
clear() {
|
||||
storage.remove(RECOVERY_KEY);
|
||||
},
|
||||
});
|
||||
return createReleaseMismatchRecovery(store);
|
||||
}
|
||||
|
||||
/**
|
||||
* Decides what a failed boot does: a release mismatch may reload at most once
|
||||
* per session within the marker TTL; anything else (and any further mismatch)
|
||||
* shows the failure.
|
||||
*/
|
||||
export function decideBootFailure(
|
||||
error: unknown,
|
||||
recovery: ReturnType<typeof createBootReleaseRecovery>,
|
||||
): ReleaseMismatchDecision {
|
||||
const key = releaseMismatchKey(error);
|
||||
return key === null ? "show-failure" : recovery.decide(key);
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
import { recordBootFailure } from "../adapters/diagnostics/index.ts";
|
||||
import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.tsx";
|
||||
import {
|
||||
createBootReleaseRecovery,
|
||||
decideBootFailure,
|
||||
} from "./boot-release-recovery.ts";
|
||||
import { createRuntimeComposition } from "./create-runtime-composition.ts";
|
||||
import { initializeColorScheme } from "./initialize-color-scheme.ts";
|
||||
import { ReleaseManifestError } from "./load-release-manifest.ts";
|
||||
import { BootConfigError } from "./load-runtime-config.ts";
|
||||
import { unexpectedBootFailure } from "./render-boot-failure.tsx";
|
||||
import { RuntimeApplication } from "./runtime-application.tsx";
|
||||
|
||||
/**
|
||||
* The application boot. main.tsx imports this module dynamically, so a module
|
||||
* in this static graph that throws while it evaluates rejects that import and
|
||||
* main.tsx shows the failure (09-03). Failures after evaluation are handled
|
||||
* here.
|
||||
*/
|
||||
const rootElement = document.getElementById("root");
|
||||
|
||||
if (!rootElement) {
|
||||
throw new Error("Missing #root mount element");
|
||||
}
|
||||
|
||||
const root = createRoot(rootElement);
|
||||
|
||||
async function boot(): Promise<void> {
|
||||
const releaseRecovery = createBootReleaseRecovery();
|
||||
try {
|
||||
const composition = await createRuntimeComposition();
|
||||
// A coherent boot clears any reload-once marker from a previous mismatch.
|
||||
releaseRecovery.markCoherentBoot();
|
||||
document.documentElement.dataset.buildId = composition.release.buildId;
|
||||
document.documentElement.dataset.releaseId = composition.release.releaseId;
|
||||
initializeColorScheme(composition.application.preferences);
|
||||
root.render(<RuntimeApplication composition={composition} />);
|
||||
import.meta.hot?.dispose(() => {
|
||||
void composition.dispose();
|
||||
});
|
||||
} catch (error: unknown) {
|
||||
const safe =
|
||||
error instanceof BootConfigError || error instanceof ReleaseManifestError
|
||||
? error.safe
|
||||
: unexpectedBootFailure(error);
|
||||
|
||||
recordBootFailure(error, safe);
|
||||
// Spec §45. A rolling-release mismatch gets exactly one fresh navigation
|
||||
// (HTML is revalidated); a repeat of the same mismatch fails closed.
|
||||
if (decideBootFailure(error, releaseRecovery) === "reload-once") {
|
||||
window.location.reload();
|
||||
return;
|
||||
}
|
||||
root.render(
|
||||
<BootErrorShell {...safe} onRetry={() => window.location.reload()} />,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
void boot();
|
||||
@@ -1,6 +1,7 @@
|
||||
import { resolveRuntimeCapabilities } from "../contracts/runtime-capabilities.ts";
|
||||
import { installBffSessionOwner } from "../features/tech-log/adapters/http/bff-session-owner.ts";
|
||||
import { INSTALLED_RUNTIME_CAPABILITIES } from "../features/installed-runtime-capabilities.ts";
|
||||
import type { TelemetryPort } from "../application/ports/telemetry-port.ts";
|
||||
import { createCompositionRoot } from "./composition-root.ts";
|
||||
import { loadReleaseManifest } from "./load-release-manifest.ts";
|
||||
import { loadRuntimeConfig } from "./load-runtime-config.ts";
|
||||
@@ -24,11 +25,14 @@ export type RuntimeCompositionDependencies = Readonly<{
|
||||
export async function createRuntimeComposition(
|
||||
dependencies: RuntimeCompositionDependencies = {},
|
||||
) {
|
||||
// 06-05. The optional host reports a Service Worker that did not start
|
||||
// through the same telemetry port as the application.
|
||||
let telemetry: TelemetryPort | undefined;
|
||||
const root = await createCompositionRoot({
|
||||
loadConfig: () => loadRuntimeConfig({ fetcher: dependencies.fetcher }),
|
||||
loadRelease: (runtime) =>
|
||||
loadReleaseManifest(runtime, { fetcher: dependencies.fetcher }),
|
||||
createAdapters: ({ config: runtime, release }) => {
|
||||
createAdapters: async ({ config: runtime, release }) => {
|
||||
// `AUTH_MODE: "external"` delegates the session to whoever hosts this
|
||||
// bundle. For Tech Log that host is its own backend — the session is an
|
||||
// httpOnly cookie the SPA cannot read — so the owner is installed here,
|
||||
@@ -46,12 +50,14 @@ export async function createRuntimeComposition(
|
||||
dependencies.fetcher ?? fetch,
|
||||
);
|
||||
}
|
||||
return createRuntimeAdapters({
|
||||
const adapters = await createRuntimeAdapters({
|
||||
runtime,
|
||||
release,
|
||||
fetcher: dependencies.fetcher,
|
||||
host: dependencies.host,
|
||||
});
|
||||
telemetry = adapters.outputPorts.telemetry;
|
||||
return adapters;
|
||||
},
|
||||
});
|
||||
|
||||
@@ -63,6 +69,7 @@ export async function createRuntimeComposition(
|
||||
capabilities,
|
||||
routerBasePath: root.config.build.routerBasePath,
|
||||
buildId: root.release.buildId,
|
||||
...(telemetry ? { telemetry } : {}),
|
||||
...(dependencies.host
|
||||
? {
|
||||
host: dependencies.host as Parameters<
|
||||
|
||||
@@ -17,6 +17,19 @@ import {
|
||||
type BootLoadFailure,
|
||||
} from "./read-bounded-boot-json.ts";
|
||||
import type { RuntimeConfigLoadResult } from "./load-runtime-config.ts";
|
||||
import {
|
||||
checkReleaseCoherence,
|
||||
type ReleaseIdentity,
|
||||
type ReleaseIdentityField,
|
||||
} from "../platform/release/release-coherence.ts";
|
||||
|
||||
const MISMATCH_CODE: Readonly<Record<ReleaseIdentityField, ReleaseManifestErrorCode>> =
|
||||
Object.freeze({
|
||||
buildId: "MANIFEST_BUILD_MISMATCH",
|
||||
configSchemaVersion: "MANIFEST_CONFIG_SCHEMA_MISMATCH",
|
||||
releaseId: "MANIFEST_RELEASE_MISMATCH",
|
||||
assetManifestHash: "MANIFEST_ASSET_MISMATCH",
|
||||
});
|
||||
|
||||
/** §5.8. Retained for one compatibility window; carries the removed scalar. */
|
||||
export const releaseManifestV1Schema = releaseManifestV1ArtifactSchema;
|
||||
@@ -233,23 +246,38 @@ export async function loadReleaseManifest(
|
||||
}
|
||||
|
||||
// §6.7 steps 5-6, in order: build, config, release, assets, then contractSet.
|
||||
let mismatchCode: ReleaseManifestErrorCode | null = null;
|
||||
if (manifest.buildId !== runtime.build.buildId) {
|
||||
mismatchCode = "MANIFEST_BUILD_MISMATCH";
|
||||
}
|
||||
if (
|
||||
!mismatchCode &&
|
||||
runtime.config.BUILD_ID &&
|
||||
manifest.buildId !== runtime.config.BUILD_ID
|
||||
) {
|
||||
mismatchCode = "MANIFEST_BUILD_MISMATCH";
|
||||
}
|
||||
if (
|
||||
!mismatchCode &&
|
||||
manifest.configSchemaVersion !== runtime.config.CONFIG_SCHEMA_VERSION
|
||||
) {
|
||||
mismatchCode = "MANIFEST_CONFIG_SCHEMA_MISMATCH";
|
||||
}
|
||||
// Spec §45. Every identity comparison is delegated to the one pure,
|
||||
// fail-closed release-coherence validator; only the V1 scalar API contract
|
||||
// pair (which has no place in the release identity) stays local.
|
||||
const identities: Readonly<Record<"html" | "config" | "manifest", ReleaseIdentity>> = {
|
||||
html: {
|
||||
buildId: runtime.build.buildId,
|
||||
...(options.expectedAssetManifestHash
|
||||
? { assetManifestHash: options.expectedAssetManifestHash }
|
||||
: {}),
|
||||
},
|
||||
config: {
|
||||
...(runtime.config.BUILD_ID ? { buildId: runtime.config.BUILD_ID } : {}),
|
||||
...(runtime.config.RELEASE_ID ? { releaseId: runtime.config.RELEASE_ID } : {}),
|
||||
configSchemaVersion: runtime.config.CONFIG_SCHEMA_VERSION,
|
||||
},
|
||||
manifest: {
|
||||
buildId: manifest.buildId,
|
||||
releaseId: manifest.releaseId,
|
||||
configSchemaVersion: manifest.configSchemaVersion,
|
||||
assetManifestHash: manifest.assetManifestHash,
|
||||
},
|
||||
};
|
||||
const mismatchFor = (
|
||||
fields: readonly ReleaseIdentityField[],
|
||||
): ReleaseManifestErrorCode | null => {
|
||||
const result = checkReleaseCoherence(identities, fields);
|
||||
return result.coherent ? null : MISMATCH_CODE[result.field];
|
||||
};
|
||||
let mismatchCode: ReleaseManifestErrorCode | null = mismatchFor([
|
||||
"buildId",
|
||||
"configSchemaVersion",
|
||||
]);
|
||||
if (
|
||||
!mismatchCode &&
|
||||
runtime.configSchema === "V1" &&
|
||||
@@ -260,20 +288,7 @@ export async function loadReleaseManifest(
|
||||
) {
|
||||
mismatchCode = "MANIFEST_API_CONTRACT_MISMATCH";
|
||||
}
|
||||
if (
|
||||
!mismatchCode &&
|
||||
runtime.config.RELEASE_ID &&
|
||||
manifest.releaseId !== runtime.config.RELEASE_ID
|
||||
) {
|
||||
mismatchCode = "MANIFEST_RELEASE_MISMATCH";
|
||||
}
|
||||
if (
|
||||
!mismatchCode &&
|
||||
options.expectedAssetManifestHash &&
|
||||
manifest.assetManifestHash !== options.expectedAssetManifestHash
|
||||
) {
|
||||
mismatchCode = "MANIFEST_ASSET_MISMATCH";
|
||||
}
|
||||
mismatchCode ??= mismatchFor(["releaseId", "assetManifestHash"]);
|
||||
if (mismatchCode) {
|
||||
throw new ReleaseManifestError(mismatchCode, identity);
|
||||
}
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { assertSafeConfigNames, getBuildConfig } from "../contracts/env.ts";
|
||||
import { checkReleaseCoherence } from "../platform/release/release-coherence.ts";
|
||||
import {
|
||||
BOOT_JSON_POLICIES,
|
||||
readBoundedBootJson,
|
||||
@@ -20,6 +21,8 @@ export type BootConfigSafe = Readonly<{
|
||||
buildId: string;
|
||||
configSchemaVersion?: string;
|
||||
releaseId?: string;
|
||||
/** 09-04. Names of rejected keys (never their values), bounded. */
|
||||
invalidKeys?: readonly string[];
|
||||
supportReference: string;
|
||||
}>;
|
||||
|
||||
@@ -27,8 +30,12 @@ type BootConfigSafeInput = Readonly<{
|
||||
buildId: string;
|
||||
configSchemaVersion?: string;
|
||||
releaseId?: string;
|
||||
invalidKeys?: readonly string[];
|
||||
}>;
|
||||
|
||||
const SAFE_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u;
|
||||
const MAX_INVALID_KEYS = 5;
|
||||
|
||||
export class BootConfigError extends Error {
|
||||
readonly kind = "BOOT_CONFIG_FAILURE" as const;
|
||||
readonly code: string;
|
||||
@@ -44,6 +51,9 @@ export class BootConfigError extends Error {
|
||||
buildId: safe.buildId,
|
||||
configSchemaVersion: safe.configSchemaVersion,
|
||||
releaseId: safe.releaseId,
|
||||
...(safe.invalidKeys === undefined
|
||||
? {}
|
||||
: { invalidKeys: safe.invalidKeys }),
|
||||
supportReference: `${safe.buildId}:${code}`,
|
||||
});
|
||||
}
|
||||
@@ -115,22 +125,40 @@ export async function loadRuntimeConfig(
|
||||
|
||||
const validated = validateRuntimeConfig(rawConfig);
|
||||
if (!validated.success) {
|
||||
// Q-6.9-10. Only a value that passed a check reaches the safe error. The
|
||||
// declared schema version did when it selected a parser; nothing else in
|
||||
// a rejected document did (RELEASE_ID could be 64 KB of anything).
|
||||
const versionAccepted = !validated.issues.some(
|
||||
(issue) => issue.path === "CONFIG_SCHEMA_VERSION",
|
||||
);
|
||||
// 09-04. Key names tell an operator what to fix without echoing a value;
|
||||
// they still come from the rejected document, so they are bounded.
|
||||
const invalidKeys = [
|
||||
...new Set(validated.issues.map((issue) => issue.path)),
|
||||
]
|
||||
.filter((path) => SAFE_KEY_PATTERN.test(path))
|
||||
.sort()
|
||||
.slice(0, MAX_INVALID_KEYS);
|
||||
throw new BootConfigError("CONFIG_SCHEMA_INVALID", {
|
||||
buildId: buildConfig.buildId,
|
||||
configSchemaVersion:
|
||||
typeof rawConfig.CONFIG_SCHEMA_VERSION === "string"
|
||||
versionAccepted && typeof rawConfig.CONFIG_SCHEMA_VERSION === "string"
|
||||
? rawConfig.CONFIG_SCHEMA_VERSION
|
||||
: undefined,
|
||||
releaseId:
|
||||
typeof rawConfig.RELEASE_ID === "string"
|
||||
? rawConfig.RELEASE_ID
|
||||
: undefined,
|
||||
invalidKeys,
|
||||
});
|
||||
}
|
||||
|
||||
// Spec §45. HTML/JS build vs runtime config: delegated to the one pure
|
||||
// release-coherence validator so config and manifest checks cannot drift.
|
||||
if (
|
||||
validated.data.BUILD_ID &&
|
||||
validated.data.BUILD_ID !== buildConfig.buildId
|
||||
!checkReleaseCoherence(
|
||||
{
|
||||
html: { buildId: buildConfig.buildId },
|
||||
config: validated.data.BUILD_ID ? { buildId: validated.data.BUILD_ID } : {},
|
||||
},
|
||||
["buildId"],
|
||||
).coherent
|
||||
) {
|
||||
throw new BootConfigError("CONFIG_BUILD_MISMATCH", {
|
||||
buildId: buildConfig.buildId,
|
||||
|
||||
+15
-39
@@ -1,7 +1,3 @@
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
import { recordBootFailure } from "../adapters/diagnostics/index.ts";
|
||||
import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.tsx";
|
||||
import "pretendard/dist/web/variable/pretendardvariable.css";
|
||||
import "@fontsource/ibm-plex-mono/400.css";
|
||||
import "@fontsource/ibm-plex-mono/500.css";
|
||||
@@ -10,39 +6,19 @@ import "../features/tech-log/presentation/styles/tech-log-theme.css";
|
||||
import "../features/tech-log/presentation/styles/globals.css";
|
||||
import "../features/tech-log/presentation/styles/studio.css";
|
||||
import "../features/tech-log/presentation/styles/studio-editor.css";
|
||||
import { createRuntimeComposition } from "./create-runtime-composition.ts";
|
||||
import { initializeColorScheme } from "./initialize-color-scheme.ts";
|
||||
import { ReleaseManifestError } from "./load-release-manifest.ts";
|
||||
import { BootConfigError } from "./load-runtime-config.ts";
|
||||
import { RuntimeApplication } from "./runtime-application.tsx";
|
||||
|
||||
const rootElement = document.getElementById("root");
|
||||
|
||||
if (!rootElement) {
|
||||
throw new Error("Missing #root mount element");
|
||||
}
|
||||
|
||||
const root = createRoot(rootElement);
|
||||
|
||||
async function boot(): Promise<void> {
|
||||
try {
|
||||
const composition = await createRuntimeComposition();
|
||||
document.documentElement.dataset.buildId = composition.release.buildId;
|
||||
document.documentElement.dataset.releaseId = composition.release.releaseId;
|
||||
initializeColorScheme(composition.application.preferences);
|
||||
root.render(<RuntimeApplication composition={composition} />);
|
||||
import.meta.hot?.dispose(() => {
|
||||
void composition.dispose();
|
||||
});
|
||||
} catch (error: unknown) {
|
||||
const safe =
|
||||
error instanceof BootConfigError || error instanceof ReleaseManifestError
|
||||
? error.safe
|
||||
: { supportReference: "boot:unknown" };
|
||||
|
||||
recordBootFailure(error, safe);
|
||||
root.render(<BootErrorShell {...safe} />);
|
||||
}
|
||||
}
|
||||
|
||||
void boot();
|
||||
/**
|
||||
* 09-03. The entry imports the application graph dynamically. A module in it
|
||||
* that throws while it evaluates (a duplicate message key, a route or
|
||||
* operation conflict) used to stop the entry before any handler ran, leaving
|
||||
* the static loading shell up. Now it rejects this import and the failure is
|
||||
* shown.
|
||||
*
|
||||
* The entry stays free of anything the application graph also imports (no
|
||||
* JSX, no React): whatever it hosted, every chunk would import from it, and
|
||||
* the entry's hash changes with every build id.
|
||||
*/
|
||||
void import("./boot.tsx").catch(async (error: unknown) => {
|
||||
const { renderBootFailure } = await import("./render-boot-failure.tsx");
|
||||
renderBootFailure(error);
|
||||
});
|
||||
|
||||
@@ -8,6 +8,7 @@ import type {
|
||||
RuntimeStopReason,
|
||||
} from "../contracts/runtime-capabilities.ts";
|
||||
import type { ServiceWorkerRuntimeHost } from "../contracts/service-worker.ts";
|
||||
import type { TelemetryPort } from "../application/ports/telemetry-port.ts";
|
||||
import { createServiceWorkerRuntimeHost } from "./register-service-worker.ts";
|
||||
|
||||
/**
|
||||
@@ -39,6 +40,8 @@ export type OptionalRuntimeHostInput = Readonly<{
|
||||
host?: Parameters<typeof createServiceWorkerRuntimeHost>[0]["host"];
|
||||
blockers?: readonly (() => boolean)[];
|
||||
observe?: (observation: Readonly<{ event: string; outcome: string }>) => void;
|
||||
/** 06-05. Receives `service-worker.start.failed`. */
|
||||
telemetry?: TelemetryPort;
|
||||
}>;
|
||||
|
||||
export function createOptionalRuntimeHost(
|
||||
@@ -107,6 +110,13 @@ export function createOptionalRuntimeHost(
|
||||
: outcome.kind === "INCOMPATIBLE"
|
||||
? "INCOMPATIBLE"
|
||||
: "DEGRADED";
|
||||
if (outcome.kind === "FAILED" || outcome.kind === "INCOMPATIBLE") {
|
||||
input.telemetry?.emit("service-worker.start.failed", {
|
||||
error_kind:
|
||||
outcome.kind === "FAILED" ? outcome.code : outcome.kind,
|
||||
build_id: input.buildId,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
if (!stopRequested) started = true;
|
||||
|
||||
@@ -51,6 +51,7 @@ export function createServiceWorkerRuntimeHost(
|
||||
buildId: input.buildId,
|
||||
...(container ? { container } : {}),
|
||||
...(host?.caches ? { caches: host.caches } : {}),
|
||||
...(host?.document ? { document: host.document } : {}),
|
||||
...(input.blockers ? { blockers: input.blockers } : {}),
|
||||
...(input.observe ? { observe: input.observe } : {}),
|
||||
});
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
import { recordBootFailure } from "../adapters/diagnostics/index.ts";
|
||||
import { getBuildConfig } from "../contracts/env.ts";
|
||||
import {
|
||||
BootErrorShell,
|
||||
type BootErrorShellProps,
|
||||
} from "../presentation/boundaries/boot-error-shell.tsx";
|
||||
|
||||
const ERROR_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9]{0,39}$/u;
|
||||
|
||||
/**
|
||||
* 09-04. A boot failure no loader classified: an assembly defect, a module
|
||||
* that threw while evaluating. It is shown as such, with the build and the
|
||||
* error's class name, never its message; a development build also reports
|
||||
* the original error to the console (`reportError`; direct console calls are
|
||||
* refused by check:diagnostics), where it was otherwise lost.
|
||||
*/
|
||||
export function unexpectedBootFailure(error: unknown): BootErrorShellProps {
|
||||
if (import.meta.env.DEV) globalThis.reportError?.(error);
|
||||
const { buildId } = getBuildConfig();
|
||||
const name = error instanceof Error ? error.name : "";
|
||||
const code = ERROR_NAME_PATTERN.test(name) ? name : "UNKNOWN_ERROR";
|
||||
return Object.freeze({
|
||||
kind: "BOOT_UNEXPECTED_FAILURE",
|
||||
code,
|
||||
buildId,
|
||||
supportReference: `${buildId}:BOOT_UNEXPECTED_FAILURE`,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 09-03. Renders the boot failure when the application graph (boot.tsx) could
|
||||
* not even be evaluated. Nothing here reaches the installed feature graph, so
|
||||
* it still loads when that graph throws.
|
||||
*/
|
||||
export function renderBootFailure(error: unknown): void {
|
||||
const safe = unexpectedBootFailure(error);
|
||||
recordBootFailure(error, safe);
|
||||
const rootElement = document.getElementById("root");
|
||||
if (!rootElement) throw error;
|
||||
createRoot(rootElement).render(<BootErrorShell {...safe} />);
|
||||
}
|
||||
@@ -18,7 +18,10 @@ import {
|
||||
type DiagnosticRecordInput,
|
||||
} from "../contracts/diagnostics.ts";
|
||||
import type { TelemetryEventName } from "../contracts/telemetry.ts";
|
||||
import { createBrowserCrossContextInvalidationFromHost } from "../adapters/cross-context-invalidation/index.ts";
|
||||
import {
|
||||
createBrowserCrossContextInvalidationFromHost,
|
||||
crossContextCacheEpochForRelease,
|
||||
} from "../adapters/cross-context-invalidation/index.ts";
|
||||
import {
|
||||
createConditionalValidatorStore,
|
||||
createQueryClient,
|
||||
@@ -27,7 +30,11 @@ import {
|
||||
} from "../adapters/query-cache/index.ts";
|
||||
import { createBrowserStorageAdapter } from "../adapters/storage/index.ts";
|
||||
import { createBrowserMutationIntentFactory } from "../adapters/platform/index.ts";
|
||||
import { createTelemetryAdapter } from "../adapters/telemetry/index.ts";
|
||||
import {
|
||||
createFeatureTelemetry,
|
||||
createTelemetryAdapter,
|
||||
createTelemetryCollector,
|
||||
} from "../adapters/telemetry/index.ts";
|
||||
import { createCsrfTokenProvider } from "../features/tech-log/adapters/http/studio-session-csrf.ts";
|
||||
import {
|
||||
attachStudioSessionCredentials,
|
||||
@@ -53,6 +60,7 @@ import {
|
||||
import {
|
||||
activeProductFeatureIds,
|
||||
resolveProductFeatures,
|
||||
unknownProductFeatureOverrides,
|
||||
} from "../contracts/product-features.ts";
|
||||
import { describeRuntimeCapabilities } from "../contracts/runtime-capabilities.ts";
|
||||
import {
|
||||
@@ -79,8 +87,12 @@ type HttpClientDependencies = Parameters<typeof createHttpClient>[0];
|
||||
* V2로 어떤 오퍼레이션도 실행되지 않는다** — 그건 결함이 아니라 제품이
|
||||
* 채우는 자리다.
|
||||
*
|
||||
* V2를 rollback/compatibility 경로로 쓰려는 제품은 이 네 슬롯을 주입해야
|
||||
* 한다. 주입하지 않은 채 V3에서 되돌리면 모든 요청이 실패한다.
|
||||
* V2는 V3를 그대로 되돌리는 롤백 경로가 아니다. 두 경로는 wire 형식이
|
||||
* 다르다. V2는 `{ success, data, meta }` 봉투를 검증하고
|
||||
* (`adapters/http/schema-registry.ts`), V3는 봉투 없는 DTO 자체를 검증한다.
|
||||
* 그래서 네 슬롯을 모두 주입해도 같은 백엔드로 V2로 되돌리면 모든 응답이
|
||||
* `ENVELOPE_MISMATCH`다. V2로 되돌리려면 슬롯 주입과 함께 서버도 V2 봉투로
|
||||
* 응답해야 한다.
|
||||
* V3(`createContractHttpExecutor`)는 설치된 feature 계약에서 오퍼레이션을
|
||||
* 받으므로 이 슬롯과 무관하게 동작한다.
|
||||
*/
|
||||
@@ -128,6 +140,7 @@ function toReleaseInfo(manifest: Readonly<ReleaseManifest>): ReleaseInfo {
|
||||
|
||||
const EXTERNAL_OWNER_METHODS = Object.freeze([
|
||||
"readState",
|
||||
"readSubject",
|
||||
"subscribe",
|
||||
"beginSignIn",
|
||||
"signOut",
|
||||
@@ -240,6 +253,10 @@ export function createHttpObservationProjector(
|
||||
...safeAttributes,
|
||||
operation: observation.diagnosticsOperation,
|
||||
outcome: observation.outcome,
|
||||
// 03-03. Request-scoped: diagnostics may carry it, telemetry never.
|
||||
...(observation.correlationId === undefined
|
||||
? {}
|
||||
: { correlation_id: observation.correlationId }),
|
||||
},
|
||||
});
|
||||
} catch {
|
||||
@@ -275,6 +292,13 @@ function isTerminalNonAbortFailure(
|
||||
): boolean {
|
||||
if (observation.outcome === "SUCCESS") return false;
|
||||
if (observation.outcome === "CANCELLED") return false;
|
||||
// 03-07. No credential, nothing sent: a client state, not an API failure.
|
||||
if (
|
||||
observation.outcome === "UNAUTHENTICATED" &&
|
||||
observation.status === undefined
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
observation.cancellationOwner !== undefined &&
|
||||
CALLER_OWNED_CANCELLATION.has(observation.cancellationOwner)
|
||||
@@ -302,10 +326,24 @@ export async function createRuntimeAdapters(
|
||||
? createExternalAuthSessionAdapter(externalOwner)
|
||||
: createUnavailableSessionAdapter();
|
||||
const diagnostics = createDiagnosticsAdapter();
|
||||
// Q-6.9-4. Both telemetry ports post through one collector transport: one
|
||||
// send-rate window, one page-exit flush and one fetch policy per endpoint.
|
||||
const telemetryCollector =
|
||||
config.TELEMETRY_ENABLED && config.TELEMETRY_ENDPOINT
|
||||
? createTelemetryCollector({
|
||||
endpoint: config.TELEMETRY_ENDPOINT,
|
||||
...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }),
|
||||
release: {
|
||||
buildId: context.release.buildId,
|
||||
releaseId: context.release.releaseId,
|
||||
},
|
||||
})
|
||||
: undefined;
|
||||
const telemetry = createTelemetryAdapter({
|
||||
enabled: config.TELEMETRY_ENABLED,
|
||||
endpoint: config.TELEMETRY_ENDPOINT,
|
||||
fetcher: context.fetcher,
|
||||
...(telemetryCollector === undefined ? {} : { collector: telemetryCollector }),
|
||||
onDrop(event) {
|
||||
const attributes =
|
||||
event.attributes && typeof event.attributes === "object"
|
||||
@@ -329,7 +367,9 @@ export async function createRuntimeAdapters(
|
||||
const crossContextInvalidation =
|
||||
createBrowserCrossContextInvalidationFromHost({
|
||||
...(context.host === undefined ? {} : { host: context.host }),
|
||||
cacheEpoch: `release.${context.release.releaseId}`,
|
||||
cacheEpoch: crossContextCacheEpochForRelease(
|
||||
context.release.releaseId,
|
||||
),
|
||||
topics: [...invalidationTopicVersions].map(([topic, topicVersion]) =>
|
||||
Object.freeze({
|
||||
topic,
|
||||
@@ -370,6 +410,7 @@ export async function createRuntimeAdapters(
|
||||
});
|
||||
const serverStateScope = createServerStateScopeRuntime({
|
||||
session: authSession,
|
||||
diagnostics,
|
||||
queryInvalidation: {
|
||||
resetLocal: () => serverStateGeneration.resetCurrent(),
|
||||
},
|
||||
@@ -424,6 +465,16 @@ export async function createRuntimeAdapters(
|
||||
const activeFeatureIds = new Set(
|
||||
activeProductFeatureIds(productFeatureStatuses),
|
||||
);
|
||||
for (const key of unknownProductFeatureOverrides(
|
||||
COMPILED_PRODUCT_FEATURE_IDS,
|
||||
config.FEATURE_OVERRIDES,
|
||||
)) {
|
||||
diagnostics.record({
|
||||
level: "warn",
|
||||
eventId: "feature.override.unknown",
|
||||
context: { feature_override_key: key },
|
||||
});
|
||||
}
|
||||
const productFeatures = Object.freeze({
|
||||
getSnapshot() {
|
||||
return productFeatureStatuses;
|
||||
@@ -604,8 +655,14 @@ export async function createRuntimeAdapters(
|
||||
...(executionContext.intent === undefined
|
||||
? {}
|
||||
: { intent: executionContext.intent }),
|
||||
...(executionContext.execution === undefined
|
||||
? {}
|
||||
: { execution: executionContext.execution }),
|
||||
});
|
||||
if (outcome.kind === "UNAUTHENTICATED") {
|
||||
// R-3.2. Only a server 401 is a session verdict. A request refused before
|
||||
// dispatch for lack of a credential carries no response metadata; telling
|
||||
// the owner would overwrite a recovering session and re-fence the scope.
|
||||
if (outcome.kind === "UNAUTHENTICATED" && outcome.metadata !== undefined) {
|
||||
authSession.onUnauthenticated();
|
||||
}
|
||||
// Fix round 2, item 1. `UNAUTHENTICATED` (401) and `FORBIDDEN` (403 —
|
||||
@@ -627,14 +684,34 @@ export async function createRuntimeAdapters(
|
||||
return outcome;
|
||||
},
|
||||
});
|
||||
const featureInputs = createInstalledFeatureInputs({
|
||||
// Spec §24–§27. Feature-owned events go through the bounded, fail-open
|
||||
// pipeline behind the provider-neutral port; features never see the sink.
|
||||
const featureTelemetry = createFeatureTelemetry({
|
||||
enabled: config.TELEMETRY_ENABLED,
|
||||
...(config.TELEMETRY_ENDPOINT === undefined
|
||||
? {}
|
||||
: { endpoint: config.TELEMETRY_ENDPOINT }),
|
||||
...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }),
|
||||
...(telemetryCollector === undefined ? {} : { collector: telemetryCollector }),
|
||||
});
|
||||
// Each installed contribution receives only the capabilities it declares.
|
||||
// 09-05. `indexedDb` is not built here: IndexedDB is an opt-in reference
|
||||
// runtime (`productionComposition: false`). Installing a feature that needs
|
||||
// it makes this object fail the app typecheck until the product adds
|
||||
// `indexedDb`, built as in recipes/frontend-capabilities/
|
||||
// indexeddb-feature-capability.ts.
|
||||
const featureCapabilities = Object.freeze({
|
||||
http: contractOperations,
|
||||
telemetry: featureTelemetry,
|
||||
studioSource: config.TECH_LOG_STUDIO_SOURCE,
|
||||
publicSource: config.TECH_LOG_PUBLIC_SOURCE,
|
||||
apiBaseUrl: config.API_BASE_URL,
|
||||
requestTimeoutMs: config.REQUEST_TIMEOUT_MS,
|
||||
csrf: techLogCsrf,
|
||||
});
|
||||
const featureInputs = createInstalledFeatureInputs(featureCapabilities, [
|
||||
...activeFeatureIds,
|
||||
]);
|
||||
|
||||
return Object.freeze({
|
||||
outputPorts: Object.freeze({
|
||||
@@ -665,6 +742,7 @@ export async function createRuntimeAdapters(
|
||||
// delivering before the diagnostics and state dependencies it observes
|
||||
// are destroyed.
|
||||
telemetry.dispose();
|
||||
featureTelemetry.dispose();
|
||||
conditionalValidators.clear();
|
||||
serverStateScope.dispose();
|
||||
serverStateGeneration.dispose();
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { StrictMode, useEffect } from "react";
|
||||
|
||||
import { ApplicationProvider } from "../presentation/providers/application-provider.tsx";
|
||||
import { PreferenceProviders } from "../presentation/providers/preference-providers.tsx";
|
||||
import { ServerStateGenerationProvider } from "../presentation/adapters/query/server-state-generation-provider.tsx";
|
||||
import { AppRouter } from "../presentation/routes/app-router.tsx";
|
||||
import type { RuntimeComposition } from "./create-runtime-composition.ts";
|
||||
@@ -28,28 +29,32 @@ export function RuntimeApplication({
|
||||
}: Readonly<{ composition: RuntimeComposition }>) {
|
||||
return (
|
||||
<StrictMode>
|
||||
<ServerStateGenerationProvider
|
||||
store={composition.infrastructure.serverStateGeneration}
|
||||
scope={composition.infrastructure.serverStateScope}
|
||||
mutationIntentFactory={
|
||||
composition.infrastructure.mutationIntentFactory
|
||||
}
|
||||
transitionFallback={
|
||||
<div
|
||||
aria-busy="true"
|
||||
className="state-surface state-surface--loading"
|
||||
data-scope-state="scope-transition"
|
||||
/>
|
||||
}
|
||||
>
|
||||
<ApplicationProvider application={composition.application}>
|
||||
<PostMountRuntimeStarter composition={composition} />
|
||||
<AppRouter
|
||||
basename={composition.config.build.routerBasePath}
|
||||
buildId={composition.release.buildId}
|
||||
/>
|
||||
</ApplicationProvider>
|
||||
</ServerStateGenerationProvider>
|
||||
{/* Preferences sit above the scope fence: a session change remounts
|
||||
everything below it, and locale/theme must survive that. */}
|
||||
<ApplicationProvider application={composition.application}>
|
||||
<PreferenceProviders>
|
||||
<ServerStateGenerationProvider
|
||||
store={composition.infrastructure.serverStateGeneration}
|
||||
scope={composition.infrastructure.serverStateScope}
|
||||
mutationIntentFactory={
|
||||
composition.infrastructure.mutationIntentFactory
|
||||
}
|
||||
transitionFallback={
|
||||
<div
|
||||
aria-busy="true"
|
||||
className="state-surface state-surface--loading"
|
||||
data-scope-state="scope-transition"
|
||||
/>
|
||||
}
|
||||
>
|
||||
<PostMountRuntimeStarter composition={composition} />
|
||||
<AppRouter
|
||||
basename={composition.config.build.routerBasePath}
|
||||
buildId={composition.release.buildId}
|
||||
/>
|
||||
</ServerStateGenerationProvider>
|
||||
</PreferenceProviders>
|
||||
</ApplicationProvider>
|
||||
</StrictMode>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -113,8 +113,15 @@ export function validateRuntimeConfig(value: unknown): RuntimeConfigValidation {
|
||||
return Object.freeze({
|
||||
success: false as const,
|
||||
issues: Object.freeze(
|
||||
result.error.issues.map((issue) =>
|
||||
Object.freeze({ path: issue.path.join("."), code: issue.code }),
|
||||
result.error.issues.flatMap((issue) =>
|
||||
// 09-04. A misspelt top-level key is one `unrecognized_keys` issue
|
||||
// at the root; name each key so the boot error can say which.
|
||||
(issue.code === "unrecognized_keys"
|
||||
? issue.keys.map((key) => [...issue.path, key])
|
||||
: [issue.path]
|
||||
).map((path) =>
|
||||
Object.freeze({ path: path.join("."), code: issue.code }),
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user