@prampta/sdk 0.9.1 → 0.11.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import * as ed3 from "@noble/ed25519";
+import * as ed4 from "@noble/ed25519";
 
 // src/canonical.ts
 function canonicalJson(obj) {
@@ -211,9 +211,9 @@ var TrustedRegistryDirectory = class _TrustedRegistryDirectory {
 // src/license.ts
 import * as ed2 from "@noble/ed25519";
 async function verifyLicenseSignatures(input) {
-  const bytes = (hex, size) => {
-    if (typeof hex !== "string" || hex.length !== size * 2 || !/^[0-9a-fA-F]+$/.test(hex)) throw new TypeError("Invalid hex");
-    return Uint8Array.from(hex.match(/../g), (s) => parseInt(s, 16));
+  const bytes = (hex2, size) => {
+    if (typeof hex2 !== "string" || hex2.length !== size * 2 || !/^[0-9a-fA-F]+$/.test(hex2)) throw new TypeError("Invalid hex");
+    return Uint8Array.from(hex2.match(/../g), (s) => parseInt(s, 16));
   };
   let body;
   let subjectSig;
@@ -353,6 +353,576 @@ var PramptaReporter = class {
   }
 };
 
+// src/pregen.ts
+import * as ed3 from "@noble/ed25519";
+import { issuerOf } from "@pregen/verify";
+var NotGeneratedError = class extends Error {
+  notGenerated = true;
+  constructor(message = "not generated") {
+    super(message);
+    this.name = "NotGeneratedError";
+  }
+};
+var PregenError = class extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "PregenError";
+  }
+  code;
+};
+var PROFILE = "likeness/1";
+var MAX_LIFETIME = 900;
+var CLOCK_TOLERANCE = 60;
+var JOB_ID = /^[A-Za-z0-9_.:-]{1,100}$/;
+var HEX64 = /^[0-9a-f]{64}$/;
+var STATUSES = /* @__PURE__ */ new Set(["allow", "deny", "review", "not_blocked"]);
+var LEVELS = /* @__PURE__ */ new Set(["self", "asserted", "consented", "verified"]);
+var PURPOSES = /* @__PURE__ */ new Set(["personal", "educational", "research", "editorial", "commercial"]);
+var ANSWER = {
+  required: ["signers", "request_id", "profile", "status", "level", "obligations", "issued_at", "expires_at"],
+  optional: ["reason", "basis", "ext", "critical"]
+};
+var ACK_FIELDS = ["signers", "report", "answer", "answer_status", "counted", "released", "provider_key_id", "received_at"];
+var enc = new TextEncoder();
+var now = () => Math.floor(Date.now() / 1e3);
+var hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+var unhex = (s) => {
+  if (typeof s !== "string" || !/^(?:[0-9a-fA-F]{2})+$/.test(s)) throw new PregenError("PG_CONFIG", "not hex");
+  return Uint8Array.from(s.match(/../g), (h) => parseInt(h, 16));
+};
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var str = (v) => typeof v === "string" && v.length > 0;
+var keysWithin = (o, allowed) => Object.keys(o).every((k) => allowed.includes(k));
+var isPgCode = (s) => {
+  try {
+    issuerOf(s);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var malformed = (why) => new PregenError("PG_MALFORMED", why);
+async function sha2562(data) {
+  return hex(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", data)));
+}
+function signingInput(type, body) {
+  return enc.encode(`PREGEN-V5\0${type}\0${canonicalJson(body)}`);
+}
+function messageId(type, body) {
+  return sha2562(enc.encode(`PREGEN-V5-ID\0${type}\0${canonicalJson(body)}`));
+}
+var keyIdOf = async (pub) => "pg-ed25519:" + (await sha2562(pub)).slice(0, 32);
+async function verifyEnvelope(env, type, role, keyFor) {
+  const e = env;
+  if (!isObj(e) || Object.keys(e).sort().join() !== "body,signatures,type" || e.type !== type || !isObj(e.body) || !Array.isArray(e.signatures)) {
+    throw malformed(`not a ${type}`);
+  }
+  const s = e.body.signers;
+  const pub = Array.isArray(s) && s.length === 1 && s[0]?.role === role && e.signatures.length === 1 && typeof s[0].key_id === "string" ? await keyFor(s[0].key_id) : void 0;
+  if (!pub) throw new PregenError("PG_SIGNATURE", `not signed by a pinned ${role} key`);
+  let ok = false;
+  try {
+    ok = await ed3.verifyAsync(unhex(e.signatures[0]), signingInput(type, e.body), pub);
+  } catch {
+  }
+  if (!ok) throw new PregenError("PG_SIGNATURE", `${type} signature does not verify`);
+  return e.body;
+}
+function checkBasis(b) {
+  if (!isObj(b)) return false;
+  if (b.kind === "grant") {
+    const g = b.grant;
+    return keysWithin(b, ["kind", "grant"]) && isObj(g) && keysWithin(g, ["format", "id", "license_id"]) && str(g.format) && typeof g.id === "string" && Object.values(g).every((v) => typeof v === "string");
+  }
+  return b.kind === "policy" && keysWithin(b, ["kind", "rule"]) && str(b.rule);
+}
+async function checkAnswer(body, request, at) {
+  if (!ANSWER.required.every((k) => k in body) || !keysWithin(body, [...ANSWER.required, ...ANSWER.optional])) throw malformed("fields");
+  if (!str(body.request_id) || !str(body.profile) || !STATUSES.has(body.status) || !LEVELS.has(body.level)) throw malformed("values");
+  if (!Number.isSafeInteger(body.issued_at) || !Number.isSafeInteger(body.expires_at)) throw malformed("times must be integers");
+  if (!Array.isArray(body.obligations) || !body.obligations.every((o) => isObj(o) && Object.keys(o).sort().join() === "id,params" && str(o.id) && isObj(o.params))) throw malformed("obligations");
+  if ("ext" in body && !isObj(body.ext)) throw malformed("ext");
+  if ("critical" in body && !(Array.isArray(body.critical) && body.critical.every(str))) throw malformed("critical");
+  const shaped = body.status === "allow" ? checkBasis(body.basis) && !("reason" in body) : str(body.reason) && !("basis" in body);
+  if (!shaped) throw malformed("an allow has a valid basis and no reason; a refusal a reason and no basis");
+  if (body.critical?.length) throw new PregenError("PG_CRITICAL", body.critical.join());
+  if (!(body.expires_at - body.issued_at > 0 && body.expires_at - body.issued_at <= MAX_LIFETIME)) throw new PregenError("PG_TIME", "lifetime");
+  if (body.issued_at > at + CLOCK_TOLERANCE) throw new PregenError("PG_TIME", "issued in the future");
+  if (body.request_id !== await messageId("pg.request.v1", request)) throw new PregenError("PG_BINDING", "answer is for another request");
+  if (body.profile !== request.profile) throw new PregenError("PG_BINDING", "profile");
+}
+function readInput(input) {
+  let c;
+  try {
+    c = structuredClone(input);
+  } catch {
+    throw malformed("the input must be plain data");
+  }
+  const u = c?.use;
+  if (!isObj(c) || !JOB_ID.test(c.jobId ?? "")) throw malformed("jobId: 1-100 of A-Z a-z 0-9 _ . : -");
+  if (!Array.isArray(c.subjects) || !c.subjects.length || !c.subjects.every(str)) {
+    throw malformed("subjects: name at least one; with no registered person there is nothing to ask");
+  }
+  if (!str(c.model) || !str(c.modality)) throw malformed("model and modality");
+  if (c.prompt !== void 0 && typeof c.prompt !== "string") throw malformed("prompt");
+  if (c.promptHash !== void 0 && !HEX64.test(c.promptHash)) throw malformed("promptHash: 64 lowercase hex");
+  if (c.prompt === void 0 && c.promptHash === void 0) throw malformed("give prompt or promptHash");
+  if (c.licenseeId !== void 0 && typeof c.licenseeId !== "string") throw malformed("licenseeId");
+  if (!isObj(u) || !PURPOSES.has(u.purpose) || !keysWithin(u, ["purpose", "rights", "territory", "channel"]) || u.rights !== void 0 && !(Array.isArray(u.rights) && u.rights.every((r) => typeof r === "string")) || u.territory !== void 0 && typeof u.territory !== "string" || u.channel !== void 0 && typeof u.channel !== "string") {
+    throw malformed("use: purpose personal|educational|research|editorial|commercial; optional rights, territory, channel");
+  }
+  return c;
+}
+function createPregen(config) {
+  const fail2 = (why) => {
+    throw new PregenError("PG_CONFIG", why);
+  };
+  if (!isObj(config)) fail2("a configuration object is required");
+  let url;
+  try {
+    url = new URL(config.baseUrl);
+  } catch {
+    return fail2("baseUrl must be a URL");
+  }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) fail2("use an HTTPS registry URL");
+  if (!str(config.providerId) || !str(config.token)) fail2("providerId and token are required strings");
+  const store = config.store;
+  if (!isObj(store) || !["claim", "update", "get", "pending"].every((m) => typeof store[m] === "function")) {
+    fail2("a store is required (postgresStore(pool), or memoryStore() for one process)");
+  }
+  const mode = config.mode === void 0 ? "enforce" : config.mode;
+  if (mode !== "enforce" && mode !== "observe") fail2(`mode must be "enforce" or "observe", not ${JSON.stringify(mode)}`);
+  const timeoutMs = config.timeoutMs ?? 5e3;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 6e4) fail2("timeoutMs: 1 to 60000");
+  const base = url.origin, providerId = config.providerId, dir = config.pregenDirectory;
+  const secret = unhex(config.providerSigningKeyHex);
+  if (secret.length !== 32) fail2("providerSigningKeyHex must be a 32-byte Ed25519 private key");
+  const rawPins = config.operatorPublicKeyHex;
+  const pins = (Array.isArray(rawPins) ? rawPins : typeof rawPins === "string" ? rawPins.split(/[\s,]+/) : []).filter(Boolean);
+  if (!pins.length && !dir || pins.some((p) => unhex(p).length !== 32)) {
+    fail2("operatorPublicKeyHex: one or more 32-byte public keys, hex (or give pregenDirectory)");
+  }
+  const sameBase = (api) => {
+    try {
+      const u = new URL(api);
+      return u.origin === base && /^\/*$/.test(u.pathname);
+    } catch {
+      return false;
+    }
+  };
+  const listed = dir?.registries.find((r) => sameBase(r.api));
+  if (dir && !listed) fail2(`${base} is not a registry listed in the PRE-GEN directory`);
+  const ready = (async () => {
+    const registry = /* @__PURE__ */ new Map();
+    for (const p of pins) registry.set(await keyIdOf(unhex(p)), unhex(p));
+    const pub = await ed3.getPublicKeyAsync(secret);
+    return { registry, pub, keyId: await keyIdOf(pub) };
+  })();
+  const fromDirectory = /* @__PURE__ */ new Map();
+  async function keyFor(keyId) {
+    const { registry } = await ready;
+    if (pins.length) return registry.get(keyId);
+    const code = listed.prefix ? `PG-${listed.prefix}-0` : "PG-0";
+    let p = fromDirectory.get(keyId);
+    if (!p) {
+      p = dir.publicKey(code, keyId).then(unhex, () => {
+        fromDirectory.delete(keyId);
+        return void 0;
+      });
+      fromDirectory.set(keyId, p);
+    }
+    return p;
+  }
+  const directoryVerdict = (subject, keyId) => !dir || !isPgCode(subject) ? "valid" : dir.checkSigner(subject, keyId);
+  async function post(path, payload) {
+    const resp = await fetch(base + path, {
+      method: "POST",
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs),
+      body: JSON.stringify(payload),
+      headers: { "Content-Type": "application/json", "X-Provider-ID": providerId, Authorization: `Bearer ${config.token}` }
+    });
+    let data = null;
+    try {
+      data = await resp.json();
+    } catch {
+    }
+    return { status: resp.status, data };
+  }
+  const errorCode = (r) => typeof r.data?.detail?.error === "string" && r.data.detail.error || `HTTP_${r.status}`;
+  async function seal(type, body) {
+    const { keyId } = await ready;
+    body = { ...body, signers: [{ role: "provider", key_id: keyId }] };
+    return { type, body, signatures: [hex(await ed3.signAsync(signingInput(type, body), secret))] };
+  }
+  async function ask(request) {
+    const subject = request.subject_ref;
+    if (dir && isPgCode(subject) && !(dir.registryFor(subject) && sameBase(dir.registryFor(subject).api))) {
+      return { request, answer: null, error: "PG_WRONG_REGISTRY" };
+    }
+    let r = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (attempt) await new Promise((ok) => setTimeout(ok, 200 * 2 ** attempt));
+      try {
+        r = await post("/v2/requests", { type: "pg.request.v1", body: request, signatures: [] });
+      } catch {
+        r = null;
+        continue;
+      }
+      if (r.status !== 429 && r.status < 500) break;
+    }
+    if (!r) return { request, answer: null, error: "PG_UNREACHABLE" };
+    if (r.status !== 200) return { request, answer: null, error: errorCode(r) };
+    const answer = r.data?.answer;
+    try {
+      await verifyEnvelope(answer, "pg.answer.v1", "registry", keyFor);
+      const verdict = directoryVerdict(subject, answer.body.signers[0].key_id);
+      if (verdict !== "valid") throw new PregenError(`PG_KEY_${verdict.toUpperCase()}`, "the directory does not list this key");
+    } catch (e) {
+      return { request, answer: null, error: e instanceof PregenError ? e.code : "PG_MALFORMED" };
+    }
+    try {
+      await checkAnswer(answer.body, request, now());
+      return { request, answer };
+    } catch (e) {
+      const code = e.code;
+      return code === "PG_BINDING" ? { request, answer: null, error: code } : { request, answer, error: code };
+    }
+  }
+  const usableAllow = (a, at) => !a.error && a.answer?.body.status === "allow" && a.answer.body.expires_at > at;
+  const obligationsOfAsk = (a) => a.answer && a.error !== "PG_MALFORMED" ? a.answer.body.obligations.map((o) => ({ subject: a.request.subject_ref, id: o.id, params: o.params })) : [];
+  const obligationsOf = (job) => job.asks.flatMap(obligationsOfAsk);
+  const applies = (applied, o) => applied.some((x) => x.subject === o.subject && x.id === o.id);
+  async function report(a, outcome, outputHash, applied) {
+    const answer = a.answer ? await messageId("pg.answer.v1", a.answer.body) : null;
+    const body = {
+      request_id: await messageId("pg.request.v1", a.request),
+      answer,
+      mode: a.request.mode,
+      job_id: a.request.job_id,
+      outcome,
+      output_hash: outcome === "generated" ? outputHash : "",
+      obligations_applied: outcome === "generated" ? [...new Set(obligationsOfAsk(a).filter((o) => applies(applied, o)).map((o) => o.id))].sort() : [],
+      occurred_at: now()
+    };
+    if (answer === null) body.request = a.request;
+    return { subject: a.request.subject_ref, answerStatus: a.answer?.body.status ?? "none", report: await seal("pg.report.v1", body) };
+  }
+  async function checkAck(r, env) {
+    const { keyId } = await ready;
+    const ack = await verifyEnvelope(env, "pg.report_ack.v1", "registry", keyFor);
+    const verdict = directoryVerdict(r.subject, ack.signers[0].key_id);
+    if (verdict !== "valid") throw new PregenError(`PG_KEY_${verdict.toUpperCase()}`, "the directory does not list this key");
+    if (Object.keys(ack).sort().join() !== [...ACK_FIELDS].sort().join()) throw malformed("acknowledgement fields");
+    if (ack.report !== await messageId("pg.report.v1", r.report.body) || ack.answer !== r.report.body.answer || ack.answer_status !== r.answerStatus || ack.provider_key_id !== keyId) {
+      throw new PregenError("PG_BINDING", "the acknowledgement is not for this report");
+    }
+    if (!(ack.counted === null || HEX64.test(ack.counted)) || !Array.isArray(ack.released) || !ack.released.every((x) => typeof x === "string" && HEX64.test(x)) || !Number.isSafeInteger(ack.received_at)) {
+      throw malformed("acknowledgement values");
+    }
+  }
+  const reread = async (job) => await store.get(providerId, job.jobId) ?? job;
+  async function send(job) {
+    const { keyId } = await ready;
+    for (const r of job.reports) {
+      if (r.ack || r.rejected) continue;
+      let res;
+      try {
+        res = await post("/v2/reports", r.report);
+        if (res.status === 401 && r.report.body.signers?.[0]?.key_id !== keyId) {
+          const { signers: _, ...body } = r.report.body;
+          r.report = await seal("pg.report.v1", body);
+          res = await post("/v2/reports", r.report);
+        }
+      } catch {
+        r.error = "PG_UNREACHABLE";
+        continue;
+      }
+      if (res.status === 409 || res.status === 422) {
+        r.rejected = true;
+        r.error = errorCode(res);
+        continue;
+      }
+      if (res.status !== 200) {
+        r.error = errorCode(res);
+        continue;
+      }
+      try {
+        await checkAck(r, res.data?.ack);
+        r.ack = res.data.ack;
+        delete r.error;
+      } catch (e) {
+        r.error = e instanceof PregenError ? e.code : "PG_MALFORMED";
+      }
+    }
+    const next = { ...job, stage: job.reports.every((r) => r.ack || r.rejected) ? "done" : "finished" };
+    return await store.update(next, "finished") ? next : reread(job);
+  }
+  function result(job, output, override) {
+    const unknown = job.stage === "claimed" || job.stage === "asked";
+    const rejected = job.reports.some((r) => r.rejected);
+    return {
+      jobId: job.jobId,
+      status: unknown || rejected || override ? "needs_check" : job.stage === "done" ? "confirmed" : "report_pending",
+      generated: unknown ? null : !!job.generated,
+      ...output !== void 0 ? { output } : {},
+      ...job.outputHash ? { outputHash: job.outputHash } : {},
+      answers: job.asks.map((a) => ({
+        subject: a.request.subject_ref,
+        status: a.answer?.body.status ?? null,
+        ...typeof a.answer?.body.reason === "string" ? { reason: a.answer.body.reason } : {},
+        ...a.error ? { error: a.error } : {}
+      })),
+      unmetObligations: job.unmetObligations ?? [],
+      detail: override ?? (unknown ? "the outcome is unknown (interrupted, the generator threw, or running in another worker): check your generator for this job, then resolve()" : rejected ? "the registry refused a report: see its error" : void 0)
+    };
+  }
+  async function finish(job, generated, outputHash = "", applied = []) {
+    const asks = generated ? job.asks : job.asks.filter((a) => a.answer?.body.status === "allow");
+    const next = {
+      ...job,
+      stage: "finished",
+      generated,
+      ...generated ? { outputHash } : {},
+      reports: await Promise.all(asks.map((a) => report(a, generated ? "generated" : "not_generated", outputHash, applied))),
+      unmetObligations: generated ? obligationsOf(job).filter((o) => !applies(applied, o)) : []
+    };
+    if (await store.update(next, "asked")) return send(next);
+    const stored = await reread(job);
+    return stored.stage === "finished" ? send(stored) : stored;
+  }
+  async function outputHashOf(r) {
+    if (!isObj(r)) throw malformed("the generator must return { output, outputHash | outputBytes }");
+    if (r.outputHash !== void 0) {
+      if (typeof r.outputHash !== "string" || !HEX64.test(r.outputHash)) throw malformed("outputHash must be 64 lowercase hex characters");
+      return r.outputHash;
+    }
+    if (typeof r.outputBytes === "string") return sha2562(enc.encode(r.outputBytes));
+    if (r.outputBytes instanceof Uint8Array) return sha2562(r.outputBytes);
+    throw malformed("return outputHash or outputBytes");
+  }
+  function appliedOf(list) {
+    if (list === void 0) return [];
+    if (!Array.isArray(list) || !list.every((x) => isObj(x) && str(x.subject) && str(x.id))) {
+      throw malformed("obligationsApplied: the { subject, id } obligations you carried out");
+    }
+    return list.map((x) => ({ subject: x.subject, id: x.id }));
+  }
+  async function currentKeyset() {
+    const resp = await fetch(`${base}/v2/keys/${encodeURIComponent(providerId)}`, { redirect: "error", signal: AbortSignal.timeout(timeoutMs) });
+    const chain = resp.ok ? (await resp.json())?.keysets : null;
+    const keyset = Array.isArray(chain) && chain.length ? chain[chain.length - 1] : null;
+    if (!keyset || !isObj(keyset.body) || !Array.isArray(keyset.body.keys)) return null;
+    return {
+      keyset,
+      id: await messageId("pg.keyset.v1", keyset.body),
+      current: keyset.body.keys.find((k) => k.status === "current")
+    };
+  }
+  async function flush() {
+    const out = [];
+    for (const job of await store.pending(providerId)) out.push(result(await send(job)));
+    return out;
+  }
+  async function run(input, fn) {
+    const subjects = [...new Set(input.subjects)].sort();
+    const promptHash = input.promptHash ?? await sha2562(enc.encode(input.prompt));
+    const manifest = {
+      job_id: input.jobId,
+      provider_id: providerId,
+      licensee_id: input.licenseeId ?? "",
+      prompt_hash: promptHash,
+      model: input.model,
+      modality: input.modality,
+      mode,
+      asks: subjects.map((s) => ({ subject_ref: s, registry: "", profile: PROFILE, use: input.use }))
+    };
+    const jobHash = await sha2562(enc.encode(canonicalJson(manifest)));
+    const fresh = { providerId, jobId: input.jobId, jobHash, stage: "claimed", asks: [], reports: [] };
+    const existing = await store.claim(fresh);
+    if (existing) {
+      if (existing.jobHash !== jobHash) throw new PregenError("PG_JOB_CONFLICT", `job ${input.jobId} was used for another generation`);
+      return result(existing.stage === "finished" ? await send(existing) : existing);
+    }
+    const asked = { ...fresh, stage: "asked", asks: await Promise.all(subjects.map((s) => ask({
+      job_id: input.jobId,
+      job_hash: jobHash,
+      subject_ref: s,
+      provider_id: providerId,
+      licensee_id: manifest.licensee_id,
+      prompt_hash: promptHash,
+      model: input.model,
+      modality: input.modality,
+      profile: PROFILE,
+      use: input.use,
+      mode
+    }))) };
+    if (!await store.update(asked, "claimed")) return result(await reread(fresh));
+    const at = now();
+    if (mode === "enforce" && !asked.asks.every((a) => usableAllow(a, at))) return result(await finish(asked, false));
+    let out;
+    try {
+      out = await fn({ obligations: obligationsOf(asked) });
+    } catch (e) {
+      if (e?.notGenerated === true) await finish(asked, false);
+      throw e;
+    }
+    const done = await finish(asked, true, await outputHashOf(out), appliedOf(out.obligationsApplied));
+    return result(done, out.output, done.generated ? void 0 : "another worker recorded that this job was not generated");
+  }
+  return {
+    /** Ask, verify, generate (only when permitted), report. See the module comment. */
+    async generate(input, fn) {
+      const copy = readInput(input);
+      if (typeof fn !== "function") throw malformed("pass your generator function");
+      return run(copy, fn);
+    },
+    /** Resend every report still waiting (after a restart, an outage). Run at startup and every minute or so. */
+    flush,
+    /** Where a job stands, or null if this store never saw it. */
+    async status(jobId) {
+      const job = await store.get(providerId, jobId);
+      return job && result(job);
+    },
+    /** After `needs_check`: record what your generator actually did with this job. Safe to call from several workers:
+     * the first recorded outcome stands. */
+    async resolve(jobId, outcome) {
+      if (!isObj(outcome) || typeof outcome.generated !== "boolean") throw malformed("outcome: { generated: true | false, ... }");
+      const job = await store.get(providerId, jobId);
+      if (!job) throw new PregenError("PG_UNKNOWN_JOB", jobId);
+      if (job.stage === "finished") return result(await send(job));
+      if (job.stage === "done") return result(job);
+      if (!outcome.generated) {
+        if (job.stage === "claimed") {
+          const closed = { ...job, stage: "done", generated: false };
+          if (await store.update(closed, "claimed")) return result(closed);
+          const stored = await reread(job);
+          return result(stored.stage === "finished" ? await send(stored) : stored);
+        }
+        return result(await finish(job, false));
+      }
+      if (job.stage === "claimed") throw new PregenError("PG_JOB", "generation cannot have started before the answers were stored");
+      return result(await finish(job, true, await outputHashOf(outcome), appliedOf(outcome.obligationsApplied)));
+    },
+    /** Register this provider's signing key with the registry, once (a `first` keyset, §4.9). Calling it again
+     * with the same key is harmless. */
+    async registerKey() {
+      const { pub, keyId } = await ready;
+      const keyset = await seal("pg.keyset.v1", {
+        kind: "first",
+        provider_id: providerId,
+        previous: null,
+        recovery_registry: "",
+        keys: [{ key_id: keyId, public_key_hex: hex(pub), status: "current" }]
+      });
+      const r = await post("/v2/keys", keyset);
+      if (r.status === 409) {
+        const latest = await currentKeyset();
+        if (latest?.current?.key_id === keyId) return { keyId, keysetId: latest.id };
+      }
+      if (r.status !== 200) throw new PregenError(errorCode(r), r.data?.detail?.error_description ?? "key not registered");
+      return { keyId, keysetId: r.data.keyset_id };
+    },
+    /** 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. */
+    async rotateKey(newSigningKeyHex) {
+      const next = unhex(newSigningKeyHex);
+      if (next.length !== 32) throw new PregenError("PG_CONFIG", "the new key must be a 32-byte Ed25519 private key");
+      const { pub, keyId } = await ready;
+      await flush();
+      const chain = await currentKeyset();
+      if (!chain || chain.current?.key_id !== keyId) {
+        throw new PregenError("PG_KEYSET", "the registry's current key is not this client's key: registerKey() first");
+      }
+      const latest = chain.keyset;
+      const nextPub = await ed3.getPublicKeyAsync(next), nextId = await keyIdOf(nextPub);
+      const body = {
+        kind: "rotation",
+        provider_id: providerId,
+        previous: await messageId("pg.keyset.v1", latest.body),
+        recovery_registry: latest.body.recovery_registry,
+        keys: [
+          { key_id: nextId, public_key_hex: hex(nextPub), status: "current" },
+          { key_id: keyId, public_key_hex: hex(pub), status: "retired" }
+        ],
+        signers: [{ role: "provider", key_id: nextId }, { role: "provider_previous", key_id: keyId }]
+      };
+      const data = signingInput("pg.keyset.v1", body);
+      const keyset = { type: "pg.keyset.v1", body, signatures: [hex(await ed3.signAsync(data, next)), hex(await ed3.signAsync(data, secret))] };
+      const r = await post("/v2/keys", keyset);
+      if (r.status !== 200) throw new PregenError(errorCode(r), r.data?.detail?.error_description ?? "key not rotated");
+      return { keyId: nextId, keysetId: r.data.keyset_id };
+    }
+  };
+}
+function memoryStore() {
+  const jobs = /* @__PURE__ */ new Map();
+  const k = (p, j) => `${p}\0${j}`;
+  return {
+    async claim(job) {
+      const found = jobs.get(k(job.providerId, job.jobId));
+      if (found) return structuredClone(found);
+      jobs.set(k(job.providerId, job.jobId), structuredClone(job));
+      return null;
+    },
+    async update(job, from) {
+      if (jobs.get(k(job.providerId, job.jobId))?.stage !== from) return false;
+      jobs.set(k(job.providerId, job.jobId), structuredClone(job));
+      return true;
+    },
+    async get(p, j) {
+      const f = jobs.get(k(p, j));
+      return f ? structuredClone(f) : null;
+    },
+    async pending(p) {
+      return [...jobs.values()].filter((j) => j.providerId === p && j.stage === "finished").map((j) => structuredClone(j));
+    }
+  };
+}
+var postgresSchema = `CREATE TABLE IF NOT EXISTS pregen_jobs (
+  provider_id text NOT NULL, job_id text NOT NULL, stage text NOT NULL, job jsonb NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (provider_id, job_id))`;
+function postgresStore(pool) {
+  let ready = null;
+  const q = async (text, values) => {
+    ready ??= pool.query(`DO $$ BEGIN
+      IF to_regclass('pregen_jobs') IS NULL THEN
+        PERFORM pg_advisory_xact_lock(hashtext('pregen_jobs'));
+        ${postgresSchema};
+      END IF;
+    END $$`).catch((e) => {
+      ready = null;
+      throw e;
+    });
+    await ready;
+    return (await pool.query(text, values)).rows;
+  };
+  const one = async (p, j) => (await q("SELECT job FROM pregen_jobs WHERE provider_id = $1 AND job_id = $2", [p, j]))[0]?.job ?? null;
+  return {
+    async claim(job) {
+      const won = await q(`INSERT INTO pregen_jobs (provider_id, job_id, stage, job) VALUES ($1, $2, $3, $4)
+        ON CONFLICT DO NOTHING RETURNING job_id`, [job.providerId, job.jobId, job.stage, JSON.stringify(job)]);
+      return won.length ? null : one(job.providerId, job.jobId);
+    },
+    async update(job, from) {
+      return (await q(
+        `UPDATE pregen_jobs SET stage = $3, job = $4, updated_at = now()
+        WHERE provider_id = $1 AND job_id = $2 AND stage = $5 RETURNING job_id`,
+        [job.providerId, job.jobId, job.stage, JSON.stringify(job), from]
+      )).length > 0;
+    },
+    get: one,
+    async pending(p) {
+      return (await q(`SELECT job FROM pregen_jobs WHERE provider_id = $1 AND stage = 'finished'
+        ORDER BY updated_at LIMIT 100`, [p])).map((r) => r.job);
+    }
+  };
+}
+
 // src/index.ts
 function singleProcessJournal() {
   const entries = /* @__PURE__ */ new Map();
@@ -497,16 +1067,16 @@ function envVar(key) {
   return "";
 }
 async function hashPrompt(prompt) {
-  return sha2562(prompt);
+  return sha2563(prompt);
 }
-async function sha2562(input) {
+async function sha2563(input) {
   const data = new TextEncoder().encode(input);
   return sha256Bytes(data);
 }
 async function verifyMerkleProof(leafHash, proof, rootHash) {
   let current = leafHash;
   for (const step of proof) {
-    current = step.position === "right" ? await sha2562(current + step.hash) : await sha2562(step.hash + current);
+    current = step.position === "right" ? await sha2563(current + step.hash) : await sha2563(step.hash + current);
   }
   return current === rootHash;
 }
@@ -526,13 +1096,13 @@ async function sha256Bytes(data) {
   const { createHash } = await import("crypto");
   return createHash("sha256").update(data).digest("hex");
 }
-function hexToBytes(hex) {
-  if (typeof hex !== "string" || !/^(?:[0-9a-fA-F]{2})+$/.test(hex)) {
+function hexToBytes(hex2) {
+  if (typeof hex2 !== "string" || !/^(?:[0-9a-fA-F]{2})+$/.test(hex2)) {
     throw new PramptaSignatureError("Invalid hexadecimal key or signature");
   }
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  const bytes = new Uint8Array(hex2.length / 2);
+  for (let i = 0; i < hex2.length; i += 2) {
+    bytes[i / 2] = parseInt(hex2.substring(i, i + 2), 16);
   }
   return bytes;
 }
@@ -684,7 +1254,7 @@ var Prampta = class _Prampta {
         if (!currentHex || !sig) throw new PramptaSignatureError("Operator key set from /keys is malformed");
         const body = { ...ks };
         delete body.signature;
-        const ok = await ed3.verifyAsync(hexToBytes(sig), new TextEncoder().encode(canonicalJson(body)), hexToBytes(currentHex));
+        const ok = await ed4.verifyAsync(hexToBytes(sig), new TextEncoder().encode(canonicalJson(body)), hexToBytes(currentHex));
         if (!ok) throw new PramptaSignatureError("Operator key set signature is invalid");
         this.keySetCache = ks;
         return ks;
@@ -699,8 +1269,8 @@ var Prampta = class _Prampta {
    * from the self-consistent /keys set with a warning.
    */
   async resolveOperatorKey(keyId) {
-    for (const hex of this.pinnedKeys) {
-      if (await keyFingerprint(hex) === keyId) return hex;
+    for (const hex2 of this.pinnedKeys) {
+      if (await keyFingerprint(hex2) === keyId) return hex2;
     }
     if (this.pinnedKeys.length > 0) {
       throw new PramptaSignatureError(
@@ -733,11 +1303,11 @@ var Prampta = class _Prampta {
    * copy of the subject index. Call verify()/assertAllowed() per hit.
    */
   async matchSubjects(text, opts) {
-    const now = Date.now();
-    if (opts?.forceRefresh || !this.subjectIndexEntries || now - this.subjectIndexFetchedAt > _Prampta.SUBJECT_INDEX_TTL_MS) {
+    const now2 = Date.now();
+    if (opts?.forceRefresh || !this.subjectIndexEntries || now2 - this.subjectIndexFetchedAt > _Prampta.SUBJECT_INDEX_TTL_MS) {
       const payload = await this.fetchSubjectIndex();
       this.subjectIndexEntries = payload.subjects || [];
-      this.subjectIndexFetchedAt = now;
+      this.subjectIndexFetchedAt = now2;
     }
     return matchSubjects(text, this.subjectIndexEntries);
   }
@@ -825,7 +1395,7 @@ var Prampta = class _Prampta {
     const sigBytes = hexToBytes(sig);
     let valid;
     try {
-      valid = await ed3.verifyAsync(sigBytes, messageBytes, pubKeyBytes);
+      valid = await ed4.verifyAsync(sigBytes, messageBytes, pubKeyBytes);
     } catch (e) {
       throw new PramptaSignatureError(`Ed25519 verification error: ${e}`);
     }
@@ -834,13 +1404,13 @@ var Prampta = class _Prampta {
         "Operator signature is invalid \u2014 decision cannot be trusted. This may indicate a compromised backend, proxy tampering, or key mismatch."
       );
     }
-    const now = Math.floor(Date.now() / 1e3);
-    if (!Number.isSafeInteger(raw.expires_at) || !Number.isSafeInteger(raw.issued_at) || raw.issued_at <= 0 || raw.expires_at <= raw.issued_at || raw.expires_at - raw.issued_at > 900 || raw.issued_at > now + 60) {
+    const now2 = Math.floor(Date.now() / 1e3);
+    if (!Number.isSafeInteger(raw.expires_at) || !Number.isSafeInteger(raw.issued_at) || raw.issued_at <= 0 || raw.expires_at <= raw.issued_at || raw.expires_at - raw.issued_at > 900 || raw.issued_at > now2 + 60) {
       throw new PramptaSchemaError("Decision has invalid validity timestamps");
     }
-    if (decision.expiresAt <= now) {
+    if (decision.expiresAt <= now2) {
       throw new PramptaSignatureError(
-        `Decision expired at ${decision.expiresAt}, current time ${now}`
+        `Decision expired at ${decision.expiresAt}, current time ${now2}`
       );
     }
   }
@@ -926,7 +1496,7 @@ var Prampta = class _Prampta {
     } : void 0 };
     this.registryDirectory?.assertEndpoint(request.subjectId, this.baseUrl);
     this.assertPregenEndpoint(request.subjectId);
-    const promptHash = request.promptHash || (request.prompt ? await sha2562(request.prompt) : null);
+    const promptHash = request.promptHash || (request.prompt ? await sha2563(request.prompt) : null);
     if (!promptHash) {
       throw new PramptaSchemaError(
         "Either prompt or promptHash is required. SDK does not allow empty prompt hashes to prevent unbound decisions."
@@ -1103,7 +1673,7 @@ var Prampta = class _Prampta {
   /** SHA-256 of everything that defines the job. Same id + different hash = a different job. */
   async requestHash(request) {
     const { generationId, subjectIds, prompt, promptHash, idempotencyKey, returnUrl, detectionId, ...rest } = request;
-    return sha2562(canonicalJson(JSON.parse(JSON.stringify({
+    return sha2563(canonicalJson(JSON.parse(JSON.stringify({
       ...rest,
       generationId,
       subjectIds: [...new Set(subjectIds)].sort(),
@@ -1261,7 +1831,7 @@ var Prampta = class _Prampta {
         provider_id: this.providerId,
         event_type: eventType
       };
-      const signature = await ed3.signAsync(
+      const signature = await ed4.signAsync(
         new TextEncoder().encode(canonicalJson(body)),
         hexToBytes(keyHex)
       );
@@ -1317,7 +1887,7 @@ var Prampta = class _Prampta {
     return this.get("/version");
   }
   static async hashPrompt(prompt) {
-    return sha2562(prompt);
+    return sha2563(prompt);
   }
   // ── Internal ─────────────────────────────────────────────────────────
   parseDecision(data) {
@@ -1445,6 +2015,7 @@ function sameEndpoint(a, b) {
 }
 export {
   HARD_REFUSAL_CODES,
+  NotGeneratedError,
   Prampta,
   PramptaApiError,
   PramptaError,
@@ -1456,15 +2027,22 @@ export {
   PramptaSchemaError,
   PramptaSignatureError,
   PramptaTimeoutError,
+  PregenError,
   REFUSAL_DESCRIPTIONS,
   RegistryDirectoryError,
   SOFT_REFUSAL_CODES,
   TrustedRegistryDirectory,
   canonicalJson,
+  createPregen,
   hashPrompt,
   loadDirectory as loadPregenDirectory,
   matchSubjects,
+  memoryStore,
+  messageId,
   normalizeForMatch,
+  postgresSchema,
+  postgresStore,
+  signingInput,
   singleProcessJournal,
   verifyLicenseSignatures,
   verifyMerkleProof