@ontrails/core 1.0.0-beta.14 → 1.0.0-beta.16

package/src/signal.ts

@@ -4,6 +4,29 @@
 
 import type { z } from 'zod';
 
+const formatExampleIssues = (issues: readonly z.core.$ZodIssue[]): string =>
+  issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+
+const assertSignalExamples = <T>(
+  id: string,
+  payload: z.ZodType<T>,
+  examples: readonly T[]
+): void => {
+  for (const [index, example] of examples.entries()) {
+    const parsed = payload.safeParse(example);
+    if (!parsed.success) {
+      throw new TypeError(
+        `signal("${id}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
+      );
+    }
+  }
+};
+
 // ---------------------------------------------------------------------------
 // Spec (input to the factory)
 // ---------------------------------------------------------------------------
@@ -11,6 +34,8 @@ import type { z } from 'zod';
 export interface SignalSpec<T> {
   readonly payload: z.ZodType<T>;
   readonly description?: string | undefined;
+  /** Example payloads validated against the signal payload schema. */
+  readonly examples?: readonly T[] | undefined;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   /** Trail IDs that produce this signal (e.g. the trails it originates from). */
   readonly from?: readonly string[] | undefined;
@@ -25,6 +50,8 @@ export interface Signal<T> {
   readonly kind: 'signal';
   readonly payload: z.ZodType<T>;
   readonly description?: string | undefined;
+  /** Example payloads validated against the signal payload schema. */
+  readonly examples?: readonly T[] | undefined;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   /** Trail IDs that produce this signal (e.g. the trails it originates from). */
   readonly from?: readonly string[] | undefined;
@@ -51,8 +78,18 @@ export function signal<T>(
   const resolvedId = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
   // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
   const resolvedSpec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  if (resolvedSpec.examples !== undefined) {
+    assertSignalExamples(
+      resolvedId,
+      resolvedSpec.payload,
+      resolvedSpec.examples
+    );
+  }
   return Object.freeze({
     description: resolvedSpec.description,
+    examples: resolvedSpec.examples
+      ? Object.freeze([...resolvedSpec.examples])
+      : undefined,
     from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
     id: resolvedId,
     kind: 'signal' as const,

package/src/store/accessor-protocol.ts

@@ -0,0 +1,56 @@
+/**
+ * Structural accessor protocol used by `deriveTrail()` to synthesize default
+ * blazes for standard CRUD operations without depending on `@ontrails/store`.
+ *
+ * @remarks
+ * This type is intentionally minimal and structural. `@ontrails/store`'s
+ * `StoreAccessor` / `StoreTableAccessor` interfaces satisfy this protocol
+ * through a compile-time extends check (see `packages/store/src/types.ts`).
+ * Keeping the protocol in core avoids a core → store dependency while still
+ * allowing the derivation helper to call accessors by convention.
+ *
+ * Required methods (`get`, `list`, `upsert`, `remove`) match the
+ * backend-agnostic write contract every bound store must expose. Optional
+ * methods (`insert`, `update`) are declared by tabular adapters that
+ * distinguish create-only and patch-only operations from the generalized
+ * `upsert` contract.
+ */
+export interface StoreAccessorProtocol<
+  TInput,
+  TEntity,
+  TId,
+  TFilters = unknown,
+> {
+  /** Retrieve a single entity by identity. Returns `null` when not found. */
+  get(id: TId): Promise<TEntity | null>;
+  /** List entities, optionally filtered. Returns `[]` when no rows match. */
+  list(filters?: TFilters): Promise<readonly TEntity[]>;
+  /** Create-or-replace one entity using the backend-agnostic contract. */
+  upsert(input: TInput): Promise<TEntity>;
+  /**
+   * Remove an entity by identity. Returns `{ deleted: true }` when the row
+   * was found and removed, `{ deleted: false }` when no matching row
+   * existed (not an error).
+   */
+  remove(id: TId): Promise<{ readonly deleted: boolean }>;
+  /**
+   * Optional insert — available on tabular adapters that distinguish
+   * create from update. When absent, synthesized blazes fall back to
+   * `upsert`.
+   */
+  insert?(input: TInput): Promise<TEntity>;
+  /**
+   * Optional patch-by-identity — available on tabular adapters. Returns
+   * `null` when no row with the given identity exists. When absent,
+   * synthesized update blazes fall back to `get` + merge + `upsert`.
+   */
+  update?(id: TId, patch: Partial<TInput>): Promise<TEntity | null>;
+}
+
+/**
+ * Record shape returned by a resource's `from(ctx)` call, keyed by accessor
+ * name. Used by `deriveTrail()` to resolve an accessor by contour name.
+ */
+export type StoreAccessorRecord = Readonly<
+  Record<string, StoreAccessorProtocol<unknown, unknown, unknown, unknown>>
+>;

package/src/store/index.ts

@@ -0,0 +1,4 @@
+export type {
+  StoreAccessorProtocol,
+  StoreAccessorRecord,
+} from './accessor-protocol.js';

package/src/structured-examples.ts

@@ -0,0 +1,245 @@
+import type { TrailExample, TrailExampleSignalAssertion } from './trail.js';
+
+export interface StructuredTrailExampleProvenance {
+  readonly source: 'trail.examples';
+}
+
+export interface StructuredSignalExampleProvenance {
+  readonly source: 'signal.examples';
+}
+
+export type StructuredTrailExampleKind = 'success' | 'error';
+
+export interface StructuredTrailExample {
+  readonly description?: string | undefined;
+  readonly error?: string | undefined;
+  readonly expected?: unknown | undefined;
+  readonly expectedMatch?: unknown | undefined;
+  readonly input: unknown;
+  readonly kind: StructuredTrailExampleKind;
+  readonly name: string;
+  readonly provenance: StructuredTrailExampleProvenance;
+  readonly signals?:
+    | readonly StructuredTrailExampleSignalAssertion[]
+    | undefined;
+}
+
+export interface StructuredTrailExampleSignalAssertion {
+  readonly payload?: unknown | undefined;
+  readonly payloadMatch?: unknown | undefined;
+  readonly signalId: string;
+  readonly times?: number | undefined;
+}
+
+export interface StructuredSignalExample {
+  readonly kind: 'payload';
+  readonly payload: unknown;
+  readonly provenance: StructuredSignalExampleProvenance;
+}
+
+// `Date`, `RegExp`, `Map`, and `Set` are objects (`typeof === 'object'`),
+// so they would pass the structural walk and reach `JSON.stringify`, which
+// silently coerces them: a `Date` becomes its ISO string, a `RegExp` and
+// any `Map`/`Set` become `{}`. Either way the projected shape diverges
+// from the example author's declared input. Treat them as non-serializable
+// leaves so the example is dropped rather than misrepresented to MCP
+// clients.
+const isNonJsonLeaf = (value: unknown): boolean => {
+  const kind = typeof value;
+  if (kind === 'function' || kind === 'symbol' || kind === 'bigint') {
+    return true;
+  }
+  return (
+    value instanceof Date ||
+    value instanceof RegExp ||
+    value instanceof Map ||
+    value instanceof Set
+  );
+};
+
+// `JSON.stringify` silently drops function / symbol property values rather than
+// throwing, so we walk the value first and reject any example whose graph
+// contains a non-serializable leaf. Without this, an MCP client consuming
+// `ontrails/examples` would receive structurally incorrect inputs.
+const containsNonSerializableLeaf = (
+  value: unknown,
+  seen: WeakSet<object>
+): boolean => {
+  if (isNonJsonLeaf(value)) {
+    return true;
+  }
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const obj = value as object;
+  if (seen.has(obj)) {
+    return false;
+  }
+  seen.add(obj);
+  if (Array.isArray(value)) {
+    return value.some((entry) => containsNonSerializableLeaf(entry, seen));
+  }
+  return Object.values(obj).some((entry) =>
+    containsNonSerializableLeaf(entry, seen)
+  );
+};
+
+const toJsonSerializable = (value: unknown): unknown | undefined => {
+  if (containsNonSerializableLeaf(value, new WeakSet<object>())) {
+    return undefined;
+  }
+  try {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? undefined : JSON.parse(encoded);
+  } catch {
+    return undefined;
+  }
+};
+
+const signalIdFromAssertion = (
+  assertion: TrailExampleSignalAssertion
+): string | undefined => {
+  if (typeof assertion.signal === 'string') {
+    return assertion.signal;
+  }
+  return typeof assertion.signal.id === 'string'
+    ? assertion.signal.id
+    : undefined;
+};
+
+const projectSignalAssertion = (
+  assertion: TrailExampleSignalAssertion
+): StructuredTrailExampleSignalAssertion | undefined => {
+  const signalId = signalIdFromAssertion(assertion);
+  if (signalId === undefined) {
+    return undefined;
+  }
+
+  const projected: Record<string, unknown> = { signalId };
+  if (assertion.payload !== undefined) {
+    const payload = toJsonSerializable(assertion.payload);
+    if (payload === undefined) {
+      return undefined;
+    }
+    projected['payload'] = payload;
+  }
+  if (assertion.payloadMatch !== undefined) {
+    const payloadMatch = toJsonSerializable(assertion.payloadMatch);
+    if (payloadMatch === undefined) {
+      return undefined;
+    }
+    projected['payloadMatch'] = payloadMatch;
+  }
+  if (assertion.times !== undefined) {
+    projected['times'] = assertion.times;
+  }
+  return Object.freeze(
+    projected
+  ) as unknown as StructuredTrailExampleSignalAssertion;
+};
+
+const projectSignalAssertions = (
+  assertions: readonly TrailExampleSignalAssertion[] | undefined
+): readonly StructuredTrailExampleSignalAssertion[] | undefined => {
+  if (assertions === undefined) {
+    return undefined;
+  }
+  const projected = assertions.map(projectSignalAssertion);
+  if (projected.some((assertion) => assertion === undefined)) {
+    return undefined;
+  }
+  return Object.freeze(projected as StructuredTrailExampleSignalAssertion[]);
+};
+
+const projectExample = (
+  example: TrailExample<unknown, unknown>
+): StructuredTrailExample | undefined => {
+  const input = toJsonSerializable(example.input);
+  if (input === undefined) {
+    return undefined;
+  }
+
+  const projected: Record<string, unknown> = {
+    input,
+    kind: example.error === undefined ? 'success' : 'error',
+    name: example.name,
+    provenance: { source: 'trail.examples' },
+  };
+
+  if (example.description !== undefined) {
+    projected['description'] = example.description;
+  }
+  if (example.expected !== undefined) {
+    const expected = toJsonSerializable(example.expected);
+    if (expected === undefined) {
+      return undefined;
+    }
+    projected['expected'] = expected;
+  }
+  if (example.expectedMatch !== undefined) {
+    const expectedMatch = toJsonSerializable(example.expectedMatch);
+    if (expectedMatch === undefined) {
+      return undefined;
+    }
+    projected['expectedMatch'] = expectedMatch;
+  }
+  if (example.error !== undefined) {
+    projected['error'] = example.error;
+  }
+  if (example.signals !== undefined) {
+    const signals = projectSignalAssertions(example.signals);
+    if (signals === undefined) {
+      return undefined;
+    }
+    projected['signals'] = signals;
+  }
+
+  return Object.freeze(projected) as unknown as StructuredTrailExample;
+};
+
+const projectSignalExample = (
+  payload: unknown
+): StructuredSignalExample | undefined => {
+  const serializablePayload = toJsonSerializable(payload);
+  if (serializablePayload === undefined) {
+    return undefined;
+  }
+
+  return Object.freeze({
+    kind: 'payload',
+    payload: serializablePayload,
+    provenance: { source: 'signal.examples' },
+  } satisfies StructuredSignalExample);
+};
+
+export const deriveStructuredTrailExamples = (
+  examples: readonly TrailExample<unknown, unknown>[] | undefined
+): readonly StructuredTrailExample[] | undefined => {
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  const projected = examples
+    .map(projectExample)
+    .filter(
+      (example): example is StructuredTrailExample => example !== undefined
+    );
+
+  return projected.length > 0 ? Object.freeze(projected) : undefined;
+};
+
+export const deriveStructuredSignalExamples = (
+  examples: readonly unknown[] | undefined
+): readonly StructuredSignalExample[] | undefined => {
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  const projected = examples
+    .map(projectSignalExample)
+    .filter(
+      (example): example is StructuredSignalExample => example !== undefined
+    );
+
+  return projected.length > 0 ? Object.freeze(projected) : undefined;
+};

package/src/surface-derivation.ts

@@ -0,0 +1,91 @@
+import { Result } from './result.js';
+import type { Layer } from './layer.js';
+import type { Intent } from './trail.js';
+import type { Topo } from './topo.js';
+import type { SurfaceName } from './transport-error-map.js';
+import type { TrailContextInit } from './types.js';
+import { SURFACE_KEY, SURFACE_LAYER_NAMES_KEY } from './types.js';
+import { validateEstablishedTopo } from './validate-established-topo.js';
+
+export type SurfaceConfigValues = Readonly<
+  Record<string, Record<string, unknown>>
+>;
+
+export interface SurfaceSelectionOptions {
+  /** Glob patterns that remove matching trail IDs. */
+  readonly exclude?: readonly string[] | undefined;
+  /** Glob patterns that keep only matching trail IDs when provided. */
+  readonly include?: readonly string[] | undefined;
+  /** Allowed intents for exposed surfaces. Empty arrays act as no filter. */
+  readonly intent?: readonly Intent[] | undefined;
+}
+
+export interface SurfaceValidationOptions {
+  /** Set to `false` to skip established-topo validation during projection. */
+  readonly validate?: boolean | undefined;
+}
+
+export interface BaseSurfaceOptions
+  extends SurfaceSelectionOptions, SurfaceValidationOptions {
+  /** Config values for resources that declare a `config` schema, keyed by resource ID. */
+  readonly configValues?: SurfaceConfigValues | undefined;
+}
+
+export const shouldValidateSurfaceTopo = (
+  options?: SurfaceValidationOptions
+): boolean => options?.validate !== false;
+
+export const validateSurfaceTopo = (
+  graph: Topo,
+  options?: SurfaceValidationOptions
+): Result<void, Error> => {
+  if (!shouldValidateSurfaceTopo(options)) {
+    return Result.ok();
+  }
+
+  const validated = validateEstablishedTopo(graph);
+  return validated.isErr() ? Result.err(validated.error) : Result.ok();
+};
+
+export type SurfaceMarkedContext = Partial<TrailContextInit> & {
+  readonly extensions: Readonly<Record<string, unknown>>;
+};
+
+export const withSurfaceMarker = (
+  surface: SurfaceName,
+  ctx: Partial<TrailContextInit> = {}
+): SurfaceMarkedContext => ({
+  ...ctx,
+  extensions: {
+    ...ctx.extensions,
+    [SURFACE_KEY]: surface,
+  },
+});
+
+const readSurfaceLayerNameRecord = (
+  value: unknown
+): Record<string, readonly string[]> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, readonly string[]>)
+    : {};
+
+export const withSurfaceLayerNames = (
+  surface: SurfaceName,
+  layers: readonly Layer[],
+  ctx: Partial<TrailContextInit> = {}
+): SurfaceMarkedContext => {
+  const existing = readSurfaceLayerNameRecord(
+    ctx.extensions?.[SURFACE_LAYER_NAMES_KEY]
+  );
+  return {
+    ...ctx,
+    extensions: {
+      ...ctx.extensions,
+      [SURFACE_KEY]: surface,
+      [SURFACE_LAYER_NAMES_KEY]: {
+        ...existing,
+        [surface]: layers.map((layer) => layer.name),
+      },
+    },
+  };
+};

package/src/surface-filter.ts

@@ -0,0 +1,176 @@
+import type { Intent, Trail } from './trail.js';
+import type { SurfaceSelectionOptions } from './surface-derivation.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type SurfaceFilterOptions = SurfaceSelectionOptions;
+
+// ---------------------------------------------------------------------------
+// Glob matching
+// ---------------------------------------------------------------------------
+
+const trailIdSegments = (trailId: string): readonly string[] =>
+  trailId.split('.');
+
+const patternSegments = (pattern: string): readonly string[] =>
+  pattern.split('.');
+
+type SegmentMatcher = (
+  trail: readonly string[],
+  pattern: readonly string[],
+  trailIndex: number,
+  patternIndex: number
+) => boolean;
+
+const matchesDoubleStar = (
+  trail: readonly string[],
+  pattern: readonly string[],
+  trailIndex: number,
+  patternIndex: number,
+  matchSegments: SegmentMatcher
+): boolean =>
+  patternIndex === pattern.length - 1 ||
+  Array.from(
+    { length: trail.length - trailIndex + 1 },
+    (_, offset) => trailIndex + offset
+  ).some((index) => matchSegments(trail, pattern, index, patternIndex + 1));
+
+const matchesSingleSegment = (
+  trail: readonly string[],
+  pattern: readonly string[],
+  trailIndex: number,
+  patternIndex: number,
+  current: string,
+  matchSegments: SegmentMatcher
+): boolean =>
+  trailIndex < trail.length &&
+  (current === '*' || current === trail[trailIndex]) &&
+  matchSegments(trail, pattern, trailIndex + 1, patternIndex + 1);
+
+const matchesFrom = function matchesFrom(
+  trail: readonly string[],
+  pattern: readonly string[],
+  trailIndex: number,
+  patternIndex: number
+): boolean {
+  if (patternIndex >= pattern.length) {
+    return trailIndex >= trail.length;
+  }
+
+  const current = pattern[patternIndex];
+  if (current === undefined) {
+    return false;
+  }
+
+  return current === '**'
+    ? matchesDoubleStar(trail, pattern, trailIndex, patternIndex, matchesFrom)
+    : matchesSingleSegment(
+        trail,
+        pattern,
+        trailIndex,
+        patternIndex,
+        current,
+        matchesFrom
+      );
+};
+
+export const matchesTrailPattern = (
+  trailId: string,
+  pattern: string
+): boolean => {
+  if (pattern === trailId) {
+    return true;
+  }
+  return matchesFrom(trailIdSegments(trailId), patternSegments(pattern), 0, 0);
+};
+
+// ---------------------------------------------------------------------------
+// Surface filtering
+// ---------------------------------------------------------------------------
+
+const matchesAnyPattern = (
+  trailId: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+
+const isExplicitInternalInclude = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean => include !== undefined && include.includes(trailId);
+
+/**
+ * Resolve the effective visibility for a trail.
+ *
+ * Returns `'internal'` when either the explicit `visibility` field is
+ * `'internal'` or the legacy `meta.internal === true` convention is set.
+ * Honoring the legacy flag keeps trails authored before the visibility
+ * field was introduced (e.g. `meta: { internal: true }`) off surfaces.
+ *
+ * The runtime always fills in `visibility: 'public'` when the spec did not
+ * declare it, so we cannot distinguish explicit `'public'` from the default.
+ * This means a trail that sets both `meta.internal = true` and
+ * `visibility: 'public'` will still be treated as internal — that
+ * combination has never been a documented override and, if the author
+ * really means "public", they should remove the legacy flag.
+ */
+const effectiveVisibility = (
+  trail: Trail<unknown, unknown, unknown>
+): 'public' | 'internal' => {
+  if (trail.visibility === 'internal') {
+    return 'internal';
+  }
+  return trail.meta?.['internal'] === true ? 'internal' : 'public';
+};
+
+const isVisibleToSurfaces = (
+  trail: Trail<unknown, unknown, unknown>,
+  include: readonly string[] | undefined
+): boolean =>
+  effectiveVisibility(trail) !== 'internal' ||
+  isExplicitInternalInclude(trail.id, include);
+
+const passesIncludeFilter = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.length === 0 ||
+  matchesAnyPattern(trailId, include);
+
+const passesIntentFilter = (
+  trail: Trail<unknown, unknown, unknown>,
+  intent: readonly Intent[] | undefined
+): boolean =>
+  intent === undefined || intent.length === 0 || intent.includes(trail.intent);
+
+export const shouldIncludeTrailForSurface = (
+  trail: Trail<unknown, unknown, unknown>,
+  options: SurfaceFilterOptions = {}
+): boolean => {
+  if (trail.activationSources.length > 0) {
+    return false;
+  }
+
+  const { exclude, include, intent } = options;
+  if (!isVisibleToSurfaces(trail, include)) {
+    return false;
+  }
+
+  if (matchesAnyPattern(trail.id, exclude)) {
+    return false;
+  }
+
+  return (
+    passesIncludeFilter(trail.id, include) && passesIntentFilter(trail, intent)
+  );
+};
+
+export const filterSurfaceTrails = (
+  trails: readonly Trail<unknown, unknown, unknown>[],
+  options: SurfaceFilterOptions = {}
+): Trail<unknown, unknown, unknown>[] =>
+  trails.filter((trail) => shouldIncludeTrailForSurface(trail, options));