@xemahq/dsl 0.1.1

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

@@ -0,0 +1,248 @@
+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
+ * `DeliverableSpecKind` in
+ * `biomes/workflow-runtime/api/deliverable-specs-api/src/deliverable-specs/dto/deliverable-spec-enums.ts`
+ * — 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(),
+
+    // 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[]`' },
+  );
+
+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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,40 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// workflow-payload-codec — Temporal PayloadCodec that transparently spills
+// large payloads to a content-addressed BlobStore (artifact-store-api in
+// prod; in-memory in tests). Register this codec on the Client AND on the
+// Worker — both sides must decode the envelope symmetrically.
+// ═══════════════════════════════════════════════════════════════════════════
+
+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/codec-context.ts

@@ -0,0 +1,38 @@
+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-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);
+}