tokenfold 0.5.0 → 0.5.1

package/README.md

@@ -19,6 +19,12 @@ const { payload, report, text } = await compress(input, {
 Payloads are `Uint8Array`; the `text` convenience getter decodes UTF-8 strictly.
 `inspect` returns only the side-effect-free receipt.
 
+`parseReport(jsonOrBytes)` reads archived v1 and current v2 receipts. It preserves the
+source schema version, normalizes v1 `mode` to `preset`, and leaves unavailable sections
+as `null`. Unknown versions and invalid required top-level fields raise
+`TokenFoldProcessError` with `code: "invalid_report"`; this is not recursive JSON Schema
+validation. `compress` and `inspect` use the same versioned reader.
+
 Recoverable pruning is explicit and generic-JSON-only:
 
 ```ts

package/dist/index.d.ts

@@ -152,6 +152,8 @@ export declare class BudgetUnmetError extends Error {
     readonly receipt: CompressionReceipt;
     constructor(receipt: CompressionReceipt);
 }
+/** Read archived v1 or current v2 receipts; unavailable sections remain null. */
+export declare function parseReport(input: string | Uint8Array): CompressionReceipt;
 export declare function compress(input: Input, options?: CompressionOptions): Promise<CompressionResult>;
 export declare function inspect(input: Input, options?: CompressionOptions): Promise<CompressionReceipt>;
 export declare function decode(input: Input, options?: {

package/dist/index.js

@@ -37,12 +37,48 @@ function parseReceipt(bytes, result) {
     const text = Buffer.from(bytes).toString("utf8");
     const json = text.split("\ntokenfold:", 1)[0] ?? "";
     try {
-        return JSON.parse(json);
+        return parseReport(json);
     }
     catch (cause) {
         throw new TokenFoldProcessError("tokenfold returned an invalid JSON receipt", { code: "invalid_report", exitCode: result.exitCode, signal: result.signal, stderr: result.stderr, cause });
     }
 }
+/** Read archived v1 or current v2 receipts; unavailable sections remain null. */
+export function parseReport(input) {
+    try {
+        const value = JSON.parse(typeof input === "string" ? input : new TextDecoder("utf-8", { fatal: true }).decode(input));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("not a receipt object");
+        if (!["1.0", "2.0"].includes(value.schema_version))
+            throw new Error("unsupported receipt schema_version");
+        if (value.schema_version === "1.0") {
+            if (!Object.hasOwn(value, "preset")) {
+                value.preset = value.mode;
+                delete value.mode;
+            }
+            if (!Object.hasOwn(value, "output_encoding"))
+                value.output_encoding = "native";
+        }
+        for (const key of ["original_tokens", "compressed_tokens", "saved_tokens", "savings_ratio", "savings_pct"]) {
+            if (typeof value[key] !== "number" || !Number.isFinite(value[key]) || value[key] < 0)
+                throw new Error(`invalid ${key}`);
+        }
+        for (const key of ["status", "preset", "format", "output_encoding", "task_scope"]) {
+            if (typeof value[key] !== "string")
+                throw new Error(`invalid ${key}`);
+        }
+        if (!value.estimator || typeof value.estimator.backend !== "string" || typeof value.estimator.is_exact !== "boolean"
+            || !Array.isArray(value.transforms) || !Array.isArray(value.warnings))
+            throw new Error("invalid receipt fields");
+        for (const key of ["request_id", "pipeline", "quality", "budget", "encoding", "pruning", "cache", "retrieval", "output_savings", "bypass", "command", "ledger"]) {
+            value[key] ??= null;
+        }
+        return value;
+    }
+    catch (cause) {
+        throw new TokenFoldProcessError("not a supported compression receipt", { code: "invalid_report", cause });
+    }
+}
 function optionsFor(input, signal) {
     const options = { env: { TOKENFOLD_ANALYTICS_ENABLED: "false" } };
     if (input !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenfold",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Token-aware compression for LLM payloads, backed by the tokenfold Rust CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -49,11 +49,11 @@
     "prepack": "npm run build"
   },
   "optionalDependencies": {
-    "@tokenfold/cli-darwin-x64": "0.5.0",
-    "@tokenfold/cli-darwin-arm64": "0.5.0",
-    "@tokenfold/cli-linux-x64": "0.5.0",
-    "@tokenfold/cli-linux-arm64": "0.5.0",
-    "@tokenfold/cli-win32-x64": "0.5.0"
+    "@tokenfold/cli-darwin-x64": "0.5.1",
+    "@tokenfold/cli-darwin-arm64": "0.5.1",
+    "@tokenfold/cli-linux-x64": "0.5.1",
+    "@tokenfold/cli-linux-arm64": "0.5.1",
+    "@tokenfold/cli-win32-x64": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",