@enterstellar-ai/types 0.1.0

package/dist/index.js

@@ -0,0 +1,428 @@
+import { z } from 'zod';
+
+// src/version.ts
+var ENTERSTELLAR_TYPES_VERSION = "0.1.0";
+
+// src/errors.ts
+var EnterstellarError = class _EnterstellarError extends Error {
+  /**
+   * Machine-readable error code.
+   * Maps to documentation at `enterstellar.dev/errors/{code}`.
+   */
+  code;
+  /** The Enterstellar module that originated this error. */
+  module;
+  /**
+   * Whether the error is recoverable.
+   * Recoverable errors can be retried or handled gracefully.
+   * Non-recoverable errors indicate fatal conditions.
+   */
+  recoverable;
+  /**
+   * ISO 8601 timestamp of when the error was created.
+   * Useful for trace correlation and debugging.
+   */
+  timestamp;
+  /**
+   * Creates a new `EnterstellarError`.
+   *
+   * @param code - Machine-readable error code (e.g., `'ENS-1001'`).
+   * @param module - The Enterstellar module that originated the error.
+   * @param message - Human-readable error message.
+   * @param recoverable - Whether the error can be retried or handled gracefully.
+   * @param cause - Optional underlying error that caused this error.
+   */
+  constructor(code, module, message, recoverable = false, cause) {
+    super(message, { cause });
+    this.name = "EnterstellarError";
+    this.code = code;
+    this.module = module;
+    this.recoverable = recoverable;
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    if ("captureStackTrace" in Error) {
+      Error.captureStackTrace(this, _EnterstellarError);
+    }
+  }
+  /**
+   * Serializes the error to a plain object for logging, telemetry, or DevTools.
+   *
+   * @returns A plain object representation of the error.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      module: this.module,
+      message: this.message,
+      recoverable: this.recoverable,
+      timestamp: this.timestamp,
+      stack: this.stack
+    };
+  }
+};
+
+// src/brands.ts
+function createComponentId(name) {
+  if (!name.trim()) {
+    throw new EnterstellarError(
+      "ENS-1009",
+      "types",
+      "[ENS-1009] ComponentId name must be a non-empty string.",
+      false
+    );
+  }
+  return name;
+}
+function createZoneId(name) {
+  if (!name.trim()) {
+    throw new EnterstellarError(
+      "ENS-1009",
+      "types",
+      "[ENS-1009] ZoneId name must be a non-empty string.",
+      false
+    );
+  }
+  return name;
+}
+function createTraceId() {
+  return globalThis.crypto.randomUUID();
+}
+var ComponentContractSchema = z.object({
+  name: z.string().min(1, "Component name is required."),
+  id: z.string().min(1, "Component ID is required."),
+  description: z.string().min(1, "Description is required.").max(120, "Description must be 120 characters or fewer (R2)."),
+  category: z.string().min(1, "Category is required."),
+  tags: z.array(z.string()).min(1, "At least one tag is required (R3)."),
+  props: z.unknown(),
+  tokens: z.record(z.string(), z.string()),
+  accessibility: z.object({
+    role: z.string().min(1, "Accessibility role is required."),
+    ariaLabel: z.string().min(1, "Accessibility ariaLabel is required."),
+    announceOnUpdate: z.boolean()
+  }),
+  states: z.object({
+    loading: z.string().min(1),
+    error: z.string().min(1),
+    empty: z.string().min(1),
+    ready: z.string().min(1)
+  }),
+  examples: z.array(
+    z.object({
+      intent: z.string().min(1),
+      props: z.record(z.string(), z.unknown())
+    })
+  ),
+  dataSource: z.object({
+    adapter: z.string().min(1),
+    resource: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional()
+  }).optional(),
+  auth: z.object({
+    required: z.boolean(),
+    roles: z.array(z.string())
+  }).optional(),
+  origin: z.object({
+    registryUrl: z.url(),
+    publisher: z.string().min(1),
+    verifiedAt: z.string().optional()
+  }).optional(),
+  _meta: z.object({
+    forged: z.boolean(),
+    version: z.string().min(1),
+    createdAt: z.string().min(1)
+  })
+});
+var DesignTokenSetSchema = z.record(
+  z.string(),
+  z.string().min(1, "Token value must be a non-empty string.")
+);
+var ComponentIntentSchema = z.object({
+  component: z.string().min(1, "Component name is required."),
+  props: z.record(z.string(), z.unknown()),
+  confidence: z.number().min(0, "Confidence must be >= 0.").max(1, "Confidence must be <= 1."),
+  layout: z.enum(["single", "split", "grid", "stack", "tabs"]).optional(),
+  mode: z.string().optional(),
+  interaction: z.enum(["read-only", "editable", "actionable"]).optional(),
+  _source: z.object({
+    protocol: z.enum([
+      "ag-ui",
+      "a2ui",
+      "mcp",
+      "websocket",
+      "sse",
+      "custom"
+    ]),
+    rawEventId: z.string().optional(),
+    correlationId: z.string().optional(),
+    raw: z.unknown().optional()
+  }).optional()
+});
+var CompilationErrorSchema = z.object({
+  code: z.string().min(1, "Error code is required."),
+  path: z.string(),
+  message: z.string().min(1, "Error message is required."),
+  received: z.unknown().optional(),
+  expected: z.unknown().optional(),
+  fix: z.object({
+    field: z.string().min(1),
+    was: z.unknown(),
+    shouldBe: z.unknown()
+  }).optional()
+});
+var CompilationResultSchema = z.object({
+  componentName: z.string().min(1, "Component name is required."),
+  props: z.record(z.string(), z.unknown()),
+  status: z.enum(["pass", "fail", "corrected"]),
+  provenance: z.object({
+    agent: z.string().min(1),
+    registry: z.string().min(1),
+    compiledAt: z.string().min(1),
+    compilerVersion: z.string().min(1),
+    forgeMode: z.enum(["local", "cloud"]).optional(),
+    contractOrigin: z.object({
+      registryUrl: z.string(),
+      publisher: z.string()
+    }).optional()
+  }),
+  errors: z.array(CompilationErrorSchema),
+  selfCorrectionAttempts: z.number().int().min(0),
+  diff: z.object({
+    raw: z.record(z.string(), z.unknown()),
+    compiled: z.record(z.string(), z.unknown())
+  }).optional(),
+  correctionTrace: z.array(
+    z.object({
+      tier: z.union([z.literal(1), z.literal(2)]),
+      errorCode: z.string().min(1),
+      field: z.string().min(1),
+      was: z.unknown(),
+      correctedTo: z.unknown(),
+      strategy: z.string().min(1)
+    })
+  ).optional()
+});
+var ZoneTraceSchema = z.object({
+  /** Unique zone-trace identifier. */
+  id: z.string().min(1, "Zone trace ID is required."),
+  /** The raw ComponentIntent that triggered compilation. */
+  intent: ComponentIntentSchema,
+  /**
+   * Compilation outcome data — status, errors, and self-correction attempts.
+   * Subset of the full TraceCompilation shape.
+   */
+  compilation: z.object({
+    /** Final compilation status. */
+    status: z.enum(["pass", "fail", "corrected"]),
+    /** Validation errors encountered during compilation. */
+    errors: z.array(CompilationErrorSchema),
+    /** Number of self-correction attempts made before final result. */
+    selfCorrectionAttempts: z.number().int().min(0)
+  }),
+  /**
+   * Provenance metadata from the CompilationResult.
+   * Mirrors the CompilationProvenance type shape exactly.
+   */
+  provenance: z.object({
+    /** Identifier of the AI agent/model. */
+    agent: z.string().min(1),
+    /** URL or name of the registry used. */
+    registry: z.string().min(1),
+    /** ISO 8601 timestamp when compilation occurred. */
+    compiledAt: z.string().min(1),
+    /** Semantic version of the compiler. */
+    compilerVersion: z.string().min(1),
+    /** Forge mode used, if the component was forged. */
+    forgeMode: z.enum(["local", "cloud"]).optional(),
+    /** Origin metadata for remote contracts. */
+    contractOrigin: z.object({
+      registryUrl: z.string(),
+      publisher: z.string()
+    }).optional()
+  }),
+  /** Zone-level performance metrics. */
+  metrics: z.object({
+    /** Total time from intent reception to render in milliseconds. */
+    totalMs: z.number().min(0),
+    /** Current retry attempt number (0-indexed). */
+    retryAttempt: z.number().int().min(0)
+  }),
+  /** ISO 8601 timestamp when this trace was created. */
+  timestamp: z.string().min(1, "Timestamp is required.")
+});
+var AgentTraceSchema = z.object({
+  id: z.string().min(1, "Trace ID is required."),
+  timestamp: z.string().min(1, "Timestamp is required."),
+  correlationId: z.string().optional(),
+  intent: z.object({
+    raw: z.string(),
+    component: z.string().min(1),
+    confidence: z.number().min(0).max(1),
+    mode: z.string().optional(),
+    interaction: z.string().optional()
+  }),
+  resolution: z.object({
+    strategy: z.enum(["exact", "semantic", "forge", "fallback"]),
+    resolvedComponent: z.string().min(1),
+    similarityScore: z.number().min(0).max(1).optional(),
+    candidatesConsidered: z.number().int().min(0)
+  }),
+  compilation: z.object({
+    status: z.enum(["pass", "fail", "corrected"]),
+    errorCount: z.number().int().min(0),
+    selfCorrectionAttempts: z.number().int().min(0),
+    tokensValidated: z.boolean(),
+    accessibilityInjected: z.boolean()
+  }),
+  determinism: z.object({
+    level: z.number().min(0).max(1),
+    cacheHit: z.boolean(),
+    zone: z.string().min(1)
+  }),
+  metrics: z.object({
+    totalMs: z.number().min(0),
+    resolutionMs: z.number().min(0),
+    compilationMs: z.number().min(0),
+    renderMs: z.number().min(0)
+  }),
+  consent: z.object({
+    anonymizedAggregation: z.boolean()
+  })
+});
+var ZoneConfigSchema = z.object({
+  id: z.string().min(1, "Zone ID is required."),
+  name: z.string().min(1, "Zone name is required."),
+  determinism: z.number().min(0, "Determinism must be >= 0.").max(1, "Determinism must be <= 1."),
+  allowedComponents: z.array(z.string()),
+  fallbackComponent: z.string().min(1, "Fallback component is required."),
+  agentTimeoutMs: z.number().int().positive("Agent timeout must be positive."),
+  cache: z.object({
+    enabled: z.boolean(),
+    ttl: z.number().int().positive("TTL must be positive.")
+  }),
+  activateOn: z.enum(["mount", "visible", "manual"])
+});
+var ForgeSignalSchema = z.object({
+  intentHash: z.string().min(1, "Intent hash is required."),
+  componentName: z.string().min(1, "Component name is required."),
+  intentCategory: z.enum([
+    "clinical",
+    "admin",
+    "navigation",
+    "data-display",
+    "form",
+    "feedback",
+    "utility"
+  ]),
+  compilationStatus: z.enum(["pass", "fail", "corrected"]),
+  forgeMode: z.enum(["none", "local", "cloud"]),
+  forgeUsed: z.boolean(),
+  latencyMs: z.number().min(0),
+  selfCorrectionAttempts: z.number().int().min(0),
+  correctionTokensUsed: z.number().int().min(0),
+  timestamp: z.string().min(1, "Timestamp is required."),
+  sdkVersion: z.string().min(1, "SDK version is required."),
+  registrySize: z.number().int().min(0),
+  platform: z.enum(["web", "native", "desktop", "cli", "unknown"])
+});
+var ZoneStateSchema = z.object({
+  name: z.string().min(1),
+  lifecycleState: z.enum(["loading", "ready", "streaming", "error", "empty"]),
+  determinism: z.number().min(0).max(1),
+  lastComponent: z.string().optional(),
+  lastUpdated: z.string().min(1)
+});
+var SessionStateSchema = z.object({
+  id: z.string().min(1),
+  threadId: z.string().optional(),
+  startedAt: z.string().min(1)
+});
+var SerializedStateSchema = z.object({
+  schemaVersion: z.string().min(1, "Schema version is required."),
+  zones: z.record(z.string(), ZoneStateSchema),
+  traceIds: z.array(z.string()),
+  session: SessionStateSchema,
+  extensions: z.record(z.string(), z.unknown())
+});
+var UserSignalSchema = z.object({
+  type: z.enum(["click", "submit", "input", "custom"]),
+  zone: z.string().min(1, "Zone name is required."),
+  component: z.string().min(1, "Component name is required."),
+  payload: z.record(z.string(), z.unknown()),
+  timestamp: z.string().min(1, "Timestamp is required."),
+  correlationId: z.string().optional()
+});
+var SemanticSearchResultSchema = z.object({
+  /** PascalCase name of the matched component. */
+  componentName: z.string().min(1),
+  /**
+   * Cosine similarity score. Clamped to [0.0, 1.0].
+   */
+  similarity: z.number().min(0).max(1),
+  /** The matched component's full contract. */
+  contract: ComponentContractSchema
+});
+var ForgeResultSchema = z.object({
+  success: z.boolean(),
+  /**
+   * `z.unknown().nullable()` instead of `ComponentContractSchema.nullable()`
+   * to avoid circular schema references (forge → contract → compiler).
+   * TS type is properly typed as `ComponentContract | null`.
+   */
+  contract: z.unknown().nullable(),
+  /**
+   * `z.unknown().nullable()` for the same reason — avoids circular
+   * schema dependency with `CompilationResultSchema`.
+   * TS type is properly typed as `CompilationResult | null`.
+   */
+  compilationResult: z.unknown().nullable(),
+  fallbackUsed: z.boolean(),
+  forgeMode: z.enum(["local", "cloud"])
+});
+var ForgeTraceRecordSchema = z.object({
+  intentSlug: z.string().min(1),
+  intentHash: z.string().min(1),
+  forgeMode: z.enum(["local", "cloud"]),
+  success: z.boolean(),
+  timestamp: z.string().min(1),
+  context: z.record(z.string(), z.unknown()).optional()
+});
+
+// src/guards.ts
+function isComponentId(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isZoneId(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isTraceId(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isForgeSignal(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["intentHash"] === "string" && typeof obj["componentName"] === "string" && typeof obj["compilationStatus"] === "string" && typeof obj["forgeMode"] === "string" && typeof obj["latencyMs"] === "number" && typeof obj["timestamp"] === "string";
+}
+function isCompilationResult(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["componentName"] === "string" && typeof obj["status"] === "string" && typeof obj["provenance"] === "object" && obj["provenance"] !== null && Array.isArray(obj["errors"]);
+}
+function isComponentIntent(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["component"] === "string" && typeof obj["props"] === "object" && obj["props"] !== null && typeof obj["confidence"] === "number";
+}
+function isAgentTrace(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["id"] === "string" && typeof obj["timestamp"] === "string" && typeof obj["intent"] === "object" && obj["intent"] !== null && typeof obj["resolution"] === "object" && obj["resolution"] !== null && typeof obj["compilation"] === "object" && obj["compilation"] !== null;
+}
+function isUserSignal(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["type"] === "string" && typeof obj["zone"] === "string" && typeof obj["component"] === "string" && typeof obj["payload"] === "object" && obj["payload"] !== null && typeof obj["timestamp"] === "string";
+}
+
+export { AgentTraceSchema, CompilationErrorSchema, CompilationResultSchema, ComponentContractSchema, ComponentIntentSchema, DesignTokenSetSchema, ENTERSTELLAR_TYPES_VERSION, EnterstellarError, ForgeResultSchema, ForgeSignalSchema, ForgeTraceRecordSchema, SemanticSearchResultSchema, SerializedStateSchema, SessionStateSchema, UserSignalSchema, ZoneConfigSchema, ZoneStateSchema, ZoneTraceSchema, createComponentId, createTraceId, createZoneId, isAgentTrace, isCompilationResult, isComponentId, isComponentIntent, isForgeSignal, isTraceId, isUserSignal, isZoneId };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map