@atolis-hq/wake 0.1.0

package/dist/src/domain/sources.js

@@ -0,0 +1,16 @@
+/**
+ * Names the configured ticket source. This is one decision with several
+ * consumers that MUST agree: main.ts names the source it wires into the fan-in
+ * and the sink router, while the UI builds `<provider>:issue:<repo>#<n>` URIs
+ * to resolve tickets against the index those same events registered. If the
+ * two ever disagreed, the UI would resolve against a provider nothing had
+ * registered, miss, and report live work items as missing.
+ *
+ * It lives here, and not inline at each call site, because adding a third
+ * source means changing this one function rather than finding every ternary —
+ * source-pluggability is the point of the adapter seams, so the choice must
+ * not be duplicated across them.
+ */
+export function configuredTicketSource(config) {
+    return config.sources.github.enabled ? 'github' : 'fake-ticketing';
+}

package/dist/src/domain/stages.js

@@ -0,0 +1,39 @@
+export const stageValues = [
+    'queue',
+    'done',
+];
+export const doneRunnerSentinel = 'DONE';
+export const blockedRunnerSentinel = 'BLOCKED';
+export const failedRunnerSentinel = 'FAILED';
+export const awaitingApprovalRunnerSentinel = 'AWAITING_APPROVAL';
+export const runnerSentinelValues = [
+    doneRunnerSentinel,
+    blockedRunnerSentinel,
+    failedRunnerSentinel,
+    awaitingApprovalRunnerSentinel,
+];
+export const terminalStageValues = ['done'];
+export function isTerminalStage(stage) {
+    return terminalStageValues.includes(stage);
+}
+export const wakeStageLabelPrefix = 'wake:stage.';
+export function stageLabelForStage(stage) {
+    return `${wakeStageLabelPrefix}${stage}`;
+}
+export function stageFromStageLabel(label, configuredStages = stageValues) {
+    if (!label.startsWith(wakeStageLabelPrefix)) {
+        return undefined;
+    }
+    const stage = label.slice(wakeStageLabelPrefix.length);
+    return new Set(configuredStages).has(stage) ? stage : undefined;
+}
+export function stageFromLabels(labels, configuredStages = stageValues) {
+    const stages = new Set();
+    for (const label of labels) {
+        const stage = stageFromStageLabel(label, configuredStages);
+        if (stage !== undefined) {
+            stages.add(stage);
+        }
+    }
+    return stages.size === 1 ? [...stages][0] : undefined;
+}

package/dist/src/domain/types.js

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

package/dist/src/domain/workflows.js

@@ -0,0 +1,83 @@
+import { stageLabelForStage } from './stages.js';
+export const universalQueueStage = 'queue';
+export const universalDoneStage = 'done';
+export const workflowChangedBlockReason = 'workflow-changed';
+export const builtInDefaultWorkflowDefinition = {
+    stages: {
+        refine: {
+            action: 'refine',
+            workspace: 'read-only',
+            tier: 'light',
+            onDone: 'implement',
+        },
+        implement: {
+            action: 'implement',
+            workspace: 'branch',
+            tier: 'standard',
+            onDone: 'done',
+        },
+    },
+};
+export function configuredWorkflowNames(config) {
+    return Object.keys(config.workflows);
+}
+export function defaultWorkflowName(config) {
+    const [name] = configuredWorkflowNames(config);
+    if (name === undefined) {
+        throw new Error('Wake config must define at least one workflow.');
+    }
+    return name;
+}
+export function workflowForProjection(projection, config) {
+    const workflowName = workflowNameForProjection(projection, config);
+    return config.workflows[workflowName] ?? null;
+}
+export function workflowNameForProjection(projection, config) {
+    const context = projection.context;
+    return (typeof context.workflow === 'string'
+        ? context.workflow
+        : defaultWorkflowName(config));
+}
+export function configuredStageNames(workflow) {
+    return Object.keys(workflow.stages);
+}
+export function workflowStageVocabulary(workflow) {
+    return [universalQueueStage, ...configuredStageNames(workflow), universalDoneStage];
+}
+export function stageLabelsForWorkflow(workflow) {
+    return workflowStageVocabulary(workflow).map((stage) => stageLabelForStage(stage));
+}
+export function isKnownWorkflowStage(stage, workflow) {
+    return workflowStageVocabulary(workflow).includes(stage);
+}
+export function entryStage(workflow) {
+    return workflow.entryStage ?? configuredStageNames(workflow)[0];
+}
+export function stageAfterQueue(workflow) {
+    return entryStage(workflow);
+}
+export function chooseAction(projection, workflow) {
+    const stage = projection.wake.stage === universalQueueStage
+        ? stageAfterQueue(workflow)
+        : projection.wake.stage;
+    const definition = workflow.stages[stage];
+    if (definition === undefined || stage === universalDoneStage) {
+        return null;
+    }
+    return {
+        action: definition.action ?? stage,
+        workspace: definition.workspace,
+        routing: {
+            ...(definition.tier === undefined ? {} : { tier: definition.tier }),
+            ...(definition.runner === undefined ? {} : { runner: definition.runner }),
+        },
+        stage,
+    };
+}
+export function nextStage(stage, sentinel, workflow) {
+    if (sentinel === 'BLOCKED' || sentinel === 'FAILED' || sentinel === 'AWAITING_APPROVAL') {
+        return null;
+    }
+    const runnableStage = stage === universalQueueStage ? stageAfterQueue(workflow) : stage;
+    return workflow.stages[runnableStage]?.onDone ?? null;
+}

package/dist/src/lib/clock.js

@@ -0,0 +1,5 @@
+export const systemClock = {
+    now() {
+        return new Date();
+    },
+};

package/dist/src/lib/event-log.js

@@ -0,0 +1,21 @@
+export function createEventEnvelope(input) {
+    return {
+        schemaVersion: 1,
+        ...input,
+    };
+}
+/**
+ * Builds a source event with no workItemKey. Sources do not self-key; the
+ * resolver in tick-runner stamps the canonical key between poll and append
+ * (spec D1).
+ *
+ * The return type is spelled structurally rather than importing
+ * core/contracts' `UnkeyedEventEnvelope` — it is the identical type, and lib/
+ * must not depend on core/.
+ */
+export function createUnkeyedEventEnvelope(input) {
+    return {
+        schemaVersion: 1,
+        ...input,
+    };
+}

package/dist/src/lib/json-file.js

@@ -0,0 +1,23 @@
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+export async function writeJsonFile(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+export async function readJsonFile(path) {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+}
+export async function appendJsonLine(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, `${JSON.stringify(value)}\n`, 'utf8');
+}

package/dist/src/lib/lock.js

@@ -0,0 +1,118 @@
+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function parseLockMetadata(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object') {
+            return null;
+        }
+        const record = parsed;
+        if (typeof record.pid !== 'number' ||
+            !Number.isInteger(record.pid) ||
+            typeof record.acquiredAt !== 'string') {
+            return null;
+        }
+        const acquiredAtMs = Date.parse(record.acquiredAt);
+        if (!Number.isFinite(acquiredAtMs)) {
+            return null;
+        }
+        return {
+            pid: record.pid,
+            acquiredAt: record.acquiredAt,
+            ...(typeof record.lockId === 'string' ? { lockId: record.lockId } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ESRCH') {
+            return false;
+        }
+        return true;
+    }
+}
+async function readLockMetadata(path) {
+    try {
+        return parseLockMetadata(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function lockIsStale(path, staleAfterMs, now) {
+    const metadata = await readLockMetadata(path);
+    if (metadata === null) {
+        return true;
+    }
+    const ageMs = now.getTime() - Date.parse(metadata.acquiredAt);
+    return ageMs >= staleAfterMs || !isPidAlive(metadata.pid);
+}
+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(),
+    };
+    async function tryAcquire() {
+        const tempPath = join(dirname(path), `.tick-lock-${metadata.lockId}.tmp`);
+        await writeFile(tempPath, `${JSON.stringify(metadata)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+        });
+        try {
+            await link(tempPath, path);
+        }
+        finally {
+            await rm(tempPath, { force: true });
+        }
+        return {
+            acquired: true,
+            metadata,
+            async release() {
+                const current = await readLockMetadata(path);
+                if (current?.pid === metadata.pid &&
+                    current.acquiredAt === metadata.acquiredAt &&
+                    current.lockId === metadata.lockId) {
+                    await rm(path, { force: true });
+                }
+            },
+        };
+    }
+    try {
+        return await tryAcquire();
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            if (options?.staleAfterMs !== undefined &&
+                await lockIsStale(path, options.staleAfterMs, options.now ?? new Date())) {
+                await rm(path, { force: true });
+                try {
+                    return await tryAcquire();
+                }
+                catch (retryError) {
+                    if (retryError.code !== 'EEXIST') {
+                        throw retryError;
+                    }
+                }
+            }
+            return {
+                acquired: false,
+                async release() { },
+            };
+        }
+        throw error;
+    }
+}

package/dist/src/lib/paths.js

@@ -0,0 +1,44 @@
+import { join } from 'node:path';
+export function sanitizeRepo(repo) {
+    return repo.replace(/[\\/]/g, '__');
+}
+export function sanitizePathKey(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '__');
+}
+export function createWakePaths(wakeRoot) {
+    return {
+        wakeRoot,
+        containerHomeRoot: join(wakeRoot, 'container-home'),
+        configFile: join(wakeRoot, 'config.json'),
+        ledgerFile: join(wakeRoot, 'ledger.json'),
+        pauseFile: join(wakeRoot, 'PAUSE'),
+        tickLockFile: join(wakeRoot, 'locks', 'tick.lock'),
+        runnerLockFile: join(wakeRoot, 'locks', 'runner.lock'),
+        issueFixtureFile: join(wakeRoot, 'fixtures', 'issues.json'),
+        workspaceRoot: join(wakeRoot, 'workspaces'),
+        transcriptsRoot: join(wakeRoot, 'transcripts'),
+        reposRoot: join(wakeRoot, 'repos'),
+        repoRoot: (repo) => join(wakeRoot, 'repos', sanitizeRepo(repo)),
+        sourceStateRoot: join(wakeRoot, 'sources'),
+        // Keyed on the minted work id, which is filename-safe by construction
+        // (src/lib/work-id.ts) — hence no sanitizePathKey here. No durable path
+        // embeds a provider, repo, or issue segment (spec §3).
+        workItemStateFile: (workId) => join(wakeRoot, 'state', `${workId}.json`),
+        archivedWorkItemStateFile: (workId) => join(wakeRoot, 'state', 'archive', `${workId}.json`),
+        sourceStateFile: (source, key) => join(wakeRoot, 'sources', sanitizePathKey(source), `${sanitizePathKey(key)}.json`),
+        runFile: (runId) => join(wakeRoot, 'runs', `${runId}.json`),
+        runDateFile: (date, runId) => join(wakeRoot, 'runs', 'by-date', date, `${runId}.json`),
+        eventFile: (date) => join(wakeRoot, 'events', `${date}.jsonl`),
+        eventEnvelopeFile: (eventId) => join(wakeRoot, 'events-by-id', `${sanitizePathKey(eventId)}.json`),
+        logFile: (date) => join(wakeRoot, 'logs', `${date}.log`),
+        // Workspaces and transcripts are ephemeral scratch rather than durable
+        // state, but they re-key to the work id anyway: they are 1:1 with a work
+        // item, not a ticket, and a ticket-shaped path here would preserve the
+        // second ticket-shaped identity this change exists to remove (spec §3).
+        workspaceDir: (workId) => join(wakeRoot, 'workspaces', workId),
+        transcriptWorkDir: (workId) => join(wakeRoot, 'transcripts', workId),
+        transcriptSessionDir: (workId, sessionKey) => join(wakeRoot, 'transcripts', workId, sanitizePathKey(sessionKey)),
+        resourceIndexRoot: join(wakeRoot, 'state', 'index'),
+        resourceIndexShardFile: (shard) => join(wakeRoot, 'state', 'index', `${shard}.json`),
+    };
+}

package/dist/src/lib/work-id.js

@@ -0,0 +1,19 @@
+import { ulid } from 'ulid';
+/** Crockford base32 alphabet, as used by ULID: no I, L, O, or U. */
+const WORK_ID_PATTERN = /^work-[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * Mints a provider-independent work item identifier.
+ *
+ * Work ids name the work, never any surface that represents it: a ticket key
+ * is not a stable name for work (issue transfer renumbers it, and work can
+ * split or merge). See docs/superpowers/specs/2026-07-16-work-identity-correlation-design.md (D3).
+ *
+ * ULIDs sort chronologically as strings, so state/ listings are naturally
+ * ordered by mint time, and are filename-safe with no escaping.
+ */
+export function createWorkId() {
+    return `work-${ulid()}`;
+}
+export function isWorkId(value) {
+    return WORK_ID_PATTERN.test(value);
+}