@atolis-hq/wake 0.1.0

package/dist/src/domain/branch-naming.js

@@ -0,0 +1,14 @@
+/**
+ * Wake's branch-naming convention for a work item's implementation branch,
+ * keyed on the originating ticket's issue number (spec D2 — human-readable,
+ * not the opaque work id).
+ *
+ * Lives in domain/ (not the git adapter) because it is pure vocabulary with
+ * no IO: `core/` needs it to compute the branch a run should have pushed to
+ * when verifying agent-reported artifacts, and `core/` may import domain/
+ * but never a concrete adapter directly. `adapters/git/git-workspace-manager.ts`
+ * re-exports this for its own callers so existing imports keep working.
+ */
+export function branchNameForIssue(issueNumber) {
+    return `wake/issue-${issueNumber}`;
+}

package/dist/src/domain/resource-uri.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/**
+ * Resource URI grammar: `<provider>:<kind>:<locator>`.
+ *
+ * `provider` matches the adapter's registered source/sink name; `kind` uses
+ * the provider's native vocabulary (`github:pr:…` but `gitlab:mr:…`). The
+ * locator grammar is provider-specific and opaque to core — everything after
+ * the second colon is matched as a single blob and never inspected here.
+ * Core compares URIs for equality only (ADR 0001 §1).
+ */
+const RESOURCE_URI_PATTERN = /^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*:.+$/;
+export const resourceUriSchema = z
+    .string()
+    .regex(RESOURCE_URI_PATTERN, 'must match <provider>:<kind>:<locator>');
+export function buildResourceUri(provider, kind, locator) {
+    return resourceUriSchema.parse(`${provider}:${kind}:${locator}`);
+}
+/**
+ * Wake-owned relationship vocabulary — the graph edge type, deliberately
+ * independent of the URI's provider-native `kind`. A new provider adds URI
+ * kinds, never new roles; a new role is a Wake modelling decision.
+ */
+export const correlationRoleSchema = z.enum([
+    'representation',
+    'implementation',
+    'discussion',
+    'review',
+    'documentation',
+    'decision',
+]);
+/** Exactly one work item may hold `primary` per resource URI (ADR 0001 §2). */
+export const correlationRelationSchema = z.enum(['primary', 'secondary']);
+export const correlationProvenanceSchema = z.enum([
+    'wake-created',
+    'agent-reported',
+    'detected',
+    'operator-declared',
+]);

package/dist/src/domain/runner-routing.js

@@ -0,0 +1,108 @@
+import { defaultWorkflowName } from './workflows.js';
+export function maxConfiguredRunnerTimeoutMs(config) {
+    const activeRunnerNames = new Set(Object.values(config.tiers).flatMap((candidates) => candidates));
+    for (const workflow of Object.values(config.workflows)) {
+        for (const stageRoute of Object.values(workflow.stages)) {
+            if (stageRoute.runner !== undefined) {
+                activeRunnerNames.add(stageRoute.runner);
+            }
+        }
+    }
+    for (const stageRoute of Object.values(config.stages)) {
+        if (stageRoute.runner !== undefined) {
+            activeRunnerNames.add(stageRoute.runner);
+        }
+    }
+    const registryTimeouts = [...activeRunnerNames]
+        .map((name) => config.runners[name])
+        .map((entry) => entry === undefined || entry.kind === 'fake' ? undefined : entry.timeoutMs)
+        .filter((timeout) => timeout !== undefined);
+    return registryTimeouts.length > 0 ? Math.max(...registryTimeouts) : Infinity;
+}
+// How often an 'estimated' pause (exponential-backoff guess, not a reset time
+// the CLI actually reported) gets a recovery probe: a real attempt let through
+// early in case the guess overshot and quota actually reset sooner. 'reported'
+// pauses (an actual reset time) are trusted for their full duration - no
+// probing needed since we already know when they clear.
+const recoveryProbeIntervalMs = 15 * 60_000;
+function isRunnerPaused(input) {
+    const health = input.ledger?.runners?.[input.runnerName];
+    const pausedUntil = health?.pausedUntil;
+    if (pausedUntil === undefined || Date.parse(pausedUntil) <= input.now.getTime()) {
+        return { paused: false, isProbe: false };
+    }
+    if (health?.pausedUntilSource === 'estimated' && health.lastFailureAt !== undefined) {
+        const sinceLastFailureMs = input.now.getTime() - Date.parse(health.lastFailureAt);
+        if (sinceLastFailureMs >= recoveryProbeIntervalMs) {
+            return { paused: false, isProbe: true };
+        }
+    }
+    return { paused: true, isProbe: false };
+}
+/**
+ * Resolves which named runner should execute a stage/action.
+ *
+ * A stage pinned directly to a runner (`stages[stage].runner`) has no
+ * fallback list, so it always returns that runner regardless of health.
+ * A stage routed through a `tier` walks the tier's ordered candidates and
+ * skips any currently quota-paused per the ledger (#67 sideways fallback),
+ * returning `null` only when every candidate in the tier is paused - callers
+ * should treat that as "nothing to do this tick", not a config error. Once a
+ * higher-priority candidate's pause expires, it is preferred again on the
+ * next call, which is the "rotation" back to the primary runner.
+ */
+export function resolveRunnerRouting(input) {
+    const workflowName = input.workflowName ?? defaultWorkflowName(input.config);
+    const workflow = input.config.workflows[workflowName];
+    if (workflow === undefined) {
+        throw new Error(`Unknown workflow "${workflowName}".`);
+    }
+    const stageRoute = workflow.stages[input.stage];
+    if (stageRoute?.runner !== undefined) {
+        const entry = input.config.runners[stageRoute.runner];
+        if (entry === undefined) {
+            throw new Error(`Stage ${input.stage} pins unknown runner "${stageRoute.runner}".`);
+        }
+        return {
+            runnerName: stageRoute.runner,
+            runnerKind: entry.kind,
+            ...(stageRoute.tier === undefined ? {} : { tier: stageRoute.tier }),
+            reason: `stage ${input.stage} pins runner ${stageRoute.runner}`,
+        };
+    }
+    const tier = stageRoute?.tier ?? input.config.defaultTier;
+    const candidates = input.config.tiers[tier];
+    if (candidates === undefined || candidates.length === 0) {
+        throw new Error(`Stage ${input.stage} routes to unknown or empty tier "${tier}".`);
+    }
+    const now = input.now ?? new Date();
+    let selected;
+    for (const candidate of candidates) {
+        const status = isRunnerPaused({ runnerName: candidate, ledger: input.ledger, now });
+        if (!status.paused) {
+            selected = { runnerName: candidate, isProbe: status.isProbe };
+            break;
+        }
+    }
+    if (selected === undefined) {
+        return null;
+    }
+    const { runnerName, isProbe } = selected;
+    const entry = input.config.runners[runnerName];
+    if (entry === undefined) {
+        throw new Error(`Tier ${tier} references unknown runner "${runnerName}".`);
+    }
+    const isFallback = runnerName !== candidates[0];
+    return {
+        runnerName,
+        runnerKind: entry.kind,
+        tier,
+        reason: isProbe
+            ? `tier ${tier} recovery probe on ${runnerName} (estimated pause not yet elapsed)`
+            : isFallback
+                ? `tier ${tier} fell back to ${runnerName} (higher-priority candidates paused)`
+                : stageRoute?.tier === undefined
+                    ? `defaultTier ${tier} selected runner ${runnerName}`
+                    : `stage ${input.stage} tier ${tier} selected runner ${runnerName}`,
+    };
+}