@ismaelsoilet/synapsejs 1.8.0 → 1.9.0

package/src/compiler/contract.ts

@@ -11,6 +11,8 @@
  * discovery and the splitter use, so the description cannot drift from behavior.
  */
 
+import { PATH_SEGMENT_PATTERN } from '../core/path-guard';
+import { REALTIME_REJECTIONS } from '../core/topics';
 import {
   ACTION_SUFFIX,
   COMPONENT_SUFFIXES,
@@ -18,6 +20,7 @@ import {
   SLICE_DDL_EXPORT,
   SLICE_ORACLE_EXPORT
 } from '../runtime/discovery-rules';
+import { SCAFFOLD_FAILURE_CODES } from './scaffolder';
 import { SLICE_EXTENSION } from './slice-discovery';
 import { SLICE_TEMPLATES } from './slice-templates';
 
@@ -49,6 +52,7 @@ export interface MachineContract {
     signed: string;
     anonymous: string;
     login: string;
+    cookieReality: string;
   };
   addressing: {
     page: string;
@@ -71,6 +75,16 @@ export interface MachineContract {
     available: string[];
     notes: string;
   };
+  scaffolding: {
+    command: string;
+    containment: string;
+    failureCodes: Record<string, string>;
+  };
+  realtime: {
+    transports: string[];
+    rule: string;
+    rejections: Record<string, number>;
+  };
   gates: Array<{ command: string; proves: string }>;
 }
 
@@ -187,16 +201,18 @@ export function machineContract(): MachineContract {
     sessions: {
       headers: ['Authorization: Bearer <token>', 'x-user-id', 'x-user-roles'],
       signed:
-        'With SYNAPSE_SESSION_SECRET set, a bearer token must be a signed session (signSessionToken) and its claims win: role headers are ignored.',
+        'With SYNAPSE_SESSION_SECRET set, a bearer token must be a signed session (signSessionToken) and its claims win: role headers are ignored, and the tenant is taken exclusively from the verified claims (a signed token without a tenant claim yields a session without a tenant). Revocation is consulted on every request, in-process first and then against the persisted blacklist. Without the secret, identity headers are honoured only under the explicit development opt-in SYNAPSE_DEV_HEADERS=true (or a development/test runtime mode); every other state resolves to an anonymous session.',
       anonymous: 'A request with none of them is anonymous: requireAuth returns Err("UNAUTHORIZED").',
       login:
-        'There is no built-in login screen and no server-side session state. A login slice (synapse new-slice auth login --template=login) verifies the password with Bun.password.verify, signs the session with signSessionToken and returns the token; the browser stores it with storeSession(token, roles) and logs out with clearSession(). After that the token travels as Authorization: Bearer and the server authorizes from the signature.'
+        'There is no built-in login screen and no server-side session state. A login slice (synapse new-slice auth login --template=login) verifies the password with Bun.password.verify, signs the session with signSessionToken and returns the token; the browser stores it with storeSession(token, roles) and logs out with clearSession(). After that the token travels as Authorization: Bearer and the server authorizes from the signature.',
+      cookieReality:
+        'A session cookie written by browser script (storeSession) is written through document.cookie, so it is readable by any script in the origin — HttpOnly cannot be set from script, by construction. A session that must be unreachable by script is the one the server emits through ctx.setCookie, which carries HttpOnly, Secure and SameSite=Lax unless the caller states otherwise.'
     },
     addressing: {
       page: 'GET /<domain>/<name>',
       rpc: 'POST /_synapse/rpc/<domain>/<name> with Content-Type: application/json',
       upload:
-        'POST /_synapse/files/<domain>/<name>?name=arquivo.pdf sends raw bytes (multipart is not needed and not parsed). It requires a session, refuses a name containing a directory, and stops reading past SYNAPSE_MAX_UPLOAD_BYTES (5 MiB by default). It answers { ok, path, bytes } with a path relative to the app root; what the bytes mean is the slice contract to decide.',
+        "POST /_synapse/files/<domain>/<name>?name=arquivo.pdf sends raw bytes or multipart/form-data. It requires a session, refuses a name containing a directory, enforces a byte ceiling while the bytes arrive on every branch (SYNAPSE_MAX_UPLOAD_BYTES, 5 MiB by default), and accepts a file only when its declared extension is within the configured policy (SYNAPSE_UPLOAD_ALLOWED_TYPES) and matches the bytes actually received — so a client cannot choose the extension its file is stored under. It answers { ok, path, bytes } with a path relative to the app root. The framework does not serve the upload directory: serving it is the application's responsibility.",
       ambiguity:
         'A bare name resolves only while it is unique across domains; otherwise the dispatcher answers 409 listing the candidates.'
     },
@@ -211,7 +227,7 @@ export function machineContract(): MachineContract {
       location: 'src/shared/<name>.ts',
       rule: 'A slice never imports another slice — the splitter fails with SLICE_IMPORTS_SLICE, transitively, and says so. What two features must do together lives in src/shared/, receives the DatabaseClient by parameter and is called from both slices. A shared module may throw; the action that calls it converts the failure into Err, so the no-throw contract of an action survives a transaction.',
       atomicity:
-        'db.transaction(fn) is the boundary: the statements inside commit together or roll back together. The mock database does not roll back, so atomicity must be proven against a real engine (SQLite in the suite, PostgreSQL via test:postgres) — never with the mock.'
+        'db.transaction(fn) is the boundary: the statements inside commit together or roll back together. The mock database rolls back its in-memory store, which makes it usable for control-flow assertions, but atomicity against a real engine (SQLite in the suite, PostgreSQL via test:postgres) is what proves the engine agrees.'
     },
     templates: {
       command: 'synapse new-slice <domain> <name> --template=<template>',
@@ -219,6 +235,17 @@ export function machineContract(): MachineContract {
       notes:
         'create is the default. crud generates create-<name>, list-<name>, update-<name> and delete-<name> for one resource. list paginates (LIMIT/OFFSET plus COUNT) with a parameterized filter; update is partial and builds its SET clause from a column allowlist, never from the payload; delete checks existence first. Every generated file already carries an oracle.'
     },
+    realtime: {
+      transports: ['GET /_synapse/sse/<topic> (event stream)', 'GET /_synapse/ws/<domain>/<name> (WebSocket upgrade)'],
+      rule: 'A topic must be declared with defineTopic({ name, owner, readRoles?, tenantId?, public? }) before anyone subscribes or publishes. Subscribing to an undeclared topic is refused; a topic declared only for another tenant is refused without disclosing that it exists; publishing into a topic the slice does not own is rejected and notifies nobody. Topics are namespaced per tenant. The WebSocket upgrade is refused unless the request carries a present origin matching SYNAPSE_ALLOWED_ORIGINS (or `*`), with a loopback-origin carve-out for local development. Both transports share one rate limiter and a per-client cap on concurrent connections.',
+      rejections: { ...REALTIME_REJECTIONS }
+    },
+    scaffolding: {
+      command:
+        'synapse new-slice <domain> <name> [--template=<template>] [--fields=<grammar>] · synapse new-shared <name> · synapse new <project>',
+      containment: `The domain, the slice name, the shared-module name and the new-project directory are each one safe path segment (pattern ${PATH_SEGMENT_PATTERN}), and before anything is written the resolved target is asserted to stay inside the directory the operation owns. A field name in --fields must be a plain identifier before it is interpolated into the generated DDL or TypeScript. Every containment failure is printed as JSON on standard output with a non-zero exit code.`,
+      failureCodes: { ...SCAFFOLD_FAILURE_CODES }
+    },
     gates: [
       {
         command: 'synapse check [arquivo]',

package/src/compiler/db-schema-generator.ts

@@ -129,20 +129,50 @@ function splitColumnDefinitions(body: string): string[] {
   return defs;
 }
 
+/** Index of the `)` matching the `(` at `openIndex`, or -1. Linear in the input. */
+function findMatchingParen(text: string, openIndex: number): number {
+  let depth = 0;
+
+  for (let index = openIndex; index < text.length; index++) {
+    const char = text[index];
+
+    if (char === '(') {
+      depth++;
+    } else if (char === ')') {
+      depth--;
+
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  return -1;
+}
+
 /**
  * Parses DDL string to extract all table and column definitions.
+ *
+ * The header is matched first and the column body is delimited by scanning for the
+ * matching parenthesis. The previous single-pattern form (`([\s\S]*?)\)(?:\s*;|\s*$)`)
+ * backtracked quadratically on a large DDL.
  */
 export function parseDdlToCatalog(ddl: string, sourceSlice?: string): TableDefinition[] {
   const tables: TableDefinition[] = [];
+  const createTableHeader = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?([a-zA-Z0-9_]+)["'`]?\s*\(/gi;
+
+  let header: RegExpExecArray | null = createTableHeader.exec(ddl);
 
-  // Match CREATE TABLE [IF NOT EXISTS] <name> (<columns>)
-  const createTableRegex =
-    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?([a-zA-Z0-9_]+)["'`]?\s*\(([\s\S]*?)\)(?:\s*;|\s*$)/gi;
+  while (header !== null) {
+    const openParen = header.index + header[0].length - 1;
+    const closeParen = findMatchingParen(ddl, openParen);
+
+    if (closeParen === -1) {
+      break;
+    }
 
-  let match: RegExpExecArray | null = createTableRegex.exec(ddl);
-  while (match !== null) {
-    const tableName = match[1].toLowerCase();
-    const body = match[2];
+    const tableName = header[1].toLowerCase();
+    const body = ddl.slice(openParen + 1, closeParen);
     const rawDefs = splitColumnDefinitions(body);
     const columns: ColumnDefinition[] = [];
 
@@ -202,7 +232,8 @@ export function parseDdlToCatalog(ddl: string, sourceSlice?: string): TableDefin
       sourceSlice
     });
 
-    match = createTableRegex.exec(ddl);
+    createTableHeader.lastIndex = closeParen + 1;
+    header = createTableHeader.exec(ddl);
   }
 
   return tables;

package/src/compiler/fields-parser.ts

@@ -6,6 +6,8 @@
  * DataForm/DataTable specs, and Fast-Check PBT test arbitraries.
  */
 
+import { Err, Ok, type Result } from '../core/machine-types';
+
 export type FieldType = 'string' | 'number' | 'integer' | 'boolean' | 'enum' | 'date' | 'timestamp' | 'json';
 
 export interface ParsedField {
@@ -17,6 +19,32 @@ export interface ParsedField {
   label: string;
 }
 
+/**
+ * Field and enum-value names are interpolated into generated DDL and generated
+ * TypeScript, so they must be plain identifiers before any code generation runs.
+ */
+const FIELD_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Validates every field name (and enum value) in a parsed field list.
+ * Returns the first offending name as the error value.
+ */
+export function validateFieldNames(fields: ParsedField[]): Result<ParsedField[], string> {
+  for (const field of fields) {
+    if (!FIELD_NAME_PATTERN.test(field.name)) {
+      return Err(field.name);
+    }
+
+    for (const value of field.enumValues ?? []) {
+      if (!FIELD_NAME_PATTERN.test(value)) {
+        return Err(value);
+      }
+    }
+  }
+
+  return Ok(fields);
+}
+
 function fieldToLabel(name: string): string {
   return name
     .replace(/_/g, ' ')
@@ -173,7 +201,6 @@ export function generateSqlColumns(fields: ParsedField[]): string {
       case 'json':
       case 'string':
       case 'enum':
-      default:
         sqlType = 'TEXT';
         break;
     }

package/src/compiler/impact-analyzer.ts

@@ -24,7 +24,10 @@ export interface ImpactedSlice {
 }
 
 export interface ImpactAnalysisReport {
-  status: 'PASS';
+  status: 'PASS' | 'FAIL';
+  /** Present only when the target could not be resolved in this project. */
+  code?: 'TARGET_NOT_RESOLVED';
+  message?: string;
   operation: 'IMPACT_ANALYSIS';
   target: string;
   targetType: 'slice' | 'table' | 'shared_module';
@@ -156,6 +159,8 @@ export function analyzeImpact(target: string, rootDir: string = process.cwd()):
 
   const impactedMap = new Map<string, ImpactedSlice>();
 
+  let resolved = false;
+
   if (targetType === 'slice') {
     const targetSlice = sliceDataList.find(
       (s) =>
@@ -164,6 +169,8 @@ export function analyzeImpact(target: string, rootDir: string = process.cwd()):
         s.filePath.endsWith(`/${cleanTarget}`)
     );
 
+    resolved = Boolean(targetSlice);
+
     if (targetSlice) {
       impactedMap.set(targetSlice.sliceName, {
         sliceName: targetSlice.sliceName,
@@ -208,6 +215,10 @@ export function analyzeImpact(target: string, rootDir: string = process.cwd()):
   } else if (targetType === 'shared_module') {
     const sharedName = path.basename(cleanTarget, path.extname(cleanTarget));
 
+    resolved =
+      fs.existsSync(path.resolve(rootDir, cleanTarget)) ||
+      fs.existsSync(path.join(rootDir, 'src', 'shared', `${sharedName}.ts`));
+
     for (const slice of sliceDataList) {
       if (slice.sharedImports.includes(sharedName)) {
         impactedMap.set(slice.sliceName, {
@@ -223,6 +234,9 @@ export function analyzeImpact(target: string, rootDir: string = process.cwd()):
     // targetType === 'table'
     const tableName = cleanTarget.toLowerCase();
 
+    // A table exists in this project when some committed slice declares it.
+    resolved = sliceDataList.some((slice) => slice.tablesCreated.includes(tableName));
+
     for (const slice of sliceDataList) {
       if (slice.tablesCreated.includes(tableName)) {
         impactedMap.set(slice.sliceName, {
@@ -267,6 +281,22 @@ export function analyzeImpact(target: string, rootDir: string = process.cwd()):
     recommendedCommands.push('synapse test');
   }
 
+  if (!resolved) {
+    // An unresolvable target is a failure, not a successful empty result. Nothing
+    // was verified, so reporting PASS would be the same defect discovery refuses.
+    return {
+      status: 'FAIL',
+      code: 'TARGET_NOT_RESOLVED',
+      message: `Alvo '${cleanTarget}' não existe no projeto: nenhuma fatia, módulo compartilhado ou tabela corresponde.`,
+      operation: 'IMPACT_ANALYSIS',
+      target: cleanTarget,
+      targetType,
+      totalImpacted: 0,
+      impactedSlices: [],
+      recommendedCommands: []
+    };
+  }
+
   return {
     status: 'PASS',
     operation: 'IMPACT_ANALYSIS',

package/src/compiler/migration-runner.ts

@@ -385,9 +385,15 @@ export function extractSliceSchema(sourceFile: ts.SourceFile): string | null {
   return ddl;
 }
 
+export interface RunMigrationsOptions {
+  /** Consult the Jev abort gate after a failure (default: disabled). */
+  enableJevGate?: boolean;
+}
+
 export async function runSliceMigrations(
   baseDir: string = process.cwd(),
-  customDb?: DatabaseClient
+  customDb?: DatabaseClient,
+  options: RunMigrationsOptions = {}
 ): Promise<MigrationReport> {
   const db = customDb || getDatabase();
   const isPostgres = db instanceof PostgresDatabaseClient;
@@ -531,8 +537,10 @@ export async function runSliceMigrations(
       }
     }
 
+    // Opt-in (default: disabled): the abort gate consults an external model provider
+    // when one is configured, so a programmatic caller asks for it explicitly.
     let abortSignal: AbortGateResult | undefined;
-    if (hasFailure) {
+    if (hasFailure && options?.enableJevGate === true) {
       try {
         const failureDetails = migrations
           .filter((m) => m.status === 'FAILED')

package/src/compiler/optional-coverage.ts

@@ -0,0 +1,137 @@
+/**
+ * SynapseJS - Optional Contract Item Coverage
+ *
+ * The slice authoring contract has optional items — webhook, background job,
+ * websocket definition, cache definition, metadata generation, broadcast and
+ * subscription. Prose cannot prove they work; a committed slice can. This module
+ * reports which optional item each shipped application exercises and which ones
+ * nothing exercises, so a capability cannot be advertised on a template assertion.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { findSliceFiles, resolveSlicesDir } from './slice-discovery';
+
+export interface OptionalItemCoverage {
+  item: string;
+  /** The committed slice that exercises it, or null when nothing does. */
+  slice: string | null;
+}
+
+export interface OptionalItemReport {
+  status: 'PASS' | 'FAIL';
+  operation: 'OPTIONAL_ITEM_COVERAGE';
+  appDir: string;
+  totalSlices: number;
+  items: OptionalItemCoverage[];
+  /** The optional items no committed slice exercises. Empty is the passing state. */
+  unexercised: string[];
+  /** Present when slice discovery failed. */
+  code?: string;
+  message?: string;
+  candidates?: string[];
+}
+
+interface Detector {
+  item: string;
+  matches: (filePath: string, source: string) => boolean;
+}
+
+function exportsName(source: string, suffix: string): boolean {
+  return new RegExp(`export\\s+(?:async\\s+)?(?:function|const|class|let|var)\\s+\\w*${suffix}\\b`).test(source);
+}
+
+const DETECTORS: Detector[] = [
+  {
+    item: 'webhook',
+    matches: (_file, source) => exportsName(source, 'Webhook')
+  },
+  {
+    item: 'background job',
+    matches: (_file, source) => exportsName(source, 'Job') || /\bdefineJob\s*[<(]/.test(source)
+  },
+  {
+    item: 'websocket definition',
+    matches: (_file, source) => exportsName(source, 'Socket') || /\bdefineSocket\s*[<(]/.test(source)
+  },
+  {
+    item: 'cache definition',
+    matches: (_file, source) => exportsName(source, 'Cache') || /\bdefineCache\s*\(/.test(source)
+  },
+  {
+    item: 'metadata generation',
+    matches: (_file, source) => /\bsliceMeta\b/.test(source) || exportsName(source, 'Meta')
+  },
+  {
+    item: 'broadcast',
+    matches: (_file, source) => /\.broadcast\s*\(/.test(source)
+  },
+  {
+    item: 'subscription',
+    matches: (_file, source) => /\buseSubscription\s*\(/.test(source) || /\bdefineTopic\s*\(/.test(source)
+  }
+];
+
+export function analyzeOptionalItemCoverage(appDir: string = process.cwd()): OptionalItemReport {
+  const resolution = resolveSlicesDir(appDir);
+
+  if (!resolution.ok) {
+    return {
+      status: 'FAIL',
+      operation: 'OPTIONAL_ITEM_COVERAGE',
+      appDir,
+      totalSlices: 0,
+      items: DETECTORS.map((detector) => ({ item: detector.item, slice: null })),
+      unexercised: DETECTORS.map((detector) => detector.item),
+      code: resolution.error.code,
+      message: resolution.error.message,
+      candidates: resolution.error.candidates
+    };
+  }
+
+  const sliceFiles = findSliceFiles(resolution.value.slicesDir);
+  const items: OptionalItemCoverage[] = DETECTORS.map((detector) => {
+    for (const filePath of sliceFiles) {
+      try {
+        const source = fs.readFileSync(filePath, 'utf-8');
+
+        if (detector.matches(filePath, source)) {
+          return { item: detector.item, slice: path.basename(filePath, '.slice.tsx') };
+        }
+      } catch {
+        // Unreadable slice: it cannot be the evidence, and discovery already reported it.
+      }
+    }
+
+    return { item: detector.item, slice: null };
+  });
+
+  const unexercised = items.filter((entry) => entry.slice === null).map((entry) => entry.item);
+
+  return {
+    status: unexercised.length === 0 ? 'PASS' : 'FAIL',
+    operation: 'OPTIONAL_ITEM_COVERAGE',
+    appDir,
+    totalSlices: sliceFiles.length,
+    items,
+    unexercised
+  };
+}
+
+/** The union of optional items covered across several shipped applications. */
+export function unionCoverage(reports: OptionalItemReport[]): { covered: string[]; unexercised: string[] } {
+  const covered = new Set<string>();
+
+  for (const report of reports) {
+    for (const entry of report.items) {
+      if (entry.slice) {
+        covered.add(entry.item);
+      }
+    }
+  }
+
+  return {
+    covered: Array.from(covered),
+    unexercised: DETECTORS.map((detector) => detector.item).filter((item) => !covered.has(item))
+  };
+}

package/src/compiler/oracle-runner.ts

@@ -157,6 +157,11 @@ export interface OracleRunOptions {
   /** Injected by tests: runs a command and returns its exit code and output. */
   spawn?: (args: string[], cwd: string) => Promise<{ exitCode: number; output: string }>;
   /** Enable Jev System One semantic test triage on failures. Default: true */
+  /**
+   * Opt-in (default: disabled). The triage consults an external model provider when
+   * one is configured, so a programmatic caller must ask for it explicitly; the CLI
+   * enables it only when the environment declares the gate.
+   */
   enableJevTriage?: boolean;
 }
 
@@ -246,7 +251,7 @@ export async function runSliceOracles(
 
   if (!fs.existsSync(reportPath)) {
     let triageResult: TestTriageResult | undefined;
-    if (options.enableJevTriage !== false) {
+    if (options.enableJevTriage === true) {
       try {
         triageResult = await triageTestFailure(output.trim() || `O runner Bun test falhou com exit ${exitCode}`);
       } catch {}
@@ -280,7 +285,7 @@ export async function runSliceOracles(
 
   if (totalCases === 0) {
     let triageResult: TestTriageResult | undefined;
-    if (options.enableJevTriage !== false) {
+    if (options.enableJevTriage === true) {
       try {
         triageResult = await triageTestFailure(`Nenhum invariante foi executado em ${results.length} fatia(s).`);
       } catch {}
@@ -301,7 +306,7 @@ export async function runSliceOracles(
 
   const isPass = passedSlices === results.length;
   let triageResult: TestTriageResult | undefined;
-  if (!isPass && options.enableJevTriage !== false) {
+  if (!isPass && options.enableJevTriage === true) {
     try {
       const failedSummaries = results
         .filter((r) => !r.passed)

package/src/compiler/scaffolder.ts

@@ -8,7 +8,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { Err, Ok, type Result } from '../core/machine-types';
-import { generateFormFieldsCode, generateSqlColumns, generateTypeBoxProperties, parseFields } from './fields-parser';
+import { isInsideBase, validatePathSegment } from '../core/path-guard';
+import {
+  generateFormFieldsCode,
+  generateSqlColumns,
+  generateTypeBoxProperties,
+  parseFields,
+  validateFieldNames
+} from './fields-parser';
 import { resolveSlicesDir, type SlicesDirErrorCode } from './slice-discovery';
 import { generateOperationTemplate, type SliceTemplate } from './slice-templates';
 
@@ -415,7 +422,28 @@ export const sliceTests = {
 `;
 }
 
-export type ScaffoldErrorCode = SlicesDirErrorCode | 'SLICE_EXISTS' | 'WRITE_FAILED';
+export type ScaffoldErrorCode =
+  | SlicesDirErrorCode
+  | 'SLICE_EXISTS'
+  | 'WRITE_FAILED'
+  | 'INVALID_PATH_SEGMENT'
+  | 'INVALID_FIELD_NAME';
+
+/**
+ * One description per scaffolding failure code. The `Record` type makes a
+ * missing member a compile error, so the documented set cannot drift from the
+ * union the functions return.
+ */
+export const SCAFFOLD_FAILURE_CODES: Record<ScaffoldErrorCode, string> = {
+  NO_SLICES_DIR: 'no src/slices directory was found; candidates lists every path examined',
+  AMBIGUOUS_SLICES_DIR:
+    'more than one application owns a slices directory; set SYNAPSE_ROOT or run inside the target application',
+  SLICE_EXISTS: 'the target file already exists',
+  WRITE_FAILED: 'the filesystem refused the write',
+  INVALID_PATH_SEGMENT:
+    'a domain, slice name, shared-module name or project directory is not a single safe path segment',
+  INVALID_FIELD_NAME: 'a field name or enum value in --fields is not a plain identifier'
+};
 
 export interface ScaffoldError {
   code: ScaffoldErrorCode;
@@ -448,6 +476,47 @@ function resolveScaffoldTarget(baseDir: string): Result<string, ScaffoldError> {
   return Ok(path.join(path.resolve(baseDir), 'src', 'slices'));
 }
 
+function segmentRejection(
+  kind: 'domain' | 'name',
+  value: string | undefined,
+  targetKind: string
+): ScaffoldError | null {
+  const validated = validatePathSegment(value);
+
+  if (validated.ok) {
+    return null;
+  }
+
+  return {
+    code: 'INVALID_PATH_SEGMENT',
+    message: `O ${kind === 'domain' ? 'domínio' : 'nome'} informado ('${value ?? ''}') não é um segmento de caminho válido para ${targetKind}. Use apenas letras, números, '-', '_' e '.', sem barras e sem '..'.`,
+    candidates: []
+  };
+}
+
+/**
+ * Field names are interpolated into generated DDL and generated TypeScript, so
+ * they are validated before a single byte is written: the migration runner is
+ * never handed a schema derived from an unchecked name.
+ */
+function fieldRejection(fieldsSpec: string | undefined): ScaffoldError | null {
+  if (!fieldsSpec?.trim()) {
+    return null;
+  }
+
+  const validation = validateFieldNames(parseFields(fieldsSpec));
+
+  if (validation.ok) {
+    return null;
+  }
+
+  return {
+    code: 'INVALID_FIELD_NAME',
+    message: `O nome de campo '${validation.error}' não é um identificador válido. Campos devem casar com [A-Za-z_][A-Za-z0-9_]*.`,
+    candidates: []
+  };
+}
+
 export function scaffoldSlice(
   domain: string,
   sliceName: string,
@@ -461,9 +530,35 @@ export function scaffoldSlice(
     return target;
   }
 
+  const domainRejection = segmentRejection('domain', domain, 'a fatia');
+
+  if (domainRejection) {
+    return Err(domainRejection);
+  }
+
+  const nameRejection = segmentRejection('name', sliceName, 'a fatia');
+
+  if (nameRejection) {
+    return Err(nameRejection);
+  }
+
+  const fieldsRejection = fieldRejection(fieldsSpec);
+
+  if (fieldsRejection) {
+    return Err(fieldsRejection);
+  }
+
   const targetDir = path.join(target.value, domain);
   const targetFile = path.join(targetDir, `${sliceName}.slice.tsx`);
 
+  if (!isInsideBase(target.value, targetFile)) {
+    return Err({
+      code: 'INVALID_PATH_SEGMENT',
+      message: `O caminho resolvido para a fatia '${sliceName}' sai do diretório de fatias da aplicação.`,
+      candidates: [targetFile]
+    });
+  }
+
   if (fs.existsSync(targetFile)) {
     return Err({
       code: 'SLICE_EXISTS',
@@ -473,11 +568,12 @@ export function scaffoldSlice(
   }
 
   try {
-    fs.mkdirSync(targetDir, { recursive: true });
     const content =
       template === 'create'
         ? generateSliceTemplate(domain, sliceName, fieldsSpec)
         : generateOperationTemplate(domain, sliceName, template, fieldsSpec);
+
+    fs.mkdirSync(targetDir, { recursive: true });
     fs.writeFileSync(targetFile, content, 'utf-8');
   } catch (err) {
     return Err({
@@ -525,11 +621,23 @@ export function scaffoldCrud(
 export function scaffoldShared(name: string, baseDir: string = process.cwd()): Result<string, ScaffoldError> {
   const cleanName = name.replace(/\.ts$/, '');
   const sharedDir = path.resolve(baseDir, 'src', 'shared');
-  if (!fs.existsSync(sharedDir)) {
-    fs.mkdirSync(sharedDir, { recursive: true });
+
+  const nameRejection = segmentRejection('name', cleanName, 'o módulo compartilhado');
+
+  if (nameRejection) {
+    return Err(nameRejection);
   }
 
   const targetFile = path.join(sharedDir, `${cleanName}.ts`);
+
+  if (!isInsideBase(sharedDir, targetFile)) {
+    return Err({
+      code: 'INVALID_PATH_SEGMENT',
+      message: `O caminho resolvido para o módulo compartilhado '${cleanName}' sai do diretório src/shared da aplicação.`,
+      candidates: [targetFile]
+    });
+  }
+
   if (fs.existsSync(targetFile)) {
     return Err({
       code: 'SLICE_EXISTS',
@@ -563,6 +671,7 @@ export async function executeShared${pascalName}(
 `;
 
   try {
+    fs.mkdirSync(sharedDir, { recursive: true });
     fs.writeFileSync(targetFile, content, 'utf-8');
     return Ok(targetFile);
   } catch (err: unknown) {

package/src/compiler/slice-discovery.ts

@@ -38,7 +38,14 @@ export function findSliceFiles(dir: string): string[] {
   }
 
   const results: string[] = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+  // `readdirSync` order is filesystem-dependent: on a fresh checkout it can differ from
+  // the developer's machine, which made generated artifacts (repo map, schema catalog,
+  // split order) drift between the two. Sorting makes every generated file reproducible.
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...findSliceFiles(full));