@shapeshift-labs/frontier-engine 0.0.1 → 0.1.0

package/README.md

@@ -1,51 +1,201 @@
 # Frontier Engine
 
-Reserved package name for the future Frontier planned diff engine package.
+Stateful planned diff engine, adaptive profiles, history planning, and reusable diff caches for Frontier.
 
-This package is not ready for production use. It exists so the package and repository names are reserved while stateful diff planning, adaptive profiles, schema plans, and engine/history boundaries are finalized.
+This package sits above [`@shapeshift-labs/frontier`](https://www.npmjs.com/package/@shapeshift-labs/frontier), the small JSON diff/apply core package. It uses [`@shapeshift-labs/frontier-codec`](https://www.npmjs.com/package/@shapeshift-labs/frontier-codec) for patch-history byte helpers. Keeping the engine separate keeps core imports small while giving state, history, and CRDT layers a shared planning surface.
 
 - npm: [`@shapeshift-labs/frontier-engine`](https://www.npmjs.com/package/@shapeshift-labs/frontier-engine)
 - source: [`siliconjungle/-shapeshift-labs-frontier-engine`](https://github.com/siliconjungle/-shapeshift-labs-frontier-engine)
-- core package: [`@shapeshift-labs/frontier`](https://www.npmjs.com/package/@shapeshift-labs/frontier)
-- codec package: [`@shapeshift-labs/frontier-codec`](https://www.npmjs.com/package/@shapeshift-labs/frontier-codec)
 - license: MIT
 
-## Intended Scope
+## Related Packages
+
+- [`@shapeshift-labs/frontier`](https://www.npmjs.com/package/@shapeshift-labs/frontier): core JSON diff/apply primitives.
+- [`@shapeshift-labs/frontier-codec`](https://www.npmjs.com/package/@shapeshift-labs/frontier-codec): patch serialization, binary frames, canonical JSON, and patch-history codecs.
+- [`@shapeshift-labs/frontier-query`](https://www.npmjs.com/package/@shapeshift-labs/frontier-query): shared query-key, selector path, condition, identity, and table-schema primitives.
+- [`@shapeshift-labs/frontier-mutation`](https://www.npmjs.com/package/@shapeshift-labs/frontier-mutation): explicit mutation and selector plans that can use engine-backed diff planning.
+
+Package source repositories:
+
+- [`siliconjungle/-shapeshift-labs-frontier`](https://github.com/siliconjungle/-shapeshift-labs-frontier)
+- [`siliconjungle/-shapeshift-labs-frontier-codec`](https://github.com/siliconjungle/-shapeshift-labs-frontier-codec)
+- [`siliconjungle/-shapeshift-labs-frontier-query`](https://github.com/siliconjungle/-shapeshift-labs-frontier-query)
+- [`siliconjungle/-shapeshift-labs-frontier-mutation`](https://github.com/siliconjungle/-shapeshift-labs-frontier-mutation)
+
+## Install
+
+```sh
+npm install @shapeshift-labs/frontier @shapeshift-labs/frontier-codec @shapeshift-labs/frontier-engine
+```
+
+## Usage
+
+```ts
+import { applyPatchImmutable } from '@shapeshift-labs/frontier';
+import { createDiffEngine } from '@shapeshift-labs/frontier-engine';
+
+const engine = createDiffEngine({
+  schema: {
+    type: 'array',
+    path: ['todos'],
+    key: 'id',
+    item: {
+      type: 'object',
+      fields: ['id', 'done', 'title']
+    }
+  }
+});
+
+const before = {
+  todos: [{ id: 'a', done: false, title: 'Draft' }]
+};
+const after = {
+  todos: [{ id: 'a', done: true, title: 'Draft' }]
+};
+
+const patch = engine.diff(before, after);
+const next = applyPatchImmutable(before, patch);
+```
+
+## API
+
+```ts
+import {
+  createDiffEngine,
+  cloneProfilePlans,
+  createEngineProfilePlansSnapshot,
+  mergeProfilePlans,
+  readProfilePlans,
+  type DiffEngine,
+  type DiffProfile,
+  type EngineOptions,
+  type ProfilePlans
+} from '@shapeshift-labs/frontier-engine';
+```
+
+### `createDiffEngine(options?)`
+
+Creates a reusable diff engine with optional schema, adaptive learning, history planning, and equality/profile helpers.
+
+```ts
+const engine = createDiffEngine({
+  adaptive: true,
+  adaptiveThreshold: 2,
+  arrayKey: 'id'
+});
+
+const patch = engine.diff(before, after);
+const reusable = [];
+engine.diffInto(before, after, reusable);
+```
 
-When this package graduates from placeholder status, it is expected to contain:
+### Schema Plans
+
+Schema plans are trusted shape hints for hot JSON structures. They let the engine skip generic discovery and emit compact patches for common record-array and object shapes.
+
+```ts
+const engine = createDiffEngine({
+  schema: {
+    type: 'array',
+    path: ['rows'],
+    key: 'id',
+    item: {
+      type: 'object',
+      fields: ['id', 'score', 'active', 'label']
+    }
+  }
+});
+```
+
+### Adaptive Profiles
+
+Adaptive engines can learn a profile from representative before/after pairs and replay that profile later.
+
+```ts
+const trainer = createDiffEngine({ adaptive: true });
+const profile = trainer.train([[before, after]]);
+
+const profiled = createDiffEngine({ profile });
+const patch = profiled.diff(before, after);
+```
+
+### History Helpers
+
+The engine can plan patch histories, then delegate binary history encoding to `@shapeshift-labs/frontier-codec`.
+
+```ts
+const patches = engine.diffHistory(initial, states);
+const bytes = engine.encodeHistory(patches);
+const final = engine.applyEncodedHistory(initial, bytes);
+```
+
+### Profile Plan Helpers
+
+```ts
+const plans = createEngineProfilePlansSnapshot(undefined, {
+  schemaCount: 1,
+  adaptivePlan: false,
+  historyStrategy: 'auto'
+});
+
+const merged = mergeProfilePlans(plans, { codec: { history: 'binary' } });
+```
+
+## Subpath Imports
+
+```ts
+import { createDiffEngine } from '@shapeshift-labs/frontier-engine/engine';
+import { mergeProfilePlans } from '@shapeshift-labs/frontier-engine/profile';
+import type { DiffEngine } from '@shapeshift-labs/frontier-engine/types';
+```
+
+## Package Scope
 
-- `createDiffEngine()` and stateful planned diff execution;
-- adaptive shape learning and schema/profile planning;
-- reusable engine caches and failed-plan thresholds;
-- profile plan snapshots shared by state, history, codec, and CRDT layers;
-- engine-level history helpers that delegate byte formats to `frontier-codec`.
+This package owns:
 
-It should sit above `@shapeshift-labs/frontier` and use `@shapeshift-labs/frontier-codec` where patch-history serialization is needed. It should stay separate from state subscriptions, CRDT actors/updates, sync providers, logging, rich text, and storage-specific event logs.
+- `createDiffEngine()`.
+- Adaptive shape learning.
+- Explicit schema/profile diff planning.
+- Reusable engine caches.
+- Profile plan snapshots shared by state/history/codec/CRDT layers.
+- Engine-level history helpers that delegate byte formats to `frontier-codec`.
+
+It does not own:
 
-## Current Status
+- Stateless diff/apply primitives. Those stay in `@shapeshift-labs/frontier`.
+- Patch wire formats. Those stay in `@shapeshift-labs/frontier-codec`.
+- State subscriptions, routers, or maintained views. Those stay in Frontier state packages.
+- CRDT actors, updates, heads, branches, sync, awareness, rich text, or providers.
 
-Use [`@shapeshift-labs/frontier`](https://www.npmjs.com/package/@shapeshift-labs/frontier) for the stable JSON diff/apply core and [`@shapeshift-labs/frontier-codec`](https://www.npmjs.com/package/@shapeshift-labs/frontier-codec) for patch transport codecs.
+## Validation
 
-The engine package is reserved only. No runtime API is exported yet.
+```sh
+npm test
+npm run fuzz
+npm run bench
+npm run pack:dry
+```
 
-## Package Family
+The package test suite covers root and subpath imports, schema diff/apply replay, profile snapshots, history planning, encoded history replay, and the absence of state/CRDT exports. The fuzzer covers schema and adaptive profile round-trips over record-array and object-shaped JSON.
 
-Published or active packages:
+## Benchmarks
 
-- [`@shapeshift-labs/frontier`](https://www.npmjs.com/package/@shapeshift-labs/frontier)
-- [`@shapeshift-labs/frontier-codec`](https://www.npmjs.com/package/@shapeshift-labs/frontier-codec)
-- [`@shapeshift-labs/frontier-mutation`](https://www.npmjs.com/package/@shapeshift-labs/frontier-mutation)
+Run the package-local benchmark:
 
-Reserved future packages:
+```sh
+npm run bench
+```
 
-- `@shapeshift-labs/frontier-state`
-- `@shapeshift-labs/frontier-crdt`
-- `@shapeshift-labs/frontier-crdt-sync`
-- `@shapeshift-labs/frontier-richtext`
-- `@shapeshift-labs/frontier-logging`
-- `@shapeshift-labs/frontier-state-cache`
-- `@shapeshift-labs/frontier-event-log`
-- `@shapeshift-labs/frontier-schema`
+Latest local package-gate run on Node v26.1.0, darwin arm64, 3 rounds:
+
+| Fixture | Median | p95 |
+| --- | ---: | ---: |
+| Engine schema diff, 1k rows | 16.67 us | 17.45 us |
+| Engine apply via core patch | 0.58 us | 0.59 us |
+| Engine equality no-op | 9.32 us | 9.44 us |
+| Engine history encode/decode/apply | 3.97 us | 4.22 us |
+
+These are Frontier-only package measurements, not competitor comparisons.
 
 ## License
 

package/benchmarks/package-bench.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..');
+const args = parseArgs(process.argv.slice(2));
+const rounds = readPositiveInt(args.rounds, 9);
+const outPath = args.out ? path.resolve(rootDir, args.out) : null;
+let sink = 0;
+
+function measure(fn, inner) {
+  for (let i = 0; i < inner; i++) fn();
+  const samples = new Array(rounds);
+  for (let roundIndex = 0; roundIndex < rounds; roundIndex++) {
+    const start = performance.now();
+    for (let i = 0; i < inner; i++) fn();
+    samples[roundIndex] = ((performance.now() - start) * 1000) / inner;
+  }
+  samples.sort((left, right) => left - right);
+  return { median: percentile(samples, 0.5), p95: percentile(samples, 0.95) };
+}
+function runRow(name, inner, fn, extra = {}) {
+  const timing = measure(fn, inner);
+  return { fixture: name, medianUs: round(timing.median), p95Us: round(timing.p95), ...extra };
+}
+function printReport(report) {
+  console.log(report.package + ' package benchmark');
+  console.log('Node ' + report.node + ' on ' + report.platform + ', rounds=' + rounds);
+  console.log('These are Frontier-only package measurements, not competitor comparisons.');
+  console.log('');
+  console.log(padRight('Fixture', 44) + padLeft('Median', 12) + padLeft('p95', 11));
+  for (const row of report.rows) {
+    console.log(padRight(row.fixture, 44) + padLeft(formatUs(row.medianUs), 12) + padLeft(formatUs(row.p95Us), 11));
+  }
+  if (outPath) console.log('\nwrote ' + path.relative(rootDir, outPath));
+}
+function finish(packageName, rows) {
+  const report = { package: packageName, version: readPackageVersion(), generatedAt: new Date().toISOString(), node: process.version, platform: process.platform + ' ' + process.arch, rounds, rows };
+  if (outPath) { fs.mkdirSync(path.dirname(outPath), { recursive: true }); fs.writeFileSync(outPath, JSON.stringify(report, null, 2) + '\n'); }
+  printReport(report);
+  if (sink === 42) console.log('sink=' + sink);
+}
+function percentile(sorted, fraction) { return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1))]; }
+function readPackageVersion() { return JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')).version; }
+function parseArgs(argv) { const out = {}; for (let i = 0; i < argv.length; i++) { const arg = argv[i]; if (arg === '--rounds') out.rounds = argv[++i]; else if (arg === '--out') out.out = argv[++i]; else if (arg === '--help' || arg === '-h') { console.log('Usage: npm run bench -- [--rounds 9] [--out benchmarks/results/package-bench.json]'); process.exit(0); } else throw new Error('unknown argument: ' + arg); } return out; }
+function readPositiveInt(value, fallback) { if (value === undefined) return fallback; const number = Number(value); if (!Number.isInteger(number) || number <= 0) throw new Error('expected positive integer, got ' + value); return number; }
+function round(value) { return Math.round(value * 100) / 100; }
+function formatUs(value) { return value >= 1000 ? (value / 1000).toFixed(2) + ' ms' : value.toFixed(2) + ' us'; }
+function padRight(value, width) { return String(value).padEnd(width); }
+function padLeft(value, width) { return String(value).padStart(width); }
+
+import { applyPatchImmutable } from '@shapeshift-labs/frontier';
+import { createDiffEngine } from '../dist/index.js';
+
+const before = { rows: makeRows(1000), meta: { version: 1 } };
+const after = cloneJson(before);
+after.rows[512] = { ...after.rows[512], score: 9999 };
+after.meta.version = 2;
+const engine = createDiffEngine({ schema: { type: 'array', path: ['rows'], key: 'id', item: { type: 'object', fields: ['id', 'score', 'active', 'label'] } } });
+const patch = engine.diff(before, after);
+const rows = [
+  runRow('Engine schema diff, 1k rows', 300, () => { sink += engine.diff(before, after).length; }),
+  runRow('Engine apply via core patch', 3000, () => { sink += applyPatchImmutable(before, patch).rows.length; }),
+  runRow('Engine equality no-op', 3000, () => { if (engine.equals(before, before)) sink++; }),
+  runRow('Engine history encode/decode/apply', 1000, () => { const bytes = engine.encodeHistory([patch]); sink += engine.applyEncodedHistory(before, bytes).rows.length; })
+];
+finish('@shapeshift-labs/frontier-engine', rows);
+function makeRows(count) { const rows = new Array(count); for (let i = 0; i < count; i++) rows[i] = { id: 'row-' + i, score: i, active: (i & 1) === 0, label: 'row ' + i }; return rows; }
+function cloneJson(value) { return JSON.parse(JSON.stringify(value)); }

package/dist/engine.d.ts

@@ -0,0 +1,3 @@
+import type { DiffEngine, EngineOptions } from './types.js';
+export declare function createDiffEngine(defaultOptions?: EngineOptions): DiffEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,UAAU,EAGV,aAAa,EAcd,MAAM,YAAY,CAAC;AA8FpB,wBAAgB,gBAAgB,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,UAAU,CA0O3E"}