@jarenjs/core 0.83.3 → 0.84.3

package/README.md

@@ -130,7 +130,7 @@ Three rules, kept by every function so that no caller has to check them again:
 - **A malformed comparison scores 0 and never throws.** Mismatched lengths, an empty vector, a null or a non-finite component answer 0: one bad vector among ten thousand loses the comparison, it does not kill the sweep, and it never poisons a ranking with `NaN`.
 - **Refuse, never fix.** `packVector` and `l2Normalize` answer `null` for anything `isVector` refuses, the way a bounding box refuses a position it cannot bound; nothing truncates, pads or zero-fills a vector into the shape it was supposed to have.
 
-The packed form is `4·d` bytes of little-endian binary32 — the value a database column stores; components round to `Math.fround` and come back exactly. Unpacking aligned bytes on a little-endian host is a *view*, not a copy, which is what a sweep over ten thousand fetched rows is paid for by; misaligned bytes (a pooled `Buffer`, an odd offset into a record) and big-endian hosts take the copy path to the same values. The client that produces embeddings — and a deterministic reference embedder for tests — lives in [`@jarenjs/ai`](../ai/README.md#embeddings).
+The packed form is `4·d` bytes of little-endian binary32 — the value a database column stores; components round to `Math.fround` and come back exactly. Unpacking aligned bytes on a little-endian host is a *view*, not a copy, which is what a sweep over ten thousand fetched rows is paid for by; misaligned bytes (a pooled `Buffer`, an odd offset into a record) and big-endian hosts take the copy path to the same values. Embedding services belong to the host; this package owns finite-vector validation, packing and similarity kernels.
 
 ## Intervals and series
 
@@ -303,6 +303,8 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/core/range` | JavaScript | declared |
 | `@jarenjs/core/retry` | JavaScript | declared |
 | `@jarenjs/core/schedule` | JavaScript | declared |
+| `@jarenjs/core/check` | JavaScript | declared |
+| `@jarenjs/core/guarded` | JavaScript | declared |
 <!--/fact-->
 
 ## Development
@@ -316,3 +318,13 @@ See [lexical search](docs/SEARCH.md) for the opt-in resident ranker and bounded
 [Bounded scheduling and retry](docs/SCHEDULING.md) describes `core/schedule` and
 `core/retry`: fair per-scope admission, drained shutdown, shared attempt budgets
 and explicit strict/AI/contract compatibility policies.
+
+## Checks and guarded editing
+
+`@jarenjs/core/check` exports `checkOutcome` and `composeChecks`. Only `true`
+or `{ valid: true }` passes. Composition stops at the first failure and
+preserves its errors. `@jarenjs/core/guarded` exports `createGuardedRefiner`: it
+copies JSON before validating/applying/planning, serializes its own commits,
+and pairs optional snapshot/restore hooks. A failed commit attempts restoration
+once and retains both original and restoration failures. External writers must
+share the host's serialization policy.

package/dist/types/check.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The shared reading of a compiled check's return value. Both the tool
+ * boundary and structured generation accept an injected `check`, and an
+ * injected one must answer strict true: the default
+ * `JarenValidator` check reports `{ valid, errors }`, a hand-written one
+ * may answer a bare boolean. Normalizing here keeps both call sites from
+ * having to know which kind they were handed.
+ */
+/**
+ * @param {any} outcome - a compiled check's return value
+ * @returns {{ valid: boolean, errors: any[] }}
+ */
+export declare function checkOutcome(outcome: any): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * Compose several checks into one, run in order: the FIRST invalid
+ * outcome wins and its errors are returned; a value that passes every
+ * check is valid with no errors. This is how "the reply validates
+ * against the schema AND compiles as a program" becomes a single
+ * injected `validator` — the schema check first (cheap, structural),
+ * the engine's compile gate second (semantic). It is deliberately
+ * engine-agnostic: a Jaren query, JSLT, app or flow compile gate all
+ * compose the same way, because each reports the same `{ valid, errors }`
+ * shape through {@link checkOutcome} and each error carries a `code`
+ * and a `docPath` the repair loop can act on.
+ *
+ * A compile gate is the two-line adapter `(doc) => { try { compile(doc);
+ * return true; } catch (e) { return { valid: false, errors: [{ code:
+ * e.code, docPath: e.docPath, message: e.reason ?? e.message }] }; } }`
+ * — `reason` is the bare text of a coded error; falling back to
+ * `message` keeps the adapter total over non-coded throws.
+ *
+ * @param {...(value: any) => any} checks - each returns a boolean or a
+ *   `{ valid, errors }` outcome (mixed freely)
+ * @returns {(value: any) => { valid: boolean, errors: any[] }}
+ */
+export declare function composeChecks(...checks: ((value: any) => any)[]): (value: any) => {
+    valid: boolean;
+    errors: any[];
+};

package/dist/types/guarded.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Guard edits to any JSON document using injected, synchronous validation and
+ * planning. Neither apply nor a validator receives the reader's original object.
+ * Commit owns atomic persistence (or snapshot/restore on a single writer).
+ * A failed restore is attempted once and retains both diagnostic causes.
+ * @param {{ read: () => Promise<any>, validateProposal: (proposal: any) => any,
+ *   apply: (document: any, proposal: any) => any,
+ *   validateCandidate: (next: any, previous: any) => any,
+ *   planCommit: (next: any, previous: any) => any,
+ *   commit: (plan: any, context: { previous: any, next: any, snapshot: any }) => Promise<any>,
+ *   snapshot?: () => Promise<any>, restore?: (token: any) => Promise<any>,
+ *   applyFailure?: (error: any) => any }} options
+ */
+export declare function createGuardedRefiner(options: {
+    read: () => Promise<any>;
+    validateProposal: (proposal: any) => any;
+    apply: (document: any, proposal: any) => any;
+    validateCandidate: (next: any, previous: any) => any;
+    planCommit: (next: any, previous: any) => any;
+    commit: (plan: any, context: {
+        previous: any;
+        next: any;
+        snapshot: any;
+    }) => Promise<any>;
+    snapshot?: () => Promise<any>;
+    restore?: (token: any) => Promise<any>;
+    applyFailure?: (error: any) => any;
+}): {
+    prepare: (document: any, proposal: any) => {
+        valid: boolean;
+        errors: any;
+        next?: undefined;
+        plan?: undefined;
+    } | {
+        valid: boolean;
+        errors: never[];
+        next: any;
+        plan: any;
+    };
+    commitPrepared: (previous: any, prepared: any) => Promise<{
+        ok: boolean;
+        stage: string;
+        errors: any;
+        cause?: undefined;
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        stage?: undefined;
+        cause?: undefined;
+        errors?: undefined;
+        ok: boolean;
+        value: any;
+        snapshot: any;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        snapshot: any;
+        restoreError?: {} | null | undefined;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        value?: undefined;
+    }>;
+    commit: (proposal: any) => Promise<{
+        ok: boolean;
+        stage: string;
+        errors: any;
+        cause?: undefined;
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        stage?: undefined;
+        cause?: undefined;
+        errors?: undefined;
+        ok: boolean;
+        value: any;
+        snapshot: any;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        snapshot: any;
+        restoreError?: {} | null | undefined;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        value?: undefined;
+    }>;
+};

package/dist/types/index.d.ts

@@ -117,3 +117,5 @@ export declare function getArrayClass(obj: any, def?: undefined): any;
  * @returns {Array} An array containing the inclusive and exclusive bounds.
  */
 export declare function getInclusiveExclusiveBounds(getType: Function, inclusive: number | string | undefined, exclusive: number | string | boolean | undefined): any[];
+export { checkOutcome, composeChecks } from './check.js';
+export { createGuardedRefiner } from './guarded.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.83.3",
+  "version": "0.84.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -192,6 +192,14 @@
     "./schedule": {
       "types": "./dist/types/schedule.d.ts",
       "default": "./src/schedule.js"
+    },
+    "./check": {
+      "types": "./dist/types/check.d.ts",
+      "default": "./src/check.js"
+    },
+    "./guarded": {
+      "types": "./dist/types/guarded.d.ts",
+      "default": "./src/guarded.js"
     }
   },
   "scripts": {

package/src/check.js

@@ -0,0 +1,51 @@
+//@ts-check
+/**
+ * The shared reading of a compiled check's return value. Both the tool
+ * boundary and structured generation accept an injected `check`, and an
+ * injected one must answer strict true: the default
+ * `JarenValidator` check reports `{ valid, errors }`, a hand-written one
+ * may answer a bare boolean. Normalizing here keeps both call sites from
+ * having to know which kind they were handed.
+ */
+
+/**
+ * @param {any} outcome - a compiled check's return value
+ * @returns {{ valid: boolean, errors: any[] }}
+ */
+export function checkOutcome(outcome) {
+  return typeof outcome === 'object' && outcome !== null
+    ? { valid: outcome.valid === true, errors: outcome.errors ?? [] }
+    : { valid: outcome === true, errors: [] };
+}
+
+/**
+ * Compose several checks into one, run in order: the FIRST invalid
+ * outcome wins and its errors are returned; a value that passes every
+ * check is valid with no errors. This is how "the reply validates
+ * against the schema AND compiles as a program" becomes a single
+ * injected `validator` — the schema check first (cheap, structural),
+ * the engine's compile gate second (semantic). It is deliberately
+ * engine-agnostic: a Jaren query, JSLT, app or flow compile gate all
+ * compose the same way, because each reports the same `{ valid, errors }`
+ * shape through {@link checkOutcome} and each error carries a `code`
+ * and a `docPath` the repair loop can act on.
+ *
+ * A compile gate is the two-line adapter `(doc) => { try { compile(doc);
+ * return true; } catch (e) { return { valid: false, errors: [{ code:
+ * e.code, docPath: e.docPath, message: e.reason ?? e.message }] }; } }`
+ * — `reason` is the bare text of a coded error; falling back to
+ * `message` keeps the adapter total over non-coded throws.
+ *
+ * @param {...(value: any) => any} checks - each returns a boolean or a
+ *   `{ valid, errors }` outcome (mixed freely)
+ * @returns {(value: any) => { valid: boolean, errors: any[] }}
+ */
+export function composeChecks(...checks) {
+  return (value) => {
+    for (const check of checks) {
+      const outcome = checkOutcome(check(value));
+      if (!outcome.valid) return outcome;
+    }
+    return { valid: true, errors: [] };
+  };
+}

package/src/guarded.js

@@ -0,0 +1,90 @@
+//@ts-check
+import { checkOutcome } from './check.js';
+
+const copy = (value) => value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+const failure = (error, stage) => ({ code: error?.code ?? 'GUARDED',
+  docPath: error?.docPath ?? '', message: error?.message ?? String(error), stage });
+
+/**
+ * Guard edits to any JSON document using injected, synchronous validation and
+ * planning. Neither apply nor a validator receives the reader's original object.
+ * Commit owns atomic persistence (or snapshot/restore on a single writer).
+ * A failed restore is attempted once and retains both diagnostic causes.
+ * @param {{ read: () => Promise<any>, validateProposal: (proposal: any) => any,
+ *   apply: (document: any, proposal: any) => any,
+ *   validateCandidate: (next: any, previous: any) => any,
+ *   planCommit: (next: any, previous: any) => any,
+ *   commit: (plan: any, context: { previous: any, next: any, snapshot: any }) => Promise<any>,
+ *   snapshot?: () => Promise<any>, restore?: (token: any) => Promise<any>,
+ *   applyFailure?: (error: any) => any }} options
+ */
+export function createGuardedRefiner(options) {
+  for (const name of ['read', 'validateProposal', 'apply', 'validateCandidate', 'planCommit', 'commit'])
+    if (typeof options[name] !== 'function') throw new TypeError(`guarded refiner needs ${name}`);
+  if (Boolean(options.snapshot) !== Boolean(options.restore))
+    throw new TypeError('snapshot and restore must be supplied together');
+  let pending = Promise.resolve();
+
+  /** Validate and plan without mutating the source or proposal. */
+  function prepare(document, proposal) {
+    let stage = 'shape';
+    try {
+      const patch = copy(proposal);
+      const shape = checkOutcome(options.validateProposal(patch));
+      if (!shape.valid) return { valid: false, errors: shape.errors };
+      const previous = copy(document);
+      stage = 'apply';
+      const next = options.apply(copy(previous), patch);
+      stage = 'candidate';
+      const candidate = checkOutcome(options.validateCandidate(copy(next), copy(previous)));
+      if (!candidate.valid) return { valid: false, errors: candidate.errors };
+      stage = 'plan';
+      const planned = options.planCommit(copy(next), copy(previous));
+      if (planned?.valid === false) return { valid: false, errors: planned.errors };
+      return { valid: true, errors: [], next, plan: planned?.plan ?? planned };
+    }
+    catch (error) {
+      return { valid: false, errors: [stage === 'apply' && options.applyFailure
+        ? options.applyFailure(error) : failure(error, stage)] };
+    }
+  }
+
+  /** Commit a prepared candidate; callers must serialize any external writers. */
+  async function commitPrepared(previous, prepared) {
+    if (!prepared.valid) return { ok: false, stage: 'validation', errors: prepared.errors };
+    let token;
+    try { token = options.snapshot ? await options.snapshot() : null; }
+    catch (error) { return { ok: false, stage: 'snapshot', cause: error, errors: [failure(error, 'snapshot')] }; }
+    try {
+      const value = await options.commit(copy(prepared.plan), {
+        previous: copy(previous), next: copy(prepared.next), snapshot: token,
+      });
+      return { ok: true, value, snapshot: token };
+    }
+    catch (cause) {
+      let restoreError;
+      if (options.restore) {
+        try {
+          const restored = await options.restore(token);
+          if (restored?.error !== undefined) throw new Error(restored.error);
+        }
+        catch (error) { restoreError = error; }
+      }
+      return { ok: false, stage: 'commit', cause, snapshot: token,
+        ...(restoreError === undefined ? {} : { restoreError }),
+        errors: [failure(cause, 'commit'), ...(restoreError === undefined ? [] : [failure(restoreError, 'restore')])] };
+    }
+  }
+
+  /** Read, prepare and commit one proposal, serialized with this engine's peers. */
+  function commit(proposal) {
+    const captured = copy(proposal);
+    const result = pending.then(async () => {
+      const previous = await options.read();
+      return commitPrepared(previous, prepare(previous, captured));
+    });
+    pending = result.then(() => undefined, () => undefined);
+    return result;
+  }
+  return { prepare, commitPrepared, commit };
+}

package/src/index.js

@@ -221,3 +221,6 @@ export function getInclusiveExclusiveBounds(getType, inclusive, exclusive) {
     ? [includes, undefined]
     : [undefined, excludes];
 }
+
+export { checkOutcome, composeChecks } from './check.js';
+export { createGuardedRefiner } from './guarded.js';