parsanol 0.10.3 → 0.10.5

package/README.md

@@ -23,6 +23,47 @@ const text = rt.renderString("ISO 5537:2025");    // F6 render
 
 Construction throws unless the artifact's embedded checksum verifies.
 
+## Provenance
+
+Every artifact embeds its provenance; the runtime exposes and verifies
+it (parsanol-ts#5):
+
+```ts
+rt.sourceHash;                    // SHA-256 of the .parg source (bare hex)
+rt.compilerVersion;               // the compiler that produced the artifact
+rt.source;                        // the embedded .parg source text
+rt.shape;                         // wire-format family, "parsanol-tree/v2"
+rt.compiledFrom(currentSource);   // false = the artifact is stale
+```
+
+A stale artifact (`compiledFrom` false against the current grammar text)
+means the source moved since compilation — recompile or fall back.
+`shape` moves independently of `compilerVersion`: the same
+`parsanol-tree/v2` artifact parses identically on every engine, forever;
+a shape bump means a new engine family.
+
+## Recovery (best-effort partial parses)
+
+`parseShapeRecovering` never throws: on success it returns
+`{ ok: true, shape }`; on failure it returns the "what did match"
+answer alongside the failure —
+
+```ts
+const r = rt.parseShapeRecovering("ab 4");
+// { ok: false,
+//   error: { offset: 4, expected: [...] },
+//   captures: { text: [{ value: "ab", offset: 0, ... }] },
+//   consumed_upto: 4 }
+```
+
+- `captures` carries every capture observed before the failure
+  (best-effort: it may include captures from branches that later
+  failed — same semantics as the rs recovery journal).
+- `consumed_upto` is the furthest position any successful match ended.
+
+The strict `parseShape` contract is unchanged; recovery is the
+editors-and-linters answer.
+
 ## Vendored engine freshness
 
 `vendor/parsanol-wasm/BUILT_FROM` records the parsanol-rs commit the

package/dist/runtime.d.ts

@@ -25,8 +25,21 @@ export declare class PargRuntime {
     readonly renderSpec: Record<string, RenderSegment[]>;
     readonly entry: string;
     readonly defaultEntry: string | null;
+    /** parsanol-ts#5 provenance: SHA-256 of the .parg source text and the
+     * compiler version. Null for artifacts compiled before these fields
+     * existed (unverifiable, not stale). */
+    readonly sourceHash: string | null;
+    readonly compilerVersion: string | null;
+    readonly source: string | null;
     readonly envelope: Record<string, unknown>;
     constructor(artifactJson: string, entry?: string);
+    /** The wire-format family ("parsanol-tree/v2"): a shape bump requires a
+     * new engine family; same-shape artifacts parse identically forever. */
+    get shape(): string | null;
+    /** True when this artifact was compiled from `source` (the current .parg
+     * revision). The compiler bakes a bare hex digest; artifacts without the
+     * field answer false — unverifiable rather than fresh. */
+    compiledFrom(source: string): boolean;
     /** Load an artifact JSON file and verify its checksum. */
     static fromFile(path: string, entry?: string): PargRuntime;
     /** The artifacts directory: PARG_ARTIFACT_DIR when set. */
@@ -35,6 +48,13 @@ export declare class PargRuntime {
     static load(grammar: string, entry?: string, dir?: string): PargRuntime;
     /** Parse with the native wasm engine; returns the parsanol-shape tree. */
     parseShape(input: string): unknown;
+    /**
+     * Best-effort recovery (TODO.sota/1): never throws. Success returns
+     * `{ ok: true, shape }`; failure returns
+     * `{ ok: false, captures, error, consumed_upto }` — the captures
+     * observed before the failure plus the failure wire.
+     */
+    parseShapeRecovering(input: string): RecoveryEnvelope;
     /** Apply the entry's bindings to a parsanol-shape tree. */
     applyBindings(shape: unknown): Record<string, unknown>;
     /** Parse and bind in one step. */
@@ -73,6 +93,21 @@ export type RenderSegment = {
 /** F6 v1 generic renderer: field / literal / cond-presence segments. */
 export declare function renderSegments(segments: RenderSegment[] | null, bound: Record<string, unknown>): string;
 /** A schema-materialized identifier: typed fields plus provenance. */
+export interface RecoveryError {
+    offset: number;
+    message?: string;
+    expected?: string[];
+    line?: number;
+    column?: number;
+}
+/** The parseShapeRecovering envelope (TODO.sota/1). */
+export interface RecoveryEnvelope {
+    ok: boolean;
+    shape?: unknown;
+    captures?: Record<string, unknown[]>;
+    error?: RecoveryError;
+    consumed_upto?: number;
+}
 export interface Materialized {
     entry: string;
     attributes: Record<string, unknown>;

package/dist/runtime.js

@@ -3,6 +3,7 @@
 //! materialization. The engine is the vendored parsanol wasm build
 //! (PargArtifactJs) — no grammar code lives in this package; the baked
 //! artifact is the contract.
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -42,6 +43,12 @@ export class PargRuntime {
     renderSpec;
     entry;
     defaultEntry;
+    /** parsanol-ts#5 provenance: SHA-256 of the .parg source text and the
+     * compiler version. Null for artifacts compiled before these fields
+     * existed (unverifiable, not stale). */
+    sourceHash;
+    compilerVersion;
+    source;
     envelope;
     constructor(artifactJson, entry) {
         const parsed = JSON.parse(artifactJson);
@@ -62,8 +69,24 @@ export class PargRuntime {
         // The compiler bakes default_entry: JSON key order is not preserved
         // across engines, so the sorted entry list cannot rederive it.
         this.defaultEntry = parsed["default_entry"] ?? null;
+        this.sourceHash = parsed["source_hash"] ?? null;
+        this.compilerVersion = parsed["compiler_version"] ?? null;
+        this.source = parsed["source"] ?? null;
         this.entry = entry ?? this.defaultEntry ?? this.artifact.entryNames()[0];
     }
+    /** The wire-format family ("parsanol-tree/v2"): a shape bump requires a
+     * new engine family; same-shape artifacts parse identically forever. */
+    get shape() {
+        return this.envelope["shape"] ?? null;
+    }
+    /** True when this artifact was compiled from `source` (the current .parg
+     * revision). The compiler bakes a bare hex digest; artifacts without the
+     * field answer false — unverifiable rather than fresh. */
+    compiledFrom(source) {
+        if (this.sourceHash === null)
+            return false;
+        return this.sourceHash === createHash("sha256").update(source).digest("hex");
+    }
     /** Load an artifact JSON file and verify its checksum. */
     static fromFile(path, entry) {
         return new PargRuntime(readFileSync(path, "utf8"), entry);
@@ -84,6 +107,15 @@ export class PargRuntime {
     parseShape(input) {
         return JSON.parse(this.artifact.parseShape(this.entry, input));
     }
+    /**
+     * Best-effort recovery (TODO.sota/1): never throws. Success returns
+     * `{ ok: true, shape }`; failure returns
+     * `{ ok: false, captures, error, consumed_upto }` — the captures
+     * observed before the failure plus the failure wire.
+     */
+    parseShapeRecovering(input) {
+        return JSON.parse(this.artifact.parseShapeRecovering(this.entry, input));
+    }
     /** Apply the entry's bindings to a parsanol-shape tree. */
     applyBindings(shape) {
         return JSON.parse(this.artifact.applyBindings(this.entry, JSON.stringify(shape)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parsanol",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "PARG artifact runtime for TypeScript \u2014 checksum-verified artifact load, wasm parse, bindings, schema-driven materialization",
   "type": "module",
   "main": "dist/runtime.js",

package/vendor/parsanol-wasm/BUILT_FROM

@@ -1,2 +1,2 @@
-68d8f05b92379bd78365ca29fae05fc58b76f235
+32937dcf6f5d7998a1f543292c88fe86b7a5a812
 built with: wasm-pack build --target=nodejs --features wasm (from parsanol-rs/parsanol)

package/vendor/parsanol-wasm/parsanol.cjs

@@ -39,7 +39,7 @@ class PargArtifactJs {
      */
     entryNames() {
         const ret = wasm.pargartifactjs_entryNames(this.__wbg_ptr);
-        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
         wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
         return v1;
     }
@@ -54,7 +54,7 @@ class PargArtifactJs {
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
-        this.__wbg_ptr = ret[0] >>> 0;
+        this.__wbg_ptr = ret[0];
         PargArtifactJsFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
@@ -75,6 +75,25 @@ class PargArtifactJs {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * Best-effort recovery (TODO.sota/1): success returns
+     * `{"ok": true, "shape": ...}`; failure returns
+     * `{"ok": false, "captures": ..., "error": ..., "consumed_upto"}`.
+     * @param {string} entry
+     * @param {string} input
+     * @returns {string}
+     */
+    parseShapeRecovering(entry, input) {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.pargartifactjs_parseShapeRecovering(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * Parse an entry with the native engine; returns the parsanol-shape
      * tree as JSON text.
@@ -106,22 +125,22 @@ class PargArtifactJs {
         return takeFromExternrefTable0(ret[0]);
     }
     /**
-     * The binding-requirements schema as JSON text.
+     * The binding-requirements schema as TypeScript source.
      * @returns {string}
      */
-    schema() {
-        const ret = wasm.pargartifactjs_schema(this.__wbg_ptr);
+    schemaTypescript() {
+        const ret = wasm.pargartifactjs_schemaTypescript(this.__wbg_ptr);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
         return takeFromExternrefTable0(ret[0]);
     }
     /**
-     * The binding-requirements schema as TypeScript source.
+     * The binding-requirements schema as JSON text.
      * @returns {string}
      */
-    schemaTypescript() {
-        const ret = wasm.pargartifactjs_schemaTypescript(this.__wbg_ptr);
+    schema() {
+        const ret = wasm.pargartifactjs_schema(this.__wbg_ptr);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
@@ -138,7 +157,6 @@ exports.PargArtifactJs = PargArtifactJs;
  */
 class WasmParser {
     static __wrap(ptr) {
-        ptr = ptr >>> 0;
         const obj = Object.create(WasmParser.prototype);
         obj.__wbg_ptr = ptr;
         WasmParserFinalization.register(obj, obj.__wbg_ptr, obj);
@@ -198,7 +216,7 @@ class WasmParser {
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
-        this.__wbg_ptr = ret[0] >>> 0;
+        this.__wbg_ptr = ret[0];
         WasmParserFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
@@ -295,11 +313,10 @@ function init() {
     wasm.init();
 }
 exports.init = init;
-
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg___wbindgen_string_get_395e606bd0ee4427: function(arg0, arg1) {
+        __wbg___wbindgen_string_get_0380ccaa2f57f0d9: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -307,10 +324,10 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_6ddd609b62940d55: function(arg0, arg1) {
+        __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_error_a6fa202b58aa1cd3: function(arg0, arg1) {
+        __wbg_error_757e9472f8410341: function(arg0, arg1) {
             let deferred0_0;
             let deferred0_1;
             try {
@@ -321,26 +338,26 @@ function __wbg_get_imports() {
                 wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
             }
         },
-        __wbg_getRandomValues_3f44b700395062e5: function() { return handleError(function (arg0, arg1) {
+        __wbg_getRandomValues_a608c4436c19407a: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
         __wbg_new_227d7c05414eb861: function() {
             const ret = new Error();
             return ret;
         },
-        __wbg_new_a70fbab9066b301f: function() {
-            const ret = new Array();
+        __wbg_new_617a8cdb8bb1130e: function() {
+            const ret = new Object();
             return ret;
         },
-        __wbg_new_ab79df5bd7c26067: function() {
-            const ret = new Object();
+        __wbg_new_ee2291f50781bf1d: function() {
+            const ret = new Array();
             return ret;
         },
-        __wbg_push_e87b0e732085a946: function(arg0, arg1) {
+        __wbg_push_2baf45db356cf468: function(arg0, arg1) {
             const ret = arg0.push(arg1);
             return ret;
         },
-        __wbg_set_7eaa4f96924fd6b3: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_set_145a351398b48c65: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
@@ -351,16 +368,16 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg_stringify_5ae93966a84901ac: function() { return handleError(function (arg0) {
+        __wbg_stringify_52ff602c1cc4fbb6: function() { return handleError(function (arg0) {
             const ret = JSON.stringify(arg0);
             return ret;
         }, arguments); },
-        __wbindgen_cast_0000000000000001: function(arg0) {
+        __wbindgen_generic_0000000000000001: function(arg0) {
             // Cast intrinsic for `F64 -> Externref`.
             const ret = arg0;
             return ret;
         },
-        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+        __wbindgen_generic_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return ret;
@@ -383,10 +400,10 @@ function __wbg_get_imports() {
 
 const PargArtifactJsFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
-    : new FinalizationRegistry(ptr => wasm.__wbg_pargartifactjs_free(ptr >>> 0, 1));
+    : new FinalizationRegistry(ptr => wasm.__wbg_pargartifactjs_free(ptr, 1));
 const WasmParserFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
-    : new FinalizationRegistry(ptr => wasm.__wbg_wasmparser_free(ptr >>> 0, 1));
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmparser_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
@@ -432,8 +449,7 @@ function getDataViewMemory0() {
 }
 
 function getStringFromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return decodeText(ptr, len);
+    return decodeText(ptr >>> 0, len);
 }
 
 let cachedUint8ArrayMemory0 = null;
@@ -524,5 +540,6 @@ let WASM_VECTOR_LEN = 0;
 const wasmPath = `${__dirname}/parsanol_bg.wasm`;
 const wasmBytes = require('fs').readFileSync(wasmPath);
 const wasmModule = new WebAssembly.Module(wasmBytes);
-let wasm = new WebAssembly.Instance(wasmModule, __wbg_get_imports()).exports;
+let wasmInstance = new WebAssembly.Instance(wasmModule, __wbg_get_imports());
+let wasm = wasmInstance.exports;
 wasm.__wbindgen_start();

package/vendor/parsanol-wasm/parsanol.d.ts

@@ -25,6 +25,12 @@ export class PargArtifactJs {
      * Parse and bind in one step.
      */
     parseAndBind(entry: string, input: string): string;
+    /**
+     * Best-effort recovery (TODO.sota/1): success returns
+     * `{"ok": true, "shape": ...}`; failure returns
+     * `{"ok": false, "captures": ..., "error": ..., "consumed_upto"}`.
+     */
+    parseShapeRecovering(entry: string, input: string): string;
     /**
      * Parse an entry with the native engine; returns the parsanol-shape
      * tree as JSON text.
@@ -35,14 +41,14 @@ export class PargArtifactJs {
      * JSON (empty array means green).
      */
     runTests(): string;
-    /**
-     * The binding-requirements schema as JSON text.
-     */
-    schema(): string;
     /**
      * The binding-requirements schema as TypeScript source.
      */
     schemaTypescript(): string;
+    /**
+     * The binding-requirements schema as JSON text.
+     */
+    schema(): string;
 }
 
 /**

package/vendor/parsanol-wasm/parsanol_bg.wasm.d.ts

@@ -3,14 +3,15 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_pargartifactjs_free: (a: number, b: number) => void;
 export const __wbg_wasmparser_free: (a: number, b: number) => void;
+export const init: () => void;
 export const pargartifactjs_applyBindings: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const pargartifactjs_entryNames: (a: number) => [number, number];
 export const pargartifactjs_new: (a: number, b: number) => [number, number, number];
 export const pargartifactjs_parseAndBind: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const pargartifactjs_parseShape: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const pargartifactjs_parseShapeRecovering: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const pargartifactjs_runTests: (a: number) => [number, number, number];
 export const pargartifactjs_schema: (a: number) => [number, number, number];
-export const pargartifactjs_schemaTypescript: (a: number) => [number, number, number];
 export const parsanol_c_last_error: () => number;
 export const parsanol_c_parse: (a: bigint, b: number, c: number, d: number) => number;
 export const parsanol_c_parse_len: (a: bigint, b: number, c: number, d: number, e: number) => number;
@@ -33,12 +34,12 @@ export const parsanol_result_error: (a: number) => number;
 export const parsanol_result_free: (a: number) => void;
 export const parsanol_result_success: (a: number) => number;
 export const parsanol_version: () => number;
+export const pargartifactjs_schemaTypescript: (a: number) => [number, number, number];
 export const wasmparser_fromArtifact: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const wasmparser_new: (a: number, b: number) => [number, number, number];
 export const wasmparser_parse: (a: number, b: number, c: number) => [number, number, number];
 export const wasmparser_parse_flat: (a: number, b: number, c: number) => [number, number, number, number];
 export const wasmparser_parse_json: (a: number, b: number, c: number) => [number, number, number, number];
-export const init: () => void;
 export const parsanol_string_free: (a: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;