@xemahq/dsl 0.8.1 → 0.8.3

package/src/deliverable-spec/index.ts

@@ -1,19 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── @xemahq/deliverable-spec-dsl ──
-//
-// Zod schema for the `manifest.yaml` files that ship inside biome
-// `deliverable-specs/` content directories. A deliverable-spec manifest
-// declares the SHAPE of a single catalog row: kind, content body, page
-// layout, validator parameters.
-//
-// Consumers:
-//   - The deliverable-specs service: the seeder validates each manifest at
-//     boot using this schema; the schemas controller serves the JSON
-//     Schema rendition at `/schemas/deliverable-spec/v1.json` so authors
-//     can wire their YAML editor via `# yaml-language-server: $schema=…`.
-//
-// Sibling to `@xemahq/workflow-dsl` and `@xemahq/workspace-manifest-dsl`.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export * from './lib/schema';
-export * from './lib/types';

package/src/deliverable-spec/lib/schema.ts

@@ -1,270 +0,0 @@
-import { z } from 'zod';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Zod schemas for `manifest.yaml` (deliverable-spec) ──
-//
-// Single source of truth: the deliverable-specs-api seeder validates each
-// biome-shipped manifest with `DeliverableSpecManifestSchema.parse(…)`,
-// and the schemas controller serves `z.toJSONSchema(…)` at
-// `https://xema.dev/schemas/deliverable/v1/DeliverableSpec.json`. Authors
-// point Monaco / IDE YAML extensions at the served URL via
-// `# yaml-language-server: $schema=…`.
-//
-// Envelope shape mirrors workflow.yaml + workspace-manifest.yaml:
-//   apiVersion: xema.dev/deliverable/v1
-//   kind: DeliverableSpec | DeliverableSpecOverlay
-//   metadata: { slug, version, title, description? }   (overlay: slug, title)
-//   spec: { kind, category, …, content?, pages?, … }
-// ═══════════════════════════════════════════════════════════════════════════
-
-// Kebab-case slug, optionally namespaced (`foo-bar` or `family/leaf`).
-const SlugRegex = /^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?$/;
-const VersionRegex = /^\d+\.\d+\.\d+$/;
-const KebabRegex = /^[a-z][a-z0-9-]*$/;
-// Overlay slugs are composed keys joining a stack/concern token to one
-// or more spec categories with `+` (e.g.
-// `react-architecture+api-design`). Lowercase alphanumerics, `-`, `+`.
-const OverlaySlugRegex = /^[a-z][a-z0-9-]*(?:\+[a-z][a-z0-9-]*)*$/;
-// Tag values are lowercase alphanumerics with `-`, `_`, `.` allowed
-// (e.g. `tensorflow`, `python-3.12`).
-const TagSlugRegex = /^[a-z0-9][a-z0-9-_.]*$/;
-
-/**
- * Closed set of deliverable kinds (the inner kind enum on `spec.kind` —
- * NOT to be confused with the envelope `kind: DeliverableSpec`). Mirrors
- * the `DeliverableSpecKind` enum used by the deliverable-specs service
- * — the wire values must stay byte-identical because they're persisted
- * verbatim to `DeliverableSpec.kind`.
- */
-export const DELIVERABLE_SPEC_KINDS = [
-  'DOCUMENT_TEMPLATE',
-  'ZOD_SCHEMA',
-  'JSON_SCHEMA',
-  'ENDPOINT_FETCH',
-  'STRUCTURED_JSON',
-  'CUSTOM',
-  'RESPONSE_ONLY',
-] as const;
-
-export type DeliverableSpecKindLiteral = (typeof DELIVERABLE_SPEC_KINDS)[number];
-
-/**
- * Closed set of artifact-versioning modes accepted by the harvester.
- * Mirrors `ArtifactVersioningMode` in `@xemahq/platform-common` — kept as
- * a string-literal trio here to keep this package free of platform deps.
- */
-export const VERSIONING_MODES = ['append', 'new', 'replace'] as const;
-
-export type VersioningModeLiteral = (typeof VERSIONING_MODES)[number];
-
-/**
- * Inline page entry — body is generated by the agent at run time from
- * `slug`/`title` alone. Stored as `{slug, title, parentSlug, content: null}`
- * in `DeliverableSpec.pages`.
- */
-export const InlinePageSourceSchema = z.object({
-  slug: z.string().regex(KebabRegex, 'page slug must be kebab-case'),
-  title: z.string().min(1).max(200),
-  parentSlug: z
-    .string()
-    .regex(KebabRegex)
-    .nullable()
-    .optional(),
-});
-
-/**
- * File-backed page entry — the seeder reads `<file>` relative to the
- * manifest, parses YAML frontmatter for `slug`/`title`/`parentSlug`, and
- * stores the remaining markdown body as `content`.
- */
-export const FilePageSourceSchema = z.object({
-  file: z.string().min(1),
-});
-
-export const PageSourceSchema = z.union([
-  InlinePageSourceSchema,
-  FilePageSourceSchema,
-]);
-
-const TargetSlotRegex = /^(?:deliverables\/|repos\/[a-z0-9][a-z0-9-_]*\/)$/;
-
-// ─── Envelope: DeliverableSpec ──────────────────────────────────────────
-
-export const DeliverableSpecMetadataSchema = z.object({
-  slug: z
-    .string()
-    .min(1)
-    .max(150)
-    .regex(
-      SlugRegex,
-      'slug must be kebab-case (`foo-bar`) or kebab/kebab (`family/leaf`)',
-    ),
-  version: z
-    .string()
-    .regex(VersionRegex, 'version must be strict semver (MAJOR.MINOR.PATCH)'),
-  title: z.string().min(1).max(200),
-  description: z.string().max(4000).optional(),
-});
-
-export const DeliverableSpecSpecSchema = z
-  .object({
-    kind: z.enum(DELIVERABLE_SPEC_KINDS),
-    category: z.string().regex(KebabRegex, 'category must be kebab-case').max(80),
-    complexity: z
-      .string()
-      .regex(KebabRegex, 'complexity must be kebab-case')
-      .optional(),
-    tags: z.array(z.string()).max(20).optional(),
-    phases: z.array(z.string()).max(20).optional(),
-    workTypes: z.array(z.string()).max(20).optional(),
-
-    // Authoritative body for DOCUMENT_TEMPLATE / JSON_SCHEMA /
-    // STRUCTURED_JSON / CUSTOM / RESPONSE_ONLY. Mutually exclusive with
-    // `contentFile` (the seeder reads the file relative to manifest.yaml
-    // when `contentFile` is set).
-    content: z.string().max(1_000_000).optional(),
-    contentFile: z.string().min(1).optional(),
-
-    multiPage: z.boolean().optional(),
-    pages: z.array(PageSourceSchema).max(64).optional(),
-
-    pageAllocationHints: z.record(z.string(), z.unknown()).optional(),
-    topologySchema: z.record(z.string(), z.unknown()).optional(),
-    sectionGuidance: z.record(z.string(), z.unknown()).optional(),
-    scope: z.record(z.string(), z.unknown()).optional(),
-    reviewDimensions: z.array(z.unknown()).optional(),
-    standards: z.array(z.unknown()).optional(),
-
-    // ZOD_SCHEMA-specific. Mutually exclusive with `zodSchemaSourceFile`.
-    zodSchemaSource: z.string().max(200_000).optional(),
-    zodSchemaSourceFile: z.string().min(1).optional(),
-    // Names WHICH exported `z.object({ … })` in the source is the
-    // deliverable contract. Required only when the source declares more
-    // than one top-level schema — with a single schema there is nothing
-    // to disambiguate. A multi-schema source without this fails fast at
-    // introspection rather than silently taking the first literal (which
-    // is an element/helper schema whenever the contract references one).
-    zodSchemaExport: z
-      .string()
-      .regex(
-        /^[A-Za-z_$][A-Za-z0-9_$]*$/,
-        'zodSchemaExport must be a JavaScript identifier (the exported const name)',
-      )
-      .optional(),
-
-    // ENDPOINT_FETCH-specific. Shape matches `EndpointFetchSpec` in
-    // `@xemahq/kernel-contracts/agent-workspace` — kept as an open record here
-    // to avoid a cross-package dependency; the activity validates the
-    // detailed shape at run time.
-    fetchSpec: z.record(z.string(), z.unknown()).optional(),
-
-    assets: z.array(z.unknown()).optional(),
-    rules: z.record(z.string(), z.unknown()).optional(),
-
-    targetSlot: z
-      .string()
-      .regex(
-        TargetSlotRegex,
-        "targetSlot must be 'deliverables/' or 'repos/<slug>/'",
-      )
-      .optional(),
-
-    versioningMode: z.enum(VERSIONING_MODES).optional(),
-  })
-  .refine(
-    (s) => !(s.content !== undefined && s.contentFile !== undefined),
-    { message: 'spec cannot declare both `content` and `contentFile`' },
-  )
-  .refine(
-    (s) =>
-      !(s.zodSchemaSource !== undefined && s.zodSchemaSourceFile !== undefined),
-    {
-      message:
-        'spec cannot declare both `zodSchemaSource` and `zodSchemaSourceFile`',
-    },
-  )
-  .refine(
-    (s) =>
-      !(s.multiPage === true && (s.pages === undefined || s.pages.length === 0)),
-    { message: 'multiPage=true requires non-empty `pages[]`' },
-  )
-  .refine(
-    (s) =>
-      s.zodSchemaExport === undefined ||
-      s.zodSchemaSource !== undefined ||
-      s.zodSchemaSourceFile !== undefined,
-    {
-      message:
-        '`zodSchemaExport` names an export in the Zod source, so it requires `zodSchemaSource` or `zodSchemaSourceFile`',
-    },
-  );
-
-export const DeliverableSpecManifestSchema = z
-  .object({
-    apiVersion: z.literal('xema.dev/deliverable/v1'),
-    kind: z.literal('DeliverableSpec'),
-    metadata: DeliverableSpecMetadataSchema,
-    spec: DeliverableSpecSpecSchema,
-  })
-  .meta({
-    id: 'https://xema.dev/schemas/deliverable/v1/DeliverableSpec.json',
-    title: 'Xema DeliverableSpec',
-    description:
-      'Biome-shipped catalog row defining a deliverable kind, content body, page layout, and validator parameters.',
-  });
-
-// ─── Envelope: DeliverableSpecOverlay ───────────────────────────────────
-
-export const DeliverableSpecOverlayMetadataSchema = z.object({
-  slug: z
-    .string()
-    .min(1)
-    .max(150)
-    .regex(
-      OverlaySlugRegex,
-      'overlay slug must be kebab tokens joined with `+` (e.g. `react-architecture+api-design`)',
-    ),
-  title: z.string().min(1).max(200),
-});
-
-export const DeliverableSpecOverlaySpecSchema = z
-  .object({
-    tagCategory: z
-      .string()
-      .min(1)
-      .max(80)
-      .regex(KebabRegex, 'tagCategory must be kebab-case'),
-    tagValue: z
-      .string()
-      .min(1)
-      .max(200)
-      .regex(
-        TagSlugRegex,
-        'tagValue must be a slug (lowercase alphanumerics, `+ . - _` allowed)',
-      ),
-    specCategories: z.array(z.string()).max(40).optional(),
-    content: z.string().max(1_000_000).optional(),
-    contentFile: z.string().min(1).optional(),
-    priority: z.number().int().min(0).max(1000).optional(),
-  })
-  .refine((s) => s.content !== undefined || s.contentFile !== undefined, {
-    message: 'spec must declare either `content` or `contentFile`',
-  })
-  .refine(
-    (s) => !(s.content !== undefined && s.contentFile !== undefined),
-    { message: 'spec cannot declare both `content` and `contentFile`' },
-  );
-
-export const DeliverableSpecOverlayManifestSchema = z
-  .object({
-    apiVersion: z.literal('xema.dev/deliverable/v1'),
-    kind: z.literal('DeliverableSpecOverlay'),
-    metadata: DeliverableSpecOverlayMetadataSchema,
-    spec: DeliverableSpecOverlaySpecSchema,
-  })
-  .meta({
-    id: 'https://xema.dev/schemas/deliverable/v1/DeliverableSpecOverlay.json',
-    title: 'Xema DeliverableSpecOverlay',
-    description:
-      'Tag-driven overlay that appends to a base spec\'s content when the render context\'s tags[] includes tagValue.',
-  });

package/src/deliverable-spec/lib/types.ts

@@ -1,26 +0,0 @@
-import type { z } from 'zod';
-
-import {
-  DeliverableSpecManifestSchema,
-  DeliverableSpecOverlayManifestSchema,
-  FilePageSourceSchema,
-  InlinePageSourceSchema,
-  PageSourceSchema,
-} from './schema';
-
-/**
- * TypeScript types inferred from the Zod schemas. Consumers prefer these
- * over the schemas themselves at compile time so refactors of the shape
- * surface as type errors at every call site.
- */
-export type DeliverableSpecManifest = z.infer<
-  typeof DeliverableSpecManifestSchema
->;
-
-export type DeliverableSpecOverlayManifest = z.infer<
-  typeof DeliverableSpecOverlayManifestSchema
->;
-
-export type InlinePageSource = z.infer<typeof InlinePageSourceSchema>;
-export type FilePageSource = z.infer<typeof FilePageSourceSchema>;
-export type PageSource = z.infer<typeof PageSourceSchema>;

package/src/payload-codec/index.ts

@@ -1,44 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// workflow-payload-codec — an engine-agnostic PayloadCodec that transparently
-// spills large payloads to a content-addressed BlobStore (an HTTP blob store
-// in prod; in-memory in tests). Register this codec on the Client AND on the
-// Worker — both sides must decode the envelope symmetrically. The core has no
-// workflow-engine dependency; the Temporal binding lives in the optional
-// `@xemahq/dsl/payload-codec/temporal` adapter.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export type { Payload, PayloadCodec } from './lib/payload';
-
-export {
-  BlobStoreKind,
-  DEFAULT_CACHE_CAPACITY_BYTES,
-  DEFAULT_SPILL_THRESHOLD_BYTES,
-  SPILL_ENCODING_V1,
-  SPILL_ENVELOPE_VERSION,
-  SpillMetadataKey,
-} from './lib/enums';
-export {
-  PayloadCodecError,
-  PayloadCodecErrorCode,
-  isPayloadCodecError,
-} from './lib/errors';
-export {
-  InMemoryBlobStore,
-  sha256Hex,
-  type BlobRef,
-  type BlobStore,
-  type StoredBlob,
-} from './lib/blob-store';
-export { HttpBlobStore, type HttpBlobStoreOptions } from './lib/http-blob-store';
-export { BytesLruCache } from './lib/lru-cache';
-export {
-  SpillPayloadCodec,
-  type SpillPayloadCodecOptions,
-  type CodecLifecycleEvent,
-  type CodecObserver,
-} from './lib/codec';
-export {
-  getCodecOrgId,
-  runWithCodecOrgId,
-  type CodecContext,
-} from './lib/codec-context';

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

@@ -1,176 +0,0 @@
-import { createHash } from 'node:crypto';
-
-import { BlobStoreKind } from './enums';
-import { PayloadCodecError, PayloadCodecErrorCode } from './errors';
-
-/**
- * Content-addressed blob stored by a BlobStore. The (orgId, sha256) pair
- * uniquely identifies a blob in a multi-tenant store; `uri` is the store's
- * opaque retrieval handle. The `orgId` MUST round-trip through the codec
- * envelope so a decoder can fetch the bytes back without ambient context.
- */
-export interface StoredBlob {
-  readonly store: BlobStoreKind;
-  readonly uri: string;
-  readonly sha256: string;
-  readonly orgId: string;
-  readonly sizeBytes: number;
-  readonly contentType: string;
-  readonly createdAt: string;
-}
-
-/** Reference to a stored blob — what the codec writes into the envelope. */
-export interface BlobRef {
-  readonly store: BlobStoreKind;
-  readonly uri: string;
-  readonly sha256: string;
-  readonly orgId: string;
-}
-
-/**
- * Generic blob store contract. Implementations MUST:
- *   - Content-address by (orgId, sha256); same bytes for the same org ⇒
- *     same uri.
- *   - Be idempotent: `put` of already-present (orgId, bytes) returns the
- *     existing row without throwing; `delete` of an absent (orgId, sha256)
- *     returns `{ deleted: false }` without throwing.
- *   - Verify sha256 on `get` and throw on mismatch.
- *
- * All implementations MUST NOT mutate their inputs. The codec reuses the
- * same Uint8Array across multiple payloads when batching.
- */
-export interface BlobStore {
-  readonly kind: BlobStoreKind;
-  put(bytes: Uint8Array, contentType: string, orgId: string): Promise<StoredBlob>;
-  get(ref: BlobRef): Promise<Uint8Array>;
-  /**
-   * Idempotent removal. Used by the workflow-engine retention sweeper
-   * after a `WorkflowRun` row is archived. Returns `{ deleted: true }`
-   * if a blob was actually removed, `{ deleted: false }` if no row was
-   * present (already-cleaned, retry-safe).
-   */
-  delete(ref: Pick<BlobRef, 'sha256' | 'orgId'>): Promise<{ deleted: boolean }>;
-}
-
-/**
- * In-memory BlobStore for tests + dev loopback. NOT horizontally scalable
- * — each process has its own map, so engine + worker don't share state.
- * Production must use HttpBlobStore against artifact-store-api.
- *
- * Tenant scoping mirrors the production store: rows are keyed by
- * `(orgId, sha256)` so a `get` with the wrong orgId returns BLOB_GET_FAILED
- * (matches the artifact-store-api behavior of returning 404 cross-org).
- */
-export class InMemoryBlobStore implements BlobStore {
-  readonly kind = BlobStoreKind.IN_MEMORY;
-  private readonly blobs = new Map<
-    string,
-    { bytes: Uint8Array; contentType: string; createdAt: string }
-  >();
-
-  async put(
-    bytes: Uint8Array,
-    contentType: string,
-    orgId: string,
-  ): Promise<StoredBlob> {
-    assertNonEmptyOrgId(orgId);
-    const sha256 = sha256Hex(bytes);
-    const key = makeKey(orgId, sha256);
-    const existing = this.blobs.get(key);
-    if (existing) {
-      return {
-        store: this.kind,
-        uri: `memory://${orgId}/${sha256}`,
-        sha256,
-        orgId,
-        sizeBytes: existing.bytes.byteLength,
-        contentType: existing.contentType,
-        createdAt: existing.createdAt,
-      };
-    }
-    const createdAt = new Date().toISOString();
-    this.blobs.set(key, { bytes, contentType, createdAt });
-    return {
-      store: this.kind,
-      uri: `memory://${orgId}/${sha256}`,
-      sha256,
-      orgId,
-      sizeBytes: bytes.byteLength,
-      contentType,
-      createdAt,
-    };
-  }
-
-  async get(ref: BlobRef): Promise<Uint8Array> {
-    if (ref.store !== this.kind) {
-      throw new PayloadCodecError(
-        PayloadCodecErrorCode.UNKNOWN_STORE_KIND,
-        `InMemoryBlobStore cannot read blobs from store '${ref.store}'.`,
-        { expected: this.kind, received: ref.store },
-      );
-    }
-    assertNonEmptyOrgId(ref.orgId);
-    const found = this.blobs.get(makeKey(ref.orgId, ref.sha256));
-    if (!found) {
-      throw new PayloadCodecError(
-        PayloadCodecErrorCode.BLOB_GET_FAILED,
-        `InMemoryBlobStore: no blob with sha256=${ref.sha256} for orgId=${ref.orgId}`,
-        { sha256: ref.sha256, orgId: ref.orgId },
-      );
-    }
-    const actualSha = sha256Hex(found.bytes);
-    if (actualSha !== ref.sha256) {
-      // Should be impossible — we keyed by sha256. Guard anyway because
-      // bytes-mutation bugs in callers would corrupt the Map.
-      throw new PayloadCodecError(
-        PayloadCodecErrorCode.SHA256_MISMATCH,
-        'InMemoryBlobStore: stored bytes no longer match the sha256 they were keyed by.',
-        { expected: ref.sha256, actual: actualSha },
-      );
-    }
-    return found.bytes;
-  }
-
-  async delete(
-    ref: Pick<BlobRef, 'sha256' | 'orgId'>,
-  ): Promise<{ deleted: boolean }> {
-    assertNonEmptyOrgId(ref.orgId);
-    const deleted = this.blobs.delete(makeKey(ref.orgId, ref.sha256));
-    return { deleted };
-  }
-
-  /** Test helper — number of stored blobs. */
-  size(): number {
-    return this.blobs.size;
-  }
-
-  /** Test helper — wipe the store. */
-  clear(): void {
-    this.blobs.clear();
-  }
-}
-
-/** Compute lowercase-hex sha256 of a byte buffer. */
-export function sha256Hex(bytes: Uint8Array): string {
-  return createHash('sha256').update(bytes).digest('hex');
-}
-
-// NUL is the separator because it cannot occur in an org id or a hex digest, so
-// no two distinct blobs can collide on a concatenation. It MUST stay spelled as
-// the unicode ESCAPE, never as a raw NUL byte in the source: one raw byte makes
-// every binary-skipping search tool (ugrep, ripgrep, `grep -I`) classify the
-// WHOLE file as binary and skip it silently, and a file no search can read is a
-// file no audit, no review and no boundary check covers. Enforced by the
-// aggregator boundary gate `grep-readable-sources`.
-function makeKey(orgId: string, sha256: string): string {
-  return `${orgId}\u0000${sha256}`;
-}
-
-function assertNonEmptyOrgId(orgId: string): void {
-  if (typeof orgId !== 'string' || orgId.length === 0) {
-    throw new PayloadCodecError(
-      PayloadCodecErrorCode.ORG_ID_REQUIRED,
-      'BlobStore operations require a non-empty orgId.',
-    );
-  }
-}

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

@@ -1,38 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-/**
- * Per-call codec context. Wrapping a Temporal client invocation in
- * {@link runWithCodecOrgId} lets the {@link SpillPayloadCodec}'s
- * `orgIdProvider` resolve the right tenant for blob writes:
- *
- *   await runWithCodecOrgId(run.orgId, () =>
- *     client.workflow.start('rootRunWorkflow', { args, ... }),
- *   );
- *
- * The engine establishes this around every `client.workflow.*` call so the
- * codec can stamp `X-Xema-Org-Id` on its blob-store traffic. The decode side
- * does NOT depend on this context — orgId rides inside the spill envelope.
- *
- * Workers don't typically use this ALS for codec calls (the worker reads
- * orgId from the active activity-auth-context or a fallback env var) but
- * the helpers are exported for symmetry.
- */
-export interface CodecContext {
-  readonly orgId: string;
-}
-
-const storage = new AsyncLocalStorage<CodecContext>();
-
-export function getCodecOrgId(): string | undefined {
-  return storage.getStore()?.orgId;
-}
-
-export async function runWithCodecOrgId<T>(
-  orgId: string,
-  fn: () => Promise<T>,
-): Promise<T> {
-  if (typeof orgId !== 'string' || orgId.length === 0) {
-    throw new Error('runWithCodecOrgId: orgId must be a non-empty string.');
-  }
-  return storage.run({ orgId }, fn);
-}