forgeos 0.1.0-alpha.32 → 0.1.0-alpha.34

package/src/forge/cli/workos.ts

@@ -28,6 +28,7 @@ export interface WorkOSCommandResult {
   checks: WorkOSCheck[];
   command?: string[];
   applied?: boolean;
+  data?: unknown;
   stdout?: string;
   stderr?: string;
   exitCode: 0 | 1;
@@ -87,6 +88,180 @@ function includesAll(haystack: string, needles: string[]): boolean {
   return needles.every((needle) => haystack.includes(needle));
 }
 
+function uniqueSorted(values: Iterable<string>): string[] {
+  return [...new Set([...values].filter(Boolean))].sort();
+}
+
+function quotedValues(text: string): string[] {
+  return [...text.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]!).filter(Boolean);
+}
+
+interface WorkOSSeedSummary {
+  exists: boolean;
+  valid: boolean;
+  path: string;
+  permissions: string[];
+  roles: string[];
+  resourceTypes: string[];
+  organizations: string[];
+  domains: string[];
+  diagnostics: string[];
+}
+
+function parseSlug(line: string): string | null {
+  const match = /(?:^|\s)-?\s*slug:\s*["']?([^"',\]\s]+)["']?/.exec(line);
+  return match?.[1] ?? null;
+}
+
+function parseName(line: string): string | null {
+  const match = /(?:^|\s)-?\s*name:\s*["']?([^"'\]]+(?:\s[^"'\]]+)*)["']?/.exec(line);
+  return match?.[1]?.trim() ?? null;
+}
+
+function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEED_FILE): WorkOSSeedSummary {
+  const seedPath = exists(workspaceRoot, preferredPath)
+    ? preferredPath
+    : exists(workspaceRoot, GENERATED_SEED_FILE)
+      ? GENERATED_SEED_FILE
+      : preferredPath;
+  const raw = readText(workspaceRoot, seedPath);
+  const permissions = new Set<string>();
+  const roles = new Set<string>();
+  const resourceTypes = new Set<string>();
+  const organizations = new Set<string>();
+  const domains = new Set<string>();
+  const diagnostics: string[] = [];
+  let section = "";
+
+  if (!raw.trim()) {
+    return {
+      exists: false,
+      valid: false,
+      path: seedPath,
+      permissions: [],
+      roles: [],
+      resourceTypes: [],
+      organizations: [],
+      domains: [],
+      diagnostics: [`${seedPath} is missing or empty`],
+    };
+  }
+
+  for (const line of raw.split(/\r?\n/)) {
+    const rootSection = /^([a-zA-Z_][\w-]*):\s*$/.exec(line);
+    if (rootSection) {
+      section = rootSection[1]!;
+      continue;
+    }
+
+    const slug = parseSlug(line);
+    if (slug) {
+      if (section === "permissions") {
+        permissions.add(slug);
+      } else if (section === "roles") {
+        roles.add(slug);
+      } else if (section === "resource_types") {
+        resourceTypes.add(slug);
+      }
+    }
+
+    if (section === "organizations") {
+      const name = parseName(line);
+      if (name) {
+        organizations.add(name);
+      }
+      for (const value of quotedValues(line)) {
+        if (value.includes(".")) {
+          domains.add(value);
+        }
+      }
+    }
+
+    for (const match of line.matchAll(/-\s*["']?([a-zA-Z0-9_.-]+:[a-zA-Z0-9_.-]+)["']?/g)) {
+      permissions.add(match[1]!);
+    }
+  }
+
+  if (permissions.size === 0) diagnostics.push("no permission slugs found");
+  if (roles.size === 0) diagnostics.push("no role slugs found");
+  if (resourceTypes.size === 0) diagnostics.push("no resource_types slugs found");
+  if (organizations.size === 0) diagnostics.push("no organizations found");
+
+  return {
+    exists: true,
+    valid: diagnostics.length === 0,
+    path: seedPath,
+    permissions: uniqueSorted(permissions),
+    roles: uniqueSorted(roles),
+    resourceTypes: uniqueSorted(resourceTypes),
+    organizations: uniqueSorted(organizations),
+    domains: uniqueSorted(domains),
+    diagnostics,
+  };
+}
+
+function collectPolicyPermissions(workspaceRoot: string): string[] {
+  const registry = readJson(workspaceRoot, `${GENERATED_DIR}/policyRegistry.json`) as {
+    policies?: Array<{ permissions?: string[] }>;
+  } | null;
+  const permissions = new Set<string>();
+  for (const policy of registry?.policies ?? []) {
+    for (const permission of policy.permissions ?? []) {
+      permissions.add(permission);
+    }
+  }
+  for (const path of ["src/policies.ts", "src/policies.workos.ts"]) {
+    const text = readText(workspaceRoot, path);
+    for (const match of text.matchAll(/canPermission\s*\(([^)]*)\)/g)) {
+      for (const value of quotedValues(match[1] ?? "")) {
+        permissions.add(value);
+      }
+    }
+  }
+  return uniqueSorted(permissions);
+}
+
+function singularResourceName(name: string): string {
+  if (name.endsWith("ies")) {
+    return `${name.slice(0, -3)}y`;
+  }
+  if (name.endsWith("ses")) {
+    return name.slice(0, -2);
+  }
+  if (name.endsWith("s") && name.length > 1) {
+    return name.slice(0, -1);
+  }
+  return name;
+}
+
+function collectExpectedResourceTypes(workspaceRoot: string): string[] {
+  const dataGraph = readJson(workspaceRoot, `${GENERATED_DIR}/dataGraph.json`) as {
+    tables?: Array<{ name?: string; fields?: Array<{ name?: string }> }>;
+  } | null;
+  const agentContract = readJson(workspaceRoot, `${GENERATED_DIR}/agentContract.json`) as {
+    auth?: { requiresTenant?: boolean };
+  } | null;
+  const resourceTypes = new Set<string>();
+  const tenantScopedTables = (dataGraph?.tables ?? []).filter((table) =>
+    (table.fields ?? []).some((field) => field.name === "tenantId")
+  );
+  if (agentContract?.auth?.requiresTenant || tenantScopedTables.length > 0) {
+    resourceTypes.add("organization");
+  }
+  for (const table of tenantScopedTables) {
+    if (!table.name || ["organizations", "organization", "memberships", "membership"].includes(table.name)) {
+      continue;
+    }
+    resourceTypes.add(singularResourceName(table.name));
+  }
+  return uniqueSorted(resourceTypes);
+}
+
+function missingValues(expected: string[], actual: string[]): string[] {
+  const actualSet = new Set(actual);
+  return expected.filter((value) => !actualSet.has(value));
+}
+
 function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
   const packageJson = readJson(workspaceRoot, "package.json") as {
     dependencies?: Record<string, string>;
@@ -103,7 +278,11 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
     ...(packageJson?.dependencies ?? {}),
     ...(packageJson?.devDependencies ?? {}),
   };
-  const seedFile = readText(workspaceRoot, DEFAULT_SEED_FILE) || readText(workspaceRoot, GENERATED_SEED_FILE);
+  const seed = parseSeedFile(workspaceRoot);
+  const activePermissions = collectPolicyPermissions(workspaceRoot);
+  const expectedResourceTypes = collectExpectedResourceTypes(workspaceRoot);
+  const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
+  const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
   const authRoutes = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/auth-routes.ts`);
   const fga = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/fga.ts`);
   const resourceMap = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/resource-map.ts`);
@@ -135,30 +314,33 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
     },
     {
       name: "seed-file",
-      ok: exists(workspaceRoot, DEFAULT_SEED_FILE) || exists(workspaceRoot, GENERATED_SEED_FILE),
-      detail: `${DEFAULT_SEED_FILE} exists at the app root; generated fallback is ${GENERATED_SEED_FILE}`,
+      ok: seed.exists,
+      detail: seed.exists
+        ? `${seed.path} exists with ${seed.permissions.length} permission(s), ${seed.roles.length} role(s), ${seed.resourceTypes.length} resource type(s)`
+        : `${DEFAULT_SEED_FILE} or ${GENERATED_SEED_FILE} is required`,
     },
     {
       name: "seed-organizations",
-      ok: includesAll(seedFile, ["Acme Corp", "Globex", "acme.test", "globex.test"]),
-      detail: "seed file contains Acme/Globex demo organizations and domains",
+      ok: seed.organizations.length > 0,
+      detail: seed.organizations.length > 0
+        ? `seed file contains organization(s): ${seed.organizations.join(", ")}`
+        : "seed file should contain at least one demo organization",
     },
     {
       name: "seed-roles-permissions",
-      ok: includesAll(seedFile, [
-        "owner",
-        "manager",
-        "member",
-        "onboarding:read",
-        "invitations:create",
-        "tasks:update",
-      ]),
-      detail: "seed file contains owner/manager/member roles and onboarding permissions",
+      ok: seed.roles.length > 0 &&
+        (activePermissions.length === 0 ? seed.permissions.length > 0 : missingSeedPermissions.length === 0),
+      detail: missingSeedPermissions.length === 0
+        ? `seed covers ${activePermissions.length} active policy permission(s) with role(s): ${seed.roles.join(", ")}`
+        : `seed missing active policy permission(s): ${missingSeedPermissions.join(", ")}`,
     },
     {
       name: "seed-resource-types",
-      ok: includesAll(seedFile, ["resource_types:", "organization", "project", "taskGroup", "task"]),
-      detail: "seed file contains WorkOS FGA resource types for the Forge app graph",
+      ok: seed.resourceTypes.length > 0 &&
+        (expectedResourceTypes.length === 0 || missingSeedResources.length === 0),
+      detail: missingSeedResources.length === 0
+        ? `seed resource_types cover app graph: ${expectedResourceTypes.length > 0 ? expectedResourceTypes.join(", ") : seed.resourceTypes.join(", ")}`
+        : `seed missing resource_type(s) for app graph: ${missingSeedResources.join(", ")}`,
     },
     {
       name: "authkit-routes",
@@ -192,14 +374,17 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
         "permissionSlug",
         "resourceExternalId",
       ]) &&
-        includesAll(fga, ["forgeWorkOSResourceTypes", "organization", "project", "task"]),
+        includesAll(fga, ["forgeWorkOSResourceTypes"]),
       detail: "WorkOS FGA resource-map bridge exists with sync, cache, telemetry, official check shape, and cross-tenant guard",
     },
     {
       name: "policies",
       ok: exists(workspaceRoot, "src/policies.workos.ts") &&
-        includesAll(policies, ["canPermission", "invitations:create", "tasks:update"]),
-      detail: "WorkOS-derived Forge policy template exists and is permission-first",
+        policies.includes("canPermission") &&
+        missingValues(activePermissions, quotedValues(policies)).length === 0,
+      detail: activePermissions.length === 0
+        ? "WorkOS-derived Forge policy template exists and is permission-first"
+        : `WorkOS-derived policy template covers active permission(s): ${activePermissions.join(", ")}`,
     },
   ];
 }
@@ -280,19 +465,60 @@ export function runWorkOSInstallCommand(options: WorkOSCommandOptions): WorkOSCo
 
 export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   const file = options.file ?? DEFAULT_SEED_FILE;
+  const seed = parseSeedFile(options.workspaceRoot, file);
+  const activePermissions = collectPolicyPermissions(options.workspaceRoot);
+  const expectedResourceTypes = collectExpectedResourceTypes(options.workspaceRoot);
+  const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
+  const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
+  const unusedSeedPermissions = seed.permissions.filter((permission) => !activePermissions.includes(permission));
   const checks = [
     {
       name: "seed-file",
-      ok: exists(options.workspaceRoot, file),
-      detail: `${file} exists`,
+      ok: seed.exists,
+      detail: seed.exists ? `${seed.path} exists` : `${file} exists`,
+    },
+    {
+      name: "seed-yaml-shape",
+      ok: seed.valid,
+      detail: seed.valid ? "seed contains permissions, roles, resource_types, and organizations" : seed.diagnostics.join("; "),
+    },
+    {
+      name: "seed-policy-coverage",
+      ok: missingSeedPermissions.length === 0,
+      detail: missingSeedPermissions.length === 0
+        ? `seed covers ${activePermissions.length} active permission(s)`
+        : `seed missing active permission(s): ${missingSeedPermissions.join(", ")}`,
+    },
+    {
+      name: "seed-resource-coverage",
+      ok: missingSeedResources.length === 0,
+      detail: missingSeedResources.length === 0
+        ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
+        : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
     },
   ];
   const command = ["npx", "--yes", "workos@latest", "seed", "--file", file];
   if (!checks.every((check) => check.ok)) {
-    return { ok: false, kind: "workos-seed", checks, command, applied: false, exitCode: 1 };
+    return {
+      ok: false,
+      kind: "workos-seed",
+      checks,
+      command,
+      applied: false,
+      data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
+      exitCode: 1,
+    };
   }
   if (!options.yes || options.dryRun) {
-    return { ok: true, kind: "workos-seed", checks, command, applied: false, exitCode: 0 };
+    return {
+      ok: true,
+      kind: "workos-seed",
+      checks,
+      command,
+      applied: false,
+      data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
+      exitCode: 0,
+    };
   }
   const child = runExternalCommand(command, options);
   return {
@@ -301,6 +527,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     checks,
     command,
     applied: child.status === 0,
+    data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
     stdout: child.stdout,
     stderr: child.stderr,
     exitCode: child.status === 0 ? 0 : 1,

package/src/forge/compiler/app-graph/build.ts

@@ -3,6 +3,8 @@ import { hashStable } from "../primitives/hash.ts";
 import { normalizePath } from "../primitives/paths.ts";
 import { stableSortEdges, stableSortSymbols } from "../primitives/sort.ts";
 import type { AppGraph, ForgeEdge, ForgeSymbol, SourceFile } from "../types/app-graph.ts";
+import { FORGE_RUNTIME_EXPORT_NAME_REQUIRED } from "../diagnostics/codes.ts";
+import { createDiagnostic } from "../diagnostics/create.ts";
 import { detectDuplicateSymbols } from "./dup-symbol.ts";
 import { buildModuleGraph } from "./module-graph.ts";
 import { incrementalParse } from "./parser.ts";
@@ -97,6 +99,46 @@ function buildAppGraphEdges(
   return edges;
 }
 
+const NAMED_EXPORT_REQUIRED_KINDS = new Set([
+  "command",
+  "query",
+  "liveQuery",
+  "action",
+  "workflow",
+  "endpoint",
+]);
+
+function detectUnnamedForgeExports(symbols: ForgeSymbol[]): AppGraph["diagnostics"] {
+  return symbols
+    .filter((symbol) =>
+      NAMED_EXPORT_REQUIRED_KINDS.has(symbol.kind) &&
+      symbol.meta.exportPath === "default"
+    )
+    .map((symbol) =>
+      createDiagnostic({
+        severity: "error",
+        code: FORGE_RUNTIME_EXPORT_NAME_REQUIRED,
+        message:
+          `Forge ${symbol.kind} in ${symbol.file} uses export default; runtime entries must be named exports for stable API names.`,
+        file: symbol.file,
+        span: symbol.span,
+        fixHint:
+          `Replace \`export default ${symbol.kind}(...)\` with \`export const ${suggestExportName(symbol)} = ${symbol.kind}(...)\`.`,
+        suggestedCommands: ["forge check --json", "forge generate"],
+      })
+    );
+}
+
+function suggestExportName(symbol: ForgeSymbol): string {
+  const base = symbol.file
+    .split("/")
+    .pop()
+    ?.replace(/\.[cm]?[jt]sx?$/, "")
+    .replace(/[^a-zA-Z0-9]+(.)/g, (_, next: string) => next.toUpperCase())
+    .replace(/^[^a-zA-Z_]+/, "") || symbol.kind;
+  return base || symbol.kind;
+}
+
 export async function buildAppGraph(
   options: AppGraphBuildOptions,
 ): Promise<AppGraph> {
@@ -141,6 +183,7 @@ export async function buildAppGraph(
   const symbolsMs = Date.now() - checkpoint;
   checkpoint = Date.now();
   const dupDiagnostics = detectDuplicateSymbols(forgeSymbols);
+  const unnamedExportDiagnostics = detectUnnamedForgeExports(forgeSymbols);
   const duplicatesMs = Date.now() - checkpoint;
   checkpoint = Date.now();
   const moduleGraph = buildModuleGraph(
@@ -166,7 +209,7 @@ export async function buildAppGraph(
     symbols: sortedSymbols,
     edges: stableSortEdges(buildAppGraphEdges(sortedSymbols, moduleGraph)),
     moduleGraph,
-    diagnostics: [...parseDiagnostics, ...dupDiagnostics],
+    diagnostics: [...parseDiagnostics, ...dupDiagnostics, ...unnamedExportDiagnostics],
   };
   recordAppGraphProfile(graph, {
     normalizeMs,

package/src/forge/compiler/client-sdk/render-client.ts

@@ -4,7 +4,12 @@ export function renderClientTypesTs(): string {
   return `export type ForgeStaticAuth = {
   userId?: string;
   tenantId?: string;
+  organizationId?: string;
+  organizationMembershipId?: string;
   role?: string;
+  roles?: string[];
+  permissions?: string[];
+  claims?: Record<string, unknown>;
   token?: string;
   getToken?: () => string | Promise<string>;
   headers?: Record<string, string>;
@@ -14,7 +19,12 @@ export function renderClientTypesTs(): string {
 export type ForgeResolvedAuth = {
   userId?: string;
   tenantId?: string;
+  organizationId?: string;
+  organizationMembershipId?: string;
   role?: string;
+  roles?: string[];
+  permissions?: string[];
+  claims?: Record<string, unknown>;
   token?: string;
   getToken?: () => string | Promise<string>;
   headers?: Record<string, string>;
@@ -159,7 +169,12 @@ async function resolveAuthHeaders(
       typeof value === "string" &&
       key !== "userId" &&
       key !== "tenantId" &&
+      key !== "organizationId" &&
+      key !== "organizationMembershipId" &&
       key !== "role" &&
+      key !== "roles" &&
+      key !== "permissions" &&
+      key !== "claims" &&
       key !== "token"
     ) {
       headers[key] = value;
@@ -172,9 +187,25 @@ async function resolveAuthHeaders(
   if (resolved.tenantId) {
     headers["x-forge-tenant-id"] = resolved.tenantId;
   }
+  if (resolved.organizationId) {
+    headers["x-forge-organization-id"] = resolved.organizationId;
+    headers["x-forge-tenant-id"] ??= resolved.organizationId;
+  }
+  if (resolved.organizationMembershipId) {
+    headers["x-forge-organization-membership-id"] = resolved.organizationMembershipId;
+  }
   if (resolved.role) {
     headers["x-forge-role"] = resolved.role;
   }
+  if (Array.isArray(resolved.roles)) {
+    headers["x-forge-roles"] = JSON.stringify(resolved.roles);
+  }
+  if (Array.isArray(resolved.permissions)) {
+    headers["x-forge-permissions"] = JSON.stringify(resolved.permissions);
+  }
+  if (resolved.claims && typeof resolved.claims === "object") {
+    headers["x-forge-claims"] = JSON.stringify(resolved.claims);
+  }
 
   return headers;
 }

package/src/forge/compiler/data-graph/parse.ts

@@ -36,6 +36,22 @@ function unwrapStringLiteral(node: SyntaxNode): string | null {
   return null;
 }
 
+function unwrapNullableType(node: SyntaxNode): string | null {
+  if (node.type !== "call_expression") {
+    return null;
+  }
+  const functionNode = node.childForFieldName("function");
+  if (functionNode?.type !== "identifier" || functionNode.text !== "nullable") {
+    return null;
+  }
+  const argsNode = node.childForFieldName("arguments");
+  const firstArg = argsNode?.namedChildren.find((child) =>
+    child.type !== "," && child.type !== "comment" && child.type !== "(" && child.type !== ")"
+  );
+  const inner = firstArg ? unwrapStringLiteral(firstArg) : null;
+  return inner ? `${inner}?` : null;
+}
+
 function extractFieldsFromObject(objectNode: SyntaxNode, options: { skipConfigName?: boolean } = {}): DataField[] {
   const fields: DataField[] = [];
 
@@ -64,7 +80,7 @@ function extractFieldsFromObject(objectNode: SyntaxNode, options: { skipConfigNa
       continue;
     }
 
-    const typeValue = unwrapStringLiteral(valueNode);
+    const typeValue = unwrapStringLiteral(valueNode) ?? unwrapNullableType(valueNode);
     if (typeValue !== null) {
       fields.push({ name: key, type: typeValue });
     }

package/src/forge/compiler/data-graph/sql/ddl.ts

@@ -34,6 +34,7 @@ const SYSTEM_LIVE_SUBSCRIPTION_DEBUG_SQL = `CREATE TABLE IF NOT EXISTS _forge_li
 
 interface ParsedFieldType {
   sqlType: string;
+  nullable?: boolean;
   references?: { table: string; column: string };
   checkConstraint?: string;
 }
@@ -102,28 +103,35 @@ function parseFieldType(
   tableName: string,
   diagnostics: Diagnostic[],
 ): ParsedFieldType | null {
-  const raw = field.type.trim().toLowerCase();
+  const declared = field.type.trim();
+  const nullable = declared.endsWith("?");
+  const raw = (nullable ? declared.slice(0, -1) : declared).trim().toLowerCase();
+
+  const withNullability = (parsed: Omit<ParsedFieldType, "nullable">): ParsedFieldType => ({
+    ...parsed,
+    ...(nullable ? { nullable: true } : {}),
+  });
 
   if (raw === "uuid") {
-    return { sqlType: "uuid" };
+    return withNullability({ sqlType: "uuid" });
   }
   if (raw === "text" || raw === "string") {
-    return { sqlType: "text" };
+    return withNullability({ sqlType: "text" });
   }
   if (raw === "number") {
-    return { sqlType: "double precision" };
+    return withNullability({ sqlType: "double precision" });
   }
   if (raw === "integer" || raw === "int") {
-    return { sqlType: "integer" };
+    return withNullability({ sqlType: "integer" });
   }
   if (raw === "boolean" || raw === "bool") {
-    return { sqlType: "boolean" };
+    return withNullability({ sqlType: "boolean" });
   }
-  if (raw === "timestamp") {
-    return { sqlType: "timestamptz" };
+  if (raw === "timestamp" || raw === "timestamptz") {
+    return withNullability({ sqlType: "timestamptz" });
   }
   if (raw === "json") {
-    return { sqlType: "jsonb" };
+    return withNullability({ sqlType: "jsonb" });
   }
 
   if (raw.startsWith("enum:")) {
@@ -144,13 +152,14 @@ function parseFieldType(
     }
     const checkValues = values.map((value) => `'${value.replace(/'/g, "''")}'`).join(", ");
     return {
+      ...(nullable ? { nullable: true } : {}),
       sqlType: "text",
       checkConstraint: `${quoteIdent(toSnakeCase(field.name))} IN (${checkValues})`,
     };
   }
 
   if (raw.startsWith("enum_")) {
-    return { sqlType: "text" };
+    return withNullability({ sqlType: "text" });
   }
 
   if (raw.startsWith("ref:")) {
@@ -166,6 +175,7 @@ function parseFieldType(
       return null;
     }
     return {
+      ...(nullable ? { nullable: true } : {}),
       sqlType: "uuid",
       references: { table: toSnakeCase(refTable), column: "id" },
     };
@@ -173,6 +183,7 @@ function parseFieldType(
 
   if (raw === "ref") {
     return {
+      ...(nullable ? { nullable: true } : {}),
       sqlType: "uuid",
       references: { table: toSnakeCase(field.name.replace(/Id$/i, "")), column: "id" },
     };
@@ -190,7 +201,7 @@ function parseFieldType(
 
 function defaultExprForField(field: DataField): string | undefined {
   const name = field.name;
-  const type = field.type.trim().toLowerCase();
+  const type = field.type.trim().replace(/\?$/, "").toLowerCase();
 
   if (name === "id" && type === "uuid") {
     return "gen_random_uuid()";
@@ -238,7 +249,7 @@ function buildColumns(table: DataTable, diagnostics: Diagnostic[]): ColumnDef[]
       name: snakeName,
       fieldName: field.name,
       sqlType: parsed.sqlType,
-      nullable: false,
+      nullable: isPrimaryKey ? false : parsed.nullable === true,
       primaryKey: isPrimaryKey,
       defaultExpr,
       references: parsed.references,
@@ -250,7 +261,7 @@ function buildColumns(table: DataTable, diagnostics: Diagnostic[]): ColumnDef[]
     const idField = fields.find((field) => field.name === "id");
     diagnostics.push(
       createDiagnostic({
-        severity: "error",
+        severity: "warning",
         code: FORGE_DB_INVALID_SQL_PLAN,
         message: `table '${table.name}' declares id as '${idField?.type ?? "unknown"}'; Forge runtime requires id: "uuid" or no id field so Forge can generate one`,
         file: table.file,

package/src/forge/compiler/diagnostics/codes.ts

@@ -27,6 +27,8 @@ export const FORGE_DUP_RUNTIME_ENTRY = "FORGE_DUP_RUNTIME_ENTRY" as const;
 export const FORGE_RUNTIME_UNRESOLVABLE = "FORGE_RUNTIME_UNRESOLVABLE" as const;
 export const FORGE_RUNTIME_NOT_FOUND = "FORGE_RUNTIME_NOT_FOUND" as const;
 export const FORGE_RUNTIME_GUARD_BLOCKED = "FORGE_RUNTIME_GUARD_BLOCKED" as const;
+export const FORGE_RUNTIME_EXPORT_NAME_REQUIRED =
+  "FORGE_RUNTIME_EXPORT_NAME_REQUIRED" as const;
 export const FORGE_EXTERNAL_RUNTIME_NOT_FOUND =
   "FORGE_EXTERNAL_RUNTIME_NOT_FOUND" as const;
 export const FORGE_EXTERNAL_RUNTIME_UNSUPPORTED =
@@ -46,6 +48,8 @@ export const FORGE_DB_MIGRATION_FAILED = "FORGE_DB_MIGRATION_FAILED" as const;
 export const FORGE_DB_UNSUPPORTED_FIELD_TYPE =
   "FORGE_DB_UNSUPPORTED_FIELD_TYPE" as const;
 export const FORGE_DB_INVALID_SQL_PLAN = "FORGE_DB_INVALID_SQL_PLAN" as const;
+export const FORGE_DB_EMPTY_TIMESTAMP_LITERAL =
+  "FORGE_DB_EMPTY_TIMESTAMP_LITERAL" as const;
 export const FORGE_DB_TRANSACTION_FAILED = "FORGE_DB_TRANSACTION_FAILED" as const;
 export const FORGE_DB_OUTBOX_WRITE_FAILED = "FORGE_DB_OUTBOX_WRITE_FAILED" as const;
 export const FORGE_DB_ADAPTER_UNAVAILABLE = "FORGE_DB_ADAPTER_UNAVAILABLE" as const;
@@ -414,6 +418,7 @@ export const DIAGNOSTIC_CODES = [
   FORGE_RUNTIME_UNRESOLVABLE,
   FORGE_RUNTIME_NOT_FOUND,
   FORGE_RUNTIME_GUARD_BLOCKED,
+  FORGE_RUNTIME_EXPORT_NAME_REQUIRED,
   FORGE_EXTERNAL_RUNTIME_NOT_FOUND,
   FORGE_EXTERNAL_RUNTIME_UNSUPPORTED,
   FORGE_EXTERNAL_RUNTIME_FAILED,
@@ -427,6 +432,7 @@ export const DIAGNOSTIC_CODES = [
   FORGE_DB_MIGRATION_FAILED,
   FORGE_DB_UNSUPPORTED_FIELD_TYPE,
   FORGE_DB_INVALID_SQL_PLAN,
+  FORGE_DB_EMPTY_TIMESTAMP_LITERAL,
   FORGE_DB_TRANSACTION_FAILED,
   FORGE_DB_OUTBOX_WRITE_FAILED,
   FORGE_DB_ADAPTER_UNAVAILABLE,

package/src/forge/compiler/diagnostics/create.ts

@@ -47,6 +47,13 @@ function defaultGuidanceForCode(code: string): DiagnosticGuidance | null {
       docs: ["src/forge/_generated/runtimeRules.md", "AGENTS.md"],
     };
   }
+  if (code === "FORGE_RUNTIME_EXPORT_NAME_REQUIRED") {
+    return {
+      fixHint: "Forge runtime entries must be named exports. Replace `export default command(...)` with `export const createThing = command(...)` so generated API, frontend bindings, and capability maps have a stable name.",
+      suggestedCommands: ["forge check --json", "forge generate"],
+      docs: ["AGENTS.md", "src/forge/_generated/runtimeRules.md"],
+    };
+  }
   if (code === "FORGE_SECRET_DIRECT_PROCESS_ENV") {
     return {
       fixHint: "Use ctx.secrets or ctx.config for Forge runtime secrets/config; public frontend bridge env may use the framework's public env surface.",
@@ -75,6 +82,13 @@ function defaultGuidanceForCode(code: string): DiagnosticGuidance | null {
       docs: ["src/forge/_generated/agentContract.json"],
     };
   }
+  if (code === "FORGE_DB_EMPTY_TIMESTAMP_LITERAL") {
+    return {
+      fixHint: "Do not use an empty string for timestamp fields. Use a real ISO timestamp, omit an optional timestamp field, declare it as `timestamp?` / `nullable(\"timestamp\")`, or model it as text if empty string is meaningful.",
+      suggestedCommands: ["forge check --json", "forge dev --db pglite --once --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
   if (code.startsWith("FORGE_UI_")) {
     return {
       fixHint: "Inspect the last UI run and use the UI report as repair input.",