@atolis-hq/wake 0.2.97 → 0.3.0

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

@@ -0,0 +1,143 @@
+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 { withFileLock } from './file-lock.js';
+export class FileEventJournal {
+    root;
+    clock;
+    constructor(root, clock) {
+        this.root = root;
+        this.clock = clock;
+    }
+    cached;
+    async append(stream, expectedSequence, drafts) {
+        return withFileLock(join(this.root, 'locks', 'event-journal.lock'), async () => {
+            const current = await this.scan();
+            const byId = new Map(current.map((event) => [event.eventId, event]));
+            const batchIds = new Set();
+            for (const draft of drafts) {
+                if (batchIds.has(draft.eventId))
+                    throw new Error(`Event id ${draft.eventId} is repeated in one append`);
+                batchIds.add(draft.eventId);
+            }
+            const existing = drafts.map((draft) => byId.get(draft.eventId));
+            for (const [index, event] of existing.entries())
+                if (event !== undefined && !sameDraft(event, drafts[index]))
+                    throw new Error(`Event id ${event.eventId} has already been used with different content`);
+            if (drafts.length > 0 && existing.every(isDefined))
+                return existing.filter(isDefined);
+            const streamEvents = current.filter((event) => key(event.stream) === key(stream));
+            if (streamEvents.length !== expectedSequence)
+                throw new WrongExpectedSequenceError(`Expected sequence ${expectedSequence} for ${key(stream)}, actual ${streamEvents.length}`);
+            for (const draft of drafts)
+                if (key(draft.stream) !== key(stream))
+                    throw new Error('Event stream mismatch');
+            const recordedAt = this.clock.now().toISOString();
+            let newCount = 0;
+            const envelopes = drafts.map((draft, index) => {
+                const prior = existing[index];
+                if (prior !== undefined)
+                    return prior;
+                newCount += 1;
+                return {
+                    ...draft,
+                    recordedAt,
+                    sequence: streamEvents.length + newCount,
+                    globalPosition: current.length + newCount,
+                };
+            });
+            const finalizedEnvelopes = envelopes.map((event) => decodeEventEnvelope(event));
+            const newEnvelopes = finalizedEnvelopes.filter((event) => !byId.has(event.eventId));
+            if (newEnvelopes.length > 0) {
+                const directory = join(this.root, 'events');
+                await mkdir(directory, { recursive: true });
+                const day = recordedAt.slice(0, 10);
+                await appendFile(join(directory, `${day}.jsonl`), newEnvelopes.map((event) => JSON.stringify(event)).join('\n') + '\n', 'utf8');
+            }
+            this.cached = undefined;
+            return finalizedEnvelopes;
+        });
+    }
+    async readStream(stream) {
+        return (await this.scan()).filter((event) => key(event.stream) === key(stream));
+    }
+    async readAll(after, limit = Number.POSITIVE_INFINITY) {
+        return (await this.scan()).filter((event) => event.globalPosition > after).slice(0, limit);
+    }
+    async readLatest(beforeGlobalPosition, limit = Number.POSITIVE_INFINITY) {
+        const events = await this.scan();
+        const before = beforeGlobalPosition ?? events.length + 1;
+        return events
+            .slice(0, before - 1)
+            .slice(-limit)
+            .reverse();
+    }
+    async scan() {
+        const directory = join(this.root, 'events');
+        let files;
+        try {
+            files = (await readdir(directory))
+                .filter((file) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(file))
+                .sort();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const fingerprint = (await Promise.all(files.map(async (file) => {
+            const info = await stat(join(directory, file));
+            return `${file}:${info.size}:${info.mtimeMs}`;
+        }))).join('|');
+        if (this.cached?.fingerprint === fingerprint)
+            return this.cached.events;
+        const events = [];
+        for (const file of files) {
+            const raw = await readFile(join(directory, file), 'utf8');
+            if (raw.length > 0 && !raw.endsWith('\n'))
+                throw new Error(`Incomplete trailing line in ${file}`);
+            for (const [index, line] of raw.split('\n').slice(0, -1).entries()) {
+                let input;
+                try {
+                    input = JSON.parse(line);
+                    const event = decodeEventEnvelope(input);
+                    validateEnvelope(event, events.length + 1);
+                    events.push(event);
+                }
+                catch (error) {
+                    const context = eventContext(input);
+                    throw new Error(`Corrupt event at ${file}:${index + 1}${context}: ${error.message}`, { cause: error });
+                }
+            }
+        }
+        this.cached = { fingerprint, events };
+        return events;
+    }
+}
+const key = (stream) => `${stream.kind}:${stream.id}`;
+const sameDraft = (event, draft) => isDeepStrictEqual({
+    eventId: event.eventId,
+    eventType: event.eventType,
+    schemaVersion: event.schemaVersion,
+    occurredAt: event.occurredAt,
+    correlationId: event.correlationId,
+    causationId: event.causationId,
+    actor: event.actor,
+    source: event.source,
+    stream: event.stream,
+    payload: event.payload,
+}, draft);
+function validateEnvelope(event, expectedPosition) {
+    if (event.globalPosition !== expectedPosition)
+        throw new Error('Invalid event envelope position');
+}
+function eventContext(input) {
+    if (typeof input !== 'object' || input === null || !('eventId' in input))
+        return '';
+    const eventId = input.eventId;
+    return typeof eventId === 'string' && eventId.length > 0 ? ` event ${eventId}` : '';
+}
+function isDefined(value) {
+    return value !== undefined;
+}

package/dist/src/persistence/filesystem/file-lock.js

@@ -0,0 +1,91 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export async function acquireFileLock(path, options) {
+    await mkdir(dirname(path), { recursive: true });
+    const metadata = {
+        pid: process.pid,
+        acquiredAt: (options?.now ?? new Date()).toISOString(),
+        lockId: randomUUID(),
+    };
+    try {
+        return await createFileLock(path, metadata);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        return reclaimStaleFileLock(path, metadata, options);
+    }
+}
+async function createFileLock(path, metadata) {
+    const handle = await open(path, 'wx');
+    try {
+        await handle.writeFile(`${JSON.stringify(metadata)}\n`, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return { acquired: true, metadata, release: () => releaseFileLock(path, metadata) };
+}
+async function releaseFileLock(path, metadata) {
+    try {
+        const current = JSON.parse(await readFile(path, 'utf8'));
+        if (current.lockId === metadata.lockId)
+            await rm(path, { force: true });
+    }
+    catch {
+        /* already released */
+    }
+}
+async function reclaimStaleFileLock(path, metadata, options) {
+    if (options?.staleAfterMs === undefined)
+        return unavailableFileLock();
+    try {
+        const prior = JSON.parse(await readFile(path, 'utf8'));
+        if (!isStale(prior, options))
+            return unavailableFileLock();
+        if (options.staleRequiresDeadProcess && ownerMayBeAlive(options, prior.pid))
+            return unavailableFileLock();
+    }
+    catch {
+        // A corrupt or vanished lock has no trustworthy owner and can be reclaimed.
+    }
+    await rm(path, { force: true });
+    return createFileLock(path, metadata);
+}
+function isStale(prior, options) {
+    return ((options.now ?? new Date()).getTime() - Date.parse(prior.acquiredAt) >= options.staleAfterMs);
+}
+function unavailableFileLock() {
+    return { acquired: false, async release() { } };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownerMayBeAlive(options, pid) {
+    try {
+        return (options.isProcessAlive ?? isProcessAlive)(pid);
+    }
+    catch {
+        // Permission and platform-probe failures are indeterminate: never steal a live owner's lock.
+        return true;
+    }
+}
+export async function withFileLock(path, operation) {
+    const lock = await acquireFileLock(path, { staleAfterMs: 60_000 });
+    if (!lock.acquired)
+        throw new Error(`File lock is already held: ${path}`);
+    try {
+        return await operation();
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/src/persistence/filesystem/file-projection-store.js

@@ -0,0 +1,64 @@
+import { mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export class FileProjectionStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async read(namespace, key) {
+        try {
+            return JSON.parse(await readFile(this.path(namespace, key), 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async write(projection) {
+        await atomicJson(this.path(projection.namespace, projection.key), projection);
+    }
+    async list(namespace) {
+        const directory = join(this.root, 'projections', encode(namespace));
+        try {
+            const files = (await readdir(directory)).filter((file) => file.endsWith('.json')).sort();
+            return Promise.all(files.map(async (file) => JSON.parse(await readFile(join(directory, file), 'utf8'))));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    async clear(namespace) {
+        await rm(namespace === undefined
+            ? join(this.root, 'projections')
+            : join(this.root, 'projections', encode(namespace)), { recursive: true, force: true });
+    }
+    path(namespace, key) {
+        return join(this.root, 'projections', encode(namespace), `${encode(key)}.json`);
+    }
+}
+export function encode(value) {
+    if (value.length === 0 || /[\\/]/.test(value))
+        throw new Error('Storage name must not contain path separators');
+    return encodeURIComponent(value).replace(/%/g, '~').replace(/\./g, '~2E');
+}
+export async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        const handle = await open(temporary, 'wx');
+        try {
+            await handle.writeFile(`${JSON.stringify(value)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/persistence/index.js

@@ -0,0 +1,8 @@
+export * from './application/projection-runner.js';
+export * from './filesystem/file-checkpoint-store.js';
+export * from './filesystem/file-event-journal.js';
+export * from './filesystem/file-lock.js';
+export * from './filesystem/file-projection-store.js';
+export * from './memory/in-memory-checkpoint-store.js';
+export * from './memory/in-memory-event-journal.js';
+export * from './memory/in-memory-projection-store.js';

package/dist/src/persistence/memory/in-memory-checkpoint-store.js

@@ -0,0 +1,14 @@
+export class InMemoryCheckpointStore {
+    values = new Map();
+    async load(consumer) {
+        return this.values.get(consumer) ?? 0;
+    }
+    async save(consumer, position) {
+        if (position < (await this.load(consumer)))
+            throw new Error(`Checkpoint regression for ${consumer}`);
+        this.values.set(consumer, position);
+    }
+    async reset(consumer) {
+        this.values.delete(consumer);
+    }
+}

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

@@ -0,0 +1,88 @@
+import { isDeepStrictEqual } from 'node:util';
+import { WrongExpectedSequenceError } from '../../kernel/index.js';
+export class InMemoryEventJournal {
+    clock;
+    streams = new Map();
+    events = [];
+    eventIds = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    async append(stream, expectedSequence, events) {
+        validateBatch(stream, events);
+        const existingEvents = events.map((draft) => this.eventIds.get(draft.eventId));
+        this.rejectChangedEventIds(events, existingEvents);
+        if (events.length > 0 && existingEvents.every((event) => event !== undefined)) {
+            return existingEvents.map((event) => event.envelope);
+        }
+        const streamEvents = this.streams.get(streamKey(stream)) ?? [];
+        if (streamEvents.length !== expectedSequence) {
+            throw new WrongExpectedSequenceError(`Expected sequence ${expectedSequence} for ${streamKey(stream)}, actual ${streamEvents.length}`);
+        }
+        const recordedAt = this.clock.now().toISOString();
+        const appended = [];
+        for (const [index, draft] of events.entries()) {
+            const prior = existingEvents[index];
+            if (prior !== undefined) {
+                appended.push(prior.envelope);
+                continue;
+            }
+            const envelope = {
+                ...draft,
+                recordedAt,
+                sequence: streamEvents.length + 1,
+                globalPosition: this.events.length + 1,
+            };
+            streamEvents.push(envelope);
+            this.events.push(envelope);
+            this.eventIds.set(draft.eventId, { draft, envelope });
+            appended.push(envelope);
+        }
+        this.streams.set(streamKey(stream), streamEvents);
+        return appended;
+    }
+    async readStream(stream) {
+        return [...(this.streams.get(streamKey(stream)) ?? [])];
+    }
+    async readAll(afterGlobalPosition, limit = Number.POSITIVE_INFINITY) {
+        return this.events
+            .filter((event) => event.globalPosition > afterGlobalPosition)
+            .slice(0, limit);
+    }
+    async readLatest(beforeGlobalPosition = this.events.length + 1, limit = Number.POSITIVE_INFINITY) {
+        return this.events
+            .slice(0, beforeGlobalPosition - 1)
+            .slice(-limit)
+            .reverse();
+    }
+    rejectChangedEventIds(drafts, existingEvents) {
+        for (const [index, draft] of drafts.entries()) {
+            const existing = existingEvents[index];
+            if (existing !== undefined && !isDeepStrictEqual(existing.draft, draft)) {
+                throw new Error(`Event id ${draft.eventId} has already been used with different content`);
+            }
+        }
+    }
+}
+function streamKey(stream) {
+    return `${stream.kind}:${stream.id}`;
+}
+function assertSameStream(expected, actual) {
+    if (streamKey(expected) !== streamKey(actual)) {
+        throw new Error(`Event stream ${streamKey(actual)} does not match append stream ${streamKey(expected)}`);
+    }
+}
+function validateBatch(stream, drafts) {
+    const eventIds = new Map();
+    for (const draft of drafts) {
+        assertSameStream(stream, draft.stream);
+        const prior = eventIds.get(draft.eventId);
+        if (prior !== undefined) {
+            if (!isDeepStrictEqual(prior, draft)) {
+                throw new Error(`Event id ${draft.eventId} is repeated with different content in one append`);
+            }
+            throw new Error(`Event id ${draft.eventId} is repeated in one append`);
+        }
+        eventIds.set(draft.eventId, draft);
+    }
+}

package/dist/src/persistence/memory/in-memory-projection-store.js

@@ -0,0 +1,17 @@
+export class InMemoryProjectionStore {
+    values = new Map();
+    async read(namespace, key) {
+        return this.values.get(`${namespace}\0${key}`) ?? null;
+    }
+    async write(projection) {
+        this.values.set(`${projection.namespace}\0${projection.key}`, structuredClone(projection));
+    }
+    async list(namespace) {
+        return [...this.values.values()].filter((value) => value.namespace === namespace);
+    }
+    async clear(namespace) {
+        for (const [key, value] of this.values)
+            if (namespace === undefined || value.namespace === namespace)
+                this.values.delete(key);
+    }
+}

package/dist/src/resources/application/lookup-projections.js

@@ -0,0 +1,48 @@
+import { ResourceEventType, selectResourceEvent } from '../contracts/events.js';
+export const externalKeyProjectionKey = (externalKey) => `${encodeURIComponent(externalKey.adapter)}:${encodeURIComponent(externalKey.key)}`;
+export const resourcesByExternalKeyProjection = {
+    name: 'resources-by-external-key',
+    select(event) {
+        const owned = selectResourceEvent(event);
+        return owned?.eventType === ResourceEventType.ResourceDiscovered
+            ? { key: externalKeyProjectionKey(owned.payload.externalKey) }
+            : null;
+    },
+    initial: () => null,
+    project(previous, event) {
+        const owned = selectResourceEvent(event);
+        if (owned?.eventType !== ResourceEventType.ResourceDiscovered)
+            return previous;
+        return previous ?? owned.stream.id;
+    },
+};
+export const workCorrelationsProjection = {
+    name: 'work-correlations',
+    select(event) {
+        const owned = selectResourceEvent(event);
+        if (owned?.eventType === ResourceEventType.WorkCorrelationEstablished)
+            return { key: owned.payload.workItemId };
+        if (owned?.eventType === ResourceEventType.WorkCorrelationRetracted)
+            return { key: owned.payload.workItemId };
+        return null;
+    },
+    initial: () => [],
+    project(previous, event) {
+        const owned = selectResourceEvent(event);
+        if (owned?.eventType === ResourceEventType.WorkCorrelationEstablished) {
+            const correlation = {
+                resourceId: owned.stream.id,
+                workItemId: owned.payload.workItemId,
+                role: owned.payload.role,
+                provenance: owned.payload.provenance,
+                establishedByEventId: owned.eventId,
+            };
+            return previous.some((value) => value.resourceId === correlation.resourceId)
+                ? previous
+                : [...previous, correlation];
+        }
+        if (owned?.eventType === ResourceEventType.WorkCorrelationRetracted)
+            return previous.filter((value) => value.resourceId !== owned.stream.id);
+        return previous;
+    },
+};

package/dist/src/resources/application/resource-lookup.js

@@ -0,0 +1,16 @@
+import { externalKeyProjectionKey, resourcesByExternalKeyProjection, workCorrelationsProjection, } from './lookup-projections.js';
+export function createResourceLookup(dependencies) {
+    const seeded = async (definition, key) => {
+        const stored = await dependencies.projections.read(definition.name, key);
+        let value = stored?.value ?? definition.initial(key);
+        for (const event of await dependencies.journal.readAll(stored?.lastGlobalPosition ?? 0)) {
+            if (definition.select(event)?.key === key)
+                value = definition.project(value, event);
+        }
+        return value;
+    };
+    return {
+        resourceIdForExternalKey: (externalKey) => seeded(resourcesByExternalKeyProjection, externalKeyProjectionKey(externalKey)),
+        correlationsForWork: (workItemId) => seeded(workCorrelationsProjection, workItemId),
+    };
+}

package/dist/src/resources/application/resource-projections.js

@@ -0,0 +1,81 @@
+import { ResourceEventType, selectResourceEvent } from '../contracts/events.js';
+export const resourceProjection = {
+    name: 'resources',
+    select(event) {
+        const owned = selectResourceEvent(event);
+        return owned === null ? null : { key: owned.stream.id };
+    },
+    initial: () => null,
+    project(previous, event) {
+        const owned = selectResourceEvent(event);
+        if (owned === null)
+            return previous;
+        switch (owned.eventType) {
+            case ResourceEventType.ResourceDiscovered:
+                return {
+                    resourceId: owned.stream.id,
+                    kind: owned.payload.kind,
+                    externalKey: owned.payload.externalKey,
+                    capabilities: owned.payload.capabilities,
+                    ...(owned.payload.revision === undefined ? {} : { revision: owned.payload.revision }),
+                    ...(owned.payload.title === undefined ? {} : { title: owned.payload.title }),
+                };
+            case ResourceEventType.ResourceRevisionObserved:
+                return previous === null ? previous : { ...previous, revision: owned.payload.revision };
+            case ResourceEventType.WorkCorrelationConflicted:
+                return previous === null
+                    ? previous
+                    : {
+                        ...previous,
+                        primaryCorrelationConflict: {
+                            attemptedWorkItemId: owned.payload.workItemId,
+                            existingWorkItemId: owned.payload.existingWorkItemId,
+                            eventId: owned.eventId,
+                        },
+                    };
+            case ResourceEventType.WorkCorrelationEstablished:
+            case ResourceEventType.WorkCorrelationRetracted:
+                return previous;
+            default:
+                return assertNever(owned);
+        }
+    },
+};
+export const resourceCorrelationProjection = {
+    name: 'resource-correlations',
+    select(event) {
+        const owned = selectResourceEvent(event);
+        return owned === null ? null : { key: owned.stream.id };
+    },
+    initial: () => [],
+    project(previous, event) {
+        const owned = selectResourceEvent(event);
+        if (owned === null)
+            return previous;
+        switch (owned.eventType) {
+            case ResourceEventType.WorkCorrelationEstablished: {
+                const correlation = {
+                    resourceId: owned.stream.id,
+                    workItemId: owned.payload.workItemId,
+                    role: owned.payload.role,
+                    provenance: owned.payload.provenance,
+                    establishedByEventId: owned.eventId,
+                };
+                return previous.some((value) => value.workItemId === correlation.workItemId)
+                    ? previous
+                    : [...previous, correlation];
+            }
+            case ResourceEventType.WorkCorrelationRetracted:
+                return previous.filter((value) => value.workItemId !== owned.payload.workItemId);
+            case ResourceEventType.ResourceDiscovered:
+            case ResourceEventType.ResourceRevisionObserved:
+            case ResourceEventType.WorkCorrelationConflicted:
+                return previous;
+            default:
+                return assertNever(owned);
+        }
+    },
+};
+function assertNever(value) {
+    throw new Error(`Unhandled Resource event: ${JSON.stringify(value)}`);
+}

package/dist/src/resources/application/resource-repository.js

@@ -0,0 +1,18 @@
+import { decodeResourceEvent, selectResourceEvent, } from '../contracts/events.js';
+import { resourceStream } from '../contracts/streams.js';
+import { foldResource } from '../domain/resource.js';
+export class ResourceRepository {
+    journal;
+    constructor(journal) {
+        this.journal = journal;
+    }
+    async load(resourceId) {
+        const events = await this.journal.readStream(resourceStream(resourceId));
+        const owned = events.map(selectResourceEvent).filter((event) => event !== null);
+        return { sequence: events.length, resource: foldResource(owned) };
+    }
+    async append(resourceId, expectedSequence, drafts) {
+        const events = await this.journal.append(resourceStream(resourceId), expectedSequence, drafts);
+        return events.map(decodeResourceEvent);
+    }
+}