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

package/dist/validate-topo.js

@@ -5,7 +5,9 @@
  * references, and output schema completeness. Returns a Result with all
  * issues collected into a single ValidationError.
  */
+import { getContourReferences } from './contour.js';
 import { ValidationError } from './errors.js';
+import { isDraftId } from './draft.js';
 import { Result } from './result.js';
 import { validateInput } from './validation.js';
 // ---------------------------------------------------------------------------
@@ -71,7 +73,7 @@ const checkCrosses = (trails, topo) => {
                     trailId: id,
                 });
             }
-            else if (!topo.has(crossedId)) {
+            else if (!topo.has(crossedId) && !isDraftId(crossedId)) {
                 issues.push({
                     message: `Crosses "${crossedId}" which is not in the topo`,
                     rule: 'cross-exists',
@@ -83,14 +85,15 @@ const checkCrosses = (trails, topo) => {
     issues.push(...detectCrossCycles(trails));
     return issues;
 };
-const checkProvisions = (trails, topo) => {
+const checkResources = (trails, topo) => {
     const issues = [];
     for (const [id, trail] of trails) {
-        for (const declaredProvision of trail.provisions) {
-            if (!topo.hasProvision(declaredProvision.id)) {
+        for (const declaredResource of trail.resources) {
+            if (!topo.hasResource(declaredResource.id) &&
+                !isDraftId(declaredResource.id)) {
                 issues.push({
-                    message: `Provision "${declaredProvision.id}" is not in the topo`,
-                    rule: 'provision-exists',
+                    message: `Resource "${declaredResource.id}" is not in the topo`,
+                    rule: 'resource-exists',
                     trailId: id,
                 });
             }
@@ -136,7 +139,7 @@ const checkSignalOrigins = (signals, topo) => {
             continue;
         }
         for (const originId of evt.from) {
-            if (!topo.has(originId)) {
+            if (!topo.has(originId) && !isDraftId(originId)) {
                 issues.push({
                     message: `Signal origin "${originId}" is not in the topo`,
                     rule: 'signal-origin-exists',
@@ -147,6 +150,21 @@ const checkSignalOrigins = (signals, topo) => {
     }
     return issues;
 };
+const checkContourReferences = (contours, topo) => {
+    const issues = [];
+    for (const [name, contourDef] of contours) {
+        for (const ref of getContourReferences(contourDef)) {
+            if (!topo.hasContour(ref.contour) && !isDraftId(ref.contour)) {
+                issues.push({
+                    message: `Contour "${name}" references "${ref.contour}" which is not in the topo`,
+                    rule: 'contour-reference-exists',
+                    trailId: name,
+                });
+            }
+        }
+    }
+    return issues;
+};
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -160,7 +178,8 @@ const checkSignalOrigins = (signals, topo) => {
 export const validateTopo = (topo) => {
     const issues = [
         ...checkCrosses(topo.trails, topo),
-        ...checkProvisions(topo.trails, topo),
+        ...checkResources(topo.trails, topo),
+        ...checkContourReferences(topo.contours, topo),
         ...checkExamples(topo.trails),
         ...checkSignalOrigins(topo.signals, topo),
     ];

package/dist/validate-topo.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -21,5 +21,5 @@ export declare const isInsideWorkspace: (filePath: string, workspaceRoot: string
 /**
  * Returns the relative path from `workspaceRoot` to `filePath`.
  */
-export declare const getRelativePath: (filePath: string, workspaceRoot: string) => string;
+export declare const deriveRelativePath: (filePath: string, workspaceRoot: string) => string;
 //# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiBrC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAqBvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,OAGF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,MAA6D,CAAC"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiBrC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAqBvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,OAGF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,MAA6D,CAAC"}

package/dist/workspace.js

@@ -53,5 +53,5 @@ export const isInsideWorkspace = (filePath, workspaceRoot) => {
 /**
  * Returns the relative path from `workspaceRoot` to `filePath`.
  */
-export const getRelativePath = (filePath, workspaceRoot) => relative(resolve(workspaceRoot), resolve(filePath));
+export const deriveRelativePath = (filePath, workspaceRoot) => relative(resolve(workspaceRoot), resolve(filePath));
 //# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,yEAAyE;AACzE,MAAM,kBAAkB,GAAG,KAAK,EAAE,GAAW,EAAoB,EAAE;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACvC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,YAAY,IAAI,GAAG,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,QAAiB,EACuB,EAAE;IAC1C,IAAI,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAEjD,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAEhC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,aAAa,CACf,iCAAiC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,CAC9D,CACF,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,QAAgB,EAChB,aAAqB,EACZ,EAAE;IACX,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACjE,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAAgB,EAChB,aAAqB,EACb,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,yEAAyE;AACzE,MAAM,kBAAkB,GAAG,KAAK,EAAE,GAAW,EAAoB,EAAE;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACvC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,YAAY,IAAI,GAAG,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,QAAiB,EACuB,EAAE;IAC1C,IAAI,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAEjD,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAEhC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,aAAa,CACf,iCAAiC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,CAC9D,CACF,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,QAAgB,EAChB,aAAqB,EACZ,EAAE;IACX,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACjE,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,QAAgB,EAChB,aAAqB,EACb,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./internal/cross-batch": "./src/internal/cross-batch.ts",
+    "./internal/signal-ref": "./src/internal/signal-ref.ts",
+    "./internal/topo-snapshots": "./src/internal/topo-snapshots.ts",
+    "./internal/topo-store": "./src/internal/topo-store.ts",
+    "./internal/tracing": "./src/internal/tracing.ts",
+    "./internal/trails-db": "./src/internal/trails-db.ts",
+    "./internal/zod-wrappers": "./src/internal/zod-wrappers.ts",
     "./patterns": "./src/patterns/index.ts",
     "./redaction": "./src/redaction/index.ts",
+    "./store": "./src/store/index.ts",
+    "./trails": "./src/trails/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/__tests__/branded.test.ts

@@ -8,7 +8,7 @@ import {
   nonEmptyString,
   positiveInt,
   shortId,
-  hashId,
+  deriveIdHash,
 } from '../branded';
 
 describe('branded', () => {
@@ -131,18 +131,18 @@ describe('branded', () => {
     });
   });
 
-  describe('hashId()', () => {
+  describe('deriveIdHash()', () => {
     test('returns a hex string', () => {
-      const id = hashId('test');
+      const id = deriveIdHash('test');
       expect(id).toMatch(/^[0-9a-f]{8}$/);
     });
 
     test('is deterministic', () => {
-      expect(hashId('hello')).toBe(hashId('hello'));
+      expect(deriveIdHash('hello')).toBe(deriveIdHash('hello'));
     });
 
     test('different inputs produce different outputs', () => {
-      expect(hashId('a')).not.toBe(hashId('b'));
+      expect(deriveIdHash('a')).not.toBe(deriveIdHash('b'));
     });
   });
 });

package/src/__tests__/context.test.ts

@@ -57,14 +57,14 @@ describe('createTrailContext', () => {
     expect(ctx.extensions?.['nested']).toEqual({ key: 'value' });
   });
 
-  test('provides a provision accessor backed by extensions', () => {
+  test('provides a resource accessor backed by extensions', () => {
     const widget = { id: 'widget-1' };
     const ctx = createTrailContext({
       extensions: { 'widget.main': widget },
     });
 
-    expect(ctx.provision('widget.main')).toBe(widget);
-    expect(ctx.provision<{ id: string }>({ id: 'widget.main' }).id).toBe(
+    expect(ctx.resource('widget.main')).toBe(widget);
+    expect(ctx.resource<{ id: string }>({ id: 'widget.main' }).id).toBe(
       'widget-1'
     );
   });

package/src/__tests__/contour.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import {
+  contour,
+  getContourIdMetadata,
+  getContourReferences,
+} from '../contour.js';
+
+const user = contour(
+  'user',
+  {
+    email: z.string().email(),
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  {
+    examples: [
+      {
+        email: 'ada@example.com',
+        id: '550e8400-e29b-41d4-a716-446655440000',
+        name: 'Ada',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+const gist = contour(
+  'gist',
+  {
+    id: z.string().uuid(),
+    ownerId: user.id(),
+    title: z.string(),
+  },
+  { identity: 'id' }
+);
+
+type UserId = z.infer<ReturnType<typeof user.id>>;
+type GistId = z.infer<ReturnType<typeof gist.id>>;
+
+const _ownerId: z.infer<typeof gist.shape.ownerId> = {} as UserId;
+// @ts-expect-error distinct contour ids should not be assignable
+const _mixedIds: UserId = {} as GistId;
+
+describe('contour()', () => {
+  describe('basics', () => {
+    test("returns kind 'contour'", () => {
+      expect(user.kind).toBe('contour');
+    });
+
+    test('preserves the contour name', () => {
+      expect(user.name).toBe('user');
+    });
+
+    test('preserves schema behavior', () => {
+      const parsed = user.safeParse({
+        email: 'ada@example.com',
+        id: '550e8400-e29b-41d4-a716-446655440000',
+        name: 'Ada',
+      });
+
+      expect(parsed.success).toBe(true);
+    });
+  });
+
+  describe('identity', () => {
+    test('stores the identity field name', () => {
+      expect(user.identity).toBe('id');
+    });
+
+    test('exposes the identity field schema', () => {
+      expect(user.identitySchema).toBe(user.shape.id);
+    });
+
+    test('returns a branded identity schema', () => {
+      const schema = user.id();
+      expect(
+        schema.safeParse('550e8400-e29b-41d4-a716-446655440000').success
+      ).toBe(true);
+      expect(schema).toBe(user.id());
+    });
+
+    test('attaches contour metadata to branded identity schemas', () => {
+      expect(getContourIdMetadata(user.id())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('preserves first-write metadata when identity schemas are shared', () => {
+      const baseUser = contour(
+        'user',
+        { id: z.string().uuid(), name: z.string() },
+        { identity: 'id' }
+      );
+      const admin = contour(
+        'admin',
+        { id: baseUser.shape.id, role: z.string() },
+        { identity: 'id' }
+      );
+
+      // The first contour to brand the schema wins — user, not admin.
+      expect(getContourIdMetadata(baseUser.id())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+      // admin still has its own id() accessor
+      expect(admin.id()).toBeDefined();
+
+      // Neither contour should emit its own identity as a cross-contour reference
+      expect(getContourReferences(baseUser)).toEqual([]);
+      expect(getContourReferences(admin)).toEqual([]);
+    });
+
+    test('rejects identity keys that are not in the shape', () => {
+      expect(() =>
+        contour(
+          'broken',
+          {
+            id: z.string(),
+          },
+          { identity: 'missing' as 'id' }
+        )
+      ).toThrow('identity "missing" must match a declared field');
+    });
+  });
+
+  describe('examples', () => {
+    test('stores examples as a frozen array', () => {
+      expect(user.examples).toHaveLength(1);
+      expect(Object.isFrozen(user.examples)).toBe(true);
+    });
+
+    test('validates examples against the contour schema', () => {
+      expect(() =>
+        contour(
+          'broken',
+          {
+            id: z.string().uuid(),
+            name: z.string(),
+          },
+          {
+            examples: [{ id: 'not-a-uuid', name: 42 as never }],
+            identity: 'id',
+          }
+        )
+      ).toThrow('example 0 is invalid');
+    });
+  });
+
+  describe('zod forwarding', () => {
+    test('supports .pick()', () => {
+      const schema = user.pick({ name: true });
+      expect(schema.safeParse({ name: 'Ada' }).success).toBe(true);
+      expect(schema.safeParse({ email: 'ada@example.com' }).success).toBe(
+        false
+      );
+    });
+
+    test('supports .extend()', () => {
+      const schema = user.extend({ active: z.boolean() });
+      expect(
+        schema.safeParse({
+          active: true,
+          email: 'ada@example.com',
+          id: '550e8400-e29b-41d4-a716-446655440000',
+          name: 'Ada',
+        }).success
+      ).toBe(true);
+    });
+
+    test('supports .array()', () => {
+      const schema = user.array();
+      expect(
+        schema.safeParse([
+          {
+            email: 'ada@example.com',
+            id: '550e8400-e29b-41d4-a716-446655440000',
+            name: 'Ada',
+          },
+        ]).success
+      ).toBe(true);
+    });
+
+    test('supports cross-contour references via .id()', () => {
+      expect(
+        gist.safeParse({
+          id: '0f31f6ba-6ff0-41ce-9f6b-8d132b6c4b81',
+          ownerId: '550e8400-e29b-41d4-a716-446655440000',
+          title: 'Hello',
+        }).success
+      ).toBe(true);
+      expect(getContourIdMetadata(gist.shape.ownerId)).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('lists declared contour references', () => {
+      expect(getContourReferences(gist)).toEqual([
+        {
+          contour: 'user',
+          field: 'ownerId',
+          identity: 'id',
+        },
+      ]);
+    });
+  });
+
+  describe('wrapper unwrapping', () => {
+    test('resolves .optional() contour id metadata', () => {
+      expect(getContourIdMetadata(user.id().optional())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves .nullable() contour id metadata', () => {
+      expect(getContourIdMetadata(user.id().nullable())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves .nullish() contour id metadata (two-level wrapper)', () => {
+      expect(getContourIdMetadata(user.id().nullish())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves deeply nested wrappers', () => {
+      expect(
+        getContourIdMetadata(user.id().nullable().optional().default(null))
+      ).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('detects references through .nullish() wrappers in contour shapes', () => {
+      const comment = contour(
+        'comment',
+        {
+          authorId: user.id().nullish(),
+          id: z.string().uuid(),
+          text: z.string(),
+        },
+        { identity: 'id' }
+      );
+
+      expect(getContourReferences(comment)).toEqual([
+        {
+          contour: 'user',
+          field: 'authorId',
+          identity: 'id',
+        },
+      ]);
+    });
+  });
+});