@prampta/sdk 0.10.0 → 0.11.1

package/dist/index.mjs

@@ -355,6 +355,14 @@ 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}`);
@@ -369,13 +377,32 @@ 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 (!/^(?:[0-9a-fA-F]{2})+$/.test(s)) throw new PregenError("PG_MALFORMED", "not hex");
+  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)));
 }
@@ -386,13 +413,13 @@ 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, keys) {
+async function verifyEnvelope(env, type, role, keyFor) {
   const e = env;
-  if (!e || typeof e !== "object" || Object.keys(e).sort().join() !== "body,signatures,type" || e.type !== type || !e.body || typeof e.body !== "object" || !Array.isArray(e.signatures)) {
-    throw new PregenError("PG_MALFORMED", `not a ${type}`);
+  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 ? keys.get(s[0].key_id) : void 0;
+  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 {
@@ -402,34 +429,117 @@ async function verifyEnvelope(env, type, role, keys) {
   if (!ok) throw new PregenError("PG_SIGNATURE", `${type} signature does not verify`);
   return e.body;
 }
+var GRANT_FORMATS = {
+  // The id is the SHA-256 of the bytes the licence's registry countersigned.
+  "pg.license.v2": (g) => keysWithin(g, ["format", "id", "license_id"]) && typeof g.id === "string" && HEX64.test(g.id) && (g.license_id === void 0 || str(g.license_id))
+};
+function checkBasis(b) {
+  if (!isObj(b)) return false;
+  if (b.kind === "grant") {
+    const g = b.grant;
+    return keysWithin(b, ["kind", "grant"]) && isObj(g) && typeof g.format === "string" && !!GRANT_FORMATS[g.format]?.(g);
+  }
+  return b.kind === "policy" && keysWithin(b, ["kind", "rule"]) && str(b.rule);
+}
 async function checkAnswer(body, request, at) {
-  if (Array.isArray(body.critical) && body.critical.length) throw new PregenError("PG_CRITICAL", body.critical.join());
+  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");
-  if (!STATUSES.has(body.status)) throw new PregenError("PG_MALFORMED", "status");
-  const shaped = body.status === "allow" ? "basis" in body && !("reason" in body) : "reason" in body && !("basis" in body);
-  if (!shaped) throw new PregenError("PG_MALFORMED", "an allow has a basis and no reason; a refusal the reverse");
+}
+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 url = new URL(config.baseUrl);
+  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)) throw new PregenError("PG_CONFIG", "use an HTTPS registry URL");
-  if (!config.providerId || !config.token) throw new PregenError("PG_CONFIG", "providerId and token are required");
-  if (!config.store) throw new PregenError("PG_CONFIG", "a store is required (postgresStore(pool), or memoryStore() for one process)");
-  const base = url.origin, mode = config.mode ?? "enforce", timeoutMs = config.timeoutMs ?? 5e3;
-  const providerId = config.providerId, store = config.store;
+  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) throw new PregenError("PG_CONFIG", "providerSigningKeyHex must be a 32-byte Ed25519 private key");
-  const pins = (Array.isArray(config.operatorPublicKeyHex) ? config.operatorPublicKeyHex : config.operatorPublicKeyHex.split(/[\s,]+/)).filter(Boolean);
-  if (!pins.length) throw new PregenError("PG_CONFIG", "operatorPublicKeyHex is required");
+  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 registryCode = listed ? listed.prefix ? `PG-${listed.prefix}-0` : "PG-0" : "";
   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);
+    let p = fromDirectory.get(keyId);
+    if (!p) {
+      p = dir.publicKey(registryCode, keyId).then(unhex, () => {
+        fromDirectory.delete(keyId);
+        return void 0;
+      });
+      fromDirectory.set(keyId, p);
+    }
+    return p;
+  }
+  const directoryVerdict = (subject, keyId) => !dir ? "valid" : dir.checkSigner(isPgCode(subject) ? subject : registryCode, keyId);
   async function post(path, payload) {
     const resp = await fetch(base + path, {
       method: "POST",
@@ -445,14 +555,17 @@ function createPregen(config) {
     }
     return { status: resp.status, data };
   }
-  const errorCode = (r) => r.data?.detail?.error ?? `HTTP_${r.status}`;
+  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 { registry } = await ready;
+    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));
@@ -468,7 +581,9 @@ function createPregen(config) {
     if (r.status !== 200) return { request, answer: null, error: errorCode(r) };
     const answer = r.data?.answer;
     try {
-      await verifyEnvelope(answer, "pg.answer.v1", "registry", registry);
+      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" };
     }
@@ -481,9 +596,11 @@ function createPregen(config) {
     }
   }
   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 required = new Set((a.answer?.body.obligations ?? []).map((o) => o.id));
     const body = {
       request_id: await messageId("pg.request.v1", a.request),
       answer,
@@ -491,19 +608,37 @@ function createPregen(config) {
       job_id: a.request.job_id,
       outcome,
       output_hash: outcome === "generated" ? outputHash : "",
-      obligations_applied: outcome === "generated" ? [...new Set(applied)].filter((id) => required.has(id)).sort() : [],
+      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 { report: await seal("pg.report.v1", body) };
+    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 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 !== r.report.body.signers?.[0]?.key_id) {
+      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 { registry } = await ready;
+    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;
@@ -518,59 +653,85 @@ function createPregen(config) {
         continue;
       }
       try {
-        const ack = await verifyEnvelope(res.data?.ack, "pg.report_ack.v1", "registry", registry);
-        if (ack.report !== await messageId("pg.report.v1", r.report.body)) throw new PregenError("PG_BINDING", "ack for another report");
+        await checkAck(r, res.data?.ack);
         r.ack = res.data.ack;
         delete r.error;
       } catch (e) {
-        r.error = e.code ?? "PG_MALFORMED";
+        r.error = e instanceof PregenError ? e.code : "PG_MALFORMED";
       }
     }
-    if (job.reports.every((r) => r.ack || r.rejected)) job.stage = "done";
-    await store.put(job);
-    return job;
+    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, detail) {
+  function result(job, output, override) {
     const unknown = job.stage === "claimed" || job.stage === "asked";
-    const conflict = job.reports.some((r) => r.rejected);
+    const rejected = job.reports.some((r) => r.rejected);
     return {
       jobId: job.jobId,
-      status: unknown || conflict ? "needs_check" : job.stage === "done" ? "confirmed" : "report_pending",
+      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,
-        ...a.answer?.body.reason ? { reason: a.answer.body.reason } : {},
+        ...typeof a.answer?.body.reason === "string" ? { reason: a.answer.body.reason } : {},
         ...a.error ? { error: a.error } : {}
       })),
       unmetObligations: job.unmetObligations ?? [],
-      detail: detail ?? (unknown ? "running in another worker, or interrupted: check your generator, then resolve()" : conflict ? "the registry refused a report: see its error" : void 0)
+      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");
-    job.reports = await Promise.all(asks.map((a) => report(a, generated ? "generated" : "not_generated", outputHash, applied)));
-    job.unmetObligations = generated ? obligationsOf(job).filter((o) => !applied.includes(o.id)) : [];
-    Object.assign(job, { stage: "finished", generated, ...generated ? { outputHash } : {} });
-    await store.put(job);
-    return send(job);
+    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;
   }
-  const obligationsOf = (job) => job.asks.flatMap((a) => a.answer && (mode === "observe" || a.answer.body.status === "allow") ? (a.answer.body.obligations ?? []).map((o) => ({ subject: a.request.subject_ref, id: o.id, params: o.params ?? {} })) : []);
   async function outputHashOf(r) {
+    if (!isObj(r)) throw malformed("the generator must return { output, outputHash | outputBytes }");
     if (r.outputHash !== void 0) {
-      if (!HEX64.test(r.outputHash)) throw new PregenError("PG_MALFORMED", "outputHash must be 64 lowercase hex characters");
+      if (typeof r.outputHash !== "string" || !HEX64.test(r.outputHash)) throw malformed("outputHash must be 64 lowercase hex characters");
       return r.outputHash;
     }
-    if (r.outputBytes === void 0) throw new PregenError("PG_MALFORMED", "return outputHash or outputBytes");
-    return sha2562(typeof r.outputBytes === "string" ? enc.encode(r.outputBytes) : r.outputBytes);
+    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 ?? (input.prompt !== void 0 ? await sha2562(enc.encode(input.prompt)) : "");
-    if (!HEX64.test(promptHash)) throw new PregenError("PG_MALFORMED", "give prompt or a 64-hex promptHash");
-    const use = JSON.parse(JSON.stringify(input.use));
+    const promptHash = input.promptHash ?? await sha2562(enc.encode(input.prompt));
     const manifest = {
       job_id: input.jobId,
       provider_id: providerId,
@@ -579,7 +740,7 @@ function createPregen(config) {
       model: input.model,
       modality: input.modality,
       mode,
-      asks: subjects.map((s) => ({ subject_ref: s, registry: "", profile: PROFILE, use }))
+      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: [] };
@@ -588,8 +749,7 @@ function createPregen(config) {
       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 job = fresh;
-    job.asks = await Promise.all(subjects.map((s) => ask({
+    const asked = { ...fresh, stage: "asked", asks: await Promise.all(subjects.map((s) => ask({
       job_id: input.jobId,
       job_hash: jobHash,
       subject_ref: s,
@@ -599,60 +759,58 @@ function createPregen(config) {
       model: input.model,
       modality: input.modality,
       profile: PROFILE,
-      use,
+      use: input.use,
       mode
-    })));
-    job.stage = "asked";
-    await store.put(job);
+    }))) };
+    if (!await store.update(asked, "claimed")) return result(await reread(fresh));
     const at = now();
-    if (mode === "enforce" && !job.asks.every((a) => usableAllow(a, at))) return result(await finish(job, false));
+    if (mode === "enforce" && !asked.asks.every((a) => usableAllow(a, at))) return result(await finish(asked, false));
     let out;
     try {
-      out = await fn({ obligations: obligationsOf(job) });
+      out = await fn({ obligations: obligationsOf(asked) });
     } catch (e) {
-      await finish(job, false);
+      if (e?.notGenerated === true) await finish(asked, false);
       throw e;
     }
-    const outputHash = await outputHashOf(out);
-    return result(await finish(job, true, outputHash, out.obligationsApplied ?? []), out.output);
+    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) {
-      if (!JOB_ID.test(input?.jobId ?? "")) throw new PregenError("PG_MALFORMED", "jobId: 1-100 of A-Z a-z 0-9 _ . : -");
-      if (!Array.isArray(input.subjects) || !input.subjects.length) {
-        throw new PregenError("PG_MALFORMED", "subjects: name at least one; with no registered person there is nothing to ask");
-      }
-      return run(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. */
-    async flush() {
-      const out = [];
-      for (const job of await store.pending(providerId)) out.push(result(await send(job)));
-      return out;
-    },
+    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. */
+    /** 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" || job.stage === "done") return result(job.stage === "finished" ? await send(job) : job);
+      if (job.stage === "finished") return result(await send(job));
+      if (job.stage === "done") return result(job);
       if (!outcome.generated) {
         if (job.stage === "claimed") {
-          Object.assign(job, { stage: "done", generated: false });
-          await store.put(job);
-          return result(job);
+          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), outcome.obligationsApplied ?? []));
+      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). */
+    /** 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", {
@@ -663,8 +821,44 @@ function createPregen(config) {
         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 };
+      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 };
     }
   };
 }
@@ -678,8 +872,10 @@ function memoryStore() {
       jobs.set(k(job.providerId, job.jobId), structuredClone(job));
       return null;
     },
-    async put(job) {
+    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));
@@ -690,12 +886,18 @@ function memoryStore() {
     }
   };
 }
+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(`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))`).catch((e) => {
+    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;
     });
@@ -709,11 +911,12 @@ function postgresStore(pool) {
         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 put(job) {
-      await q(
-        "UPDATE pregen_jobs SET stage = $3, job = $4, updated_at = now() WHERE provider_id = $1 AND job_id = $2",
-        [job.providerId, job.jobId, job.stage, JSON.stringify(job)]
-      );
+    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) {
@@ -1815,6 +2018,7 @@ function sameEndpoint(a, b) {
 }
 export {
   HARD_REFUSAL_CODES,
+  NotGeneratedError,
   Prampta,
   PramptaApiError,
   PramptaError,
@@ -1839,6 +2043,7 @@ export {
   memoryStore,
   messageId,
   normalizeForMatch,
+  postgresSchema,
   postgresStore,
   signingInput,
   singleProcessJournal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prampta/sdk",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "PRAMPTA SDK — authorization before generation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,7 +24,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "typecheck:examples": "tsc -p tsconfig.examples.json",
-    "prepublishOnly": "npm run typecheck && npm run typecheck:examples && npm test",
+    "prepublishOnly": "npm run typecheck && npm run typecheck:examples && npm test && bash ../../scripts/sdk-v2-e2e/run.sh",
     "prepack": "npm run build"
   },
   "keywords": [
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@noble/ed25519": "^3.1.0",
-    "@pregen/verify": "^0.6.0"
+    "@pregen/verify": "^0.7.0"
   },
   "repository": {
     "type": "git",