@ontrails/core 1.0.0-beta.2 → 1.0.0-beta.21

package/src/layer-projection.ts

@@ -0,0 +1,193 @@
+/**
+ * Shared, surface-agnostic helpers for projecting typed layer `input` schemas
+ * onto a surface's native idiom.
+ *
+ * Layer projection has two halves:
+ *   1. **Collection** — walk the trail's effective layers (topo → surface →
+ *      trail) and keep only the ones that declare an `input` schema. These
+ *      are the layers a surface needs to project.
+ *   2. **Naming/collision policy** — when a layer field's projected name
+ *      collides with a name already claimed by the trail, by another layer,
+ *      or by a surface-reserved name, the field is renamed using the
+ *      deterministic `<layerName>-<originalField>` rule. The collision-detection
+ *      logic itself is surface-agnostic; the *shape* of the projected name
+ *      (kebab-case CLI flag, camelCase MCP parameter, HTTP request field)
+ *      stays per-surface.
+ *
+ * This module owns the surface-agnostic half. CLI/MCP/HTTP each layer their
+ * own projection on top: see `@ontrails/cli/build`, `@ontrails/mcp/build`,
+ * and `@ontrails/http/build`.
+ *
+ * @see TRL-473 for the CLI projection that introduced this contract.
+ * @see TRL-474 for the MCP and HTTP projections that lifted these helpers.
+ */
+
+import type { Layer } from './layer.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+
+export const LAYER_FIELD_RESERVED_NAMES: ReadonlySet<string> = new Set([
+  'all',
+  'devPermit',
+  'dryRun',
+  'input',
+  'inputJson',
+  'json',
+  'jsonl',
+  'output',
+  'permit',
+  'quiet',
+  'token',
+  'trailVersion',
+  'trace',
+  'watch',
+]);
+
+const toKebabCase = (name: string): string =>
+  name.replaceAll(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+
+export const LAYER_FIELD_RESERVED_NAMES_KEBAB: ReadonlySet<string> = new Set(
+  [...LAYER_FIELD_RESERVED_NAMES].map(toKebabCase)
+);
+
+// ---------------------------------------------------------------------------
+// Collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Source of a typed layer attached to a trail.
+ *
+ * Surfaces may want to know whether a layer came from topo-, surface-, or
+ * trail-scope (e.g. for descriptive errors). The collection helper preserves
+ * this information so callers don't have to recompute it.
+ */
+export type AttachedLayerScope = 'topo' | 'surface' | 'trail';
+
+export interface AttachedTypedLayer {
+  readonly layer: Layer;
+  readonly scope: AttachedLayerScope;
+}
+
+/**
+ * Collect every typed layer attached to a trail in the same composition order
+ * the executor uses (topo → surface → trail). Layers without an `input`
+ * schema are skipped — they have nothing to project onto a surface.
+ *
+ * @param graph - The topo carrying topo-scope layers.
+ * @param trail - The trail whose effective layers we are projecting.
+ * @param surfaceLayers - Layers attached at surface scope (`options.layers`
+ *   on the surface builder).
+ */
+export const collectAttachedTypedLayers = (
+  graph: Topo,
+  trail: AnyTrail,
+  surfaceLayers?: readonly Layer[] | undefined
+): readonly AttachedTypedLayer[] => {
+  const layers: AttachedTypedLayer[] = [];
+  for (const layer of graph.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'topo' });
+    }
+  }
+  if (surfaceLayers !== undefined) {
+    for (const layer of surfaceLayers) {
+      if (layer.input !== undefined) {
+        layers.push({ layer, scope: 'surface' });
+      }
+    }
+  }
+  for (const layer of trail.layers) {
+    if (layer.input !== undefined) {
+      layers.push({ layer, scope: 'trail' });
+    }
+  }
+  return layers;
+};
+
+// ---------------------------------------------------------------------------
+// Collision rename rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Reason a layer field was renamed during projection.
+ *
+ * Surfaces map this onto their own warning/error idiom. CLI emits a stderr
+ * warning, while MCP/HTTP rely on the projected schema as the source of truth.
+ */
+export type LayerFieldRenameReason = 'reserved-name' | 'flag-collision';
+
+/**
+ * Outcome of projecting a single layer field's name.
+ *
+ * `claimedName` is the name the surface will publish to consumers; it is the
+ * field name when no collision was detected, or `<layerName>-<fieldName>` (or
+ * an analogous transformed form, depending on the surface's convention) when
+ * a collision required a rename. `routingTarget` is the original field name
+ * the value should be assigned back to inside the layer's runtime input.
+ */
+export interface LayerFieldProjection {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: false;
+}
+
+export interface RenamedLayerFieldProjection {
+  readonly claimedName: string;
+  readonly routingTarget: string;
+  readonly renamed: true;
+  readonly originalName: string;
+  readonly reason: LayerFieldRenameReason;
+}
+
+export type ProjectedLayerField =
+  | LayerFieldProjection
+  | RenamedLayerFieldProjection;
+
+/**
+ * Apply the deterministic collision rename rule to a single projected layer
+ * field name.
+ *
+ * @param layerName - The layer's logical name (used as the rename prefix).
+ * @param originalName - The layer field's name as authored on its schema.
+ * @param projectedName - The candidate name in the surface's native idiom
+ *   (e.g. kebab-case for CLI, camelCase for MCP, request field for HTTP).
+ * @param renamedName - The fallback name applied when a collision is detected.
+ *   Surfaces compute this with their own casing rule.
+ * @param claimedNames - Names already taken by the trail's input or by
+ *   previous layer projections. Updated in place when a name is claimed.
+ * @param reservedNames - Framework-owned names that force a rename across
+ *   surface projections.
+ */
+export const projectLayerFieldName = (
+  _layerName: string,
+  originalName: string,
+  projectedName: string,
+  renamedName: string,
+  claimedNames: Set<string>,
+  reservedNames: ReadonlySet<string>
+): ProjectedLayerField => {
+  const collidesWithClaimed = claimedNames.has(projectedName);
+  const collidesWithReserved = reservedNames.has(projectedName);
+
+  if (!collidesWithClaimed && !collidesWithReserved) {
+    claimedNames.add(projectedName);
+    return {
+      claimedName: projectedName,
+      renamed: false,
+      routingTarget: originalName,
+    };
+  }
+
+  let claimedName = renamedName;
+  for (let suffix = 2; claimedNames.has(claimedName); suffix += 1) {
+    claimedName = `${renamedName}${suffix}`;
+  }
+  claimedNames.add(claimedName);
+  return {
+    claimedName,
+    originalName: projectedName,
+    reason: collidesWithReserved ? 'reserved-name' : 'flag-collision',
+    renamed: true,
+    routingTarget: originalName,
+  };
+};

package/src/layer.ts

@@ -1,18 +1,55 @@
-import type { Trail } from './trail.js';
+import type { z } from 'zod';
+
+import type { AnyTrail } from './trail.js';
 import type { Implementation } from './types.js';
 
 // ---------------------------------------------------------------------------
 // Layer interface
 // ---------------------------------------------------------------------------
 
-/** A composable middleware that wraps trail implementations */
+/**
+ * A composable, named layer that wraps blazes.
+ *
+ * Layers attach at trail, surface, or topo scope and may declare an object
+ * `input` schema describing the configuration they need from the surrounding
+ * surface. Surface packages (CLI, MCP, HTTP) project this schema onto their
+ * native idioms — flags, tool parameters, query strings — alongside the
+ * trail's own input schema.
+ *
+ * @remarks
+ * The `input` schema is metadata for surface projection. It must be an object
+ * schema so every surface can project named fields consistently. It is
+ * optional; layers without an `input` schema behave as plain wrappers. The
+ * layer's `wrap` function is the runtime contract.
+ */
+export type LayerInputSchema = z.ZodObject<z.ZodRawShape>;
+
 export interface Layer {
   readonly name: string;
   readonly description?: string | undefined;
 
-  /** Wrap a trail's implementation, returning a new implementation */
+  /**
+   * Authored configuration the layer needs from the surrounding surface.
+   *
+   * Surface packages project this schema onto their native idioms (CLI flags,
+   * MCP tool parameters, HTTP query strings) so a layer's input fields appear
+   * alongside the trail's own input fields. Optional — layers that wrap purely
+   * by behavior, with no surface-visible inputs, may omit it.
+   *
+   * @see TRL-473 for CLI flag projection.
+   * @see TRL-474 for MCP and HTTP projection.
+   */
+  readonly input?: LayerInputSchema | undefined;
+
+  /**
+   * Wrap a trail's implementation, returning a new implementation.
+   *
+   * The trail is passed for metadata inspection (intent, schema, etc.).
+   * The implementation and return type are generic over the input/output
+   * types so layers remain type-safe when composed.
+   */
   wrap<I, O>(
-    trail: Trail<I, O>,
+    trail: AnyTrail,
     implementation: Implementation<I, O>
   ): Implementation<I, O>;
 }
@@ -29,10 +66,10 @@ export interface Layer {
  */
 export const composeLayers = <I, O>(
   layers: readonly Layer[],
-  trail: Trail<I, O>,
+  trail: AnyTrail,
   implementation: Implementation<I, O>
 ): Implementation<I, O> => {
-  // Fold right so layers[0] is the outermost wrapper
+  // Fold right so layers[0] is the outermost wrapper.
   let result = implementation;
   for (let i = layers.length - 1; i >= 0; i -= 1) {
     const layer = layers[i];

package/src/observe.ts

@@ -0,0 +1,361 @@
+import { ValidationError } from './errors.js';
+import type { TraceSink } from './tracing.js';
+import type { Layer } from './layer.js';
+import { safeStringify } from './serialization.js';
+import type { Logger, LogLevel, LogRecord, LogSink } from './types.js';
+
+export interface ObserveConfig {
+  readonly log?: Logger | LogSink | undefined;
+  readonly trace?: TraceSink | undefined;
+}
+
+export interface ObserveCapabilities {
+  readonly log?: true | undefined;
+  readonly trace?: true | undefined;
+}
+
+interface ObserveCapable {
+  readonly observes?: ObserveCapabilities | undefined;
+}
+
+export type ObserveInput = Logger | LogSink | TraceSink | ObserveConfig;
+
+export interface TopoOptions {
+  readonly observe?: ObserveInput | undefined;
+  /**
+   * Typed layers attached at topo scope.
+   *
+   * Layers declared here wrap every trail invoked through this topo, on every
+   * surface. The execution pipeline composes topo-scope layers outermost —
+   * around surface-scope and trail-scope layers — so the final order is
+   * `topo → surface → trail → blaze` (outermost-first).
+   */
+  readonly layers?: readonly Layer[] | undefined;
+}
+
+const OBSERVE_CONFIG_KEYS = new Set(['log', 'trace']);
+export const OBSERVE_LOGGER_CONTEXT_KEY = '__trails_observe_logger';
+
+/**
+ * Context extension key that carries metadata accumulated on the observe
+ * logger across rebindings (e.g. signal fan-out metadata such as `consumerId`
+ * and `signalId`). When `applyTopoObserveContext` rebinds the logger for a
+ * new trail, it merges this metadata into the freshly built observe logger
+ * so consumer log records retain provenance back to the triggering signal.
+ */
+export const OBSERVE_LOGGER_METADATA_KEY = '__trails_observe_logger_metadata';
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const hasFunction = (value: Record<string, unknown>, key: string): boolean =>
+  typeof value[key] === 'function';
+
+export const isLogger = (value: unknown): value is Logger =>
+  isObject(value) &&
+  hasFunction(value, 'child') &&
+  hasFunction(value, 'debug') &&
+  hasFunction(value, 'error') &&
+  hasFunction(value, 'fatal') &&
+  hasFunction(value, 'info') &&
+  hasFunction(value, 'trace') &&
+  hasFunction(value, 'warn');
+
+export const isLogSink = (value: unknown): value is LogSink =>
+  isObject(value) &&
+  typeof value['name'] === 'string' &&
+  hasFunction(value, 'write');
+
+const readObserveCapabilities = (
+  value: unknown
+): ObserveCapabilities | undefined => {
+  if (!isObject(value)) {
+    return undefined;
+  }
+  const capabilities = (value as ObserveCapable).observes;
+  if (!isObject(capabilities)) {
+    return undefined;
+  }
+  const log = capabilities['log'] === true;
+  const trace = capabilities['trace'] === true;
+  if (!log && !trace) {
+    return undefined;
+  }
+  return Object.freeze({
+    ...(log ? { log: true as const } : {}),
+    ...(trace ? { trace: true as const } : {}),
+  });
+};
+
+export const isTraceSink = (value: unknown): value is TraceSink =>
+  isObject(value) && hasFunction(value, 'write');
+
+const isObserveConfigShape = (value: unknown): value is ObserveConfig => {
+  if (!isObject(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((key) => OBSERVE_CONFIG_KEYS.has(key)) &&
+    ('log' in value || 'trace' in value)
+  );
+};
+
+/**
+ * Type guard for the `ObserveInput` union. Returns `true` only for shapes
+ * that {@link normalizeObserve} will accept without throwing — i.e. a
+ * `Logger`, an explicit `ObserveConfig`, or a `TraceSink`. Capability-only
+ * payloads (`{ observes: { trace: true } }` without an accompanying
+ * `write` method) and bare `LogSink` shorthand are intentionally rejected:
+ * the former is metadata about a missing implementation, and the latter
+ * is ambiguous between a `LogSink` and a `TraceSink` and is rejected by
+ * `normalizeObserve` accordingly. Keeping the guard tighter than the
+ * runtime accepts would let callers narrow to `ObserveInput` and then
+ * see `normalizeObserve` throw at runtime.
+ */
+export const isObserveInput = (
+  value: unknown
+): value is ObserveInput | undefined => {
+  if (value === undefined) {
+    return true;
+  }
+  if (isLogger(value)) {
+    return true;
+  }
+  if (isObserveConfigShape(value)) {
+    return true;
+  }
+  if (isTraceSink(value) && !isLogSink(value)) {
+    // A bare TraceSink (no `name`) is unambiguous — `normalizeObserve`
+    // accepts it via the `isTraceSink` fallthrough. A LogSink shape is
+    // ambiguous (matches both guards) and would be rejected by
+    // `normalizeObserve`, so the guard rejects it here too.
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Returns true when `value` carries explicit observe capabilities via the
+ * `observes` discriminator. Used by the topo classifier to distinguish
+ * an `ObserveCapable` sink (clearly options) from a bare sink (ambiguous
+ * with a module export named `observe`).
+ */
+export const hasObserveCapabilities = (value: unknown): boolean =>
+  readObserveCapabilities(value) !== undefined;
+
+/**
+ * Returns true when `value` is shaped like the explicit `{ log?, trace? }`
+ * `ObserveConfig` payload. Exposed for the topo classifier so a config-style
+ * trailing argument is unambiguously classified as options.
+ */
+export const isObserveConfig = (value: unknown): value is ObserveConfig =>
+  isObserveConfigShape(value);
+
+const normalizeLogTarget = (
+  target: ObserveConfig['log']
+): ObserveConfig['log'] => {
+  if (target === undefined || isLogger(target) || isLogSink(target)) {
+    return target;
+  }
+  throw new ValidationError('topo observe.log must be a Logger or LogSink');
+};
+
+const normalizeTraceTarget = (
+  target: ObserveConfig['trace']
+): ObserveConfig['trace'] => {
+  if (target === undefined || isTraceSink(target)) {
+    return target;
+  }
+  throw new ValidationError('topo observe.trace must be a TraceSink');
+};
+
+/**
+ * Maps observe log levels to the `console` method that should receive the
+ * formatted record. `silent` is intentionally absent — records at that level
+ * are dropped before reaching `console`.
+ */
+const DEFAULT_SINK_CONSOLE_METHOD: Record<
+  LogLevel,
+  'debug' | 'error' | 'info' | 'warn' | undefined
+> = {
+  debug: 'debug',
+  error: 'error',
+  fatal: 'error',
+  info: 'info',
+  silent: undefined,
+  trace: 'debug',
+  warn: 'warn',
+};
+
+const stringifyDefaultConsoleRecord = (record: LogRecord): string => {
+  const serialized = safeStringify({
+    category: record.category,
+    level: record.level,
+    message: record.message,
+    metadata: record.metadata,
+    timestamp: record.timestamp.toISOString(),
+  });
+  if (serialized.isOk()) {
+    return serialized.value;
+  }
+  return JSON.stringify({
+    category: record.category,
+    level: record.level,
+    message: record.message,
+    metadata: '[unserializable]',
+    timestamp: record.timestamp.toISOString(),
+  });
+};
+
+/**
+ * In-core mirror of `@ontrails/observe`'s `createConsoleSink` shape, kept
+ * minimal and private to avoid a reverse dependency from `@ontrails/core`
+ * onto `@ontrails/observe`. It mirrors the console level mapping in
+ * `packages/observe/src/sinks.ts:50` and emits each record as a single-line
+ * JSON object written to the matching `console.{debug|info|warn|error}` method.
+ *
+ * @remarks
+ * Used as the default `observe.log` target when `topo()` is called without an
+ * explicit `observe` option, so every app gets a non-null `ctx.logger` with
+ * structured stdout output and zero configuration. Apps that want richer
+ * formatting, file destinations, or custom sink behavior should pass an explicit
+ * `observe` option, which fully replaces this default.
+ */
+const createDefaultConsoleSink = (): LogSink => ({
+  name: 'console',
+  write(record): void {
+    const method = DEFAULT_SINK_CONSOLE_METHOD[record.level];
+    if (method === undefined) {
+      return;
+    }
+    const payload = stringifyDefaultConsoleRecord(record);
+    // oxlint-disable-next-line trails-local/no-console-in-packages -- ADR 0041 mandates a default console logger in core; this is the single sanctioned console boundary, mirroring `@ontrails/observe`'s `createConsoleSink`.
+    console[method](payload);
+  },
+});
+
+/**
+ * The default observe configuration applied when `topo()` receives no
+ * `observe` option. Frozen so callers cannot mutate the shared default; the
+ * sink itself is shared across topos because it has no per-topo state.
+ */
+const DEFAULT_OBSERVE_CONFIG: ObserveConfig = Object.freeze({
+  log: createDefaultConsoleSink(),
+});
+
+export const normalizeObserve = (
+  observe: ObserveInput | undefined
+): ObserveConfig | undefined => {
+  if (observe === undefined) {
+    // ADR 0041 promises a non-null `ctx.logger` with zero configuration.
+    // Returning the default config here lets the existing topo → adapter
+    // path project this log sink into `ctx.logger` without a second
+    // resolution point or a reverse dependency on `@ontrails/observe`.
+    return DEFAULT_OBSERVE_CONFIG;
+  }
+
+  const capabilities = readObserveCapabilities(observe);
+  if (capabilities !== undefined) {
+    const log =
+      capabilities.log === true
+        ? normalizeLogTarget(observe as Logger | LogSink)
+        : undefined;
+    const trace =
+      capabilities.trace === true
+        ? normalizeTraceTarget(observe as TraceSink)
+        : undefined;
+    return Object.freeze({
+      ...(log === undefined ? {} : { log }),
+      ...(trace === undefined ? {} : { trace }),
+    });
+  }
+
+  if (isLogger(observe)) {
+    return Object.freeze({ log: observe });
+  }
+
+  if (isObserveConfigShape(observe)) {
+    const log = normalizeLogTarget(observe.log);
+    const trace = normalizeTraceTarget(observe.trace);
+    if (log === undefined && trace === undefined) {
+      return undefined;
+    }
+    return Object.freeze({
+      ...(log === undefined ? {} : { log }),
+      ...(trace === undefined ? {} : { trace }),
+    });
+  }
+
+  if (isLogSink(observe)) {
+    throw new ValidationError(
+      'topo observe shorthand is ambiguous for named sinks; use { log: sink } or { trace: sink }'
+    );
+  }
+
+  if (isTraceSink(observe)) {
+    return Object.freeze({ trace: observe });
+  }
+
+  throw new ValidationError(
+    'topo observe must be a Logger, LogSink, TraceSink, or { log, trace } object'
+  );
+};
+
+const createLogSinkLogger = (
+  sink: LogSink,
+  category: string,
+  baseMetadata: Record<string, unknown>
+): Logger => {
+  const write = (
+    level: LogLevel,
+    message: string,
+    metadata?: Record<string, unknown>
+  ): void => {
+    sink.write({
+      category,
+      level,
+      message,
+      metadata: { ...baseMetadata, ...metadata },
+      timestamp: new Date(),
+    });
+  };
+
+  return {
+    child(metadata: Record<string, unknown>): Logger {
+      return createLogSinkLogger(sink, category, {
+        ...baseMetadata,
+        ...metadata,
+      });
+    },
+    debug(message, metadata): void {
+      write('debug', message, metadata);
+    },
+    error(message, metadata): void {
+      write('error', message, metadata);
+    },
+    fatal(message, metadata): void {
+      write('fatal', message, metadata);
+    },
+    info(message, metadata): void {
+      write('info', message, metadata);
+    },
+    name: category,
+    trace(message, metadata): void {
+      write('trace', message, metadata);
+    },
+    warn(message, metadata): void {
+      write('warn', message, metadata);
+    },
+  };
+};
+
+export const createObserveLogger = (
+  log: Logger | LogSink,
+  category: string,
+  metadata: Record<string, unknown>
+): Logger =>
+  isLogger(log)
+    ? log.child(metadata)
+    : createLogSinkLogger(log, category, metadata);

package/src/path-security.ts

@@ -70,7 +70,7 @@ export const isPathSafe = (basePath: string, userPath: string): boolean => {
  * Joins multiple path segments, resolves them against `basePath`, and
  * validates the result stays within the base directory.
  */
-export const resolveSafePath = (
+export const deriveSafePath = (
   basePath: string,
   ...segments: string[]
 ): Result<string, PermissionError> => {

package/src/permits.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+/** Minimal permit shape available on TrailContext. */
+export interface BasePermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
+export const basePermitSchema: z.ZodType<BasePermit> = z.object({
+  id: z.string(),
+  scopes: z.array(z.string()).readonly(),
+});

package/src/redaction/patterns.ts

@@ -16,11 +16,14 @@ export const DEFAULT_PATTERNS: RegExp[] = [
   // SSN: XXX-XX-XXXX
   /\b\d{3}-\d{2}-\d{4}\b/g,
 
-  // Bearer tokens
-  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g,
+  // Bearer tokens. Keep the threshold above short prose like "Bearer token".
+  /Bearer\s+[A-Za-z0-9\-._~+/=]{6,}/g,
 
   // Basic auth
-  /Basic\s+[A-Za-z0-9+/]+=*/g,
+  /Basic\s+[A-Za-z0-9+/=]{8,}/g,
+
+  // Common key/value secrets embedded in strings
+  /\b(?:password|secret|token|api[_-]?key|cookie)\s*[:=]\s*[^\s,;]+/gi,
 
   // API keys: sk-*, pk_*, sk_* prefixed tokens
   /\b(?:sk-|pk_|sk_)[A-Za-z0-9_-]{8,}\b/g,