@prampta/sdk 0.10.0 → 0.11.1

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.10.0; sections name the version that added them.
+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,47 +36,53 @@ 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.10.0, `/v2`)
+## 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.
+up once; wrap each generation in one call. Use 0.11.1 or later: 0.10.0 and
+0.11.0 had defects found by external reviews (see CHANGELOG). A complete
+program you can run as it stands: https://prampta.com/get-started-v2.md.
 
 ```typescript
 import pg from "pg";
-import { createPregen, postgresStore } from "@prampta/sdk";
+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
-  operatorPublicKeyHex: process.env.PRAMPTA_OPERATOR_PUBLIC_KEY!, // obtained independently, not from the API
-  store: postgresStore(new pg.Pool()),                    // shared by all your workers; creates table pregen_jobs
+  pregenDirectory: await loadPregenDirectory({ previous: lastAccepted }), // PRAMPTA's keys, namespaces, revocations;
+                                         // lastAccepted: the directory you saved last time (toJSON()), or undefined
+  store: postgresStore(new pg.Pool()),                    // shared by all your workers; table pregen_jobs
 });
 
-await pregen.registerKey();                    // once: registers your public key with the registry
+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: ["PGXX-..."],                    // everyone in the output
+    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 }) => {
-    const image = await render(prompt, obligations);   // YOU apply the obligations (watermark, disclosure...)
-    return { output: image, outputBytes: image.bytes, obligationsApplied: obligations.map((o) => o.id) };
+    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.** Asks the registry about every subject under one job
-hash; verifies every answer (your pinned key, 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; counts a report as filed only when the registry's
-signed acknowledgement of exactly it verifies. Refused, or your function
-threw: nothing is generated and every allow is given back.
+**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:**
 
@@ -84,37 +90,66 @@ threw: nothing is generated and every allow is given back.
 |---|---|---|
 | `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: the job was interrupted after it may have started generating, or is running in another worker; or the registry refused a report for good. | Check your generator for this `jobId`, then `pregen.resolve(jobId, { generated: true, outputBytes })` or `{ generated: false }`. |
+| `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`). The SDK never guesses whether an interrupted generation
-finished; only your generator knows, so it asks you.
+(`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 and listed in the report as you
-declare them in `obligationsApplied`; 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.
+**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.
 
-**`observe` mode** (`mode: "observe"`): generates whatever the answers say and
+**`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`). Rotation is not available yet.
-
-**Stores.** `postgresStore(pool)` takes any node-postgres `Pool` or `Client`
-(the `pg` package is yours; the SDK does not depend on it). `memoryStore()`
-is for tests and a single process: it is lost on restart.
+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 rotation.
+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)
 

package/dist/index.d.mts

@@ -140,11 +140,16 @@ interface PregenConfig {
     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 from its documentation, not from its API. */
-    operatorPublicKeyHex: string | 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. */
+    /** `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 {
@@ -174,21 +179,30 @@ type GenerateFn<T> = (ctx: {
     /** One of these is required: the SHA-256 of the output, or the bytes to hash. */
     outputHash?: string;
     outputBytes?: Uint8Array | string;
-    /** Ids of the obligations you applied (watermark, disclosure...). */
-    obligationsApplied?: 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_TIME, PG_BINDING... */
+    /** 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,
-     * or running in another worker) or the registry holds a different report; check, then `resolve()`. */
+     * 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;
@@ -200,6 +214,7 @@ interface PregenResult<T = unknown> {
     unmetObligations: Obligation[];
     detail?: string;
 }
+type Stage = "claimed" | "asked" | "finished" | "done";
 /** One job as the store keeps it. */
 interface PregenJob {
     providerId: string;
@@ -208,7 +223,7 @@ interface PregenJob {
     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: "claimed" | "asked" | "finished" | "done";
+    stage: Stage;
     asks: {
         request: Record<string, any>;
         answer: Envelope | null;
@@ -219,6 +234,8 @@ interface PregenJob {
     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;
@@ -229,8 +246,9 @@ 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>;
-    /** Replace the job. Resolve only after a durable write. */
-    put(job: PregenJob): Promise<void>;
+    /** 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[]>;
@@ -246,33 +264,49 @@ 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[]>;
+    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. */
+    /** 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?: string[];
+        obligationsApplied?: {
+            subject: string;
+            id: string;
+        }[];
     }): Promise<PregenResult>;
-    /** Register this provider's signing key with the registry, once (a `first` keyset, §4.9). */
+    /** 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 or Client. */
+/** Anything with node-postgres' `query(text, values)`: a `pg` Pool, Client or PoolClient. */
 interface PgQueryable {
     query(text: string, values?: unknown[]): Promise<{
         rows: any[];
     }>;
 }
-/** Postgres, shared by every worker. Creates its table `pregen_jobs` on first use. */
+/** 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;
 
 /**
@@ -858,4 +892,4 @@ declare class Prampta {
     private getOnce;
 }
 
-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, 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, postgresStore, signingInput, 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

@@ -140,11 +140,16 @@ interface PregenConfig {
     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 from its documentation, not from its API. */
-    operatorPublicKeyHex: string | 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. */
+    /** `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 {
@@ -174,21 +179,30 @@ type GenerateFn<T> = (ctx: {
     /** One of these is required: the SHA-256 of the output, or the bytes to hash. */
     outputHash?: string;
     outputBytes?: Uint8Array | string;
-    /** Ids of the obligations you applied (watermark, disclosure...). */
-    obligationsApplied?: 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_TIME, PG_BINDING... */
+    /** 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,
-     * or running in another worker) or the registry holds a different report; check, then `resolve()`. */
+     * 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;
@@ -200,6 +214,7 @@ interface PregenResult<T = unknown> {
     unmetObligations: Obligation[];
     detail?: string;
 }
+type Stage = "claimed" | "asked" | "finished" | "done";
 /** One job as the store keeps it. */
 interface PregenJob {
     providerId: string;
@@ -208,7 +223,7 @@ interface PregenJob {
     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: "claimed" | "asked" | "finished" | "done";
+    stage: Stage;
     asks: {
         request: Record<string, any>;
         answer: Envelope | null;
@@ -219,6 +234,8 @@ interface PregenJob {
     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;
@@ -229,8 +246,9 @@ 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>;
-    /** Replace the job. Resolve only after a durable write. */
-    put(job: PregenJob): Promise<void>;
+    /** 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[]>;
@@ -246,33 +264,49 @@ 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[]>;
+    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. */
+    /** 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?: string[];
+        obligationsApplied?: {
+            subject: string;
+            id: string;
+        }[];
     }): Promise<PregenResult>;
-    /** Register this provider's signing key with the registry, once (a `first` keyset, §4.9). */
+    /** 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 or Client. */
+/** Anything with node-postgres' `query(text, values)`: a `pg` Pool, Client or PoolClient. */
 interface PgQueryable {
     query(text: string, values?: unknown[]): Promise<{
         rows: any[];
     }>;
 }
-/** Postgres, shared by every worker. Creates its table `pregen_jobs` on first use. */
+/** 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;
 
 /**
@@ -858,4 +892,4 @@ declare class Prampta {
     private getOnce;
 }
 
-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, 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, postgresStore, signingInput, 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 };