@xemahq/dsl 0.8.0 → 0.8.2

package/src/payload-codec/lib/errors.ts

@@ -1,54 +0,0 @@
-/**
- * Typed error codes emitted by the spill codec. Callers MUST branch on
- * `.code` — free-form message matching is forbidden, because these errors
- * travel across process + network boundaries (Temporal workflow ↔ engine)
- * and need a stable identity.
- */
-export enum PayloadCodecErrorCode {
-  /** Input payload shape is invalid (e.g. missing data). */
-  INVALID_PAYLOAD = 'INVALID_PAYLOAD',
-  /** BlobStore.put failed during encode. */
-  BLOB_PUT_FAILED = 'BLOB_PUT_FAILED',
-  /** BlobStore.get failed during decode. */
-  BLOB_GET_FAILED = 'BLOB_GET_FAILED',
-  /** Received a spilled payload but no BlobStore is configured. */
-  NO_BLOB_STORE_CONFIGURED = 'NO_BLOB_STORE_CONFIGURED',
-  /** Spill envelope is malformed or uses an unknown version. */
-  MALFORMED_ENVELOPE = 'MALFORMED_ENVELOPE',
-  /** Envelope declares a store kind this codec doesn't know. */
-  UNKNOWN_STORE_KIND = 'UNKNOWN_STORE_KIND',
-  /** sha256 mismatch between envelope declaration and fetched blob. */
-  SHA256_MISMATCH = 'SHA256_MISMATCH',
-  /** orgIdProvider returned no orgId at encode time (fail-fast — no silent fallback). */
-  ORG_ID_REQUIRED = 'ORG_ID_REQUIRED',
-}
-
-export class PayloadCodecError extends Error {
-  readonly code: PayloadCodecErrorCode;
-  readonly details: Readonly<Record<string, unknown>>;
-
-  constructor(
-    code: PayloadCodecErrorCode,
-    message: string,
-    details: Readonly<Record<string, unknown>> = {},
-  ) {
-    super(message);
-    this.name = 'PayloadCodecError';
-    this.code = code;
-    this.details = details;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-
-  toJSON(): Readonly<Record<string, unknown>> {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      details: this.details,
-    };
-  }
-}
-
-export function isPayloadCodecError(err: unknown): err is PayloadCodecError {
-  return err instanceof PayloadCodecError;
-}

package/src/payload-codec/lib/http-blob-store.ts

@@ -1,267 +0,0 @@
-import type { Response as UndiciResponse } from 'undici-types';
-
-import { BlobStoreKind } from './enums';
-import { PayloadCodecError, PayloadCodecErrorCode } from './errors';
-import {
-  type BlobRef,
-  type BlobStore,
-  type StoredBlob,
-  sha256Hex,
-} from './blob-store';
-
-export interface HttpBlobStoreOptions {
-  /**
-   * Resolves the `artifact-store-api` base URL. Invoked PER REQUEST so the
-   * store is boot-order-safe (no URL is needed at construction time) and
-   * topology-safe under horizontal scaling — wire it to the service
-   * registry, e.g.
-   * `() => resolveHttpUrl(registry, ServiceName.ARTIFACT_STORE_API)`.
-   * Resolution is a cheap in-memory registry-cache read, so per-request
-   * resolution is correct rather than caching a possibly-stale instance URL.
-   */
-  readonly resolveBaseUrl: () => string | Promise<string>;
-  /**
-   * Async provider for the service identity JWT. The codec mints new
-   * requests on every put/get so the token can expire without a restart.
-   */
-  readonly tokenProvider: () => Promise<string>;
-  /** Optional correlation id; appended to `X-Correlation-Id`. */
-  readonly correlationIdProvider?: () => string | null;
-  /** Absolute timeout for an individual put/get request (ms). */
-  readonly requestTimeoutMs?: number;
-}
-
-const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
-const PUT_PATH = '/blobs';
-const GET_PATH_PREFIX = '/blobs/';
-
-/**
- * BlobStore backed by `artifact-store-api`. Contract the service exposes:
- *
- *   POST /blobs  Content-Type: any
- *     headers: Authorization: Bearer <jwt>; X-Xema-Org-Id: <tenant>
- *     body: raw bytes
- *     response: { data: { sha256, sizeBytes, contentType, createdAt } }
- *
- *   GET /blobs/:sha256
- *     headers: Authorization: Bearer <jwt>; X-Xema-Org-Id: <tenant>
- *     response: raw bytes, Content-Type header from the upload
- *
- * `X-Xema-Org-Id` is required on every call — the artifact-store-api scopes
- * blob rows by `(orgId, sha256)`, so reads/writes must declare a tenant.
- * The codec passes the orgId at the call site (encode reads it from the
- * configured orgIdProvider; decode reads it from the spill envelope).
- *
- * Authentication is service-to-service — the caller provides a bearer
- * token (minted via `identity-api`). Idempotent: the server dedupes by
- * `(orgId, sha256)`.
- */
-export class HttpBlobStore implements BlobStore {
-  readonly kind = BlobStoreKind.ARTIFACT_STORE;
-
-  constructor(private readonly options: HttpBlobStoreOptions) {}
-
-  async put(
-    bytes: Uint8Array,
-    contentType: string,
-    orgId: string,
-  ): Promise<StoredBlob> {
-    assertOrgId(orgId);
-    const token = await this.options.tokenProvider();
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () => controller.abort(),
-      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-    );
-    try {
-      // Node's undici fetch accepts Uint8Array directly; Buffer is a
-      // Uint8Array subclass AND a documented BodyInit in @types/node's
-      // ambient fetch types, so wrap once to keep TS happy without `any`.
-      const response = (await fetch(await this.resolveUrl(PUT_PATH), {
-        method: 'POST',
-        headers: this.buildHeaders(token, contentType, orgId),
-        body: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
-        signal: controller.signal,
-      })) as unknown as UndiciResponse;
-      if (!response.ok) {
-        throw new PayloadCodecError(
-          PayloadCodecErrorCode.BLOB_PUT_FAILED,
-          `artifact-store-api POST /blobs failed: ${response.status} ${response.statusText}`,
-          { status: response.status, orgId },
-        );
-      }
-      const parsed = (await response.json()) as {
-        data?: {
-          sha256?: unknown;
-          sizeBytes?: unknown;
-          contentType?: unknown;
-          createdAt?: unknown;
-          uri?: unknown;
-        };
-      };
-      const data = parsed.data;
-      if (!data || typeof data.sha256 !== 'string') {
-        throw new PayloadCodecError(
-          PayloadCodecErrorCode.BLOB_PUT_FAILED,
-          'artifact-store-api POST /blobs: malformed response envelope.',
-          { received: parsed },
-        );
-      }
-      const expectedSha = sha256Hex(bytes);
-      if (data.sha256 !== expectedSha) {
-        throw new PayloadCodecError(
-          PayloadCodecErrorCode.SHA256_MISMATCH,
-          'artifact-store-api returned a different sha256 than the client computed.',
-          { expected: expectedSha, received: data.sha256 },
-        );
-      }
-      // The current artifact-store BlobResponseDto omits `uri`; the (orgId,
-      // sha256) pair is canonical for retrieval, so we synthesize a
-      // stable handle for diagnostics.
-      const uri =
-        typeof data.uri === 'string' && data.uri.length > 0
-          ? data.uri
-          : `artifact-store://${orgId}/${data.sha256}`;
-      const sizeBytes =
-        typeof data.sizeBytes === 'number' ? data.sizeBytes : bytes.byteLength;
-      const contentTypeOut =
-        typeof data.contentType === 'string' ? data.contentType : contentType;
-      const createdAt =
-        typeof data.createdAt === 'string'
-          ? data.createdAt
-          : new Date().toISOString();
-      return {
-        store: this.kind,
-        uri,
-        sha256: data.sha256,
-        orgId,
-        sizeBytes,
-        contentType: contentTypeOut,
-        createdAt,
-      };
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async get(ref: BlobRef): Promise<Uint8Array> {
-    if (ref.store !== this.kind) {
-      throw new PayloadCodecError(
-        PayloadCodecErrorCode.UNKNOWN_STORE_KIND,
-        `HttpBlobStore cannot read blobs from store '${ref.store}'.`,
-        { expected: this.kind, received: ref.store },
-      );
-    }
-    assertOrgId(ref.orgId);
-    const token = await this.options.tokenProvider();
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () => controller.abort(),
-      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-    );
-    try {
-      const response = (await fetch(
-        await this.resolveUrl(`${GET_PATH_PREFIX}${encodeURIComponent(ref.sha256)}`),
-        {
-          method: 'GET',
-          headers: this.buildHeaders(token, 'application/octet-stream', ref.orgId),
-          signal: controller.signal,
-        },
-      )) as unknown as UndiciResponse;
-      if (!response.ok) {
-        throw new PayloadCodecError(
-          PayloadCodecErrorCode.BLOB_GET_FAILED,
-          `artifact-store-api GET /blobs/${ref.sha256} failed: ${response.status} ${response.statusText}`,
-          { status: response.status, sha256: ref.sha256, orgId: ref.orgId },
-        );
-      }
-      const buffer = new Uint8Array(await response.arrayBuffer());
-      const actualSha = sha256Hex(buffer);
-      if (actualSha !== ref.sha256) {
-        throw new PayloadCodecError(
-          PayloadCodecErrorCode.SHA256_MISMATCH,
-          'Blob fetched from artifact-store-api does not match the requested sha256.',
-          { expected: ref.sha256, actual: actualSha },
-        );
-      }
-      return buffer;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async delete(
-    ref: Pick<BlobRef, 'sha256' | 'orgId'>,
-  ): Promise<{ deleted: boolean }> {
-    assertOrgId(ref.orgId);
-    const token = await this.options.tokenProvider();
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () => controller.abort(),
-      this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-    );
-    try {
-      const response = (await fetch(
-        await this.resolveUrl(`${GET_PATH_PREFIX}${encodeURIComponent(ref.sha256)}`),
-        {
-          method: 'DELETE',
-          headers: this.buildHeaders(token, 'application/octet-stream', ref.orgId),
-          signal: controller.signal,
-        },
-      )) as unknown as UndiciResponse;
-      if (response.status === 204) {
-        // artifact-store-api returns 204 whether or not the row existed
-        // (idempotent). We log the call site's perspective ("requested
-        // delete completed") rather than the row-existed dimension —
-        // the sweeper persists the actual deletion count from its own
-        // database delete in the SnapshotPointer table.
-        return { deleted: true };
-      }
-      if (response.status === 404) {
-        // Defensive: some auth proxies surface 404 for cross-tenant
-        // misses. Treat as "already gone" so retries don't loop.
-        return { deleted: false };
-      }
-      throw new PayloadCodecError(
-        PayloadCodecErrorCode.BLOB_GET_FAILED,
-        `artifact-store-api DELETE /blobs/${ref.sha256} failed: ${response.status} ${response.statusText}`,
-        { status: response.status, sha256: ref.sha256, orgId: ref.orgId },
-      );
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  private async resolveUrl(path: string): Promise<string> {
-    const raw = await this.options.resolveBaseUrl();
-    if (!raw) {
-      throw new Error(
-        'HttpBlobStore: resolveBaseUrl() returned an empty URL — the ' +
-          'artifact-store-api peer could not be resolved.',
-      );
-    }
-    return `${raw.replace(/\/+$/, '')}${path}`;
-  }
-
-  private buildHeaders(token: string, contentType: string, orgId: string): Headers {
-    const headers = new Headers({
-      Authorization: `Bearer ${token}`,
-      'Content-Type': contentType,
-      'X-Xema-Org-Id': orgId,
-    });
-    const correlationId = this.options.correlationIdProvider?.();
-    if (correlationId) {
-      headers.set('X-Correlation-Id', correlationId);
-    }
-    return headers;
-  }
-}
-
-function assertOrgId(orgId: string): void {
-  if (typeof orgId !== 'string' || orgId.length === 0) {
-    throw new PayloadCodecError(
-      PayloadCodecErrorCode.ORG_ID_REQUIRED,
-      'HttpBlobStore operations require a non-empty orgId for X-Xema-Org-Id.',
-    );
-  }
-}

package/src/payload-codec/lib/lru-cache.ts

@@ -1,81 +0,0 @@
-/**
- * Tiny byte-capacity LRU cache keyed by string (sha256). Kept intentionally
- * dependency-free — adding a full LRU lib for this alone would bloat the
- * package. Map's insertion-order iteration gives us O(1) recency tracking:
- * re-insert on access, evict from the front when over budget.
- *
- * Entries that exceed the cache's total capacity are refused outright
- * (returned bytes bypass the cache). This avoids the anti-pattern where
- * inserting a single huge value evicts everything else.
- */
-export class BytesLruCache {
-  private readonly entries = new Map<string, Uint8Array>();
-  private totalBytes = 0;
-
-  constructor(private readonly capacityBytes: number) {
-    if (!Number.isFinite(capacityBytes) || capacityBytes < 0) {
-      throw new Error(`BytesLruCache: capacityBytes must be a non-negative finite number, got ${capacityBytes}.`);
-    }
-  }
-
-  /**
-   * Return cached bytes for `key`, or null if absent. Accessing an entry
-   * marks it most-recently-used (moves to the back of the Map).
-   */
-  get(key: string): Uint8Array | null {
-    const found = this.entries.get(key);
-    if (found === undefined) {
-      return null;
-    }
-    // Refresh LRU position.
-    this.entries.delete(key);
-    this.entries.set(key, found);
-    return found;
-  }
-
-  /**
-   * Insert `value` under `key`. If `value` is larger than the total
-   * capacity, the cache skips insertion and the caller receives the
-   * untouched bytes. Evicts oldest entries until under capacity.
-   */
-  put(key: string, value: Uint8Array): void {
-    if (value.byteLength > this.capacityBytes) {
-      return; // Too big; don't thrash the cache.
-    }
-    if (this.entries.has(key)) {
-      const prev = this.entries.get(key)!;
-      this.totalBytes -= prev.byteLength;
-      this.entries.delete(key);
-    }
-    this.entries.set(key, value);
-    this.totalBytes += value.byteLength;
-    while (this.totalBytes > this.capacityBytes) {
-      const oldest = this.entries.keys().next();
-      if (oldest.done === true) {
-        break;
-      }
-      const evicted = this.entries.get(oldest.value);
-      if (evicted === undefined) {
-        break;
-      }
-      this.totalBytes -= evicted.byteLength;
-      this.entries.delete(oldest.value);
-    }
-  }
-
-  /** Clears the cache. Used by tests. */
-  clear(): void {
-    this.entries.clear();
-    this.totalBytes = 0;
-  }
-
-  /** Current occupancy in bytes. Used by tests + instrumentation. */
-  get size(): number {
-    return this.totalBytes;
-  }
-
-  /** Current number of entries. Used by tests. */
-  get count(): number {
-    return this.entries.size;
-  }
-}

package/src/payload-codec/lib/payload.ts

@@ -1,26 +0,0 @@
-/**
- * Engine-agnostic payload shapes used by the spill codec.
- *
- * These mirror the structural shape of a workflow-engine payload and codec —
- * a `data` byte buffer plus string→bytes `metadata`, and an encode/decode pair
- * over payload batches. Defining them here keeps the codec free of any direct
- * workflow-engine dependency. The binding to a concrete engine (currently
- * Temporal) lives in a separate adapter — see
- * `@xemahq/dsl/payload-codec/temporal` — so switching engines means adding a
- * sibling adapter, not changing the codec core.
- *
- * The shapes are intentionally structural: any codec implementing this
- * interface is assignable to a matching engine `PayloadCodec` interface.
- */
-
-/** A single payload: optional raw bytes plus optional string→bytes metadata. */
-export interface Payload {
-  metadata?: Record<string, Uint8Array> | null;
-  data?: Uint8Array | null;
-}
-
-/** Symmetric encode/decode over batches of {@link Payload}s. */
-export interface PayloadCodec {
-  encode(payloads: Payload[]): Promise<Payload[]>;
-  decode(payloads: Payload[]): Promise<Payload[]>;
-}

package/src/payload-codec/temporal/index.ts

@@ -1,36 +0,0 @@
-/**
- * Temporal binding for the spill payload codec.
- *
- * This is the ONLY module in `payload-codec` that references
- * `@temporalio/common`; everything else is engine-agnostic (see
- * `../lib/payload`). To target a different workflow engine, add a sibling
- * adapter — the codec core does not change.
- *
- * `@temporalio/common` is an OPTIONAL peer dependency: install it only if you
- * import this adapter. Consumers using just the engine-agnostic codec core
- * (`@xemahq/dsl/payload-codec`) do not need Temporal at all.
- */
-import type {
-  Payload as TemporalPayload,
-  PayloadCodec as TemporalPayloadCodec,
-} from '@temporalio/common';
-
-import type { PayloadCodec } from '../lib/payload';
-
-/**
- * Present an engine-agnostic {@link PayloadCodec} (e.g. `SpillPayloadCodec`)
- * as a Temporal `PayloadCodec` for registration on a Temporal Client/Worker.
- *
- * This is a typed pass-through with no runtime cost. Its signature also serves
- * as a compile-time guarantee that the engine-agnostic shapes remain
- * structurally compatible with Temporal's: if a future Temporal release
- * diverges, this module fails to build — a signal to update the adapter, not
- * the codec core.
- */
-export function asTemporalPayloadCodec(
-  codec: PayloadCodec,
-): TemporalPayloadCodec {
-  return codec;
-}
-
-export type { TemporalPayload, TemporalPayloadCodec };

package/src/workflow/index.ts

@@ -1,108 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Xema Workflow DSL — Barrel Export ──
-//
-// Pure TypeScript package (no NestJS, no Temporal, no DB access). Exposes:
-//   - JSON Schema Draft 2020-12 validation for workflow / reusable-workflow
-//     / action documents.
-//   - A deterministic expression engine (no `eval`, closed grammar).
-//   - A semantic compiler that produces CompiledRun structures consumed by
-//     workflow-engine-api and workflow-runtime-worker.
-//
-// Consumers: `workflow-engine-api` (compile + seed), `workflow-runtime-worker`
-// (evaluate `if`/outputs/matrix-from/mount-plan at dispatch), and CI scripts
-// that validate authored YAML in `biomes/software-dev/workflow-config/`.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export { WorkflowDslError, isWorkflowDslError } from './lib/errors';
-export {
-  validateActionInputs,
-  type ActionInputValidationFailure,
-  type ActionInputValidationResult,
-} from './lib/action-input-validator';
-export {
-  InstallationResourceKind,
-  collectInstallationResourceHints,
-  type InstallationResourceFieldHint,
-} from './lib/installation-resource-kind';
-export type { InstallationCompileScope } from './lib/compiler/types';
-export {
-  parseAndValidateActionYaml,
-  parseAndValidateReusableWorkflowYaml,
-  parseAndValidateWorkflowYaml,
-  validateActionManifest,
-  validateReusableWorkflowDocument,
-  validateWorkflowDocument,
-} from './lib/validate';
-export {
-  EMPTY_CONTEXT_SEEDS,
-  ExpressionFunction,
-  ExpressionNodeKind,
-  ExpressionRoot,
-  compileExpression,
-  evaluateExpression,
-  extractInterpolations,
-  isInterpolationWrapped,
-  stripInterpolation,
-  type ExpressionContext,
-  type ExpressionNode,
-  type NeedsEntry,
-} from './lib/expression';
-export { parseDurationMs } from './lib/duration';
-export {
-  DispatchInputFieldType,
-  DispatchInputStringFormat,
-  extractDispatchInputDescriptors,
-  type DispatchInputDescriptor,
-} from './lib/dispatch-inputs';
-export { dispatchInputsToJsonSchema } from './lib/dispatch-inputs/to-json-schema';
-export { serializeWorkflowDocument } from './lib/serializer';
-export {
-  DECISION_GATE_ACTION_ID,
-  applyGateDefaults,
-  canonicalJsonSha256,
-  canonicalJsonStringify,
-  compileManifestSource,
-  compileWorkflow,
-  getWorkspaceManifestContract,
-  isAgentShapedAction,
-  type CompileInput,
-  type ResolvedAgentMeta,
-  type ResolvedDeliverableSpec,
-  type ResolvedRef,
-} from './lib/compiler';
-export {
-  extractZodTopLevelObjectKeys,
-  extractJsonSchemaTopLevelKeys,
-} from './lib/deliverable-spec-keys';
-export {
-  DeliverableSpecIntrospectionError,
-  DeliverableSpecIntrospectionFailure,
-  isDeliverableSpecIntrospectionError,
-} from './lib/deliverable-spec-introspection-error';
-export { scanTopLevelZodObjectDeclarations } from './lib/deliverable-spec-source-scan';
-export type { TopLevelZodObjectDeclaration } from './lib/deliverable-spec-source-scan';
-export type {
-  ActionContract,
-  ActionManifest,
-  ActionManifestMetadata,
-  ActionManifestRetryDefaults,
-  ActionManifestSpec,
-  ActionManifestTimeoutDefaults,
-  WorkspaceManifestActionContract,
-  ScheduleDeclaration,
-  WebhookDeclaration,
-  WorkflowCallDeclaration,
-  WorkflowConcurrencyDeclaration,
-  WorkflowDefaults,
-  WorkflowGateDefaults,
-  WorkflowDispatchDeclaration,
-  WorkflowDocument,
-  WorkflowDynamicStrategyDeclaration,
-  WorkflowInputDeclaration,
-  WorkflowJobDeclaration,
-  WorkflowMetadata,
-  WorkflowPermissions,
-  WorkflowRetryDeclaration,
-  WorkflowStrategyDeclaration,
-  WorkflowTriggerDeclarations,
-} from './lib/types';