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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @ontrails/core
 
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- 99523f2: Clean up resource context naming in shipped source and examples so resource
+  factories consistently use resource vocabulary.
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- 851a2a3: Derive trail caller and blaze input types from the authored input schema while keeping one public input contract.
+
 ## 1.0.0-beta.19
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.21",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/resource.ts

@@ -9,7 +9,7 @@ import type { z } from 'zod';
  *
  * Resources are app-level singletons, so they intentionally do not receive
  * the full per-request TrailContext. When a resource declares a `config` schema,
- * the validated config is passed as `svc.config`.
+ * the validated config is passed as `resourceCtx.config`.
  */
 export type ResourceContext<C = unknown> = Pick<
   TrailContext,
@@ -32,7 +32,7 @@ export interface ResourceUnmockable {
 export interface ResourceSpec<T, C = unknown> {
   /** Create the resource instance from stable process-scoped context. */
   readonly create: (
-    svc: ResourceContext<C>
+    resourceCtx: ResourceContext<C>
   ) => Result<T, Error> | Promise<Result<T, Error>>;
   /** Config schema — when present, config is validated and passed to `create`. */
   readonly config?: z.ZodType<C> | undefined;

package/src/trail.ts

@@ -86,6 +86,102 @@ export type BlazeInput<I, CI> = [CI] extends [never] ? I : I & CI;
 
 type TrailRef = string | { readonly id: string };
 
+type ComposeSchemaOutput<TSchema extends z.ZodType | undefined> =
+  TSchema extends z.ZodType ? z.output<TSchema> : never;
+
+type SchemaOwnedTrailSpec<
+  TInputSchema extends z.ZodType,
+  O,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+  C extends readonly TrailRef[] | undefined = undefined,
+> = Omit<
+  TrailSpec<
+    z.output<TInputSchema>,
+    O,
+    ComposeSchemaOutput<TComposeInputSchema>,
+    C
+  >,
+  'blaze' | 'composeInput' | 'detours' | 'examples' | 'input' | 'versions'
+> & {
+  /** Zod schema for validating caller input and materializing blaze input. */
+  readonly input: TInputSchema;
+  /** The pure function receives schema-materialized input after validation/defaults. */
+  readonly blaze: Implementation<
+    BlazeInput<
+      z.output<TInputSchema>,
+      ComposeSchemaOutput<TComposeInputSchema>
+    >,
+    O,
+    ComposeContextFor<C>
+  >;
+  /** Named examples use caller-side input; schema defaults may be omitted. */
+  readonly examples?:
+    | readonly TrailExample<z.input<TInputSchema>, O>[]
+    | undefined;
+  /** Recovery paths see the same materialized input as the blaze. */
+  readonly detours?:
+    | readonly Detour<z.output<TInputSchema>, O, TrailsError>[]
+    | undefined;
+  /** Composition-only schema, merged internally for ctx.compose() calls. */
+  readonly composeInput?: TComposeInputSchema | undefined;
+  /** Explicit historical trail versions. Current stays top-level. */
+  readonly versions?: TrailVersions<z.output<TInputSchema>, O> | undefined;
+};
+
+type SchemaOwnedOutputTrailSpec<
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+  C extends readonly TrailRef[] | undefined = undefined,
+> = Omit<
+  SchemaOwnedTrailSpec<
+    TInputSchema,
+    z.output<TOutputSchema>,
+    TComposeInputSchema,
+    C
+  >,
+  'output'
+> & {
+  readonly output: TOutputSchema;
+};
+
+type SchemaOwnedTrail<
+  TInputSchema extends z.ZodType,
+  O,
+  TComposeInputSchema extends z.ZodType | undefined,
+> = Trail<
+  z.output<TInputSchema>,
+  O,
+  ComposeSchemaOutput<TComposeInputSchema>
+> & {
+  readonly input: TInputSchema;
+  readonly composeInput?: TComposeInputSchema | undefined;
+};
+
+type LegacyOutputTrailSpec<
+  I,
+  O,
+  CI,
+  C extends readonly TrailRef[] | undefined,
+> = Omit<TrailSpec<I, O, CI, C>, 'blaze' | 'output'> & {
+  readonly blaze: Implementation<
+    BlazeInput<I, CI>,
+    NoInfer<O>,
+    ComposeContextFor<C>
+  >;
+  readonly output: z.ZodType<O>;
+};
+
+type LegacyOutputlessTrailSpec<
+  I,
+  O,
+  CI,
+  C extends readonly TrailRef[] | undefined,
+> = Omit<TrailSpec<I, O, CI, C>, 'blaze' | 'output'> & {
+  readonly blaze: Implementation<BlazeInput<I, CI>, O, ComposeContextFor<C>>;
+  readonly output?: undefined;
+};
+
 // ---------------------------------------------------------------------------
 // Trail versioning
 // ---------------------------------------------------------------------------
@@ -1015,18 +1111,75 @@ const normalizeCollections = <
  * });
  * ```
  */
+export function trail<
+  const TInputSchema extends z.ZodType,
+  const TOutputSchema extends z.ZodType,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  id: string,
+  spec: SchemaOwnedOutputTrailSpec<
+    TInputSchema,
+    TOutputSchema,
+    TComposeInputSchema,
+    C
+  >
+): SchemaOwnedTrail<TInputSchema, z.output<TOutputSchema>, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  const TOutputSchema extends z.ZodType,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  spec: SchemaOwnedOutputTrailSpec<
+    TInputSchema,
+    TOutputSchema,
+    TComposeInputSchema,
+    C
+  > & {
+    readonly id: string;
+  }
+): SchemaOwnedTrail<TInputSchema, z.output<TOutputSchema>, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  O,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  id: string,
+  spec: SchemaOwnedTrailSpec<TInputSchema, O, TComposeInputSchema, C>
+): SchemaOwnedTrail<TInputSchema, O, TComposeInputSchema>;
+export function trail<
+  const TInputSchema extends z.ZodType,
+  O,
+  const TComposeInputSchema extends z.ZodType | undefined = undefined,
+  const C extends readonly TrailRef[] | undefined = undefined,
+>(
+  spec: SchemaOwnedTrailSpec<TInputSchema, O, TComposeInputSchema, C> & {
+    readonly id: string;
+  }
+): SchemaOwnedTrail<TInputSchema, O, TComposeInputSchema>;
 export function trail<
   I,
   O,
   CI = never,
   const C extends readonly TrailRef[] | undefined = undefined,
->(id: string, spec: TrailSpec<I, O, CI, C>): Trail<I, O, CI>;
+>(
+  id: string,
+  spec:
+    | LegacyOutputTrailSpec<I, O, CI, C>
+    | LegacyOutputlessTrailSpec<I, O, CI, C>
+): Trail<I, O, CI>;
 export function trail<
   I,
   O,
   CI = never,
   const C extends readonly TrailRef[] | undefined = undefined,
->(spec: TrailSpec<I, O, CI, C> & { readonly id: string }): Trail<I, O, CI>;
+>(
+  spec:
+    | (LegacyOutputTrailSpec<I, O, CI, C> & { readonly id: string })
+    | (LegacyOutputlessTrailSpec<I, O, CI, C> & { readonly id: string })
+): Trail<I, O, CI>;
 export function trail<
   I,
   O,

package/src/trails/ingest.ts

@@ -114,16 +114,17 @@ export const ingest = <
     id,
     transform
   );
-  const baseTrail = trail(id, {
+  const baseSpec = {
     ...trailSpec,
-    blaze: baseBlaze,
+    blaze: baseBlaze as TrailSpec<unknown, unknown>['blaze'],
     examples: deriveExamples(schema as ExampleBearingSchema<TSchema>, signalId),
     fires: [signal],
-    input: schema as z.ZodType<SchemaValue<TSchema>>,
+    input: schema as z.ZodType<unknown>,
     intent: 'write',
     output: z.void(),
     pattern: 'ingest',
-  }) as Trail<SchemaValue<TSchema>, void>;
+  } as TrailSpec<unknown, unknown>;
+  const baseTrail = trail(id, baseSpec) as Trail<SchemaValue<TSchema>, void>;
 
   if (verify === undefined) {
     return baseTrail;

package/src/type-utils.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Result } from './result.js';
-import type { AnyTrail } from './trail.js';
+import type { AnyTrail, Trail } from './trail.js';
 import type { Implementation } from './types.js';
 import type { z } from 'zod';
 
@@ -13,11 +13,31 @@ import type { z } from 'zod';
 
 /* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
 
+type SchemaInputOrFallback<TSchema extends z.ZodType, TFallback> =
+  unknown extends z.input<TSchema> ? TFallback : z.input<TSchema>;
+
+type ComposeSchemaOf<T extends AnyTrail> = T extends {
+  readonly composeInput?: (infer TComposeSchema) | undefined;
+}
+  ? NonNullable<TComposeSchema>
+  : never;
+
+type ComposeInputPart<T extends AnyTrail> =
+  ComposeSchemaOf<T> extends z.ZodType
+    ? T extends Trail<any, any, infer CI>
+      ? SchemaInputOrFallback<ComposeSchemaOf<T>, CI>
+      : z.input<ComposeSchemaOf<T>>
+    : T extends Trail<any, any, infer CI>
+      ? CI
+      : never;
+
 /** Extract the input type from a Trail. */
 export type TrailInput<T extends AnyTrail> = T extends {
-  readonly input: z.ZodType<infer I>;
+  readonly input: infer TInputSchema extends z.ZodType;
 }
-  ? I
+  ? T extends Trail<infer I, any, any>
+    ? SchemaInputOrFallback<TInputSchema, I>
+    : z.input<TInputSchema>
   : never;
 
 /** Extract the output type from a Trail. */
@@ -35,12 +55,11 @@ export type TrailOutput<T extends AnyTrail> = T extends {
  * merges both schemas so the compiler enforces the full shape at the call
  * site. Falls back to plain `TrailInput<T>` when no `composeInput` exists.
  */
-export type ComposeInput<T extends AnyTrail> =
-  NonNullable<T['composeInput']> extends z.ZodType<infer CI>
-    ? [CI] extends [never]
-      ? TrailInput<T>
-      : TrailInput<T> & CI
-    : TrailInput<T>;
+export type ComposeInput<T extends AnyTrail> = [ComposeInputPart<T>] extends [
+  never,
+]
+  ? TrailInput<T>
+  : TrailInput<T> & ComposeInputPart<T>;
 
 /**
  * Extracts the full `Result<Output, Error>` type from a trail definition.