@jini-ai/daemon 0.1.0

package/dist/legacy-data-migration.js

@@ -0,0 +1,239 @@
+/**
+ * @module legacy-data-migration
+ *
+ * A one-shot, idempotent, host-configured migrator for moving a daemon's
+ * data root from one location to another (e.g. a pre-packaging install that
+ * ran out of a repo checkout, moved to a per-namespace directory under an
+ * OS user-data location). The mechanism — refuse-if-missing-proof,
+ * refuse-if-destination-populated, refuse-if-already-migrated, reject
+ * symlinks, stage-then-atomically-promote, rollback-on-any-failure — is
+ * product-neutral; the *shape* of a data root's payload (which files/dirs
+ * constitute "real data", and which single entry proves a directory holds
+ * real payload rather than an empty scaffold) is host-supplied via
+ * {@link LegacyDataMigrationConfig}, never hardcoded here.
+ *
+ * Sync by design: intended to run at daemon startup before any database
+ * connection opens, so it can't race a concurrent open of the destination.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DEFAULT_MARKER_FILE = '.migrated-from';
+/**
+ * Thrown when `legacyDir` is explicitly set but is not a usable legacy data
+ * dir, or the new `dataDir` is already populated and would be merged into.
+ * Failing loud here is the point: a silent skip trains an operator to
+ * assume a migration ran when it didn't.
+ */
+export class LegacyMigrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LegacyMigrationError';
+    }
+}
+function isExistingDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isExistingFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true when `dataDir` looks like a fresh / never-used data root:
+ * either the directory does not exist, or it exists but does not contain
+ * the configured `proofEntry` as a file. Deliberately not just "the
+ * directory is empty" — a packaged install commonly pre-creates an empty
+ * `dataDir` before the daemon ever boots, so emptiness alone is not proof
+ * of "no prior data."
+ *
+ * @param dataDir - The data root to check.
+ * @param config - The host's payload/proof-entry configuration.
+ */
+export function dataDirIsEmptyOrFresh(dataDir, config) {
+    if (!isExistingDir(dataDir))
+        return true;
+    return !isExistingFile(path.join(dataDir, config.proofEntry));
+}
+/**
+ * Returns true when `legacyDir` contains a payload worth migrating: it
+ * exists and its configured `proofEntry` exists as a file.
+ *
+ * @param legacyDir - The candidate legacy data directory.
+ * @param config - The host's payload/proof-entry configuration.
+ */
+export function legacyDirHasPayload(legacyDir, config) {
+    if (!isExistingDir(legacyDir))
+        return false;
+    return isExistingFile(path.join(legacyDir, config.proofEntry));
+}
+/**
+ * Returns the list of configured payload entries that already exist under
+ * `dataDir`. Migration refuses to merge on top of any of them — a database
+ * file/WAL pair or a project tree cannot be safely interleaved with a
+ * foreign counterpart, and a partial overlay is worse than no migration.
+ *
+ * @param dataDir - The data root to check.
+ * @param config - The host's payload/proof-entry configuration.
+ */
+export function dataDirHasExistingPayload(dataDir, config) {
+    if (!isExistingDir(dataDir))
+        return [];
+    return config.payloadEntries.filter((entry) => fs.existsSync(path.join(dataDir, entry)));
+}
+/**
+ * Walk a payload subtree and refuse to copy if any node is a symlink — a
+ * preserved symlink would let a downstream reader escape the data root.
+ * @internal
+ */
+function assertNoSymlinks(srcRoot, displayPath = srcRoot) {
+    const stat = fs.lstatSync(srcRoot);
+    if (stat.isSymbolicLink()) {
+        throw new LegacyMigrationError('symlink_in_payload', `legacy payload contains a symlink at "${displayPath}"; refusing to migrate`);
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const child of fs.readdirSync(srcRoot)) {
+        assertNoSymlinks(path.join(srcRoot, child), path.join(displayPath, child));
+    }
+}
+/** Stage every present payload entry into `stagingDir`. Returns the entries actually copied. @internal */
+function stagePayload(legacyDir, stagingDir, payloadEntries) {
+    fs.mkdirSync(stagingDir, { recursive: true });
+    const copied = [];
+    for (const entry of payloadEntries) {
+        const src = path.join(legacyDir, entry);
+        if (!fs.existsSync(src))
+            continue;
+        assertNoSymlinks(src);
+        const dst = path.join(stagingDir, entry);
+        fs.cpSync(src, dst, { recursive: true, force: true, errorOnExist: false });
+        copied.push(entry);
+    }
+    return copied;
+}
+/**
+ * Move staged payload entries into the final `dataDir`. Each entry is moved
+ * with `renameSync` (atomic on the same filesystem); a cross-device rename
+ * falls back to copy + remove. Rollback-safe in two layers: the copy
+ * fallback removes a partial destination on its own failure, and the outer
+ * loop removes every entry it already promoted before rethrowing.
+ *
+ * @param stagingDir - The sibling staging directory holding the copied payload.
+ * @param dataDir - The destination data root.
+ * @param entries - The payload entries to promote.
+ * @returns The entries that were placed into `dataDir` before any failure.
+ */
+export function promoteStaged(stagingDir, dataDir, entries) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const promoted = [];
+    try {
+        for (const entry of entries) {
+            const src = path.join(stagingDir, entry);
+            const dst = path.join(dataDir, entry);
+            try {
+                fs.renameSync(src, dst);
+            }
+            catch {
+                try {
+                    fs.cpSync(src, dst, { recursive: true, force: true, errorOnExist: false });
+                    fs.rmSync(src, { recursive: true, force: true });
+                }
+                catch (cpErr) {
+                    fs.rmSync(dst, { recursive: true, force: true });
+                    throw cpErr;
+                }
+            }
+            promoted.push(entry);
+        }
+    }
+    catch (err) {
+        rollbackPromoted(dataDir, promoted);
+        throw err;
+    }
+    return promoted;
+}
+function rollbackPromoted(dataDir, promoted) {
+    for (const entry of promoted) {
+        fs.rmSync(path.join(dataDir, entry), { recursive: true, force: true });
+    }
+}
+function writeMarkerDefault(dataDir, legacyDir, markerFile) {
+    const marker = path.join(dataDir, markerFile);
+    const temp = `${marker}.tmp-${process.pid}-${Date.now()}`;
+    const payload = JSON.stringify({ legacyDir: path.resolve(legacyDir), migratedAt: new Date().toISOString() }, null, 2);
+    try {
+        fs.writeFileSync(temp, `${payload}\n`, 'utf8');
+        fs.renameSync(temp, marker);
+    }
+    catch (err) {
+        fs.rmSync(temp, { force: true });
+        throw err;
+    }
+}
+/**
+ * One-shot, idempotent legacy data migrator. Synchronous so it can run at
+ * module import time before a database connection opens. Throws
+ * {@link LegacyMigrationError} on operator-actionable failures (env set but
+ * path invalid; `dataDir` already populated; symlink in payload).
+ *
+ * @param options - Legacy/current dir paths plus the host's payload config.
+ * @returns The migration outcome (`noop` when unconfigured, `skipped` when
+ *   already migrated, `migrated` with the copied entry list otherwise).
+ */
+export function migrateLegacyDataDirSync(options) {
+    const log = options.logger ?? { info: (m) => console.log(`[jini-migrate] ${m}`) };
+    const markerFile = options.markerFile ?? DEFAULT_MARKER_FILE;
+    const raw = options.legacyDir;
+    if (raw === undefined || raw.length === 0) {
+        return { status: 'noop', reason: 'legacy data dir not configured' };
+    }
+    const legacyDir = path.resolve(raw);
+    const dataDir = path.resolve(options.dataDir);
+    if (legacyDir === dataDir) {
+        return { status: 'noop', reason: 'legacy data dir equals current data dir' };
+    }
+    // Marker check runs before legacyDirHasPayload on purpose: once a
+    // migration has succeeded, the marker is the canonical "do not touch"
+    // signal, even if the legacy source is later moved or deleted.
+    const markerPath = path.join(dataDir, markerFile);
+    if (fs.existsSync(markerPath)) {
+        return { status: 'skipped', reason: 'migration marker already present' };
+    }
+    if (!legacyDirHasPayload(legacyDir, options)) {
+        throw new LegacyMigrationError('legacy_dir_invalid', `legacy data dir "${legacyDir}" is not a usable legacy data dir (expected "${options.proofEntry}" directly inside it).`);
+    }
+    const existing = dataDirHasExistingPayload(dataDir, options);
+    if (existing.length > 0) {
+        throw new LegacyMigrationError('data_dir_not_empty', `data dir "${dataDir}" already contains payload entries (${existing.join(', ')}); refusing to merge legacy data on top. Move the existing data aside or pick a fresh data root before retrying.`);
+    }
+    log.info(`migrating legacy data from "${legacyDir}" to "${dataDir}"`);
+    fs.mkdirSync(path.dirname(dataDir), { recursive: true });
+    const stagingDir = path.join(path.dirname(dataDir), `${path.basename(dataDir)}.migrate-${process.pid}-${Date.now()}`);
+    let copied;
+    let promoted = [];
+    try {
+        copied = stagePayload(legacyDir, stagingDir, options.payloadEntries);
+        promoted = promoteStaged(stagingDir, dataDir, copied);
+        (options.writeMarker ?? writeMarkerDefault)(dataDir, legacyDir, markerFile);
+    }
+    catch (err) {
+        rollbackPromoted(dataDir, promoted);
+        fs.rmSync(markerPath, { force: true });
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+        throw err;
+    }
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    log.info(`migration complete: copied ${copied.length} entr${copied.length === 1 ? 'y' : 'ies'} (${copied.join(', ')})`);
+    return { status: 'migrated', reason: 'copied legacy payload', copied };
+}
+//# sourceMappingURL=legacy-data-migration.js.map

package/dist/legacy-data-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-data-migration.js","sourceRoot":"","sources":["../src/legacy-data-migration.ts"],"names":[],"mappings":"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"}

package/dist/routines/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module routines
+ *
+ * The routine scheduler ({@link ./scheduler.js}'s `RoutineService`, `./schedule.js`'s DST-safe
+ * wall-clock math) plus its HTTP-facing CRUD + run-history counterpart ({@link ./routine-store.js}'s
+ * `RoutineStore`). See `../../source-map.md`'s dated routines section for full provenance.
+ */
+export * from './types.js';
+export * from './schedule.js';
+export * from './scheduler.js';
+export * from './routine-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/routines/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routines/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/routines/index.js

@@ -0,0 +1,12 @@
+/**
+ * @module routines
+ *
+ * The routine scheduler ({@link ./scheduler.js}'s `RoutineService`, `./schedule.js`'s DST-safe
+ * wall-clock math) plus its HTTP-facing CRUD + run-history counterpart ({@link ./routine-store.js}'s
+ * `RoutineStore`). See `../../source-map.md`'s dated routines section for full provenance.
+ */
+export * from './types.js';
+export * from './schedule.js';
+export * from './scheduler.js';
+export * from './routine-store.js';
+//# sourceMappingURL=index.js.map

package/dist/routines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routines/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/routines/routine-store.d.ts

@@ -0,0 +1,77 @@
+import type { Routine, RoutineContextSelection, RoutineProjectTarget, RoutineRun, RoutineSchedule } from './types.js';
+export interface RoutineCreateInput {
+    readonly name: string;
+    readonly prompt: string;
+    readonly schedule: RoutineSchedule;
+    readonly target: RoutineProjectTarget;
+    readonly skillId?: string | null;
+    readonly agentId?: string | null;
+    readonly context?: RoutineContextSelection;
+    /** @default true */
+    readonly enabled?: boolean;
+}
+export interface RoutineUpdateInput {
+    readonly name?: string;
+    readonly prompt?: string;
+    readonly schedule?: RoutineSchedule;
+    readonly target?: RoutineProjectTarget;
+    readonly skillId?: string | null;
+    readonly agentId?: string | null;
+    readonly context?: RoutineContextSelection;
+    readonly enabled?: boolean;
+}
+/**
+ * Storage-agnostic CRUD + read-only run-history port for routines. `@jini-ai/daemon` ships
+ * {@link createInMemoryRoutineStore} as the reference implementation; a durable adapter
+ * (`@jini-ai/sqlite`, future work) implements the same interface.
+ */
+export interface RoutineStore {
+    list(): Promise<readonly Routine[]>;
+    /** Returns `null` when no routine with `id` exists — never throws for a missing id. */
+    get(id: string): Promise<Routine | null>;
+    /** Assigns and returns the new routine's `id` — never supplied by the caller, matching `EventLog.append`'s cursor-assignment precedent. */
+    create(input: RoutineCreateInput): Promise<Routine>;
+    /** Applies a partial patch and returns the updated routine, or `null` if `id` does not exist. */
+    update(id: string, patch: RoutineUpdateInput): Promise<Routine | null>;
+    /** Returns whether a routine with `id` existed (and was removed). */
+    delete(id: string): Promise<boolean>;
+    /** Returns up to `limit` runs for `routineId`, newest first. Returns `[]` for an unknown routine rather than throwing — mirrors `list()`'s empty-collection convention. */
+    listRuns(routineId: string, limit: number): Promise<readonly RoutineRun[]>;
+    /** Returns the most recently started run for `routineId`, or `null` if none has ever run. */
+    getLatestRun(routineId: string): Promise<RoutineRun | null>;
+}
+/**
+ * The display-shaped run summary OD's own `routineDbRowToContract` embedded on `Routine.lastRun`
+ * — a filtered/relabeled projection of a `RoutineRun` (its `id` renamed to `runId`; nullish
+ * `completedAt`/`summary`/`error`/`errorCode` omitted entirely rather than included as `null`).
+ * Kept as its own exported pure function (not inlined) so it is directly unit-testable, matching
+ * this repo's "extract to a testable pure function" convention for awkward-to-cover branches.
+ */
+export declare function summarizeLastRun(run: RoutineRun | null): Record<string, unknown> | null;
+/**
+ * `RoutineStore` plus two extra write hooks for run history that are deliberately NOT part of
+ * the public {@link RoutineStore} contract (see this module's doc comment for why run-writing
+ * stays out of the interface). Exposed as a concrete-type superset so:
+ * 1. This module's own tests can seed `listRuns`/`getLatestRun` fixtures without a second store.
+ * 2. A host bridging `./scheduler.js`'s `RoutinePersistence.insertRun`/`updateRun` calls into
+ *    this same in-memory instance (so `RoutineStore`'s read side observes the scheduler's writes)
+ *    has a documented, shape-matched target to forward them to.
+ */
+export interface InMemoryRoutineStore extends RoutineStore {
+    /** Records a run — mirrors `RoutinePersistence.insertRun`'s signature minus the scheduled-slot claim (this reference store has no concept of a "slot," only a flat run history), returning `false` if `run.id` was already recorded. */
+    recordRun(run: RoutineRun): boolean;
+    /** Patches a previously recorded run in place. A patch for an unknown `id` is a no-op, mirroring `RoutinePersistence.updateRun`'s own silent-no-op-on-unknown-id convention (see `./scheduler.js`'s `updateRun` call sites, none of which check a return value). */
+    patchRun(id: string, patch: Partial<RoutineRun>): void;
+}
+/**
+ * Reference `RoutineStore` implementation: an in-process `Map` of routines plus a flat array of
+ * runs, no durable copy — matching `createInMemoryEventLog`'s own scope (a real persistent
+ * adapter is `@jini-ai/sqlite`'s job).
+ *
+ * @complexity `get`/`create`/`update`/`delete` are O(1). `list` is O(n log n) (stable id-sort for
+ * deterministic ordering). `listRuns`/`getLatestRun` are O(m log m) in the number of runs
+ * recorded for the routine (m), since each sorts by `startedAt` descending on every call rather
+ * than maintaining a secondary index — acceptable at this reference implementation's scale.
+ */
+export declare function createInMemoryRoutineStore(): InMemoryRoutineStore;
+//# sourceMappingURL=routine-store.d.ts.map

package/dist/routines/routine-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine-store.d.ts","sourceRoot":"","sources":["../../src/routines/routine-store.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C,oBAAoB;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACpC,uFAAuF;IACvF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACzC,2IAA2I;IAC3I,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,iGAAiG;IACjG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACvE,qEAAqE;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,2KAA2K;IAC3K,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IAC3E,6FAA6F;IAC7F,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAevF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,wOAAwO;IACxO,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,oQAAoQ;IACpQ,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;CACxD;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,IAAI,oBAAoB,CAyFjE"}

package/dist/routines/routine-store.js

@@ -0,0 +1,162 @@
+/**
+ * `RoutineStore` — the CRUD + run-history persistence port for `@jini-ai/http`'s routine routes.
+ * Designed the same way `../event-log.js`'s `EventLog` is designed (that module's own doc
+ * comment is the explicit template named by the porting proposal,
+ * `ADS-memory/reports/proposals/PROP-http-route-packs-automation-routines-2026-07-21.md`): a
+ * storage-agnostic interface plus an in-memory reference implementation, async-only from day one
+ * (extraction-plan §2.6) so a durable `@jini-ai/sqlite` adapter is a drop-in swap later without an
+ * API break.
+ *
+ * No such port existed anywhere in this repo before this file — OD's own `routine.ts` route file
+ * called eight raw `db.js` SQL functions directly (`getRoutine`/`insertRoutine`/`updateRoutine`/
+ * `deleteRoutine`/`listRoutines`/`listRoutineRuns`/`getLatestRoutineRun`/`getRoutineRun`) against
+ * `routines`/`routine_runs` tables that `packages/sqlite/source-map.md` already documents as
+ * explicitly out of scope for the db-barrel port. This is the missing design.
+ *
+ * **Deliberately separate from `./scheduler.js`'s `RoutinePersistence`, not a shared interface**,
+ * matching OD's own architecture: OD itself used two different narrow ports over the same
+ * conceptual `routine_runs` table — `RoutinePersistence.insertRun`/`updateRun` (injected into
+ * `RoutineService`, the scheduler's write path for a routine actually firing) and `routine.ts`'s
+ * own direct DB reads (the HTTP layer's read path for CRUD + run-history display). This port
+ * mirrors that same split: `RoutineStore` owns Routine CRUD and *read-only* run history
+ * (`listRuns`/`getLatestRun`); it does not write run records — that stays the scheduler's job via
+ * its own separately-injected `RoutinePersistence`. A host wiring both together against one real
+ * durable table (a future `@jini-ai/sqlite` adapter) is host-level integration wiring, the same way
+ * `runs.ts`'s `onStarted` driver is host-supplied rather than built into `RunLifecycle` itself —
+ * not attempted here, out of this port's scope.
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * The display-shaped run summary OD's own `routineDbRowToContract` embedded on `Routine.lastRun`
+ * — a filtered/relabeled projection of a `RoutineRun` (its `id` renamed to `runId`; nullish
+ * `completedAt`/`summary`/`error`/`errorCode` omitted entirely rather than included as `null`).
+ * Kept as its own exported pure function (not inlined) so it is directly unit-testable, matching
+ * this repo's "extract to a testable pure function" convention for awkward-to-cover branches.
+ */
+export function summarizeLastRun(run) {
+    if (!run)
+        return null;
+    return {
+        runId: run.id,
+        status: run.status,
+        trigger: run.trigger,
+        startedAt: run.startedAt,
+        ...(run.completedAt == null ? {} : { completedAt: run.completedAt }),
+        projectId: run.projectId,
+        conversationId: run.conversationId,
+        agentRunId: run.agentRunId,
+        ...(run.summary ? { summary: run.summary } : {}),
+        ...(run.error ? { error: run.error } : {}),
+        ...(run.errorCode ? { errorCode: run.errorCode } : {}),
+    };
+}
+function cloneContext(context) {
+    return {
+        ...(context.skillIds ? { skillIds: [...context.skillIds] } : {}),
+        ...(context.pluginIds ? { pluginIds: [...context.pluginIds] } : {}),
+        ...(context.mcpServerIds ? { mcpServerIds: [...context.mcpServerIds] } : {}),
+        ...(context.connectorIds ? { connectorIds: [...context.connectorIds] } : {}),
+    };
+}
+/** Defensive deep clone so a caller mutating a returned `Routine` (its `context` array fields, `schedule`, or `target`) cannot corrupt this store's internal state — the store's only copy is never handed out by reference. */
+function cloneRoutine(routine) {
+    return {
+        ...routine,
+        context: cloneContext(routine.context),
+        schedule: { ...routine.schedule },
+        target: { ...routine.target },
+    };
+}
+/**
+ * Reference `RoutineStore` implementation: an in-process `Map` of routines plus a flat array of
+ * runs, no durable copy — matching `createInMemoryEventLog`'s own scope (a real persistent
+ * adapter is `@jini-ai/sqlite`'s job).
+ *
+ * @complexity `get`/`create`/`update`/`delete` are O(1). `list` is O(n log n) (stable id-sort for
+ * deterministic ordering). `listRuns`/`getLatestRun` are O(m log m) in the number of runs
+ * recorded for the routine (m), since each sorts by `startedAt` descending on every call rather
+ * than maintaining a secondary index — acceptable at this reference implementation's scale.
+ */
+export function createInMemoryRoutineStore() {
+    const routines = new Map();
+    const runs = [];
+    function runsFor(routineId) {
+        return runs
+            .filter((run) => run.routineId === routineId)
+            .sort((a, b) => b.startedAt - a.startedAt);
+    }
+    async function withLastRun(routine) {
+        const latest = runsFor(routine.id)[0] ?? null;
+        return { ...cloneRoutine(routine), lastRun: summarizeLastRun(latest) };
+    }
+    return {
+        async list() {
+            const ids = Array.from(routines.keys()).sort();
+            return Promise.all(ids.map((id) => withLastRun(routines.get(id))));
+        },
+        async get(id) {
+            const routine = routines.get(id);
+            return routine ? withLastRun(routine) : null;
+        },
+        async create(input) {
+            const now = Date.now();
+            const routine = {
+                id: `routine-${randomUUID()}`,
+                name: input.name,
+                prompt: input.prompt,
+                schedule: input.schedule,
+                target: input.target,
+                skillId: input.skillId ?? null,
+                agentId: input.agentId ?? null,
+                context: input.context ?? {},
+                enabled: input.enabled ?? true,
+                nextRunAt: null,
+                lastRun: null,
+                createdAt: now,
+                updatedAt: now,
+            };
+            routines.set(routine.id, routine);
+            return withLastRun(routine);
+        },
+        async update(id, patch) {
+            const existing = routines.get(id);
+            if (!existing)
+                return null;
+            const updated = {
+                ...existing,
+                ...(patch.name !== undefined ? { name: patch.name } : {}),
+                ...(patch.prompt !== undefined ? { prompt: patch.prompt } : {}),
+                ...(patch.schedule !== undefined ? { schedule: patch.schedule } : {}),
+                ...(patch.target !== undefined ? { target: patch.target } : {}),
+                ...(patch.skillId !== undefined ? { skillId: patch.skillId } : {}),
+                ...(patch.agentId !== undefined ? { agentId: patch.agentId } : {}),
+                ...(patch.context !== undefined ? { context: patch.context } : {}),
+                ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
+                updatedAt: Date.now(),
+            };
+            routines.set(id, updated);
+            return withLastRun(updated);
+        },
+        async delete(id) {
+            return routines.delete(id);
+        },
+        async listRuns(routineId, limit) {
+            return runsFor(routineId).slice(0, limit);
+        },
+        async getLatestRun(routineId) {
+            return runsFor(routineId)[0] ?? null;
+        },
+        recordRun(run) {
+            if (runs.some((existing) => existing.id === run.id))
+                return false;
+            runs.push({ ...run });
+            return true;
+        },
+        patchRun(id, patch) {
+            const run = runs.find((candidate) => candidate.id === id);
+            if (run)
+                Object.assign(run, patch);
+        },
+    };
+}
+//# sourceMappingURL=routine-store.js.map

package/dist/routines/routine-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine-store.js","sourceRoot":"","sources":["../../src/routines/routine-store.ts"],"names":[],"mappings":"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"}

package/dist/routines/schedule.d.ts

@@ -0,0 +1,72 @@
+/**
+ * DST-safe wall-clock schedule math + input validation for {@link ./scheduler.js}'s
+ * `RoutineService`. Ported verbatim (logic unchanged) from OD's `apps/daemon/src/routines.ts` —
+ * see that module's own header comment, quoted in the porting proposal
+ * (`ADS-memory/reports/proposals/PROP-http-route-packs-automation-routines-2026-07-21.md`), for
+ * why this is "real, non-trivial, DST-safe timezone math... genuinely hard to get right and not
+ * something to casually reinvent." Its only dependency is `Intl.DateTimeFormat`, which Node ships
+ * with full-icu by default — no OD coupling.
+ */
+import type { RoutineProjectTarget, RoutineSchedule, Weekday } from './types.js';
+/**
+ * Returns the wall-clock parts of `atUtc` rendered in `timezone`. Uses `Intl.DateTimeFormat`. If
+ * the timezone is invalid the formatter throws — callers catch upstream.
+ *
+ * Exported for the same reason as {@link tzWallToUtcCandidates}/{@link tzWallToUtcGapFallback}:
+ * its two defensive fallbacks (an Intl-reported hour of `"24"` at local midnight in some
+ * locale/zone combinations, and an unrecognized weekday abbreviation) are ICU-implementation
+ * edge cases no timezone on this test runner's ICU data naturally triggers — directly testable
+ * with a mocked `Intl.DateTimeFormat.prototype.formatToParts` instead of left unreachable.
+ */
+export declare function partsInTimezone(timezone: string, atUtc: Date): {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    weekday: Weekday;
+};
+/**
+ * Returns every UTC instant at which the wall clock in `timezone` reads the requested Y-M-D h:m,
+ * sorted ascending. Most days have exactly one match. On a fall-back transition day the requested
+ * time inside the repeated hour has two matches (one before the transition, one after); outside
+ * that hour it still has one. On a spring-forward gap the requested time inside the gap has zero
+ * matches — callers fall back to {@link tzWallToUtcGapFallback} to land on a post-gap instant the
+ * same day. Probes offsets at three reference points across the day so that both pre- and
+ * post-transition offsets are sampled regardless of which side of the transition `tentative`
+ * happens to land on. Returns `[]` if `timezone` is invalid.
+ *
+ * Exported (unlike this module's other low-level helpers) so its own `catch` branch is directly
+ * unit-testable: {@link nextWallTimeMatching}, this function's only real caller, already calls
+ * the unguarded `partsInTimezone` earlier in its own loop body, so an invalid timezone throws
+ * there first — this function's defensive catch is otherwise unreachable through that call path.
+ */
+export declare function tzWallToUtcCandidates(timezone: string, year: number, month: number, day: number, hour: number, minute: number): Date[];
+/**
+ * Spring-forward gap fallback: when the requested wall time doesn't exist in `timezone` on this
+ * day (clocks jumped over it), return the later of the two probe candidates. That instant has
+ * crossed the transition and renders as the first valid post-gap wall time, so a routine still
+ * fires today instead of firing an hour early before the gap. Returns `null` if `timezone` is
+ * invalid.
+ *
+ * Exported for the same reason as {@link tzWallToUtcCandidates} — its own `catch` branch is
+ * otherwise unreachable through {@link nextWallTimeMatching}'s call path.
+ */
+export declare function tzWallToUtcGapFallback(timezone: string, year: number, month: number, day: number, hour: number, minute: number): Date | null;
+export declare function nextHourlyRunAt(minute: number, now?: Date): Date;
+/**
+ * Returns the next instant at which the wall-clock in `timezone` reads "HH:MM" on a day where
+ * `predicate(weekday)` holds. Walks forward at most 14 calendar days as a safety bound (covers
+ * any weekday-based pattern). Exported (unlike this module's other internal helpers) so its
+ * 14-day-exhaustion fallback is directly unit-testable: every `predicate` `nextRunAtForSchedule`
+ * actually passes (daily/weekdays/weekly) structurally guarantees a match within 7 days, making
+ * that branch otherwise unreachable through the public schedule-kind API alone.
+ */
+export declare function nextWallTimeMatching(timezone: string, time: string, predicate: (weekday: Weekday) => boolean, now: Date): Date | null;
+export declare function nextRunAtForSchedule(schedule: RoutineSchedule, now?: Date): Date | null;
+export declare function isValidWallTime(time: string): boolean;
+export declare function isValidTimezone(tz: string): boolean;
+export declare function validateSchedule(schedule: RoutineSchedule): void;
+export declare function validateTarget(target: RoutineProjectTarget): void;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/routines/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/routines/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAIjF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,IAAI,GACV;IACD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,CAoCA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,IAAI,EAAE,CAoBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,IAAI,GAAG,IAAI,CAWb;AAwBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,IAAI,CAQtE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,EACxC,GAAG,EAAE,IAAI,GACR,IAAI,GAAG,IAAI,CAuCb;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAa,GAAG,IAAI,GAAG,IAAI,CAe7F;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAQnD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CA2BhE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAYjE"}