@stackstackstack/dsh-goal 0.1.5

package/lib/types/index.js

@@ -0,0 +1,495 @@
+/**
+ * Same-session goal domain: event-sourced state, compare-and-set mutations,
+ * and process-local continuation activation.
+ * @module @stackstackstack/dsh-goal
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { randomUUID } from 'node:crypto';
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import { agentEvents } from '@stackstackstack/dsh-agent';
+import { TypertRemoteService, Remote } from '@stackstackstack/dsh-typert-protocol';
+import { applyGoalEvent, decodeGoalChange, emptyGoalFoldState, goalChangeRef, } from "./fold.js";
+import { GOAL_CHANGE_VERSION, GoalError, GoalId, } from "./runtime.js";
+export { GOAL_CHANGE_VERSION, GoalError, GoalId } from "./runtime.js";
+export { decodeGoalChange, foldGoal, goalChangeRef } from "./fold.js";
+/** Wire payload schema of the `goal` projection (whole current goal or pre-create/cleared null). */
+const goalProjectionSchema = zod.union([
+    zod.object({
+        goal: zod.object({
+            id: zod.string().min(1),
+            revision: zod.number().int().positive(),
+            objective: zod.string().min(1),
+            phase: zod.union([zod.literal('active'), zod.literal('paused'), zod.literal('blocked'), zod.literal('complete')]),
+            blockedReason: zod.object({ code: zod.string(), message: zod.string() }).optional(),
+            maxGoalRounds: zod.number().int().positive(),
+        }),
+        roundsStarted: zod.number().int().nonnegative(),
+        createdAt: zod.number(),
+        updatedAt: zod.number(),
+    }),
+    zod.null(),
+]);
+/**
+ * Light last-wins fold of the `goal` projection unit. Unlike the strict
+ * replay fold (fold.ts: transition validation, fail-loud on malformed
+ * changes, Set-typed state), this transition is projection-grade: the state
+ * is plain JSON (persisted-cache precondition), any non-goal or malformed
+ * event returns the same reference (the registry's Object.is gate — the
+ * title/todos posture), and correctness of the written change is the write
+ * side's job (GoalService validated it before appending; the package
+ * invariant rejects a violating stream fail-loud where it is installed).
+ * @param state - the projection covering all prior events.
+ * @param event - the next committed session event.
+ * @returns the next projection (same reference when the event is not a goal change).
+ */
+export function applyGoalProjection(state, event) {
+    if (event.type !== 'goal/change')
+        return state;
+    let change;
+    try {
+        change = decodeGoalChange(event.data);
+    }
+    catch (_invalidPersistedGoalChange) {
+        return state;
+    }
+    if (change === undefined)
+        return state;
+    return change.operation === 'clear'
+        ? null
+        : {
+            goal: change.goal,
+            roundsStarted: change.roundsStarted,
+            createdAt: change.createdAt,
+            updatedAt: change.updatedAt,
+        };
+}
+/** Validate a caller-visible positive safe-integer round cap. */
+function resolveMaxGoalRounds(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new GoalError('maxGoalRounds must be a positive safe integer', 'GOAL_INVALID_MAX_ROUNDS');
+    }
+    return value;
+}
+/** Validate and normalize an objective at the domain boundary. */
+function resolveObjective(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new GoalError('goal objective must be a non-empty string', 'GOAL_INVALID_OBJECTIVE');
+    }
+    return value.trim();
+}
+/** Materialize deployment defaults and validate one create request. */
+function resolveCreateGoal(request, defaultMaxGoalRounds) {
+    return {
+        objective: resolveObjective(request.objective),
+        maxGoalRounds: resolveMaxGoalRounds(request.maxGoalRounds ?? defaultMaxGoalRounds),
+    };
+}
+/** Validate and detach one policy-owned blocker explanation. */
+function resolveBlockReason(reason) {
+    const record = typeof reason === 'object' && reason !== null && !Array.isArray(reason)
+        ? reason
+        : undefined;
+    const code = record?.['code'];
+    const message = record?.['message'];
+    if (typeof code !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(code)
+        || typeof message !== 'string' || message.trim().length === 0) {
+        throw new GoalError('goal block reason requires a lower-kebab-case code and a non-empty message', 'GOAL_INVALID_BLOCK_REASON');
+    }
+    return { code, message: message.trim() };
+}
+/** Goal service (`ctx.goals`) backed exclusively by the owning session log. */
+let GoalService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _edit_decorators;
+    let _pause_decorators;
+    let _resume_decorators;
+    let _complete_decorators;
+    let _clear_decorators;
+    let _remoteExportCreate_decorators;
+    return class GoalService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _edit_decorators = [Remote('edit')];
+            _pause_decorators = [Remote('pause')];
+            _resume_decorators = [Remote('resume')];
+            _complete_decorators = [Remote('complete')];
+            _clear_decorators = [Remote('clear')];
+            _remoteExportCreate_decorators = [Remote('create')];
+            __esDecorate(this, null, _edit_decorators, { kind: "method", name: "edit", static: false, private: false, access: { has: obj => "edit" in obj, get: obj => obj.edit }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _pause_decorators, { kind: "method", name: "pause", static: false, private: false, access: { has: obj => "pause" in obj, get: obj => obj.pause }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _resume_decorators, { kind: "method", name: "resume", static: false, private: false, access: { has: obj => "resume" in obj, get: obj => obj.resume }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _complete_decorators, { kind: "method", name: "complete", static: false, private: false, access: { has: obj => "complete" in obj, get: obj => obj.complete }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clear_decorators, { kind: "method", name: "clear", static: false, private: false, access: { has: obj => "clear" in obj, get: obj => obj.clear }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _remoteExportCreate_decorators, { kind: "method", name: "remoteExportCreate", static: false, private: false, access: { has: obj => "remoteExportCreate" in obj, get: obj => obj.remoteExportCreate }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['agents'];
+        static Config = z.object({
+            defaultMaxGoalRounds: z.number().default(256),
+        });
+        resolved = __runInitializers(this, _instanceExtraInitializers);
+        caches = new WeakMap();
+        constructor(ctx, config = {}) {
+            super(ctx, 'goals');
+            this.resolved = {
+                defaultMaxGoalRounds: resolveMaxGoalRounds(config.defaultMaxGoalRounds ?? 256),
+            };
+            ctx.on('agent/session-start', ({ agent }) => {
+                this.cache(agent.session).activation = 'disarmed';
+            });
+            // The `goal` projection unit: last-wins fold of goal/change whole values
+            // (see applyGoalProjection). The unit child activates only when a
+            // projection registry is composed (headless assemblies stay unaffected).
+            ctx.inject(['sessionProjections'], (projectionCtx) => {
+                projectionCtx.sessionProjections.register({
+                    key: 'goal',
+                    schema: goalProjectionSchema,
+                    init: () => null,
+                    apply: applyGoalProjection,
+                    view: state => state,
+                    stateVersion: 4,
+                });
+            });
+        }
+        /**
+         * Read the current goal for one exact live agent.
+         * @param agent - owning live agent.
+         * @returns a fresh view or `undefined` when no goal is current.
+         * @throws {@link GoalError} when the agent is not the registry's live instance.
+         */
+        get(agent) {
+            this.assertLive(agent);
+            const cache = this.cache(agent.session);
+            this.sync(agent.session, cache);
+            return this.view(cache);
+        }
+        /**
+         * Remove process-local continuation authority without changing durable goal
+         * phase or revision. Lifecycle owners use this before unloading a driver;
+         * a later human-authorized {@link resume} records the new activation edge.
+         * @param agent - owning live agent.
+         * @returns a fresh disarmed view, or `undefined` when no goal is current.
+         */
+        disarm(agent) {
+            this.assertLive(agent);
+            const cache = this.cache(agent.session);
+            this.sync(agent.session, cache);
+            cache.activation = 'disarmed';
+            return this.view(cache);
+        }
+        /**
+         * Create and arm a goal. A completed goal may be replaced; every other
+         * current phase must be cleared or resumed instead.
+         * @param agent - owning live agent.
+         * @param request - objective and optional round cap.
+         * @returns the created live view.
+         */
+        create(agent, request) {
+            const spec = resolveCreateGoal(request, this.resolved.defaultMaxGoalRounds);
+            const cache = this.prepareMutation(agent);
+            const current = cache.state.goal;
+            if (current !== undefined && current.phase !== 'complete') {
+                throw new GoalError(`goal "${current.id}" already exists with phase "${current.phase}"`, 'GOAL_ALREADY_EXISTS');
+            }
+            const now = Date.now();
+            const goal = {
+                id: GoalId(`goal-${randomUUID()}`),
+                revision: 1,
+                objective: spec.objective,
+                phase: 'active',
+                maxGoalRounds: spec.maxGoalRounds,
+            };
+            return this.commitSnapshot(agent, cache, 'create', goal, 0, now, now, 'armed');
+        }
+        /**
+         * Edit objective and/or round cap without changing phase.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @param request - at least one replacement field.
+         * @returns the edited view.
+         */
+        edit(agent, ref, request) {
+            const cache = this.prepareMutation(agent);
+            const current = this.expectCurrent(cache, ref);
+            if (request.objective === undefined && request.maxGoalRounds === undefined) {
+                throw new GoalError('goal edit requires objective and/or maxGoalRounds', 'GOAL_INVALID_EDIT');
+            }
+            const goal = {
+                ...current,
+                revision: current.revision + 1,
+                ...request.objective === undefined ? {} : { objective: resolveObjective(request.objective) },
+                ...request.maxGoalRounds === undefined ? {} : { maxGoalRounds: resolveMaxGoalRounds(request.maxGoalRounds) },
+            };
+            return this.commitCurrent(agent, cache, 'edit', goal, cache.activation);
+        }
+        /**
+         * Pause an active goal and disarm automatic continuation.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @returns the paused view.
+         */
+        pause(agent, ref) {
+            return this.transition(agent, ref, 'pause', ['active'], 'paused', 'disarmed');
+        }
+        /**
+         * Resume and arm a stopped goal, or rearm an active goal after a
+         * session-start edge, while its round budget still has capacity.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @returns the active view.
+         */
+        resume(agent, ref) {
+            const cache = this.prepareMutation(agent);
+            const current = this.expectCurrent(cache, ref);
+            const resumable = ['active', 'paused', 'blocked'];
+            if (!resumable.includes(current.phase)) {
+                throw this.transitionError(current, 'resume', resumable);
+            }
+            if (current.phase === 'active' && cache.activation === 'armed') {
+                throw new GoalError(`goal "${current.id}" is already active and armed`, 'GOAL_INVALID_TRANSITION');
+            }
+            if (cache.state.roundsStarted >= current.maxGoalRounds) {
+                throw new GoalError(`goal "${current.id}" exhausted ${current.maxGoalRounds} goal rounds; increase maxGoalRounds before resuming`, 'GOAL_INVALID_TRANSITION');
+            }
+            return this.commitCurrent(agent, cache, 'resume', this.withPhase(current, 'active'), 'armed');
+        }
+        /**
+         * Mark a current non-complete goal complete and disarm it.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @returns the completed view.
+         */
+        complete(agent, ref) {
+            return this.transition(agent, ref, 'complete', ['active', 'paused', 'blocked'], 'complete', 'disarmed');
+        }
+        /**
+         * Mark an active goal blocked and disarm it.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @param reason - policy-owned stable code and human-readable explanation.
+         * @returns the blocked view with its durable reason.
+         */
+        block(agent, ref, reason) {
+            const cache = this.prepareMutation(agent);
+            const current = this.expectCurrent(cache, ref);
+            if (current.phase !== 'active') {
+                throw this.transitionError(current, 'block', ['active']);
+            }
+            return this.commitCurrent(agent, cache, 'block', { ...this.withPhase(current, 'blocked'), blockedReason: resolveBlockReason(reason) }, 'disarmed');
+        }
+        /**
+         * Clear the current goal while retaining a durable tombstone and history.
+         * @param agent - owning live agent.
+         * @param ref - expected current revision.
+         * @returns the tombstone ref whose revision is one past the cleared snapshot.
+         */
+        clear(agent, ref) {
+            const cache = this.prepareMutation(agent);
+            const current = this.expectCurrent(cache, ref);
+            const tombstone = { id: current.id, revision: current.revision + 1 };
+            const change = {
+                kind: 'goal/change',
+                version: GOAL_CHANGE_VERSION,
+                operation: 'clear',
+                cleared: tombstone,
+                clearedAt: this.nextMutationTime(cache),
+            };
+            this.commit(agent, cache, change, 'disarmed');
+            return { ...tombstone };
+        }
+        /** Resolve and validate the cache used by a mutation. */
+        prepareMutation(agent) {
+            this.assertLive(agent);
+            const cache = this.cache(agent.session);
+            this.sync(agent.session, cache);
+            return cache;
+        }
+        /** Reject stale or missing current-state refs. */
+        expectCurrent(cache, ref) {
+            const current = cache.state.goal;
+            if (current === undefined)
+                throw new GoalError('no current goal', 'GOAL_NOT_FOUND');
+            if (ref.id !== current.id || ref.revision !== current.revision) {
+                throw new GoalError(`stale goal ref "${ref.id}" revision ${ref.revision}; current is "${current.id}" revision ${current.revision}`, 'GOAL_STALE_REVISION');
+            }
+            return current;
+        }
+        /** Enforce exact live-agent identity rather than trusting a matching id. */
+        assertLive(agent) {
+            if (this.ctx.agents.get(agent.id) !== agent) {
+                throw new GoalError(`agent "${agent.id}" is not live in this registry`, 'GOAL_AGENT_NOT_LIVE');
+            }
+        }
+        /** Return the per-session cache, folding a seed once with activation disarmed. */
+        cache(session) {
+            let cache = this.caches.get(session);
+            if (cache !== undefined)
+                return cache;
+            const state = emptyGoalFoldState();
+            for (const event of session.events)
+                applyGoalEvent(state, event);
+            cache = {
+                state,
+                activation: 'disarmed',
+                observedSeq: session.seq,
+                pendingActivation: undefined,
+            };
+            this.caches.set(session, cache);
+            return cache;
+        }
+        /** Incrementally observe durable events and reconcile local activation intent. */
+        sync(session, cache) {
+            for (const event of session.events.slice(cache.observedSeq)) {
+                applyGoalEvent(cache.state, event);
+                if (event.type === 'goal/change') {
+                    cache.activation = cache.pendingActivation?.seq === event.seq
+                        ? cache.pendingActivation.activation
+                        : 'disarmed';
+                }
+                cache.observedSeq += 1;
+            }
+        }
+        /** Build a new revision with one replacement phase. */
+        withPhase(current, phase) {
+            return {
+                id: current.id,
+                revision: current.revision + 1,
+                objective: current.objective,
+                phase,
+                maxGoalRounds: current.maxGoalRounds,
+            };
+        }
+        /** Shared validated phase transition. */
+        transition(agent, ref, operation, allowed, phase, activation) {
+            const cache = this.prepareMutation(agent);
+            const current = this.expectCurrent(cache, ref);
+            if (!allowed.includes(current.phase))
+                throw this.transitionError(current, operation, allowed);
+            return this.commitCurrent(agent, cache, operation, this.withPhase(current, phase), activation);
+        }
+        /** Render a stable invalid-transition error. */
+        transitionError(current, operation, allowed) {
+            return new GoalError(`cannot ${operation} goal "${current.id}" from phase "${current.phase}"; expected ${allowed.join(' or ')}`, 'GOAL_INVALID_TRANSITION');
+        }
+        /** Commit a mutation that retains the current goal's derived counters/times. */
+        commitCurrent(agent, cache, operation, goal, activation) {
+            const createdAt = cache.state.createdAt;
+            /* v8 ignore next -- strict replay and every snapshot commit set createdAt whenever a current goal exists */
+            if (createdAt === undefined)
+                throw new Error('current goal cache lacks createdAt');
+            return this.commitSnapshot(agent, cache, operation, goal, cache.state.roundsStarted, createdAt, this.nextMutationTime(cache), activation);
+        }
+        /** Clamp a current goal's next timestamp across backward wall-clock movement. */
+        nextMutationTime(cache) {
+            const updatedAt = cache.state.updatedAt;
+            /* v8 ignore next -- strict replay and every snapshot commit set updatedAt whenever a current goal exists */
+            if (updatedAt === undefined)
+                throw new Error('current goal cache lacks updatedAt');
+            return Math.max(Date.now(), updatedAt);
+        }
+        /** Build and commit one full-snapshot mutation. */
+        commitSnapshot(agent, cache, operation, goal, roundsStarted, createdAt, updatedAt, activation) {
+            const change = {
+                kind: 'goal/change',
+                version: GOAL_CHANGE_VERSION,
+                operation,
+                goal,
+                roundsStarted,
+                createdAt,
+                updatedAt,
+            };
+            this.commit(agent, cache, change, activation);
+            const view = this.view(cache);
+            /* v8 ignore next -- the durable goal event installs the snapshot before this read */
+            if (view === undefined)
+                throw new Error('snapshot commit cleared the goal unexpectedly');
+            return view;
+        }
+        /** Commit one mutation into the goal log, cache, and live event stream. */
+        commit(agent, cache, change, activation) {
+            const ref = goalChangeRef(change);
+            cache.pendingActivation = { seq: agent.session.seq, activation };
+            try {
+                agent.session.append('goal/change', change);
+                this.sync(agent.session, cache);
+            }
+            finally {
+                cache.pendingActivation = undefined;
+            }
+            const goal = this.view(cache);
+            const notification = {
+                operation: change.operation,
+                ref: { ...ref },
+                ...goal === undefined ? {} : { goal },
+            };
+            agentEvents(this.ctx, agent).emit('goal/changed', { change: notification });
+        }
+        /** Build a detached current view. */
+        view(cache) {
+            const goal = cache.state.goal;
+            const createdAt = cache.state.createdAt;
+            const updatedAt = cache.state.updatedAt;
+            if (goal === undefined)
+                return undefined;
+            /* v8 ignore next 3 -- strict replay and snapshot commits establish both timestamps with every current goal */
+            if (createdAt === undefined || updatedAt === undefined) {
+                throw new Error(`goal "${goal.id}" cache lacks timestamps`);
+            }
+            return {
+                ...goal,
+                roundsStarted: cache.state.roundsStarted,
+                createdAt,
+                updatedAt,
+                activation: cache.activation,
+            };
+        }
+        /**
+         * Create one Goal through the remote boundary.
+         * @param agent - exact live Agent resolved from the wire identity.
+         * @param request - objective and optional round cap.
+         * @returns the created Goal identity.
+         */
+        remoteExportCreate(agent, request) {
+            const view = this.create(agent, request);
+            return { ref: { id: view.id, revision: view.revision } };
+        }
+    };
+})();
+export { GoalService };
+export default GoalService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned durable goal-stream invariants. @module @stackstackstack/dsh-goal/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "goal-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the goal-stream invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,70 @@
+/** Package-owned durable goal-stream invariants. @module @stackstackstack/dsh-goal/invariant */
+import { applyGoalEvent, emptyGoalFoldState } from "./fold.js";
+const PACKAGE_NAME = '@stackstackstack/dsh-goal';
+/** Cordis companion plugin name. */
+export const name = 'goal-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Copy the independent fold before validating one candidate event. */
+function cloneState(state) {
+    return {
+        goal: state.goal,
+        roundsStarted: state.roundsStarted,
+        createdAt: state.createdAt,
+        updatedAt: state.updatedAt,
+        lastRef: state.lastRef,
+        seenGoalIds: new Set(state.seenGoalIds),
+    };
+}
+/** Apply one event through the strict goal decoder and attribute failures. */
+function applyChecked(state, event, fail) {
+    try {
+        applyGoalEvent(state, event);
+    }
+    catch (error) {
+        /* v8 ignore next -- the strict goal decoder throws Error instances */
+        const message = error instanceof Error ? error.message : String(error);
+        fail(`session event ${event.seq} violates the durable goal stream: ${message}`);
+    }
+}
+/** Install an independent incremental fold over every attached session. */
+const install = Object.assign((ctx, fail) => {
+    const states = new WeakMap();
+    const staged = new WeakMap();
+    const seed = (session) => {
+        const state = emptyGoalFoldState();
+        for (const event of session.events)
+            applyChecked(state, event, fail);
+        states.set(session, state);
+        return state;
+    };
+    /* v8 ignore next -- session/event always follows list() or session/created seeding */
+    const stateFor = (session) => states.get(session) ?? seed(session);
+    for (const session of ctx.sessions.list())
+        seed(session);
+    ctx.on('session/created', (session) => { seed(session); }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        const state = cloneState(stateFor(session));
+        applyChecked(state, event, fail);
+        staged.set(event, { session, state });
+    }, { global: true });
+    ctx.on('session/event', (session, event) => {
+        const candidate = staged.get(event);
+        /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
+        if (candidate === undefined || candidate.session !== session) {
+            return fail('session/event reached publication without matching goal-fold validation');
+        }
+        staged.delete(event);
+        states.set(session, candidate.state);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/**
+ * Register the goal-stream invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/runtime.d.ts

@@ -0,0 +1,21 @@
+/** Runtime constructors and protocol constants for the goal domain. */
+import { HarnessError } from '@stackstackstack/dsh-llm';
+import type { GoalId as GoalIdType } from './types.ts';
+import type { GoalErrorCode } from './domain.ts';
+/** Version of the goal change embedded in a round-zero message source. */
+export declare const GOAL_CHANGE_VERSION = 1;
+/**
+ * Brand a string as a goal id.
+ * @param id - raw goal identifier.
+ * @returns the same string with the compile-time brand.
+ */
+export declare function GoalId(id: string): GoalIdType;
+/** Error returned by the goal domain boundary. */
+export declare class GoalError extends HarnessError {
+    /**
+     * @param message - human-readable rejection reason.
+     * @param code - stable machine-routable classification.
+     */
+    constructor(message: string, code: GoalErrorCode);
+}
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/runtime.js

@@ -0,0 +1,25 @@
+/** Runtime constructors and protocol constants for the goal domain. */
+import { HarnessError } from '@stackstackstack/dsh-llm';
+/** Version of the goal change embedded in a round-zero message source. */
+export const GOAL_CHANGE_VERSION = 1;
+/**
+ * Brand a string as a goal id.
+ * @param id - raw goal identifier.
+ * @returns the same string with the compile-time brand.
+ */
+export function GoalId(id) {
+    return id;
+}
+/** Error returned by the goal domain boundary. */
+export class GoalError extends HarnessError {
+    /**
+     * @param message - human-readable rejection reason.
+     * @param code - stable machine-routable classification.
+     */
+    // Keep the constructor to narrow HarnessError's string code at this boundary.
+    // oxlint-disable-next-line typescript/no-useless-constructor -- type-only narrowing
+    constructor(message, code) {
+        super(message, code);
+    }
+}
+//# sourceMappingURL=runtime.js.map