retold-workflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Velozo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# retold-workflow
+
+A reusable, product-agnostic workflow capability for Retold, built on the
+[fable-workflow](https://github.com/fable-retold/fable-workflow) engine.
+
+It is the middle of three tiers:
+
+- **fable-workflow** is the pure engine: workflow definitions, an append-only event
+  log, folded projections (time metrics and eligibility), guards, and agency queries.
+- **retold-workflow** (this module) is the capability built on that engine: a workflow
+  service, a built-in/clone type catalog with provenance and drift, and the board,
+  timeline, metrics, and agency UI.
+- **A product** supplies the concrete wiring: its tables, a few small stores, a context
+  resolver over its data, and any seeds.
+
+The reason this is reusable rather than welded into one product is the same discipline
+that makes the engine reusable: it depends only on injected interfaces, never on a
+product's tables. A product implements an event store, a projection store, a
+type-catalog store, and a context resolver over its own schema; a different product
+implements the same four and gets the same workflow capability and the same UI, with no
+new workflow code. The engine example already runs an editorial review and a hardware
+return on one engine; this tier lets a whole product do the same.
+
+## Status
+
+In progress. Phase 1 is in: the type catalog and the workflow service. The UI is next.
+
+## The type catalog
+
+A catalog holds two kinds of workflow type:
+
+- **built-in**: platform-owned archetypes (Software, Recipe, Physical Manufacturing).
+  Read-only and versioned.
+- **owned**: a tenant's own types, either authored or deep-cloned from a built-in. A
+  clone records where it came from, so the platform can evolve a built-in without
+  disturbing anyone's running workflows, and a tenant can choose when to take the update.
+
+`WorkflowTypeCatalog` is the generic logic over an injected, tenant-bound store. It does
+not name a table or a customer.
+
+```javascript
+const { WorkflowTypeCatalog } = require('retold-workflow');
+
+let tmpCatalog = new WorkflowTypeCatalog(myTenantBoundStore);
+
+await tmpCatalog.unionList();        // built-ins (labeled) + this tenant's own types
+await tmpCatalog.adoptBuiltIn(id);   // lazy, idempotent: find-or-create the tenant's clone
+await tmpCatalog.driftStatus(owned); // has the source built-in moved past this clone?
+```
+
+Adopting a built-in is lazy and idempotent: the first time a tenant picks one it is
+deep-cloned into an owned type stamped with its source and version; later picks of the
+same built-in return that one clone.
+
+### The store interface
+
+A product implements this, already bound to the current tenant (all Promise-returning):
+
+```
+listBuiltIns()            -> [typeRecord]
+getBuiltIn(id)            -> typeRecord | null
+listOwnedTypes()          -> [typeRecord]
+findCloneOfBuiltIn(id)    -> typeRecord | null
+createOwnedType(record)   -> typeRecord
+```
+
+A `typeRecord` carries at least `{ ID, TypeKey, Name, Description, Version,
+WorkflowDefinition, MetadataManifest, SourceID, SourceVersion }`. `WorkflowDefinition`
+and `MetadataManifest` are arbitrary JSON the engine layer consumes; the catalog copies
+them verbatim and never inspects them.
+
+## The workflow service
+
+`WorkflowService` drives a subject through its workflow, but it holds no state of its own.
+The event log is the source of truth: every call loads the subject's log, rebuilds the
+engine from it by replaying that log, runs the operation, and persists only the new events
+plus a projection snapshot. A second service instance over the same stores sees the same
+subject, which is what makes it safe behind a stateless server.
+
+```javascript
+const { WorkflowService } = require('retold-workflow');
+
+let tmpService = new WorkflowService(
+	{
+		eventStore,          // listEvents(id) / appendEvents(id, events)
+		contextResolver,     // (id) -> the data the subject's guards address into
+		definitionResolver,  // (id) -> the workflow definition that governs the subject
+		projectionStore      // optional: saveSnapshot(id, snap) / subjectsForActor(actor)
+	});
+
+await tmpService.open(id, actor);
+await tmpService.advance(id, 'review', actor);   // { ok, reason?, state? }, under role and data gates
+await tmpService.reevaluate(id);                 // after the subject's data changed
+await tmpService.getMetrics(id);                 // time in state, effort, active, overlap
+await tmpService.whoCanActOn(id);                // who has agency here, now
+await tmpService.whatCanAdvance(actor);          // which subjects this actor can move (indexed)
+```
+
+The product implements the stores over its own schema and the resolvers over its own data.
+retold-workflow names none of it.
+
+## Test
+
+```
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "retold-workflow",
+	"version": "0.1.0",
+	"description": "Reusable, product-agnostic workflow capability for Retold, built on the fable-workflow engine. A workflow service, a built-in/clone type catalog with provenance and drift detection, and (in progress) board, timeline, metrics, and agency UI. It depends on injected stores and a context resolver, so it carries no opinion about a product's data model or persistence.",
+	"main": "source/Retold-Workflow.js",
+	"scripts": {
+		"test": "npx mocha -u tdd --exit --timeout 5000 test/*_tests.js",
+		"coverage": "npx nyc --reporter=lcov --reporter=text npm test"
+	},
+	"mocha": {
+		"ui": "tdd",
+		"reporter": "spec",
+		"timeout": "5000"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fable-retold/retold-workflow.git"
+	},
+	"author": "steven velozo <steven@velozo.com>",
+	"license": "MIT",
+	"dependencies": {
+		"fable-serviceproviderbase": "^3.0.19",
+		"fable-workflow": "^0.2.0",
+		"manyfest": "^1.0.49"
+	},
+	"devDependencies": {
+		"fable": "^3.1.75",
+		"mocha": "^10.2.0",
+		"quackage": "^1.3.0"
+	}
+}

package/source/Retold-Workflow.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * retold-workflow
+ *
+ * A reusable, product-agnostic workflow capability built on the fable-workflow engine.
+ * It is the middle tier of three:
+ *
+ *   fable-workflow   the pure engine (definitions, event log, projections, guards, agency)
+ *   retold-workflow  this module: a workflow service, a built-in/clone type catalog, and
+ *                    (in progress) board / timeline / metrics / agency UI
+ *   <product>        the concrete wiring: tables, stores, a context resolver, seeds
+ *
+ * It stays reusable by depending only on injected interfaces, never on a product's
+ * tables: an event store, a projection store, a type-catalog store, and a context
+ * resolver. A product implements those over its own schema; an editorial-review product
+ * and a manufacturing product implement the same four and get the same capability.
+ *
+ * Phase 1 ships the type catalog. The WorkflowService and the UI follow.
+ *
+ * @author Steven Velozo <steven@velozo.com>
+ * @license MIT
+ */
+
+const libWorkflowTypeCatalog = require('./Workflow-Type-Catalog.js');
+const libWorkflowService = require('./Workflow-Service.js');
+
+module.exports =
+{
+	WorkflowTypeCatalog: libWorkflowTypeCatalog,
+	WorkflowService: libWorkflowService
+};

package/source/Workflow-Service.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * Workflow-Service
+ *
+ * The product-agnostic core of retold-workflow. It drives a subject through its workflow
+ * on top of the fable-workflow engine, but it is stateless and persistence-backed: the
+ * event log is the source of truth, and the engine is rebuilt from it for each operation,
+ * then discarded. Nothing about a product's schema, tenancy, or storage leaks in;
+ * everything arrives through injected, already-tenant-bound interfaces.
+ *
+ * Injected (constructor config):
+ *   eventStore         { listEvents(subjectId) -> [event],
+ *                        appendEvents(subjectId, [event]) -> void }       (required)
+ *   contextResolver    (subjectId) -> data object (Promise or value)      (required)
+ *                        the data a subject's guards address into; fetched once per op
+ *   definitionResolver (subjectId) -> WorkflowDefinition (Promise/value)  (required)
+ *                        which workflow governs the subject (its type's definition)
+ *   projectionStore    { saveSnapshot(subjectId, snapshot) -> void,
+ *                        subjectsForActor(actor) -> [subjectId] }         (optional)
+ *                        the materialized eligibility that whatCanAdvance reads
+ *   now                () -> ms timestamp                                 (optional)
+ *   engineClass        a WorkflowEngine class                            (optional)
+ *
+ * Each write loads the subject's log, fetches its context once, builds a fresh engine,
+ * hydrates (or opens), runs the operation, and persists only the new events plus a
+ * projection snapshot. Reads hydrate and answer. Because state lives in the stores and
+ * not here, the same subject behaves identically whichever process touches it.
+ *
+ * @author Steven Velozo <steven@velozo.com>
+ * @license MIT
+ */
+
+const libFableWorkflow = require('fable-workflow');
+
+class WorkflowService
+{
+	constructor(pConfig)
+	{
+		let tmpConfig = pConfig || {};
+		if (!tmpConfig.eventStore) { throw new Error('WorkflowService requires an eventStore'); }
+		if (typeof tmpConfig.contextResolver !== 'function') { throw new Error('WorkflowService requires a contextResolver function'); }
+		if (typeof tmpConfig.definitionResolver !== 'function') { throw new Error('WorkflowService requires a definitionResolver function'); }
+
+		this._eventStore = tmpConfig.eventStore;
+		this._contextResolver = tmpConfig.contextResolver;
+		this._definitionResolver = tmpConfig.definitionResolver;
+		this._projectionStore = tmpConfig.projectionStore || null;
+		this._now = (typeof tmpConfig.now === 'function') ? tmpConfig.now : (() => Date.now());
+		this._EngineClass = tmpConfig.engineClass || libFableWorkflow.WorkflowEngine;
+	}
+
+	// -- writes ----------------------------------------------------------------
+
+	async open(pSubjectId, pActor, pAt)
+	{
+		let tmpExisting = await this._eventStore.listEvents(pSubjectId);
+		if (tmpExisting && tmpExisting.length) { throw new Error('subject "' + pSubjectId + '" is already open'); }
+		let tmpPrepared = await this._prepareEngine(pSubjectId);
+		tmpPrepared.engine.open(pSubjectId, tmpPrepared.definition.Key, pActor, pAt);
+		await this._persist(tmpPrepared, pSubjectId, 0);
+		return tmpPrepared.engine.getState(pSubjectId);
+	}
+
+	async advance(pSubjectId, pToState, pActor, pAt)
+	{
+		let tmpPrepared = await this._hydrate(pSubjectId);
+		let tmpResult = tmpPrepared.engine.advance(pSubjectId, pToState, pActor, pAt);
+		if (tmpResult.ok) { await this._persist(tmpPrepared, pSubjectId, tmpPrepared.priorCount); }
+		return tmpResult;
+	}
+
+	async emit(pSubjectId, pEvent, pAt)
+	{
+		let tmpPrepared = await this._hydrate(pSubjectId);
+		tmpPrepared.engine.emit(pSubjectId, pEvent, pAt);
+		await this._persist(tmpPrepared, pSubjectId, tmpPrepared.priorCount);
+		return tmpPrepared.engine.getState(pSubjectId);
+	}
+
+	async reevaluate(pSubjectId, pAt)
+	{
+		let tmpPrepared = await this._hydrate(pSubjectId);
+		tmpPrepared.engine.reevaluate(pSubjectId, pAt);
+		await this._persist(tmpPrepared, pSubjectId, tmpPrepared.priorCount);
+		return tmpPrepared.engine.getAvailableExits(pSubjectId);
+	}
+
+	// -- reads -----------------------------------------------------------------
+
+	async getState(pSubjectId) { let tmpPrepared = await this._hydrate(pSubjectId); return tmpPrepared.engine.getState(pSubjectId); }
+	async getMetrics(pSubjectId) { let tmpPrepared = await this._hydrate(pSubjectId); return tmpPrepared.engine.getMetrics(pSubjectId); }
+	async getAvailableExits(pSubjectId) { let tmpPrepared = await this._hydrate(pSubjectId); return tmpPrepared.engine.getAvailableExits(pSubjectId); }
+	async whoCanActOn(pSubjectId) { let tmpPrepared = await this._hydrate(pSubjectId); return tmpPrepared.engine.whoCanActOn(pSubjectId); }
+	async getTimeline(pSubjectId) { let tmpEvents = await this._eventStore.listEvents(pSubjectId); return tmpEvents || []; }
+
+	/** Cross-subject agency. Delegates to the projection store's indexed query. */
+	async whatCanAdvance(pActor)
+	{
+		if (!this._projectionStore || typeof this._projectionStore.subjectsForActor !== 'function')
+		{
+			throw new Error('whatCanAdvance requires a projectionStore with a subjectsForActor query');
+		}
+		return this._projectionStore.subjectsForActor(pActor);
+	}
+
+	/**
+	 * Whether an actor can take any satisfied exit in a stored snapshot. A projection store
+	 * uses this (after its own indexed pre-filter) to answer subjectsForActor, so the agency
+	 * rule lives in one place.
+	 */
+	static actorCanAct(pSnapshot, pActor)
+	{
+		let tmpActor = pActor || {};
+		let tmpEntitlements = tmpActor.Entitlements || [];
+		let tmpExits = (pSnapshot && pSnapshot.Eligibility) || [];
+		return tmpExits.some((pExit) => pExit.GuardSatisfied
+			&& (!pExit.RequiredEntitlement || tmpEntitlements.indexOf(pExit.RequiredEntitlement) >= 0)
+			&& (pExit.ResolvedActor == null || pExit.ResolvedActor === tmpActor.ID));
+	}
+
+	// -- internals -------------------------------------------------------------
+
+	async _prepareEngine(pSubjectId)
+	{
+		let tmpDefinition = await this._definitionResolver(pSubjectId);
+		if (!tmpDefinition || !tmpDefinition.Key) { throw new Error('no workflow definition for subject "' + pSubjectId + '"'); }
+		let tmpContext = (await this._contextResolver(pSubjectId)) || {};
+		let tmpEngine = new this._EngineClass({ contextResolver: () => tmpContext, now: this._now });
+		tmpEngine.defineWorkflow(tmpDefinition);
+		return { engine: tmpEngine, definition: tmpDefinition };
+	}
+
+	async _hydrate(pSubjectId)
+	{
+		let tmpEvents = await this._eventStore.listEvents(pSubjectId);
+		if (!tmpEvents || !tmpEvents.length) { throw new Error('subject "' + pSubjectId + '" is not open'); }
+		let tmpPrepared = await this._prepareEngine(pSubjectId);
+		tmpPrepared.engine.hydrate(pSubjectId, tmpPrepared.definition.Key, tmpEvents);
+		tmpPrepared.priorCount = tmpPrepared.engine.getTimeline(pSubjectId).length;
+		return tmpPrepared;
+	}
+
+	async _persist(pPrepared, pSubjectId, pPriorCount)
+	{
+		let tmpDelta = pPrepared.engine.getTimeline(pSubjectId).slice(pPriorCount);
+		if (tmpDelta.length) { await this._eventStore.appendEvents(pSubjectId, tmpDelta); }
+		if (this._projectionStore && typeof this._projectionStore.saveSnapshot === 'function')
+		{
+			await this._projectionStore.saveSnapshot(pSubjectId,
+				{
+					State: pPrepared.engine.getState(pSubjectId),
+					Metrics: pPrepared.engine.getMetrics(pSubjectId),
+					Eligibility: pPrepared.engine.getAvailableExits(pSubjectId)
+				});
+		}
+	}
+}
+
+module.exports = WorkflowService;

package/source/Workflow-Type-Catalog.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Workflow-Type-Catalog
+ *
+ * The reusable built-in / clone type catalog, with provenance and drift, over an
+ * injected store. The store is the only coupling to a product's schema and tenancy:
+ * retold-workflow never names a table or a customer. A product hands in a store that
+ * is already bound to the current tenant, and this class adds the generic behavior.
+ *
+ * Two kinds of type live in the catalog:
+ *   - built-in: platform-owned archetypes (Software, Recipe, ...). Read-only, versioned.
+ *   - owned:    a tenant's own types. Either authored, or a deep clone of a built-in
+ *               that records where it came from (SourceID + SourceVersion).
+ *
+ * Adopting a built-in is lazy and idempotent: the first time a tenant picks one it is
+ * deep-cloned into an owned type; later picks of the same built-in return that one clone.
+ *
+ * Expected store interface (all Promise-returning), already bound to the current tenant:
+ *   listBuiltIns()              -> [typeRecord]
+ *   getBuiltIn(pBuiltInID)      -> typeRecord | null
+ *   listOwnedTypes()            -> [typeRecord]
+ *   findCloneOfBuiltIn(pID)     -> typeRecord | null
+ *   createOwnedType(pRecord)    -> typeRecord (the persisted row, with its new ID)
+ *
+ * A typeRecord is a plain object carrying at least:
+ *   { ID, TypeKey, Name, Description, Version, WorkflowDefinition, MetadataManifest,
+ *     SourceID, SourceVersion }
+ * ID and SourceID are opaque here. WorkflowDefinition and MetadataManifest are arbitrary
+ * JSON the engine layer consumes; this class copies them verbatim and never inspects them.
+ *
+ * @author Steven Velozo <steven@velozo.com>
+ * @license MIT
+ */
+
+const ORIGIN_BUILTIN = 'builtin';
+const ORIGIN_OWNED = 'owned';
+
+class WorkflowTypeCatalog
+{
+	constructor(pStore)
+	{
+		if (!pStore) { throw new Error('WorkflowTypeCatalog requires a store'); }
+		this.store = pStore;
+	}
+
+	/**
+	 * The picker list: built-ins (labeled) plus the tenant's own types. A built-in the
+	 * tenant has already adopted carries AdoptedAsID pointing at its clone, so a product
+	 * can show "already in use" instead of offering a second copy.
+	 */
+	async unionList()
+	{
+		let tmpBuiltIns = (await this.store.listBuiltIns()) || [];
+		let tmpOwned = (await this.store.listOwnedTypes()) || [];
+
+		let tmpOwnedBySource = {};
+		tmpOwned.forEach((pType) => { if (pType.SourceID != null) { tmpOwnedBySource[pType.SourceID] = pType; } });
+
+		let tmpList = [];
+		tmpBuiltIns.forEach((pType) =>
+		{
+			let tmpClone = tmpOwnedBySource[pType.ID];
+			tmpList.push(Object.assign({}, pType, { Origin: ORIGIN_BUILTIN, AdoptedAsID: tmpClone ? tmpClone.ID : null }));
+		});
+		tmpOwned.forEach((pType) =>
+		{
+			tmpList.push(Object.assign({}, pType, { Origin: ORIGIN_OWNED }));
+		});
+		return tmpList;
+	}
+
+	/** The tenant's own types only. */
+	async ownedTypes()
+	{
+		let tmpOwned = (await this.store.listOwnedTypes()) || [];
+		return tmpOwned.map((pType) => Object.assign({}, pType, { Origin: ORIGIN_OWNED }));
+	}
+
+	/**
+	 * Adopt a built-in: find-or-create the tenant's clone of it. Idempotent, so a second
+	 * call for the same built-in returns the same clone. Returns the owned typeRecord.
+	 */
+	async adoptBuiltIn(pBuiltInID)
+	{
+		let tmpExisting = await this.store.findCloneOfBuiltIn(pBuiltInID);
+		if (tmpExisting) { return Object.assign({}, tmpExisting, { Origin: ORIGIN_OWNED }); }
+
+		let tmpBuiltIn = await this.store.getBuiltIn(pBuiltInID);
+		if (!tmpBuiltIn) { throw new Error('no built-in workflow type with id "' + pBuiltInID + '"'); }
+
+		let tmpClone =
+		{
+			TypeKey: tmpBuiltIn.TypeKey,
+			Name: tmpBuiltIn.Name,
+			Description: tmpBuiltIn.Description,
+			WorkflowDefinition: _deepCopy(tmpBuiltIn.WorkflowDefinition),
+			MetadataManifest: _deepCopy(tmpBuiltIn.MetadataManifest),
+			SourceID: tmpBuiltIn.ID,
+			SourceVersion: tmpBuiltIn.Version
+		};
+		let tmpCreated = await this.store.createOwnedType(tmpClone);
+		return Object.assign({}, tmpCreated, { Origin: ORIGIN_OWNED });
+	}
+
+	/**
+	 * Drift of an owned type against the built-in it was cloned from. Returns
+	 * { Drifted, SourceID, FromVersion, ToVersion }. Drifted is false for a type with no
+	 * source (authored from scratch) or whose source built-in version is unchanged.
+	 */
+	async driftStatus(pOwnedType)
+	{
+		if (!pOwnedType || pOwnedType.SourceID == null)
+		{
+			return { Drifted: false, SourceID: null, FromVersion: null, ToVersion: null };
+		}
+		let tmpBuiltIn = await this.store.getBuiltIn(pOwnedType.SourceID);
+		if (!tmpBuiltIn)
+		{
+			return { Drifted: false, SourceID: pOwnedType.SourceID, FromVersion: pOwnedType.SourceVersion, ToVersion: null };
+		}
+		let tmpDrifted = Number(tmpBuiltIn.Version) > Number(pOwnedType.SourceVersion);
+		return { Drifted: tmpDrifted, SourceID: pOwnedType.SourceID, FromVersion: pOwnedType.SourceVersion, ToVersion: tmpBuiltIn.Version };
+	}
+}
+
+function _deepCopy(pValue)
+{
+	if (pValue === undefined || pValue === null) { return pValue; }
+	return JSON.parse(JSON.stringify(pValue));
+}
+
+module.exports = WorkflowTypeCatalog;
+module.exports.ORIGIN_BUILTIN = ORIGIN_BUILTIN;
+module.exports.ORIGIN_OWNED = ORIGIN_OWNED;

package/test/Workflow-Service_tests.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * retold-workflow - WorkflowService tests
+ *
+ * The service is exercised against in-memory event and projection stores standing in for a
+ * product's persistence. The point is that the service holds no state of its own: a second
+ * service instance built over the same stores sees the same subject, because the log is the
+ * source of truth and the engine is rebuilt from it on every call.
+ */
+
+const libAssert = require('node:assert');
+const libRetoldWorkflow = require('../source/Retold-Workflow.js');
+const libWorkflowService = libRetoldWorkflow.WorkflowService;
+
+// A deploy-pipeline definition (config). The service never names these fields.
+function deployDefinition()
+{
+	return {
+		Key: 'deploy',
+		Name: 'Deploy',
+		States: [ { Key: 'queued', IsInitial: true }, { Key: 'building' }, { Key: 'review' }, { Key: 'deployed', IsTerminal: true } ],
+		Transitions:
+		[
+			{ From: 'queued', To: 'building', RequiresEntitlement: 'build', Guard: { address: 'Change.HasTests', op: '==', value: true } },
+			{ From: 'building', To: 'review', RequiresEntitlement: 'build' },
+			{ From: 'review', To: 'deployed', RequiresEntitlement: 'deploy', Guard: { address: 'Change.Approved', op: '==', value: true } },
+			{ From: 'review', To: 'building', RequiresEntitlement: 'deploy' }
+		]
+	};
+}
+
+class MemoryEventStore
+{
+	constructor() { this.logs = {}; }
+	async listEvents(pID) { return (this.logs[pID] || []).map((pEvent) => Object.assign({}, pEvent)); }
+	async appendEvents(pID, pEvents) { if (!this.logs[pID]) { this.logs[pID] = []; } pEvents.forEach((pEvent) => this.logs[pID].push(Object.assign({}, pEvent))); }
+}
+
+class MemoryProjectionStore
+{
+	constructor() { this.snaps = {}; }
+	async saveSnapshot(pID, pSnap) { this.snaps[pID] = pSnap; }
+	async subjectsForActor(pActor) { return Object.keys(this.snaps).filter((pID) => libWorkflowService.actorCanAct(this.snaps[pID], pActor)); }
+}
+
+function makeService(pChanges, pClock, pEventStore, pProjectionStore)
+{
+	return new libWorkflowService(
+		{
+			eventStore: pEventStore,
+			projectionStore: pProjectionStore,
+			now: () => pClock.t,
+			contextResolver: (pID) => ({ Change: pChanges[pID] }),
+			definitionResolver: () => deployDefinition()
+		});
+}
+
+suite
+(
+	'retold-workflow: WorkflowService',
+	() =>
+	{
+		test('requires the core stores and resolvers', () =>
+		{
+			libAssert.throws(() => new libWorkflowService({}), /eventStore/);
+			libAssert.throws(() => new libWorkflowService({ eventStore: {} }), /contextResolver/);
+			libAssert.throws(() => new libWorkflowService({ eventStore: {}, contextResolver: () => ({}) }), /definitionResolver/);
+		});
+
+		test('open persists the log and lands in the initial state', async () =>
+		{
+			let tmpEvents = new MemoryEventStore();
+			let tmpService = makeService({ c1: { HasTests: false } }, { t: 0 }, tmpEvents, new MemoryProjectionStore());
+			let tmpState = await tmpService.open('c1', { ID: 'jan', Entitlements: ['build'] }, 0);
+			libAssert.deepStrictEqual(tmpState.CurrentStates, ['queued']);
+			let tmpLog = await tmpEvents.listEvents('c1');
+			libAssert.ok(tmpLog.length >= 2, 'opened + state.enter persisted');
+		});
+
+		test('a guard blocks, then reevaluate plus advance moves and persists', async () =>
+		{
+			let tmpChanges = { c1: { HasTests: false } };
+			let tmpService = makeService(tmpChanges, { t: 0 }, new MemoryEventStore(), new MemoryProjectionStore());
+			await tmpService.open('c1', { ID: 'jan', Entitlements: ['build'] }, 0);
+
+			let tmpBlocked = await tmpService.advance('c1', 'building', { ID: 'jan', Entitlements: ['build'] }, 100);
+			libAssert.strictEqual(tmpBlocked.ok, false);
+
+			tmpChanges.c1.HasTests = true;
+			await tmpService.reevaluate('c1', 200);
+			let tmpReady = await tmpService.advance('c1', 'building', { ID: 'jan', Entitlements: ['build'] }, 300);
+			libAssert.strictEqual(tmpReady.ok, true);
+			libAssert.deepStrictEqual((await tmpService.getState('c1')).CurrentStates, ['building']);
+		});
+
+		test('a second service over the same stores sees the same subject (stateless)', async () =>
+		{
+			let tmpChanges = { c1: { HasTests: true, Approved: true } };
+			let tmpEvents = new MemoryEventStore();
+			let tmpProjections = new MemoryProjectionStore();
+			let tmpFirst = makeService(tmpChanges, { t: 0 }, tmpEvents, tmpProjections);
+			await tmpFirst.open('c1', { ID: 'jan', Entitlements: ['build'] }, 0);
+			await tmpFirst.advance('c1', 'building', { ID: 'jan', Entitlements: ['build'] }, 1000);
+			await tmpFirst.advance('c1', 'review', { ID: 'jan', Entitlements: ['build'] }, 2000);
+
+			// a brand-new service instance, as if a different request or process
+			let tmpSecond = makeService(tmpChanges, { t: 0 }, tmpEvents, tmpProjections);
+			libAssert.deepStrictEqual((await tmpSecond.getState('c1')).CurrentStates, ['review']);
+			let tmpMetrics = await tmpSecond.getMetrics('c1');
+			libAssert.strictEqual(tmpMetrics.StateTime.queued, 1000);
+			libAssert.strictEqual(tmpMetrics.StateTime.building, 1000);
+		});
+
+		test('agency: whoCanActOn per subject, whatCanAdvance via the projection store', async () =>
+		{
+			let tmpChanges = { c1: { HasTests: true, Approved: true }, c2: { HasTests: true, Approved: false } };
+			let tmpEvents = new MemoryEventStore();
+			let tmpProjections = new MemoryProjectionStore();
+			let tmpService = makeService(tmpChanges, { t: 0 }, tmpEvents, tmpProjections);
+
+			for (let pID of ['c1', 'c2'])
+			{
+				await tmpService.open(pID, { ID: 'jan', Entitlements: ['build'] }, 0);
+				await tmpService.advance(pID, 'building', { ID: 'jan', Entitlements: ['build'] }, 100);
+				await tmpService.advance(pID, 'review', { ID: 'jan', Entitlements: ['build'] }, 200);
+			}
+
+			let tmpDeployer = { ID: 'deb', Entitlements: ['deploy'] };
+			let tmpC1Exits = (await tmpService.whoCanActOn('c1')).map((pExit) => pExit.ToState);
+			libAssert.ok(tmpC1Exits.indexOf('deployed') >= 0, 'c1 is approved, so the deploy exit is ready');
+
+			let tmpAdvanceable = await tmpService.whatCanAdvance(tmpDeployer);
+			libAssert.ok(tmpAdvanceable.indexOf('c1') >= 0, 'deployer can deploy c1');
+			libAssert.ok(tmpAdvanceable.indexOf('c2') >= 0, 'deployer can reject c2 back to building');
+		});
+
+		test('whatCanAdvance needs a projection store', async () =>
+		{
+			let tmpService = new libWorkflowService({ eventStore: new MemoryEventStore(), contextResolver: () => ({}), definitionResolver: () => deployDefinition() });
+			await libAssert.rejects(() => tmpService.whatCanAdvance({ ID: 'x', Entitlements: [] }), /projectionStore/);
+		});
+	}
+);

package/test/Workflow-Type-Catalog_tests.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * retold-workflow - Workflow-Type-Catalog tests
+ *
+ * The catalog is exercised against a small in-memory store standing in for a product's
+ * tenant-bound persistence. The point is that the catalog logic (union list, lazy clone,
+ * provenance, drift) is correct without any database, framework, or product schema.
+ */
+
+const libAssert = require('node:assert');
+const libWorkflowTypeCatalog = require('../source/Workflow-Type-Catalog.js');
+
+// An in-memory store bound to a single tenant. Returns shallow copies on read (a real
+// store hands back fresh rows), which is enough to prove the catalog deep-copies on clone.
+class MemoryStore
+{
+	constructor()
+	{
+		this.builtIns = [];
+		this.owned = [];
+		this._seq = 0;
+	}
+
+	seedBuiltIn(pRecord)
+	{
+		let tmpRecord = Object.assign({ ID: 'b' + (++this._seq) }, pRecord);
+		this.builtIns.push(tmpRecord);
+		return tmpRecord;
+	}
+
+	async listBuiltIns() { return this.builtIns.map((pRow) => Object.assign({}, pRow)); }
+	async getBuiltIn(pID) { let tmpRow = this.builtIns.find((pRow) => pRow.ID === pID); return tmpRow ? Object.assign({}, tmpRow) : null; }
+	async listOwnedTypes() { return this.owned.map((pRow) => Object.assign({}, pRow)); }
+	async findCloneOfBuiltIn(pID) { let tmpRow = this.owned.find((pRow) => pRow.SourceID === pID); return tmpRow ? Object.assign({}, tmpRow) : null; }
+	async createOwnedType(pRecord) { let tmpRow = Object.assign({ ID: 'o' + (++this._seq) }, pRecord); this.owned.push(tmpRow); return Object.assign({}, tmpRow); }
+}
+
+function softwareBuiltIn()
+{
+	return {
+		TypeKey: 'software',
+		Name: 'Software',
+		Description: 'Software delivery lifecycle',
+		Version: 1,
+		WorkflowDefinition: { Key: 'software', States: [{ Key: 'backlog' }, { Key: 'done' }] },
+		MetadataManifest: { Fields: [{ Address: 'PR.Approved', Type: 'boolean' }] }
+	};
+}
+
+suite('retold-workflow: WorkflowTypeCatalog', () =>
+{
+	suite('Construction', () =>
+	{
+		test('requires a store', () =>
+		{
+			libAssert.throws(() => new libWorkflowTypeCatalog(), /requires a store/);
+		});
+	});
+
+	suite('Union list', () =>
+	{
+		test('labels built-ins and owned, with no adoption yet', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpList = await tmpCatalog.unionList();
+			libAssert.strictEqual(tmpList.length, 1);
+			libAssert.strictEqual(tmpList[0].Origin, 'builtin');
+			libAssert.strictEqual(tmpList[0].AdoptedAsID, null);
+			libAssert.strictEqual(tmpList[0].TypeKey, 'software');
+		});
+
+		test('after adoption the built-in row points at its clone', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpClone = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			let tmpList = await tmpCatalog.unionList();
+
+			let tmpBuiltInRow = tmpList.find((pRow) => pRow.Origin === 'builtin');
+			let tmpOwnedRow = tmpList.find((pRow) => pRow.Origin === 'owned');
+			libAssert.strictEqual(tmpBuiltInRow.AdoptedAsID, tmpClone.ID);
+			libAssert.ok(tmpOwnedRow, 'the owned clone is listed');
+			libAssert.strictEqual(tmpOwnedRow.SourceID, tmpBuiltIn.ID);
+		});
+	});
+
+	suite('Adopt a built-in (lazy, idempotent clone)', () =>
+	{
+		test('creates a clone with provenance stamped', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpClone = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			libAssert.strictEqual(tmpClone.Origin, 'owned');
+			libAssert.strictEqual(tmpClone.SourceID, tmpBuiltIn.ID);
+			libAssert.strictEqual(tmpClone.SourceVersion, 1);
+			libAssert.strictEqual(tmpClone.TypeKey, 'software');
+			libAssert.deepStrictEqual(tmpClone.WorkflowDefinition, tmpBuiltIn.WorkflowDefinition);
+			libAssert.strictEqual(tmpStore.owned.length, 1);
+		});
+
+		test('a second adopt returns the same clone (find-or-create)', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpFirst = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			let tmpSecond = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			libAssert.strictEqual(tmpFirst.ID, tmpSecond.ID);
+			libAssert.strictEqual(tmpStore.owned.length, 1);
+		});
+
+		test('the clone deep-copies the definition (independent of the built-in)', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			// Mutate the stored built-in after the clone exists.
+			tmpStore.builtIns[0].WorkflowDefinition.States.push({ Key: 'injected' });
+
+			let tmpClone = await tmpStore.findCloneOfBuiltIn(tmpBuiltIn.ID);
+			libAssert.strictEqual(tmpClone.WorkflowDefinition.States.length, 2, 'clone unchanged by built-in mutation');
+		});
+
+		test('adopting an unknown built-in throws', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+			await libAssert.rejects(() => tmpCatalog.adoptBuiltIn('nope'), /no built-in workflow type/);
+		});
+	});
+
+	suite('Drift', () =>
+	{
+		test('a fresh clone has not drifted', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpClone = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			let tmpDrift = await tmpCatalog.driftStatus(tmpClone);
+			libAssert.strictEqual(tmpDrift.Drifted, false);
+		});
+
+		test('bumping the built-in version drifts the clone', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpBuiltIn = tmpStore.seedBuiltIn(softwareBuiltIn());
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+
+			let tmpClone = await tmpCatalog.adoptBuiltIn(tmpBuiltIn.ID);
+			tmpStore.builtIns[0].Version = 2;
+
+			let tmpDrift = await tmpCatalog.driftStatus(tmpClone);
+			libAssert.strictEqual(tmpDrift.Drifted, true);
+			libAssert.strictEqual(tmpDrift.FromVersion, 1);
+			libAssert.strictEqual(tmpDrift.ToVersion, 2);
+		});
+
+		test('an authored type (no source) never drifts', async () =>
+		{
+			let tmpStore = new MemoryStore();
+			let tmpCatalog = new libWorkflowTypeCatalog(tmpStore);
+			let tmpDrift = await tmpCatalog.driftStatus({ ID: 'o9', TypeKey: 'custom', SourceID: null });
+			libAssert.strictEqual(tmpDrift.Drifted, false);
+		});
+	});
+});