@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/agentic/workflow-coordinator.d.ts

@@ -0,0 +1,170 @@
+import { WorkflowInstanceRecord } from '@alneas/eaos-core';
+import { AgentGraphEngine, AgentGraphState } from './graph.js';
+import { ServerWorkflowManager, ServerWorkflowOptions } from './workflow-manager.js';
+import { ServerApprovalCallbackPayload } from './types.js';
+import '@langchain/langgraph';
+
+/**
+ * Durable business-instance record with host compare-and-swap revision.
+ * @see DurableWorkflowCoordinator.
+ */
+interface StoredWorkflowInstance {
+    /** Workflow instance ID, aligned with graph sessionId. */
+    id: string;
+    /** Host CAS revision, starting at one for coordinator-created records. */
+    revision: number;
+    /** Domain workflow instance metadata; graph payload remains in its checkpointer. */
+    value: WorkflowInstanceRecord;
+}
+/** Host-owned durable store for the companion workflow instance record.
+ * @see DurableWorkflowCoordinator for usage.
+ */
+interface WorkflowInstanceStore {
+    /**
+     * Reads an authorized tenant's companion instance.
+     * @param tenantId - Verified owning tenant.
+     * @param instanceId - Workflow session/instance ID.
+     * @returns Stored record, or null if absent.
+     * @throws Persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowInstanceStore } from "@alneas/eaos-server";
+     * export async function readTenantInstance(
+     *   store: WorkflowInstanceStore, verifiedTenantId: string, instanceId: string,
+     * ) {
+     *   const record = await store.read(verifiedTenantId, instanceId);
+     *   return record?.value.status; // A missing instance yields undefined here.
+     * }
+     * ```
+     */
+    read(tenantId: string, instanceId: string): Promise<StoredWorkflowInstance | null>;
+    /**
+     * Atomically inserts a new companion instance, rejecting duplicates.
+     * @param tenantId - Verified owning tenant.
+     * @param record - Initial revision-one queued record.
+     * @returns No value; resolves when durable creation completes.
+     * @throws Duplicate/conflicting identity or persistence failure must reject.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowInstanceStore } from "@alneas/eaos-server";
+     * export async function createQueuedInstance(
+     *   store: WorkflowInstanceStore, verifiedTenantId: string,
+     *   initialRecord: Parameters<WorkflowInstanceStore["create"]>[1],
+     * ) {
+     *   // Supply an aligned, admitted revision-one queued record.
+     *   await store.create(verifiedTenantId, initialRecord);
+     * }
+     * ```
+     */
+    create(tenantId: string, record: StoredWorkflowInstance): Promise<void>;
+    /**
+     * Atomically replaces a companion record only if its revision matches.
+     * @param tenantId - Verified owning tenant.
+     * @param record - Replacement with incremented revision.
+     * @param expectedRevision - Previously read revision required for CAS.
+     * @returns True on replacement, false on stale revision.
+     * @throws Persistence failures propagate.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowInstanceStore } from "@alneas/eaos-server";
+     * export async function replaceTenantInstance(
+     *   store: WorkflowInstanceStore, verifiedTenantId: string,
+     *   nextRecord: Parameters<WorkflowInstanceStore["replace"]>[1], previouslyReadRevision: number,
+     * ) {
+     *   // nextRecord has the incremented revision; false means another writer won.
+     *   return await store.replace(verifiedTenantId, nextRecord, previouslyReadRevision);
+     * }
+     * ```
+     */
+    replace(tenantId: string, record: StoredWorkflowInstance, expectedRevision: number): Promise<boolean>;
+}
+/**
+ * Workflow notification/approval callbacks plus durable companion-instance storage.
+ * @see DurableWorkflowCoordinator.
+ */
+interface DurableWorkflowCoordinatorOptions extends ServerWorkflowOptions {
+    /** Host-authorized tenant-scoped store with atomic create and revision checks. */
+    store: WorkflowInstanceStore;
+}
+/**
+ * Keeps the business workflow instance synchronized with the LangGraph
+ * checkpoint without making either one the other's database implementation.
+ * @remarks Checkpoint and companion record updates are separate operations; failures can leave them temporarily divergent. The host owns writer serialization, tenant authorization, durable stores, and reconciliation rather than blind retry after partial outcomes.
+ * @example
+ * ```typescript
+ * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+ * import type { DurableWorkflowCoordinatorOptions } from "@alneas/eaos-server/agentic/workflow-coordinator";
+ * export function coordinator(options: DurableWorkflowCoordinatorOptions) { return new DurableWorkflowCoordinator(options); }
+ * ```
+ */
+declare class DurableWorkflowCoordinator extends ServerWorkflowManager {
+    private readonly store;
+    /**
+     * Captures workflow callbacks and required durable instance store.
+     * @param options - Host store, approval notification, and live resume authorization.
+     * @throws If store is missing.
+     */
+    constructor(options: DurableWorkflowCoordinatorOptions);
+    /**
+     * Creates a queued companion instance then runs and persists its graph outcome.
+     * @param graph - Configured graph with appropriate checkpoint persistence.
+     * @param record - Host-admitted instance metadata; instanceId and tenantId must match initialState.
+     * @param initialState - Verified workflow identity and starting state.
+     * @returns Graph state after execution and companion CAS persistence.
+     * @throws Rejects alignment mismatch, existing instance, graph/callback/clone/store failures, or companion revision conflict.
+     * @remarks The queued record can exist even if graph execution later fails; no cross-store rollback occurs. Atomic duplicate prevention belongs to store.create.
+     * @example
+     * ```typescript
+     * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+     * import type { AgentGraphEngine, AgentGraphState } from "@alneas/eaos-server/agentic/graph";
+     * import type { WorkflowInstanceRecord } from "@alneas/eaos-core";
+     * export async function start(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, record: WorkflowInstanceRecord, state: AgentGraphState) { return coordinator.start(graph, record, state); }
+     * ```
+     */
+    start(graph: AgentGraphEngine, record: WorkflowInstanceRecord, initialState: AgentGraphState): Promise<AgentGraphState>;
+    /**
+     * Runs an existing graph instance and CAS-updates its companion status.
+     * @param graph - Graph whose session already has a companion record.
+     * @param initialState - Verified state aligned with that record.
+     * @returns Graph result after companion persistence; status prioritizes pending approval, error, completion, then running.
+     * @throws Graph/store/clock failures, missing companion, or changed revision; graph checkpoints may already have advanced.
+     * @example
+     * ```typescript
+     * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+     * import type { AgentGraphEngine, AgentGraphState } from "@alneas/eaos-server/agentic/graph";
+     * export async function run(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, state: AgentGraphState) { return coordinator.runWorkflow(graph, state); }
+     * ```
+     */
+    runWorkflow(graph: AgentGraphEngine, initialState: AgentGraphState): Promise<AgentGraphState>;
+    /**
+     * Resumes a verified graph approval then persists its resulting companion state.
+     * @param graph - Graph owning the pending checkpoint.
+     * @param payload - Host-authenticated approver decision and optional binding checks.
+     * @returns Resume outcome; companion persistence failure becomes resumed:false error data even when graph resume already succeeded.
+     * @throws Underlying graph/store failures outside normalized resume/persistence handling may reject.
+     * @remarks A false result does not prove no side effects occurred; reconcile graph and companion state before retrying.
+     * @example
+     * ```typescript
+     * import { DurableWorkflowCoordinator } from "@alneas/eaos-server/agentic/workflow-coordinator";
+     * import type { AgentGraphEngine } from "@alneas/eaos-server/agentic/graph";
+     * import type { ServerApprovalCallbackPayload } from "@alneas/eaos-server/agentic/types";
+     * export async function approve(coordinator: DurableWorkflowCoordinator, graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload) { return coordinator.handleApproval(graph, payload); }
+     * ```
+     */
+    handleApproval(graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload): Promise<{
+        /** True only when graph resumption and companion-instance persistence complete; false may also mean companion persistence failed after the graph advanced. */
+        resumed: boolean;
+        /** Optional resumed graph state returned when companion persistence succeeds; omitted when companion persistence is normalized into failure data. */
+        state?: AgentGraphState;
+        /** Optional graph resume or companion persistence failure detail; reconcile both stores before retrying because graph effects may already have completed. */
+        error?: string;
+    }>;
+    private runAndPersist;
+    private persist;
+}
+
+export { DurableWorkflowCoordinator };
+export type { DurableWorkflowCoordinatorOptions, StoredWorkflowInstance, WorkflowInstanceStore };

package/dist/agentic/workflow-coordinator.js

@@ -0,0 +1,8 @@
+import {
+  DurableWorkflowCoordinator
+} from "../chunk-EJKWDZIU.js";
+import "../chunk-FD6VC2NA.js";
+export {
+  DurableWorkflowCoordinator
+};
+//# sourceMappingURL=workflow-coordinator.js.map

package/dist/agentic/workflow-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/workflow-manager.d.ts

@@ -0,0 +1,91 @@
+import { AgentGraphState, AgentGraphEngine } from './graph.js';
+import { ServerApprovalCallbackPayload } from './types.js';
+import '@langchain/langgraph';
+import '@alneas/eaos-core';
+
+/**
+ * Host notification and approval authority callbacks used by {@link ServerWorkflowManager}.
+ */
+interface ServerWorkflowOptions {
+    /** Called after runStep returns pendingApproval; receives the returned state. Notification failures are warned and do not fail runWorkflow. */
+    onApprovalRequired?: (state: AgentGraphState) => Promise<void>;
+    /** Live host approval check receiving workflow state and verified approver/decision; must resolve true to permit resume. Errors are delegated to graph resume handling. */
+    authorizeResume?: (state: AgentGraphState, input: {
+        /**
+         * Host-authenticated approver identifier attached to the pending decision.
+         */
+        approverId: string;
+        /**
+         * Host-verified approver role to recheck against current resource/approval policy.
+         */
+        approverRole: string;
+        /**
+         * True requests continuation; false requests rejection, and a supplied authorizer also checks that decision.
+         */
+        approved: boolean;
+    }) => Promise<boolean>;
+}
+/**
+ * Coordinates graph execution and host approval notifications without choosing a notification transport.
+ * @remarks Checkpoint persistence and approval binding are delegated to AgentGraphEngine; the host authenticates approval callbacks. No webhook listener, retry queue, or delivery guarantee is installed.
+ * @example
+ * ```typescript
+ * import { ServerWorkflowManager, type ServerWorkflowOptions } from "@alneas/eaos-server/agentic/workflow-manager";
+ * export function workflowManager(options: ServerWorkflowOptions) {
+ *   return new ServerWorkflowManager(options);
+ * }
+ * ```
+ */
+declare class ServerWorkflowManager {
+    private onApprovalRequired?;
+    private authorizeResume?;
+    /**
+     * Captures optional host approval notification and authorization callbacks.
+     * @param options - Host callbacks; omitted options perform no external notification and supply no resume authorizer.
+     */
+    constructor(options?: ServerWorkflowOptions);
+    /**
+     * Runs the graph and notifies the host if execution pauses for approval.
+     * @param graph - Configured graph with appropriate durable checkpointer/admission.
+     * @param initialState - Verified workflow identity and starting state.
+     * @returns Graph state after runStep, including any pending approval; notification failures do not change it.
+     * @throws Rejects graph execution failures; notification errors are caught and warned.
+     * @example
+     * ```typescript
+     * import { ServerWorkflowManager } from "@alneas/eaos-server/agentic/workflow-manager";
+     * import type { AgentGraphEngine, AgentGraphState } from "@alneas/eaos-server/agentic/graph";
+     * export async function run(graph: AgentGraphEngine, initialState: AgentGraphState) {
+     *   return new ServerWorkflowManager().runWorkflow(graph, initialState);
+     * }
+     * ```
+     */
+    runWorkflow(graph: AgentGraphEngine, initialState: AgentGraphState): Promise<AgentGraphState>;
+    /**
+     * Delegates an authenticated approval decision to graph checkpoint/binding verification and resume.
+     * @param graph - Graph owning the pending task checkpoint.
+     * @param payload - Verified approver decision with optional approval/hash bindings; taskId selects the graph session.
+     * @returns Resume outcome, optional updated state, or failure data from resumeAfterApproval.
+     * @throws Propagates graph/checkpointer errors not normalized by resumeAfterApproval.
+     * @remarks The host verifies caller identity and role before constructing payload. This wrapper does not send a second approval notification after resume.
+     * @example
+     * ```typescript
+     * import { ServerWorkflowManager, type ServerWorkflowOptions } from "@alneas/eaos-server/agentic/workflow-manager";
+     * import type { AgentGraphEngine } from "@alneas/eaos-server/agentic/graph";
+     * import type { ServerApprovalCallbackPayload } from "@alneas/eaos-server/agentic/types";
+     * export async function approve(graph: AgentGraphEngine, options: ServerWorkflowOptions, payload: ServerApprovalCallbackPayload) {
+     *   return new ServerWorkflowManager(options).handleApproval(graph, payload);
+     * }
+     * ```
+     */
+    handleApproval(graph: AgentGraphEngine, payload: ServerApprovalCallbackPayload): Promise<{
+        /** Whether graph approval verification/resumption produced a saved state; false can follow partial effects and is not proof that nothing ran. */
+        resumed: boolean;
+        /** Optional graph checkpoint state returned after successful resumption; absent on the normalized failure paths. */
+        state?: AgentGraphState;
+        /** Optional normalized checkpoint, approval, authorization or invocation failure detail when resumed is false; other errors can still reject the Promise. */
+        error?: string;
+    }>;
+}
+
+export { ServerWorkflowManager };
+export type { ServerWorkflowOptions };

package/dist/agentic/workflow-manager.js

@@ -0,0 +1,7 @@
+import {
+  ServerWorkflowManager
+} from "../chunk-FD6VC2NA.js";
+export {
+  ServerWorkflowManager
+};
+//# sourceMappingURL=workflow-manager.js.map

package/dist/agentic/workflow-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/workflow-registry.d.ts

@@ -0,0 +1,334 @@
+import { WorkflowDefinitionLifecycle, WorkflowDefinition } from '@alneas/eaos-core';
+
+/**
+ * Versioned workflow definition with lifecycle, integrity hash, revision, and actor/timestamp metadata.
+ * @see InMemoryWorkflowDefinitionRegistry.
+ */
+interface WorkflowDefinitionRecord {
+    /** Workflow identifier copied from the validated definition. */
+    workflowId: string;
+    /** Immutable version key within a workflow after draft. */
+    version: string;
+    /** Current draft/validated/approved/published/retired lifecycle phase. */
+    status: WorkflowDefinitionLifecycle;
+    /** Validated serializable definition; returned records are cloned by this registry. */
+    definition: WorkflowDefinition;
+    /** Canonical SHA-256 definition hash calculated on saveDraft. */
+    definitionHash: string;
+    /** Record revision starting at one and incrementing on each saved transition. */
+    revision: number;
+    /** Creation timestamp from the registry clock. */
+    createdAt: string;
+    /** Latest transition timestamp from the registry clock. */
+    updatedAt: string;
+    /** Optional first author label. */
+    createdBy?: string;
+    /** Optional latest actor label. */
+    updatedBy?: string;
+    /** Optional approval timestamp. */
+    approvedAt?: string;
+    /** Optional approver label. */
+    approvedBy?: string;
+    /** Optional publication timestamp. */
+    publishedAt?: string;
+    /** Optional publisher label. */
+    publishedBy?: string;
+    /** Optional retirement timestamp. */
+    retiredAt?: string;
+    /** Optional retiring actor label. */
+    retiredBy?: string;
+}
+/**
+ * Workflow authoring lifecycle contract; durable hosts must supply authorization and consistent persistence.
+ * @see InMemoryWorkflowDefinitionRegistry for transition semantics.
+ */
+interface WorkflowDefinitionRegistry {
+    /**
+     * Validates and inserts or replaces a draft version, incrementing its revision.
+     * @param definition - Unknown workflow definition validated by core validation.
+     * @param actorId - Optional author label recorded as creator/updater; not authenticated here.
+     * @returns A cloned draft record with canonical definition hash.
+     * @throws Invalid definition, non-draft existing version, clock/hash/clone failure.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function saveReviewedDraft(
+     *   registry: WorkflowDefinitionRegistry,
+     *   definition: Parameters<WorkflowDefinitionRegistry["saveDraft"]>[0], authenticatedActorId: string,
+     * ) {
+     *   // Supply a real host workflow definition with its registered node types.
+     *   return registry.saveDraft(definition, authenticatedActorId);
+     * }
+     * ```
+     */
+    saveDraft(definition: unknown, actorId?: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions an existing draft to validated after core and optional host checks.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @param actorId - Optional updater label.
+     * @returns A cloned validated record with incremented revision.
+     * @throws Missing version, nondraft status, validation/callback/clock failure.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function validateStoredDraft(
+     *   registry: WorkflowDefinitionRegistry, workflowId: string, version: string, actorId: string,
+     * ) {
+     *   const record = registry.validate(workflowId, version, actorId);
+     *   return record.status; // Host/Core validation must succeed before transition.
+     * }
+     * ```
+     */
+    validate(workflowId: string, version: string, actorId?: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions a validated version to approved and records approver metadata.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @param actorId - Nonblank verified host approver label; no role check occurs here.
+     * @returns A cloned approved record.
+     * @throws Blank actor, missing version, nonvalidated status, or clock failure.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function approveValidatedWorkflow(
+     *   registry: WorkflowDefinitionRegistry, workflowId: string, version: string, authorizedApproverId: string,
+     * ) {
+     *   // The host checks reviewer authority before requesting this lifecycle change.
+     *   return registry.approve(workflowId, version, authorizedApproverId);
+     * }
+     * ```
+     */
+    approve(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Publishes an approved version and retires any currently published version of the same workflow.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Approved version to publish.
+     * @param actorId - Nonblank verified host publisher label.
+     * @returns A cloned published record; previous published records become retired.
+     * @throws Blank actor, missing version, nonapproved status, or clock/clone failure; earlier retirement updates can already have occurred.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function publishApprovedWorkflow(
+     *   registry: WorkflowDefinitionRegistry, workflowId: string, version: string, authorizedPublisherId: string,
+     * ) {
+     *   return registry.publish(workflowId, version, authorizedPublisherId);
+     *   // Host execution can select the resulting published record explicitly.
+     * }
+     * ```
+     */
+    publish(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions a published version to retired and records retirement metadata.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Currently published version.
+     * @param actorId - Nonblank verified host operator label.
+     * @returns A cloned retired record.
+     * @throws Blank actor, missing version, nonpublished status, or clock failure.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function retirePublishedWorkflow(
+     *   registry: WorkflowDefinitionRegistry, workflowId: string, version: string, authorizedActorId: string,
+     * ) {
+     *   return registry.retire(workflowId, version, authorizedActorId);
+     * }
+     * ```
+     */
+    retire(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Reads one workflow version without mutating lifecycle state.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @returns A cloned record, or undefined when absent.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function inspectWorkflowVersion(
+     *   registry: WorkflowDefinitionRegistry, workflowId: string, version: string,
+     * ) {
+     *   return registry.get(workflowId, version); // Undefined when this version is absent.
+     * }
+     * ```
+     */
+    get(workflowId: string, version: string): WorkflowDefinitionRecord | undefined;
+    /**
+     * Finds the currently published version of one workflow.
+     * @param workflowId - Exact workflow identifier.
+     * @returns A cloned published record, or undefined when none exists.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function inspectPublishedWorkflow(registry: WorkflowDefinitionRegistry, workflowId: string) {
+     *   return registry.getPublished(workflowId); // Undefined when no version is published.
+     * }
+     * ```
+     */
+    getPublished(workflowId: string): WorkflowDefinitionRecord | undefined;
+    /**
+     * Lists records in insertion order with optional workflow filtering.
+     * @param workflowId - Exact workflow identifier to filter, or omit for all workflows.
+     * @returns Independent cloned records, or an empty array.
+     
+     * @example
+     * ```typescript
+     * import type { WorkflowDefinitionRegistry } from "@alneas/eaos-server";
+     * export function listWorkflowVersions(registry: WorkflowDefinitionRegistry, workflowId: string) {
+     *   return registry.list(workflowId).map(record => ({ version: record.version, status: record.status }));
+     * }
+     * ```
+     */
+    list(workflowId?: string): readonly WorkflowDefinitionRecord[];
+}
+/**
+ * Stores versioned workflow drafts and validated/approved/published/retired records in process memory.
+ * @remarks Reference registry for tests/local authoring; it performs no actor authentication, role authorization, durable storage, or cross-process coordination. Transitions increment record revision and preserve definitions after draft.
+ * @example
+ * ```typescript
+ * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+ * const registry = new InMemoryWorkflowDefinitionRegistry();
+ * console.log(registry.list()); // []
+ * ```
+ */
+declare class InMemoryWorkflowDefinitionRegistry implements WorkflowDefinitionRegistry {
+    private readonly records;
+    private readonly now;
+    private readonly validateDefinition?;
+    /**
+     * Captures authoring clock and optional semantic validation callback.
+     * @param options - now returns a timestamp string and defaults to current ISO time; validate synchronously checks a structurally valid draft during validate and may throw.
+     */
+    constructor(options?: {
+        /**
+         * Optional timestamp-string clock used when creating/updating registry records; defaults to current ISO time.
+         * @returns Timestamp text recorded without additional format validation by this registry.
+         * @see {@link InMemoryWorkflowDefinitionRegistry.saveDraft}
+         */
+        now?: () => string;
+        /**
+         * Optional synchronous host semantic validator called after Core structural validation during a draft-to-validated transition.
+         * @param definition - Structurally valid stored workflow definition presented for host semantic checks.
+         * @returns No value when accepted; throw to reject validation before the status update.
+         * @remarks The callback receives the stored definition reference, so it should inspect without mutating it; this registry supplies no actor authentication or cross-process coordination.
+         * @see {@link InMemoryWorkflowDefinitionRegistry.validate}
+         */
+        validate?: (definition: WorkflowDefinition) => void;
+    });
+    /**
+     * Validates and inserts or replaces a draft version, incrementing its revision.
+     * @param input - Unknown workflow definition validated by core validation.
+     * @param actorId - Optional author label recorded as creator/updater; not authenticated here.
+     * @returns A cloned draft record with canonical definition hash.
+     * @throws Invalid definition, non-draft existing version, clock/hash/clone failure.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * export function draft(input: unknown) { return new InMemoryWorkflowDefinitionRegistry().saveDraft(input); }
+     * ```
+     */
+    saveDraft(input: unknown, actorId?: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions an existing draft to validated after core and optional host checks.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @param actorId - Optional updater label.
+     * @returns A cloned validated record with incremented revision.
+     * @throws Missing version, nondraft status, validation/callback/clock failure.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * export function validate(registry: InMemoryWorkflowDefinitionRegistry, workflowId: string, version: string) { return registry.validate(workflowId, version); }
+     * ```
+     */
+    validate(workflowId: string, version: string, actorId?: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions a validated version to approved and records approver metadata.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @param actorId - Nonblank verified host approver label; no role check occurs here.
+     * @returns A cloned approved record.
+     * @throws Blank actor, missing version, nonvalidated status, or clock failure.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * export function approve(registry: InMemoryWorkflowDefinitionRegistry, workflowId: string, version: string, actorId: string) { return registry.approve(workflowId, version, actorId); }
+     * ```
+     */
+    approve(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Publishes an approved version and retires any currently published version of the same workflow.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Approved version to publish.
+     * @param actorId - Nonblank verified host publisher label.
+     * @returns A cloned published record; previous published records become retired.
+     * @throws Blank actor, missing version, nonapproved status, or clock/clone failure; earlier retirement updates can already have occurred.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * export function publish(registry: InMemoryWorkflowDefinitionRegistry, workflowId: string, version: string, actorId: string) { return registry.publish(workflowId, version, actorId); }
+     * ```
+     */
+    publish(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Transitions a published version to retired and records retirement metadata.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Currently published version.
+     * @param actorId - Nonblank verified host operator label.
+     * @returns A cloned retired record.
+     * @throws Blank actor, missing version, nonpublished status, or clock failure.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * export function retire(registry: InMemoryWorkflowDefinitionRegistry, workflowId: string, version: string, actorId: string) { return registry.retire(workflowId, version, actorId); }
+     * ```
+     */
+    retire(workflowId: string, version: string, actorId: string): WorkflowDefinitionRecord;
+    /**
+     * Reads one workflow version without mutating lifecycle state.
+     * @param workflowId - Exact workflow identifier.
+     * @param version - Exact stored version.
+     * @returns A cloned record, or undefined when absent.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * console.log(new InMemoryWorkflowDefinitionRegistry().get("example", "1.0.0")); // undefined
+     * ```
+     */
+    get(workflowId: string, version: string): WorkflowDefinitionRecord | undefined;
+    /**
+     * Finds the currently published version of one workflow.
+     * @param workflowId - Exact workflow identifier.
+     * @returns A cloned published record, or undefined when none exists.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * console.log(new InMemoryWorkflowDefinitionRegistry().getPublished("example")); // undefined
+     * ```
+     */
+    getPublished(workflowId: string): WorkflowDefinitionRecord | undefined;
+    /**
+     * Lists records in insertion order with optional workflow filtering.
+     * @param workflowId - Exact workflow identifier to filter, or omit for all workflows.
+     * @returns Independent cloned records, or an empty array.
+     * @example
+     * ```typescript
+     * import { InMemoryWorkflowDefinitionRegistry } from "@alneas/eaos-server/agentic/workflow-registry";
+     * console.log(new InMemoryWorkflowDefinitionRegistry().list()); // []
+     * ```
+     */
+    list(workflowId?: string): readonly WorkflowDefinitionRecord[];
+    private require;
+    private update;
+    private key;
+}
+
+export { InMemoryWorkflowDefinitionRegistry };
+export type { WorkflowDefinitionRecord, WorkflowDefinitionRegistry };

package/dist/agentic/workflow-registry.js

@@ -0,0 +1,7 @@
+import {
+  InMemoryWorkflowDefinitionRegistry
+} from "../chunk-HVC7FG6B.js";
+export {
+  InMemoryWorkflowDefinitionRegistry
+};
+//# sourceMappingURL=workflow-registry.js.map

package/dist/agentic/workflow-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}