bonescript-compiler 0.2.0 → 0.3.0

package/src/commands/check.ts

@@ -0,0 +1,33 @@
+/**
+ * bonec check <file>
+ * Lex + parse + type check without code generation.
+ */
+
+import { Lexer } from "../lexer";
+import { RecoveringParser } from "../parser_recovery";
+import { TypeChecker } from "../typechecker";
+
+export function runCheck(source: string): void {
+  const tokens = new Lexer(source).tokenize();
+  const result = new RecoveringParser(tokens).parse();
+  let totalErrors = 0;
+
+  for (const e of result.errors) {
+    console.error(`  parse: ${e.message}`);
+    totalErrors++;
+  }
+
+  if (result.ast) {
+    for (const err of new TypeChecker().check(result.ast)) {
+      console.error(`  type:  ${err.code} at ${err.loc.line}:${err.loc.column}: ${err.message}`);
+      totalErrors++;
+    }
+  }
+
+  if (totalErrors === 0) {
+    console.log("v Check passed (0 errors)");
+  } else {
+    console.log(`x ${totalErrors} error(s) found.`);
+    process.exit(1);
+  }
+}

package/src/commands/compile.ts

@@ -0,0 +1,160 @@
+/**
+ * bonec compile <file>
+ * Full 7-stage compilation pipeline → runnable project.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { createHash } from "crypto";
+import { Lexer } from "../lexer";
+import { TypeChecker } from "../typechecker";
+import { Lowering } from "../lowering";
+import { ConstraintSolver } from "../solver";
+import { FullEmitter } from "../emit_full";
+import { Verifier } from "../verifier";
+import { ModuleLoader } from "../module_loader";
+import { mergeWithExisting } from "../extension_manager";
+import { optimize } from "../optimizer";
+
+export async function runCompile(source: string, resolved: string): Promise<void> {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    console.log(`  [1/7] Lexed: ${tokens.length} tokens`);
+
+    const loader = new ModuleLoader();
+    const loadResult = await loader.load(resolved);
+
+    if (loadResult.errors.length > 0) {
+      console.log(`  [2/7] Parse: ${loadResult.errors.length} error(s)`);
+      for (const e of loadResult.errors.slice(0, 10)) {
+        console.log(`         ${path.basename(e.file)}: ${e.error.message}`);
+      }
+      if (!loadResult.ast) process.exit(1);
+    } else {
+      const sysCount = loadResult.ast?.systems.length || 0;
+      console.log(`  [2/7] Parsed: ${sysCount} system(s) from ${loadResult.loadedFiles.length} file(s)`);
+    }
+
+    const ast = loadResult.ast!;
+
+    for (const sys of ast.systems) {
+      console.log(`         System '${sys.name}':`);
+      const counts: Record<string, number> = {};
+      for (const d of sys.declarations) counts[d.kind] = (counts[d.kind] || 0) + 1;
+      for (const [kind, count] of Object.entries(counts)) {
+        console.log(`           ${kind}: ${count}`);
+      }
+    }
+
+    // Stage 3: Type Check
+    const typeErrors = new TypeChecker().check(ast);
+    if (typeErrors.length > 0) {
+      console.log(`  [3/7] Type check: ${typeErrors.length} error(s)`);
+      for (const err of typeErrors) {
+        console.log(`         ${err.code} at ${err.loc.line}:${err.loc.column}: ${err.message}`);
+      }
+    } else {
+      console.log(`  [3/7] Type check: v (0 errors)`);
+    }
+
+    // Stage 4: Lower to IR
+    const sourceHash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+    const irSystems = new Lowering().lower(ast, sourceHash);
+    const totalModules = irSystems.reduce((sum, s) => sum + s.modules.length, 0);
+    const totalEvents  = irSystems.reduce((sum, s) => sum + s.events.length, 0);
+    const totalFlows   = irSystems.reduce((sum, s) => sum + s.flows.length, 0);
+    console.log(`  [4/7] Lower to IR: ${totalModules} modules, ${totalEvents} events, ${totalFlows} flows`);
+    for (const sys of irSystems) {
+      for (const mod of sys.modules) {
+        const methodCount = mod.interfaces.reduce((s, i) => s + i.methods.length, 0);
+        console.log(`         ${mod.kind.padEnd(16)} ${mod.name.padEnd(24)} (${methodCount} methods, ${mod.models.length} models)`);
+      }
+    }
+
+    // Stage 4.5: IR Optimization
+    for (let i = 0; i < irSystems.length; i++) {
+      const result = optimize(irSystems[i]);
+      irSystems[i] = result.system;
+      if (result.log.length > 0) {
+        console.log(`  [4.5] IR optimize: ${result.modulesRemoved} modules removed, ${result.eventsDeduped} events deduped, ${result.depsRemoved} deps minimized`);
+      }
+    }
+
+    // Stage 5: Constraint Solve
+    const solver = new ConstraintSolver();
+    let totalResolved = 0;
+    for (const sys of irSystems) {
+      const result = solver.solve(sys);
+      sys.resolution = result.resolution;
+      totalResolved += Object.keys(result.resolution).length;
+      if (result.errors.length > 0) {
+        console.log(`  [5/7] Constraint solve: ${result.errors.length} error(s)`);
+        for (const err of result.errors) console.log(`         x ${err}`);
+      } else {
+        console.log(`  [5/7] Constraint solve: v (${totalResolved} resolved, ${result.assumptions.length} assumptions)`);
+        for (const a of result.assumptions.slice(0, 5)) console.log(`         ${a}`);
+        if (result.assumptions.length > 5) console.log(`         ... and ${result.assumptions.length - 5} more`);
+      }
+    }
+
+    // Stage 6: Code Emit
+    const emitter = new FullEmitter();
+    const allFiles: ReturnType<typeof emitter.emit> = [];
+    for (const sys of irSystems) allFiles.push(...emitter.emit(sys));
+    console.log(`  [6/7] Code emit: ${allFiles.length} files generated`);
+    const byLang: Record<string, number> = {};
+    for (const f of allFiles) byLang[f.language] = (byLang[f.language] || 0) + 1;
+    for (const [lang, count] of Object.entries(byLang)) {
+      console.log(`         ${lang}: ${count} file(s)`);
+    }
+
+    // Stage 7: Verify
+    const verifyResult = new Verifier().verify(irSystems[0], allFiles);
+    const errCount  = verifyResult.issues.filter(i => i.severity === "error").length;
+    const warnCount = verifyResult.issues.filter(i => i.severity === "warning").length;
+    if (verifyResult.passed) {
+      console.log(`  [7/7] Verify: v (${allFiles.length} files, ${warnCount} warnings)`);
+    } else {
+      console.log(`  [7/7] Verify: FAILED (${errCount} errors, ${warnCount} warnings)`);
+    }
+    for (const issue of verifyResult.issues.slice(0, 10)) {
+      console.log(`         ${issue.severity === "error" ? "x" : "!"} ${issue.code}: ${issue.message}`);
+    }
+
+    // Write output — all writes in parallel per directory
+    const outputDir = path.resolve(path.dirname(resolved), "output");
+    const allExtensions = irSystems.flatMap(s => s.extension_points || []);
+    const extensionErrors: string[] = [];
+
+    // Collect unique directories and create them all first
+    const dirs = new Set(allFiles.map(f => path.dirname(path.join(outputDir, f.path))));
+    await Promise.all([...dirs].map(dir => fs.promises.mkdir(dir, { recursive: true })));
+
+    // Write all files (extensions.ts merged, rest written directly)
+    await Promise.all(allFiles.map(async f => {
+      const outPath = path.join(outputDir, f.path);
+
+      if (f.path === "src/extensions.ts" && allExtensions.length > 0) {
+        const astExtensions = ast.systems.flatMap(s =>
+          s.declarations.filter((d): d is any => d.kind === "ExtensionPointDecl")
+        );
+        const { content, validationErrors } = await mergeWithExisting(f.content, outPath, astExtensions);
+        for (const e of validationErrors) extensionErrors.push(e.message);
+        await fs.promises.writeFile(outPath, content, "utf-8");
+      } else {
+        await fs.promises.writeFile(outPath, f.content, "utf-8");
+      }
+    }));
+
+    if (extensionErrors.length > 0) {
+      console.log(`\n  Extension point errors:`);
+      for (const e of extensionErrors) console.log(`    x ${e}`);
+      process.exit(1);
+    }
+
+    console.log(`\nv Compilation complete. ${allFiles.length} files written to output/`);
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/debug.ts

@@ -0,0 +1,33 @@
+/**
+ * bonec debug <file>
+ * Generate source maps (.bone.map) for runtime error annotation.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { createHash } from "crypto";
+import { Lexer } from "../lexer";
+import { Parser } from "../parser";
+import { Lowering } from "../lowering";
+import { emitSourceMapFile } from "../emit_sourcemap";
+
+export async function runDebug(source: string, resolved: string): Promise<void> {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    const ast = new Parser(tokens).parse();
+    const sourceHash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+    const irSystems = new Lowering().lower(ast, sourceHash);
+
+    await Promise.all(irSystems.map(async sys => {
+      const mapContent = emitSourceMapFile(sys, path.basename(resolved));
+      const mapPath = path.join(path.dirname(resolved), `${sys.name}.bone.map`);
+      await fs.promises.writeFile(mapPath, mapContent, "utf-8");
+      console.log(`v Source map written: ${mapPath}`);
+      console.log(`  ${sys.modules.length} modules mapped`);
+      console.log(`  Use output/src/debug.ts to get annotated runtime errors`);
+    }));
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/diff.ts

@@ -0,0 +1,108 @@
+/**
+ * bonec diff <old.bone> <new.bone>
+ * Show SQL schema migration diff between two .bone files.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { createHash } from "crypto";
+import { Lexer } from "../lexer";
+import { Parser } from "../parser";
+import { Lowering } from "../lowering";
+import type * as IR from "../ir";
+
+const SQL_TYPE_MAP: Record<string, string> = {
+  string: "VARCHAR", uint: "BIGINT", int: "BIGINT", float: "DOUBLE PRECISION",
+  bool: "BOOLEAN", timestamp: "TIMESTAMPTZ", uuid: "UUID", bytes: "BYTEA", json: "JSONB",
+};
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+async function compileToIR(filePath: string): Promise<IR.IRSystem[]> {
+  const resolved = path.resolve(filePath);
+  try {
+    await fs.promises.access(resolved);
+  } catch {
+    console.error(`File not found: ${resolved}`);
+    process.exit(1);
+  }
+  const source = await fs.promises.readFile(resolved, "utf-8");
+  const tokens = new Lexer(source).tokenize();
+  const ast = new Parser(tokens).parse();
+  const hash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  return new Lowering().lower(ast, hash);
+}
+
+export async function runDiff(args: string[]): Promise<void> {
+  if (args.length < 2) {
+    console.error("Usage: bonec diff <old.bone> <new.bone>");
+    process.exit(1);
+  }
+
+  const [oldFile, newFile] = args;
+
+  // Load both files in parallel
+  const [oldIR, newIR] = await Promise.all([
+    compileToIR(oldFile),
+    compileToIR(newFile),
+  ]);
+
+  const collectModels = (systems: IR.IRSystem[]) => {
+    const models: IR.IRModel[] = [];
+    for (const sys of systems)
+      for (const mod of sys.modules)
+        for (const m of mod.models) models.push(m);
+    return models;
+  };
+
+  const oldByName = new Map(collectModels(oldIR).map(m => [m.name, m]));
+  const newByName = new Map(collectModels(newIR).map(m => [m.name, m]));
+  const statements: string[] = [];
+
+  for (const [name] of newByName) {
+    if (!oldByName.has(name)) {
+      statements.push(`-- NEW TABLE: ${name}`);
+      statements.push(`-- Run: bonec compile ${newFile} (generates full migration)`);
+    }
+  }
+
+  for (const [name] of oldByName) {
+    if (!newByName.has(name)) {
+      const table = toSnakeCase(name) + "s";
+      statements.push(`-- WARNING: Table '${table}' removed from schema`);
+      statements.push(`-- Manual: ALTER TABLE ${table} ... (or DROP TABLE ${table})`);
+    }
+  }
+
+  for (const [name, newModel] of newByName) {
+    const oldModel = oldByName.get(name);
+    if (!oldModel) continue;
+    const table = toSnakeCase(name) + "s";
+    const oldFields = new Map(oldModel.fields.map(f => [f.name, f]));
+    const newFields = new Map(newModel.fields.map(f => [f.name, f]));
+
+    for (const [fname, field] of newFields) {
+      if (!oldFields.has(fname)) {
+        const sqlType = SQL_TYPE_MAP[field.type] || "JSONB";
+        statements.push(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${fname} ${sqlType};`);
+      }
+    }
+    for (const [fname] of oldFields) {
+      if (!newFields.has(fname)) {
+        statements.push(`-- WARNING: Column '${table}.${fname}' removed`);
+        statements.push(`-- Manual: ALTER TABLE ${table} DROP COLUMN ${fname};`);
+      }
+    }
+  }
+
+  if (statements.length === 0) {
+    console.log("No schema changes detected.");
+  } else {
+    console.log(`-- BoneScript schema diff: ${path.basename(oldFile)} → ${path.basename(newFile)}`);
+    console.log(`-- Generated: ${new Date().toISOString()}`);
+    console.log(``);
+    console.log(statements.join("\n"));
+  }
+}

package/src/commands/fmt.ts

@@ -0,0 +1,22 @@
+/**
+ * bonec fmt <file>
+ * Format a .bone file in place.
+ */
+
+import * as fs from "fs";
+import { Lexer } from "../lexer";
+import { Parser } from "../parser";
+import { Formatter } from "../formatter";
+
+export async function runFormat(source: string, resolved: string): Promise<void> {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    const ast = new Parser(tokens).parse();
+    const formatted = new Formatter().format(ast);
+    await fs.promises.writeFile(resolved, formatted, "utf-8");
+    console.log(`v Formatted ${resolved}`);
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,46 @@
+/**
+ * bonec init <name> [--domain <domain>] [--out <dir>]
+ * Scaffold a new project from a domain template.
+ */
+
+import * as path from "path";
+import { scaffold, ScaffoldDomain } from "../scaffold";
+
+const VALID_DOMAINS: ScaffoldDomain[] = [
+  "multiplayer_game", "saas_platform", "iot_system",
+  "social_network", "marketplace", "realtime_collaboration",
+];
+
+export async function runInit(args: string[]): Promise<void> {
+  if (args.length === 0) {
+    console.error("Error: bonec init requires a project name.");
+    console.error("Example: bonec init my-project --domain saas_platform");
+    process.exit(1);
+  }
+
+  const name = args[0];
+  let domain: ScaffoldDomain = "saas_platform";
+  let outDir = path.resolve(name);
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--domain" && args[i + 1]) {
+      domain = args[i + 1] as ScaffoldDomain;
+      i++;
+    } else if (args[i] === "--out" && args[i + 1]) {
+      outDir = path.resolve(args[i + 1]);
+      i++;
+    }
+  }
+
+  if (!VALID_DOMAINS.includes(domain)) {
+    console.error(`Error: Invalid domain '${domain}'. Valid: ${VALID_DOMAINS.join(", ")}`);
+    process.exit(1);
+  }
+
+  const result = await scaffold({ name, domain, outDir });
+  console.log(`v Created ${result.created.length} file(s):`);
+  for (const f of result.created) console.log(`  ${f}`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${outDir}`);
+  console.log(`  bonec compile ${name}.bone`);
+}

package/src/commands/ir.ts

@@ -0,0 +1,23 @@
+/**
+ * bonec ir <file>
+ * Print the IR as JSON.
+ */
+
+import { createHash } from "crypto";
+import { Lexer } from "../lexer";
+import { Parser } from "../parser";
+import { Lowering } from "../lowering";
+
+export function runIR(source: string): void {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    const ast = new Parser(tokens).parse();
+    const sourceHash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+    const irSystems = new Lowering().lower(ast, sourceHash);
+    console.log(JSON.stringify(irSystems, null, 2));
+    console.log(`\nv Lowered to ${irSystems.length} IR system(s).`);
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/lex.ts

@@ -0,0 +1,17 @@
+/**
+ * bonec lex <file>
+ * Print the token stream as JSON.
+ */
+
+import { Lexer } from "../lexer";
+
+export function runLex(source: string): void {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    console.log(JSON.stringify(tokens, null, 2));
+    console.log(`\nv ${tokens.length} tokens produced.`);
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/parse.ts

@@ -0,0 +1,24 @@
+/**
+ * bonec parse <file>
+ * Print the AST as JSON.
+ */
+
+import { Lexer } from "../lexer";
+import { RecoveringParser } from "../parser_recovery";
+
+export function runParse(source: string): void {
+  try {
+    const tokens = new Lexer(source).tokenize();
+    const result = new RecoveringParser(tokens).parse();
+    if (result.errors.length > 0) {
+      console.error(`x ${result.errors.length} parse error(s):`);
+      for (const e of result.errors) console.error(`  ${e.message}`);
+      if (!result.ast) process.exit(1);
+    }
+    console.log(JSON.stringify(result.ast, null, 2));
+    console.log(`\nv Parsed ${result.ast?.systems.length || 0} system(s).`);
+  } catch (e: any) {
+    console.error(`x ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/test.ts

@@ -0,0 +1,36 @@
+/**
+ * bonec test [output-dir]
+ * Run the generated regression test suite against a live server.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+export async function runTest(args: string[]): Promise<void> {
+  const outputDir = args[0] ? path.resolve(args[0]) : path.resolve("output");
+  const testFile = path.join(outputDir, "src", "tests.ts");
+
+  try {
+    await fs.promises.access(testFile);
+  } catch {
+    console.error(`No test file found at ${testFile}`);
+    console.error("Run 'bonec compile <file>' first to generate tests.");
+    process.exit(1);
+  }
+
+  console.log(`Running BoneScript regression tests...`);
+  console.log(`Test file: ${testFile}`);
+  console.log(`Target: ${process.env.TEST_BASE_URL || "http://localhost:3000"}`);
+  console.log(``);
+
+  try {
+    execSync(`npx ts-node ${testFile}`, {
+      cwd: outputDir,
+      stdio: "inherit",
+      env: { ...process.env },
+    });
+  } catch {
+    process.exit(1);
+  }
+}

package/src/commands/verify_determinism.ts

@@ -0,0 +1,66 @@
+/**
+ * bonec verify-determinism <file>
+ * Compile twice and assert bitwise-identical output.
+ */
+
+import { createHash } from "crypto";
+import { Lexer } from "../lexer";
+import { Parser } from "../parser";
+import { Lowering } from "../lowering";
+import { FullEmitter } from "../emit_full";
+
+export function runVerifyDeterminism(source: string): void {
+  console.log("Verifying compilation determinism...");
+
+  const compile = (): string => {
+    const tokens = new Lexer(source).tokenize();
+    const ast = new Parser(tokens).parse();
+    const hash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+    const ir = new Lowering().lower(ast, hash);
+    const emitter = new FullEmitter();
+    const files: { path: string; content: string }[] = [];
+    for (const sys of ir) {
+      for (const f of emitter.emit(sys)) {
+        files.push({ path: f.path, content: f.content });
+      }
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return JSON.stringify(files);
+  };
+
+  const run1 = compile();
+  const run2 = compile();
+
+  if (run1 === run2) {
+    const hash = createHash("sha256").update(run1).digest("hex").slice(0, 16);
+    console.log(`v Deterministic. Both runs produced identical output.`);
+    console.log(`  Output hash: ${hash}`);
+    return;
+  }
+
+  const files1: { path: string; content: string }[] = JSON.parse(run1);
+  const files2: { path: string; content: string }[] = JSON.parse(run2);
+
+  for (let i = 0; i < Math.max(files1.length, files2.length); i++) {
+    const f1 = files1[i];
+    const f2 = files2[i];
+    if (!f1 || !f2 || f1.path !== f2.path || f1.content !== f2.content) {
+      console.error(`x NON-DETERMINISTIC: First divergence at file ${i}`);
+      console.error(`  Run 1: ${f1?.path || "(missing)"}`);
+      console.error(`  Run 2: ${f2?.path || "(missing)"}`);
+      if (f1 && f2 && f1.path === f2.path) {
+        const lines1 = f1.content.split("\n");
+        const lines2 = f2.content.split("\n");
+        for (let j = 0; j < Math.max(lines1.length, lines2.length); j++) {
+          if (lines1[j] !== lines2[j]) {
+            console.error(`  First differing line ${j + 1}:`);
+            console.error(`    Run 1: ${lines1[j]}`);
+            console.error(`    Run 2: ${lines2[j]}`);
+            break;
+          }
+        }
+      }
+      process.exit(1);
+    }
+  }
+}

package/src/commands/watch.ts

@@ -0,0 +1,25 @@
+/**
+ * bonec watch <file>
+ * Recompile on every save.
+ */
+
+import * as fs from "fs";
+import { runCompile } from "./compile";
+
+export function runWatch(_source: string, resolved: string): void {
+  console.log(`Watching ${resolved}...`);
+
+  const compile = () => {
+    fs.promises.readFile(resolved, "utf-8")
+      .then(fresh => {
+        console.log(`\n[${new Date().toLocaleTimeString()}] Compiling...`);
+        return runCompile(fresh, resolved);
+      })
+      .catch((e: any) => console.error(`x ${e.message}`));
+  };
+
+  compile();
+  fs.watchFile(resolved, { interval: 500 }, (curr, prev) => {
+    if (curr.mtimeMs !== prev.mtimeMs) compile();
+  });
+}

package/src/emit_auth.ts

@@ -0,0 +1,67 @@
+/**
+ * BoneScript Auth Emitter
+ * Generates auth.ts — JWT middleware with production safety checks.
+ */
+
+import * as IR from "./ir";
+
+export function emitAuthMiddleware(_system: IR.IRSystem): string {
+  return `// Generated by BoneScript compiler. DO NOT EDIT.
+import { Request, Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+
+// JWT_SECRET must be set in production. The server will refuse to start without it
+// when NODE_ENV is "production" to prevent accidental use of a weak fallback.
+const JWT_SECRET = (() => {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) {
+    if (process.env.NODE_ENV === "production") {
+      console.error("[FATAL] JWT_SECRET environment variable is not set. Refusing to start in production.");
+      process.exit(1);
+    }
+    console.warn("[WARN] JWT_SECRET is not set. Using insecure default — do not use in production.");
+    return "bonescript-dev-secret-do-not-use-in-production";
+  }
+  if (secret.length < 32) {
+    console.warn("[WARN] JWT_SECRET is shorter than 32 characters. Use a longer secret in production.");
+  }
+  return secret;
+})();
+
+export interface AuthContext {
+  authenticated: boolean;
+  actor_id: string | null;
+  trace_id: string;
+}
+
+export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
+  const header = req.headers.authorization;
+  if (!header || !header.startsWith("Bearer ")) {
+    (req as any).auth = { authenticated: false, actor_id: null, trace_id: req.headers["x-trace-id"] as string || "" };
+    next();
+    return;
+  }
+  try {
+    const token = header.slice(7);
+    const decoded = jwt.verify(token, JWT_SECRET) as { sub: string };
+    (req as any).auth = {
+      authenticated: true,
+      actor_id: decoded.sub,
+      trace_id: req.headers["x-trace-id"] as string || "",
+    };
+  } catch {
+    (req as any).auth = { authenticated: false, actor_id: null, trace_id: req.headers["x-trace-id"] as string || "" };
+  }
+  next();
+}
+
+export function requireAuth(req: Request, res: Response, next: NextFunction): void {
+  const auth: AuthContext = (req as any).auth;
+  if (!auth || !auth.authenticated) {
+    res.status(401).json({ error: { code: "UNAUTHORIZED", message: "Authentication required" } });
+    return;
+  }
+  next();
+}
+`;
+}