parsanol 0.10.4 → 0.10.5

package/README.md

@@ -42,6 +42,28 @@ means the source moved since compilation — recompile or fall back.
 `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

@@ -48,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. */
@@ -86,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

@@ -107,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.4",
+  "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 @@
-b3459f6887a178ffd177922a9b7666a525da6e2d
+32937dcf6f5d7998a1f543292c88fe86b7a5a812
 built with: wasm-pack build --target=nodejs --features wasm (from parsanol-rs/parsanol)

package/vendor/parsanol-wasm/parsanol.cjs

@@ -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.

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.

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

@@ -9,6 +9,7 @@ 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 parsanol_c_last_error: () => number;