@ontrails/core 0.2.0

package/src/signal-ref.ts

@@ -0,0 +1,111 @@
+import type { AnySignal, Signal } from './signal.js';
+
+export interface LateBoundSignalRef {
+  readonly kind: 'store-derived';
+  readonly token: string;
+}
+
+export interface LateBoundSignalMarker {
+  readonly displayId: string;
+  readonly token: string;
+}
+
+const LATE_BOUND_SIGNAL_REF = Symbol('trails.late-bound-signal-ref');
+const LATE_BOUND_SIGNAL_BOUND = Symbol('trails.late-bound-signal-bound');
+const LATE_BOUND_SIGNAL_MARKER_PREFIX = '@@trails:late-bound-signal-ref:';
+
+const defineLateBoundSignalRef = <T extends object>(
+  value: T,
+  ref: LateBoundSignalRef
+): T => {
+  Object.defineProperty(value, LATE_BOUND_SIGNAL_REF, {
+    configurable: false,
+    enumerable: false,
+    value: ref,
+    writable: false,
+  });
+  return value;
+};
+
+const defineLateBoundSignalBound = <T extends object>(value: T): T => {
+  Object.defineProperty(value, LATE_BOUND_SIGNAL_BOUND, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false,
+  });
+  return value;
+};
+
+export const isBoundLateBoundSignal = (
+  signal: Pick<AnySignal, 'id'> | undefined
+): boolean =>
+  signal !== undefined &&
+  (signal as Record<PropertyKey, unknown>)[LATE_BOUND_SIGNAL_BOUND] === true;
+
+export const getLateBoundSignalRef = (
+  signal: Pick<AnySignal, 'id'> | undefined
+): LateBoundSignalRef | undefined =>
+  signal === undefined
+    ? undefined
+    : ((signal as Record<PropertyKey, unknown>)[LATE_BOUND_SIGNAL_REF] as
+        | LateBoundSignalRef
+        | undefined);
+
+export const attachLateBoundSignalRef = <T>(
+  signal: Signal<T>,
+  ref: LateBoundSignalRef
+): Signal<T> =>
+  Object.freeze(
+    defineLateBoundSignalRef(
+      {
+        ...signal,
+      },
+      ref
+    )
+  ) as Signal<T>;
+
+export const cloneSignalWithId = <T>(
+  signal: Signal<T>,
+  id: string
+): Signal<T> => {
+  const clone = {
+    ...signal,
+    id,
+  };
+  const ref = getLateBoundSignalRef(signal);
+  return Object.freeze(
+    ref
+      ? defineLateBoundSignalBound(defineLateBoundSignalRef(clone, ref))
+      : clone
+  ) as Signal<T>;
+};
+
+export const createLateBoundSignalMarker = (
+  ref: LateBoundSignalRef,
+  displayId: string
+): string =>
+  `${LATE_BOUND_SIGNAL_MARKER_PREFIX}${encodeURIComponent(ref.token)}:${displayId}`;
+
+export const parseLateBoundSignalMarker = (
+  value: string
+): LateBoundSignalMarker | null => {
+  if (!value.startsWith(LATE_BOUND_SIGNAL_MARKER_PREFIX)) {
+    return null;
+  }
+
+  const remainder = value.slice(LATE_BOUND_SIGNAL_MARKER_PREFIX.length);
+  const separator = remainder.indexOf(':');
+  if (separator <= 0 || separator === remainder.length - 1) {
+    return null;
+  }
+
+  try {
+    const token = decodeURIComponent(remainder.slice(0, separator));
+    return token.length === 0
+      ? null
+      : { displayId: remainder.slice(separator + 1), token };
+  } catch {
+    return null;
+  }
+};

package/src/signal.ts

@@ -0,0 +1,104 @@
+/**
+ * Signal — a named payload schema with optional provenance meta.
+ */
+
+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)
+// ---------------------------------------------------------------------------
+
+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;
+  /** Reserved for future signal-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+// ---------------------------------------------------------------------------
+// Shape (output of the factory)
+// ---------------------------------------------------------------------------
+
+export interface Signal<T> {
+  readonly id: string;
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a signal definition.
+ *
+ * A signal is a named payload schema describing something that happened.
+ * Returns a frozen object with `kind: "signal"` and all spec fields.
+ */
+export function signal<T>(id: string, spec: SignalSpec<T>): Signal<T>;
+export function signal<T>(
+  spec: SignalSpec<T> & { readonly id: string }
+): Signal<T>;
+export function signal<T>(
+  idOrSpec: string | (SignalSpec<T> & { readonly id: string }),
+  maybeSpec?: SignalSpec<T>
+): 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,
+    meta: resolvedSpec.meta,
+    payload: resolvedSpec.payload,
+  });
+}
+
+/** Existential type for heterogeneous signal collections */
+export type AnySignal = Signal<unknown>;

package/src/store/accessor-protocol.ts

@@ -0,0 +1,56 @@
+/**
+ * Structural accessor protocol used by `deriveTrail()` to synthesize default
+ * implementations 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 implementations 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 implementations 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 entity 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,248 @@
+import type { TrailExample, TrailExampleSignalAssertion } from './trail.js';
+
+export interface StructuredTrailExampleProvenance {
+  readonly source: 'trail.examples' | 'trail.versions.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 derived 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 deriveSignalAssertion = (
+  assertion: TrailExampleSignalAssertion
+): StructuredTrailExampleSignalAssertion | undefined => {
+  const signalId = signalIdFromAssertion(assertion);
+  if (signalId === undefined) {
+    return undefined;
+  }
+
+  const derived: Record<string, unknown> = { signalId };
+  if (assertion.payload !== undefined) {
+    const payload = toJsonSerializable(assertion.payload);
+    if (payload === undefined) {
+      return undefined;
+    }
+    derived['payload'] = payload;
+  }
+  if (assertion.payloadMatch !== undefined) {
+    const payloadMatch = toJsonSerializable(assertion.payloadMatch);
+    if (payloadMatch === undefined) {
+      return undefined;
+    }
+    derived['payloadMatch'] = payloadMatch;
+  }
+  if (assertion.times !== undefined) {
+    derived['times'] = assertion.times;
+  }
+  return Object.freeze(
+    derived
+  ) as unknown as StructuredTrailExampleSignalAssertion;
+};
+
+const deriveSignalAssertions = (
+  assertions: readonly TrailExampleSignalAssertion[] | undefined
+): readonly StructuredTrailExampleSignalAssertion[] | undefined => {
+  if (assertions === undefined) {
+    return undefined;
+  }
+  const derived = assertions.map(deriveSignalAssertion);
+  if (derived.some((assertion) => assertion === undefined)) {
+    return undefined;
+  }
+  return Object.freeze(derived as StructuredTrailExampleSignalAssertion[]);
+};
+
+const deriveExample = (
+  example: TrailExample<unknown, unknown>,
+  provenance: StructuredTrailExampleProvenance
+): StructuredTrailExample | undefined => {
+  const input = toJsonSerializable(example.input);
+  if (input === undefined) {
+    return undefined;
+  }
+
+  const derived: Record<string, unknown> = {
+    input,
+    kind: example.error === undefined ? 'success' : 'error',
+    name: example.name,
+    provenance,
+  };
+
+  if (example.description !== undefined) {
+    derived['description'] = example.description;
+  }
+  if (example.expected !== undefined) {
+    const expected = toJsonSerializable(example.expected);
+    if (expected === undefined) {
+      return undefined;
+    }
+    derived['expected'] = expected;
+  }
+  if (example.expectedMatch !== undefined) {
+    const expectedMatch = toJsonSerializable(example.expectedMatch);
+    if (expectedMatch === undefined) {
+      return undefined;
+    }
+    derived['expectedMatch'] = expectedMatch;
+  }
+  if (example.error !== undefined) {
+    derived['error'] = example.error;
+  }
+  if (example.signals !== undefined) {
+    const signals = deriveSignalAssertions(example.signals);
+    if (signals === undefined) {
+      return undefined;
+    }
+    derived['signals'] = signals;
+  }
+
+  return Object.freeze(derived) as unknown as StructuredTrailExample;
+};
+
+const deriveSignalExample = (
+  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,
+  options?: { readonly provenance?: StructuredTrailExampleProvenance }
+): readonly StructuredTrailExample[] | undefined => {
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  const provenance = options?.provenance ?? { source: 'trail.examples' };
+  const derived = examples
+    .map((example) => deriveExample(example, provenance))
+    .filter(
+      (example): example is StructuredTrailExample => example !== undefined
+    );
+
+  return derived.length > 0 ? Object.freeze(derived) : undefined;
+};
+
+export const deriveStructuredSignalExamples = (
+  examples: readonly unknown[] | undefined
+): readonly StructuredSignalExample[] | undefined => {
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  const derived = examples
+    .map(deriveSignalExample)
+    .filter(
+      (example): example is StructuredSignalExample => example !== undefined
+    );
+
+  return derived.length > 0 ? Object.freeze(derived) : 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 derivation. */
+  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),
+      },
+    },
+  };
+};