@outcrawl/sdk 0.1.0

package/dist/types/_deps/core/agent-alias.d.ts

@@ -0,0 +1,219 @@
+/**
+ * The harness a customer names, and the models behind it that they never see.
+ *
+ * ── One name on the wire ────────────────────────────────────────────────────
+ *
+ * A customer asks for `Scout 1` or `Voyager 1`. That is the entire vocabulary:
+ * {@link AgentAlias} has two members, `AgentRequest.agent` accepts nothing else,
+ * and `AgentRequest.model` — which documented itself as "`'default'` for the
+ * model we host, or a BYOK model id" and was read by exactly one function whose
+ * only behaviour was to refuse it — is gone. The harness is the product name;
+ * which model runs underneath it is ours to change without telling anyone,
+ * including on the failover branch, mid-run.
+ *
+ * That is not a preference, it is the only shape that survives the arithmetic.
+ * A published per-minute price and a customer-chosen model cannot coexist: the
+ * customer picks the model, we absorb the difference, and the difference between
+ * the cheapest and the most expensive credible driver measured on one real
+ * production run is a factor of 126. So the customer picks the *capability* and
+ * we pick what delivers it.
+ *
+ * ── What the indirection buys, stated so nobody removes it ──────────────────
+ *
+ * If a model in a chain changes — a cheaper planner clears the Voyager bar, a
+ * preview slug is withdrawn, a rank is reordered — that is a ONE-LINE EDIT to
+ * {@link AGENT_MODEL_CHAINS} and nothing else moves: no wire type, no
+ * accept-list, no error string, no test fixture, no customer-visible byte, no
+ * migration. That property is the entire reason this file exists rather than a
+ * model id sitting on `AgentRequest`, and it is the thing somebody will be
+ * tempted to "simplify" away in six months. It is not indirection for its own
+ * sake; it is what makes the model a decision we can revisit weekly against a
+ * price we published once.
+ *
+ * ── Why this file is not `types.ts` ─────────────────────────────────────────
+ *
+ * `types.ts` is the wire contract — the thing every surface is checked against,
+ * with no dependency and no secret in it. {@link AGENT_MODEL_CHAINS} is the
+ * opposite: it is the one table in `@outcrawl/core` that must never reach a
+ * customer, and it drags a second concern (which vendor bills us, in what order)
+ * that has no business sitting beside `AgentResult`. Keeping it here means the
+ * audit question "can a slug reach a projector" has a one-file answer.
+ *
+ * Nothing in this file is serialized. `AgentAlias` crosses the wire; every other
+ * export is consumed by `@outcrawl/model`, which resolves a chain into clients,
+ * and by the cost gate, which prices it. No wire type, no projector and no error
+ * string reads a slug from here — which is a property that was audited across
+ * `Usage`, `aggregateCache`, `Meter.tokens`, `StepTrace`, the replay metadata and
+ * `webhookBody` before it was written down.
+ *
+ * ── `role` and `rank`, and why not one flat union ───────────────────────────
+ *
+ * A slot is what a model DOES ({@link AgentModelRole}) and where it sits in that
+ * role's failover order ({@link AgentModelChoice.rank}). The obvious alternative
+ * — a single union of `primary | failover | reasoner | actuator` — makes the two
+ * aliases two different data structures, because Scout is one role with three
+ * ranks and Voyager is two roles with one rank each, and a consumer then needs a
+ * branch per alias. Split this way both are the same list and the cost gate has
+ * exactly one formula:
+ *
+ *     cost/min(alias) = SUM over roles ( MAX over ranks ( perCall x callsPerStep ) x steps/min )
+ *
+ * `MAX` within a role prices the failover branch, because only one rank is ever
+ * live at a time and the expensive branch is the one that must not go underwater
+ * unnoticed. `SUM` across roles prices Voyager's pair, because both run in the
+ * same run. Adding a third role forces that switch to be re-decided before the
+ * build goes green, which is the point.
+ *
+ * ── No prices here, and no measured numbers ─────────────────────────────────
+ *
+ * {@link AgentModelChoice} carries no `$/MTok` and no tokens-per-call. Prices
+ * live in the cost gate's committed OpenRouter snapshot, keyed by slug, and the
+ * seam is: **topology here, measurement there**. `callsPerStep` is on this side
+ * because it is a harness decision — how often our loop chooses to invoke a slot
+ * — and it moves only when the loop changes. Tokens per call is on the other
+ * side because it is measured off production and moves whenever traffic does.
+ * One source of truth each, and a weight in here would have forced an edit to
+ * this file every time somebody re-measured.
+ *
+ * Every slug below is a literal string constant. Not composed, not interpolated,
+ * not read from the environment — so the gate can enumerate them offline with no
+ * network and fail the build on any slug it has no price for. Adding a model
+ * therefore forces the cost calculation to be redone, which is the whole reason
+ * the gate exists.
+ */
+/**
+ * The harness names, as they appear on the wire.
+ *
+ * Lower-case and hyphenated because this is a JSON string a customer types, and
+ * `Scout 1` is the name in the documentation. There is no `'default'` member:
+ * absence means {@link DEFAULT_AGENT_ALIAS}, and a third spelling of the same
+ * request is a third thing to keep consistent.
+ */
+export type AgentAlias = 'scout-1' | 'voyager-1';
+/**
+ * Every alias, for validation and for iterating the table.
+ *
+ * `satisfies` rather than a bare annotation, so the array is checked against the
+ * union in both directions: a member missing here does not compile, and a
+ * misspelled one does not either.
+ */
+export declare const AGENT_ALIASES: readonly ["scout-1", "voyager-1"];
+/**
+ * The harness a request gets when it names none.
+ *
+ * `scout-1`, because it is the cheap one. A default that silently selected the
+ * expensive pair would put an unasked-for bill on every caller who omitted a
+ * field, and the omission is the common case — the SDK, the CLI and every MCP
+ * client will reach this path far more often than they name a harness.
+ */
+export declare const DEFAULT_AGENT_ALIAS: AgentAlias;
+/** Whether a value is one of the two names. Narrows, for use at a boundary. */
+export declare function isAgentAlias(value: unknown): value is AgentAlias;
+/**
+ * The alias, or a throw naming the whole closed set.
+ *
+ * The message lists both names rather than saying "invalid", because a caller
+ * who guessed wrong has no documentation open and one round trip should teach
+ * them the entire vocabulary. `undefined` is NOT accepted here: absence is a
+ * decision the boundary makes with {@link DEFAULT_AGENT_ALIAS}, and folding it
+ * in would make `parseAgentAlias(undefined)` silently mean `scout-1` at call
+ * sites that meant to require a value.
+ */
+export declare function parseAgentAlias(value: unknown): AgentAlias;
+/**
+ * What a model does in a harness.
+ *
+ * `actuator` reads the page and emits the action: it receives the rendered
+ * accessibility tree and it runs on every step. `planner` decides where the run
+ * is going: it receives a distilled digest, never a tree, and it runs
+ * occasionally.
+ *
+ * The distinction is economic before it is architectural. Input dominates cost
+ * and input IS the snapshot — a measured 529,164 input tokens per minute on a
+ * content-heavy production run, which is the tree re-sent every step. A planner
+ * that saw that tree would cost 69x the per-minute price at frontier rates, so
+ * the pair only exists at all because the planner does not see it. Consumers may
+ * rely on that: the planner seam takes a digest type and has no tree parameter.
+ */
+export type AgentModelRole = 'planner' | 'actuator';
+/** One model, in one role, at one position in that role's failover order. */
+export interface AgentModelChoice {
+    /**
+     * The provider's own id, exactly as it goes on the wire to them — so
+     * `vendor/slug` for OpenRouter. The same string keys the rate card and the
+     * action cache, and a second spelling anywhere silently misses both.
+     */
+    readonly slug: string;
+    readonly role: AgentModelRole;
+    /**
+     * `0` is the model this role uses. `1` and up are tried in ascending order
+     * when a call to a lower rank fails in a way that another model could survive.
+     *
+     * Rank is the ordering contract, not array position. Do not sort this list and
+     * do not infer order from it.
+     */
+    readonly rank: number;
+    /**
+     * How many times this slot is invoked per agent step, as a harness decision.
+     *
+     * `1` for a slot the loop calls every step. A fraction for one it calls
+     * periodically: `0.2` is once every five steps. This is topology and not a
+     * measurement — it changes when the loop changes, never when traffic does —
+     * which is why it lives here and why no token count or price does.
+     */
+    readonly callsPerStep: number;
+}
+/**
+ * Which models each harness runs, and in what order it falls back.
+ *
+ * ── scout-1 ─────────────────────────────────────────────────────────────────
+ *
+ * One actuator, three ranks. Mercury drives; the two Gemini Flash models exist
+ * so that a rate limit or a decommissioned preview slug does not end a run.
+ *
+ * The ranks are not equally affordable and that is a live risk rather than a
+ * footnote. On the measured content-heavy burn Mercury costs roughly 1.4x the
+ * per-minute price and `google/gemini-3-flash-preview` costs roughly 17x, so the
+ * failover branch is where this alias loses money. The cost gate prices
+ * max-over-ranks precisely so that this is visible, and every demotion is
+ * logged, because failover share is the number nobody measures yet.
+ *
+ * ── voyager-1 ───────────────────────────────────────────────────────────────
+ *
+ * A pair, run concurrently: a reasoner that plans and an actuator that acts. The
+ * planner is deliberately the most capable model on the board and deliberately
+ * the one that never sees a page — it reads a digest, at one call per five
+ * steps. That combination is what makes hours-long autonomy priceable at all,
+ * and it is still planner-dominated: the planner is roughly three quarters of
+ * this alias's cost per minute on a content-heavy run and nearly all of it on an
+ * app-shaped one.
+ *
+ * The actuator is the same slug as scout-1's rank 0, which is not a coincidence
+ * to be tidied away — turning a plan into a click is the same job in both
+ * harnesses, and the cheapest model that does it well should do it in both.
+ *
+ * Both voyager slugs are OpenRouter `vendor/slug` ids, so both resolve to one
+ * provider. That satisfies the constraint `modelConfigFrom` already enforces for
+ * `OUTCRAWL_EXTRACT_MODEL` — one client holds one provider — without loosening
+ * it: the pair is two clients over one shared ledger, one per slot.
+ */
+export declare const AGENT_MODEL_CHAINS: Readonly<Record<AgentAlias, readonly AgentModelChoice[]>>;
+/** One harness's slots. Pure; the typed accessor for {@link AGENT_MODEL_CHAINS}. */
+export declare function agentModelChain(alias: AgentAlias): readonly AgentModelChoice[];
+/**
+ * The slots for one role, in failover order, or an empty list when the harness
+ * has no model in that role.
+ *
+ * Sorted by {@link AgentModelChoice.rank} here rather than trusting the table's
+ * order, so the ordering contract is enforced in one function instead of relied
+ * upon at every reader.
+ */
+export declare function agentModelsInRole(alias: AgentAlias, role: AgentModelRole): readonly AgentModelChoice[];
+/**
+ * Every distinct slug any harness can reach.
+ *
+ * The cost gate's enumeration point: each of these must have a price in the
+ * committed snapshot or the build fails, so adding a model to a chain forces the
+ * per-minute cost to be recalculated. Sorted for a stable diff.
+ */
+export declare function allAgentModelSlugs(): readonly string[];

package/dist/types/_deps/core/brand.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The brand icon set, as bytes.
+ *
+ * GENERATED by `node packages/browser/scripts/build-brand-icons.mjs` from
+ * `packages/browser/branding/logo.png` (512x512 RGBA). Do not hand-edit: run
+ * the script, which is also where the reasoning lives — why these sizes, why
+ * PNG payloads inside the .ico, why there is no SVG, and why the whole image
+ * pipeline is hand-written.
+ *
+ * WHY BYTES IN THE BUNDLE and not an R2 object, which was the other candidate.
+ * `/favicon.ico` is the single most requested path on any origin and the one a
+ * browser asks for without being told to. Fetching it from R2 puts a network
+ * call, an availability dependency and a cold-start latency spike underneath a
+ * request that must never fail — and the failure mode is a 404, which is the
+ * exact symptom this change exists to remove. Embedded, the answer is a slice
+ * of memory the isolate already holds: no round trip, no binding, nothing to be
+ * down, and correct on the first request after a deploy.
+ *
+ * The cost is bundle size, so it was measured rather than waved at:
+ * 28012 bytes of image data across 5 files
+ * — 27.4 KB against a 1 MB Worker limit. Decoded
+ * ONCE at module scope, not per request, so serving an icon allocates nothing
+ * beyond the `Response`.
+ */
+/** 32x32 PNG — the desktop tab, and the ICO fallback. */
+export declare const BRAND_ICON_32_BASE64: string;
+/** @see BRAND_ICON_32_BASE64 */
+export declare const BRAND_ICON_32: Uint8Array<ArrayBufferLike>;
+/** 180x180 PNG — apple-touch-icon: iOS home screen, the size Apple reads. */
+export declare const BRAND_ICON_180_BASE64: string;
+/** @see BRAND_ICON_180_BASE64 */
+export declare const BRAND_ICON_180: Uint8Array<ArrayBufferLike>;
+/** 192x192 PNG — the web app manifest, Android home screen. */
+export declare const BRAND_ICON_192_BASE64: string;
+/** @see BRAND_ICON_192_BASE64 */
+export declare const BRAND_ICON_192: Uint8Array<ArrayBufferLike>;
+/** 512x512 PNG — the manifest splash entry, and the MCP client icon. */
+export declare const BRAND_ICON_512_BASE64: string;
+/** @see BRAND_ICON_512_BASE64 */
+export declare const BRAND_ICON_512: Uint8Array<ArrayBufferLike>;
+/**
+ * `favicon.ico`, carrying 16, 32, 48px PNG entries.
+ *
+ * Still shipped, because the path is hardcoded in the client: a browser
+ * requests `/favicon.ico` from the root of an origin whether or not any page
+ * mentions it. That request is the one that was 404ing.
+ */
+export declare const BRAND_FAVICON_ICO_BASE64: string;
+/** @see BRAND_FAVICON_ICO_BASE64 */
+export declare const BRAND_FAVICON_ICO: Uint8Array<ArrayBufferLike>;
+/**
+ * The 32px icon as a `data:` URI, for an HTML surface to inline.
+ *
+ * A URI and not a path, and the reason is an invariant rather than a
+ * preference: a replay is a frozen artefact, and a self-contained export of one
+ * is a single HTML file that may be opened from disk with no origin at all. A
+ * `<link rel=icon href=/favicon.ico>` in that file resolves against wherever
+ * it happens to be opened — a 404 at best, somebody else's icon at worst.
+ * Inline bytes cannot miss, cost no request, and are already covered by the
+ * player's `img-src 'self' blob: data:` without widening it.
+ */
+export declare const BRAND_ICON_DATA_URI = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAwFBMVEUAAABLG/NLG/hNG/pMG/VLG/U2API6BfI8CPI+C/JBDvJCEPJEEvNFE/NLG/RLG/RHFvNLG/NLG/NNHPlOHPxNHvNQIvNPHf9UJ/RYK/RgNvRnPvVtRfVvSfVxS/V5VfZ+XfaFZPeLbPeOb/eWeviehPihiPiljfmpkvmslvmvmvmxnPmzn/m2ovq6qPrBsfrIufvKvPvNwPvQw/vZz/zc0/zf1/zi2vzl3v3q5P3t6f328/749v75+P77+v7////JaF8sAAAAQHRSTlMABA8PQYL//////////9fm//r/////////////////////////////////////////////////////////////zvITygAAAaxJREFUeNqFU11v2kAQnL019hkMTS2gEkkeouT//5z2uSIPtJg0iQ3Gvo/tA8a20ot6T6ududnZ0R2BhFXKhI9HXO0dCZNE2fxfGCCeKeeJEN3AEQAwXIfxpRDGq2WV8QVH00YdofYMAOQVG8W6u3++e6g7/HFTXxhOs0ptZ4DM8sEwM5un3KiuZ1OeXk0nhd+4wtvz5tvPXXa1Q5T3tvm4bJGgoegwc8MyAwFc3a8i2N/PmRs106E8Pa4VoObxPpG+q0Z4ngNVBazyyxIAgGgQ81O47R7re5UeEFAAFF5/ab17+9Ac/J5hvdbeoqGQSYmcfr+9zdOjOrAER8h3nRMtkx8Ij4CbfoEIFvozAh9beA9T0ycEs9ob5rZYtQiZ5Gb+ZHen9+LrXVXHEgjK3WC9eMM6weIFoSRpAq814FVMQYIYkAAgtBI0qUqAiAioOERw0+IPecDTyyEdHgRrGrI+zmIv6vQ8Slo4HuT4XGcTqrdt1BPIsp+5q4bEdZU021PSD5BJSWo+6Rlg48CTAWdTsjitfK9BcQQZcJSOybc8eqMio+Da0hL97/v/BWW4vDuRYfz0AAAAAElFTkSuQmCC";

package/dist/types/_deps/core/certificate.d.ts

@@ -0,0 +1,100 @@
+/**
+ * What a certificate says about itself, and the one function that reads it.
+ *
+ * WHY THIS IS IN `core` AND NOT BESIDE EITHER CALLER. Two packages must agree
+ * on this to the millisecond, for a reason that is the whole point of the
+ * feature:
+ *
+ *   `@outcrawl/worker` parses the PEM bytes it is about to hand to
+ *   `Bun.serve` and reports the result, so what it reports is provably the
+ *   certificate ON THE WIRE.
+ *
+ *   `@outcrawl/agent` parses the PEM on disk to decide whether to renew.
+ *
+ * Those two answers DIVERGE on purpose — a renewal that has landed on disk but
+ * whose worker has not been respawned yet shows a new file and an old wire —
+ * and that divergence is only legible if both sides derive their answer the
+ * same way. Two copies of "read notAfter out of a PEM" that disagreed by a
+ * timezone would make the interesting case unreadable.
+ *
+ * `node:crypto`'s `X509Certificate` does the parsing. It is in Bun and in
+ * workerd-free Node alike, and it means no ASN.1 parser here: this module
+ * consumes attacker-adjacent input (a PEM file), so unlike the DER *encoder*
+ * in `@outcrawl/agent`'s `acme.ts` it must not be hand-rolled.
+ */
+/**
+ * The leaf's own claims. Deliberately small: every field here is something an
+ * operator reads in `admin fleet` or an alert quotes.
+ */
+export interface CertificateFacts {
+    /** ISO 8601. The instant customers start failing handshakes. */
+    readonly notAfter: string;
+    readonly notBefore: string;
+    /** e.g. `CN=mac-01.fleet.outcrawl.ai`. */
+    readonly subject: string;
+    /**
+     * e.g. `C=US, O=Let's Encrypt, CN=R11`. The field that distinguishes a real
+     * certificate from a STAGING one, which is the mistake that looks correct
+     * from the machine and fails every client — see the same warning in
+     * `scripts/issue-fleet-cert.sh`.
+     */
+    readonly issuer: string;
+    /** Uppercase hex, no separators. Changes on every renewal, so it is the proof a renewal actually replaced anything. */
+    readonly serial: string;
+    /** DNS names this certificate is valid for, `subjectAltName` only. */
+    readonly dnsNames: readonly string[];
+}
+export declare class CertificateReadError extends Error {
+    readonly name = "CertificateReadError";
+}
+/**
+ * Reads the LEAF of a PEM chain.
+ *
+ * The leaf and not the whole chain: `fullchain.pem` starts with the leaf and
+ * continues with intermediates whose `notAfter` is years away, so a reader
+ * that took the last or the longest-lived block would report a comfortable
+ * date for an expired certificate. `X509Certificate` given a multi-block PEM
+ * parses the FIRST block, which is the leaf — asserted by the staging
+ * end-to-end run rather than assumed.
+ */
+export declare function readCertificateFacts(pem: string): CertificateFacts;
+/**
+ * Does this certificate cover `hostname`?
+ *
+ * Wildcard matching is included because the fleet is MID-MIGRATION: the live
+ * certificate is `*.fleet.outcrawl.ai` and the replacement is
+ * `mac-01.fleet.outcrawl.ai`, and during the cutover a machine must be able to
+ * recognise that the wildcard it already holds is still serving it and NOT
+ * treat that as "no usable certificate" and issue on every tick.
+ *
+ * One label only, and never the parent: `*.fleet.outcrawl.ai` matches
+ * `mac-01.fleet.outcrawl.ai` but not `a.b.fleet.outcrawl.ai` and not
+ * `fleet.outcrawl.ai`. That is RFC 6125 §6.4.3, and it is the reason
+ * `scripts/issue-fleet-cert.sh` orders the bare name alongside the wildcard.
+ */
+export declare function certificateCovers(facts: CertificateFacts, hostname: string): boolean;
+/**
+ * Whole days until `notAfter`, floored, and NEGATIVE once expired.
+ *
+ * Floored rather than rounded so "1 day left" never reads as 2, and signed
+ * rather than clamped at zero because "expired 3 days ago" and "expires in 3
+ * days" must not print identically in `admin fleet`.
+ */
+export declare function daysUntilExpiry(notAfter: string, now: number): number;
+/**
+ * Does this private key belong to this certificate?
+ *
+ * Compares the two SPKI encodings — the certificate's public key, and the
+ * public key derived from the private key. Equal DER means the pair matches.
+ *
+ * WORTH ITS OWN FUNCTION because a mismatched pair is a REAL failure class on
+ * this fleet, not a hypothetical. Today's certificate and key were issued on
+ * one machine and hand-copied to another, and a copy that picked up a new
+ * `fleet.crt` beside a stale `fleet.key` produces precisely the outage this
+ * whole ticket exists to prevent: the worker refuses to bind, or binds and
+ * fails every handshake, while the agent keeps dialling out and the fleet
+ * reports the machine healthy. Renewal writes two files, so it can introduce
+ * the same mismatch if it is ever interrupted between them — this is the check
+ * that makes that detectable instead of silent.
+ */
+export declare function certificateMatchesPrivateKey(certificatePem: string, privateKeyPem: string): boolean;

package/dist/types/_deps/core/cron.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Five-field cron expressions, and the only question anything asks of one:
+ * when is this next due?
+ *
+ * This lives in core because three packages need the same answer and any second
+ * implementation is a disagreement waiting to happen. The API refuses an
+ * unparseable schedule at `monitors.create`, the worker's scheduler computes the
+ * next run after each check, and the server's control plane clamps what a worker
+ * reports. If those three parsed cron differently, a monitor could be accepted
+ * by one, never selected by another, and rejected by the third — the silent
+ * never-fires failure the monitors work exists to end.
+ *
+ * **Everything is UTC.** `MonitorSpec.schedule` has no timezone field, the
+ * monitors table has no timezone column and the API takes no timezone
+ * parameter, so there is no tenant-local zone to resolve against. Inventing one
+ * here would be inventing a product feature in a parser, and the customer would
+ * have no way to see or set it. UTC is therefore explicit in every signature and
+ * every returned instant rather than left to whatever `TZ` the process booted
+ * with — a scheduler and a control plane that disagree about local midnight are
+ * the same class of bug as two cron parsers.
+ *
+ * No clock is read here. The instant is always a parameter, for the reason
+ * `packages/persistence/src/lease.ts` gives: the clock that matters belongs to
+ * the caller — the database's `now()` for a real decision, a fixed instant for a
+ * test or a replay.
+ *
+ * No dependencies and no `node:` imports: this runs on workerd as well as Bun.
+ */
+/**
+ * How many candidate days `nextRunAfter` examines before returning `null`.
+ *
+ * The bound is the point of the function. `0 0 30 2 *` is well-formed and can
+ * never match, and a scheduler that scanned for it forever would hang the
+ * process holding the lease — strictly worse than one monitor that never fires.
+ *
+ * Ten years, not the four you would guess. The longest legitimate gap between
+ * consecutive matches of any well-formed expression is `0 0 29 2 *`, and leap
+ * days are eight years apart across a skipped century — 2096-02-29 to
+ * 2104-02-29, because 2100 is not a leap year. A five-year horizon would report
+ * `null` for a valid expression, which is the silent-failure mode this whole
+ * bound exists to avoid. Ten years clears the worst real gap with room, and
+ * nothing that fails to match inside it can match at all.
+ *
+ * The cost of the bound is a loop over days, not minutes: 3660 iterations of
+ * three membership tests, which is microseconds.
+ */
+export declare const CRON_HORIZON_DAYS = 3660;
+/** Thrown by {@link parseCron}. Never thrown for a well-formed expression. */
+export declare class CronSyntaxError extends Error {
+    /**
+     * The offending field — `minute`, `hour`, `day-of-month`, `month`,
+     * `day-of-week` — or `expression` when the fault is the expression as a whole.
+     * Callers turning this into a 400 can point the customer at one token.
+     */
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * A parsed expression: every field expanded to the exact set of values it
+ * matches, sorted ascending, with no duplicates.
+ *
+ * Expanded rather than kept as syntax because matching a day then becomes three
+ * membership tests, and because two expressions that mean the same thing —
+ * `@daily` and `0 0 * * *`, `SUN` and `0` and `7` — become the same object.
+ */
+export interface CronSchedule {
+    /** 0-59. */
+    readonly minutes: readonly number[];
+    /** 0-23. */
+    readonly hours: readonly number[];
+    /** 1-31. Values above the length of a given month simply never match it. */
+    readonly daysOfMonth: readonly number[];
+    /** 1-12, January = 1. */
+    readonly months: readonly number[];
+    /** 0-6, Sunday = 0. A `7` in the expression is folded to `0` here. */
+    readonly daysOfWeek: readonly number[];
+    /**
+     * The day-of-month field did not begin with `*`. Together with
+     * {@link daysOfWeekRestricted} this decides whether the two day fields are
+     * combined with OR or with AND — see {@link nextRunAfter}.
+     */
+    readonly daysOfMonthRestricted: boolean;
+    /** The day-of-week field did not begin with `*`. */
+    readonly daysOfWeekRestricted: boolean;
+    /**
+     * The five fields as parsed, single-space separated, macros expanded. What
+     * `@daily` actually meant, in a form you can log or show back to a customer.
+     */
+    readonly expression: string;
+}
+/**
+ * Parses a five-field expression, or one of the `@` macros.
+ *
+ * Throws {@link CronSyntaxError} naming the offending field, what was received
+ * and what is allowed. The message reaches a customer through the API's 400, so
+ * "invalid cron" would be useless: they cannot fix a field they cannot identify.
+ */
+export declare function parseCron(expression: string): CronSchedule;
+/** True when {@link parseCron} would accept the expression. */
+export declare function isValidCron(expression: string): boolean;
+/**
+ * The first instant matching `expression` strictly after `after`, in UTC, with
+ * seconds and milliseconds zeroed. `null` when nothing matches within
+ * {@link CRON_HORIZON_DAYS}.
+ *
+ * **Strictly after**, and **truncated to the minute**, both for the same
+ * consumer. A cron expression's resolution is one minute, so a scheduler that
+ * stored a result equal to the instant it asked about would select the same
+ * check on the next tick and every tick after: an infinite loop that re-runs one
+ * monitor and starves the rest. `nextRunAfter(s, t)` is always greater than `t`.
+ *
+ * The search walks candidate *days* and only then matches hours and minutes.
+ * Minute-by-minute would be ~5.3 million iterations per call for the
+ * never-matching case, once per monitor per check.
+ */
+export declare function nextRunAfter(expression: string | CronSchedule, after: Date): Date | null;