@atolis-hq/wake 0.3.81 → 0.3.83

package/dist/src/bootstrap/index.js

@@ -4,8 +4,8 @@ import { createRuntimeProjectionRunner } from './projection-runtime.js';
 export function composeDeliveryService(dependencies) {
     return new DeliveryService(dependencies);
 }
-export function composeDeliveryOutcomeReactor(journal, checkpoints, orchestration) {
-    return new DeliveryOutcomeReactor(journal, checkpoints, orchestration);
+export function composeDeliveryOutcomeReactor(journal, checkpoints, orchestration, projections) {
+    return new DeliveryOutcomeReactor(journal, checkpoints, orchestration, projections);
 }
 export function composeDeliveryRuntime(dependencies) {
     const projectionRunner = createRuntimeProjectionRunner(dependencies.journal, dependencies.projections, dependencies.checkpoints);
@@ -16,7 +16,7 @@ export function composeDeliveryRuntime(dependencies) {
         adapter: dependencies.adapter,
         now: dependencies.now,
     });
-    const reactor = composeDeliveryOutcomeReactor(dependencies.journal, dependencies.checkpoints, dependencies.orchestration);
+    const reactor = composeDeliveryOutcomeReactor(dependencies.journal, dependencies.checkpoints, dependencies.orchestration, dependencies.projections);
     return {
         async runOnce(signal) {
             await projectionRunner.runRegisteredOnce();

package/dist/src/bootstrap/integration-runtime.js

@@ -120,7 +120,7 @@ export async function composeIntegrationRuntime(input) {
         await resourceTransitions.drain();
         return operation();
     });
-    const outcomes = new DeliveryOutcomeReactor(input.journal, input.checkpoints, input.orchestration);
+    const outcomes = new DeliveryOutcomeReactor(input.journal, input.checkpoints, input.orchestration, input.projections);
     const catchUpProjections = async () => {
         await projectionRunner.runRegisteredOnce();
     };

package/dist/src/bootstrap/persistence-composition.js

@@ -13,6 +13,7 @@ function serializeJournalAppends(journal) {
         readStream: (stream) => journal.readStream(stream),
         readAll: (afterGlobalPosition, limit) => journal.readAll(afterGlobalPosition, limit),
         latestGlobalPosition: () => journal.latestGlobalPosition(),
+        changeSignal: journal.changeSignal,
         ...(journal.readLatest === undefined
             ? {}
             : {

package/dist/src/bootstrap/surface-api-applications.js

@@ -229,6 +229,21 @@ function createSystemApplications(root, now) {
                 meta: sampledMeta(sampledAt),
             };
         },
+        async commands() {
+            const sampledAt = now();
+            return {
+                data: {
+                    adapters: root.providers
+                        .filter((instance) => instance.commands !== undefined)
+                        .map((instance) => ({
+                        adapter: instance.adapter,
+                        provider: instance.provider,
+                        commands: instance.commands(),
+                    })),
+                },
+                meta: sampledMeta(sampledAt),
+            };
+        },
     };
 }
 function commandAccepted(command, acceptedAt) {

package/dist/src/bootstrap/surface-cli-applications.js

@@ -39,12 +39,13 @@ export function createSurfaceCliApplications(root, api, now) {
     // hammered every cycle instead of given a chance to recover.
     const runnerResident = new ResidentHost(runnerTick, (signal, { consecutiveIdleTicks, consecutiveErrorTicks }) => {
         if (consecutiveErrorTicks > 0)
-            return sleepUntilAbort(signal, nextIdleBackoffMs(root.config.controlPlane.resident, consecutiveErrorTicks));
+            return sleepUntilAbort(signal, nextPollBackoffMs(root.config.controlPlane.resident, consecutiveErrorTicks));
+        // Genuine idle (no errors): wait for the journal to actually change.
         return consecutiveIdleTicks === 0
             ? Promise.resolve()
-            : sleepUntilAbort(signal, root.config.controlPlane.resident?.idleBackoffMs ?? 1000);
+            : root.journal.changeSignal.waitForChange(signal, JOURNAL_WAIT_FALLBACK_MS);
     }, reportResidentError('runner'));
-    const intakeResident = new ResidentHost(intakeHost, (signal, { consecutiveIdleTicks }) => sleepUntilAbort(signal, nextIdleBackoffMs(root.config.controlPlane.resident, consecutiveIdleTicks)), reportResidentError('intake'));
+    const intakeResident = new ResidentHost(intakeHost, (signal, { consecutiveIdleTicks }) => sleepUntilAbort(signal, nextPollBackoffMs(root.config.controlPlane.resident, consecutiveIdleTicks)), reportResidentError('intake'));
     const servers = new Set();
     const startHttp = createHttpStarter(root, api, servers);
     return {
@@ -134,8 +135,11 @@ export function createSurfaceCliApplications(root, api, now) {
         operational: createOperationalApplications(root),
     };
 }
+// Safety net for a missed in-process notify() or a cross-process writer the
+// EventEmitter can't see; a real append wakes waiters within milliseconds
+// regardless, so there's no operational reason to make this configurable.
+const JOURNAL_WAIT_FALLBACK_MS = 30_000;
 export async function runProjectionPump(root, signal) {
-    const intervalMs = 1000;
     while (!signal.aborted) {
         try {
             await root.projectionRunner.runRegisteredOnce();
@@ -143,12 +147,12 @@ export async function runProjectionPump(root, signal) {
         catch (error) {
             process.stderr.write(`Wake projection pump failed: ${error instanceof Error ? error.message : String(error)}\n`);
         }
-        await sleepUntilAbort(signal, intervalMs);
+        await root.journal.changeSignal.waitForChange(signal, JOURNAL_WAIT_FALLBACK_MS);
     }
 }
-function nextIdleBackoffMs(resident, consecutiveIdleTicks) {
-    const baseMs = resident?.idleBackoffMs ?? 1000;
-    const maxMs = resident?.maxIdleBackoffMs ?? baseMs * 16;
+function nextPollBackoffMs(resident, consecutiveIdleTicks) {
+    const baseMs = resident?.pollBackoffMs ?? 1000;
+    const maxMs = resident?.maxPollBackoffMs ?? baseMs * 16;
     return Math.min(baseMs * 2 ** Math.min(consecutiveIdleTicks, 20), maxMs);
 }
 function sleepUntilAbort(signal, milliseconds) {

package/dist/src/bootstrap/version.js

@@ -108,4 +108,4 @@ export function resolveWakeVersion(options = {}) {
         return `g${headHash.slice(0, 7)}`;
     return '0.1.0-dev';
 }
-export const wakeVersion = "gb8f09ad";
+export const wakeVersion = "gedf016c";

package/dist/src/control-plane/application/control-plane-service.js

@@ -2,22 +2,36 @@ import { EventActorKind, correlationId, } from '../../kernel/index.js';
 import { ControlEventType, createControlEventDraft, selectControlEvent, } from '../contracts/events.js';
 import { controlPlaneStream } from '../contracts/streams.js';
 export function createControlPlaneService(input) {
+    // isPaused() is checked many times per pipeline run, so memoize by
+    // journal position to skip the read entirely when nothing has moved.
+    let cached;
     return {
         pause: (key) => change(input, key, 'pause'),
         resume: (key) => change(input, key, 'resume'),
         async isPaused() {
-            let paused = false;
-            for (const envelope of await input.journal.readStream(controlPlaneStream())) {
-                const event = selectControlEvent(envelope);
-                if (event?.eventType === ControlEventType.DispatchPaused)
-                    paused = true;
-                if (event?.eventType === ControlEventType.DispatchResumed)
-                    paused = false;
-            }
+            const position = await input.journal.latestGlobalPosition();
+            if (cached !== undefined && cached.position === position)
+                return cached.paused;
+            const paused = await currentIsPaused(input.journal);
+            cached = { position, paused };
             return paused;
         },
     };
 }
+async function currentIsPaused(journal) {
+    return isPausedIn(await journal.readStream(controlPlaneStream()));
+}
+function isPausedIn(events) {
+    let paused = false;
+    for (const envelope of events) {
+        const event = selectControlEvent(envelope);
+        if (event?.eventType === ControlEventType.DispatchPaused)
+            paused = true;
+        if (event?.eventType === ControlEventType.DispatchResumed)
+            paused = false;
+    }
+    return paused;
+}
 async function change(input, idempotencyKey, operation) {
     const stream = controlPlaneStream();
     const events = await input.journal.readStream(stream);
@@ -25,7 +39,7 @@ async function change(input, idempotencyKey, operation) {
     const correlation = correlationId(`control:${operation}:${idempotencyKey}`);
     if (events.some((event) => event.eventType === eventType && event.correlationId === correlation))
         return;
-    const currentlyPaused = await createControlPlaneService(input).isPaused();
+    const currentlyPaused = isPausedIn(events);
     if ((operation === 'pause' && currentlyPaused) || (operation === 'resume' && !currentlyPaused))
         return;
     const occurredAt = input.clock.now().toISOString();

package/dist/src/control-plane/contracts/config.js

@@ -14,10 +14,13 @@ export const controlPlaneConfigSchema = z
     schedules: z.array(scheduleSchema).default([]),
     resident: z
         .object({
-        idleBackoffMs: z.number().int().positive().default(1000),
-        maxIdleBackoffMs: z.number().int().positive().optional(),
+        // Backoff for the resident loop's own retry cadence when idle or
+        // erroring, not a per-adapter rate limit (e.g.
+        // integrations.github.polling.intervalMs gates the actual call).
+        pollBackoffMs: z.number().int().positive().default(1000),
+        maxPollBackoffMs: z.number().int().positive().optional(),
     })
         .strict()
-        .default({ idleBackoffMs: 1000 }),
+        .default({ pollBackoffMs: 1000 }),
 })
     .strict();

package/dist/src/integrations/delivery/application/delivery-outcome-reactor.js

@@ -1,34 +1,63 @@
 import { ActivityOutcomeKind, activationId } from '../../../activities/index.js';
-import { EventActorKind } from '../../../kernel/index.js';
+import { EventActorKind, } from '../../../kernel/index.js';
 import { ActivityActivationStatus, workflowInstanceId, } from '../../../orchestration/index.js';
 import { DeliveryEventType, selectDeliveryEvent } from '../contracts/events.js';
 import { DeliveryResultKind } from '../contracts/vocabulary.js';
 const deliveryResultSignalKind = 'delivery-result';
+const pendingNamespace = 'reactor:delivery-outcomes:pending';
+const pendingKey = 'pending-confirmations';
 export class DeliveryOutcomeReactor {
     journal;
     checkpoints;
     orchestration;
-    constructor(journal, checkpoints, orchestration) {
+    projections;
+    constructor(journal, checkpoints, orchestration, projections) {
         this.journal = journal;
         this.checkpoints = checkpoints;
         this.orchestration = orchestration;
+        this.projections = projections;
     }
     async runOnce() {
         const consumer = 'reactor:delivery-outcomes';
         const events = await this.journal.readAll(await this.checkpoints.load(consumer));
-        const resolvedDeliveryEventIds = new Set();
+        const resolved = new Set();
+        const pending = new Map((await this.loadPending()).map((event) => [event.eventId, event]));
         for (const event of events) {
-            await this.reconcile(event, resolvedDeliveryEventIds);
+            const matched = await this.reconcile(event, resolved);
+            if (matched === false) {
+                // reconcile() only ever returns false for a delivery-terminal event
+                // (selectDeliveryEvent(event) !== null), so this lookup can't miss.
+                const delivery = selectDeliveryEvent(event);
+                pending.set(delivery.eventId, event);
+            }
             await this.checkpoints.save(consumer, event.globalPosition);
         }
-        for (const event of await this.journal.readAll(0))
-            await this.reconcile(event, resolvedDeliveryEventIds);
+        // Catches a confirmation checkpointed before its workflow reached
+        // "waiting for delivery" — re-checked here on every call rather than
+        // relying on the incremental pass above, which never revisits a
+        // position once checkpointed.
+        for (const [id, pendingEvent] of pending) {
+            if (resolved.has(id)) {
+                pending.delete(id);
+                continue;
+            }
+            const matched = await this.reconcile(pendingEvent, resolved);
+            if (matched === true)
+                pending.delete(id);
+        }
+        await this.savePending([...pending.values()]);
         return events.length;
     }
+    // true: resolved (accepted this call, or already accepted earlier this
+    // same call). false: a delivery-terminal event whose workflow isn't
+    // waiting on it yet — belongs in the pending set for a later retry. null:
+    // not a delivery-terminal event at all.
     async reconcile(event, seen) {
         const delivery = selectDeliveryEvent(event);
-        if (delivery === null || seen.has(delivery.eventId))
-            return;
+        if (delivery === null)
+            return null;
+        if (seen.has(delivery.eventId))
+            return true;
         const outcome = delivery.eventType === DeliveryEventType.Confirmed ||
             (delivery.eventType === DeliveryEventType.Reconciled &&
                 delivery.payload.result === DeliveryResultKind.Confirmed)
@@ -37,13 +66,13 @@ export class DeliveryOutcomeReactor {
                 ? { kind: ActivityOutcomeKind.Failed, data: { reason: delivery.payload.code } }
                 : null;
         if (outcome === null)
-            return;
+            return null;
         const command = {
             workflowInstanceId: workflowInstanceId(delivery.payload.workflowInstanceId),
             activationId: activationId(delivery.payload.activationId),
         };
         if (!(await this.isAwaitingThisDelivery(command, delivery.payload.intentEventId)))
-            return;
+            return false;
         seen.add(delivery.eventId);
         await this.orchestration.acceptOutcome({ ...command, outcome }, {
             commandId: delivery.eventId,
@@ -51,6 +80,7 @@ export class DeliveryOutcomeReactor {
             actor: { kind: EventActorKind.System, id: 'delivery-outcome-reactor' },
             occurredAt: event.recordedAt,
         });
+        return true;
     }
     /**
      * A delivery's own completion may only resolve the activation that
@@ -66,4 +96,16 @@ export class DeliveryOutcomeReactor {
             view.waitingFor?.signalKind === deliveryResultSignalKind &&
             view.waitingFor.intentEventId === intentEventId);
     }
+    async loadPending() {
+        const stored = await this.projections.read(pendingNamespace, pendingKey);
+        return stored?.value.events ?? [];
+    }
+    async savePending(events) {
+        await this.projections.write({
+            namespace: pendingNamespace,
+            key: pendingKey,
+            lastGlobalPosition: 0,
+            value: { events },
+        });
+    }
 }

package/dist/src/integrations/github/application/inbound-comment-syntax.js

@@ -1,15 +1,17 @@
 import { ReviewActorKind } from '../../../activities/index.js';
+import { GitHubBuiltInCommand } from '../contracts/vocabulary.js';
 export function isHumanNonWakeReply(actorKind, body) {
     return actorKind === ReviewActorKind.Human && !body.includes('<!-- wake:');
 }
 export function recognizedCommand(body) {
     const normalized = body.trim().toLowerCase();
-    if (normalized === '/approved')
-        return '/approved';
-    if (normalized === '/changes' || normalized.startsWith('/changes '))
-        return '/changes';
-    if (normalized === '/retry')
-        return '/retry';
+    if (normalized === GitHubBuiltInCommand.Approved)
+        return GitHubBuiltInCommand.Approved;
+    if (normalized === GitHubBuiltInCommand.Changes ||
+        normalized.startsWith(`${GitHubBuiltInCommand.Changes} `))
+        return GitHubBuiltInCommand.Changes;
+    if (normalized === GitHubBuiltInCommand.Retry)
+        return GitHubBuiltInCommand.Retry;
     return null;
 }
 export function isPlainReply(body) {
@@ -17,5 +19,5 @@ export function isPlainReply(body) {
     return normalized.length > 0 && !normalized.startsWith('/');
 }
 export function shouldResumeBlockedStage(command, plainReply) {
-    return command === '/changes' || plainReply;
+    return command === GitHubBuiltInCommand.Changes || plainReply;
 }

package/dist/src/integrations/github/application/inbound-review-signals.js

@@ -3,7 +3,7 @@ import { ActivityOutcomeKind, ReviewActorKind, ReviewDecisionKind, ReviewerAutho
 import { ApprovalAuthorityKind, selectOperatorRetryTarget, } from '../../../orchestration/index.js';
 import { BuiltInResourceKind, ResourceCorrelationRole, ResourceStreamKind, resourceId, } from '../../../resources/index.js';
 import { WorkStatus } from '../../../work/index.js';
-import { UnknownGitHubIdentity } from '../contracts/vocabulary.js';
+import { GitHubBuiltInCommand, UnknownGitHubIdentity } from '../contracts/vocabulary.js';
 import { isHumanNonWakeReply, isPlainReply, recognizedCommand, shouldResumeBlockedStage, } from './inbound-comment-syntax.js';
 import { commandContext } from './inbound-context.js';
 import { ignoreIneligibleOperatorRetry } from './operator-retry-command.js';
@@ -77,7 +77,7 @@ async function applyIssueReviewSignal(input) {
     const resource = await resources.get(resourceIdValue);
     const command = recognizedCommand(event.payload.body);
     const plainReply = isPlainReply(event.payload.body);
-    if (command === '/retry') {
+    if (command === GitHubBuiltInCommand.Retry) {
         return applyIssueRetrySignal({
             event,
             resources,
@@ -93,7 +93,9 @@ async function applyIssueReviewSignal(input) {
             work,
             orchestration,
             resourceId: resourceIdValue,
-            outcome: command === '/approved' ? ActivityOutcomeKind.Done : ActivityOutcomeKind.Rejected,
+            outcome: command === GitHubBuiltInCommand.Approved
+                ? ActivityOutcomeKind.Done
+                : ActivityOutcomeKind.Rejected,
             acceptWaitingSignal: command !== null,
             resumeBlockedOnChanges: shouldResumeBlockedStage(command, plainReply),
         });
@@ -153,8 +155,10 @@ async function applyIssueApprovalSignal(input) {
         work,
         orchestration,
         resourceId: resourceIdValue,
-        outcome: command === '/approved' ? ActivityOutcomeKind.Done : ActivityOutcomeKind.Rejected,
-        resumeBlockedOnChanges: command === '/changes',
+        outcome: command === GitHubBuiltInCommand.Approved
+            ? ActivityOutcomeKind.Done
+            : ActivityOutcomeKind.Rejected,
+        resumeBlockedOnChanges: command === GitHubBuiltInCommand.Changes,
     });
 }
 async function applyPullRequestWorkflowSignal(input) {

package/dist/src/integrations/github/application/review-command-translator.js

@@ -1,7 +1,8 @@
 import { ReviewDecisionKind, } from '../../../activities/index.js';
+import { GitHubBuiltInCommand } from '../contracts/vocabulary.js';
 export function translateGitHubReviewCommand(input) {
     const command = input.body.trim();
-    if (command !== '/accepted' && command !== '/changes')
+    if (command !== GitHubBuiltInCommand.Accepted && command !== GitHubBuiltInCommand.Changes)
         return null;
     return {
         resourceId: input.resourceId,
@@ -11,6 +12,8 @@ export function translateGitHubReviewCommand(input) {
         resourceAuthorId: input.resourceAuthorId,
         authorization: input.authorization,
         providerEventId: input.providerEventId,
-        kind: command === '/accepted' ? ReviewDecisionKind.Accepted : ReviewDecisionKind.ChangesRequested,
+        kind: command === GitHubBuiltInCommand.Accepted
+            ? ReviewDecisionKind.Accepted
+            : ReviewDecisionKind.ChangesRequested,
     };
 }

package/dist/src/integrations/github/contracts/config.js

@@ -52,5 +52,10 @@ export const gitHubConfigSchema = z
         .object({ postStatusComments: z.boolean().default(true) })
         .strict()
         .default({ postStatusComments: true }),
+    // Additional command syntax to advertise on the commands/instructions
+    // surface alongside the adapter's built-in commands. Purely descriptive:
+    // Wake does not recognize these itself, so any behavior they imply must
+    // be handled by whatever reads the comment (e.g. a workflow prompt).
+    commands: z.array(z.string().trim().min(1)).default([]),
 })
     .strict();

package/dist/src/integrations/github/contracts/vocabulary.js

@@ -54,3 +54,15 @@ export const GitHubOutboundAction = {
     Reply: 'reply',
     Close: 'close',
 };
+// Comment-channel commands the GitHub adapter recognizes from human replies.
+// /approved and /changes drive issue-review and PR-issue-comment signals;
+// /accepted and /changes drive formal (native) PR review comments; /retry
+// resumes a blocked/failed stage. Kept as the single source of truth for both
+// recognition (inbound-comment-syntax.ts, review-command-translator.ts) and
+// the commands/instructions surface, so the two cannot drift.
+export const GitHubBuiltInCommand = defineClosedVocabulary({
+    Approved: '/approved',
+    Accepted: '/accepted',
+    Changes: '/changes',
+    Retry: '/retry',
+});

package/dist/src/integrations/github/infrastructure/comment-source.js

@@ -1,4 +1,5 @@
 import { ReviewerAuthorizationSource, } from '../../../activities/index.js';
+import { GitHubBuiltInCommand } from '../contracts/vocabulary.js';
 import { issueCommentObservation } from './issue-source.js';
 import { mergeBatches, reportPartialPollFailure } from './poll-watermark.js';
 import { githubReviewObservation } from './review-source.js';
@@ -69,7 +70,7 @@ async function issueCommentEventsForComment(context, issue, comment) {
     return event === null ? [] : [event];
 }
 async function retryAuthorization(context, comment) {
-    if (comment.body?.trim().toLowerCase() !== '/retry')
+    if (comment.body?.trim().toLowerCase() !== GitHubBuiltInCommand.Retry)
         return undefined;
     const login = comment.user?.login;
     if (login === undefined || context.client.collaboratorPermission === undefined)

package/dist/src/integrations/github/infrastructure/review-source.js

@@ -3,7 +3,7 @@ import { createEventDraft, EventActorKind, EventSourceKind } from '../../../kern
 import { integrationStream } from '../../contracts/streams.js';
 import { GitHubEventType } from '../contracts/events.js';
 import { formatGitHubResourceKey } from '../contracts/external-key.js';
-import { GitHubAdapter, GitHubReviewState, UnknownGitHubIdentity, } from '../contracts/vocabulary.js';
+import { GitHubAdapter, GitHubBuiltInCommand, GitHubReviewState, UnknownGitHubIdentity, } from '../contracts/vocabulary.js';
 export function githubReviewObservation(input) {
     const body = input.review.body?.trim();
     const command = reviewCommand(input.review.state);
@@ -62,8 +62,8 @@ function configuredAuthorization(actorId, reviewers) {
 }
 function reviewCommand(state) {
     if (state === GitHubReviewState.Approved)
-        return '/accepted';
-    return state === GitHubReviewState.ChangesRequested ? '/changes' : null;
+        return GitHubBuiltInCommand.Accepted;
+    return state === GitHubReviewState.ChangesRequested ? GitHubBuiltInCommand.Changes : null;
 }
 function sameIdentity(left, right) {
     return left.toLowerCase() === right.toLowerCase();

package/dist/src/integrations/github/provider.js

@@ -6,6 +6,7 @@ import { translateGitHubOutbound } from './application/outbound-translator.js';
 import { createGitHubWakeLabelReconciler } from './application/wake-labels.js';
 import { gitHubConfigSchema } from './contracts/config.js';
 import { GitHubEventType } from './contracts/events.js';
+import { GitHubBuiltInCommand } from './contracts/vocabulary.js';
 import { createGitHubAdapterHealthRegistry } from './infrastructure/adapter-health-registry.js';
 import { createGitHubClient } from './infrastructure/client.js';
 import { createGitHubDelivery } from './infrastructure/delivery.js';
@@ -43,6 +44,10 @@ export const gitHubProviderDefinition = {
                 requests,
             }),
             health: () => health.snapshotAll(),
+            commands: () => [
+                ...Object.values(GitHubBuiltInCommand).map((syntax) => ({ syntax })),
+                ...config.commands.map((syntax) => ({ syntax })),
+            ],
             delivery: createGitHubDelivery(async (intent, idempotencyKey) => {
                 const resource = await services.resources.get(resourceId(intent.resourceId));
                 if (resource === null)

package/dist/src/kernel/contracts/journal-change-signal.js

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

package/dist/src/kernel/index.js

@@ -5,6 +5,7 @@ export * from './contracts/event-journal.js';
 export * from './contracts/event-schema.js';
 export * from './contracts/events.js';
 export * from './contracts/id-generator.js';
+export * from './contracts/journal-change-signal.js';
 export { causationId, correlationId, eventId } from './contracts/identifiers.js';
 export * from './contracts/projection-store.js';
 export * from './contracts/relations.js';
@@ -14,5 +15,6 @@ export * from './domain/event-envelope.js';
 export * from './domain/match-mode.js';
 export * from './domain/relation.js';
 export * from './infrastructure/cached-journal-view.js';
+export * from './infrastructure/journal-change-signal.js';
 export * from './infrastructure/system-clock.js';
 export * from './infrastructure/ulid-id-generator.js';

package/dist/src/kernel/infrastructure/journal-change-signal.js

@@ -0,0 +1,30 @@
+export class InProcessJournalChangeSignal {
+    waiters = [];
+    notify() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
+    waitForChange(signal, fallbackMs) {
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let settled = false;
+            const done = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal.removeEventListener('abort', done);
+                // Must drop this waiter here too, not just in notify() — otherwise
+                // every timeout/abort leaks an entry into `waiters` forever.
+                this.waiters = this.waiters.filter((waiter) => waiter !== done);
+                resolve();
+            };
+            this.waiters.push(done);
+            const timer = setTimeout(done, fallbackMs);
+            signal.addEventListener('abort', done, { once: true });
+        });
+    }
+}

package/dist/src/persistence/filesystem/file-event-journal.js

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { decodeEventEnvelope, WrongExpectedSequenceError } from '../../kernel/index.js';
+import { decodeEventEnvelope, InProcessJournalChangeSignal, WrongExpectedSequenceError, } from '../../kernel/index.js';
 import { withFileLock } from './file-lock.js';
 export class FileEventJournal {
     root;
@@ -10,6 +10,10 @@ export class FileEventJournal {
         this.root = root;
         this.clock = clock;
     }
+    changeSignalSource = new InProcessJournalChangeSignal();
+    get changeSignal() {
+        return this.changeSignalSource;
+    }
     cached;
     async append(stream, expectedSequence, drafts) {
         return withFileLock(join(this.root, 'locks', 'event-journal.lock'), async () => {
@@ -56,6 +60,7 @@ export class FileEventJournal {
                 const file = `${day}.jsonl`;
                 await appendFile(join(directory, file), newEnvelopes.map((event) => JSON.stringify(event)).join('\n') + '\n', 'utf8');
                 await this.extendCache(file, current, newEnvelopes);
+                this.changeSignalSource.notify();
             }
             return finalizedEnvelopes;
         });

package/dist/src/persistence/memory/in-memory-event-journal.js

@@ -1,13 +1,17 @@
 import { isDeepStrictEqual } from 'node:util';
-import { WrongExpectedSequenceError } from '../../kernel/index.js';
+import { InProcessJournalChangeSignal, WrongExpectedSequenceError } from '../../kernel/index.js';
 export class InMemoryEventJournal {
     clock;
     streams = new Map();
     events = [];
     eventIds = new Map();
+    changeSignalSource = new InProcessJournalChangeSignal();
     constructor(clock) {
         this.clock = clock;
     }
+    get changeSignal() {
+        return this.changeSignalSource;
+    }
     async append(stream, expectedSequence, events) {
         validateBatch(stream, events);
         const existingEvents = events.map((draft) => this.eventIds.get(draft.eventId));
@@ -21,6 +25,7 @@ export class InMemoryEventJournal {
         }
         const recordedAt = this.clock.now().toISOString();
         const appended = [];
+        let newCount = 0;
         for (const [index, draft] of events.entries()) {
             const prior = existingEvents[index];
             if (prior !== undefined) {
@@ -37,8 +42,11 @@ export class InMemoryEventJournal {
             this.events.push(envelope);
             this.eventIds.set(draft.eventId, { draft, envelope });
             appended.push(envelope);
+            newCount += 1;
         }
         this.streams.set(streamKey(stream), streamEvents);
+        if (newCount > 0)
+            this.changeSignalSource.notify();
         return appended;
     }
     async readStream(stream) {

package/dist/src/surfaces/api/routes/read.js

@@ -36,6 +36,8 @@ async function readSingleton(applications, url) {
             return noQuery(url, async () => ok(await applications.system.health()));
         case '/api/v1/system/configuration':
             return noQuery(url, async () => ok(await applications.system.configuration()));
+        case '/api/v1/system/commands':
+            return noQuery(url, async () => ok(await applications.system.commands()));
         default:
             return undefined;
     }

package/dist/src/surfaces/api/routes/system.js

@@ -1 +1,5 @@
-export const systemRoutes = ['/api/v1/system/health', '/api/v1/system/configuration'];
+export const systemRoutes = [
+    '/api/v1/system/health',
+    '/api/v1/system/configuration',
+    '/api/v1/system/commands',
+];