@prampta/sdk 0.11.1 → 0.11.3

package/README.md

@@ -40,8 +40,8 @@ exists solely so an already-connected provider keeps working mid-migration.
 
 `createPregen` speaks the simplified PRE-GEN v5 formats at `/v2`: signed
 answers bound to your request, signed reports, signed acknowledgements. Set it
-up once; wrap each generation in one call. Use 0.11.1 or later: 0.10.0 and
-0.11.0 had defects found by external reviews (see CHANGELOG). A complete
+up once; wrap each generation in one call. Use 0.11.3 or later: earlier versions
+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
@@ -180,8 +180,9 @@ const result = await pg.generateAuthorized(
   { subjectIds: [subjectCode], generationId: jobId, promptHash, model, modality: "image",
     intendedUse: { useCase: "commercial" } },
   async (decisions) => {
-    const image = await render(prompt); // apply every decision's obligations
-    return { output: image, outputBytes: image.bytes };
+    const image = await render(prompt, decisions.map((d) => d.obligations));   // apply the obligations yourself
+    return { output: image, outputBytes: image.bytes,
+      obligationsApplied: { attribution: true } };   // only what you actually did (0.11.3: nothing is assumed)
   },
   { journal },
 );
@@ -267,10 +268,17 @@ const decision = await pg.assertLicensed(subjectCode, {
 - stores the output hash and the **exact receipts** (signed, if you sign)
   before sending them, and after a failure resends those receipts byte for
   byte — receipt options passed on a later call do not replace them;
-- a receipt counts as filed only when the registry accepted exactly it:
-  `unreported` lists receipts to resend (call again with the same id and
-  request), `conflicts` lists decisions for which the registry holds a
+- a receipt counts as filed only when the registry's answer is about exactly
+  it (0.11.3): `recorded` or `already_recorded`, this decision, and the
+  `receipt_hash` of these bytes (`checkReceiptAck`; `submitReceipt` checks
+  it too); `unreported` lists receipts to resend (call again with the same
+  id and request), `conflicts` lists decisions for which the registry holds a
   different receipt;
+- claims only the obligations your `generate` returns in
+  `obligationsApplied` (and `watermarkEmbedded`); with none, the receipt
+  says none were applied and PRAMPTA records it as not compliant. Before
+  0.11.3 the SDK copied the decision's obligations into the receipt, a claim
+  of work nobody had confirmed;
 - gives the allows back (`releaseDecision`) when a subject refuses or your
   `generate` throws; that job is then closed, use a new `generationId`;
 - never reruns a job that may have started generating.

package/dist/index.d.mts

@@ -619,6 +619,17 @@ interface AuthorizedGeneration<T> {
      * Resending will not help; find out why. */
     conflicts: SignedDecision[];
 }
+/** What your `generate` returns to `generateAuthorized`. Report only obligations you carried out: the receipt is a
+ * signed statement, and nothing is claimed on your behalf. */
+interface GeneratedOutput<T> {
+    output: T;
+    outputHash?: string;
+    outputBytes?: Uint8Array | string;
+    /** The obligations you applied, by name (e.g. `{ attribution: true }`). Default: none. */
+    obligationsApplied?: Record<string, unknown>;
+    /** Whether you embedded the watermark an obligation asked for. Default: false. */
+    watermarkEmbedded?: boolean;
+}
 interface OutputMetadata {
     prampta_decision_id: string;
     prampta_license_id: string | null;
@@ -819,11 +830,7 @@ declare class Prampta {
      * If a subject refuses or `generate` throws, the allows are given back.
      * `generate` must throw only when nothing was produced.
      */
-    generateAuthorized<T>(request: AuthorizedRequest, generate: (decisions: SignedDecision[]) => Promise<{
-        output: T;
-        outputHash?: string;
-        outputBytes?: Uint8Array | string;
-    }>, options: {
+    generateAuthorized<T>(request: AuthorizedRequest, generate: (decisions: SignedDecision[]) => Promise<GeneratedOutput<T>>, options: {
         journal: GenerationJournal;
         receipt?: ReceiptOptions;
     }): Promise<AuthorizedGeneration<T>>;
@@ -855,6 +862,10 @@ declare class Prampta {
         /** 32-byte Ed25519 private key, hex; keep server-side. Never sent to PRAMPTA. */
         providerSigningKeyHex?: string;
     }): Promise<Record<string, unknown>>;
+    /** A receipt counts as filed only when PRAMPTA's answer is about exactly it: `recorded` or `already_recorded`
+     * (the identical receipt again), this decision, and the receipt_hash of the body the registry built from these
+     * bytes (app/core/receipt_body.py). A success status alone proves nothing about which receipt was accepted. */
+    checkReceiptAck(decision: SignedDecision, payload: Record<string, unknown>, ack: unknown): Promise<Record<string, unknown>>;
     /** The exact receipt body submitReceipt() would send, signed if a key is given. */
     buildReceipt(decision: SignedDecision, result?: NonNullable<Parameters<Prampta["submitReceipt"]>[1]>): Promise<Record<string, unknown>>;
     /**
@@ -892,4 +903,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, 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 };
+export { type AskResult, type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type Envelope, type GenerateFn, type GeneratedOutput, 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

@@ -619,6 +619,17 @@ interface AuthorizedGeneration<T> {
      * Resending will not help; find out why. */
     conflicts: SignedDecision[];
 }
+/** What your `generate` returns to `generateAuthorized`. Report only obligations you carried out: the receipt is a
+ * signed statement, and nothing is claimed on your behalf. */
+interface GeneratedOutput<T> {
+    output: T;
+    outputHash?: string;
+    outputBytes?: Uint8Array | string;
+    /** The obligations you applied, by name (e.g. `{ attribution: true }`). Default: none. */
+    obligationsApplied?: Record<string, unknown>;
+    /** Whether you embedded the watermark an obligation asked for. Default: false. */
+    watermarkEmbedded?: boolean;
+}
 interface OutputMetadata {
     prampta_decision_id: string;
     prampta_license_id: string | null;
@@ -819,11 +830,7 @@ declare class Prampta {
      * If a subject refuses or `generate` throws, the allows are given back.
      * `generate` must throw only when nothing was produced.
      */
-    generateAuthorized<T>(request: AuthorizedRequest, generate: (decisions: SignedDecision[]) => Promise<{
-        output: T;
-        outputHash?: string;
-        outputBytes?: Uint8Array | string;
-    }>, options: {
+    generateAuthorized<T>(request: AuthorizedRequest, generate: (decisions: SignedDecision[]) => Promise<GeneratedOutput<T>>, options: {
         journal: GenerationJournal;
         receipt?: ReceiptOptions;
     }): Promise<AuthorizedGeneration<T>>;
@@ -855,6 +862,10 @@ declare class Prampta {
         /** 32-byte Ed25519 private key, hex; keep server-side. Never sent to PRAMPTA. */
         providerSigningKeyHex?: string;
     }): Promise<Record<string, unknown>>;
+    /** A receipt counts as filed only when PRAMPTA's answer is about exactly it: `recorded` or `already_recorded`
+     * (the identical receipt again), this decision, and the receipt_hash of the body the registry built from these
+     * bytes (app/core/receipt_body.py). A success status alone proves nothing about which receipt was accepted. */
+    checkReceiptAck(decision: SignedDecision, payload: Record<string, unknown>, ack: unknown): Promise<Record<string, unknown>>;
     /** The exact receipt body submitReceipt() would send, signed if a key is given. */
     buildReceipt(decision: SignedDecision, result?: NonNullable<Parameters<Prampta["submitReceipt"]>[1]>): Promise<Record<string, unknown>>;
     /**
@@ -892,4 +903,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, 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 };
+export { type AskResult, type AuthorizedGeneration, type AuthorizedRequest, type DeliveryResult, type Envelope, type GenerateFn, type GeneratedOutput, 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.js

@@ -502,7 +502,7 @@ 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 keysWithin(b, ["kind", "grant"]) && isObj(g) && typeof g.format === "string" && Object.hasOwn(GRANT_FORMATS, g.format) && GRANT_FORMATS[g.format](g) === true;
   }
   return b.kind === "policy" && keysWithin(b, ["kind", "rule"]) && str(b.rule);
 }
@@ -1787,16 +1787,20 @@ var Prampta = class _Prampta {
     const outputHash = result.outputHash ?? (bytes ? await sha256Bytes(bytes) : "");
     const generatedAt = Math.floor(Date.now() / 1e3);
     const receipts = {};
-    for (const d of decisions) receipts[d.decisionId] = await this.buildReceipt(d, { ...receipt, outputHash, generatedAt });
+    const done = {
+      ...result.obligationsApplied !== void 0 ? { obligationsApplied: result.obligationsApplied } : {},
+      ...result.watermarkEmbedded !== void 0 ? { watermarkEmbedded: result.watermarkEmbedded } : {}
+    };
+    for (const d of decisions) receipts[d.decisionId] = await this.buildReceipt(d, { ...receipt, ...done, outputHash, generatedAt });
     const generated = { ...entry, stage: "generated", outputHash, generatedAt, receipts };
     await journal.put(generated);
     return this.report(journal, generated, "generated", result.output, receipt);
   }
   async report(journal, entry, status, output, receipt) {
-    const results = await Promise.allSettled(entry.decisions.map(async (d) => this.post(
-      "/v1/receipts/",
-      entry.receipts?.[d.decisionId] ?? await this.buildReceipt(d, { ...receipt, outputHash: entry.outputHash ?? "", generatedAt: entry.generatedAt })
-    )));
+    const results = await Promise.allSettled(entry.decisions.map(async (d) => {
+      const payload = entry.receipts?.[d.decisionId] ?? await this.buildReceipt(d, { ...receipt, outputHash: entry.outputHash ?? "", generatedAt: entry.generatedAt });
+      return this.checkReceiptAck(d, payload, await this.post("/v1/receipts/", payload));
+    }));
     const unreported = [], conflicts = [];
     results.forEach((r, i) => {
       if (r.status === "fulfilled") return;
@@ -1863,7 +1867,33 @@ var Prampta = class _Prampta {
    * provider attestation, not proof of complete reporting or actual execution.
    */
   async submitReceipt(decision, result = {}) {
-    return this.post("/v1/receipts/", await this.buildReceipt(decision, result));
+    const payload = await this.buildReceipt(decision, result);
+    return this.checkReceiptAck(decision, payload, await this.post("/v1/receipts/", payload));
+  }
+  /** A receipt counts as filed only when PRAMPTA's answer is about exactly it: `recorded` or `already_recorded`
+   * (the identical receipt again), this decision, and the receipt_hash of the body the registry built from these
+   * bytes (app/core/receipt_body.py). A success status alone proves nothing about which receipt was accepted. */
+  async checkReceiptAck(decision, payload, ack) {
+    const a = ack;
+    const v = String(payload.schema_version ?? "pg.receipt.v2");
+    const body = {
+      v,
+      decision_id: payload.decision_id,
+      subject_id: decision.subjectId,
+      licensee_id: this.licenseeId,
+      provider_id: this.providerId,
+      prompt_hash: payload.prompt_hash,
+      output_hash: payload.output_hash,
+      model: payload.model,
+      obligations_applied: payload.obligations_applied,
+      watermark_embedded: payload.watermark_embedded,
+      generated_at: payload.generated_at,
+      ...v === "pg.receipt.v3" ? { event_type: payload.event_type } : {}
+    };
+    if (!a || typeof a !== "object" || a.status !== "recorded" && a.status !== "already_recorded" || a.decision_id !== decision.decisionId || a.receipt_hash !== await sha2563(canonicalJson(body))) {
+      throw new PramptaSchemaError("The registry's receipt answer is not about this receipt");
+    }
+    return a;
   }
   /** The exact receipt body submitReceipt() would send, signed if a key is given. */
   async buildReceipt(decision, result = {}) {
@@ -1873,7 +1903,8 @@ var Prampta = class _Prampta {
       output_hash: result.outputHash ?? "",
       model: result.model ?? decision.model,
       watermark_embedded: result.watermarkEmbedded ?? false,
-      obligations_applied: result.obligationsApplied ?? decision.obligations ?? {},
+      // Only what the caller says it did: copying the decision's obligations here claimed work never done.
+      obligations_applied: result.obligationsApplied ?? {},
       generated_at: result.generatedAt ?? Math.floor(Date.now() / 1e3)
     };
     if (result.providerSigningKeyHex !== void 0) {

package/dist/index.mjs

@@ -437,7 +437,7 @@ 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 keysWithin(b, ["kind", "grant"]) && isObj(g) && typeof g.format === "string" && Object.hasOwn(GRANT_FORMATS, g.format) && GRANT_FORMATS[g.format](g) === true;
   }
   return b.kind === "policy" && keysWithin(b, ["kind", "rule"]) && str(b.rule);
 }
@@ -1722,16 +1722,20 @@ var Prampta = class _Prampta {
     const outputHash = result.outputHash ?? (bytes ? await sha256Bytes(bytes) : "");
     const generatedAt = Math.floor(Date.now() / 1e3);
     const receipts = {};
-    for (const d of decisions) receipts[d.decisionId] = await this.buildReceipt(d, { ...receipt, outputHash, generatedAt });
+    const done = {
+      ...result.obligationsApplied !== void 0 ? { obligationsApplied: result.obligationsApplied } : {},
+      ...result.watermarkEmbedded !== void 0 ? { watermarkEmbedded: result.watermarkEmbedded } : {}
+    };
+    for (const d of decisions) receipts[d.decisionId] = await this.buildReceipt(d, { ...receipt, ...done, outputHash, generatedAt });
     const generated = { ...entry, stage: "generated", outputHash, generatedAt, receipts };
     await journal.put(generated);
     return this.report(journal, generated, "generated", result.output, receipt);
   }
   async report(journal, entry, status, output, receipt) {
-    const results = await Promise.allSettled(entry.decisions.map(async (d) => this.post(
-      "/v1/receipts/",
-      entry.receipts?.[d.decisionId] ?? await this.buildReceipt(d, { ...receipt, outputHash: entry.outputHash ?? "", generatedAt: entry.generatedAt })
-    )));
+    const results = await Promise.allSettled(entry.decisions.map(async (d) => {
+      const payload = entry.receipts?.[d.decisionId] ?? await this.buildReceipt(d, { ...receipt, outputHash: entry.outputHash ?? "", generatedAt: entry.generatedAt });
+      return this.checkReceiptAck(d, payload, await this.post("/v1/receipts/", payload));
+    }));
     const unreported = [], conflicts = [];
     results.forEach((r, i) => {
       if (r.status === "fulfilled") return;
@@ -1798,7 +1802,33 @@ var Prampta = class _Prampta {
    * provider attestation, not proof of complete reporting or actual execution.
    */
   async submitReceipt(decision, result = {}) {
-    return this.post("/v1/receipts/", await this.buildReceipt(decision, result));
+    const payload = await this.buildReceipt(decision, result);
+    return this.checkReceiptAck(decision, payload, await this.post("/v1/receipts/", payload));
+  }
+  /** A receipt counts as filed only when PRAMPTA's answer is about exactly it: `recorded` or `already_recorded`
+   * (the identical receipt again), this decision, and the receipt_hash of the body the registry built from these
+   * bytes (app/core/receipt_body.py). A success status alone proves nothing about which receipt was accepted. */
+  async checkReceiptAck(decision, payload, ack) {
+    const a = ack;
+    const v = String(payload.schema_version ?? "pg.receipt.v2");
+    const body = {
+      v,
+      decision_id: payload.decision_id,
+      subject_id: decision.subjectId,
+      licensee_id: this.licenseeId,
+      provider_id: this.providerId,
+      prompt_hash: payload.prompt_hash,
+      output_hash: payload.output_hash,
+      model: payload.model,
+      obligations_applied: payload.obligations_applied,
+      watermark_embedded: payload.watermark_embedded,
+      generated_at: payload.generated_at,
+      ...v === "pg.receipt.v3" ? { event_type: payload.event_type } : {}
+    };
+    if (!a || typeof a !== "object" || a.status !== "recorded" && a.status !== "already_recorded" || a.decision_id !== decision.decisionId || a.receipt_hash !== await sha2563(canonicalJson(body))) {
+      throw new PramptaSchemaError("The registry's receipt answer is not about this receipt");
+    }
+    return a;
   }
   /** The exact receipt body submitReceipt() would send, signed if a key is given. */
   async buildReceipt(decision, result = {}) {
@@ -1808,7 +1838,8 @@ var Prampta = class _Prampta {
       output_hash: result.outputHash ?? "",
       model: result.model ?? decision.model,
       watermark_embedded: result.watermarkEmbedded ?? false,
-      obligations_applied: result.obligationsApplied ?? decision.obligations ?? {},
+      // Only what the caller says it did: copying the decision's obligations here claimed work never done.
+      obligations_applied: result.obligationsApplied ?? {},
       generated_at: result.generatedAt ?? Math.floor(Date.now() / 1e3)
     };
     if (result.providerSigningKeyHex !== void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prampta/sdk",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "PRAMPTA SDK — authorization before generation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@noble/ed25519": "^3.1.0",
-    "@pregen/verify": "^0.7.0"
+    "@pregen/verify": "^0.8.0"
   },
   "repository": {
     "type": "git",