@ismaelsoilet/synapsejs 1.8.0 → 1.11.1

package/src/compiler/client-bundler.ts

@@ -17,6 +17,7 @@ import * as path from 'path';
 import { Err, Ok, type Result } from '../core/machine-types';
 import { clientEntrySource } from '../runtime/client-entry';
 import { isComponent } from '../runtime/discovery-rules';
+import { SYNAPSE_VERSION } from '../version';
 import { findSliceFiles, resolveSlicesDir, type SlicesDirError } from './slice-discovery';
 import { artifactDirectory, splitSlice, verifySplit, writeSplitArtifacts } from './slice-splitter';
 
@@ -61,6 +62,29 @@ export function clientManifestPath(baseDir: string): string {
   return path.join(baseDir, '.synapse', 'client', 'manifest.json');
 }
 
+export async function buildCssBundle(baseDir: string): Promise<Result<{ path: string; bytes: number }, BuildError>> {
+  const clientDir = path.join(baseDir, '.synapse/client');
+  fs.mkdirSync(clientDir, { recursive: true });
+  const outPath = path.join(clientDir, 'synapse.css');
+
+  const sourceCssCandidates = [
+    path.join(baseDir, 'public/synapse.css'),
+    path.join(baseDir, 'src/styles/synapse.css'),
+    path.join(baseDir, 'src/styles/main.css')
+  ];
+
+  for (const src of sourceCssCandidates) {
+    if (fs.existsSync(src)) {
+      const content = fs.readFileSync(src, 'utf-8');
+      fs.writeFileSync(outPath, content, 'utf-8');
+      return Ok({ path: outPath, bytes: Buffer.byteLength(content, 'utf-8') });
+    }
+  }
+
+  // No source means no stylesheet: the framework does not impose a theme.
+  return Ok({ path: outPath, bytes: 0 });
+}
+
 export async function buildVendorBundle(
   baseDir: string,
   vendorPackages: string[] = []
@@ -72,6 +96,7 @@ export async function buildVendorBundle(
   const extraExports = (vendorPackages || []).map((pkg) => `export * from '${pkg}';`).join('\n');
 
   const vendorEntryContent = [
+    `// SynapseJS Client Vendor Entry - Framework v${SYNAPSE_VERSION}`,
     `import React from 'react';`,
     `import * as ReactDOM from 'react-dom';`,
     `import * as ReactDOMClient from 'react-dom/client';`,
@@ -114,6 +139,30 @@ export async function buildVendorBundle(
     `  Children,`,
     `  startTransition`,
     `} = (React as unknown as Record<string, unknown>);`,
+    `const {`,
+    `  Badge,`,
+    `  Button,`,
+    `  Card,`,
+    `  DataForm,`,
+    `  DataTable,`,
+    `  Drawer,`,
+    `  DropdownItem,`,
+    `  DropdownMenu,`,
+    `  Modal,`,
+    `  Pagination,`,
+    `  Tab,`,
+    `  TabList,`,
+    `  TabPanel,`,
+    `  Tabs,`,
+    `  ToastProvider,`,
+    `  useToast,`,
+    `  SynapseProvider,`,
+    `  useAction,`,
+    `  useLoaderData,`,
+    `  useSubscription,`,
+    `  useWebSocket,`,
+    `  rpcCall`,
+    `} = (SynapseClient as unknown as Record<string, unknown>);`,
     `export {`,
     `  ReactDOM,`,
     `  ReactDOMClient,`,
@@ -146,7 +195,29 @@ export async function buildVendorBundle(
     `  memo,`,
     `  forwardRef,`,
     `  Children,`,
-    `  startTransition`,
+    `  startTransition,`,
+    `  Badge,`,
+    `  Button,`,
+    `  Card,`,
+    `  DataForm,`,
+    `  DataTable,`,
+    `  Drawer,`,
+    `  DropdownItem,`,
+    `  DropdownMenu,`,
+    `  Modal,`,
+    `  Pagination,`,
+    `  Tab,`,
+    `  TabList,`,
+    `  TabPanel,`,
+    `  Tabs,`,
+    `  ToastProvider,`,
+    `  useToast,`,
+    `  SynapseProvider,`,
+    `  useAction,`,
+    `  useLoaderData,`,
+    `  useSubscription,`,
+    `  useWebSocket,`,
+    `  rpcCall`,
     `};`,
     ``
   ].join('\n');
@@ -160,7 +231,28 @@ export async function buildVendorBundle(
   fs.mkdirSync(buildDir, { recursive: true });
   const vendorFile = path.join(buildDir, VENDOR_BUNDLE_NAME);
 
-  if (fs.existsSync(vendorFile) && existingEntry === vendorEntryContent) {
+  let isVendorStale = false;
+  if (fs.existsSync(vendorFile)) {
+    const vendorMtime = fs.statSync(vendorFile).mtimeMs;
+    try {
+      const localClientPath = path.resolve(__dirname, '../client.ts');
+      if (fs.existsSync(localClientPath) && fs.statSync(localClientPath).mtimeMs > vendorMtime) {
+        isVendorStale = true;
+      }
+      const localComponentsPath = path.resolve(__dirname, '../client/components.tsx');
+      if (fs.existsSync(localComponentsPath) && fs.statSync(localComponentsPath).mtimeMs > vendorMtime) {
+        isVendorStale = true;
+      }
+      const pkgJsonPath = path.join(baseDir, 'package.json');
+      if (fs.existsSync(pkgJsonPath) && fs.statSync(pkgJsonPath).mtimeMs > vendorMtime) {
+        isVendorStale = true;
+      }
+    } catch {
+      // ignore stat errors
+    }
+  }
+
+  if (fs.existsSync(vendorFile) && existingEntry === vendorEntryContent && !isVendorStale) {
     return Ok({
       sliceKey: '_vendor',
       url: VENDOR_BUNDLE_URL,

package/src/compiler/context-bench.ts

@@ -22,6 +22,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as ts from 'typescript';
+import { assertCompilerApi } from './typescript-api';
 
 export const TOKENS_PER_BYTE_ESTIMATE = 0.25;
 
@@ -149,6 +150,7 @@ interface BenchConfig {
 }
 
 export function measureAppSurface(appRoot: string): AppSurface {
+  assertCompilerApi();
   const configPath = path.join(appRoot, 'bench.config.json');
   if (!fs.existsSync(configPath)) {
     throw new Error(`bench.config.json ausente em ${appRoot}`);
@@ -174,7 +176,7 @@ export function measureAppSurface(appRoot: string): AppSurface {
 
 export function renderSurfaceReport(surfaces: AppSurface[]): string {
   const lines = [
-    '| app | feature | arquivos (app) | tokens (app, est.) | arquivos (total) | tokens (total, est.) |',
+    '| app | feature | arquivos (app) | tokens (app, est.) | arquivos (total, não comparável) | tokens (total, est., não comparável) |',
     '|---|---|---|---|---|---|'
   ];
 
@@ -187,5 +189,11 @@ export function renderSurfaceReport(surfaces: AppSurface[]): string {
     }
   }
 
+  lines.push(
+    '',
+    'As colunas `app` são as comparáveis (os arquivos da própria funcionalidade em cada aplicação).',
+    'As colunas `total` cobrem conjuntos de arquivos diferentes por repositório e não são comparáveis'
+  );
+
   return lines.join('\n');
 }

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-domain <domain> [--fields=<grammar>] · 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

@@ -156,7 +156,14 @@ export function oracleWrapperSource(importPath: string, sliceName: string): stri
 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 }>;
+  /** Optional target slice name or pattern to run tests exclusively for */
+  targetSlice?: 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;
 }
 
@@ -191,7 +198,14 @@ export async function runSliceOracles(
   }
 
   const slicesDir = resolution.value.slicesDir;
-  const sliceFiles = findSliceFiles(slicesDir);
+  const allSliceFiles = findSliceFiles(slicesDir);
+  const targetSlice = options.targetSlice;
+  const sliceFiles = targetSlice
+    ? allSliceFiles.filter((f) => {
+        const name = path.basename(f, '.slice.tsx');
+        return name === targetSlice || f.includes(targetSlice);
+      })
+    : allSliceFiles;
   const oraclesDir = path.join(root, '.synapse', ORACLE_DIR_NAME);
   const reportPath = path.join(oraclesDir, 'report.xml');
 
@@ -246,7 +260,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 +294,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 +315,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)