@nt-ai-lab/deterministic-agent-workflow-engine 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -8,8 +8,10 @@ export { reflectionCategorySchema, reflectionConfidenceSchema, reflectionEvidenc
 export type { ReflectionCategory, ReflectionEvidence, ReflectionFinding, ReflectionPayload, RecordReflectionInput, StoredReflection, } from './platform/domain/reflection-types';
 export { reviewTypeSchema, reviewVerdictSchema, reviewFindingSeveritySchema, reviewFindingStatusSchema, reviewFindingSchema, reviewPayloadSchema, recordReviewInputSchema, storedReviewSchema, listedReviewSchema, reviewFiltersSchema, } from './platform/domain/review-types';
 export type { ReviewType, ReviewVerdict, ReviewFindingSeverity, ReviewFindingStatus, ReviewFinding, ReviewPayload, RecordReviewInput, StoredReview, ListedReview, ReviewFilters, } from './platform/domain/review-types';
-export { engineEventSchema } from './platform/domain/engine-events';
+export { engineEventSchema, reviewRecordedEventSchema, } from './platform/domain/engine-events';
 export type { EngineEvent, SessionStartedEvent, TransitionedEvent, AgentRegisteredEvent, AgentShutDownEvent, JournalEntryEvent, WriteCheckedEvent, BashCheckedEvent, PluginReadCheckedEvent, IdleCheckedEvent, IdentityVerifiedEvent, ContextRequestedEvent, ReviewRecordedEvent, } from './platform/domain/engine-events';
+export { isPlatformOwnedEventExcludedFromWorkflowState } from './platform/domain/engine-events';
+export { reduceWorkflowStateFromStoredEvents } from './platform/domain/workflow-state-reducer';
 export { repositoryMetadataEventSchema } from './platform/domain/repository-tracking-events';
 export type { DomainMetadataEvent, IssueRecordedEvent, BranchRecordedEvent, PrRecordedEvent, } from './platform/domain/repository-tracking-events';
 export { checkBashCommand } from './platform/domain/bash-enforcement';

package/dist/index.js

@@ -3,7 +3,9 @@ export { baseEventSchema } from './platform/domain/base-event.js';
 export { flattenStoredEvent, stripEnvelopeKeys, toPayload, } from './platform/domain/stored-event.js';
 export { reflectionCategorySchema, reflectionConfidenceSchema, reflectionEvidenceSchema, reflectionFindingSchema, reflectionPayloadSchema, recordReflectionInputSchema, storedReflectionSchema, } from './platform/domain/reflection-types.js';
 export { reviewTypeSchema, reviewVerdictSchema, reviewFindingSeveritySchema, reviewFindingStatusSchema, reviewFindingSchema, reviewPayloadSchema, recordReviewInputSchema, storedReviewSchema, listedReviewSchema, reviewFiltersSchema, } from './platform/domain/review-types.js';
-export { engineEventSchema } from './platform/domain/engine-events.js';
+export { engineEventSchema, reviewRecordedEventSchema, } from './platform/domain/engine-events.js';
+export { isPlatformOwnedEventExcludedFromWorkflowState } from './platform/domain/engine-events.js';
+export { reduceWorkflowStateFromStoredEvents } from './platform/domain/workflow-state-reducer.js';
 export { repositoryMetadataEventSchema } from './platform/domain/repository-tracking-events.js';
 export { checkBashCommand } from './platform/domain/bash-enforcement.js';
 export { pass, fail } from './platform/domain/precondition-result.js';

package/dist/platform/domain/engine-events.d.ts

@@ -208,7 +208,7 @@ declare const contextRequestedSchema: z.ZodObject<{
     at: string;
     agentName: string;
 }>;
-declare const reviewRecordedSchema: z.ZodObject<{
+export declare const reviewRecordedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"review-recorded">;
     at: z.ZodString;
     reviewId: z.ZodNumber;
@@ -444,6 +444,8 @@ export declare const engineEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodOb
     reviewType: string;
     reviewId: number;
 }>]>;
+/** @riviere-role domain-service */
+export declare function isPlatformOwnedEventExcludedFromWorkflowState(type: string): boolean;
 /** @riviere-role value-object */
 export type EngineEvent = z.infer<typeof engineEventSchema>;
 /** @riviere-role value-object */
@@ -469,5 +471,5 @@ export type IdentityVerifiedEvent = z.infer<typeof identityVerifiedSchema>;
 /** @riviere-role value-object */
 export type ContextRequestedEvent = z.infer<typeof contextRequestedSchema>;
 /** @riviere-role value-object */
-export type ReviewRecordedEvent = z.infer<typeof reviewRecordedSchema>;
+export type ReviewRecordedEvent = z.infer<typeof reviewRecordedEventSchema>;
 export {};

package/dist/platform/domain/engine-events.js

@@ -76,7 +76,7 @@ const contextRequestedSchema = z.object({
     at: z.string(),
     agentName: z.string(),
 });
-const reviewRecordedSchema = z.object({
+export const reviewRecordedEventSchema = z.object({
     type: z.literal('review-recorded'),
     at: z.string(),
     reviewId: z.number().int().positive(),
@@ -95,5 +95,20 @@ export const engineEventSchema = z.discriminatedUnion('type', [
     idleCheckedSchema,
     identityVerifiedSchema,
     contextRequestedSchema,
-    reviewRecordedSchema,
+    reviewRecordedEventSchema,
 ]);
+const platformOwnedEventTypesExcludedFromWorkflowState = new Set([
+    'agent-registered',
+    'agent-shut-down',
+    'journal-entry',
+    'write-checked',
+    'bash-checked',
+    'plugin-read-checked',
+    'idle-checked',
+    'identity-verified',
+    'context-requested',
+]);
+/** @riviere-role domain-service */
+export function isPlatformOwnedEventExcludedFromWorkflowState(type) {
+    return platformOwnedEventTypesExcludedFromWorkflowState.has(type);
+}

package/dist/platform/domain/workflow-engine-platform-operations.d.ts

@@ -0,0 +1,17 @@
+import type { BaseWorkflowState } from './workflow-state';
+import type { BashForbiddenConfig } from './workflow-registry';
+import type { EngineResult, RehydratableWorkflow, WorkflowDefinition, WorkflowEngineDeps } from './workflow-engine-types';
+type PlatformOperationContext<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string> = {
+    readonly workflow: TWorkflow;
+    readonly engineDeps: WorkflowEngineDeps;
+    readonly factory: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>;
+    readonly applyIdentityGate: (op: string) => EngineResult | undefined;
+    readonly persistPlatformEvent: (event: unknown) => void;
+};
+/** @riviere-role domain-service */
+export declare function writeJournalWithPlatformEvents<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(context: PlatformOperationContext<TWorkflow, TState, TDeps, TStateName, TOperation>, agentName: string, content: string): EngineResult;
+/** @riviere-role domain-service */
+export declare function checkBashWithPlatformEvents<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(context: PlatformOperationContext<TWorkflow, TState, TDeps, TStateName, TOperation>, toolName: string, command: string, bashForbidden: BashForbiddenConfig): EngineResult;
+/** @riviere-role domain-service */
+export declare function checkWriteWithPlatformEvents<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(context: PlatformOperationContext<TWorkflow, TState, TDeps, TStateName, TOperation>, toolName: string, filePath: string, isWriteAllowed: (filePath: string, state: TState) => boolean): EngineResult;
+export {};

package/dist/platform/domain/workflow-engine-platform-operations.js

@@ -0,0 +1,147 @@
+import { checkBashCommand } from './bash-enforcement.js';
+import { formatOperationGateError, formatOperationSuccess, } from '../infra/cli/presentation/output-guidance.js';
+import { getExpectedPrefix } from './workflow-engine-support.js';
+/** @riviere-role domain-service */
+export function writeJournalWithPlatformEvents(context, agentName, content) {
+    const gate = context.applyIdentityGate('write-journal');
+    if (gate !== undefined)
+        return gate;
+    context.persistPlatformEvent({
+        type: 'journal-entry',
+        at: context.engineDeps.now(),
+        agentName,
+        content,
+    });
+    const state = context.workflow.getState();
+    const body = context.factory.getOperationBody?.('write-journal', state) ?? 'Write journal entry';
+    return {
+        type: 'success',
+        output: formatOperationSuccess('write-journal', body, getExpectedPrefix(state.currentStateMachineState, context.factory.getRegistry())),
+    };
+}
+/** @riviere-role domain-service */
+export function checkBashWithPlatformEvents(context, toolName, command, bashForbidden) {
+    const state = context.workflow.getState();
+    const currentStateName = state.currentStateMachineState;
+    const currentPrefix = getExpectedPrefix(currentStateName, context.factory.getRegistry());
+    const gate = context.applyIdentityGate('bash-check');
+    if (gate !== undefined)
+        return gate;
+    if (toolName !== 'Bash') {
+        context.persistPlatformEvent({
+            type: 'bash-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            command,
+            allowed: true,
+        });
+        return {
+            type: 'success',
+            output: '',
+        };
+    }
+    const exemptions = context.factory.getRegistry()[currentStateName].allowForbidden?.bash ?? [];
+    const bashCheckResult = checkBashCommand(command, bashForbidden, exemptions);
+    if (!bashCheckResult.pass) {
+        const reason = `Bash command blocked in ${currentStateName}. ${bashCheckResult.reason}`;
+        context.persistPlatformEvent({
+            type: 'bash-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            command,
+            allowed: false,
+            reason,
+        });
+        return {
+            type: 'blocked',
+            output: formatOperationGateError('bash-check', reason, currentPrefix),
+        };
+    }
+    context.persistPlatformEvent({
+        type: 'bash-checked',
+        at: context.engineDeps.now(),
+        tool: toolName,
+        command,
+        allowed: true,
+    });
+    return {
+        type: 'success',
+        output: '',
+    };
+}
+/** @riviere-role domain-service */
+export function checkWriteWithPlatformEvents(context, toolName, filePath, isWriteAllowed) {
+    const state = context.workflow.getState();
+    const currentStateName = state.currentStateMachineState;
+    const currentPrefix = getExpectedPrefix(currentStateName, context.factory.getRegistry());
+    const gate = context.applyIdentityGate('write-check');
+    if (gate !== undefined)
+        return gate;
+    const writeTools = new Set(['Write', 'Edit', 'NotebookEdit']);
+    if (!writeTools.has(toolName)) {
+        context.persistPlatformEvent({
+            type: 'write-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            filePath,
+            allowed: true,
+        });
+        return {
+            type: 'success',
+            output: '',
+        };
+    }
+    const storePath = `${context.engineDeps.getPluginRoot()}/workflow.db`;
+    if (filePath === storePath) {
+        context.persistPlatformEvent({
+            type: 'write-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            filePath,
+            allowed: true,
+        });
+        return {
+            type: 'success',
+            output: '',
+        };
+    }
+    if (!(context.factory.getRegistry()[currentStateName].forbidden?.write ?? false)) {
+        context.persistPlatformEvent({
+            type: 'write-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            filePath,
+            allowed: true,
+        });
+        return {
+            type: 'success',
+            output: '',
+        };
+    }
+    if (!isWriteAllowed(filePath, state)) {
+        const reason = `Write to '${filePath}' is forbidden in state ${currentStateName}`;
+        context.persistPlatformEvent({
+            type: 'write-checked',
+            at: context.engineDeps.now(),
+            tool: toolName,
+            filePath,
+            allowed: false,
+            reason,
+        });
+        return {
+            type: 'blocked',
+            output: formatOperationGateError('write-check', reason, currentPrefix),
+        };
+    }
+    context.persistPlatformEvent({
+        type: 'write-checked',
+        at: context.engineDeps.now(),
+        tool: toolName,
+        filePath,
+        allowed: true,
+    });
+    return {
+        type: 'success',
+        output: '',
+    };
+}

package/dist/platform/domain/workflow-engine.d.ts

@@ -10,6 +10,7 @@ export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TStat
     constructor(factory: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>, engineDeps: WorkflowEngineDeps, workflowDeps: TDeps);
     startSession(sessionId: string, transcriptPath: string, repository?: string): EngineResult;
     transaction(sessionId: string, op: string, fn: (workflow: TWorkflow) => PreconditionResult): EngineResult;
+    writeJournal(sessionId: string, agentName: string, content: string): EngineResult;
     transition(sessionId: string, target: TStateName): EngineResult;
     checkBash(sessionId: string, toolName: string, command: string, bashForbidden: BashForbiddenConfig): EngineResult;
     checkWrite(sessionId: string, toolName: string, filePath: string, isWriteAllowed: (filePath: string, state: TState) => boolean): EngineResult;
@@ -23,4 +24,6 @@ export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TStat
     private wrapEvents;
     private applyIdentityGate;
     private verifyIdentity;
+    private platformOperationContext;
+    private persistPlatformEvent;
 }

package/dist/platform/domain/workflow-engine.js

@@ -1,9 +1,11 @@
-import { checkBashCommand } from './bash-enforcement.js';
 import { checkIdentity } from './identity-verification.js';
+import { checkBashWithPlatformEvents, checkWriteWithPlatformEvents, writeJournalWithPlatformEvents, } from './workflow-engine-platform-operations.js';
 import { buildPrefixPattern, buildProcedurePath, enrichSessionStartedEvents, getExpectedPrefix, readProcedure, } from './workflow-engine-support.js';
 import { formatIllegalTransitionError, formatInitSuccess, formatOperationGateError, formatOperationSuccess, formatTransitionError, formatTransitionSuccess, } from '../infra/cli/presentation/output-guidance.js';
-import { flattenStoredEvent, toPayload, } from './stored-event.js';
+import { toPayload, } from './stored-event.js';
+import { engineEventSchema } from './engine-events.js';
 import { WorkflowStateError, } from './workflow-state.js';
+import { reduceWorkflowStateFromStoredEvents } from './workflow-state-reducer.js';
 import { serializeWorkflowState } from './workflow-state-serialization.js';
 /** @riviere-role domain-service */
 export class WorkflowEngine {
@@ -59,6 +61,11 @@ export class WorkflowEngine {
             output: formatOperationSuccess(op, body, currentPrefix)
         };
     }
+    writeJournal(sessionId, agentName, content) {
+        this.requireSession(sessionId);
+        const workflow = this.rehydrateFromEvents(sessionId);
+        return writeJournalWithPlatformEvents(this.platformOperationContext(sessionId, workflow), agentName, content);
+    }
     transition(sessionId, target) {
         this.requireSession(sessionId);
         const workflow = this.rehydrateFromEvents(sessionId);
@@ -119,138 +126,12 @@ export class WorkflowEngine {
     checkBash(sessionId, toolName, command, bashForbidden) {
         this.requireSession(sessionId);
         const workflow = this.rehydrateFromEvents(sessionId);
-        const registry = this.factory.getRegistry();
-        const currentStateName = workflow.getState().currentStateMachineState;
-        const currentPrefix = getExpectedPrefix(currentStateName, registry);
-        const gate = this.applyIdentityGate(sessionId, workflow, 'bash-check');
-        if (gate !== undefined)
-            return gate;
-        if (toolName !== 'Bash') {
-            workflow.appendEvent({
-                type: 'bash-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                command,
-                allowed: true
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'success',
-                output: ''
-            };
-        }
-        const exemptions = registry[currentStateName].allowForbidden?.bash ?? [];
-        const bashCheckResult = checkBashCommand(command, bashForbidden, exemptions);
-        if (!bashCheckResult.pass) {
-            const reason = `Bash command blocked in ${currentStateName}. ${bashCheckResult.reason}`;
-            workflow.appendEvent({
-                type: 'bash-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                command,
-                allowed: false,
-                reason,
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError('bash-check', reason, currentPrefix)
-            };
-        }
-        workflow.appendEvent({
-            type: 'bash-checked',
-            at: this.engineDeps.now(),
-            tool: toolName,
-            command,
-            allowed: true
-        });
-        this.persistEvents(sessionId, workflow);
-        return {
-            type: 'success',
-            output: ''
-        };
+        return checkBashWithPlatformEvents(this.platformOperationContext(sessionId, workflow), toolName, command, bashForbidden);
     }
     checkWrite(sessionId, toolName, filePath, isWriteAllowed) {
         this.requireSession(sessionId);
         const workflow = this.rehydrateFromEvents(sessionId);
-        const registry = this.factory.getRegistry();
-        const currentStateName = workflow.getState().currentStateMachineState;
-        const currentPrefix = getExpectedPrefix(currentStateName, registry);
-        const gate = this.applyIdentityGate(sessionId, workflow, 'write-check');
-        if (gate !== undefined)
-            return gate;
-        const writeTools = new Set(['Write', 'Edit', 'NotebookEdit']);
-        if (!writeTools.has(toolName)) {
-            workflow.appendEvent({
-                type: 'write-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                filePath,
-                allowed: true
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'success',
-                output: ''
-            };
-        }
-        const storePath = `${this.engineDeps.getPluginRoot()}/workflow.db`;
-        if (filePath === storePath) {
-            workflow.appendEvent({
-                type: 'write-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                filePath,
-                allowed: true
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'success',
-                output: ''
-            };
-        }
-        if (!(registry[currentStateName].forbidden?.write ?? false)) {
-            workflow.appendEvent({
-                type: 'write-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                filePath,
-                allowed: true
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'success',
-                output: ''
-            };
-        }
-        if (!isWriteAllowed(filePath, workflow.getState())) {
-            const reason = `Write to '${filePath}' is forbidden in state ${currentStateName}`;
-            workflow.appendEvent({
-                type: 'write-checked',
-                at: this.engineDeps.now(),
-                tool: toolName,
-                filePath,
-                allowed: false,
-                reason,
-            });
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError('write-check', reason, currentPrefix)
-            };
-        }
-        workflow.appendEvent({
-            type: 'write-checked',
-            at: this.engineDeps.now(),
-            tool: toolName,
-            filePath,
-            allowed: true
-        });
-        this.persistEvents(sessionId, workflow);
-        return {
-            type: 'success',
-            output: ''
-        };
+        return checkWriteWithPlatformEvents(this.platformOperationContext(sessionId, workflow), toolName, filePath, isWriteAllowed);
     }
     getState(sessionId) {
         this.requireSession(sessionId);
@@ -272,8 +153,7 @@ export class WorkflowEngine {
     }
     rehydrateFromEvents(sessionId) {
         const stored = this.engineDeps.store.readEvents(sessionId);
-        const events = stored.map(flattenStoredEvent);
-        const state = events.reduce((accumulator, event) => this.factory.fold(accumulator, event), this.factory.initialState());
+        const state = reduceWorkflowStateFromStoredEvents(this.factory, stored);
         return this.factory.buildWorkflow(state, this.workflowDeps);
     }
     persistEvents(sessionId, workflow) {
@@ -318,12 +198,12 @@ export class WorkflowEngine {
         const pattern = buildPrefixPattern(registry);
         const messages = this.engineDeps.transcriptReader.readMessages(transcriptPath);
         const identityCheckResult = checkIdentity(messages, pattern);
-        this.engineDeps.store.appendEvents(sessionId, this.wrapEvents([{
-                type: 'identity-verified',
-                at: this.engineDeps.now(),
-                status: identityCheckResult.status,
-                transcriptPath,
-            }], workflow.getState()));
+        this.persistPlatformEvent(sessionId, workflow.getState(), {
+            type: 'identity-verified',
+            at: this.engineDeps.now(),
+            status: identityCheckResult.status,
+            transcriptPath,
+        });
         if (identityCheckResult.status === 'lost') {
             const currentProcedure = readProcedure(this.engineDeps, state);
             return [
@@ -339,4 +219,24 @@ export class WorkflowEngine {
         }
         return undefined;
     }
+    platformOperationContext(sessionId, workflow) {
+        return {
+            workflow,
+            engineDeps: this.engineDeps,
+            factory: this.factory,
+            applyIdentityGate: (op) => this.applyIdentityGate(sessionId, workflow, op),
+            persistPlatformEvent: (event) => this.persistPlatformEvent(sessionId, workflow.getState(), event),
+        };
+    }
+    persistPlatformEvent(sessionId, state, event) {
+        const platformEvent = engineEventSchema.parse(event);
+        this.engineDeps.store.appendEvents(sessionId, [{
+                envelope: {
+                    type: platformEvent.type,
+                    at: platformEvent.at,
+                    state: state.currentStateMachineState,
+                },
+                payload: toPayload(platformEvent),
+            }]);
+    }
 }

package/dist/platform/domain/workflow-engine.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/domain/workflow-engine.spec.js

@@ -0,0 +1,305 @@
+import { describe, expect, it, } from 'vitest';
+import { z } from 'zod';
+import { flattenStoredEvent, pass, reduceWorkflowStateFromStoredEvents, reviewRecordedEventSchema, WorkflowEngine, WorkflowStateError, } from '../../index.js';
+function isSessionStartedEvent(event) {
+    return event.type === 'session-started';
+}
+function allowAgentRegistration(agentType, agentId) {
+    void agentType;
+    void agentId;
+    return pass();
+}
+function allowIdleCheck(agentName) {
+    void agentName;
+    return pass();
+}
+class StrictPlanningWorkflow {
+    state;
+    pendingEvents;
+    constructor(state, pendingEvents = []) {
+        this.state = state;
+        this.pendingEvents = pendingEvents;
+    }
+    getState() {
+        return this.state;
+    }
+    appendEvent(event) {
+        if (!isSessionStartedEvent(event)) {
+            throw new WorkflowStateError(`Unexpected event in appendEvent: ${event.type}`);
+        }
+        this.pendingEvents = [...this.pendingEvents, event];
+        this.state = {
+            ...this.state,
+            transcriptPath: event.transcriptPath,
+        };
+    }
+    getPendingEvents() {
+        return this.pendingEvents;
+    }
+    startSession(transcriptPath, repository) {
+        void repository;
+        this.state = {
+            ...this.state,
+            transcriptPath,
+        };
+        this.pendingEvents = [...this.pendingEvents, {
+                type: 'session-started',
+                at: '2026-01-01T00:00:00Z',
+                transcriptPath,
+                currentState: this.state.currentStateMachineState,
+                states: ['PLANNING'],
+            }];
+    }
+    getTranscriptPath() {
+        return this.state.transcriptPath;
+    }
+    registerAgent(agentType, agentId) {
+        return allowAgentRegistration(agentType, agentId);
+    }
+    handleTeammateIdle(agentName) {
+        return allowIdleCheck(agentName);
+    }
+}
+class ReviewTrackingWorkflow {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    getState() {
+        return this.state;
+    }
+    appendEvent(event) {
+        void event;
+        throw new WorkflowStateError('appendEvent is not used in this test');
+    }
+    getPendingEvents() {
+        return [];
+    }
+    startSession(transcriptPath, repository) {
+        void transcriptPath;
+        void repository;
+        throw new WorkflowStateError('startSession is not used in this test');
+    }
+    getTranscriptPath() {
+        return '';
+    }
+    registerAgent(agentType, agentId) {
+        return allowAgentRegistration(agentType, agentId);
+    }
+    handleTeammateIdle(agentName) {
+        return allowIdleCheck(agentName);
+    }
+}
+class InMemoryWorkflowEventStore {
+    eventsBySessionId = new Map();
+    readEvents(sessionId) {
+        return this.eventsBySessionId.get(sessionId) ?? [];
+    }
+    appendEvents(sessionId, events) {
+        const existingEvents = this.eventsBySessionId.get(sessionId) ?? [];
+        this.eventsBySessionId.set(sessionId, [...existingEvents, ...events]);
+    }
+    sessionExists(sessionId) {
+        return this.eventsBySessionId.has(sessionId);
+    }
+    hasSessionStarted(sessionId) {
+        return this.readEvents(sessionId).some((event) => event.envelope.type === 'session-started');
+    }
+    recordReflection(sessionId, createdAt, input) {
+        void sessionId;
+        void createdAt;
+        void input;
+        throw new WorkflowStateError('Reflection storage is not configured for this test');
+    }
+    listReflections(sessionId) {
+        void sessionId;
+        return [];
+    }
+    recordReview(sessionId, createdAt, input) {
+        void sessionId;
+        void createdAt;
+        void input;
+        throw new WorkflowStateError('Review storage is not configured for this test');
+    }
+    recordReviewWithEvent(sessionId, createdAt, input, eventState) {
+        void sessionId;
+        void createdAt;
+        void input;
+        void eventState;
+        throw new WorkflowStateError('Review storage is not configured for this test');
+    }
+    listSessionReviews(sessionId) {
+        void sessionId;
+        return [];
+    }
+    listReviews(filters) {
+        void filters;
+        return [];
+    }
+}
+const workflowDefinition = {
+    fold(state, event) {
+        if (!isSessionStartedEvent(event)) {
+            throw new WorkflowStateError(`Unexpected event in fold: ${event.type}`);
+        }
+        return {
+            ...state,
+            transcriptPath: event.transcriptPath,
+        };
+    },
+    buildWorkflow(state) {
+        return new StrictPlanningWorkflow(state);
+    },
+    stateSchema: z.literal('PLANNING'),
+    initialState() {
+        return {
+            currentStateMachineState: 'PLANNING',
+            transcriptPath: '',
+        };
+    },
+    getRegistry() {
+        return {
+            PLANNING: {
+                emoji: '🧭',
+                agentInstructions: 'states/planning.md',
+                canTransitionTo: [],
+                allowedWorkflowOperations: ['write'],
+                forbidden: { write: true },
+            },
+        };
+    },
+    buildTransitionContext(state, from, to) {
+        return {
+            state,
+            from,
+            to,
+            gitInfo: {
+                currentBranch: 'main',
+                workingTreeClean: true,
+                headCommit: 'abc123',
+                changedFilesVsDefault: [],
+                hasCommitsVsDefault: false,
+            },
+        };
+    },
+};
+const reviewTrackingWorkflowDefinition = {
+    fold(state, event) {
+        const reviewRecordedEvent = reviewRecordedEventSchema.parse(event);
+        if (reviewRecordedEvent.reviewType !== 'code-review') {
+            return state;
+        }
+        return {
+            ...state,
+            codeReviewPassed: reviewRecordedEvent.verdict === 'PASS',
+        };
+    },
+    buildWorkflow(state) {
+        return new ReviewTrackingWorkflow(state);
+    },
+    stateSchema: z.literal('REVIEWING'),
+    initialState() {
+        return {
+            currentStateMachineState: 'REVIEWING',
+            codeReviewPassed: false,
+        };
+    },
+    getRegistry() {
+        return {
+            REVIEWING: {
+                emoji: '🔎',
+                agentInstructions: 'states/reviewing.md',
+                canTransitionTo: [],
+                allowedWorkflowOperations: ['record-review'],
+            },
+        };
+    },
+    buildTransitionContext(state, from, to) {
+        return {
+            state,
+            from,
+            to,
+            gitInfo: {
+                currentBranch: 'main',
+                workingTreeClean: true,
+                headCommit: 'abc123',
+                changedFilesVsDefault: [],
+                hasCommitsVsDefault: false,
+            },
+        };
+    },
+};
+function buildStoredEvent(type, at, state, payload) {
+    return {
+        envelope: {
+            type,
+            at,
+            state,
+        },
+        payload,
+    };
+}
+function createEngine() {
+    const store = new InMemoryWorkflowEventStore();
+    const engineDeps = {
+        store,
+        getPluginRoot: () => '/plugin-root',
+        getEnvFilePath: () => '/plugin-root/.env',
+        readFile: () => '',
+        appendToFile: () => undefined,
+        now: () => '2026-01-01T00:00:00Z',
+        transcriptReader: { readMessages: () => [] },
+    };
+    return {
+        store,
+        engine: new WorkflowEngine(workflowDefinition, engineDeps, {}),
+    };
+}
+describe('WorkflowEngine platform-owned events', () => {
+    it('persists journal and write-check events without routing them through the consumer workflow', () => {
+        const { engine, store, } = createEngine();
+        engine.startSession('session-1', '/transcripts/session-1.jsonl');
+        const journalResult = engine.writeJournal('session-1', 'gpt-5.4', 'Captured planning context.');
+        const writeCheckResult = engine.checkWrite('session-1', 'Read', '', () => true);
+        const stateResult = engine.getState('session-1');
+        expect(journalResult.type).toBe('success');
+        expect(writeCheckResult).toStrictEqual({
+            type: 'success',
+            output: '',
+        });
+        expect(stateResult).toStrictEqual({
+            type: 'success',
+            output: JSON.stringify({
+                currentStateMachineState: 'PLANNING',
+                transcriptPath: '/transcripts/session-1.jsonl',
+            }, null, 2),
+        });
+        expect(store.readEvents('session-1').map((event) => event.envelope.type)).toStrictEqual([
+            'session-started',
+            'identity-verified',
+            'journal-entry',
+            'identity-verified',
+            'write-checked',
+        ]);
+    });
+    it('keeps review-recorded available to consumer workflow state reconstruction', () => {
+        const storedEvents = [buildStoredEvent('review-recorded', '2026-01-01T00:01:00Z', 'REVIEWING', {
+                reviewId: 7,
+                reviewType: 'code-review',
+                verdict: 'PASS',
+            })];
+        const state = reduceWorkflowStateFromStoredEvents(reviewTrackingWorkflowDefinition, storedEvents);
+        const flattenedEvent = flattenStoredEvent(storedEvents[0]);
+        expect(reviewRecordedEventSchema.parse(flattenedEvent)).toStrictEqual({
+            type: 'review-recorded',
+            at: '2026-01-01T00:01:00Z',
+            reviewId: 7,
+            reviewType: 'code-review',
+            verdict: 'PASS',
+        });
+        expect(state).toStrictEqual({
+            currentStateMachineState: 'REVIEWING',
+            codeReviewPassed: true,
+        });
+    });
+});

package/dist/platform/domain/workflow-state-reducer.d.ts

@@ -0,0 +1,5 @@
+import { type StoredEvent } from './stored-event';
+import type { BaseWorkflowState } from './workflow-state';
+import type { RehydratableWorkflow, WorkflowDefinition } from './workflow-engine-types';
+/** @riviere-role domain-service */
+export declare function reduceWorkflowStateFromStoredEvents<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>, storedEvents: readonly StoredEvent[]): TState;

package/dist/platform/domain/workflow-state-reducer.js

@@ -0,0 +1,9 @@
+import { isPlatformOwnedEventExcludedFromWorkflowState } from './engine-events.js';
+import { flattenStoredEvent, } from './stored-event.js';
+/** @riviere-role domain-service */
+export function reduceWorkflowStateFromStoredEvents(workflowDefinition, storedEvents) {
+    return storedEvents
+        .map(flattenStoredEvent)
+        .filter((event) => !isPlatformOwnedEventExcludedFromWorkflowState(event.type))
+        .reduce((workflowState, event) => workflowDefinition.fold(workflowState, event), workflowDefinition.initialState());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-engine",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "private": false,
   "type": "module",
   "exports": {