tina4-nodejs 3.13.116 → 3.13.117

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.116)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.117)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.116 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.117 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.116",
+  "version": "3.13.117",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -45430,23 +45430,203 @@ var FIELD_TYPE_MAP = {
   blob: { orm: '"string"', sql: "BLOB", defaultVal: "NULL" }
 };
 function ensureDir(dir) {
+  if (__resolution.dryRun) return;
   if (!existsSync33(dir)) {
     mkdirSync23(dir, { recursive: true });
   }
 }
 function writeFileSafe(path8, content) {
+  if (__resolution.dryRun) {
+    return;
+  }
   if (existsSync33(path8)) {
-    console.log(`  File already exists: ${path8}`);
+    if (!__resolution.jsonMode) console.log(`  File already exists: ${path8}`);
     return;
   }
   writeFileSync20(path8, content, "utf-8");
-  console.log(`  Created ${path8}`);
+  __resolution.actionsTaken.push(`wrote ${path8}`);
+  if (!__resolution.jsonMode) console.log(`  Created ${path8}`);
 }
 function toSnake(name) {
   return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
 }
+var SQL_RESERVED_TABLE_NAMES = /* @__PURE__ */ new Set([
+  "order",
+  "group",
+  "user",
+  "table",
+  "select",
+  "from",
+  "where",
+  "index",
+  "key",
+  "values",
+  "column",
+  "constraint",
+  "check",
+  "default",
+  "primary",
+  "foreign",
+  "references",
+  "unique",
+  "join",
+  "union",
+  "having",
+  "limit",
+  "offset",
+  "desc",
+  "asc",
+  "case",
+  "when",
+  "then",
+  "else",
+  "end",
+  "and",
+  "or",
+  "not",
+  "null",
+  "insert",
+  "update",
+  "delete",
+  "create",
+  "drop",
+  "alter",
+  "grant",
+  "revoke",
+  "commit",
+  "rollback",
+  "view",
+  "trigger",
+  "procedure",
+  "function",
+  "database",
+  "schema",
+  "session",
+  "set",
+  "into",
+  "as",
+  "on",
+  "by",
+  "inner",
+  "outer",
+  "left",
+  "right",
+  "full",
+  "natural",
+  "using",
+  "with",
+  "distinct",
+  "between",
+  "exists",
+  "like",
+  "in",
+  "is",
+  "all",
+  "any",
+  "cross",
+  "add",
+  "row",
+  "rows",
+  "range",
+  "current",
+  "to"
+]);
+function pluralizeReserved(name) {
+  if (name.endsWith("y") && !/[aeiouy]y$/i.test(name)) return name.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/.test(name)) return name + "es";
+  return name + "s";
+}
 function toTableName(name) {
-  return toSnake(name);
+  const raw = toSnake(name);
+  if (SQL_RESERVED_TABLE_NAMES.has(raw)) {
+    const safe = pluralizeReserved(raw);
+    recordTransformation({
+      kind: "reserved_word_pluralize",
+      from: raw,
+      to: safe,
+      reason: `SQL reserved word '${raw}' would break CREATE TABLE`,
+      override: `--table ${raw} --quote (requires quoted-identifier mode, not yet implemented)`
+    });
+    return safe;
+  }
+  return raw;
+}
+var RESOLUTION_ENVELOPE_VERSION = "generate_v1";
+var __resolution = {
+  target: "",
+  input: { name: "", fields: null },
+  body: { transformations: [] },
+  actionsTaken: [],
+  dryRun: false,
+  jsonMode: false
+};
+function resetResolution(target, input, opts) {
+  __resolution.target = target;
+  __resolution.input = input;
+  __resolution.body = { transformations: [] };
+  __resolution.actionsTaken = [];
+  __resolution.dryRun = opts.dryRun;
+  __resolution.jsonMode = opts.jsonMode;
+}
+function recordTransformation(t) {
+  __resolution.body.transformations.push(t);
+}
+function currentResolution() {
+  return {
+    command: "generate",
+    target: __resolution.target,
+    input: { ...__resolution.input },
+    resolution: {
+      ...__resolution.body,
+      transformations: [...__resolution.body.transformations]
+    },
+    actions_taken: [...__resolution.actionsTaken],
+    dry_run: __resolution.dryRun
+  };
+}
+function setResolutionField(key, value) {
+  __resolution.body[key] = value;
+}
+function pushRoute(routePattern) {
+  if (!__resolution.body.routes) __resolution.body.routes = [];
+  __resolution.body.routes.push(routePattern);
+}
+function pushTestPath(path8) {
+  if (!__resolution.body.test_paths) __resolution.body.test_paths = [];
+  __resolution.body.test_paths.push(path8);
+}
+function printResolution() {
+  if (__resolution.jsonMode) {
+    process.stdout.write(JSON.stringify(currentResolution(), null, 2) + "\n");
+    return;
+  }
+  const b = __resolution.body;
+  const lines = [];
+  lines.push("");
+  lines.push(`Generated ${__resolution.target} ${__resolution.input.name}`);
+  if (b.class_name || b.file_path) {
+    const where = b.file_path ? `  (in ${b.file_path})` : "";
+    lines.push(`  class      ${b.class_name ?? __resolution.input.name}${where}`);
+  }
+  if (b.table_name) {
+    const t = b.transformations.find((x) => x.kind === "reserved_word_pluralize");
+    const note = t ? `  (auto-pluralized: '${t.from}' is a SQL reserved word)` : "";
+    lines.push(`  table      ${b.table_name}${note}`);
+  }
+  if (b.routes && b.routes.length) {
+    lines.push(`  routes     ${b.routes.join(", ")}`);
+  }
+  if (b.migration_path) {
+    lines.push(`  migration  ${b.migration_path}`);
+  }
+  const reserved = b.transformations.find((t) => t.kind === "reserved_word_pluralize");
+  if (reserved && reserved.from && reserved.override) {
+    lines.push("");
+    lines.push(`  To keep the raw name '${reserved.from}' as the table:`);
+    lines.push(`    tina4nodejs generate ${__resolution.target} ${__resolution.input.name} ${reserved.override}`);
+  }
+  lines.push("");
+  process.stderr.write(lines.join("\n"));
 }
 function toPlural(name) {
   const lower = name.toLowerCase();
@@ -45488,7 +45668,10 @@ function parseCliArgs(args) {
     "all",
     "clear",
     "public",
-    "no-migration"
+    "no-migration",
+    // Resolution transparency (Feature B, 3.13.117): both accept NO value.
+    "json",
+    "dry-run"
   ]);
   const flags = {};
   const positional = [];
@@ -45576,6 +45759,8 @@ async function generate2(what, name, extraArgs = []) {
     console.error('  Options:    --fields "name:string,price:float"  --model ModelName');
     console.error("              --public                 open a route's writes (default: secure)");
     console.error('              --every 5m | --cron "\u2026"   service schedule');
+    console.error("              --json                    emit machine-readable resolution envelope on stdout");
+    console.error("              --dry-run                 report resolution without writing any files");
     process.exit(1);
   }
   const noNameGenerators = /* @__PURE__ */ new Set(["auth"]);
@@ -45584,6 +45769,9 @@ async function generate2(what, name, extraArgs = []) {
     process.exit(1);
   }
   const { flags } = parseCliArgs(extraArgs);
+  const jsonMode = Boolean(flags.json);
+  const dryRun = Boolean(flags["dry-run"]);
+  resetResolution(what, { name, fields: flags.fields ?? null }, { dryRun, jsonMode });
   const spec = GENERATORS[what];
   if (spec) {
     spec.handler(name, flags);
@@ -45592,6 +45780,7 @@ async function generate2(what, name, extraArgs = []) {
     console.error(`  Available: ${GENERATOR_LIST}`);
     process.exit(1);
   }
+  printResolution();
 }
 function generateModel(name, flags, emitTest = true) {
   const fields = fieldsOrDefault(flags.fields || "");
@@ -45599,6 +45788,10 @@ function generateModel(name, flags, emitTest = true) {
   const dir = resolve28("src/models");
   ensureDir(dir);
   const path8 = join35(dir, `${name}.ts`);
+  setResolutionField("class_name", name);
+  setResolutionField("table_name", table2);
+  setResolutionField("file_path", `src/models/${name}.ts`);
+  pushTestPath(`tests/${table2}_model.test.ts`);
   const fieldLines = [
     `    id: { type: "integer" as const, primaryKey: true, autoIncrement: true },`
   ];
@@ -45636,6 +45829,11 @@ function generateRoute(name, flags, emitTest = true) {
   const idDir = join35(base, "[id]");
   ensureDir(base);
   ensureDir(idDir);
+  pushRoute(`/api/${routePath}`);
+  pushRoute(`/api/${routePath}/{id}`);
+  if (__resolution.target === "route") {
+    setResolutionField("file_path", `src/routes/api/${routePath}/get.ts`);
+  }
   const table2 = model ? toTableName(model) : "";
   const modelImportBase = model ? `import ${model} from "../../../models/${model}.js";
 ` : "";
@@ -45876,13 +46074,21 @@ function generateMigration(name, flags, fieldsOverride, tableOverride, emitTest
   if (tableOverride) {
     table2 = tableOverride;
   } else {
-    table2 = name.replace(/^create_/, "").replace(/^add_/, "").replace(/^drop_/, "");
-    table2 = toSnake(table2);
+    const raw = name.replace(/^create_/, "").replace(/^add_/, "").replace(/^drop_/, "");
+    table2 = toTableName(raw);
+  }
+  if (__resolution.target === "migration") {
+    setResolutionField("table_name", table2);
   }
   const fields = fieldsOverride || parseFields(flags.fields || "");
   const isCreate = name.startsWith("create_") || fieldsOverride !== void 0;
   const fileName = `${ts}_${name}.sql`;
   const path8 = join35(dir, fileName);
+  setResolutionField("migration_path", `migrations/${fileName}`);
+  if (__resolution.target === "migration") {
+    setResolutionField("file_path", `migrations/${fileName}`);
+    pushTestPath(`tests/${table2}_migration.test.ts`);
+  }
   let upSql;
   let downSql;
   if (isCreate) {
@@ -45928,6 +46134,11 @@ function generateMiddleware(name, _flags) {
   const dir = resolve28("src/middleware");
   ensureDir(dir);
   const path8 = join35(dir, `${snake}.ts`);
+  if (__resolution.target === "middleware") {
+    setResolutionField("class_name", name);
+    setResolutionField("file_path", `src/middleware/${snake}.ts`);
+    pushTestPath(`tests/${snake}.test.ts`);
+  }
   const content = `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 /**
@@ -46240,7 +46451,7 @@ export default async function (req: Tina4Request, res: Tina4Response) {
     return;
   }
 
-  const existing = await User.selectOne("SELECT * FROM user WHERE email = ?", [email]);
+  const existing = await User.selectOne("SELECT * FROM users WHERE email = ?", [email]);
   if (existing) {
     res.json({ error: "Email already registered" }, 409);
     return;
@@ -46271,7 +46482,7 @@ export default async function (req: Tina4Request, res: Tina4Response) {
     return;
   }
 
-  const user = await User.selectOne("SELECT * FROM user WHERE email = ?", [email]);
+  const user = await User.selectOne("SELECT * FROM users WHERE email = ?", [email]);
   if (!user || !checkPassword(password, user.toObject().password as string)) {
     res.json({ error: "Invalid credentials" }, 401);
     return;
@@ -47381,7 +47592,15 @@ function buildCommandManifest() {
     if (spec.args && spec.args.length) entry.args = [...spec.args];
     commands.push(entry);
   }
-  return { framework: "nodejs", version: readCliVersion(), commands };
+  return {
+    framework: "nodejs",
+    version: readCliVersion(),
+    commands,
+    // Feature B (3.13.117): declare the resolution envelope this framework
+    // emits for `generate <what> --json`. Consumers read this to know which
+    // schema to parse — never hard-code the shape.
+    resolution_contract: { version: "1", envelope: RESOLUTION_ENVELOPE_VERSION }
+  };
 }
 function runCommands(args = []) {
   const manifest = buildCommandManifest();

package/packages/cli/src/bin.ts

@@ -6,7 +6,7 @@ import { migrateStatus } from "./commands/migrateStatus.js";
 import { migrateRollback } from "./commands/migrateRollback.js";
 import { listRoutes } from "./commands/routes.js";
 import { runTests } from "./commands/test.js";
-import { generate, GENERATORS } from "./commands/generate.js";
+import { generate, GENERATORS, RESOLUTION_ENVELOPE_VERSION } from "./commands/generate.js";
 import { runSeeds } from "./commands/seed.js";
 import { queueCommand, QUEUE_SUBCOMMAND_NAMES } from "./commands/queue.js";
 import { buildImage } from "./commands/build.js";
@@ -85,10 +85,24 @@ export interface CommandManifestEntry {
   delegated?: boolean;
 }
 
+/**
+ * A stable, machine-readable pointer to the `generate` resolution envelope
+ * this framework speaks. Consumers (the tina4 client, an AI agent, a
+ * downstream tool) MUST NOT hard-code an envelope shape — instead they read
+ * `resolution_contract.envelope` from this manifest and follow its version.
+ * `version` bumps on any breaking key rename or removal; `envelope` is the
+ * name of the schema (currently `generate_v1`).
+ */
+export interface ResolutionContract {
+  version: string;
+  envelope: string;
+}
+
 export interface CommandManifest {
   framework: string;
   version: string;
   commands: CommandManifestEntry[];
+  resolution_contract: ResolutionContract;
 }
 
 /**
@@ -120,7 +134,15 @@ export function buildCommandManifest(): CommandManifest {
     if (spec.args && spec.args.length) entry.args = [...spec.args];
     commands.push(entry);
   }
-  return { framework: "nodejs", version: readCliVersion(), commands };
+  return {
+    framework: "nodejs",
+    version: readCliVersion(),
+    commands,
+    // Feature B (3.13.117): declare the resolution envelope this framework
+    // emits for `generate <what> --json`. Consumers read this to know which
+    // schema to parse — never hard-code the shape.
+    resolution_contract: { version: "1", envelope: RESOLUTION_ENVELOPE_VERSION },
+  };
 }
 
 /**

package/packages/cli/src/commands/generate.ts

@@ -55,18 +55,25 @@ const FIELD_TYPE_MAP: Record<string, { orm: string; sql: string; defaultVal: str
 // ── Helpers ─────────────────────────────────────────────────────────
 
 function ensureDir(dir: string): void {
+  if (__resolution.dryRun) return; // dry-run creates NO directories
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
 }
 
 function writeFileSafe(path: string, content: string): void {
+  if (__resolution.dryRun) {
+    // Dry-run: record what WOULD have been written, but touch no disk state
+    // and print no per-file line to stdout (that would leak into --json).
+    return;
+  }
   if (existsSync(path)) {
-    console.log(`  File already exists: ${path}`);
+    if (!__resolution.jsonMode) console.log(`  File already exists: ${path}`);
     return;
   }
   writeFileSync(path, content, "utf-8");
-  console.log(`  Created ${path}`);
+  __resolution.actionsTaken.push(`wrote ${path}`);
+  if (!__resolution.jsonMode) console.log(`  Created ${path}`);
 }
 
 export function toSnake(name: string): string {
@@ -76,8 +83,207 @@ export function toSnake(name: string): string {
     .toLowerCase();
 }
 
+// Table names that collide with SQL reserved words. `CREATE TABLE order (...)`
+// is a syntax error on every engine, and the ORM interpolates table names into
+// SQL unquoted (and hands the raw name to driver insert/update/delete), so the
+// safe fix is to never GENERATE one. The plural form is not reserved and reads
+// naturally as a table name. Mirrors the Python master's SQL_RESERVED_TABLE_NAMES
+// at tina4-python/tina4_python/cli/__init__.py.
+export const SQL_RESERVED_TABLE_NAMES: ReadonlySet<string> = new Set([
+  "order", "group", "user", "table", "select", "from", "where", "index",
+  "key", "values", "column", "constraint", "check", "default", "primary",
+  "foreign", "references", "unique", "join", "union", "having", "limit",
+  "offset", "desc", "asc", "case", "when", "then", "else", "end", "and",
+  "or", "not", "null", "insert", "update", "delete", "create", "drop",
+  "alter", "grant", "revoke", "commit", "rollback", "view", "trigger",
+  "procedure", "function", "database", "schema", "session", "set", "into",
+  "as", "on", "by", "inner", "outer", "left", "right", "full", "natural",
+  "using", "with", "distinct", "between", "exists", "like", "in", "is",
+  "all", "any", "cross", "add", "row", "rows", "range", "current", "to",
+]);
+
+/** Simple English plural, used to escape a reserved-word table name. */
+export function pluralizeReserved(name: string): string {
+  if (name.endsWith("y") && !/[aeiouy]y$/i.test(name)) return name.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/.test(name)) return name + "es";
+  return name + "s";
+}
+
+/**
+ * Class name -> table name (singular by default), with a resolution side effect:
+ * a name that collides with a SQL reserved word is pluralised (Order -> orders)
+ * AND recorded on the current run's resolution as a `reserved_word_pluralize`
+ * transformation. Every generator routes through here so the model, migration,
+ * routes and tests all agree on the same table name.
+ */
 export function toTableName(name: string): string {
-  return toSnake(name);
+  const raw = toSnake(name);
+  if (SQL_RESERVED_TABLE_NAMES.has(raw)) {
+    const safe = pluralizeReserved(raw);
+    recordTransformation({
+      kind: "reserved_word_pluralize",
+      from: raw,
+      to: safe,
+      reason: `SQL reserved word '${raw}' would break CREATE TABLE`,
+      override: `--table ${raw} --quote (requires quoted-identifier mode, not yet implemented)`,
+    });
+    return safe;
+  }
+  return raw;
+}
+
+// ── Resolution surface — the machine-readable envelope every generator ─
+// populates so `--json` can print it and a human run can print the same
+// facts to stderr. See the JSDoc on `printResolution` below for the envelope
+// shape (kept stable under `resolution_contract` in `commands --json`).
+
+/** One transformation the resolver made — visible to the caller so an AI
+ * agent (or human) knows exactly why the output differs from the input. */
+export interface ResolutionTransformation {
+  kind: string;
+  from?: string;
+  to?: string;
+  reason?: string;
+  override?: string;
+}
+
+export interface ResolutionInput {
+  name: string;
+  fields: string | null;
+}
+
+export interface ResolutionBody {
+  class_name?: string;
+  table_name?: string;
+  file_path?: string;
+  migration_path?: string;
+  routes?: string[];
+  test_paths?: string[];
+  transformations: ResolutionTransformation[];
+}
+
+export interface ResolutionEnvelope {
+  command: "generate";
+  target: string;
+  input: ResolutionInput;
+  resolution: ResolutionBody;
+  actions_taken: string[];
+  dry_run: boolean;
+}
+
+/**
+ * A stable version tag on the JSON envelope. `commands --json` echoes this in
+ * `resolution_contract.envelope` so the tina4 client (or any consumer) can
+ * discover the exact contract this framework speaks. Bump when a breaking
+ * key rename / removal lands; keep unchanged when new OPTIONAL keys are added.
+ */
+export const RESOLUTION_ENVELOPE_VERSION = "generate_v1";
+
+/**
+ * Per-run mutable resolution state. Reset by `resetResolution()` on every
+ * top-level `generate()` call so a sub-generator (crud -> model + route +
+ * migration + form + view + test) contributes to ONE envelope, not many.
+ */
+const __resolution: {
+  target: string;
+  input: ResolutionInput;
+  body: ResolutionBody;
+  actionsTaken: string[];
+  dryRun: boolean;
+  jsonMode: boolean;
+} = {
+  target: "",
+  input: { name: "", fields: null },
+  body: { transformations: [] },
+  actionsTaken: [],
+  dryRun: false,
+  jsonMode: false,
+};
+
+function resetResolution(target: string, input: ResolutionInput, opts: { dryRun: boolean; jsonMode: boolean }): void {
+  __resolution.target = target;
+  __resolution.input = input;
+  __resolution.body = { transformations: [] };
+  __resolution.actionsTaken = [];
+  __resolution.dryRun = opts.dryRun;
+  __resolution.jsonMode = opts.jsonMode;
+}
+
+function recordTransformation(t: ResolutionTransformation): void {
+  __resolution.body.transformations.push(t);
+}
+
+/** Read-only snapshot of the current resolution — exported for tests that
+ * want to inspect it in-process (the CLI itself uses only the envelope). */
+export function currentResolution(): ResolutionEnvelope {
+  return {
+    command: "generate",
+    target: __resolution.target,
+    input: { ...__resolution.input },
+    resolution: {
+      ...__resolution.body,
+      transformations: [...__resolution.body.transformations],
+    },
+    actions_taken: [...__resolution.actionsTaken],
+    dry_run: __resolution.dryRun,
+  };
+}
+
+function setResolutionField<K extends keyof ResolutionBody>(key: K, value: ResolutionBody[K]): void {
+  __resolution.body[key] = value;
+}
+
+function pushRoute(routePattern: string): void {
+  if (!__resolution.body.routes) __resolution.body.routes = [];
+  __resolution.body.routes.push(routePattern);
+}
+
+function pushTestPath(path: string): void {
+  if (!__resolution.body.test_paths) __resolution.body.test_paths = [];
+  __resolution.body.test_paths.push(path);
+}
+
+/**
+ * Emit the resolution — as JSON on STDOUT for `--json`, otherwise as a human
+ * block on STDERR (stderr so a caller piping stdout for other output isn't
+ * polluted). Called from `generate()` BEFORE the files are written on the
+ * human path so an operator sees WHY the tool made its choices before disk
+ * changes; the JSON path prints after collection so the envelope carries the
+ * completed `actions_taken`.
+ */
+function printResolution(): void {
+  if (__resolution.jsonMode) {
+    process.stdout.write(JSON.stringify(currentResolution(), null, 2) + "\n");
+    return;
+  }
+  // Human block on STDERR, so `command | jq …` on stdout works cleanly.
+  const b = __resolution.body;
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(`Generated ${__resolution.target} ${__resolution.input.name}`);
+  if (b.class_name || b.file_path) {
+    const where = b.file_path ? `  (in ${b.file_path})` : "";
+    lines.push(`  class      ${b.class_name ?? __resolution.input.name}${where}`);
+  }
+  if (b.table_name) {
+    const t = b.transformations.find((x) => x.kind === "reserved_word_pluralize");
+    const note = t ? `  (auto-pluralized: '${t.from}' is a SQL reserved word)` : "";
+    lines.push(`  table      ${b.table_name}${note}`);
+  }
+  if (b.routes && b.routes.length) {
+    lines.push(`  routes     ${b.routes.join(", ")}`);
+  }
+  if (b.migration_path) {
+    lines.push(`  migration  ${b.migration_path}`);
+  }
+  const reserved = b.transformations.find((t) => t.kind === "reserved_word_pluralize");
+  if (reserved && reserved.from && reserved.override) {
+    lines.push("");
+    lines.push(`  To keep the raw name '${reserved.from}' as the table:`);
+    lines.push(`    tina4nodejs generate ${__resolution.target} ${__resolution.input.name} ${reserved.override}`);
+  }
+  lines.push("");
+  process.stderr.write(lines.join("\n"));
 }
 
 function toPlural(name: string): string {
@@ -135,6 +341,8 @@ export function parseCliArgs(args: string[]): { flags: Record<string, string | b
   const booleanFlags = new Set([
     "no-browser", "no-reload", "production", "managed", "all", "clear",
     "public", "no-migration",
+    // Resolution transparency (Feature B, 3.13.117): both accept NO value.
+    "json", "dry-run",
   ]);
 
   const flags: Record<string, string | boolean> = {};
@@ -278,6 +486,8 @@ export async function generate(what: string, name: string, extraArgs: string[] =
     console.error('  Options:    --fields "name:string,price:float"  --model ModelName');
     console.error("              --public                 open a route's writes (default: secure)");
     console.error('              --every 5m | --cron "…"   service schedule');
+    console.error("              --json                    emit machine-readable resolution envelope on stdout");
+    console.error("              --dry-run                 report resolution without writing any files");
     process.exit(1);
   }
 
@@ -290,6 +500,15 @@ export async function generate(what: string, name: string, extraArgs: string[] =
 
   const { flags } = parseCliArgs(extraArgs);
 
+  // Feature B (3.13.117): resolution transparency. `--json` emits a stable
+  // envelope on STDOUT (see `RESOLUTION_ENVELOPE_VERSION` / `commands --json`
+  // -> `resolution_contract`); the human path prints the same facts to STDERR.
+  // `--dry-run` short-circuits every file write so an agent can preview the
+  // resolution and then rerun without the flag to commit.
+  const jsonMode = Boolean(flags.json);
+  const dryRun = Boolean(flags["dry-run"]);
+  resetResolution(what, { name, fields: (flags.fields as string) ?? null }, { dryRun, jsonMode });
+
   // Dispatch from the single-source-of-truth GENERATORS registry (also feeds
   // `bin.ts` help + the `commands --json` manifest subcommands).
   const spec = GENERATORS[what];
@@ -300,6 +519,10 @@ export async function generate(what: string, name: string, extraArgs: string[] =
     console.error(`  Available: ${GENERATOR_LIST}`);
     process.exit(1);
   }
+
+  // Emit the resolution AFTER dispatch so `actions_taken` reflects the real
+  // writes (or the empty list under `--dry-run`).
+  printResolution();
 }
 
 // ── Model ───────────────────────────────────────────────────────────
@@ -311,6 +534,18 @@ function generateModel(name: string, flags: Record<string, string | boolean>, em
   ensureDir(dir);
   const path = join(dir, `${name}.ts`);
 
+  // Populate the resolution — the top-level `generate()` prints this AFTER
+  // dispatch (as JSON on stdout for `--json`, or as a human block on stderr).
+  // Fields set here are relative paths (portable across cwd) — path.resolve
+  // above uses cwd, then we express the file path relative to it for the
+  // envelope, matching the Python master's `src/models/Order.ts` string.
+  setResolutionField("class_name", name);
+  setResolutionField("table_name", table);
+  setResolutionField("file_path", `src/models/${name}.ts`);
+  // Matches the real path emitted by emitModelTest() so the envelope never
+  // lies about where a generated test lands.
+  pushTestPath(`tests/${table}_model.test.ts`);
+
   // Build field definitions
   const fieldLines: string[] = [
     `    id: { type: "integer" as const, primaryKey: true, autoIncrement: true },`,
@@ -373,6 +608,15 @@ function generateRoute(name: string, flags: Record<string, string | boolean>, em
   ensureDir(base);
   ensureDir(idDir);
 
+  // Populate the resolution — routes AND file paths always safe to add; only
+  // set the primary file_path when THIS is the top-level target so a `generate
+  // model` running us as a sub-step doesn't overwrite the model's file_path.
+  pushRoute(`/api/${routePath}`);
+  pushRoute(`/api/${routePath}/{id}`);
+  if (__resolution.target === "route") {
+    setResolutionField("file_path", `src/routes/api/${routePath}/get.ts`);
+  }
+
   const table = model ? toTableName(model) : "";
   // Model import path is RELATIVE to the route file's directory. Files directly
   // under src/routes/api/<name>/ are 3 levels above src/models/; the [id]/ files
@@ -649,16 +893,30 @@ function generateMigration(
   const dir = resolve("migrations");
   ensureDir(dir);
 
-  // Determine table name
+  // Determine table name. When called from `generateModel` (tableOverride set),
+  // the model already ran toTableName() and recorded any reserved-word
+  // pluralisation — reuse that resolved name so the two files agree. When
+  // called directly (`generate migration create_order`), strip the prefix and
+  // route through toTableName() so a reserved word is caught HERE too.
   let table: string;
   if (tableOverride) {
     table = tableOverride;
   } else {
-    table = name
+    const raw = name
       .replace(/^create_/, "")
       .replace(/^add_/, "")
       .replace(/^drop_/, "");
-    table = toSnake(table);
+    // toTableName also records a `reserved_word_pluralize` transformation
+    // on the resolution when the raw form collides with a SQL reserved word.
+    table = toTableName(raw);
+  }
+  // Only set table_name / migration_path when THIS is the top-level target.
+  // A migration produced by generateModel is a side effect of `generate model`,
+  // and the model already populated `table_name` / `file_path` for that
+  // resolution — overwriting them here would lie about what the caller asked
+  // for. `migration_path` is always safe to record either way.
+  if (__resolution.target === "migration") {
+    setResolutionField("table_name", table);
   }
 
   // Build SQL columns from fields
@@ -667,6 +925,15 @@ function generateMigration(
 
   const fileName = `${ts}_${name}.sql`;
   const path = join(dir, fileName);
+  // Record on the resolution — always safe (a `generate model` run overwrites
+  // this with each nested migration; the last write wins, which is the one
+  // the operator actually gets on disk).
+  setResolutionField("migration_path", `migrations/${fileName}`);
+  if (__resolution.target === "migration") {
+    setResolutionField("file_path", `migrations/${fileName}`);
+    // Matches emitMigrationTest's real write path.
+    pushTestPath(`tests/${table}_migration.test.ts`);
+  }
 
   let upSql: string;
   let downSql: string;
@@ -719,6 +986,14 @@ function generateMiddleware(name: string, _flags: Record<string, string | boolea
   ensureDir(dir);
   const path = join(dir, `${snake}.ts`);
 
+  // Populate the resolution for --json/--dry-run visibility.
+  if (__resolution.target === "middleware") {
+    setResolutionField("class_name", name);
+    setResolutionField("file_path", `src/middleware/${snake}.ts`);
+    // Matches emitMiddlewareTest's real write path.
+    pushTestPath(`tests/${snake}.test.ts`);
+  }
+
   const content = `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
 
 /**
@@ -1084,7 +1359,7 @@ export default async function (req: Tina4Request, res: Tina4Response) {
     return;
   }
 
-  const existing = await User.selectOne("SELECT * FROM user WHERE email = ?", [email]);
+  const existing = await User.selectOne("SELECT * FROM users WHERE email = ?", [email]);
   if (existing) {
     res.json({ error: "Email already registered" }, 409);
     return;
@@ -1117,7 +1392,7 @@ export default async function (req: Tina4Request, res: Tina4Response) {
     return;
   }
 
-  const user = await User.selectOne("SELECT * FROM user WHERE email = ?", [email]);
+  const user = await User.selectOne("SELECT * FROM users WHERE email = ?", [email]);
   if (!user || !checkPassword(password, user.toObject().password as string)) {
     res.json({ error: "Invalid credentials" }, 401);
     return;

package/packages/core/dist/_missing.js

@@ -0,0 +1,20 @@
+// src/_missing.ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+function realSubpaths() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = join(here, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  const pkgName2 = pkg.name ?? "@tina4/core";
+  const exportsMap = pkg.exports ?? {};
+  const subpaths2 = [];
+  for (const key of Object.keys(exportsMap)) {
+    if (key === "." || key === "./*") continue;
+    subpaths2.push(key.startsWith("./") ? key.slice(2) : key);
+  }
+  return { pkgName: pkgName2, subpaths: subpaths2 };
+}
+var { pkgName, subpaths } = realSubpaths();
+var message = `${pkgName}: no such subpath. Real subpaths: ${subpaths.join(", ")}. (Node's wildcard resolver can't see the original request, so this message lists every real subpath rather than pointing at the closest match \u2014 see ADR-0062.)`;
+throw new Error(message);

package/packages/core/src/_missing.ts

@@ -0,0 +1,67 @@
+/**
+ * Last-resort finder for `@tina4/core/<subpath>` under Node's ESM resolver.
+ *
+ * The `exports` map registers `"./*": "./dist/_missing.js"` as the LAST entry.
+ * Any subpath that no earlier entry matched (a typo, a guess, an ORM name
+ * imported from the core entry, etc.) lands here at import time and throws a
+ * helpful Error that names every REAL subpath — parsed at throw time from the
+ * OWN package.json's `exports` map so the message can never drift from what's
+ * actually exported.
+ *
+ * NODE PARITY GAP (accepted, ADR-0062).
+ *
+ * Node's wildcard resolver invokes this file with the RESOLVED target path,
+ * not the ORIGINAL requested subpath — so we cannot know what the caller
+ * typed. Python / PHP / Ruby's finders receive the raw request and can point
+ * at the closest match ("did you mean `router`?"). Node's message is
+ * necessarily generic: it lists ALL real subpaths as a browsable set. For an
+ * AI-agent consumer (or a human agent), the browsable list is enough to make
+ * the correct next call; the asymmetry is called out here so nobody wonders
+ * why Node's message lacks the pointed "did you mean" line.
+ *
+ * The module SIDE-EFFECT throws — importing this file is enough to raise,
+ * whether the caller does a bare-`import` or a named-`import { X }`. That is
+ * what routes the wildcard's fallback through this file: Node evaluates the
+ * module body BEFORE resolving named bindings.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+/**
+ * Read the OWN package.json (walking up from this file's URL) and return the
+ * real subpaths — everything in `exports` except `.` (the root) and the
+ * wildcard `./*` itself. Order matches the declaration in package.json, which
+ * is the order a maintainer curated for discoverability.
+ */
+function realSubpaths(): { pkgName: string; subpaths: string[] } {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // dist/ (or src/ under tsx) → package root is one level up
+  const pkgPath = join(here, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+    name?: string;
+    exports?: Record<string, unknown>;
+  };
+  const pkgName = pkg.name ?? "@tina4/core";
+  const exportsMap = pkg.exports ?? {};
+  const subpaths: string[] = [];
+  for (const key of Object.keys(exportsMap)) {
+    if (key === "." || key === "./*") continue;
+    // Strip the leading "./" so a caller sees "router" not "./router"
+    subpaths.push(key.startsWith("./") ? key.slice(2) : key);
+  }
+  return { pkgName, subpaths };
+}
+
+const { pkgName, subpaths } = realSubpaths();
+
+// The message shape matches the Python / PHP / Ruby import-hint format so an
+// AI-agent consumer that switches languages sees a recognisable string.
+const message =
+  `${pkgName}: no such subpath. ` +
+  `Real subpaths: ${subpaths.join(", ")}. ` +
+  `(Node's wildcard resolver can't see the original request, so this message ` +
+  `lists every real subpath rather than pointing at the closest match — ` +
+  `see ADR-0062.)`;
+
+throw new Error(message);

package/types/cli/src/bin.d.ts

@@ -6,10 +6,23 @@ export interface CommandManifestEntry {
     /** True when the tina4 client implements this command, not the framework. */
     delegated?: boolean;
 }
+/**
+ * A stable, machine-readable pointer to the `generate` resolution envelope
+ * this framework speaks. Consumers (the tina4 client, an AI agent, a
+ * downstream tool) MUST NOT hard-code an envelope shape — instead they read
+ * `resolution_contract.envelope` from this manifest and follow its version.
+ * `version` bumps on any breaking key rename or removal; `envelope` is the
+ * name of the schema (currently `generate_v1`).
+ */
+export interface ResolutionContract {
+    version: string;
+    envelope: string;
+}
 export interface CommandManifest {
     framework: string;
     version: string;
     commands: CommandManifestEntry[];
+    resolution_contract: ResolutionContract;
 }
 /**
  * Build the machine-readable manifest of the CLI's command surface.

package/types/cli/src/commands/generate.d.ts

@@ -1,5 +1,55 @@
 export declare function toSnake(name: string): string;
+export declare const SQL_RESERVED_TABLE_NAMES: ReadonlySet<string>;
+/** Simple English plural, used to escape a reserved-word table name. */
+export declare function pluralizeReserved(name: string): string;
+/**
+ * Class name -> table name (singular by default), with a resolution side effect:
+ * a name that collides with a SQL reserved word is pluralised (Order -> orders)
+ * AND recorded on the current run's resolution as a `reserved_word_pluralize`
+ * transformation. Every generator routes through here so the model, migration,
+ * routes and tests all agree on the same table name.
+ */
 export declare function toTableName(name: string): string;
+/** One transformation the resolver made — visible to the caller so an AI
+ * agent (or human) knows exactly why the output differs from the input. */
+export interface ResolutionTransformation {
+    kind: string;
+    from?: string;
+    to?: string;
+    reason?: string;
+    override?: string;
+}
+export interface ResolutionInput {
+    name: string;
+    fields: string | null;
+}
+export interface ResolutionBody {
+    class_name?: string;
+    table_name?: string;
+    file_path?: string;
+    migration_path?: string;
+    routes?: string[];
+    test_paths?: string[];
+    transformations: ResolutionTransformation[];
+}
+export interface ResolutionEnvelope {
+    command: "generate";
+    target: string;
+    input: ResolutionInput;
+    resolution: ResolutionBody;
+    actions_taken: string[];
+    dry_run: boolean;
+}
+/**
+ * A stable version tag on the JSON envelope. `commands --json` echoes this in
+ * `resolution_contract.envelope` so the tina4 client (or any consumer) can
+ * discover the exact contract this framework speaks. Bump when a breaking
+ * key rename / removal lands; keep unchanged when new OPTIONAL keys are added.
+ */
+export declare const RESOLUTION_ENVELOPE_VERSION = "generate_v1";
+/** Read-only snapshot of the current resolution — exported for tests that
+ * want to inspect it in-process (the CLI itself uses only the envelope). */
+export declare function currentResolution(): ResolutionEnvelope;
 /** slug-of-anything → PascalCase (order-emails → OrderEmails). */
 export declare function toPascal(name: string): string;
 export declare function parseFields(fieldsStr: string): Array<[string, string]>;

package/types/core/src/_missing.d.ts

@@ -0,0 +1 @@
+export {};