@ainize/core 0.1.0

package/dist/local-ledger.js

@@ -0,0 +1,229 @@
+/**
+ * LocalLedger — signed record DAG stored in SQLite (node:sqlite), replicated by set reconciliation.
+ *
+ * Record hash = sha256(canonicalJson({kind, body, author, ts, parents})); sig = ecSignMessage(hash).
+ * `parents` = hashes of the newest records known when the record was created (causal frontier), which
+ * gives a partial order without needing a single writer — suited to many independent peers.
+ *
+ * Import compatibility: blocks from the reference prototype's ledger.jsonl (linear HMAC chain written by
+ * Python) are re-hashed with `pythonJson` so their original `hash` values are preserved and the linear
+ * chain can still be verified.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createHmac } from 'node:crypto';
+import { canonicalJson, pythonJson, sha256Hex } from './canonical.js';
+import { signMessage, verifyMessage } from './identity.js';
+/** Secret used by the reference Python prototype for its HMAC "signature" mock. */
+const PROTOTYPE_SECRET = 'x402-demo-facilitator';
+const PROTOTYPE_AUTHOR = 'prototype:kimminhyun-ai';
+export function recordHash(kind, body, author, ts, parents) {
+    return sha256Hex(canonicalJson({ kind, body, author, ts, parents }));
+}
+/**
+ * A record this ledger will never accept, however often it is offered — a hash that does not match its body, a
+ * signature that is not its author's.
+ *
+ * The distinction matters to whoever is feeding records in: a refusal is final, so a sync may pass over it, while
+ * anything else (a busy database, a write that threw part-way) is this node's problem and the record must be
+ * offered again rather than skipped for ever.
+ */
+export class RecordRefused extends Error {
+    refused = true;
+    constructor(message) { super(message); this.name = 'RecordRefused'; }
+}
+/** Is this the ledger saying "never", rather than "not now"? */
+export function isRecordRefusal(e) {
+    return !!e && typeof e === 'object' && e.refused === true;
+}
+export class LocalLedger {
+    path;
+    identity;
+    events;
+    network;
+    kind = 'local';
+    db;
+    constructor(path, identity, events = {}, network = 'local') {
+        this.path = path;
+        this.identity = identity;
+        this.events = events;
+        this.network = network;
+    }
+    async init() {
+        if (this.path !== ':memory:')
+            mkdirSync(dirname(this.path), { recursive: true });
+        this.db = new DatabaseSync(this.path);
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS records (
+        seq     INTEGER PRIMARY KEY AUTOINCREMENT,
+        hash    TEXT NOT NULL UNIQUE,
+        kind    TEXT NOT NULL,
+        author  TEXT NOT NULL,
+        ts      REAL NOT NULL,
+        parents TEXT NOT NULL,
+        body    TEXT NOT NULL,
+        sig     TEXT NOT NULL,
+        legacy  INTEGER NOT NULL DEFAULT 0,
+        received_at REAL NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_records_kind ON records(kind);
+      CREATE INDEX IF NOT EXISTS idx_records_ts ON records(ts);
+      CREATE INDEX IF NOT EXISTS idx_records_recv ON records(received_at);
+    `);
+    }
+    async close() { this.db.close(); }
+    async info() {
+        const row = this.db.prepare('SELECT COUNT(*) AS n, MAX(seq) AS h FROM records').get();
+        const head = this.db.prepare('SELECT hash FROM records ORDER BY seq DESC LIMIT 1').get();
+        return { kind: 'local', network: this.network, records: row.n, height: row.h ?? 0, head: head?.hash };
+    }
+    frontier(limit = 4) {
+        const rows = this.db.prepare('SELECT hash FROM records ORDER BY seq DESC LIMIT ?').all(limit);
+        return rows.map((r) => r.hash);
+    }
+    async append(kind, body) {
+        const ts = Date.now();
+        const parents = this.frontier();
+        const hash = recordHash(kind, body, this.identity.address, ts, parents);
+        const sig = signMessage(hash, this.identity.privateKey);
+        const rec = { hash, kind, body, author: this.identity.address, ts, parents, sig };
+        this.insert(rec, false);
+        this.events.onRecord?.(rec);
+        return rec;
+    }
+    async ingest(record) {
+        if (this.has(record.hash))
+            return false;
+        if (!LocalLedger.validate(record))
+            throw new RecordRefused(`invalid record ${record.hash}`);
+        this.insert(record, record.author.startsWith('prototype:'));
+        this.events.onRecord?.(record);
+        return true;
+    }
+    static validate(record) {
+        if (record.author.startsWith('prototype:'))
+            return LocalLedger.validateLegacy(record);
+        const expect = recordHash(record.kind, record.body, record.author, record.ts, record.parents);
+        if (expect !== record.hash)
+            return false;
+        return verifyMessage(record.hash, record.sig, record.author);
+    }
+    /** Legacy prototype block: {i,t,kind,body,prev,hash,sig(HMAC)} mapped into a record. */
+    static validateLegacy(record) {
+        const legacy = record.body.__legacy;
+        if (!legacy)
+            return false;
+        const { __legacy, ...body } = record.body;
+        const raw = pythonJson({ i: legacy.i, t: legacy.t, kind: record.kind, body, prev: legacy.prev });
+        if (sha256Hex(raw) !== record.hash)
+            return false;
+        const sig = createHmac('sha256', PROTOTYPE_SECRET).update(record.hash).digest('hex');
+        return sig === record.sig;
+    }
+    has(hash) {
+        return !!this.db.prepare('SELECT 1 FROM records WHERE hash = ?').get(hash);
+    }
+    insert(rec, legacy) {
+        this.db.prepare('INSERT INTO records (hash, kind, author, ts, parents, body, sig, legacy, received_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)').run(rec.hash, rec.kind, rec.author, rec.ts, JSON.stringify(rec.parents), JSON.stringify(rec.body), rec.sig, legacy ? 1 : 0, Date.now());
+    }
+    rowToRecord(r) {
+        return {
+            hash: r.hash,
+            kind: r.kind,
+            author: r.author,
+            ts: r.ts,
+            parents: JSON.parse(r.parents),
+            body: JSON.parse(r.body),
+            sig: r.sig,
+        };
+    }
+    async list(opts = {}) {
+        const where = [];
+        const args = [];
+        if (opts.since !== undefined) {
+            where.push('received_at > ?');
+            args.push(opts.since);
+        }
+        if (opts.kind) {
+            where.push('kind = ?');
+            args.push(opts.kind);
+        }
+        const sql = `SELECT * FROM records ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY seq ASC ${opts.limit ? 'LIMIT ' + Number(opts.limit) : ''}`;
+        return this.db.prepare(sql).all(...args).map((r) => this.rowToRecord(r));
+    }
+    async get(hash) {
+        const r = this.db.prepare('SELECT * FROM records WHERE hash = ?').get(hash);
+        return r ? this.rowToRecord(r) : null;
+    }
+    /** Records received after `since` (peer-local receive clock) plus the cursor to continue from. */
+    async sync(since = 0, limit = 500) {
+        const rows = this.db.prepare('SELECT * FROM records WHERE received_at > ? ORDER BY received_at ASC, seq ASC LIMIT ?').all(since, limit);
+        const records = rows.map((r) => this.rowToRecord(r));
+        const cursor = rows.length ? rows[rows.length - 1].received_at : since;
+        return { records, cursor };
+    }
+    async hashes(since = 0) {
+        return this.db.prepare('SELECT hash FROM records WHERE received_at > ? ORDER BY seq').all(since).map((r) => r.hash);
+    }
+    async byKind(kind, filter) {
+        const recs = (await this.list({ kind }));
+        return filter ? recs.filter((r) => filter(r.body)) : recs;
+    }
+    anchors() { return this.byKind('anchor'); }
+    attestations(patchId) { return this.byKind('attest', patchId ? (b) => b.patch_id === patchId : undefined); }
+    settlements(patchId) { return this.byKind('settle', patchId ? (b) => b.patch_id === patchId : undefined); }
+    challenges(patchId) { return this.byKind('challenge', patchId ? (b) => b.patch_id === patchId : undefined); }
+    disputes(patchId) { return this.byKind('dispute', patchId ? (b) => b.patch_id === patchId : undefined); }
+    branches() { return this.byKind('branch'); }
+    nodes() { return this.byKind('node'); }
+    supersedes() { return this.byKind('supersede'); }
+    subscriptions() { return this.byKind('subscribe'); }
+    async verify() {
+        const errors = [];
+        const all = await this.list();
+        // legacy linear chain check
+        let prev = '0'.repeat(64);
+        for (const r of all) {
+            if (!LocalLedger.validate(r))
+                errors.push(`bad hash/sig: ${r.hash}`);
+            const legacy = r.body.__legacy;
+            if (legacy) {
+                if (legacy.prev !== prev)
+                    errors.push(`legacy chain broken at ${r.hash}`);
+                prev = r.hash;
+            }
+        }
+        return { valid: errors.length === 0, checked: all.length, errors };
+    }
+    /**
+     * Import the reference prototype's ledger.jsonl (Python HMAC chain). Blocks become records whose
+     * `hash` is the original block hash; their Python-shaped bodies are normalised onto our schema by the
+     * caller (see node/seed.ts) — here we only preserve them verbatim so `verify()` can re-check the chain.
+     */
+    async importPrototypeLedger(file) {
+        if (!existsSync(file))
+            return 0;
+        let n = 0;
+        for (const line of readFileSync(file, 'utf8').split('\n')) {
+            if (!line.trim())
+                continue;
+            const blk = JSON.parse(line);
+            const kind = (blk.kind === 'settle' || blk.kind === 'attest' || blk.kind === 'anchor') ? blk.kind : 'anchor';
+            const rec = {
+                hash: blk.hash,
+                kind,
+                body: { ...blk.body, __legacy: { i: blk.i, t: blk.t, prev: blk.prev } },
+                author: PROTOTYPE_AUTHOR,
+                ts: Math.round(blk.t * 1000),
+                parents: blk.prev === '0'.repeat(64) ? [] : [blk.prev],
+                sig: blk.sig,
+            };
+            if (await this.ingest(rec))
+                n++;
+        }
+        return n;
+    }
+}
+//# sourceMappingURL=local-ledger.js.map

package/dist/local-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-ledger.js","sourceRoot":"","sources":["../src/local-ledger.ts"],"names":[],"mappings":"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"}

package/dist/npz.d.ts

@@ -0,0 +1,107 @@
+export interface NpyHeader {
+    descr: string;
+    fortranOrder: boolean;
+    shape: number[];
+    dataOffset: number;
+}
+export declare function parseNpyHeader(buf: Buffer): NpyHeader;
+export interface NpzInfo {
+    members: {
+        name: string;
+        descr: string;
+        shape: number[];
+        bytes: number;
+    }[];
+    rows: number;
+    rowDim: number;
+}
+/** Inspect an .npz without loading array bodies (except headers). */
+export declare function inspectNpz(path: string): NpzInfo;
+/** Load the int64 address array as BigInt64Array (copy). */
+export declare function readNpzAddrs(path: string): BigInt64Array;
+/** Sorted, de-duplicated address set. */
+export declare function addressSet(addrs: BigInt64Array): BigInt64Array;
+/** |A ∩ B| for two sorted address sets (도 6 conflict test). */
+export declare function intersectionCount(a: BigInt64Array, b: BigInt64Array): number;
+/** Bottom-k MinHash-style sketch of an address set for cheap remote pre-checks. */
+export declare function addressSketch(addrs: BigInt64Array, k?: number): number[];
+/** Estimated Jaccard similarity from two bottom-k sketches. */
+export declare function sketchJaccard(a: number[], b: number[]): number;
+/** Read one array member of an .npz (header + raw little-endian body). Used by the teach stub to copy fixture rows. */
+export declare function readNpzMember(path: string, name: string): {
+    header: NpyHeader;
+    body: Buffer;
+};
+export interface NpzMemberSpec {
+    name: string;
+    descr: string;
+    shape: number[];
+    body: Buffer;
+}
+/**
+ * Write a minimal .npz (ZIP_STORED members, npy v1) — enough for `inspectNpz` / `readNpzAddrs` / numpy.load.
+ * Only the teach stub backend uses it (a valid 1-row knowledge file when no fixture is available).
+ */
+export declare function writeNpz(path: string, members: NpzMemberSpec[]): void;
+/**
+ * Row-level agreement between two knowledge files (§9 step 2, and the evidence behind "these two really do
+ * disagree"): over the addresses both files touch, how many hold bf16-identical `after` values.
+ *
+ * bf16 is the comparison unit because that is what the table stores (patch_hook.py:98) — two files whose float32
+ * `after` differ in the dropped 16 bits are the same row as far as the model is concerned.
+ */
+export declare function valuesEqualCount(pathA: string, pathB: string): {
+    shared: number;
+    equal: number;
+    differ: number;
+    dim: number;
+};
+/**
+ * Row-level report for a MERGE of two knowledge files (design §9 step 2). Where `valuesEqualCount` answers "do these
+ * two disagree", this answers the four numbers SC-14 puts on the screen — `{ra} only in A · {rb} only in B · {shared}
+ * written by both ({dis} disagree)` — plus the two facts that decide whether a merge can be done without training:
+ *
+ *  - `disagree`: shared addresses whose `after` differs in bf16 (the unit the table stores).
+ *  - `opposing`: shared addresses where BOTH files moved the row away from their own `before` and landed on different
+ *    values. A disagreement where only one file wrote the row is a stacking order question; an opposing one cannot be
+ *    resolved by order at all, and is the honest count behind "these two really cannot just be combined".
+ *  - `before_differs`: shared addresses whose `before` differs — the two files disagree about what was underneath
+ *    them, so a stand-alone union of them has no single value to write as `before` (a delta over a stack, merged with
+ *    a file built on the bare model, is the usual cause).
+ */
+export interface NpzCompare {
+    a_rows: number;
+    b_rows: number;
+    a_only: number;
+    b_only: number;
+    shared: number;
+    equal: number;
+    disagree: number;
+    opposing: number;
+    before_differs: number;
+    dim: number;
+}
+export declare function compareNpz(pathA: string, pathB: string): NpzCompare;
+/** Why a union of two files cannot be written (design §9 T0). */
+export type UnionRefusal = 'rows_disagree' | 'before_differs' | 'dim_mismatch';
+export interface UnionResult {
+    rows: number;
+    a_rows: number;
+    b_rows: number;
+    shared: number;
+    pre_state_sha256: string;
+    dim: number;
+}
+/**
+ * **T0 “Just combine”** (design §9 step 3): the row UNION of two knowledge files, written as a new .npz — no training,
+ * no GPU, seconds.
+ *
+ * It is allowed only when the two files cannot contradict each other on the model: either their address sets are
+ * disjoint, or every shared address holds a bf16-identical `after` AND a bf16-identical `before`. Anything else throws
+ * — **nothing is averaged and nothing is added** (design §9 “Forbidden”, F8): a row two files disagree about has to be
+ * retrained (T1) or rebuilt (T2), because a value neither file measured is not knowledge.
+ *
+ * `extra` members (a job marker, `meta`) are written beside `addrs`/`before`/`after` exactly as given.
+ */
+export declare function unionNpz(dest: string, pathA: string, pathB: string, extra?: NpzMemberSpec[]): UnionResult;
+//# sourceMappingURL=npz.d.ts.map

package/dist/npz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npz.d.ts","sourceRoot":"","sources":["../src/npz.ts"],"names":[],"mappings":"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"}