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

package/src/store/accessor-protocol.ts

@@ -10,8 +10,8 @@
  * allowing the derivation helper to call accessors by convention.
  *
  * Required methods (`get`, `list`, `upsert`, `remove`) match the
- * connector-agnostic write contract every bound store must expose. Optional
- * methods (`insert`, `update`) are declared by tabular connectors that
+ * 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.
  */
@@ -25,7 +25,7 @@ export interface StoreAccessorProtocol<
   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 connector-agnostic contract. */
+  /** 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
@@ -34,13 +34,13 @@ export interface StoreAccessorProtocol<
    */
   remove(id: TId): Promise<{ readonly deleted: boolean }>;
   /**
-   * Optional insert — available on tabular connectors that distinguish
+   * 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 connectors. Returns
+   * 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`.
    */

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

@@ -1,17 +1,11 @@
 import type { Intent, Trail } from './trail.js';
+import type { SurfaceSelectionOptions } from './surface-derivation.js';
 
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
 
-export interface SurfaceFilterOptions {
-  /** Glob patterns that keep only matching trail IDs when provided. */
-  readonly include?: readonly string[] | undefined;
-  /** Glob patterns that remove matching trail IDs. */
-  readonly exclude?: readonly string[] | undefined;
-  /** Allowed intents for exposed trailheads. Empty arrays act as no filter. */
-  readonly intent?: readonly Intent[] | undefined;
-}
+export type SurfaceFilterOptions = SurfaceSelectionOptions;
 
 // ---------------------------------------------------------------------------
 // Glob matching
@@ -93,7 +87,7 @@ export const matchesTrailPattern = (
 };
 
 // ---------------------------------------------------------------------------
-// Trailhead filtering
+// Surface filtering
 // ---------------------------------------------------------------------------
 
 const matchesAnyPattern = (
@@ -114,7 +108,7 @@ const isExplicitInternalInclude = (
  * 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 trailheads.
+ * 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.
@@ -132,7 +126,7 @@ const effectiveVisibility = (
   return trail.meta?.['internal'] === true ? 'internal' : 'public';
 };
 
-const isVisibleToTrailheads = (
+const isVisibleToSurfaces = (
   trail: Trail<unknown, unknown, unknown>,
   include: readonly string[] | undefined
 ): boolean =>
@@ -157,12 +151,12 @@ export const shouldIncludeTrailForSurface = (
   trail: Trail<unknown, unknown, unknown>,
   options: SurfaceFilterOptions = {}
 ): boolean => {
-  if (trail.on.length > 0) {
+  if (trail.activationSources.length > 0) {
     return false;
   }
 
   const { exclude, include, intent } = options;
-  if (!isVisibleToTrailheads(trail, include)) {
+  if (!isVisibleToSurfaces(trail, include)) {
     return false;
   }