@prampta/sdk 0.9.1 → 0.11.0

package/README.md

@@ -13,7 +13,7 @@ support is not claimed: CommonJS loads the ESM-only crypto dependency through
 [`require(esm)`](https://nodejs.org/en/blog/release/v20.19.0). Local ESM/CommonJS
 smoke tests run on Node 22.20; a wider runtime/browser matrix is still a release gate.
 
-This README describes SDK 0.7.0.
+This README describes SDK 0.11.0; sections name the version that added them.
 In older 0.4.0, `assertAllowed` throws on
 personal-use `not_blocked` and `PramptaReporter` is unavailable. Use `verify()`
 and inspect `disposition` when supporting older installations;
@@ -36,6 +36,119 @@ production PRAMPTA deployment running the v1.0.0-default trust posture
 refuses it with `PG_NO_PAIR`. Don't build a new integration against it; it
 exists solely so an already-connected provider keeps working mid-migration.
 
+## PRE-GEN v5: one setup, one call (0.11.0, `/v2`)
+
+`createPregen` speaks the simplified PRE-GEN v5 formats at `/v2`: signed
+answers bound to your request, signed reports, signed acknowledgements. Set it
+up once; wrap each generation in one call. Use 0.11.0 or later: 0.10.0 had
+defects found by an external review (see CHANGELOG).
+
+```typescript
+import pg from "pg";
+import { createPregen, postgresStore, loadPregenDirectory, NotGeneratedError } from "@prampta/sdk";
+
+const pregen = createPregen({
+  baseUrl: "https://api2.prampta.com",
+  providerId: "my-ai",
+  token: process.env.PRAMPTA_TOKEN!,                      // your exchange_secret, server-side only
+  providerSigningKeyHex: process.env.PREGEN_SIGNING_KEY!, // your Ed25519 private key (32 bytes hex): signs your reports
+  pregenDirectory: await loadPregenDirectory({ previous: saved }), // PRAMPTA's keys, namespaces, revocations
+  store: postgresStore(new pg.Pool()),                    // shared by all your workers; table pregen_jobs
+});
+
+await pregen.registerKey();                    // once (again is harmless): registers your public key
+setInterval(() => pregen.flush(), 60_000);     // and at startup: resends reports still waiting
+
+const result = await pregen.generate(
+  { jobId: task.id,                            // YOUR stable task id: a retry reuses it, a new generation gets a new one
+    subjects: ["PG-..."],                      // everyone in the output
+    prompt, model: "my-model", modality: "image", use: { purpose: "commercial" },
+    licenseeId },                              // the connected user, or omit for a provider-level request
+  async ({ obligations }) => {
+    if (queueFull) throw new NotGeneratedError("queue full");   // ONLY when you are sure nothing was produced
+    const image = await render(prompt, obligations);            // YOU apply the obligations
+    return { output: image, outputBytes: image.bytes, obligationsApplied: obligations };  // the ones you carried out
+  },
+);
+```
+
+**What one call does.** Checks and copies your input before anything else
+(changing your object afterwards changes nothing). Asks the registry about
+every subject under one job hash; verifies every answer: your pinned key, the
+directory if given, every field of the body, bound to your request, times. In
+`enforce` mode generates only when **all** subjects allow, re-checking right
+before your function runs. Stores the outcome and the signed reports
+**before** sending them, and counts a report as filed only when the
+registry's signed acknowledgement matches it: the report, the answer, its
+status, your key.
+
+**The result tells you where the job stands:**
+
+| `status` | Meaning | What you do |
+|---|---|---|
+| `confirmed` | Finished; every report acknowledged. `generated` says whether it generated. | Nothing. |
+| `report_pending` | Finished; a report has not been acknowledged yet (network, outage). | Nothing: `flush()` resends it, byte for byte. |
+| `needs_check` | The outcome is unknown: your function threw, the job was interrupted after it may have started generating, or it is running in another worker; or the registry refused a report for good. | Find this `jobId` in your generator, then `pregen.resolve(jobId, { generated: true, outputBytes })` or `{ generated: false }`. |
+
+**When your function throws.** An error does not prove that nothing was
+produced: a connection reset can arrive after the generator accepted the job.
+So any error leaves the job `needs_check`, nothing is reported, and the use
+stays reserved until you `resolve()` it. Throw `NotGeneratedError` only when
+you are sure the generator never started; then the use is given back at once.
+
+The same `jobId` never generates twice: calling again returns where the job
+stands. The same `jobId` with a different generation is refused
+(`PG_JOB_CONFLICT`). Several workers may call `resolve()` or `flush()` for the
+same job at once: the first recorded outcome stands and everyone sends that
+one report.
+
+**Obligations** are handed to your function per subject (`{ subject, id,
+params }`). Return the ones you carried out in `obligationsApplied`; the
+report lists them, and any you did not apply come back in `unmetObligations`.
+How to apply a watermark or a disclosure depends on your medium (image,
+video, audio) and is yours to implement.
+
+**Which subjects.** You name them. Matching names in a prompt
+(`matchSubjects`) only suggests candidates; faces, voices and uploaded
+references are for your own pipeline to identify.
+
+**`mode`** is `enforce` (default) or `observe`; anything else is refused when
+you create the client. `observe` generates whatever the answers say and
+reports every generation. Nothing is blocked and nothing is granted: use it
+to trial the integration, then switch to `enforce`; nothing else changes.
+
+**Registry keys.** With `pregenDirectory` the SDK takes the registry's keys
+from its key set, keeping only those the steward-signed directory lists and
+has not revoked (the steward key is built into `@pregen/verify`); answers and
+acknowledgements must be signed by one of them. Without a directory, pin them
+yourself with `operatorPublicKeyHex`, obtained independently.
+
+**Your signing key.** Reports must be signed. `registerKey()` sends a `first`
+keyset signed by the key it names. After that, the registry also requires
+your `/v1` receipts to be signed with the same key (`providerSigningKeyHex`
+in `submitReceipt`). To replace the key, `rotateKey(newKeyHex)` sends a
+`rotation` keyset signed by both keys; then create the client again with the
+new key in every worker. Acknowledged reports stand; reports still waiting,
+or sent by a worker that still has the old key, are signed again with the
+new key by the next `flush()`. Recovering a lost key through the registry is
+not available yet. A provider's keysets are public: `GET /v2/keys/{provider_id}`.
+
+**Limits.** Per IP address, 200 requests and 300 reports a minute. Above
+them a job is not generated (`error: "HTTP_429"` in its answers) and waiting
+reports go out with the next `flush()`.
+
+**Stores.** `postgresStore(pool)` takes any node-postgres `Pool`, `Client` or
+pooled client (the `pg` package is yours; the SDK does not depend on it). It
+creates its table on first use under a lock, so many workers may start at
+once; if your database role may not create tables, run `postgresSchema` in
+your migrations. `memoryStore()` is for tests and a single process: it is
+lost on restart. A custom store must make `claim` and `update` atomic.
+
+Not in this release: Python, other stores, several registries in one job,
+key recovery through the registry. The directory is checked in the
+`pregen.registries.v2` format of `@pregen/verify` 0.7.0. From zero, with the
+failures to handle before production: https://prampta.com/get-started-v2.md.
+
 ## Quick Start: the safe setup (0.9.0)
 
 One configuration turns on every check: the signed PRE-GEN directory, your

package/dist/index.d.mts

@@ -122,6 +122,193 @@ declare class PramptaReporter {
     deliver(event: Observation): Promise<DeliveryResult>;
 }
 
+type Envelope = {
+    type: string;
+    body: Record<string, any>;
+    signatures: string[];
+};
+type Purpose = "personal" | "educational" | "research" | "editorial" | "commercial";
+interface Obligation {
+    subject: string;
+    id: string;
+    params: Record<string, unknown>;
+}
+interface PregenConfig {
+    baseUrl: string;
+    providerId: string;
+    /** Your runtime credential (`exchange_secret`). */
+    token: string;
+    /** Your Ed25519 private key, 32 bytes hex. Signs reports; register its public key once with `registerKey()`. */
+    providerSigningKeyHex: string;
+    /** The registry's public key(s), hex, obtained independently, not from its API. Optional with `pregenDirectory`:
+     * the keys are then taken from the registry's key set, keeping only those the signed directory lists. */
+    operatorPublicKeyHex?: string | string[];
+    store: PregenStore;
+    /** `enforce` (default): generate only when every subject allows. `observe`: generate anyway and report; nothing is
+     * blocked or granted. Any other value is refused. */
+    mode?: "enforce" | "observe";
+    /** The PRE-GEN directory (`loadPregenDirectory()`): the registry must own each subject's namespace, and every answer
+     * and acknowledgement must be signed by a key the directory lists for it and has not revoked. Recommended. */
+    pregenDirectory?: Directory;
+    timeoutMs?: number;
+}
+interface PregenJobInput {
+    /** Your own stable id for this generation, e.g. your task id. Calling again with the same id
+     * never generates twice; a new generation needs a new id. */
+    jobId: string;
+    /** PRE-GEN codes of everyone in the output. Name matching can suggest them; you decide. */
+    subjects: string[];
+    /** Hashed locally; never sent. */
+    prompt?: string;
+    promptHash?: string;
+    model: string;
+    modality: string;
+    use: {
+        purpose: Purpose;
+        rights?: string[];
+        territory?: string;
+        channel?: string;
+    };
+    /** The connected end user's licensee id; empty for a provider-level request. */
+    licenseeId?: string;
+}
+type GenerateFn<T> = (ctx: {
+    obligations: Obligation[];
+}) => Promise<{
+    output: T;
+    /** One of these is required: the SHA-256 of the output, or the bytes to hash. */
+    outputHash?: string;
+    outputBytes?: Uint8Array | string;
+    /** The obligations you applied, per subject: return the ones from `obligations` you carried out. */
+    obligationsApplied?: {
+        subject: string;
+        id: string;
+    }[];
+}>;
+/** Throw this from your generator only when you are sure it produced nothing (it never started). Any other error
+ * leaves the outcome unknown: the job becomes `needs_check` and nothing is reported until you `resolve()` it. */
+declare class NotGeneratedError extends Error {
+    readonly notGenerated = true;
+    constructor(message?: string);
+}
+interface AskResult {
+    subject: string;
+    status: "allow" | "deny" | "review" | "not_blocked" | null;
+    reason?: string;
+    /** Why the answer is missing or unusable: PG_UNREACHABLE, PG_SIGNATURE, PG_MALFORMED, PG_TIME, PG_BINDING... */
+    error?: string;
+}
+interface PregenResult<T = unknown> {
+    jobId: string;
+    /** confirmed: finished, every report acknowledged. report_pending: finished, a report waits
+     * for acknowledgement; `flush()` resends it. needs_check: the outcome is unknown (interrupted, the generator threw,
+     * or running in another worker) or the registry refused a report; check, then `resolve()`. */
+    status: "confirmed" | "report_pending" | "needs_check";
+    /** null while the outcome is unknown. */
+    generated: boolean | null;
+    /** Only from the call that generated. */
+    output?: T;
+    outputHash?: string;
+    answers: AskResult[];
+    /** Obligations the answers set that `obligationsApplied` did not list. */
+    unmetObligations: Obligation[];
+    detail?: string;
+}
+type Stage = "claimed" | "asked" | "finished" | "done";
+/** One job as the store keeps it. */
+interface PregenJob {
+    providerId: string;
+    jobId: string;
+    /** SHA-256 of the manifest; the same job id with another manifest is refused. */
+    jobHash: string;
+    /** claimed: one worker owns it. asked: answers stored, generation may have started.
+     * finished: outcome and signed reports stored, some not acknowledged. done: nothing left to send. */
+    stage: Stage;
+    asks: {
+        request: Record<string, any>;
+        answer: Envelope | null;
+        error?: string;
+    }[];
+    generated?: boolean;
+    outputHash?: string;
+    unmetObligations?: Obligation[];
+    /** `rejected`: the registry refused this report for good (it holds a different one, or found it malformed). */
+    reports: {
+        subject: string;
+        answerStatus: string;
+        report: Envelope;
+        ack?: Envelope;
+        rejected?: boolean;
+        error?: string;
+    }[];
+}
+interface PregenStore {
+    /** ATOMIC across every worker: store `job` if none exists for (providerId, jobId) and return
+     * null; otherwise change nothing and return the existing job. */
+    claim(job: PregenJob): Promise<PregenJob | null>;
+    /** ATOMIC: replace the job only if its stored stage is still `from`; true if it was replaced.
+     * Resolve only after a durable write. */
+    update(job: PregenJob, from: Stage): Promise<boolean>;
+    get(providerId: string, jobId: string): Promise<PregenJob | null>;
+    /** Jobs in stage `finished`, oldest first. */
+    pending(providerId: string): Promise<PregenJob[]>;
+}
+declare class PregenError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare function signingInput(type: string, body: Record<string, unknown>): Uint8Array;
+/** The id of a message: covers type and body, not signatures. */
+declare function messageId(type: string, body: Record<string, unknown>): Promise<string>;
+declare function createPregen(config: PregenConfig): {
+    /** Ask, verify, generate (only when permitted), report. See the module comment. */
+    generate<T>(input: PregenJobInput, fn: GenerateFn<T>): Promise<PregenResult<T>>;
+    /** Resend every report still waiting (after a restart, an outage). Run at startup and every minute or so. */
+    flush: () => Promise<PregenResult[]>;
+    /** Where a job stands, or null if this store never saw it. */
+    status(jobId: string): Promise<PregenResult | null>;
+    /** After `needs_check`: record what your generator actually did with this job. Safe to call from several workers:
+     * the first recorded outcome stands. */
+    resolve(jobId: string, outcome: {
+        generated: false;
+    } | {
+        generated: true;
+        outputHash?: string;
+        outputBytes?: Uint8Array | string;
+        obligationsApplied?: {
+            subject: string;
+            id: string;
+        }[];
+    }): Promise<PregenResult>;
+    /** Register this provider's signing key with the registry, once (a `first` keyset, §4.9). Calling it again
+     * with the same key is harmless. */
+    registerKey(): Promise<{
+        keyId: string;
+        keysetId: string;
+    }>;
+    /** Replace this client's signing key with `newSigningKeyHex` (a `rotation` keyset signed by both keys).
+     * Then create the client again with the new key, in every worker. Reports already acknowledged keep their
+     * acknowledgements; reports still waiting, or sent by a worker that still has the old key, are signed again
+     * with the new key by the next `flush()` of a client that has it. */
+    rotateKey(newSigningKeyHex: string): Promise<{
+        keyId: string;
+        keysetId: string;
+    }>;
+};
+type Pregen = ReturnType<typeof createPregen>;
+/** In memory. Correct for ONE process only, and lost on restart: tests and trials. */
+declare function memoryStore(): PregenStore;
+/** Anything with node-postgres' `query(text, values)`: a `pg` Pool, Client or PoolClient. */
+interface PgQueryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+/** The table `postgresStore` uses. Run it in your migrations if your database role may not create tables. */
+declare const postgresSchema = "CREATE TABLE IF NOT EXISTS pregen_jobs (\n  provider_id text NOT NULL, job_id text NOT NULL, stage text NOT NULL, job jsonb NOT NULL,\n  updated_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (provider_id, job_id))";
+/** Postgres, shared by every worker. Creates its table on first use, under a lock, so many workers may start at once. */
+declare function postgresStore(pool: PgQueryable): PregenStore;
+
 /**
  * PRAMPTA SDK for TypeScript / Node.js
  *
@@ -705,4 +892,4 @@ declare class Prampta {
     private getOnce;
 }
 
-export { type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaJobConflictError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, singleProcessJournal, verifyLicenseSignatures, verifyMerkleProof };
+export { type AskResult, type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type Envelope, type GenerateFn, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, NotGeneratedError, type Obligation, type Observation, type ObservationOutbox, type OutputMetadata, type PgQueryable, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaJobConflictError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, type Pregen, type PregenConfig, PregenError, type PregenJob, type PregenJobInput, type PregenResult, type PregenStore, type Purpose, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, createPregen, hashPrompt, matchSubjects, memoryStore, messageId, normalizeForMatch, postgresSchema, postgresStore, signingInput, singleProcessJournal, verifyLicenseSignatures, verifyMerkleProof };

package/dist/index.d.ts

@@ -122,6 +122,193 @@ declare class PramptaReporter {
     deliver(event: Observation): Promise<DeliveryResult>;
 }
 
+type Envelope = {
+    type: string;
+    body: Record<string, any>;
+    signatures: string[];
+};
+type Purpose = "personal" | "educational" | "research" | "editorial" | "commercial";
+interface Obligation {
+    subject: string;
+    id: string;
+    params: Record<string, unknown>;
+}
+interface PregenConfig {
+    baseUrl: string;
+    providerId: string;
+    /** Your runtime credential (`exchange_secret`). */
+    token: string;
+    /** Your Ed25519 private key, 32 bytes hex. Signs reports; register its public key once with `registerKey()`. */
+    providerSigningKeyHex: string;
+    /** The registry's public key(s), hex, obtained independently, not from its API. Optional with `pregenDirectory`:
+     * the keys are then taken from the registry's key set, keeping only those the signed directory lists. */
+    operatorPublicKeyHex?: string | string[];
+    store: PregenStore;
+    /** `enforce` (default): generate only when every subject allows. `observe`: generate anyway and report; nothing is
+     * blocked or granted. Any other value is refused. */
+    mode?: "enforce" | "observe";
+    /** The PRE-GEN directory (`loadPregenDirectory()`): the registry must own each subject's namespace, and every answer
+     * and acknowledgement must be signed by a key the directory lists for it and has not revoked. Recommended. */
+    pregenDirectory?: Directory;
+    timeoutMs?: number;
+}
+interface PregenJobInput {
+    /** Your own stable id for this generation, e.g. your task id. Calling again with the same id
+     * never generates twice; a new generation needs a new id. */
+    jobId: string;
+    /** PRE-GEN codes of everyone in the output. Name matching can suggest them; you decide. */
+    subjects: string[];
+    /** Hashed locally; never sent. */
+    prompt?: string;
+    promptHash?: string;
+    model: string;
+    modality: string;
+    use: {
+        purpose: Purpose;
+        rights?: string[];
+        territory?: string;
+        channel?: string;
+    };
+    /** The connected end user's licensee id; empty for a provider-level request. */
+    licenseeId?: string;
+}
+type GenerateFn<T> = (ctx: {
+    obligations: Obligation[];
+}) => Promise<{
+    output: T;
+    /** One of these is required: the SHA-256 of the output, or the bytes to hash. */
+    outputHash?: string;
+    outputBytes?: Uint8Array | string;
+    /** The obligations you applied, per subject: return the ones from `obligations` you carried out. */
+    obligationsApplied?: {
+        subject: string;
+        id: string;
+    }[];
+}>;
+/** Throw this from your generator only when you are sure it produced nothing (it never started). Any other error
+ * leaves the outcome unknown: the job becomes `needs_check` and nothing is reported until you `resolve()` it. */
+declare class NotGeneratedError extends Error {
+    readonly notGenerated = true;
+    constructor(message?: string);
+}
+interface AskResult {
+    subject: string;
+    status: "allow" | "deny" | "review" | "not_blocked" | null;
+    reason?: string;
+    /** Why the answer is missing or unusable: PG_UNREACHABLE, PG_SIGNATURE, PG_MALFORMED, PG_TIME, PG_BINDING... */
+    error?: string;
+}
+interface PregenResult<T = unknown> {
+    jobId: string;
+    /** confirmed: finished, every report acknowledged. report_pending: finished, a report waits
+     * for acknowledgement; `flush()` resends it. needs_check: the outcome is unknown (interrupted, the generator threw,
+     * or running in another worker) or the registry refused a report; check, then `resolve()`. */
+    status: "confirmed" | "report_pending" | "needs_check";
+    /** null while the outcome is unknown. */
+    generated: boolean | null;
+    /** Only from the call that generated. */
+    output?: T;
+    outputHash?: string;
+    answers: AskResult[];
+    /** Obligations the answers set that `obligationsApplied` did not list. */
+    unmetObligations: Obligation[];
+    detail?: string;
+}
+type Stage = "claimed" | "asked" | "finished" | "done";
+/** One job as the store keeps it. */
+interface PregenJob {
+    providerId: string;
+    jobId: string;
+    /** SHA-256 of the manifest; the same job id with another manifest is refused. */
+    jobHash: string;
+    /** claimed: one worker owns it. asked: answers stored, generation may have started.
+     * finished: outcome and signed reports stored, some not acknowledged. done: nothing left to send. */
+    stage: Stage;
+    asks: {
+        request: Record<string, any>;
+        answer: Envelope | null;
+        error?: string;
+    }[];
+    generated?: boolean;
+    outputHash?: string;
+    unmetObligations?: Obligation[];
+    /** `rejected`: the registry refused this report for good (it holds a different one, or found it malformed). */
+    reports: {
+        subject: string;
+        answerStatus: string;
+        report: Envelope;
+        ack?: Envelope;
+        rejected?: boolean;
+        error?: string;
+    }[];
+}
+interface PregenStore {
+    /** ATOMIC across every worker: store `job` if none exists for (providerId, jobId) and return
+     * null; otherwise change nothing and return the existing job. */
+    claim(job: PregenJob): Promise<PregenJob | null>;
+    /** ATOMIC: replace the job only if its stored stage is still `from`; true if it was replaced.
+     * Resolve only after a durable write. */
+    update(job: PregenJob, from: Stage): Promise<boolean>;
+    get(providerId: string, jobId: string): Promise<PregenJob | null>;
+    /** Jobs in stage `finished`, oldest first. */
+    pending(providerId: string): Promise<PregenJob[]>;
+}
+declare class PregenError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare function signingInput(type: string, body: Record<string, unknown>): Uint8Array;
+/** The id of a message: covers type and body, not signatures. */
+declare function messageId(type: string, body: Record<string, unknown>): Promise<string>;
+declare function createPregen(config: PregenConfig): {
+    /** Ask, verify, generate (only when permitted), report. See the module comment. */
+    generate<T>(input: PregenJobInput, fn: GenerateFn<T>): Promise<PregenResult<T>>;
+    /** Resend every report still waiting (after a restart, an outage). Run at startup and every minute or so. */
+    flush: () => Promise<PregenResult[]>;
+    /** Where a job stands, or null if this store never saw it. */
+    status(jobId: string): Promise<PregenResult | null>;
+    /** After `needs_check`: record what your generator actually did with this job. Safe to call from several workers:
+     * the first recorded outcome stands. */
+    resolve(jobId: string, outcome: {
+        generated: false;
+    } | {
+        generated: true;
+        outputHash?: string;
+        outputBytes?: Uint8Array | string;
+        obligationsApplied?: {
+            subject: string;
+            id: string;
+        }[];
+    }): Promise<PregenResult>;
+    /** Register this provider's signing key with the registry, once (a `first` keyset, §4.9). Calling it again
+     * with the same key is harmless. */
+    registerKey(): Promise<{
+        keyId: string;
+        keysetId: string;
+    }>;
+    /** Replace this client's signing key with `newSigningKeyHex` (a `rotation` keyset signed by both keys).
+     * Then create the client again with the new key, in every worker. Reports already acknowledged keep their
+     * acknowledgements; reports still waiting, or sent by a worker that still has the old key, are signed again
+     * with the new key by the next `flush()` of a client that has it. */
+    rotateKey(newSigningKeyHex: string): Promise<{
+        keyId: string;
+        keysetId: string;
+    }>;
+};
+type Pregen = ReturnType<typeof createPregen>;
+/** In memory. Correct for ONE process only, and lost on restart: tests and trials. */
+declare function memoryStore(): PregenStore;
+/** Anything with node-postgres' `query(text, values)`: a `pg` Pool, Client or PoolClient. */
+interface PgQueryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+/** The table `postgresStore` uses. Run it in your migrations if your database role may not create tables. */
+declare const postgresSchema = "CREATE TABLE IF NOT EXISTS pregen_jobs (\n  provider_id text NOT NULL, job_id text NOT NULL, stage text NOT NULL, job jsonb NOT NULL,\n  updated_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (provider_id, job_id))";
+/** Postgres, shared by every worker. Creates its table on first use, under a lock, so many workers may start at once. */
+declare function postgresStore(pool: PgQueryable): PregenStore;
+
 /**
  * PRAMPTA SDK for TypeScript / Node.js
  *
@@ -705,4 +892,4 @@ declare class Prampta {
     private getOnce;
 }
 
-export { type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, type Observation, type ObservationOutbox, type OutputMetadata, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaJobConflictError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, hashPrompt, matchSubjects, normalizeForMatch, singleProcessJournal, verifyLicenseSignatures, verifyMerkleProof };
+export { type AskResult, type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type Envelope, type GenerateFn, type GenerationJournal, type GenerationJournalEntry, HARD_REFUSAL_CODES, type LicenseRequestInput, type LicenseRequestResult, type LicenseSignatureInput, NotGeneratedError, type Obligation, type Observation, type ObservationOutbox, type OutputMetadata, type PgQueryable, Prampta, PramptaApiError, type PramptaConfig, PramptaError, PramptaFailClosedError, PramptaJobConflictError, PramptaNetworkError, PramptaRefusalError, PramptaReporter, PramptaSchemaError, PramptaSignatureError, PramptaTimeoutError, type Pregen, type PregenConfig, PregenError, type PregenJob, type PregenJobInput, type PregenResult, type PregenStore, type Purpose, REFUSAL_DESCRIPTIONS, type ReceiptOptions, RegistryDirectoryError, type RegistryDirectoryOptions, type ReportInput, SOFT_REFUSAL_CODES, type SignedDecision, type SubjectIndexEntry, type SubjectInfo, TrustedRegistryDirectory, type VerifyOptions, type VerifyRequest, canonicalJson, createPregen, hashPrompt, matchSubjects, memoryStore, messageId, normalizeForMatch, postgresSchema, postgresStore, signingInput, singleProcessJournal, verifyLicenseSignatures, verifyMerkleProof };