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

package/src/__tests__/validate-topo.test.ts

@@ -2,7 +2,10 @@ import { describe, expect, test } from 'bun:test';
 
 import { z } from 'zod';
 
-import { provision } from '../provision.js';
+import { deriveDraftReport, isDraftId } from '../draft.js';
+import { contour } from '../contour.js';
+import { validateEstablishedTopo } from '../validate-established-topo.js';
+import { resource } from '../resource.js';
 import { Result } from '../result.js';
 import { topo } from '../topo.js';
 import type { TopoIssue } from '../validate-topo.js';
@@ -19,6 +22,7 @@ const mockTrail = (
   id: string,
   overrides?: {
     crosses?: readonly string[];
+    contours?: readonly ReturnType<typeof contour>[];
     examples?: readonly {
       name: string;
       input: unknown;
@@ -26,20 +30,21 @@ const mockTrail = (
       error?: string;
     }[];
     output?: z.ZodType;
-    provisions?: readonly ReturnType<typeof provision>[];
+    resources?: readonly ReturnType<typeof resource>[];
   }
 ) => ({
   blaze: noop,
+  contours: Object.freeze([...(overrides?.contours ?? [])]),
   crosses: Object.freeze([...(overrides?.crosses ?? [])]),
   id,
   input: z.object({ name: z.string() }),
   kind: 'trail' as const,
-  provisions: Object.freeze([...(overrides?.provisions ?? [])]),
+  resources: Object.freeze([...(overrides?.resources ?? [])]),
   ...overrides,
 });
 
-const mockProvision = (id: string) =>
-  provision(id, {
+const mockResource = (id: string) =>
+  resource(id, {
     create: () => Result.ok({ id }),
   });
 
@@ -78,6 +83,17 @@ describe('validateTopo', () => {
   });
 
   describe('trail crossing', () => {
+    test('draft crossings are allowed in the authored graph', () => {
+      const app = topo('app', {
+        exportTrail: mockTrail('entity.export', {
+          crosses: ['_draft.entity.prepare'],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
     test('trail crossing a non-existent trail fails', () => {
       const app = topo('app', {
         onboard: mockTrail('entity.onboard', {
@@ -149,13 +165,25 @@ describe('validateTopo', () => {
     });
   });
 
-  describe('provision declarations', () => {
-    test('trail declaring a registered provision passes', () => {
-      const db = mockProvision('db.main');
+  describe('resource declarations', () => {
+    test('draft resource references are allowed in the authored graph', () => {
+      const db = mockResource('_draft.db.main');
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          resources: [db],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('trail declaring a registered resource passes', () => {
+      const db = mockResource('db.main');
       const app = topo('app', {
         db,
         show: mockTrail('entity.show', {
-          provisions: [db],
+          resources: [db],
         }),
       });
 
@@ -163,11 +191,11 @@ describe('validateTopo', () => {
       expect(result.isOk()).toBe(true);
     });
 
-    test('trail declaring a missing provision fails', () => {
-      const db = mockProvision('db.main');
+    test('trail declaring a missing resource fails', () => {
+      const db = mockResource('db.main');
       const app = topo('app', {
         show: mockTrail('entity.show', {
-          provisions: [db],
+          resources: [db],
         }),
       });
 
@@ -176,7 +204,7 @@ describe('validateTopo', () => {
 
       const issues = extractIssues(result);
       expect(issues).toHaveLength(1);
-      expect(issues[0]?.rule).toBe('provision-exists');
+      expect(issues[0]?.rule).toBe('resource-exists');
       expect(issues[0]?.message).toContain('db.main');
     });
   });
@@ -275,6 +303,68 @@ describe('validateTopo', () => {
     });
   });
 
+  describe('contour references', () => {
+    test('contour referencing a registered contour passes', () => {
+      const user = contour(
+        'user',
+        { id: z.string().uuid(), name: z.string() },
+        { identity: 'id' }
+      );
+      const post = contour(
+        'post',
+        { authorId: user.id(), id: z.string().uuid() },
+        { identity: 'id' }
+      );
+
+      const app = topo('app', { post, user });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('contour referencing a missing contour fails', () => {
+      const user = contour(
+        'user',
+        { id: z.string().uuid(), name: z.string() },
+        { identity: 'id' }
+      );
+      const post = contour(
+        'post',
+        { authorId: user.id(), id: z.string().uuid() },
+        { identity: 'id' }
+      );
+
+      // Only register post, not user — the reference is dangling
+      const app = topo('app', { post });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('contour-reference-exists');
+      expect(issues[0]?.message).toContain('user');
+    });
+
+    test('draft contour references are allowed', () => {
+      const draftUser = contour(
+        '_draft.user',
+        { id: z.string().uuid() },
+        { identity: 'id' }
+      );
+      const post = contour(
+        'post',
+        { authorId: draftUser.id(), id: z.string().uuid() },
+        { identity: 'id' }
+      );
+
+      const app = topo('app', { post });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+
   describe('event origins', () => {
     test('event with non-existent origin fails', () => {
       const app = topo('app', {
@@ -301,11 +391,11 @@ describe('validateTopo', () => {
   });
 
   test('collects multiple issues', () => {
-    const db = mockProvision('db.main');
+    const db = mockResource('db.main');
     const app = topo('app', {
       broken: mockTrail('entity.broken', { crosses: ['entity.missing'] }),
-      missingService: mockTrail('entity.missing-service', {
-        provisions: [db],
+      missingResource: mockTrail('entity.missing-resource', {
+        resources: [db],
       }),
       show: mockTrail('entity.show', {
         examples: [{ input: { name: 123 }, name: 'Bad' }],
@@ -319,4 +409,203 @@ describe('validateTopo', () => {
     const issues = extractIssues(result);
     expect(issues).toHaveLength(4);
   });
+
+  describe('signal origins', () => {
+    test('draft signal origins are allowed in the authored graph', () => {
+      const app = topo('app', {
+        updated: mockEvent('entity.updated', ['_draft.entity.prepare']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+});
+
+describe('draft state analysis', () => {
+  test('detects declared draft ids', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const analysis = deriveDraftReport(app);
+
+    expect(analysis.declaredDraftIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('_draft.entity.prepare')).toBe(true);
+    expect(analysis.findings.map((finding) => finding.rule)).toContain(
+      'draft-id'
+    );
+  });
+
+  test('propagates contamination through dependencies', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.prepare'],
+      }),
+      prepareTrail: mockTrail('entity.prepare', {
+        crosses: ['_draft.entity.store'],
+      }),
+    });
+
+    const analysis = deriveDraftReport(app);
+    const exportFinding = analysis.findings.find(
+      (finding) => finding.id === 'entity.export'
+    );
+
+    expect(analysis.contaminatedIds.has('entity.prepare')).toBe(true);
+    expect(analysis.contaminatedIds.has('entity.export')).toBe(true);
+    expect(exportFinding).toBeDefined();
+    expect(exportFinding?.rule).toBe('draft-contamination');
+  });
+
+  test('detects draft contour declarations and schema-reference contamination', () => {
+    const draftUser = contour(
+      '_draft.user',
+      {
+        id: z.string().uuid(),
+      },
+      { identity: 'id' }
+    );
+    const gist = contour(
+      'gist',
+      {
+        id: z.string().uuid(),
+        ownerId: draftUser.id(),
+      },
+      { identity: 'id' }
+    );
+
+    const app = topo('app', {
+      draftUser,
+      gist,
+    });
+
+    const analysis = deriveDraftReport(app);
+    expect(analysis.declaredDraftIds.has('_draft.user')).toBe(true);
+    expect(analysis.contaminatedIds.has('gist')).toBe(true);
+    expect(analysis.dependencies).toContainEqual({
+      fromId: 'gist',
+      kind: 'schema-reference',
+      toId: '_draft.user',
+    });
+  });
+
+  test('propagates contamination through trail contour dependencies', () => {
+    const draftUser = contour(
+      '_draft.user',
+      {
+        id: z.string().uuid(),
+      },
+      { identity: 'id' }
+    );
+
+    const app = topo('app', {
+      createGist: mockTrail('gist.create', {
+        contours: [draftUser],
+      }),
+      draftUser,
+    });
+
+    const analysis = deriveDraftReport(app);
+    const finding = analysis.findings.find(
+      (entry) => entry.id === 'gist.create'
+    );
+
+    expect(analysis.contaminatedIds.has('gist.create')).toBe(true);
+    expect(finding?.via).toBe('contour');
+  });
+});
+
+describe('validateEstablishedTopo', () => {
+  test('passes for an established topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+
+  test('fails when draft declarations remain', () => {
+    const app = topo('app', {
+      draftTrail: mockTrail('_draft.entity.prepare'),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-id');
+  });
+
+  test('fails when established trails depend on draft state', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['_draft.entity.prepare'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('draft-contamination');
+    expect(issues[0]?.message).toContain('entity.export');
+  });
+
+  test('fails when authored structural validation still fails', () => {
+    const app = topo('app', {
+      exportTrail: mockTrail('entity.export', {
+        crosses: ['entity.missing'],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('cross-exists');
+  });
+
+  test('fails when resource declarations are not established in the topo', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        resources: [mockResource('db.main')],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.rule).toBe('resource-exists');
+  });
+
+  test('allows authoring-only example issues outside projection checks', () => {
+    const app = topo('app', {
+      show: mockTrail('entity.show', {
+        examples: [
+          {
+            expected: { ok: true },
+            input: { name: 'test' },
+            name: 'Has expected',
+          },
+        ],
+      }),
+    });
+
+    const result = validateEstablishedTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+});
+
+describe('isDraftId', () => {
+  test('recognizes the reserved draft prefix', () => {
+    expect(isDraftId('_draft.entity.show')).toBe(true);
+    expect(isDraftId('entity.show')).toBe(false);
+  });
 });

package/src/__tests__/workspace.test.ts

@@ -7,7 +7,7 @@ import { NotFoundError } from '../errors.js';
 import {
   findWorkspaceRoot,
   isInsideWorkspace,
-  getRelativePath,
+  deriveRelativePath,
 } from '../workspace.js';
 
 // ---------------------------------------------------------------------------
@@ -162,22 +162,22 @@ describe('isInsideWorkspace', () => {
 });
 
 // ---------------------------------------------------------------------------
-// getRelativePath
+// deriveRelativePath
 // ---------------------------------------------------------------------------
 
-describe('getRelativePath', () => {
+describe('deriveRelativePath', () => {
   test('returns relative path from workspace root', () => {
     expect(
-      getRelativePath('/project/packages/core/src/index.ts', '/project')
+      deriveRelativePath('/project/packages/core/src/index.ts', '/project')
     ).toBe('packages/core/src/index.ts');
   });
 
   test('returns .. segments for paths outside workspace', () => {
-    const rel = getRelativePath('/other/file.ts', '/project');
+    const rel = deriveRelativePath('/other/file.ts', '/project');
     expect(rel.startsWith('..')).toBe(true);
   });
 
   test('returns empty string for the root itself', () => {
-    expect(getRelativePath('/project', '/project')).toBe('');
+    expect(deriveRelativePath('/project', '/project')).toBe('');
   });
 });

package/src/__tests__/zod-wrappers.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import {
+  stripDefaultsFromShape,
+  stripDefaultWrappers,
+} from '../internal/zod-wrappers.js';
+
+describe('stripDefaultWrappers', () => {
+  test('drops plain default wrappers', () => {
+    const withDefault = z.string().default('x');
+    const stripped = stripDefaultWrappers(withDefault);
+
+    expect(stripped.def.type).toBe('string');
+    // Feeding an undefined through the stripped schema no longer
+    // materializes the default.
+    expect(stripped.safeParse().success).toBe(false);
+    expect(stripped.safeParse('value').success).toBe(true);
+  });
+
+  test('drops optional + default layers together', () => {
+    const schema = z.string().optional().default('x');
+    const stripped = stripDefaultWrappers(schema);
+
+    // Every wrapper around the underlying string is gone — optional is
+    // dropped on purpose because downstream `.partial()` calls re-add it.
+    expect(stripped.def.type).toBe('string');
+    expect(stripped.safeParse().success).toBe(false);
+    expect(stripped.safeParse('value').success).toBe(true);
+  });
+
+  test('preserves nullable constraints through the strip', () => {
+    const schema = z.string().nullable().default('x');
+    const stripped = stripDefaultWrappers(schema);
+
+    // Default is gone; null is still a legal input.
+    expect(stripped.def.type).toBe('nullable');
+    expect(stripped.safeParse(null).success).toBe(true);
+    expect(stripped.safeParse('value').success).toBe(true);
+  });
+
+  test('is load-bearing for .partial() on both call sites', () => {
+    const shape = {
+      author: z.string().optional().default('anon'),
+      title: z.string().default('untitled'),
+    };
+    const schema = z.object(shape);
+
+    // Both the store `deriveUpdateSchema` helper and the core derive-trail
+    // `toPartialSchema` helper compose the same pattern: extend the schema
+    // with the stripped shape, then call `.partial()`. Both call sites
+    // must produce a schema that accepts an empty object without
+    // re-materializing defaults.
+    const stripped = stripDefaultsFromShape(schema);
+    const partial = schema.extend(stripped).partial();
+
+    const parsed = partial.parse({});
+    expect(parsed).toEqual({});
+    expect('author' in parsed).toBe(false);
+    expect('title' in parsed).toBe(false);
+  });
+});

package/src/branded.ts

@@ -120,7 +120,7 @@ export const shortId = (length = 8): string => {
  * Produce a deterministic hex hash from an input string.
  * Uses a simple FNV-1a 32-bit hash — good enough for non-cryptographic IDs.
  */
-export const hashId = (input: string): string => {
+export const deriveIdHash = (input: string): string => {
   // FNV offset basis
   let hash = 2_166_136_261;
   for (let i = 0; i < input.length; i += 1) {

package/src/context.ts

@@ -1,10 +1,26 @@
-import { createProvisionLookup } from './provision.js';
-import type { TrailContext, TrailContextInit } from './types.js';
+import { createResourceLookup } from './resource.js';
+import type { TrailContext, TrailContextInit, TraceFn } from './types.js';
 
 type MutableTrailContext = {
   -readonly [K in keyof TrailContext]: TrailContext[K];
 };
 
+/**
+ * Default passthrough `trace` used when a context is built outside
+ * `executeTrail`. `executeTrail` replaces this with a real sink-writing
+ * implementation. The passthrough runs `fn` without recording anything so
+ * direct `createTrailContext()` callers (tests, ad-hoc compositions) don't
+ * crash when invoking `ctx.trace(...)`.
+ *
+ * Declared `async` so both synchronous throws and async rejections from `fn`
+ * propagate as a rejected promise to the caller — matching the real
+ * sink-writing implementation's error semantics.
+ */
+export const passthroughTrace: TraceFn = async <T>(
+  _label: string,
+  fn: () => T | Promise<T>
+): Promise<T> => await fn();
+
 /**
  * Create a TrailContext with sensible defaults.
  *
@@ -20,9 +36,13 @@ export const createTrailContext = (
     cwd: process.cwd(),
     env: process.env as Record<string, string | undefined>,
     requestId: Bun.randomUUIDv7(),
+    trace: passthroughTrace,
     ...overrides,
   } as MutableTrailContext;
-  const lookup = overrides?.provision ?? createProvisionLookup(() => ctx);
-  ctx.provision = lookup;
+  const lookup = overrides?.resource ?? createResourceLookup(() => ctx);
+  ctx.resource = lookup;
+  if (ctx.trace === undefined) {
+    ctx.trace = passthroughTrace;
+  }
   return ctx;
 };