gorsee 0.2.11 → 0.2.12

package/README.md

@@ -1,14 +1,14 @@
 # Gorsee.js
 
-AI-first reactive full-stack TypeScript framework for deterministic collaboration between humans and coding agents.
+AI-first reactive full-stack TypeScript framework and application platform for deterministic collaboration between humans and coding agents across frontend, fullstack, and server systems.
 
-Gorsee is not a pet project, not a research toy, and not a bundle of optional recipes. It is a product-grade framework with strict runtime contracts, built-in security boundaries, fine-grained reactivity, and AI-native developer tooling.
+Gorsee is not a pet project, not a research toy, and not a bundle of optional recipes. It is a product-grade platform with strict runtime contracts, built-in security boundaries, fine-grained reactivity, and AI-native developer tooling.
 
 ## Product Direction
 
 Gorsee is built around four non-negotiable product goals:
 
-- AI-first development: the framework must be predictable for coding agents, not only ergonomic for humans.
+- AI-first development: the platform must be predictable for coding agents, not only ergonomic for humans.
 - Deterministic architecture: one clear way beats many inconsistent ways.
 - Reactive execution: fine-grained reactivity, islands, and minimal client JavaScript over VDOM-heavy legacy models.
 - Built-in guarantees: auth, request policy, cache boundaries, diagnostics, and deploy contracts are framework properties, not scattered ecosystem recipes.
@@ -17,6 +17,7 @@ Read the strategic docs:
 
 - [Product Vision](./docs/PRODUCT_VISION.md)
 - [Framework Doctrine](./docs/FRAMEWORK_DOCTRINE.md)
+- [Application Modes](./docs/APPLICATION_MODES.md)
 - [Security Model](./docs/SECURITY_MODEL.md)
 - [Top-Tier Roadmap](./docs/TOP_TIER_ROADMAP.md)
 - [Canonical Language Plan](./docs/CANONICAL_LANGUAGE_PLAN.md)
@@ -77,6 +78,33 @@ Read the strategic docs:
 - [Evidence Policy](./docs/EVIDENCE_POLICY.md)
 - [Roadmap Completion Policy](./docs/ROADMAP_COMPLETION_POLICY.md)
 
+## Canonical Modes
+
+Gorsee ships one product with three canonical application modes:
+
+- `frontend` for browser-first prerendered apps deployed to static-capable targets
+- `fullstack` for the canonical Gorsee route/runtime model across UI + server execution
+- `server` for API-first and service-oriented systems without mandatory browser surfaces
+
+Set the mode explicitly in `app.config.ts`:
+
+```ts
+export default {
+  app: {
+    mode: "fullstack",
+  },
+}
+```
+
+`fullstack` remains the default when `app.mode` is omitted.
+
+High-level mode guidance:
+
+- `frontend` builds browser-first prerendered output and should prefer static-capable deploy targets.
+- `fullstack` keeps the canonical Gorsee route/runtime model and can target Bun, Node, or worker-style deploy adapters.
+- `server` focuses on API-first and service-oriented systems with process/runtime ownership kept explicit.
+- `server` mode should prefer `gorsee worker` for canonical long-running worker and service entry execution.
+
 ## Quick Start
 
 ```bash
@@ -86,6 +114,22 @@ bun install
 bun run dev
 ```
 
+Worker-first server path:
+
+```bash
+bunx gorsee create my-service --template worker-service
+cd my-service
+bun install
+bun run worker
+```
+
+Canonical worker CLI path for server-mode apps:
+
+```bash
+gorsee worker
+gorsee worker --entry workers/custom.ts
+```
+
 Alternative bootstrap paths:
 
 ```bash
@@ -238,21 +282,25 @@ const userRoute = createTypedRoute("/users/[id]")
 
 ## Starter Templates
 
-`gorsee create` ships with one generic baseline and four first-party product starters:
+`gorsee create` ships with canonical starters for each official mode:
 
+- `frontend` for browser-first prerendered apps
 - `basic` for the minimal canonical scaffold
 - `secure-saas` for authenticated SaaS apps with protected route groups
 - `content-site` for public content and marketing sites
 - `agent-aware-ops` for internal tools with AI-first workflows enabled
 - `workspace-monorepo` for workspace layouts with one app package and one shared package
+- `server-api` for API-first and service-oriented server apps
 
 Examples:
 
 ```bash
+bunx gorsee create my-frontend --template frontend
 bunx gorsee create my-saas --template secure-saas
 bunx gorsee create my-site --template content-site
 bunx gorsee create my-ops --template agent-aware-ops
 bunx gorsee create my-workspace --template workspace-monorepo
+bunx gorsee create my-service --template server-api
 npx create-gorsee my-app
 npm create gorsee@latest my-app
 ```

package/dist-pkg/ai/bundle.d.ts

@@ -17,6 +17,7 @@ export interface AIContextBundle {
     diagnostics: {
         updatedAt?: string;
         sessionId?: string;
+        app?: AIContextPacket["app"];
         latest?: Partial<AIDiagnostic>;
     } | null;
     recentEvents: AIEvent[];

package/dist-pkg/ai/framework-context.d.ts

@@ -1,3 +1,4 @@
+import { type AppMode } from "../runtime/app-config.js";
 export interface AIFrameworkDocRef {
     path: string;
     purpose: string;
@@ -8,6 +9,7 @@ export interface AIFrameworkPacket {
     generatedAt: string;
     cwd: string;
     projectName: string;
+    appMode: AppMode;
     product: {
         name: "Gorsee";
         version?: string;

package/dist-pkg/ai/framework-context.js

@@ -1,12 +1,14 @@
 import { access, readFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { generateFrameworkMD } from "../cli/framework-md.js";
+import { loadAppConfig, resolveAppMode } from "../runtime/app-config.js";
 const LOCAL_DOCS = [
   { path: "AGENTS.md", purpose: "\u041F\u0440\u043E\u0435\u043A\u0442\u043D\u044B\u0439 operating contract \u0434\u043B\u044F \u0430\u0433\u0435\u043D\u0442\u043E\u0432" },
   { path: "FRAMEWORK.md", purpose: "AI-friendly reference \u0434\u043B\u044F \u0442\u0435\u043A\u0443\u0449\u0435\u0433\u043E \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F" },
   { path: "README.md", purpose: "\u0411\u044B\u0441\u0442\u0440\u044B\u0439 \u0432\u0445\u043E\u0434 \u0438 \u043F\u0443\u0431\u043B\u0438\u0447\u043D\u0430\u044F \u043F\u043E\u0432\u0435\u0440\u0445\u043D\u043E\u0441\u0442\u044C" }
 ], CANONICAL_DOCS = [
   { path: "docs/FRAMEWORK_DOCTRINE.md", purpose: "\u0410\u0440\u0445\u0438\u0442\u0435\u043A\u0442\u0443\u0440\u043D\u0430\u044F \u0434\u043E\u043A\u0442\u0440\u0438\u043D\u0430 \u0438 \u0438\u043D\u0432\u0430\u0440\u0438\u0430\u043D\u0442\u044B" },
+  { path: "docs/APPLICATION_MODES.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0435 \u0440\u0435\u0436\u0438\u043C\u044B frontend/fullstack/server \u0438 \u0433\u0440\u0430\u043D\u0438\u0446\u044B \u043C\u0435\u0436\u0434\u0443 \u043D\u0438\u043C\u0438" },
   { path: "docs/API_STABILITY.md", purpose: "\u0421\u0442\u0430\u0431\u0438\u043B\u044C\u043D\u044B\u0435 \u043F\u0443\u0431\u043B\u0438\u0447\u043D\u044B\u0435 entrypoints \u0438 migration semantics" },
   { path: "docs/SECURITY_MODEL.md", purpose: "Runtime/security guarantees \u0438 fail-closed \u043C\u043E\u0434\u0435\u043B\u044C" },
   { path: "docs/AI_WORKFLOWS.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0439 human+agent workflow" },
@@ -68,13 +70,14 @@ function renderDocLines(docs) {
   return docs.map((doc) => `- \`${doc.path}\` -- ${doc.purpose}`);
 }
 export async function buildAIFrameworkPacket(cwd) {
-  const projectName = await resolveProjectName(cwd), localDocs = await collectDocRefs(cwd, LOCAL_DOCS), canonicalDocs = await collectDocRefs(cwd, CANONICAL_DOCS), frameworkReferencePath = await pathExists(join(cwd, "FRAMEWORK.md")) ? relative(cwd, join(cwd, "FRAMEWORK.md")) || "FRAMEWORK.md" : void 0, frameworkReferenceMarkdown = frameworkReferencePath ? await readFile(join(cwd, frameworkReferencePath), "utf-8") : generateFrameworkMD(projectName);
+  const projectName = await resolveProjectName(cwd), appMode = resolveAppMode(await loadAppConfig(cwd)), localDocs = await collectDocRefs(cwd, LOCAL_DOCS), canonicalDocs = await collectDocRefs(cwd, CANONICAL_DOCS), frameworkReferencePath = await pathExists(join(cwd, "FRAMEWORK.md")) ? relative(cwd, join(cwd, "FRAMEWORK.md")) || "FRAMEWORK.md" : void 0, frameworkReferenceMarkdown = frameworkReferencePath ? await readFile(join(cwd, frameworkReferencePath), "utf-8") : generateFrameworkMD(projectName);
   return {
     kind: "gorsee.framework",
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
     cwd,
     projectName,
+    appMode,
     product: {
       name: "Gorsee",
       version: await resolveFrameworkVersion(),
@@ -108,6 +111,7 @@ export async function buildAIFrameworkPacket(cwd) {
     recommendedStart: [
       "Read AGENTS.md first when it exists.",
       "Read FRAMEWORK.md for the current app shape and syntax.",
+      `Respect the current app.mode contract: ${appMode}.`,
       "Use gorsee/client for browser-safe code and gorsee/server for runtime/server boundaries.",
       "Prefer scoped stable subpaths when auth, db, security, forms, routes, ai, or log is the primary concern.",
       "Use gorsee ai export --bundle for incident/debug context, not for framework cold-start context."
@@ -122,6 +126,7 @@ export function renderAIFrameworkMarkdown(packet) {
     "",
     `Generated: ${packet.generatedAt}`,
     `Project: ${packet.projectName}`,
+    `App Mode: ${packet.appMode}`,
     packet.product.version ? `Framework Version: ${packet.product.version}` : void 0,
     "",
     "## Product",

package/dist-pkg/ai/ide.d.ts

@@ -8,6 +8,7 @@ export interface IDEProjectionPaths {
 export interface IDEProjection {
     schemaVersion: string;
     updatedAt: string;
+    app?: AIContextPacket["app"];
     diagnostics: Array<{
         code?: string;
         message: string;

package/dist-pkg/ai/ide.js

@@ -16,6 +16,7 @@ export async function buildIDEProjection(storePaths, options = {}) {
   return {
     schemaVersion: GORSEE_AI_CONTEXT_SCHEMA_VERSION,
     updatedAt: new Date().toISOString(),
+    app: context.app,
     diagnostics: diagnosticsSnapshot?.latest ? [{
       code: diagnosticsSnapshot.latest.code,
       message: diagnosticsSnapshot.latest.message ?? "",
@@ -44,11 +45,13 @@ export async function writeIDEProjection(projectionPaths, projection) {
   await writeFile(projectionPaths.diagnosticsPath, JSON.stringify({
     schemaVersion: projection.schemaVersion,
     updatedAt: projection.updatedAt,
+    app: projection.app,
     diagnostics: projection.diagnostics
   }, null, 2), "utf-8");
   await writeFile(projectionPaths.eventsPath, JSON.stringify({
     schemaVersion: projection.schemaVersion,
     updatedAt: projection.updatedAt,
+    app: projection.app,
     events: projection.recentEvents,
     artifactRegressions: projection.artifactRegressions
   }, null, 2), "utf-8");

package/dist-pkg/ai/index.d.ts

@@ -4,7 +4,7 @@ export { writeArtifactFailurePack, writeArtifactLifecycleEvent, writeArtifactSuc
 export { createAIBridgeHandler, createAIBridgeServer, type AIBridgeHandler, type AIBridgeServer, type AIBridgeServerOptions, type AIBridgeSnapshot, } from "./bridge.js";
 export { buildAIHealthReport, readAIDiagnosticsSnapshot, readReactiveTraceArtifact, readAIEvents, resolveAIStorePaths, type AIHealthReport, type AIStorePaths, } from "./store.js";
 export { createAIMCPServer, createLineReader, type AIMCPServerOptions, } from "./mcp.js";
-export { createAIContextPacket, renderAIContextMarkdown, type AIContextPacket, } from "./summary.js";
+export { createAIContextPacket, createAIDeploySummary, createAIIncidentBrief, createAIIncidentSnapshot, createAIReleaseBrief, renderAIDeploySummaryMarkdown, renderAIIncidentBriefMarkdown, renderAIIncidentSnapshotMarkdown, renderAIContextMarkdown, renderAIReleaseBriefMarkdown, type AIContextPacket, type AIDeploySummary, type AIIncidentBrief, type AIIncidentSnapshot, type AIReleaseBrief, } from "./summary.js";
 export { buildAIContextBundle, renderAIContextBundleMarkdown, type AIContextBundle, type AIContextSnippet, } from "./bundle.js";
 export { buildAIFrameworkPacket, renderAIFrameworkMarkdown, type AIFrameworkDocRef, type AIFrameworkPacket, } from "./framework-context.js";
 export { buildIDEProjection, resolveIDEProjectionPaths, writeIDEProjection, type IDEProjection, type IDEProjectionPaths, } from "./ide.js";
@@ -12,6 +12,12 @@ export { createIDEProjectionWatcher, type IDEProjectionWatcher, type IDEProjecti
 export { resolveAISessionPackConfig, resolveAISessionPackPaths, shouldGenerateAISessionPack, writeAISessionPack, type AISessionPackConfig, type AISessionPackPaths, } from "./session-pack.js";
 export type AIEventSeverity = "debug" | "info" | "warn" | "error";
 export type AIEventSource = "runtime" | "build" | "cli" | "check" | "deploy" | "dev" | "log";
+export type AIAppMode = "frontend" | "fullstack" | "server";
+export type AIRuntimeTopology = "single-instance" | "multi-instance";
+export interface AIAppContext {
+    mode: AIAppMode;
+    runtimeTopology: AIRuntimeTopology;
+}
 export interface AITraceContext {
     requestId?: string;
     traceId: string;
@@ -28,6 +34,7 @@ export interface AIDiagnostic {
     route?: string;
     fix?: string;
     ts: string;
+    app?: AIAppContext;
 }
 export interface AIEvent {
     id: string;
@@ -48,6 +55,7 @@ export interface AIEvent {
     line?: number;
     tags?: string[];
     data?: Record<string, unknown>;
+    app?: AIAppContext;
 }
 export interface AIBridgeConfig {
     url: string;
@@ -63,6 +71,7 @@ export interface AIObservabilityConfig {
     sessionId?: string;
     bridge?: AIBridgeConfig;
     sessionPack?: AISessionPackConfig;
+    app?: AIAppContext;
 }
 export declare function configureAIObservability(config?: AIObservabilityConfig): void;
 export declare function getAIObservabilityConfig(): AIObservabilityConfig;

package/dist-pkg/ai/index.js

@@ -31,7 +31,15 @@ export {
 } from "./mcp.js";
 export {
   createAIContextPacket,
-  renderAIContextMarkdown
+  createAIDeploySummary,
+  createAIIncidentBrief,
+  createAIIncidentSnapshot,
+  createAIReleaseBrief,
+  renderAIDeploySummaryMarkdown,
+  renderAIIncidentBriefMarkdown,
+  renderAIIncidentSnapshotMarkdown,
+  renderAIContextMarkdown,
+  renderAIReleaseBriefMarkdown
 } from "./summary.js";
 export {
   buildAIContextBundle,
@@ -88,6 +96,7 @@ export async function emitAIEvent(input) {
     id: input.id ?? crypto.randomUUID(),
     ts: input.ts ?? new Date().toISOString(),
     ...input,
+    app: input.app ?? currentConfig.app,
     data: redactValue(input.data, currentConfig.redactKeys ?? DEFAULT_REDACT_KEYS)
   }, writes = [];
   if (currentConfig.jsonlPath)
@@ -194,6 +203,7 @@ async function writeDiagnosticsSnapshot(path, event) {
   const snapshot = {
     updatedAt: event.ts,
     sessionId: currentConfig.sessionId,
+    app: event.app,
     latest: {
       code: event.code,
       message: event.message,
@@ -204,7 +214,8 @@ async function writeDiagnosticsSnapshot(path, event) {
       route: event.route,
       requestId: event.requestId,
       traceId: event.traceId,
-      spanId: event.spanId
+      spanId: event.spanId,
+      app: event.app
     }
   };
   await mkdir(dirname(path), { recursive: !0 });

package/dist-pkg/ai/mcp.js

@@ -131,6 +131,10 @@ export function createLineReader(input) {
 }
 function renderDoctorText(report) {
   const lines = [
+    ...report.app ? [
+      `App mode: ${report.app.mode}`,
+      `Runtime topology: ${report.app.runtimeTopology}`
+    ] : [],
     `Events: ${report.events.total}`,
     `Diagnostics: ${report.diagnostics.total}`,
     `Errors: ${report.diagnostics.errors}`,

package/dist-pkg/ai/session-pack.d.ts

@@ -13,6 +13,14 @@ export interface AISessionPackPaths {
     outDir: string;
     latestJsonPath: string;
     latestMarkdownPath: string;
+    latestReleaseBriefJsonPath: string;
+    latestReleaseBriefMarkdownPath: string;
+    latestIncidentBriefJsonPath: string;
+    latestIncidentBriefMarkdownPath: string;
+    latestDeploySummaryJsonPath: string;
+    latestDeploySummaryMarkdownPath: string;
+    latestIncidentSnapshotJsonPath: string;
+    latestIncidentSnapshotMarkdownPath: string;
     historyDir: string;
 }
 export declare function resolveAISessionPackConfig(cwd: string, config?: AISessionPackConfig): AISessionPackConfig | undefined;

package/dist-pkg/ai/session-pack.js

@@ -2,6 +2,16 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { buildAIContextBundle, renderAIContextBundleMarkdown } from "./bundle.js";
 import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
+import {
+  createAIDeploySummary,
+  createAIIncidentBrief,
+  createAIIncidentSnapshot,
+  createAIReleaseBrief,
+  renderAIDeploySummaryMarkdown,
+  renderAIIncidentBriefMarkdown,
+  renderAIIncidentSnapshotMarkdown,
+  renderAIReleaseBriefMarkdown
+} from "./summary.js";
 export function resolveAISessionPackConfig(cwd, config) {
   if (!config?.enabled)
     return config;
@@ -21,6 +31,14 @@ export function resolveAISessionPackPaths(cwd, config) {
     outDir,
     latestJsonPath: join(outDir, "latest.json"),
     latestMarkdownPath: join(outDir, "latest.md"),
+    latestReleaseBriefJsonPath: join(outDir, "release-brief.json"),
+    latestReleaseBriefMarkdownPath: join(outDir, "release-brief.md"),
+    latestIncidentBriefJsonPath: join(outDir, "incident-brief.json"),
+    latestIncidentBriefMarkdownPath: join(outDir, "incident-brief.md"),
+    latestDeploySummaryJsonPath: join(outDir, "deploy-summary.json"),
+    latestDeploySummaryMarkdownPath: join(outDir, "deploy-summary.md"),
+    latestIncidentSnapshotJsonPath: join(outDir, "incident-snapshot.json"),
+    latestIncidentSnapshotMarkdownPath: join(outDir, "incident-snapshot.md"),
     historyDir: join(outDir, "history")
   };
 }
@@ -30,18 +48,50 @@ export async function writeAISessionPack(cwd, storePaths, config) {
     maxSnippets: resolved.maxSnippets
   });
   await mkdir(paths.historyDir, { recursive: !0 });
-  const stamp = bundle.generatedAt.replace(/[:.]/g, "-"), json = JSON.stringify(bundle, null, 2), markdown = [
+  const stamp = bundle.generatedAt.replace(/[:.]/g, "-"), deploySummary = createAIDeploySummary(bundle.packet), releaseBrief = createAIReleaseBrief(bundle.packet), incidentBrief = createAIIncidentBrief(bundle.packet), incidentSnapshot = createAIIncidentSnapshot(bundle.packet), json = JSON.stringify(bundle, null, 2), markdown = [
     `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
     renderAIContextBundleMarkdown(bundle)
   ].join(`
+`), releaseBriefJson = JSON.stringify(releaseBrief, null, 2), deploySummaryJson = JSON.stringify(deploySummary, null, 2), deploySummaryMarkdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    renderAIDeploySummaryMarkdown(deploySummary)
+  ].join(`
+`), releaseBriefMarkdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    renderAIReleaseBriefMarkdown(releaseBrief)
+  ].join(`
+`), incidentBriefJson = JSON.stringify(incidentBrief, null, 2), incidentBriefMarkdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    renderAIIncidentBriefMarkdown(incidentBrief)
+  ].join(`
+`), incidentSnapshotJson = JSON.stringify(incidentSnapshot, null, 2), incidentSnapshotMarkdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    renderAIIncidentSnapshotMarkdown(incidentSnapshot)
+  ].join(`
 `);
   if ((resolved.formats ?? ["json", "markdown"]).includes("json")) {
     await writeFile(paths.latestJsonPath, json, "utf-8");
     await writeFile(join(paths.historyDir, `${stamp}.json`), json, "utf-8");
+    await writeFile(paths.latestDeploySummaryJsonPath, deploySummaryJson, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.deploy-summary.json`), deploySummaryJson, "utf-8");
+    await writeFile(paths.latestReleaseBriefJsonPath, releaseBriefJson, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.release-brief.json`), releaseBriefJson, "utf-8");
+    await writeFile(paths.latestIncidentBriefJsonPath, incidentBriefJson, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.incident-brief.json`), incidentBriefJson, "utf-8");
+    await writeFile(paths.latestIncidentSnapshotJsonPath, incidentSnapshotJson, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.incident-snapshot.json`), incidentSnapshotJson, "utf-8");
   }
   if ((resolved.formats ?? ["json", "markdown"]).includes("markdown")) {
     await writeFile(paths.latestMarkdownPath, markdown, "utf-8");
     await writeFile(join(paths.historyDir, `${stamp}.md`), markdown, "utf-8");
+    await writeFile(paths.latestDeploySummaryMarkdownPath, deploySummaryMarkdown, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.deploy-summary.md`), deploySummaryMarkdown, "utf-8");
+    await writeFile(paths.latestReleaseBriefMarkdownPath, releaseBriefMarkdown, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.release-brief.md`), releaseBriefMarkdown, "utf-8");
+    await writeFile(paths.latestIncidentBriefMarkdownPath, incidentBriefMarkdown, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.incident-brief.md`), incidentBriefMarkdown, "utf-8");
+    await writeFile(paths.latestIncidentSnapshotMarkdownPath, incidentSnapshotMarkdown, "utf-8");
+    await writeFile(join(paths.historyDir, `${stamp}.incident-snapshot.md`), incidentSnapshotMarkdown, "utf-8");
   }
   return { bundle, paths, stamp };
 }

package/dist-pkg/ai/store.d.ts

@@ -1,11 +1,33 @@
-import type { AIDiagnostic, AIEvent } from "./index.js";
+import type { AIAppContext, AIDiagnostic, AIEvent } from "./index.js";
 import type { ReactiveTraceArtifact } from "../reactive/diagnostics.js";
+import type { ReleaseArtifact } from "../server/manifest.js";
 export interface AIStorePaths {
     eventsPath: string;
     diagnosticsPath: string;
     reactiveTracePath: string;
+    releaseArtifactPath?: string;
 }
 export interface AIHealthReport {
+    app?: AIAppContext;
+    release?: {
+        appMode: ReleaseArtifact["appMode"];
+        runtimeKind: ReleaseArtifact["runtime"]["kind"];
+        processEntrypoints: string[];
+        handlerEntrypoints: string[];
+        workerEntrypoint?: string;
+        summary: ReleaseArtifact["summary"];
+        generatedAt: string;
+    };
+    readiness: {
+        deploy: {
+            status: "ready" | "caution" | "blocked";
+            reasons: string[];
+        };
+        scaling: {
+            status: "ready" | "caution" | "blocked" | "not-applicable";
+            reasons: string[];
+        };
+    };
     events: {
         total: number;
         bySeverity: Record<string, number>;
@@ -59,9 +81,11 @@ export declare function readAIEvents(path: string, options?: {
 export declare function readAIDiagnosticsSnapshot(path: string): Promise<{
     updatedAt?: string;
     sessionId?: string;
+    app?: AIAppContext;
     latest?: Partial<AIDiagnostic>;
 } | null>;
 export declare function readReactiveTraceArtifact(path: string): Promise<ReactiveTraceArtifact | null>;
+export declare function readReleaseArtifact(path: string): Promise<ReleaseArtifact | null>;
 export declare function buildAIHealthReport(paths: AIStorePaths, options?: {
     limit?: number;
 }): Promise<AIHealthReport>;

package/dist-pkg/ai/store.js

@@ -5,7 +5,8 @@ export function resolveAIStorePaths(cwd) {
   return {
     eventsPath: join(cwd, ".gorsee", "ai-events.jsonl"),
     diagnosticsPath: join(cwd, ".gorsee", "ai-diagnostics.json"),
-    reactiveTracePath: join(cwd, ".gorsee", "reactive-trace.json")
+    reactiveTracePath: join(cwd, ".gorsee", "reactive-trace.json"),
+    releaseArtifactPath: join(cwd, "dist", "release.json")
   };
 }
 export async function readAIEvents(path, options = {}) {
@@ -32,8 +33,14 @@ export async function readReactiveTraceArtifact(path) {
     return null;
   return safeJSONParse(content);
 }
+export async function readReleaseArtifact(path) {
+  const content = await safeReadFile(path);
+  if (!content)
+    return null;
+  return safeJSONParse(content);
+}
 export async function buildAIHealthReport(paths, options = {}) {
-  const events = await readAIEvents(paths.eventsPath, options), snapshot = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), bySeverity = {}, byKind = {};
+  const events = await readAIEvents(paths.eventsPath, options), snapshot = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), releaseArtifact = paths.releaseArtifactPath ? await readReleaseArtifact(paths.releaseArtifactPath) : null, bySeverity = {}, byKind = {};
   let errors = 0, warnings = 0;
   for (const event of events) {
     bySeverity[event.severity] = (bySeverity[event.severity] ?? 0) + 1;
@@ -51,8 +58,33 @@ export async function buildAIHealthReport(paths, options = {}) {
     file: event.file,
     line: event.line,
     code: event.code
-  })), incidentClusters = buildIncidentClusters(events), artifactRegressions = buildArtifactRegressions(events);
+  })), incidentClusters = buildIncidentClusters(events), artifactRegressions = buildArtifactRegressions(events), appContext = snapshot?.app ?? [...events].reverse().find((event) => event.app)?.app, releaseContext = releaseArtifact ? {
+    appMode: releaseArtifact.appMode,
+    runtimeKind: releaseArtifact.runtime.kind,
+    processEntrypoints: releaseArtifact.runtime.processEntrypoints,
+    handlerEntrypoints: releaseArtifact.runtime.handlerEntrypoints,
+    workerEntrypoint: releaseArtifact.runtime.workerEntrypoint,
+    summary: releaseArtifact.summary,
+    generatedAt: releaseArtifact.generatedAt
+  } : void 0;
   return {
+    app: appContext,
+    release: releaseContext,
+    readiness: {
+      deploy: buildDeployReadiness({
+        app: appContext,
+        release: releaseContext,
+        diagnosticsErrors: errors,
+        diagnosticsWarnings: warnings,
+        incidents,
+        artifactRegressions
+      }),
+      scaling: buildScalingReadiness({
+        app: appContext,
+        release: releaseContext,
+        events
+      })
+    },
     events: {
       total: events.length,
       bySeverity,
@@ -70,6 +102,60 @@ export async function buildAIHealthReport(paths, options = {}) {
     artifactRegressions
   };
 }
+function buildDeployReadiness(input) {
+  const reasons = [];
+  if (!input.release)
+    reasons.push("dist/release.json is missing; release-level runtime context is not available.");
+  if (input.app && input.release && input.app.mode !== input.release.appMode)
+    reasons.push(`app.mode (${input.app.mode}) does not match release artifact mode (${input.release.appMode}).`);
+  if (input.diagnosticsErrors > 0)
+    reasons.push(`AI diagnostics currently report ${input.diagnosticsErrors} error event(s).`);
+  if (input.artifactRegressions.some((entry) => entry.errors > 0))
+    reasons.push("artifact regressions contain error-level failures.");
+  if (reasons.length > 0)
+    return { status: "blocked", reasons };
+  if (input.diagnosticsWarnings > 0)
+    reasons.push(`AI diagnostics currently report ${input.diagnosticsWarnings} warning event(s).`);
+  if (input.incidents.length > 0)
+    reasons.push(`recent incident history is non-empty (${input.incidents.length}).`);
+  if (input.artifactRegressions.some((entry) => entry.warnings > 0))
+    reasons.push("artifact regressions contain warning-level drift.");
+  if (reasons.length > 0)
+    return { status: "caution", reasons };
+  reasons.push(input.release ? `release artifact is aligned for ${input.release.appMode} (${input.release.runtimeKind}).` : "no blocking deploy signals were found.");
+  return { status: "ready", reasons };
+}
+function buildScalingReadiness(input) {
+  const reasons = [], eventCodes = new Set(input.events.map((event) => event.code).filter((code) => Boolean(code)));
+  if (input.release?.appMode === "frontend")
+    return {
+      status: "not-applicable",
+      reasons: ["frontend-static release artifacts do not own a multi-instance server runtime."]
+    };
+  if (input.app?.runtimeTopology !== "multi-instance")
+    return {
+      status: "not-applicable",
+      reasons: ["runtime.topology is not declared as multi-instance."]
+    };
+  if (!input.release)
+    reasons.push("dist/release.json is missing; scaling cannot be assessed against the built runtime.");
+  if (input.release && input.release.runtimeKind === "frontend-static")
+    reasons.push("release runtime kind is frontend-static, which cannot satisfy multi-instance server scaling.");
+  for (const code of ["W917", "W918", "W919", "W920"])
+    if (eventCodes.has(code))
+      reasons.push(`check/runtime events still report ${code}, which blocks distributed scaling readiness.`);
+  if (reasons.length > 0)
+    return { status: "blocked", reasons };
+  if (eventCodes.has("W921"))
+    return {
+      status: "caution",
+      reasons: ["multi-instance runtime is configured, but AI observability does not yet forward to a bridge/aggregator (W921)."]
+    };
+  return {
+    status: "ready",
+    reasons: ["multi-instance topology is declared and no distributed-state blocker signals are present."]
+  };
+}
 function buildIncidentClusters(events) {
   const clusters = new Map;
   for (const event of events) {