@pome-sh/checks 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @pome-sh/checks
+
+## 0.1.0
+
+First release. Carries the grading vocabulary of all five digital twins so a
+publish + pin bump.
+
+- The five check arrays (`GITHUB_CHECKS`, `SLACK_CHECKS`, `STRIPE_CHECKS`,
+  `GMAIL_CHECKS`, `LINEAR_CHECKS`), keyed as `TWIN_CHECKS`.
+- Each twin's seed schema, `parseSeed` and default seed, prefixed by twin in the
+  barrel and under the twin's own names on the per-twin subpaths.
+- The check DSL from `@pome-sh/sdk/checks`, re-exported whole.
+
+`@pome-sh/sdk` and the five `@pome-sh/twin-*` packages stay `private: true`;
+their compiled output is inlined here by tsup, so this package declares zero
+`@pome-sh/*` runtime dependencies. `zod` is a peer dependency, never bundled, so
+a consumer's process holds exactly one zod schema identity.

package/README.md

@@ -0,0 +1,88 @@
+# `@pome-sh/checks`
+
+The grading vocabulary of Pome's five digital twins: the **check declarations**,
+the **seed schemas** and the **default seeds**, plus the **check DSL** they are
+written in.
+
+Declarations only. No twin server, no database, no HTTP routes, no tool
+dispatch. If you want to *run* a twin, install
+[`@pome-sh/cli`](https://www.npmjs.com/package/@pome-sh/cli) (`npx @pome-sh/cli
+twin start github`) or pull the twin's container image — this package cannot
+start one and does not try to.
+
+```bash
+npm install @pome-sh/checks zod
+```
+
+`zod` is a **peer dependency**, and installing your own copy is the point: the
+seed schemas are zod values, and two copies of zod in one process means two
+schema identities — `instanceof` fails and parsed results stop being
+interchangeable. One zod, one identity.
+
+## What it is for
+
+A Pome task scores an agent with criteria. A `[code]` criterion is graded by a
+**check**: a declared, templated assertion over the twin's final state, its seed
+compared against its final state, or the recorded tape of tool calls. This
+package is where those declarations live, so the thing that grades a run and the
+twin that produced it agree on the vocabulary rather than each keeping its own
+copy of it.
+
+## Use
+
+Everything under one specifier, with the seed helpers prefixed by twin:
+
+```ts
+import { GITHUB_CHECKS, TWIN_CHECKS, parseGitHubSeed, renderCheck } from "@pome-sh/checks";
+
+const check = GITHUB_CHECKS.find((c) => c.id === "github.issue-closed");
+```
+
+Or one twin at a time, keeping that twin's own names:
+
+```ts
+import { GITHUB_CHECKS, parseSeed, seedSchema } from "@pome-sh/checks/github";
+```
+
+Subpaths: `./github`, `./slack`, `./stripe`, `./gmail`, `./linear`, and `./dsl`
+for the DSL alone.
+
+| Export | What |
+| --- | --- |
+| `GITHUB_CHECKS`, `SLACK_CHECKS`, `STRIPE_CHECKS`, `GMAIL_CHECKS`, `LINEAR_CHECKS` | Each twin's declarations, in authoring order |
+| `TWIN_CHECKS` | The five arrays keyed by twin id |
+| `CHECKS_TWIN_NAMES`, `ChecksTwinName` | The five twin ids, and the type derived from them |
+| `parse<Twin>Seed`, `<twin>SeedSchema`, `default<Twin>Seed` | Seed contract per twin |
+| `defineCheck`, `parseCheck`, `renderCheck`, `checkPattern`, `checksDigest`, `templateSlots`, `statePath`, `childStatePath` | The DSL |
+| `GitHubCheck`, `GmailCheck`, `LinearCheck`, `SlackCheck`, `StripeCheck` | Each twin's check element type. Every twin declares its own `Check<TArgs>` over its own state, so the barrel prefixes them; the per-twin subpaths keep the plain name `Check` |
+| `CheckDefinition`, `Check…State` types | The generic declaration type, and each twin's state shape — what you want when the twin is a parameter rather than known |
+| `VACUITY_SENTINEL`, `VACUITY_SENTINEL_NUMBER`, `VACUITY_SENTINEL_SNAKE` | The values that mark an assertion no state can satisfy |
+
+`applySeed` and `loadSeedFromEnv` are **not** exported. The first writes rows
+into a live SQLite database and the second reads `process.env`; both are twin
+runtime behaviour, not declarations.
+
+## Versioning
+
+Pre-1.0, so `^0.x` caret semantics apply and **minor plays the major role**:
+
+- **Minor (`0.N+1.0`)** — anything a consumer must act on: a check id renamed or
+  removed, a template changed, a polarity flipped, a seed schema tightened, an
+  `engines` floor bump.
+- **Patch (`0.N.x`)** — additive checks or exports, wording that does not change
+  a pattern, internal implementation swaps behind an unchanged surface.
+
+A grading vocabulary is a contract in a stricter sense than a normal library: a
+renamed check id does not break a build, it silently stops binding, and a
+criterion that stops binding scores nothing. Treat every id as public.
+
+## Where the source lives
+
+Nowhere in this package. Every declaration is re-exported from the twin that
+owns it (`packages/twin-*/src/check-*.ts`) and the DSL from
+`packages/sdk/src/checks.ts`, all in
+[pome-sh/digital-twins](https://github.com/pome-sh/digital-twins). Their
+compiled output is inlined here at build time, so this package declares no
+`@pome-sh/*` dependency and there is no second copy to drift.
+
+Licence: Apache-2.0.

package/dist/_types/sdk/check-discrimination.d.ts

@@ -0,0 +1,7 @@
+import type { CheckDefinition, DiscriminationVerdict } from "./checks.js";
+/**
+ * Run a check against the worlds it names and say whether they actually
+ * discriminate. Pure: no vitest, no ledger — each twin's contract test owns the
+ * ledger half, so an empty ledger cannot silently excuse anything.
+ */
+export declare function probeDiscrimination<TState, TArgs extends Record<string, string>>(def: CheckDefinition<TState, TArgs>, args: TArgs): DiscriminationVerdict;

package/dist/_types/sdk/check-state-path.d.ts

@@ -0,0 +1,71 @@
+import type { CheckDefinition } from "./checks.js";
+/**
+ * A pointer from the ROOT of the exported tree.
+ *
+ * Numbers are array indices and strings are object keys, but this function does
+ * not enforce that — the tree decides, at resolution time. Passing no segments
+ * returns `""`, which RFC 6901 defines as the whole document; a check with
+ * nothing narrower to name must OMIT `evidenceStatePaths` rather than cite the
+ * root, for the same reason it must omit rather than send `[]`.
+ */
+export declare function statePath(...segments: readonly (string | number)[]): string;
+/**
+ * A pointer relative to one a resolver already built.
+ *
+ * The twins' `resolve*` helpers walk the tree to find an entity and now hand
+ * back the pointer they walked; a check appends the field it went on to read.
+ * Written as its own function rather than string concatenation at 37 call sites
+ * because the escaping has to happen on the appended segments and NOT on the
+ * base, which already contains real `/` separators — concatenating by hand is
+ * how a `~1` ends up double-encoded.
+ */
+export declare function childStatePath(base: string, ...segments: readonly (string | number)[]): string;
+/**
+ * What a pointer addresses in a tree, or `null` when it addresses nothing.
+ *
+ * `null` is a NORMAL answer and every caller must handle it: the state blob a
+ * report renders can be a different export from the one the check read (a
+ * re-run, a truncated upload, a snapshot predating a field). A consumer turns
+ * `null` into "no affordance", exactly as `findEventIndexForEvidence` turns an
+ * unresolvable event id into one.
+ *
+ * Wrapped in `{ value }` rather than returned bare because `undefined` and
+ * `null` are both legal JSON-ish values a tree can hold at a pointer, and a bare
+ * return could not tell "the path is absent" from "the path holds null" — the
+ * difference between no evidence and evidence that the field is empty.
+ */
+export declare function resolveStatePath(tree: unknown, pointer: string): {
+    value: unknown;
+} | null;
+export type StateCitationArm = "passing" | "failing";
+export type StateCitationVerdict = {
+    kind: "cites";
+} | {
+    kind: "declined";
+} | {
+    kind: "uncited";
+    arm: StateCitationArm;
+} | {
+    kind: "unresolvable";
+    arm: StateCitationArm;
+    pointer: string;
+} | {
+    kind: "malformed";
+    arm: StateCitationArm;
+    detail: string;
+};
+/**
+ * Does this state-reading check say WHERE it looked, in a form that resolves?
+ *
+ * Probes BOTH arms, and that is deliberate. A citation present on the passing
+ * world and absent on the failing one is worse than no citation at all: its
+ * absence starts reading as a verdict class — "no evidence" would come to mean
+ * "this one failed" — and the reader has no way to know that is an accident of
+ * how the predicate was written. So a check must be able to say where it looked
+ * whether or not it liked what it found there.
+ *
+ * Only meaningful for `final` / `seed+final` checks. A `tape` check cites
+ * `evidenceEventIds` instead and is not this gate's business; callers filter on
+ * `substrate` before probing.
+ */
+export declare function probeStateCitation<TState, TArgs extends Record<string, string>>(def: CheckDefinition<TState, TArgs>, args: TArgs): StateCitationVerdict;

package/dist/_types/sdk/checks.d.ts

@@ -0,0 +1,93 @@
+export type CheckPolarity = "positive" | "negative";
+export declare const VACUITY_SENTINEL = "pome-vacuity-never";
+export declare const VACUITY_SENTINEL_SNAKE = "pome_vacuity_never";
+export declare const VACUITY_SENTINEL_NUMBER = 987654321;
+export type CheckSubstrateKind = "final" | "seed+final" | "tape";
+export interface CheckParamType {
+    readonly name: string;
+    readonly pattern: string;
+    readonly example: string;
+    render(value: string): string;
+    parse(raw: string): string;
+}
+export declare const repoRef: CheckParamType;
+export declare function oneOf(name: string, values: readonly string[], example?: string): CheckParamType;
+export interface CheckOutcome {
+    passed: boolean;
+    reason: string;
+    status?: "passed" | "failed" | "unmatched" | "skipped";
+    evidenceEventIds?: string[];
+    evidenceStatePaths?: string[];
+}
+export interface CheckTapeEvent {
+    ts?: string | null;
+    twin?: string | null;
+    method?: string | null;
+    path?: string | null;
+    request_body?: unknown;
+    request_headers?: Record<string, string>;
+    status?: number | null;
+    response_body?: unknown;
+    latency_ms?: number | null;
+    fidelity?: string | null;
+    state_mutation?: boolean | null;
+    error?: string | null;
+    tool?: string | null;
+    event_id?: string | null;
+}
+export interface CheckSubstrate<TState> {
+    seed: TState | null;
+    final: TState;
+    tape: readonly CheckTapeEvent[] | null;
+}
+export interface CheckWorlds<TState> {
+    passing: CheckSubstrate<TState>;
+    failing: CheckSubstrate<TState>;
+}
+export type DiscriminationArm = "passing" | "failing" | "degenerate";
+export type DiscriminationVerdict = {
+    kind: "discriminates";
+} | {
+    kind: "declined";
+} | {
+    kind: "broken";
+    arm: DiscriminationArm;
+    detail: string;
+};
+export interface CheckDefinition<TState, TArgs extends Record<string, string>> {
+    id: string;
+    description: string;
+    template: string;
+    params: {
+        [K in keyof TArgs]: CheckParamType;
+    };
+    substrate: CheckSubstrateKind;
+    polarity(args: TArgs): CheckPolarity;
+    subject?(args: TArgs): string | null;
+    vacuityMutant(args: TArgs): TArgs | null;
+    discriminatingWorlds(args: TArgs): CheckWorlds<TState> | null;
+    evaluate(args: TArgs, substrate: CheckSubstrate<TState>): CheckOutcome;
+}
+export declare function templateSlots(template: string): {
+    literals: string[];
+    params: string[];
+};
+type ArgsOfParams<TParams extends Record<string, CheckParamType>> = {
+    [K in keyof TParams]: string;
+};
+export declare function defineCheck<TState, TParams extends Record<string, CheckParamType>>(def: Omit<CheckDefinition<TState, ArgsOfParams<TParams>>, "params"> & {
+    params: TParams;
+}): CheckDefinition<TState, ArgsOfParams<TParams>>;
+export declare function renderCheck<TState, TArgs extends Record<string, string>>(def: CheckDefinition<TState, TArgs>, args: TArgs): string;
+export interface CheckBindingShape {
+    readonly id: string;
+    readonly template: string;
+    readonly substrate: CheckSubstrateKind;
+    readonly params: Readonly<Record<string, CheckParamType>>;
+}
+export declare function checkPattern(def: CheckBindingShape): RegExp;
+export declare function checksDigest(defs: readonly CheckBindingShape[]): string;
+export declare function checkNearMissPattern(def: CheckBindingShape): RegExp;
+export declare function parseCheck<TState, TArgs extends Record<string, string>>(def: CheckDefinition<TState, TArgs>, text: string): TArgs | null;
+export { probeDiscrimination } from "./check-discrimination.js";
+export { statePath, childStatePath, resolveStatePath, probeStateCitation, type StateCitationArm, type StateCitationVerdict, } from "./check-state-path.js";

package/dist/_types/sdk/db.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Mutation outcome — the shape both better-sqlite3's `RunResult` and
+ * node:sqlite's `StatementResultingChanges` return; `changes` is coerced to
+ * number, `lastInsertRowid` may be a bigint for rowids beyond safe-integer
+ * range.
+ */
+export interface TwinRunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+export interface TwinStatement {
+    run(...params: unknown[]): TwinRunResult;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+/**
+ * A wrapped transaction function (better-sqlite3's shape). The `.immediate`
+ * variant takes the write lock up front (BEGIN IMMEDIATE) — github's domain
+ * runs its mutations under it.
+ */
+export type TwinTransaction<F extends (...args: never[]) => unknown> = F & {
+    immediate: F;
+};
+export interface TwinDatabase {
+    prepare(sql: string): TwinStatement;
+    exec(sql: string): void;
+    pragma(statement: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    /** Same shape as better-sqlite3: wraps `fn` so calling it runs atomically. */
+    transaction<F extends (...args: never[]) => unknown>(fn: F): TwinTransaction<F>;
+    close(): void;
+}
+export interface OpenTwinDatabaseOptions {
+    /** Schema migration hook, run once right after the pragmas are applied. */
+    migrate?: (db: TwinDatabase) => void;
+}
+/**
+ * Open a twin database with the pome pragma set applied:
+ * `busy_timeout = 5000`, `journal_mode = WAL` (file-backed), and
+ * `foreign_keys = ON` — the exact pragmas every twin's hand-rolled db.ts
+ * applied before F-681 centralized them.
+ */
+export declare function openTwinDatabase(path?: string, options?: OpenTwinDatabaseOptions): TwinDatabase;

package/dist/_types/sdk/failure-injection-rules.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+export declare const FAILURE_INJECTION_OVERRIDE_KEY = "failureInjectionOverride";
+export type FailureInjectionOverride = {
+    status: number;
+    body: unknown;
+};
+export type FailureInjectionMode = "before_handler" | "after_handler";
+export type FailureInjectionRule = {
+    method: string;
+    path: string;
+    attempt: number;
+    mode: FailureInjectionMode;
+    status: number;
+    body: unknown;
+};
+export declare const failureInjectionRuleSchema: z.ZodObject<{
+    method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    path: z.ZodString;
+    attempt: z.ZodNumber;
+    mode: z.ZodDefault<z.ZodEnum<{
+        before_handler: "before_handler";
+        after_handler: "after_handler";
+    }>>;
+    status: z.ZodNumber;
+    body: z.ZodUnknown;
+}, z.core.$strip>;
+export type FailureInjectionStore = {
+    setRules(rules: FailureInjectionRule[]): void;
+    clear(): void;
+    matchAndConsume(accountId: string, method: string, path: string): FailureInjectionRule | null;
+};
+export declare function createFailureInjectionStore(): FailureInjectionStore;

package/dist/_types/twin-github/src/check-kind.d.ts

@@ -0,0 +1,3 @@
+import type { CheckDefinition } from "../../sdk/checks.js";
+import type { GitHubCheckState } from "./check-state.js";
+export type Check<TArgs extends Record<string, string>> = CheckDefinition<GitHubCheckState, TArgs>;

package/dist/_types/twin-github/src/check-state.d.ts

@@ -0,0 +1,77 @@
+import { type CheckOutcome } from "../../sdk/checks.js";
+export interface GitHubCheckStateLabel {
+    name?: string;
+}
+export interface GitHubCheckStateComment {
+    body?: string;
+}
+export interface GitHubCheckStateIssue {
+    number?: number;
+    state?: string | null;
+    labels?: GitHubCheckStateLabel[] | null;
+    assignees?: string[] | null;
+    comments?: GitHubCheckStateComment[] | null;
+}
+export interface GitHubCheckStateReview {
+    state?: string | null;
+}
+export interface GitHubCheckStatePullRequest {
+    number?: number;
+    state?: string | null;
+    merged?: number | boolean | null;
+    reviews?: GitHubCheckStateReview[] | null;
+    comments?: GitHubCheckStateComment[] | null;
+}
+export interface GitHubCheckStateCommitStatus {
+    context?: string;
+    state?: string | null;
+}
+export interface GitHubCheckStateFile {
+    path?: string;
+    branch?: string;
+}
+export interface GitHubCheckStateRepo {
+    owner?: string;
+    name?: string;
+    full_name?: string;
+    labels?: GitHubCheckStateLabel[] | null;
+    files?: GitHubCheckStateFile[] | null;
+    issues?: GitHubCheckStateIssue[] | null;
+    pull_requests?: GitHubCheckStatePullRequest[] | null;
+    commit_statuses?: GitHubCheckStateCommitStatus[] | null;
+}
+export interface GitHubCheckState {
+    repositories?: GitHubCheckStateRepo[] | null;
+}
+export declare function findRepo(state: GitHubCheckState, ref: string): {
+    repo: GitHubCheckStateRepo;
+    index: number;
+} | null;
+export declare function issueNumbers(repo: GitHubCheckStateRepo): Set<number>;
+export declare function labelNames(repo: GitHubCheckStateRepo): Set<string>;
+export type Resolved<T> = {
+    found: T;
+    path: string;
+} | {
+    missing: string;
+    searched?: string;
+};
+/**
+ * The `failed` outcome a missing entity produces, citing where the lookup
+ * looked.
+ *
+ * One function rather than a conditional spread at every `if ("missing" in …)`
+ * site, because the rule it encodes — cite the searched collection, cite nothing
+ * when there was none — is one rule, and twelve hand-written copies of it is
+ * twelve chances for one to quietly drop the citation.
+ */
+export declare function missOutcome(miss: {
+    missing: string;
+    searched?: string;
+}): CheckOutcome;
+export declare function resolveRepo(state: GitHubCheckState, ref: string, where: string): Resolved<GitHubCheckStateRepo>;
+export declare function resolveIssue(state: GitHubCheckState, ref: string, number: string): Resolved<GitHubCheckStateIssue>;
+export declare function resolvePullRequest(state: GitHubCheckState, ref: string, number: string): Resolved<GitHubCheckStatePullRequest>;
+export declare function isMerged(pull: GitHubCheckStatePullRequest): boolean;
+export declare function sameLabel(a: string, b: string): boolean;
+export declare function appliedLabelNames(issue: GitHubCheckStateIssue): string[];

package/dist/_types/twin-github/src/checks.d.ts

@@ -0,0 +1,50 @@
+export type { Check } from "./check-kind.js";
+export type { GitHubCheckState, GitHubCheckStateComment, GitHubCheckStateCommitStatus, GitHubCheckStateFile, GitHubCheckStateIssue, GitHubCheckStateLabel, GitHubCheckStatePullRequest, GitHubCheckStateRepo, GitHubCheckStateReview, } from "./check-state.js";
+export declare const GITHUB_CHECKS: readonly [import("./check-kind.js").Check<{
+    issue: string;
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    issue: string;
+    repo: string;
+    state: string;
+}>, import("./check-kind.js").Check<{
+    issue: string;
+    repo: string;
+    label: string;
+}>, import("./check-kind.js").Check<{
+    issue: string;
+    repo: string;
+    label: string;
+}>, import("./check-kind.js").Check<{
+    issue: string;
+    repo: string;
+    login: string;
+}>, import("./check-kind.js").Check<{
+    needle: string;
+    issue: string;
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    pr: string;
+    repo: string;
+    state: string;
+}>, import("./check-kind.js").Check<{
+    pr: string;
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    review: string;
+    pr: string;
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    path: string;
+    repo: string;
+}>, import("./check-kind.js").Check<{
+    context: string;
+    repo: string;
+    state: string;
+}>, import("./check-kind.js").Check<Record<string, never>>, import("./check-kind.js").Check<{
+    tool: string;
+}>];

package/dist/_types/twin-github/src/seed.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import type { GitHubStateSeed } from "./types.js";
+export declare const seedSchema: z.ZodObject<{
+    users: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        login: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            User: "User";
+            Organization: "Organization";
+        }>>;
+        name: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+    repositories: z.ZodArray<z.ZodObject<{
+        owner: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+        private: z.ZodDefault<z.ZodBoolean>;
+        default_branch: z.ZodDefault<z.ZodString>;
+        collaborators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        labels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            color: z.ZodDefault<z.ZodString>;
+            description: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+        files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            content: z.ZodString;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        issues: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            number: z.ZodOptional<z.ZodNumber>;
+            title: z.ZodString;
+            body: z.ZodDefault<z.ZodString>;
+            state: z.ZodDefault<z.ZodEnum<{
+                open: "open";
+                closed: "closed";
+            }>>;
+            labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            assignees: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        pull_requests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            number: z.ZodOptional<z.ZodNumber>;
+            title: z.ZodString;
+            body: z.ZodDefault<z.ZodString>;
+            head: z.ZodString;
+            base: z.ZodDefault<z.ZodString>;
+            state: z.ZodDefault<z.ZodEnum<{
+                open: "open";
+                closed: "closed";
+            }>>;
+            author: z.ZodOptional<z.ZodString>;
+            reviews: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                author: z.ZodString;
+                state: z.ZodDefault<z.ZodEnum<{
+                    APPROVED: "APPROVED";
+                    CHANGES_REQUESTED: "CHANGES_REQUESTED";
+                    COMMENTED: "COMMENTED";
+                }>>;
+                body: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>>;
+            statuses: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                context: z.ZodDefault<z.ZodString>;
+                state: z.ZodDefault<z.ZodEnum<{
+                    error: "error";
+                    failure: "failure";
+                    pending: "pending";
+                    success: "success";
+                }>>;
+                description: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ParsedGitHubStateSeed = z.output<typeof seedSchema>;
+export declare function parseSeed(input: unknown): ParsedGitHubStateSeed;
+/**
+ * Boot-time seed loader: prefer `POME_SEED_JSON` env (set by the cloud
+ * control-plane from the CLI-supplied scenario seed; see FDRS-353) and
+ * fall back to `defaultSeedState()` when the env is absent. Throws on
+ * malformed JSON or schema-invalid seed, so a misconfigured cloud
+ * deploy fails the twin server's healthz instead of silently booting
+ * with the default world.
+ */
+/**
+ * `Record<string, string | undefined>` rather than `NodeJS.ProcessEnv`, which is
+ * structurally the same thing but an AMBIENT global. This signature is vendored
+ * into `@pome-sh/checks`'s published declarations, and an ambient reference there
+ * makes a consumer's `tsc` fail with TS2503 unless they happen to have
+ * `@types/node` installed — a dependency this package should not impose to
+ * describe a plain string map.
+ */
+export declare function loadSeedFromEnv(env?: Record<string, string | undefined>): ParsedGitHubStateSeed;
+export declare function defaultSeedState(): GitHubStateSeed;