@ontrails/core 0.2.0

package/src/draft.ts

@@ -0,0 +1,350 @@
+import type { AnyEntity } from './entity.js';
+import { getEntityReferences } from './entity.js';
+import { ValidationError } from './errors.js';
+import type { AnySignal } from './signal.js';
+import type { AnyResource } from './resource.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+
+export const DRAFT_ID_PREFIX = '_draft.';
+
+export type DraftDependencyKind =
+  | 'compose'
+  | 'entity'
+  | 'resource'
+  | 'replaced-by'
+  | 'schema-reference'
+  | 'signal-fire'
+  | 'signal-on'
+  | 'signal-from';
+
+export interface DraftDependency {
+  readonly fromId: string;
+  readonly kind: DraftDependencyKind;
+  readonly toId: string;
+}
+
+export interface DraftDiagnostic {
+  readonly id: string;
+  readonly kind: 'entity' | 'resource' | 'signal' | 'trail' | 'unknown';
+  readonly message: string;
+  readonly rule: 'draft-contamination' | 'draft-id';
+  readonly via?: DraftDependencyKind | undefined;
+  readonly dependsOn?: string | undefined;
+}
+
+/**
+ * @deprecated Use {@link DraftDiagnostic}. Kept as a source-compatible alias
+ * during the v1 vocabulary cutover.
+ */
+export interface DraftFinding extends DraftDiagnostic {
+  readonly id: DraftDiagnostic['id'];
+}
+
+export interface DraftReport {
+  readonly contaminatedIds: ReadonlySet<string>;
+  readonly declaredDraftIds: ReadonlySet<string>;
+  readonly dependencies: readonly DraftDependency[];
+  readonly findings: readonly DraftDiagnostic[];
+}
+
+interface DraftReason {
+  readonly dependsOn: string;
+  readonly via: DraftDependencyKind;
+}
+
+type TopoNode = AnyEntity | AnyResource | AnySignal | AnyTrail;
+
+const replacedByTarget = (value: TopoNode): string | undefined => {
+  const raw = value as unknown as { replacedBy?: unknown };
+  return typeof raw.replacedBy === 'string' ? raw.replacedBy : undefined;
+};
+
+export const isDraftId = (id: string): boolean =>
+  id.startsWith(DRAFT_ID_PREFIX);
+
+const dependenciesFromIds = (
+  fromId: string,
+  toIds: readonly string[],
+  kind: DraftDependencyKind
+): DraftDependency[] =>
+  toIds.map((toId) => ({
+    fromId,
+    kind,
+    toId,
+  }));
+
+const dependencyFromTarget = (
+  fromId: string,
+  toId: string | undefined,
+  kind: DraftDependencyKind
+): DraftDependency[] =>
+  toId === undefined
+    ? []
+    : [
+        {
+          fromId,
+          kind,
+          toId,
+        },
+      ];
+
+const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
+  ...dependenciesFromIds(
+    trail.id,
+    (trail.entities ?? []).map((entity) => entity.name),
+    'entity'
+  ),
+  ...dependenciesFromIds(trail.id, trail.composes, 'compose'),
+  ...dependenciesFromIds(
+    trail.id,
+    trail.resources.map(({ id }) => id),
+    'resource'
+  ),
+  ...dependenciesFromIds(trail.id, trail.fires ?? [], 'signal-fire'),
+  ...dependenciesFromIds(trail.id, trail.on ?? [], 'signal-on'),
+  ...dependencyFromTarget(trail.id, replacedByTarget(trail), 'replaced-by'),
+];
+
+const entityDependencies = (entity: AnyEntity): DraftDependency[] =>
+  dependenciesFromIds(
+    entity.name,
+    getEntityReferences(entity).map((reference) => reference.entity),
+    'schema-reference'
+  );
+
+const signalDependencies = (signal: AnySignal): DraftDependency[] => [
+  ...dependenciesFromIds(signal.id, signal.from ?? [], 'signal-from'),
+  ...dependencyFromTarget(signal.id, replacedByTarget(signal), 'replaced-by'),
+];
+
+const resourceDependencies = (resource: AnyResource): DraftDependency[] =>
+  dependencyFromTarget(resource.id, replacedByTarget(resource), 'replaced-by');
+
+const nodeKind = (
+  id: string,
+  entities: ReadonlyMap<string, AnyEntity>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  resources: ReadonlyMap<string, AnyResource>
+): DraftDiagnostic['kind'] => {
+  if (entities.has(id)) {
+    return 'entity';
+  }
+  if (trails.has(id)) {
+    return 'trail';
+  }
+  if (signals.has(id)) {
+    return 'signal';
+  }
+  if (resources.has(id)) {
+    return 'resource';
+  }
+  return 'unknown';
+};
+
+const displayKind = (kind: DraftDiagnostic['kind']): string =>
+  kind === 'unknown' ? 'Node' : kind[0]?.toUpperCase() + kind.slice(1);
+
+const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
+  [...keys].filter(isDraftId);
+
+const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
+  new Set([
+    ...draftIdsFromKeys(topo.entities.keys()),
+    ...draftIdsFromKeys(topo.trails.keys()),
+    ...draftIdsFromKeys(topo.signals.keys()),
+    ...draftIdsFromKeys(topo.resources.keys()),
+  ]);
+
+const findingForDraftId = (
+  id: string,
+  kind: DraftDiagnostic['kind']
+): DraftDiagnostic => ({
+  id,
+  kind,
+  message: `${displayKind(id ? kind : 'unknown')} "${id}" is draft and cannot appear in the established graph.`,
+  rule: 'draft-id',
+});
+
+const findingForContamination = (
+  id: string,
+  kind: DraftDiagnostic['kind'],
+  reason: DraftReason
+): DraftDiagnostic => {
+  const dependencyLabel = isDraftId(reason.dependsOn)
+    ? `draft "${reason.dependsOn}"`
+    : `draft-contaminated "${reason.dependsOn}"`;
+
+  return {
+    dependsOn: reason.dependsOn,
+    id,
+    kind,
+    message:
+      `Established ${kind} "${id}" depends on ${dependencyLabel} ` +
+      `via ${reason.via} and cannot appear in the established graph.`,
+    rule: 'draft-contamination',
+    via: reason.via,
+  };
+};
+
+const contaminationReason = (
+  dependency: DraftDependency,
+  contaminatedIds: ReadonlySet<string>
+): DraftReason | undefined => {
+  if (contaminatedIds.has(dependency.fromId)) {
+    return undefined;
+  }
+
+  if (!isDraftId(dependency.toId) && !contaminatedIds.has(dependency.toId)) {
+    return undefined;
+  }
+
+  return {
+    dependsOn: dependency.toId,
+    via: dependency.kind,
+  };
+};
+
+const markContaminatedDependency = (
+  dependency: DraftDependency,
+  contaminatedIds: Set<string>,
+  reasons: Map<string, DraftReason>
+): boolean => {
+  const reason = contaminationReason(dependency, contaminatedIds);
+
+  if (reason === undefined) {
+    return false;
+  }
+
+  contaminatedIds.add(dependency.fromId);
+  reasons.set(dependency.fromId, reason);
+  return true;
+};
+
+const propagateContaminatedIds = (
+  declaredDraftIds: ReadonlySet<string>,
+  dependencies: readonly DraftDependency[]
+): { contaminatedIds: Set<string>; reasons: Map<string, DraftReason> } => {
+  const contaminatedIds = new Set<string>(declaredDraftIds);
+  const reasons = new Map<string, DraftReason>();
+
+  const visit = (): void => {
+    if (
+      dependencies.some((dependency) =>
+        markContaminatedDependency(dependency, contaminatedIds, reasons)
+      )
+    ) {
+      visit();
+    }
+  };
+
+  visit();
+  return { contaminatedIds, reasons };
+};
+
+const contaminationFindingForId = (
+  id: string,
+  declaredDraftIds: ReadonlySet<string>,
+  reasons: ReadonlyMap<string, DraftReason>,
+  entities: ReadonlyMap<string, AnyEntity>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  resources: ReadonlyMap<string, AnyResource>
+): DraftDiagnostic | undefined => {
+  if (declaredDraftIds.has(id)) {
+    return undefined;
+  }
+
+  const reason = reasons.get(id);
+  if (reason === undefined) {
+    return undefined;
+  }
+
+  return findingForContamination(
+    id,
+    nodeKind(id, entities, trails, signals, resources),
+    reason
+  );
+};
+
+const collectFindings = (
+  declaredDraftIds: ReadonlySet<string>,
+  contaminatedIds: ReadonlySet<string>,
+  reasons: ReadonlyMap<string, DraftReason>,
+  entities: ReadonlyMap<string, AnyEntity>,
+  trails: ReadonlyMap<string, AnyTrail>,
+  signals: ReadonlyMap<string, AnySignal>,
+  resources: ReadonlyMap<string, AnyResource>
+): DraftDiagnostic[] => [
+  ...[...declaredDraftIds]
+    .toSorted()
+    .map((id) =>
+      findingForDraftId(id, nodeKind(id, entities, trails, signals, resources))
+    ),
+  ...[...contaminatedIds].toSorted().flatMap((id) => {
+    const finding = contaminationFindingForId(
+      id,
+      declaredDraftIds,
+      reasons,
+      entities,
+      trails,
+      signals,
+      resources
+    );
+
+    return finding === undefined ? [] : [finding];
+  }),
+];
+
+const collectDependencies = (topo: Topo): DraftDependency[] => [
+  ...[...topo.entities.values()].flatMap(entityDependencies),
+  ...[...topo.trails.values()].flatMap(trailDependencies),
+  ...[...topo.signals.values()].flatMap(signalDependencies),
+  ...[...topo.resources.values()].flatMap(resourceDependencies),
+];
+
+export const deriveDraftReport = (topo: Topo): DraftReport => {
+  const declaredDraftIds = collectDeclaredDraftIds(topo);
+  const dependencies = collectDependencies(topo);
+  const { contaminatedIds, reasons } = propagateContaminatedIds(
+    declaredDraftIds,
+    dependencies
+  );
+  const findings = collectFindings(
+    declaredDraftIds,
+    contaminatedIds,
+    reasons,
+    topo.entities,
+    topo.trails,
+    topo.signals,
+    topo.resources
+  );
+
+  return {
+    contaminatedIds,
+    declaredDraftIds,
+    dependencies,
+    findings,
+  };
+};
+
+export const validateDraftFreeTopo = (
+  topo: Topo
+): Result<void, ValidationError> => {
+  const analysis = deriveDraftReport(topo);
+
+  if (analysis.findings.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Established topo validation failed with ${analysis.findings.length} draft issue(s)`,
+      {
+        context: { issues: analysis.findings },
+      }
+    )
+  );
+};

package/src/entity.ts

@@ -0,0 +1,346 @@
+import { z } from 'zod';
+
+import type { Branded } from './branded.js';
+
+/**
+ * Runtime options for an entity declaration.
+ */
+export interface EntityOptions<
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+> {
+  /** Field name that acts as the entity's primary identity. */
+  readonly identity: TIdentity;
+  /** Example instances validated against the entity schema at declaration time. */
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+  /** Reserved for future entity-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+/** Type-level brand name applied to an entity's identity schema. */
+export type EntityIdBrand<TName extends string> = `${Capitalize<TName>}Id`;
+
+type BrandedSchema<
+  TSchema extends z.core.$ZodType,
+  TBrand extends string,
+> = TSchema & z.ZodType<Branded<z.output<TSchema>, TBrand>>;
+
+type BrandableSchema<TSchema extends z.core.$ZodType> = TSchema & {
+  brand<TBrand extends string>(): BrandedSchema<TSchema, TBrand>;
+};
+
+/** Output value of a branded entity identity schema. */
+export type EntityIdValue<
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+> = Branded<z.output<TSchema>, EntityIdBrand<TName>>;
+
+/** Runtime metadata attached to schemas returned from `entity.id()`. */
+export interface EntityIdMetadata<
+  TName extends string = string,
+  TIdentity extends string = string,
+> {
+  readonly entity: TName;
+  readonly identity: TIdentity;
+}
+
+/** A structural entity reference declared by another entity field schema. */
+export interface EntityReference<
+  TName extends string = string,
+  TIdentity extends string = string,
+> extends EntityIdMetadata<TName, TIdentity> {
+  readonly field: string;
+}
+
+/** Symbol used to tag branded entity reference schemas at runtime. */
+export const ENTITY_ID_METADATA = Symbol.for('@ontrails/core/entity-id');
+
+/**
+ * Module-level WeakMap storing entity identity metadata keyed by schema object.
+ *
+ * First-write-wins: when multiple entities share the same underlying schema
+ * (e.g. `entity('admin', { id: user.shape.id }, ...)`), the first entity to
+ * brand the schema claims it. Subsequent calls skip the write to prevent
+ * silent metadata corruption.
+ */
+const entityIdMetadata = new WeakMap<object, EntityIdMetadata>();
+
+/**
+ * An entity identity schema branded for one entity and tagged with runtime
+ * metadata so the topo layer can recognize declared references later on.
+ */
+export type EntityIdSchema<
+  TSchema extends z.core.$ZodType = z.core.$ZodType,
+  TName extends string = string,
+  TIdentity extends string = string,
+> = BrandedSchema<TSchema, EntityIdBrand<TName>> & {
+  /** @deprecated Use `getEntityIdMetadata()` — metadata lives in a WeakMap, not on the schema. */
+  readonly [ENTITY_ID_METADATA]?: EntityIdMetadata<TName, TIdentity>;
+};
+
+/**
+ * A first-class domain object with schema, identity metadata, and examples.
+ *
+ * An entity behaves like the `ZodObject` it wraps, so standard Zod composition
+ * helpers such as `.pick()`, `.extend()`, and `.array()` continue to work.
+ */
+export type Entity<
+  TName extends string = string,
+  TShape extends z.ZodRawShape = z.ZodRawShape,
+  TIdentity extends keyof TShape & string = keyof TShape & string,
+> = z.ZodObject<TShape> & {
+  readonly kind: 'entity';
+  readonly name: TName;
+  readonly identity: TIdentity;
+  readonly identitySchema: TShape[TIdentity];
+  readonly id: () => EntityIdSchema<TShape[TIdentity], TName, TIdentity>;
+  readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+};
+
+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 assertIdentityField = <
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: string,
+  shape: TShape,
+  identity: TIdentity
+): void => {
+  if (!Object.hasOwn(shape, identity)) {
+    throw new TypeError(
+      `entity("${name}") identity "${identity}" must match a declared field`
+    );
+  }
+};
+
+const assertExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples: readonly z.output<z.ZodObject<TShape>>[]
+): void => {
+  for (const [index, example] of examples.entries()) {
+    const parsed = schema.safeParse(example);
+    if (!parsed.success) {
+      throw new TypeError(
+        `entity("${name}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
+      );
+    }
+  }
+};
+
+const validateExamples = <TShape extends z.ZodRawShape>(
+  name: string,
+  schema: z.ZodObject<TShape>,
+  examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined
+): void => {
+  if (examples) {
+    assertExamples(name, schema, examples);
+  }
+};
+
+const brandIdentitySchema = <
+  TSchema extends z.core.$ZodType,
+  TName extends string,
+  TIdentity extends string,
+>(
+  entity: TName,
+  identity: TIdentity,
+  schema: TSchema
+): EntityIdSchema<TSchema, TName, TIdentity> => {
+  const branded = (schema as BrandableSchema<TSchema>).brand<
+    EntityIdBrand<TName>
+  >();
+
+  // First-write-wins: if another entity already claimed this schema object
+  // (possible when Zod v4 brand() returns `this`), preserve the original
+  // metadata rather than silently overwriting it.
+  if (!entityIdMetadata.has(branded)) {
+    entityIdMetadata.set(branded, {
+      entity,
+      identity,
+    } satisfies EntityIdMetadata<TName, TIdentity>);
+  }
+
+  return branded as EntityIdSchema<TSchema, TName, TIdentity>;
+};
+
+const attachEntityMetadata = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  schema: z.ZodObject<TShape>,
+  metadata: {
+    readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
+    readonly idSchema: EntityIdSchema<TShape[TIdentity], TName, TIdentity>;
+    readonly identity: TIdentity;
+    readonly identitySchema: TShape[TIdentity];
+    readonly name: TName;
+  }
+): void => {
+  Object.defineProperties(schema, {
+    examples: {
+      enumerable: true,
+      value: metadata.examples,
+      writable: false,
+    },
+    id: {
+      enumerable: true,
+      value: () => metadata.idSchema,
+      writable: false,
+    },
+    identity: {
+      enumerable: true,
+      value: metadata.identity,
+      writable: false,
+    },
+    identitySchema: {
+      enumerable: true,
+      value: metadata.identitySchema,
+      writable: false,
+    },
+    kind: {
+      enumerable: true,
+      value: 'entity',
+      writable: false,
+    },
+    name: {
+      enumerable: true,
+      value: metadata.name,
+      writable: false,
+    },
+  });
+};
+
+/** Read entity identity metadata from the module-level WeakMap, if present. */
+const readMetadata = (schema: unknown): EntityIdMetadata | undefined =>
+  typeof schema === 'object' && schema !== null
+    ? entityIdMetadata.get(schema)
+    : undefined;
+
+/** Resolve the inner schema from a Zod wrapper (ZodOptional, ZodNullable, etc.). */
+const unwrapInner = (schema: unknown): unknown => {
+  const def = (schema as { _def?: Record<string, unknown> })._def;
+  return (def?.['innerType'] ?? def?.['schema']) as unknown;
+};
+
+/**
+ * Walk through Zod wrapper layers searching for `ENTITY_ID_METADATA`.
+ *
+ * `.nullish()` produces `ZodOptional<ZodNullable<T>>` — two wrapper levels —
+ * so a single-step unwrap is insufficient. This iterates until it finds the
+ * metadata or exhausts all wrapper layers.
+ */
+const unwrapToMetadata = (schema: unknown): EntityIdMetadata | undefined => {
+  let current: unknown = schema;
+  while (typeof current === 'object' && current !== null) {
+    const inner = unwrapInner(current);
+    if (typeof inner !== 'object' || inner === null) {
+      return undefined;
+    }
+    const metadata = readMetadata(inner);
+    if (metadata !== undefined) {
+      return metadata;
+    }
+    current = inner;
+  }
+  return undefined;
+};
+
+/**
+ * Read entity-reference metadata from a schema returned by `entity.id()`.
+ *
+ * When the schema is wrapped by Zod combinators (`.optional()`, `.nullable()`,
+ * `.default()`, `.nullish()`, etc.) the `ENTITY_ID_METADATA` symbol lives on
+ * the inner schema, not on the wrapper. The unwrap handles arbitrarily nested
+ * wrapper levels.
+ */
+export const getEntityIdMetadata = (
+  schema: unknown
+): EntityIdMetadata | undefined =>
+  readMetadata(schema) ?? unwrapToMetadata(schema);
+
+/** Inspect an entity schema for fields that reference other entities via `.id()`. */
+export const getEntityReferences = (
+  entity: AnyEntity
+): readonly EntityReference[] =>
+  Object.entries(entity.shape)
+    .flatMap(([field, schema]) => {
+      if (field === entity.identity) {
+        return [];
+      }
+      const metadata = getEntityIdMetadata(schema);
+      if (metadata === undefined) {
+        return [];
+      }
+
+      return [{ field, ...metadata }];
+    })
+    .toSorted((left, right) =>
+      left.field === right.field
+        ? left.entity.localeCompare(right.entity)
+        : left.field.localeCompare(right.field)
+    );
+
+/**
+ * Create an entity definition from a raw Zod object shape.
+ *
+ * @example
+ * ```typescript
+ * const user = entity(
+ *   'user',
+ *   {
+ *     id: z.string().uuid(),
+ *     email: z.string().email(),
+ *     name: z.string(),
+ *   },
+ *   { identity: 'id' }
+ * );
+ * ```
+ */
+export const entity = <
+  TName extends string,
+  TShape extends z.ZodRawShape,
+  TIdentity extends keyof TShape & string,
+>(
+  name: TName,
+  shape: TShape,
+  options: EntityOptions<TShape, TIdentity>
+): Entity<TName, TShape, TIdentity> => {
+  assertIdentityField(name, shape, options.identity);
+
+  const schema = z.object(shape);
+  validateExamples(name, schema, options.examples);
+
+  const identitySchema = shape[options.identity];
+  if (!identitySchema) {
+    throw new TypeError(
+      `entity("${name}") identity "${options.identity}" must resolve to a schema`
+    );
+  }
+
+  const idSchema = brandIdentitySchema(name, options.identity, identitySchema);
+  const examples = options.examples
+    ? Object.freeze([...options.examples])
+    : undefined;
+
+  attachEntityMetadata(schema, {
+    examples,
+    idSchema,
+    identity: options.identity,
+    identitySchema,
+    name,
+  });
+
+  return schema as Entity<TName, TShape, TIdentity>;
+};
+
+/** Existential type for heterogeneous entity collections. */
+export type AnyEntity = Entity<string, z.ZodRawShape, string>;