@brika/type-system 0.1.1

package/src/from-zod.ts

@@ -0,0 +1,293 @@
+/**
+ * Zod → TypeDescriptor conversion.
+ *
+ * Converts Zod schemas to TypeDescriptor, handling:
+ * - Standard Zod types (string, number, object, array, union, enum, etc.)
+ * - GenericRef, PassthroughRef, ResolvedRef marker objects from @brika/sdk
+ *
+ * This function is used at block registration time (SDK side) to produce
+ * TypeDescriptor metadata that ships over IPC.
+ */
+
+import type { TypeDescriptor } from './descriptor';
+
+/**
+ * Convert a Zod schema or SDK marker ref to a TypeDescriptor.
+ *
+ * @param schemaOrRef - A Zod schema, GenericRef, PassthroughRef, or ResolvedRef
+ * @returns TypeDescriptor
+ */
+export function zodToDescriptor(schemaOrRef: unknown): TypeDescriptor {
+  // Handle SDK marker refs (GenericRef, PassthroughRef, ResolvedRef)
+  if (isMarkerRef(schemaOrRef)) {
+    return markerToDescriptor(schemaOrRef);
+  }
+
+  // Handle Zod schemas via JSON Schema intermediary
+  // This avoids depending on Zod internals
+  return fromZodViaJsonSchema(schemaOrRef);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Marker Ref Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface MarkerRef {
+  __type: 'generic' | 'passthrough' | 'resolved';
+  __generic?: string;
+  __passthrough?: string;
+  __source?: string;
+  __configField?: string;
+}
+
+function isMarkerRef(value: unknown): value is MarkerRef {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__type' in value &&
+    typeof (value as MarkerRef).__type === 'string' &&
+    ['generic', 'passthrough', 'resolved'].includes((value as MarkerRef).__type)
+  );
+}
+
+function markerToDescriptor(ref: MarkerRef): TypeDescriptor {
+  switch (ref.__type) {
+    case 'generic':
+      return { kind: 'generic', typeVar: ref.__generic ?? 'T' };
+    case 'passthrough':
+      return { kind: 'passthrough', sourcePortId: ref.__passthrough ?? '' };
+    case 'resolved':
+      return { kind: 'resolved', source: ref.__source ?? '', configField: ref.__configField ?? '' };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Zod → TypeDescriptor (via JSON Schema)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function fromZodViaJsonSchema(schema: unknown): TypeDescriptor {
+  try {
+    // Try using Zod's built-in toJSONSchema (Zod v4+)
+    const zod = getZodModule(schema);
+    if (zod?.toJSONSchema) {
+      const jsonSchema = zod.toJSONSchema(schema, { unrepresentable: 'any' }) as Record<
+        string,
+        unknown
+      >;
+      return fromJsonSchema(jsonSchema);
+    }
+  } catch {
+    // Fall through to constructor-based detection
+  }
+
+  // Fallback: detect type from Zod constructor name
+  return fromZodConstructor(schema);
+}
+
+/**
+ * Try to get the Zod module from a schema instance.
+ * Avoids a direct import of Zod so this package stays dependency-free.
+ */
+function getZodModule(
+  schema: unknown
+): { toJSONSchema: (s: unknown, opts: Record<string, unknown>) => unknown } | null {
+  try {
+    // Zod v4 schemas have a registry reference
+    const s = schema as { constructor?: { name?: string }; '~standard'?: unknown };
+    if (s.constructor?.name?.startsWith('Zod') || s['~standard']) {
+      // Dynamic import would be async, so we use a direct approach:
+      // The caller should have Zod in scope when using this function
+      // We look for toJSONSchema on the Zod namespace
+      const zod = (globalThis as Record<string, unknown>).__brika_zod as
+        | { toJSONSchema: (s: unknown, opts: Record<string, unknown>) => unknown }
+        | undefined;
+      return zod ?? null;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Convert a JSON Schema to TypeDescriptor.
+ * This is the primary conversion path and handles the full JSON Schema spec subset we use.
+ */
+export function fromJsonSchema(schema: Record<string, unknown>): TypeDescriptor {
+  const type = schema.type as string | undefined;
+
+  // anyOf → union
+  if (schema.anyOf) {
+    const variants = (schema.anyOf as Record<string, unknown>[]).map(fromJsonSchema);
+    return variants.length === 1 && variants[0] ? variants[0] : { kind: 'union', variants };
+  }
+
+  // oneOf → union
+  if (schema.oneOf) {
+    const variants = (schema.oneOf as Record<string, unknown>[]).map(fromJsonSchema);
+    return variants.length === 1 && variants[0] ? variants[0] : { kind: 'union', variants };
+  }
+
+  // enum
+  if (schema.enum) {
+    const values = schema.enum as (string | number)[];
+    return { kind: 'enum', values };
+  }
+
+  // const → literal
+  if ('const' in schema) {
+    return { kind: 'literal', value: schema.const as string | number | boolean };
+  }
+
+  switch (type) {
+    case 'string':
+      return { kind: 'primitive', type: 'string' };
+    case 'number':
+    case 'integer':
+      return { kind: 'primitive', type: 'number' };
+    case 'boolean':
+      return { kind: 'primitive', type: 'boolean' };
+    case 'null':
+      return { kind: 'primitive', type: 'null' };
+
+    case 'array': {
+      if (schema.items) {
+        return { kind: 'array', element: fromJsonSchema(schema.items as Record<string, unknown>) };
+      }
+      if (schema.prefixItems) {
+        const elements = (schema.prefixItems as Record<string, unknown>[]).map(fromJsonSchema);
+        return { kind: 'tuple', elements };
+      }
+      return { kind: 'array', element: { kind: 'unknown' } };
+    }
+
+    case 'object': {
+      const properties = schema.properties as Record<string, Record<string, unknown>> | undefined;
+      if (!properties) {
+        // Bare object or Record type
+        if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+          return {
+            kind: 'record',
+            value: fromJsonSchema(schema.additionalProperties as Record<string, unknown>),
+          };
+        }
+        return { kind: 'record', value: { kind: 'unknown' } };
+      }
+
+      const required = new Set((schema.required as string[] | undefined) ?? []);
+      const fields: Record<string, { type: TypeDescriptor; optional: boolean }> = {};
+
+      for (const [key, propSchema] of Object.entries(properties)) {
+        fields[key] = {
+          type: fromJsonSchema(propSchema),
+          optional: !required.has(key),
+        };
+      }
+
+      return { kind: 'object', fields };
+    }
+
+    default:
+      // Unknown or mixed type
+      return { kind: 'unknown' };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fallback: Constructor-based detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+function fromZodConstructor(schema: unknown): TypeDescriptor {
+  const name = getZodTypeName(schema);
+
+  switch (name) {
+    case 'string':
+      return { kind: 'primitive', type: 'string' };
+    case 'number':
+      return { kind: 'primitive', type: 'number' };
+    case 'boolean':
+      return { kind: 'primitive', type: 'boolean' };
+    case 'null':
+      return { kind: 'primitive', type: 'null' };
+    case 'any':
+      return { kind: 'any' };
+    case 'unknown':
+      return { kind: 'unknown' };
+    case 'undefined':
+      return { kind: 'unknown' };
+
+    case 'array': {
+      const def = getDef(schema);
+      const element = def?.element ?? def?.type;
+      return {
+        kind: 'array',
+        element: element ? fromZodConstructor(element) : { kind: 'unknown' },
+      };
+    }
+
+    case 'object': {
+      const def = getDef(schema);
+      const shape = def?.shape;
+      if (!shape || typeof shape !== 'object') {
+        return { kind: 'record', value: { kind: 'unknown' } };
+      }
+
+      const fields: Record<string, { type: TypeDescriptor; optional: boolean }> = {};
+      for (const [key, fieldSchema] of Object.entries(shape as Record<string, unknown>)) {
+        const fieldName = getZodTypeName(fieldSchema);
+        fields[key] = {
+          type: fromZodConstructor(fieldName === 'optional' ? getInner(fieldSchema) : fieldSchema),
+          optional: fieldName === 'optional',
+        };
+      }
+      return { kind: 'object', fields };
+    }
+
+    case 'optional':
+    case 'nullable':
+      return fromZodConstructor(getInner(schema));
+
+    case 'union': {
+      const def = getDef(schema);
+      const options = def?.options as unknown[] | undefined;
+      if (options) {
+        return { kind: 'union', variants: options.map(fromZodConstructor) };
+      }
+      return { kind: 'unknown' };
+    }
+
+    case 'enum': {
+      const def = getDef(schema);
+      const values = def?.entries ?? def?.values;
+      if (Array.isArray(values)) {
+        return { kind: 'enum', values: values as (string | number)[] };
+      }
+      return { kind: 'unknown' };
+    }
+
+    case 'record':
+      return { kind: 'record', value: { kind: 'unknown' } };
+
+    default:
+      return { kind: 'unknown' };
+  }
+}
+
+function getZodTypeName(schema: unknown): string {
+  const s = schema as { constructor?: { name?: string } };
+  const name = s?.constructor?.name;
+  if (name?.startsWith('Zod')) {
+    return name.slice(3).toLowerCase();
+  }
+  return 'unknown';
+}
+
+function getDef(schema: unknown): Record<string, unknown> | null {
+  const s = schema as { _def?: Record<string, unknown> };
+  return s?._def ?? null;
+}
+
+function getInner(schema: unknown): unknown {
+  const def = getDef(schema);
+  return def?.innerType ?? def?.unwrapped ?? schema;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @brika/type-system — unified type system for workflow port types.
+ *
+ * Single source of truth for port types across backend and frontend.
+ * Provides:
+ * - TypeDescriptor: serializable, structural type representation
+ * - isCompatible: structural type compatibility checking
+ * - inferTypes: graph-based type inference for generic/passthrough/resolved ports
+ * - getCompletions: autocomplete items from resolved types
+ * - displayType: human-readable type name strings
+ * - zodToDescriptor: Zod schema → TypeDescriptor conversion
+ * - fromJsonSchema: JSON Schema → TypeDescriptor conversion
+ * - toJsonSchema: TypeDescriptor → JSON Schema conversion
+ */
+
+export type { PrimitiveType, TypeDescriptor } from './descriptor';
+export { T, isConcrete, isWildcard, needsResolution, parseTypeName, parsePortType, inferType } from './descriptor';
+
+export { displayType } from './display';
+
+export { isCompatible } from './compatibility';
+
+export type { CompletionItem } from './autocomplete';
+export { getCompletions } from './autocomplete';
+
+export type { GraphEdge, GraphNode, PortTypeMap, TypeResolver } from './inference';
+export { inferTypes, portKey } from './inference';
+
+export { fromJsonSchema, zodToDescriptor } from './from-zod';
+
+export { toJsonSchema } from './to-json-schema';

package/src/inference.ts

@@ -0,0 +1,275 @@
+/**
+ * Graph Type Inference Engine
+ *
+ * Resolves generic, passthrough, and resolved port types
+ * based on the workflow graph structure and connections.
+ *
+ * Algorithm:
+ * 1. Resolve external types ($resolve markers via TypeResolver)
+ * 2. Forward propagation: concrete output → connected generic input
+ * 3. Passthrough resolution: passthrough(inputId) → copy input's resolved type
+ * 4. Backward propagation: concrete input → connected generic output
+ * 5. Iterate until stable (max 10 passes)
+ */
+
+import { type TypeDescriptor, isConcrete, needsResolution } from './descriptor';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Graph Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GraphNode {
+  id: string;
+  ports: Record<string, { direction: 'input' | 'output'; type: TypeDescriptor }>;
+  config?: Record<string, unknown>;
+}
+
+export interface GraphEdge {
+  sourceNode: string;
+  sourcePort: string;
+  targetNode: string;
+  targetPort: string;
+}
+
+/**
+ * External type resolver — looks up types from external sources.
+ * e.g., spark registry for $resolve:spark:sparkType
+ */
+export interface TypeResolver {
+  resolve(source: string, key: string): TypeDescriptor | null;
+}
+
+/** Map of "nodeId:portId" → resolved TypeDescriptor */
+export type PortTypeMap = Map<string, TypeDescriptor>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MAX_ITERATIONS = 10;
+
+/**
+ * Infer types for all ports in a workflow graph.
+ * Returns a map of resolved types for every port.
+ */
+export function inferTypes(
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  resolver?: TypeResolver
+): PortTypeMap {
+  const result: PortTypeMap = new Map();
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+
+  // Build edge lookup maps
+  const incoming = buildIncomingMap(edges);
+  const outgoing = buildOutgoingMap(edges);
+
+  // Seed with declared types (concrete types go directly into result)
+  for (const node of nodes) {
+    for (const [portId, port] of Object.entries(node.ports)) {
+      const key = portKey(node.id, portId);
+      if (isConcrete(port.type)) {
+        result.set(key, port.type);
+      }
+    }
+  }
+
+  // Phase 1: Resolve external types ($resolve markers)
+  if (resolver) {
+    resolveExternalTypes(nodes, resolver, result);
+  }
+
+  // Phase 2-4: Iterate until stable
+  for (let iter = 0; iter < MAX_ITERATIONS; iter++) {
+    let changed = false;
+
+    for (const node of nodes) {
+      // Forward propagation: concrete output → connected generic input
+      if (propagateForward(node, incoming, nodeMap, result)) changed = true;
+
+      // Passthrough resolution
+      if (resolvePassthrough(node, result)) changed = true;
+
+      // Backward propagation: concrete input → connected generic output
+      if (propagateBackward(node, outgoing, nodeMap, result)) changed = true;
+    }
+
+    if (!changed) break;
+  }
+
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Edge Lookup Maps
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface EdgeTarget {
+  node: string;
+  port: string;
+}
+
+/** Map: targetNodeId → (targetPortId → source) */
+type IncomingMap = Map<string, Map<string, EdgeTarget>>;
+
+/** Map: sourceNodeId → (sourcePortId → targets[]) */
+type OutgoingMap = Map<string, Map<string, EdgeTarget[]>>;
+
+function buildIncomingMap(edges: GraphEdge[]): IncomingMap {
+  const map: IncomingMap = new Map();
+  for (const e of edges) {
+    if (!map.has(e.targetNode)) map.set(e.targetNode, new Map());
+    map.get(e.targetNode)?.set(e.targetPort, { node: e.sourceNode, port: e.sourcePort });
+  }
+  return map;
+}
+
+function buildOutgoingMap(edges: GraphEdge[]): OutgoingMap {
+  const map: OutgoingMap = new Map();
+  for (const e of edges) {
+    if (!map.has(e.sourceNode)) map.set(e.sourceNode, new Map());
+    const portMap = map.get(e.sourceNode);
+    if (portMap) {
+      if (!portMap.has(e.sourcePort)) portMap.set(e.sourcePort, []);
+      portMap.get(e.sourcePort)?.push({ node: e.targetNode, port: e.targetPort });
+    }
+  }
+  return map;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1: External Type Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolveExternalTypes(
+  nodes: GraphNode[],
+  resolver: TypeResolver,
+  result: PortTypeMap
+): void {
+  for (const node of nodes) {
+    for (const [portId, port] of Object.entries(node.ports)) {
+      if (port.type.kind !== 'resolved') continue;
+
+      const configValue = node.config?.[port.type.configField] as string | undefined;
+      if (!configValue) continue;
+
+      const resolved = resolver.resolve(port.type.source, configValue);
+      if (resolved && isConcrete(resolved)) {
+        result.set(portKey(node.id, portId), resolved);
+      }
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 2: Forward Propagation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function propagateForward(
+  node: GraphNode,
+  incoming: IncomingMap,
+  nodeMap: Map<string, GraphNode>,
+  result: PortTypeMap
+): boolean {
+  let changed = false;
+  const nodeIncoming = incoming.get(node.id);
+  if (!nodeIncoming) return false;
+
+  for (const [inputPortId, port] of Object.entries(node.ports)) {
+    if (port.direction !== 'input') continue;
+
+    const key = portKey(node.id, inputPortId);
+    if (result.has(key)) continue; // already resolved
+
+    const source = nodeIncoming.get(inputPortId);
+    if (!source) continue;
+
+    // Check if the source's declared type or its inferred type is concrete
+    const sourceKey = portKey(source.node, source.port);
+    const sourceType = result.get(sourceKey);
+
+    if (sourceType && isConcrete(sourceType) && needsResolution(port.type)) {
+      result.set(key, sourceType);
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 3: Passthrough Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolvePassthrough(node: GraphNode, result: PortTypeMap): boolean {
+  let changed = false;
+
+  for (const [portId, port] of Object.entries(node.ports)) {
+    if (port.type.kind !== 'passthrough') continue;
+
+    const key = portKey(node.id, portId);
+    if (result.has(key)) continue;
+
+    // Look up the referenced input port on the same node
+    const sourceInputKey = portKey(node.id, port.type.sourcePortId);
+    const resolvedInput = result.get(sourceInputKey);
+
+    if (resolvedInput && isConcrete(resolvedInput)) {
+      result.set(key, resolvedInput);
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 4: Backward Propagation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function propagateBackward(
+  node: GraphNode,
+  outgoing: OutgoingMap,
+  nodeMap: Map<string, GraphNode>,
+  result: PortTypeMap
+): boolean {
+  let changed = false;
+  const nodeOutgoing = outgoing.get(node.id);
+  if (!nodeOutgoing) return false;
+
+  for (const [outputPortId, port] of Object.entries(node.ports)) {
+    if (port.direction !== 'output') continue;
+
+    const key = portKey(node.id, outputPortId);
+    if (result.has(key)) continue; // already resolved
+
+    if (!needsResolution(port.type)) continue;
+
+    const targets = nodeOutgoing.get(outputPortId);
+    if (!targets) continue;
+
+    // If any connected input has a concrete type, use it
+    for (const target of targets) {
+      const targetKey = portKey(target.node, target.port);
+      const targetType = result.get(targetKey);
+
+      if (targetType && isConcrete(targetType)) {
+        result.set(key, targetType);
+        changed = true;
+        break;
+      }
+    }
+  }
+
+  return changed;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility
+// ─────────────────────────────────────────────────────────────────────────────
+
+function portKey(nodeId: string, portId: string): string {
+  return `${nodeId}:${portId}`;
+}
+
+export { portKey };

package/src/to-json-schema.ts

@@ -0,0 +1,65 @@
+/**
+ * TypeDescriptor → JSON Schema conversion.
+ *
+ * Produces standard JSON Schema (draft 2020-12 compatible) for API consumers
+ * that need JSON Schema format (e.g., UI schema rendering, documentation).
+ */
+
+import type { TypeDescriptor } from './descriptor';
+
+/**
+ * Convert a TypeDescriptor to a JSON Schema object.
+ */
+export function toJsonSchema(desc: TypeDescriptor): Record<string, unknown> {
+  switch (desc.kind) {
+    case 'primitive':
+      return { type: desc.type === 'null' ? 'null' : desc.type };
+
+    case 'literal':
+      return { const: desc.value };
+
+    case 'object': {
+      const properties: Record<string, Record<string, unknown>> = {};
+      const required: string[] = [];
+
+      for (const [key, field] of Object.entries(desc.fields)) {
+        properties[key] = toJsonSchema(field.type);
+        if (!field.optional) required.push(key);
+      }
+
+      const schema: Record<string, unknown> = { type: 'object', properties };
+      if (required.length > 0) schema.required = required;
+      return schema;
+    }
+
+    case 'array':
+      return { type: 'array', items: toJsonSchema(desc.element) };
+
+    case 'tuple':
+      return { type: 'array', prefixItems: desc.elements.map(toJsonSchema) };
+
+    case 'union':
+      return { anyOf: desc.variants.map(toJsonSchema) };
+
+    case 'record':
+      return { type: 'object', additionalProperties: toJsonSchema(desc.value) };
+
+    case 'enum':
+      return { enum: [...desc.values] };
+
+    case 'any':
+      return {};
+
+    case 'unknown':
+      return {};
+
+    case 'generic':
+      return { description: `generic<${desc.typeVar}>` };
+
+    case 'passthrough':
+      return { description: `passthrough(${desc.sourcePortId})` };
+
+    case 'resolved':
+      return { description: `$resolve:${desc.source}:${desc.configField}` };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}