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

package/src/resource.ts

@@ -18,6 +18,11 @@ export type ResourceContext<C = unknown> = Pick<
   readonly config: C;
 };
 
+/** Explicit marker for resources that intentionally cannot provide a mock. */
+export interface ResourceUnmockable {
+  readonly reason: string;
+}
+
 /**
  * Everything needed to describe a resource before a factory is introduced.
  *
@@ -31,7 +36,7 @@ export interface ResourceSpec<T, C = unknown> {
   ) => Result<T, Error> | Promise<Result<T, Error>>;
   /** Config schema — when present, config is validated and passed to `create`. */
   readonly config?: z.ZodType<C> | undefined;
-  /** Optional cleanup performed when the hosting trailhead shuts down. */
+  /** Optional cleanup performed when the host application shuts down. */
   readonly dispose?: ((resource: T) => void | Promise<void>) | undefined;
   /** Optional operational readiness probe for introspection tooling. */
   readonly health?:
@@ -41,6 +46,8 @@ export interface ResourceSpec<T, C = unknown> {
     | undefined;
   /** Optional test factory used by higher-level helpers. */
   readonly mock?: (() => T | Promise<T>) | undefined;
+  /** Document why this resource intentionally cannot provide a test mock. */
+  readonly unmockable?: ResourceUnmockable | undefined;
   /** Human-readable description. */
   readonly description?: string | undefined;
   /** Arbitrary meta for tooling and filtering. */
@@ -114,6 +121,19 @@ export const resource = <T>(id: string, spec: ResourceSpec<T>): Resource<T> =>
         `Resource "${id}" is invalid because resource ids may not contain ":"`
       );
     }
+    if (spec.mock !== undefined && spec.unmockable !== undefined) {
+      throw new InternalError(
+        `Resource "${id}" cannot define both mock and unmockable`
+      );
+    }
+    if (
+      spec.unmockable !== undefined &&
+      spec.unmockable.reason.trim().length === 0
+    ) {
+      throw new InternalError(
+        `Resource "${id}" is invalid because unmockable.reason must not be empty`
+      );
+    }
 
     return Object.freeze({
       ...spec,

package/src/result.ts

@@ -4,6 +4,24 @@
 
 import { InternalError, ValidationError } from './errors.js';
 
+export const resultAccessorNames = [
+  'error',
+  'flatMap',
+  'isErr',
+  'isOk',
+  'map',
+  'mapErr',
+  'match',
+  'unwrap',
+  'unwrapOr',
+  'value',
+] as const satisfies readonly (
+  | keyof Ok<unknown, unknown>
+  | keyof Err<unknown>
+)[];
+
+export type ResultAccessorName = (typeof resultAccessorNames)[number];
+
 class Ok<T, E> {
   readonly value: T;
 

package/src/run.ts

@@ -1,5 +1,5 @@
 /**
- * Headless trail execution without mounting a trailhead.
+ * Headless trail execution without surface registration.
  *
  * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
  * Returns a `Result` and never throws.
@@ -23,7 +23,7 @@ export type RunOptions = ExecuteTrailOptions;
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a trail by ID from a topo without mounting a trailhead.
+ * Execute a trail by ID from a topo without registering it on a surface.
  *
  * Resolves the trail from the topo, then runs it through the standard
  * `executeTrail` pipeline with `topo` threaded so `ctx.fire()` is bound