@plurnk/plurnk-schedule 1.19.0

package/.env.defaults

@@ -0,0 +1,15 @@
+# @plurnk/plurnk-schedule — scheduled messages for workers.
+
+# Time zone for schedules and for every command a worker runs; an IANA name. UTC unless the
+# operator or a worker (through env) says otherwise; a rule without a TZID is stamped with the
+# effective zone when it is added.
+TZ=UTC
+# Initially enabled service-origin rule aliases, JSON array; [] = none.
+PLURNK_SCHEDULE_ENABLED=[]
+# Upcoming occurrences shown when rule text is read before it is added, positive integer.
+PLURNK_SCHEDULE_PREVIEW_OCCURRENCES=3
+# A service-origin rule: the operator's crontab. JSON with the RFC 5545 rule text (without a
+# DTSTART it starts when the daemon starts), the target worker, the message, and an optional
+# loop policy. Disable-only for a worker; may be unbounded.
+# An empty alias definition masks the service rule and its ENABLED selection.
+# PLURNK_SCHEDULE_heartbeat={"rule":"FREQ=HOURLY","target":"worker://plurnkbot","prompt":"Check for new messages and report."}

package/README.md

@@ -0,0 +1,45 @@
+# @plurnk/plurnk-schedule
+
+Scheduled messages for [Plurnk](https://github.com/plurnk/plurnk-service)
+workers, on RFC 5545 recurrence rules. A rule delivers its message to a
+worker at each occurrence, as an ordinary message from `schedule://<alias>`;
+the worker's live loop takes it, or a new loop starts. Workers manage their
+own rules through the `schedule` family (`discover`, `add`, `list`, `enable`,
+`disable`, `remove`); the operator can seed rules from the environment.
+
+## Configure
+
+Put overrides in the shell, `./.env`, or `$XDG_CONFIG_HOME/plurnk/.env`:
+
+```dotenv
+TZ=America/New_York
+PLURNK_SCHEDULE_HEARTBEAT={"rule":"FREQ=HOURLY","target":"worker://plurnkbot","prompt":"Check for new messages and report."}
+PLURNK_SCHEDULE_ENABLED=["heartbeat"]
+```
+
+- `TZ` is the zone rules are read in and the time is told in. The package
+  defaults it to UTC; the shell overrides; a workspace overrides through the
+  `env` family.
+- `PLURNK_SCHEDULE_<ALIAS>` is one definition as JSON: `rule`, `target`
+  (`worker://<name>`), `prompt`, and optionally `policy`
+  (`{"proposals":"accept"}` for a loop nobody watches). A service rule may be
+  unbounded; a rule a worker adds carries `COUNT` or `UNTIL`. Without a
+  `DTSTART` a service rule starts when the daemon starts: `FREQ=HOURLY` is a
+  check-in at start and every hour after; `BYHOUR`, `BYMINUTE` and `BYSECOND`
+  pin a time of day instead.
+- `PLURNK_SCHEDULE_ENABLED` names the aliases a workspace starts with.
+
+## Behaviour
+
+- No packet carries a clock; a worker reads the time through `discover`.
+- One armed occurrence per rule. A late fire delivers once and skips what it
+  missed.
+- Timers outlive a workspace's residency and re-arm at daemon start from the
+  persisted family state.
+- A delivery that fails, because the target worker is gone, lists the rule
+  `unavailable` with its Problem; `enable` retries.
+- An occurrence arrives as a message and runs its own loop on the target
+  worker; no WAIT holds a loop for it.
+
+`SPEC.md` is the specification; `docs/schedule.md` is the model-facing
+teaching beneath the generated family document.

package/SPEC.md

@@ -0,0 +1,96 @@
+# Plurnk schedule specification
+
+## §schedule-family The schedule family
+
+Scheduled messages are one workspace Functionality family named `schedule`,
+owned by `@plurnk/plurnk-schedule` ({§functionality-adapter}). A definition is
+`{ rule, target, prompt, policy? }`: RFC 5545 rule text ({§schedule-rule}), a
+`worker://<name>` target in the workspace ({§worker-name}, preserved exactly), the message delivered at each
+occurrence, and optionally the proposal policy of a loop the delivery starts
+({§schedule-delivery}). Aliases take the shared grammar. The verbs are the
+coordinator's: `list`, `discover` ({§schedule-clock}), `add`, `enable`,
+`disable`, `remove`. The adapter publishes no documents of its own; the
+family document's authored body is `docs/schedule.md`
+({§functionality-model-projection}).
+
+## §schedule-rule Rule text
+
+A rule is RFC 5545 text: an optional `DTSTART` line, exactly one `RRULE` line,
+and any `EXDATE` or `RDATE` lines. Bare `FREQ=…` parts are the RRULE line; the
+`RRULE:` prefix is optional. The recurrence library owns the grammar and the
+expansion. The family refuses by name what the library would drop silently: an
+RRULE part outside the fourteen RFC 5545 names, a second RRULE, a second
+DTSTART, any other line. Admission stores the library's canonical text,
+`DTSTART;TZID=<zone>:<local>` then `RRULE:<parts>` then the date lines, and
+every later read parses that text; a canonical text that fails to parse is a
+defect, not a refusal.
+
+## §schedule-bound Bound
+
+A workspace rule ends: its RRULE carries `COUNT` or `UNTIL`, else `add`
+refuses with `rule-unbounded`. A service rule ({§schedule-environment}) may be
+unbounded; the operator owns it. An exhausted rule stays listed `active` with
+`exhausted: true` and `next: null`; it arms nothing.
+
+## §schedule-zone Zone
+
+`TZ` is the zone a rule is read in and the zone the time is told in. The
+package declares `TZ=UTC` in `.env.defaults`; the operator's environment
+overrides it, a workspace overrides it through the `env` family
+({§workspace-env}), and a Worker's own `env` override wins for the verbs that
+Worker invokes ({§functionality-scope}). A call carrying `env` metadata with
+`TZ` is read in that zone for that call. A rule keeps the zone stamped at its
+`add`; a later `env` change moves no existing rule. Without a `DTSTART` a rule starts when it is read, at the
+next whole second in the effective zone, so its first occurrence is still
+ahead: a workspace rule is read at `add`, a service rule once, when the daemon
+starts, in the service's zone. A floating `DTSTART` is read in the effective
+zone; a `DTSTART` with a `TZID` or a UTC `Z` keeps its own zone. An unknown
+zone refuses with `zone-unknown`.
+
+## §schedule-clock The clock
+
+No packet carries a clock. The time is told on demand: `discover` with rule
+text in `source` returns one inert candidate whose summary opens with the
+current time in the effective zone (RFC 9557, to the second), states the rule
+in words, and previews its next `PLURNK_SCHEDULE_PREVIEW_OCCURRENCES`
+occurrences ({§schedule-discovery-preview}); the candidate's definition
+carries the canonical rule text. Discovery persists nothing; a `query` or a
+`configuration` is refused.
+
+§schedule-discovery-preview `PLURNK_SCHEDULE_PREVIEW_OCCURRENCES` is a family control
+like `PLURNK_SCHEDULE_ENABLED`: a positive integer, never read as a rule alias.
+
+## §schedule-delivery Delivery
+
+The module holds one armed occurrence per enabled (workspace, alias). At the
+occurrence it resolves the target worker by name and delivers the prompt
+through the application port's `runLoop` with the source `schedule://<alias>`
+and the definition's policy: the message joins the worker's live loop or
+starts one ({§message-arrival}, {§message-causal-source}); no WAIT holds a loop
+for an occurrence — a loop with nothing live concludes, and the occurrence's
+message starts the next loop on the same worker. The next occurrence
+then arms from the present: a late fire delivers once and skips what it
+missed, never a backlog. A missing worker or a refused delivery disarms the
+rule and lists it `unavailable` with the Problem; `enable` retries. After
+every delivery attempt the family's outcomes are refreshed where the workspace
+is resident.
+
+## §schedule-residency Residency
+
+A schedule is an obligation, not a runtime. Cooling a workspace leaves its
+timers armed; `disable` and `remove` disarm through the published rule set. At
+daemon start the module arms every workspace's enabled rules from the
+coordinator's persisted family state ({§functionality-state}) over the
+service definitions, resident or not; an unreadable definition is reported and
+stays disarmed.
+
+## §schedule-environment Environment
+
+`PLURNK_SCHEDULE_<ALIAS>` holds one definition as JSON; the alias is the
+suffix case-folded to the family grammar, and two variables folding to one
+alias fail at boot. `PLURNK_SCHEDULE_ENABLED` is the JSON array of aliases a
+workspace starts with; `[]` is the one spelling of none, and an absent or empty
+key is refused by name. A service definition is disable-only in a workspace,
+as for every family. An explicitly empty definition masks that service rule and
+its inherited `ENABLED` selection; it does not remove a workspace-owned rule or
+prohibit adding one. Case-fold collisions still fail validation.

package/dist/Functionality.d.ts

@@ -0,0 +1,102 @@
+import { type FunctionalityCandidate, type FunctionalityDiscoverQuery, type JsonSchema, type ProblemDetails } from "@plurnk/plurnk-contracts";
+import { type ScheduleDefinition } from "./definition.ts";
+import Scheduler, { type SchedulerOptions } from "./Scheduler.ts";
+import ScheduleResources from "./ScheduleResources.ts";
+export declare const SCHEDULE_FAMILY = "schedule";
+export declare const SCHEDULE_OWNER = "@plurnk/plurnk-schedule";
+interface WorkspaceIdentity {
+    readonly workspaceId: number;
+}
+interface CallIdentity extends WorkspaceIdentity {
+    readonly workerId?: number;
+}
+interface CallOptions {
+    readonly env?: Readonly<Record<string, string>>;
+}
+type Outcome = {
+    readonly state: "active";
+    readonly detail?: object;
+} | {
+    readonly state: "unavailable";
+    readonly problem: ProblemDetails;
+} | {
+    readonly state: "authorization-required";
+    readonly authorization: {
+        readonly url: string;
+    };
+};
+interface Preparation extends WorkspaceIdentity {
+    readonly enabled: ReadonlyMap<string, object>;
+    readonly previous: unknown | null;
+    readonly failure: "publish-unavailable" | "reject";
+    readonly force?: string;
+    retain(): () => void;
+}
+interface Prepared {
+    readonly documents: readonly {
+        readonly pathname: string;
+        readonly content: string;
+    }[];
+    readonly outcomes: ReadonlyMap<string, Outcome>;
+    readonly snapshot: unknown;
+    commit(): Promise<void>;
+    abort(): Promise<void>;
+}
+export interface FunctionalityFamilyHandle {
+    invoke(verb: "list" | "discover" | "add" | "enable" | "disable" | "remove", params: unknown, identity: WorkspaceIdentity): Promise<{
+        readonly status: number;
+        readonly body: unknown;
+    }>;
+    refresh(identity: WorkspaceIdentity): Promise<void>;
+}
+export interface EnvironmentSeam {
+    readWorkspaceEnvironment(workspaceId: number): Promise<(ambient?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv>;
+    readWorkerEnvironment(workspaceId: number, workerId: number): Promise<(ambient?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv>;
+}
+export interface ScheduleFunctionalityOptions extends Omit<SchedulerOptions, "settled"> {
+}
+export declare class ScheduleFunctionalityError extends Error {
+    readonly problem: ProblemDetails;
+    constructor(problem: ProblemDetails, cause?: unknown);
+}
+export default class ScheduleFunctionality {
+    #private;
+    readonly scheme: ScheduleResources;
+    readonly family = "schedule";
+    readonly namespaceOwner = "@plurnk/plurnk-schedule";
+    readonly summary = "Manage scheduled messages";
+    readonly definitionSchema: JsonSchema;
+    readonly example: {
+        alias: string;
+        definition: {
+            rule: string;
+            target: string;
+            prompt: string;
+        };
+    };
+    readonly docsDir: string;
+    readonly discovery: {
+        details: string;
+    };
+    constructor(env?: NodeJS.ProcessEnv, options?: ScheduleFunctionalityOptions);
+    attach(handle: FunctionalityFamilyHandle, environment: EnvironmentSeam): void;
+    get scheduler(): Scheduler;
+    service(): ReadonlyMap<string, {
+        readonly definition: ScheduleDefinition;
+        readonly enabled: boolean;
+    }>;
+    available(): Promise<readonly {
+        alias: string;
+        definition: object;
+        enabled: boolean;
+    }[]>;
+    discover(query: FunctionalityDiscoverQuery, identity: CallIdentity, options?: CallOptions): Promise<readonly FunctionalityCandidate[]>;
+    admit(input: unknown, identity: CallIdentity, _caller?: unknown, options?: CallOptions): Promise<{
+        alias: string;
+        definition: object;
+    }>;
+    prepare(preparation: Preparation): Promise<Prepared>;
+    teardown(_snapshot: unknown, _identity: WorkspaceIdentity): Promise<void>;
+}
+export {};
+//# sourceMappingURL=Functionality.d.ts.map

package/dist/Functionality.d.ts.map

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

package/dist/Functionality.js

@@ -0,0 +1,242 @@
+// {§schedule-family} — scheduled messages as one workspace Functionality family named `schedule`.
+// The adapter owns the family's truth: the environment's rules, inert discovery that reads a rule
+// and tells the time ({§schedule-clock}), admission that canonicalizes and bounds a rule, and the
+// outcomes the timers stand behind ({§schedule-delivery}, {§schedule-residency}).
+import { fileURLToPath } from "node:url";
+import { Problems, } from "@plurnk/plurnk-contracts";
+import { previewOccurrences, serviceDefinitions, serviceEnabled } from "./config.js";
+import { DEFINITION_SCHEMA, DefinitionError, readDefinition } from "./definition.js";
+import { describeRule, nextOccurrence, normalizeRule, parseRule, ScheduleRuleError, upcoming } from "./rules.js";
+import Scheduler, {} from "./Scheduler.js";
+import { isoString, zoned } from "./temporal.js";
+import ScheduleResources from "./ScheduleResources.js";
+export const SCHEDULE_FAMILY = "schedule";
+export const SCHEDULE_OWNER = "@plurnk/plurnk-schedule";
+export class ScheduleFunctionalityError extends Error {
+    problem;
+    constructor(problem, cause) {
+        super(problem.detail, cause === undefined ? undefined : { cause });
+        this.name = "ScheduleFunctionalityError";
+        this.problem = problem;
+    }
+}
+const problem = (code, status, detail, extensions = {}) => Problems.create("schedule:functionality", code, status, detail, {
+    stage: "schedule-functionality",
+    ...extensions,
+});
+const failure = (code, status, detail, extensions = {}, cause) => new ScheduleFunctionalityError(problem(code, status, detail, extensions), cause);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+export default class ScheduleFunctionality {
+    scheme;
+    family = SCHEDULE_FAMILY;
+    namespaceOwner = SCHEDULE_OWNER;
+    summary = "Manage scheduled messages";
+    definitionSchema = DEFINITION_SCHEMA;
+    example = {
+        alias: "standup",
+        definition: {
+            rule: "FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0;COUNT=20",
+            target: "worker://scribe",
+            prompt: "Summarize yesterday's log entries for the team.",
+        },
+    };
+    docsDir = fileURLToPath(new URL("..", import.meta.url));
+    discovery = {
+        details: "`source` is rule text: RFC 5545, an optional DTSTART line and one RRULE line, or bare `FREQ=…` parts. One inert candidate comes back. Its summary opens with the current time in the effective zone and previews the first occurrences; its definition carries the rule as it would be stored, to `add` with a `target` and a `prompt`. Nothing is persisted.",
+    };
+    #env;
+    #scheduler;
+    #report;
+    // {§schedule-environment} — the service's rules, canonical from construction: a rule without a
+    // DTSTART starts when it is read, and a service rule is read once, when the daemon starts.
+    #service;
+    #handle = null;
+    #environment = null;
+    constructor(env = process.env, options = {}) {
+        this.#env = env;
+        this.#report = options.report ?? ((message, cause) => { console.error(`${message}:`, cause); });
+        this.#scheduler = new Scheduler({ ...options, report: this.#report, settled: (workspaceId) => { this.#settled(workspaceId); } });
+        this.scheme = new ScheduleResources(async (workspaceId) => {
+            if (this.#handle === null)
+                throw new Error("schedule family is not attached");
+            const listing = await this.#handle.invoke("list", {}, { workspaceId });
+            return listing.body.definitions;
+        });
+        const zone = env.TZ;
+        if (zone === undefined || zone.length === 0)
+            throw new Error("TZ is unset; @plurnk/plurnk-schedule declares its default in .env.defaults.");
+        const enabled = serviceEnabled(env);
+        const now = this.#scheduler.now();
+        this.#service = new Map([...serviceDefinitions(env)].map(([alias, definition]) => {
+            let parsed;
+            try {
+                parsed = normalizeRule(definition.rule, zone, now);
+            }
+            catch (cause) {
+                throw new Error(`PLURNK_SCHEDULE_${alias.toUpperCase()}: ${messageOf(cause)}`, { cause });
+            }
+            return [alias, { definition: { ...definition, rule: parsed.text }, enabled: enabled.has(alias) }];
+        }));
+    }
+    attach(handle, environment) {
+        this.#handle = handle;
+        this.#environment = environment;
+    }
+    get scheduler() {
+        return this.#scheduler;
+    }
+    // The service's rules as the coordinator's baseline, and as the module re-arms them at start.
+    service() {
+        return this.#service;
+    }
+    async available() {
+        return [...this.#service].map(([alias, { definition, enabled }]) => ({ alias, definition, enabled }));
+    }
+    // {§schedule-clock} — the one place the time is told: on demand, beside the rule it reads.
+    async discover(query, identity, options) {
+        if (query.configuration !== undefined) {
+            throw failure("configuration-unsupported", 400, "schedule discovery reads rule text from `source`; it takes no configuration.", { retryable: false });
+        }
+        if (query.query !== undefined) {
+            throw failure("query-unsupported", 400, "schedule discovery reads rule text from `source`; there is no catalog to search.", { retryable: false });
+        }
+        if (query.source === undefined) {
+            throw failure("source-required", 400, "schedule discovery needs rule text in `source`; `FREQ=DAILY` is enough to read the time.", { retryable: false });
+        }
+        const zone = await this.#zone(identity, options);
+        const now = this.#scheduler.now();
+        const parsed = this.#read(query.source, zone, now);
+        const preview = upcoming(parsed, now, previewOccurrences(this.#env)).map(isoString);
+        return [{
+                alias: parsed.rule.options().freq.toLowerCase(),
+                summary: [
+                    `now ${isoString(zoned(now, zone))}`,
+                    describeRule(parsed),
+                    preview.length === 0 ? "no occurrence ahead" : `next ${preview.join(", ")}`,
+                    ...(parsed.bounded ? [] : ["unbounded: add needs COUNT or UNTIL"]),
+                ].join("; "),
+                definition: { rule: parsed.text },
+                provenance: { kind: "rule", source: query.source },
+            }];
+    }
+    async admit(input, identity, _caller, options) {
+        const params = isRecord(input) ? input : {};
+        if (typeof params.alias !== "string")
+            throw failure("alias-required", 400, "schedule add needs an alias.", { retryable: false });
+        let definition;
+        try {
+            definition = readDefinition(params.definition);
+        }
+        catch (cause) {
+            if (!(cause instanceof DefinitionError))
+                throw cause;
+            throw failure("definition-invalid", 400, "The schedule definition is invalid.", { errors: cause.errors, retryable: false }, cause);
+        }
+        const parsed = this.#read(definition.rule, await this.#zone(identity, options), this.#scheduler.now());
+        // {§schedule-bound}
+        if (!parsed.bounded)
+            throw failure("rule-unbounded", 400, "A workspace rule ends: give the RRULE a COUNT or an UNTIL.", { retryable: false });
+        return { alias: params.alias, definition: { ...definition, rule: parsed.text } };
+    }
+    async prepare(preparation) {
+        const { workspaceId } = preparation;
+        const previous = preparation.previous;
+        const rules = new Map();
+        const unavailable = new Map();
+        const outcomes = new Map();
+        const now = this.#scheduler.now();
+        for (const [alias, raw] of preparation.enabled) {
+            if (preparation.force === alias)
+                this.#scheduler.forgive(workspaceId, alias);
+            let definition;
+            let parsed;
+            try {
+                definition = readDefinition(raw);
+                parsed = parseRule(definition.rule);
+            }
+            catch (cause) {
+                const text = JSON.stringify(raw);
+                const fresh = previous?.unavailable.get(alias) !== text;
+                const unreadable = problem("rule-invalid", 400, `The rule of '${alias}' is unreadable: ${messageOf(cause)}`, { alias, retryable: false });
+                if (preparation.failure === "reject" && fresh)
+                    throw new ScheduleFunctionalityError(unreadable, cause);
+                if (fresh)
+                    this.#report(`schedule '${alias}' unavailable in workspace ${workspaceId}`, cause);
+                unavailable.set(alias, text);
+                outcomes.set(alias, { state: "unavailable", problem: unreadable });
+                continue;
+            }
+            rules.set(alias, { alias, definition, parsed });
+            const failed = this.#scheduler.failure(workspaceId, alias);
+            if (failed !== undefined && failed.text === parsed.text) {
+                unavailable.set(alias, parsed.text);
+                outcomes.set(alias, { state: "unavailable", problem: structuredClone(failed.problem) });
+                continue;
+            }
+            const next = nextOccurrence(parsed, now);
+            outcomes.set(alias, {
+                state: "active",
+                detail: {
+                    path: `schedule:///rules/${encodeURIComponent(alias)}`,
+                    rule: parsed.text,
+                    zone: parsed.zone,
+                    text: describeRule(parsed),
+                    next: next === null ? null : isoString(next),
+                    exhausted: next === null,
+                    target: definition.target,
+                    ...(definition.policy === undefined ? {} : { policy: definition.policy }),
+                },
+            });
+        }
+        const snapshot = { rules, unavailable };
+        return {
+            documents: [],
+            outcomes,
+            snapshot,
+            commit: async () => { await this.#scheduler.sync(workspaceId, rules); },
+            abort: async () => { },
+        };
+    }
+    // {§schedule-residency} — a schedule is an obligation, not a runtime: cooling the workspace
+    // leaves its timers armed.
+    async teardown(_snapshot, _identity) { }
+    // {§schedule-zone} — the zone a rule is read in: the call's own env when it carries one (a
+    // worker's `env` metadata), else the invoking Worker's environment (its overrides over the
+    // workspace layer over the service's), else the workspace's.
+    async #zone(identity, options) {
+        const called = options?.env?.TZ;
+        if (called !== undefined && called.length > 0)
+            return called;
+        const environment = this.#environment === null
+            ? this.#env
+            : identity.workerId === undefined
+                ? (await this.#environment.readWorkspaceEnvironment(identity.workspaceId))(this.#env)
+                : (await this.#environment.readWorkerEnvironment(identity.workspaceId, identity.workerId))(this.#env);
+        const zone = environment.TZ;
+        if (zone === undefined || zone.length === 0)
+            throw new Error("TZ is unset; @plurnk/plurnk-schedule declares its default in .env.defaults.");
+        return zone;
+    }
+    #read(text, zone, now) {
+        try {
+            return normalizeRule(text, zone, now);
+        }
+        catch (cause) {
+            if (!(cause instanceof ScheduleRuleError))
+                throw cause;
+            throw failure(cause.code, 400, cause.message, { retryable: false }, cause);
+        }
+    }
+    // A delivery settled: the outcomes name the next occurrence or the failure. A workspace that
+    // is not resident has nothing published; the coordinator's refresh returns at once.
+    #settled(workspaceId) {
+        const handle = this.#handle;
+        if (handle === null)
+            return;
+        void handle.refresh({ workspaceId }).catch((cause) => {
+            this.#report(`schedule outcomes did not refresh for workspace ${workspaceId}`, cause);
+        });
+    }
+}
+//# sourceMappingURL=Functionality.js.map

package/dist/Functionality.js.map

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

package/dist/Module.d.ts

@@ -0,0 +1,21 @@
+import type { ApplicationPort } from "@plurnk/plurnk-contracts";
+import ScheduleFunctionality, { type EnvironmentSeam, type FunctionalityFamilyHandle, type ScheduleFunctionalityOptions } from "./Functionality.ts";
+interface SetupSeam extends EnvironmentSeam {
+    registerFunctionalityAdapter(adapter: ScheduleFunctionality): FunctionalityFamilyHandle;
+    readWorkspaceModuleState(workspaceId: number, namespaceOwner: string): Promise<unknown | null>;
+}
+type StartSeam = Pick<ApplicationPort, "listWorkspaces" | "listWorkers" | "runLoop">;
+export interface ModuleOptions extends ScheduleFunctionalityOptions {
+    readonly env?: NodeJS.ProcessEnv;
+}
+export default class Module {
+    #private;
+    static init(options?: ModuleOptions): Module;
+    private constructor();
+    get functionality(): ScheduleFunctionality;
+    setup(seam: SetupSeam): void;
+    start(seam: StartSeam): Promise<void>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=Module.d.ts.map

package/dist/Module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Module.d.ts","sourceRoot":"","sources":["../src/Module.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,qBAAqB,EAAE,EAE1B,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACpC,MAAM,oBAAoB,CAAC;AAI5B,UAAU,SAAU,SAAQ,eAAe;IACvC,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,yBAAyB,CAAC;IACxF,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAClG;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,eAAe,EAAE,gBAAgB,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC;AAarF,MAAM,WAAW,aAAc,SAAQ,4BAA4B;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AAKD,MAAM,CAAC,OAAO,OAAO,MAAM;;IAOvB,MAAM,CAAC,IAAI,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAE/C;IAED,OAAO,eAKN;IAED,IAAI,aAAa,IAAI,qBAAqB,CAEzC;IAED,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAI3B;IAEK,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B1C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;CASJ"}

package/dist/Module.js

@@ -0,0 +1,79 @@
+import { readDefinition } from "./definition.js";
+import ScheduleFunctionality, { SCHEDULE_OWNER, } from "./Functionality.js";
+import { parseRule } from "./rules.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export default class Module {
+    #env;
+    #functionality;
+    #report;
+    #seam = null;
+    #started = false;
+    static init(options = {}) {
+        return new Module(options);
+    }
+    constructor(options) {
+        const { env, ...functionality } = options;
+        this.#env = env ?? process.env;
+        this.#report = options.report ?? ((message, cause) => { console.error(`${message}:`, cause); });
+        this.#functionality = new ScheduleFunctionality(this.#env, functionality);
+    }
+    get functionality() {
+        return this.#functionality;
+    }
+    setup(seam) {
+        if (this.#seam !== null)
+            throw new Error("schedule module already set up");
+        this.#seam = seam;
+        this.#functionality.attach(seam.registerFunctionalityAdapter(this.#functionality), seam);
+    }
+    async start(seam) {
+        const setup = this.#seam;
+        if (setup === null)
+            throw new Error("schedule module started before setup");
+        if (this.#started)
+            throw new Error("schedule module already started");
+        this.#started = true;
+        this.#functionality.scheduler.start(seam);
+        const service = this.#functionality.service();
+        for (const workspace of await seam.listWorkspaces()) {
+            const state = Module.#state(await setup.readWorkspaceModuleState(workspace.id, SCHEDULE_OWNER));
+            const effective = new Map();
+            for (const [alias, { definition, enabled }] of service)
+                effective.set(alias, { definition, enabled });
+            for (const [alias, record] of Object.entries(state.definitions)) {
+                if (record.origin !== "service") {
+                    effective.set(alias, { definition: record.definition, enabled: record.enabled });
+                    continue;
+                }
+                const base = effective.get(alias);
+                if (base !== undefined)
+                    effective.set(alias, { ...base, enabled: record.enabled });
+            }
+            const rules = new Map();
+            for (const [alias, { definition, enabled }] of effective) {
+                if (!enabled)
+                    continue;
+                try {
+                    const read = readDefinition(definition);
+                    rules.set(alias, { alias, definition: read, parsed: parseRule(read.rule) });
+                }
+                catch (cause) {
+                    this.#report(`schedule '${alias}' in workspace ${workspace.id} is unreadable and stays disarmed`, cause);
+                }
+            }
+            await this.#functionality.scheduler.sync(workspace.id, rules);
+        }
+    }
+    async close() {
+        await this.#functionality.scheduler.close();
+    }
+    static #state(raw) {
+        if (raw === null)
+            return { version: 1, definitions: {} };
+        if (!isRecord(raw) || raw.version !== 1 || !isRecord(raw.definitions)) {
+            throw new Error("schedule state in workspace_module_state is not a version-1 family state");
+        }
+        return raw;
+    }
+}
+//# sourceMappingURL=Module.js.map

package/dist/Module.js.map

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