@lapxo/bound 0.1.0

package/dist/land/ledger.js

@@ -0,0 +1,148 @@
+import { appendFileSync, closeSync, dirname, existsSync, join, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "../host/io.js";
+import { storeRoot } from "../host/ports/store.js";
+import { canonical, EXTENSION, PROTOCOL } from '@lapxo/topos/wire';
+import { fieldOf } from "../fold/claims.js";
+import { observeText } from "../observe/files.js";
+export function storeOf(root) {
+    return join(storeRoot(root), EXTENSION);
+}
+/**
+ * The store of a place: every name under it is read here and nowhere else, whoever needs a place asks for it by its
+ * steps, and one append-only file per writer stands beside the bytes kept by digest — one per region for a writer
+ * whose lines are about regions, so a fold opens only the regions it reaches. A file is read once per stamp, and a
+ * ledger only grows: what it held is kept, and only the bytes appended since, from where it last ended a line, are read.
+ */
+export function storeAt(store, ...steps) {
+    return join(store, ...steps);
+}
+export function writerFile(store, writer) {
+    return storeAt(store, 'ledger', `${writer.replace(/[^a-zA-Z0-9_-]/g, '')}${EXTENSION}`);
+}
+const held = new Map();
+export function ledgerLines(store, writer) {
+    return linesAt(writerFile(store, writer));
+}
+export function shardFile(store, writer, region) {
+    return storeAt(store, 'ledger', writer.replace(/[^a-zA-Z0-9_-]/g, ''), `${region.replace(/\/+$/, '') || '@'}${EXTENSION}`);
+}
+export const shardLines = (store, writer, region) => linesAt(shardFile(store, writer, region));
+export function landShard(store, writer, region, lines) {
+    return appendNew(shardFile(store, writer, region), lines);
+}
+function linesAt(at) {
+    const st = statSync(at, { throwIfNoEntry: false });
+    if (!st)
+        return [];
+    const stamp = `${Math.floor(st.mtimeMs)}-${st.size}`;
+    const mine = held.get(at);
+    if (mine?.stamp === stamp)
+        return mine.lines;
+    const grown = mine !== undefined && mine.size > 0 && st.size > mine.size ? tailOf(at, mine.size, st.size) : undefined;
+    const lines = grown !== undefined && mine !== undefined ? [...mine.lines, ...grown.split('\n').filter((line) => line.startsWith(PROTOCOL))] : readFileSync(at, 'utf8').split('\n').filter((line) => line.startsWith(PROTOCOL));
+    held.set(at, { stamp, size: st.size, lines });
+    return lines;
+}
+function tailOf(at, from, to) {
+    const fd = openSync(at, 'r');
+    try {
+        const bytes = Buffer.alloc(to - from + 1);
+        readSync(fd, bytes, 0, bytes.length, from - 1);
+        return bytes[0] === 0x0a ? bytes.subarray(1).toString('utf8') : undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function appendNew(at, lines) {
+    const had = new Set(linesAt(at));
+    const fresh = [...new Set(lines)].filter((line) => line.startsWith(PROTOCOL) && !had.has(line));
+    if (fresh.length) {
+        mkdirSync(dirname(at), { recursive: true });
+        appendFileSync(at, `${fresh.join('\n')}\n`);
+    }
+    return fresh.length;
+}
+export function signedLines(store, writer) {
+    return ledgerLines(store, writer).filter((line) => line.includes(`by=${writer}`) && /\bsig=/.test(line));
+}
+export function blobAt(store, digest) {
+    return storeAt(store, 'cas', 'blobs', digest.slice(digest.indexOf(':') + 1));
+}
+/**
+ * Where the bytes of one digest are kept: naming a blob is not reading it. A file named by the digest of its bytes lands
+ * whole, once, whoever lands it: every writer writes the same bytes, so a
+ * rename over one already there changes nothing, and a reader never meets half of it.
+ */
+function landWhole(at, bytes) {
+    if (existsSync(at))
+        return at;
+    replaceWhole(at, bytes);
+    return at;
+}
+/** A file replaced whole: the bytes land in a temp beside it and the name moves in one rename, so a killed write keeps the temp, never a torn file under the name a later read parses. */
+export function replaceWhole(at, bytes) {
+    mkdirSync(dirname(at), { recursive: true });
+    const part = `${at}.${process.pid}.part`;
+    writeFileSync(part, bytes);
+    renameSync(part, at);
+}
+export const landBlob = (store, digest, bytes) => {
+    const at = landWhole(blobAt(store, digest), bytes);
+    holdStore(store, 'blobs', digest, bytes.byteLength);
+    return at;
+};
+export function holdStore(store, kind, name, bytes) {
+    const hex = name.replace(/^[^:]*:/, '');
+    const scope = `cas/${kind}/${hex}`;
+    const held = ledgerLines(store, 'store').filter((line) => fieldOf(line, 'scope') === scope);
+    if (held.length && fieldOf(held[held.length - 1], 'value') !== 'withdraw')
+        return;
+    land(store, 'store', [canonical({
+            scope, role: 'writes', form: 'interval', measure: 'bytes',
+            value: `${bytes}..${bytes}`, at: `place:${kind === 'answers' ? hex : `sha256:${hex}`}`, by: 'store',
+        })]);
+}
+export const memoAt = (store, key) => storeAt(store, 'cas', 'memo', ...key.split('/').map((step) => step.replace(/[^a-zA-Z0-9._@-]/g, '_')));
+export function landMemo(store, key, bytes) {
+    const at = memoAt(store, key);
+    if (existsSync(at))
+        return at;
+    mkdirSync(dirname(at), { recursive: true });
+    const part = `${at}.${process.pid}.part`;
+    writeFileSync(part, bytes);
+    try {
+        linkSync(part, at);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    finally {
+        rmSync(part, { force: true });
+    }
+    return at;
+}
+export const landEnvelope = (store, digest, bytes) => landWhole(storeAt(store, 'cas', 'envelopes', `${digest.slice(digest.indexOf(':') + 1)}.json`), bytes);
+export function land(store, writer, lines) {
+    const at = writerFile(store, writer);
+    return { at, appended: appendNew(at, lines) };
+}
+const step = (value) => value.replace(/[^a-zA-Z0-9._@-]/g, '_');
+function verdictAt(store, tree, lot) {
+    return memoAt(store, `verdict/${step(tree)}/${step(lot)}`);
+}
+export function keptVerdict(store, tree, lot) {
+    const text = observeText(verdictAt(store, tree, lot));
+    if (text === undefined)
+        return undefined;
+    try {
+        const got = JSON.parse(text);
+        return Array.isArray(got) ? got : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function keepVerdict(store, tree, lot, judged) {
+    landMemo(store, `verdict/${step(tree)}/${step(lot)}`, new TextEncoder().encode(JSON.stringify(judged)));
+}

package/dist/land/owned.d.ts

@@ -0,0 +1,23 @@
+export type Owned = {
+    readonly ledger: readonly string[];
+    readonly own: ReadonlyMap<string, readonly string[]>;
+    readonly nowhere: readonly string[];
+    readonly forked: readonly {
+        readonly place: string;
+        readonly key: string;
+    }[];
+};
+/**
+ * A lot named with --place lands in those own locks and not the ledger: a lot never mixes. A line the ledger does not admit is a place's own when that place's own lock admits it: signed by a key the tree admits,
+ * inside the window it held, inside its coverage of the place, the line's scope read as a region of the place. An own
+ * lock speaks of its place without naming it, so a line whose scope names a place first is the ledger's alone, and the
+ * same line can stand in many own locks: named places take every line they admit, and with none named a line lands in
+ * the one own lock that admits it. The lines are told to their locks for the gates and land in them signed, beside what
+ * the ledger takes. A line no lock admits, or one two locks would take and no place names, is admitted nowhere, and a
+ * batch that holds one is refused whole: nothing is ever written into a lock bare. An own lot never forks a lock: lines
+ * that would leave a place's lock with two standing claims where it had one are refused whole, so a lot for many places
+ * lands the same lines at each, and lines meant for one place go in a lot of their own.
+ */
+export declare function ownedOf(root: string, signed: readonly string[], admits: (line: string) => boolean, coverage: (by: string) => readonly string[], named?: readonly string[], placedAt?: (line: string) => readonly string[] | undefined): Owned;
+/** A place's own lock gains the lines a batch landed there, appended whole: a reader never meets half of it, and every line already there keeps its bytes as they were. */
+export declare function landOwned(root: string, place: string, lines: readonly string[]): void;

package/dist/land/owned.js

@@ -0,0 +1,65 @@
+import { join, renameSync, writeFileSync } from "../host/io.js";
+import { fieldOf, LOCK } from "../fold/claims.js";
+import { lockStanding } from "../fold/keys.js";
+import { placesIn } from "../fold/places.js";
+import { admittedIn, forksIn, tellOwn } from "../fold/signed.js";
+import { wordOf } from "../fold/wire.js";
+import { observeText } from "../observe/files.js";
+import { landShard, storeOf } from "./ledger.js";
+/**
+ * A lot named with --place lands in those own locks and not the ledger: a lot never mixes. A line the ledger does not admit is a place's own when that place's own lock admits it: signed by a key the tree admits,
+ * inside the window it held, inside its coverage of the place, the line's scope read as a region of the place. An own
+ * lock speaks of its place without naming it, so a line whose scope names a place first is the ledger's alone, and the
+ * same line can stand in many own locks: named places take every line they admit, and with none named a line lands in
+ * the one own lock that admits it. The lines are told to their locks for the gates and land in them signed, beside what
+ * the ledger takes. A line no lock admits, or one two locks would take and no place names, is admitted nowhere, and a
+ * batch that holds one is refused whole: nothing is ever written into a lock bare. An own lot never forks a lock: lines
+ * that would leave a place's lock with two standing claims where it had one are refused whole, so a lot for many places
+ * lands the same lines at each, and lines meant for one place go in a lot of their own.
+ */
+export function ownedOf(root, signed, admits, coverage, named = [], placedAt = () => undefined) {
+    const places = placesIn(root);
+    const headed = (line) => places.includes(fieldOf(line, 'scope').split('/')[0] ?? '');
+    const ledger = named.length ? [] : signed.filter(admits);
+    const rest = [...new Set(signed.filter((line) => (named.length || !admits(line)) && !headed(line)))];
+    const placed = signed.filter((line) => !ledger.includes(line) && !rest.includes(line));
+    if (!rest.length)
+        return { ledger, own: new Map(), nowhere: placed, forked: [] };
+    const family = wordOf(lockStanding(storeOf(root)), 'families', 'region');
+    const covers = new Set(rest.map((line) => fieldOf(line, 'by')).flatMap((by) => coverage(by)));
+    const namedOf = (line) => placedAt(line) ?? named;
+    const asked = [...new Set(rest.flatMap((line) => (namedOf(line).length ? namedOf(line) : places)))].filter((place) => [...covers].some((prefix) => prefix === '*' || prefix.startsWith(`${family}/${place}/`) || prefix === `${family}/${place}`));
+    const takers = new Map();
+    for (const place of asked) {
+        tellOwn(place, rest);
+        for (const line of rest)
+            if ((!namedOf(line).length || namedOf(line).includes(place)) && admittedIn(root, place, line))
+                takers.set(line, [...(takers.get(line) ?? []), place]);
+        tellOwn(place, []);
+    }
+    const lands = (line) => (namedOf(line).length ? (takers.get(line)?.length ?? 0) > 0 : takers.get(line)?.length === 1);
+    const own = new Map();
+    for (const line of rest.filter(lands))
+        for (const place of takers.get(line))
+            own.set(place, [...(own.get(place) ?? []), line]);
+    const forked = [...own].flatMap(([place, lines]) => {
+        tellOwn(place, []);
+        const before = new Set(forksIn(root, place));
+        tellOwn(place, lines);
+        return forksIn(root, place).filter((key) => !before.has(key)).map((key) => ({ place, key }));
+    });
+    return { ledger, own, nowhere: [...placed, ...rest.filter((line) => !lands(line))], forked };
+}
+/** A place's own lock gains the lines a batch landed there, appended whole: a reader never meets half of it, and every line already there keeps its bytes as they were. */
+export function landOwned(root, place, lines) {
+    if (!lines.length)
+        return tellOwn(place, []);
+    const at = join(root, place, LOCK);
+    const text = observeText(at) ?? '';
+    for (const by of new Set(lines.map(line => fieldOf(line, 'by')))) {
+        landShard(storeOf(root), by, `${place}/${LOCK}`, lines.filter(line => fieldOf(line, 'by') === by));
+    }
+    writeFileSync(`${at}.${process.pid}.landing`, `${text.replace(/\n*$/, '\n')}${lines.join('\n')}\n`);
+    renameSync(`${at}.${process.pid}.landing`, at);
+    tellOwn(place, []);
+}

package/dist/land/sign.d.ts

@@ -0,0 +1,16 @@
+type Signed = {
+    readonly kind: 'fact';
+    readonly line: string;
+} | {
+    readonly kind: 'refuse';
+    readonly why: string;
+};
+/** A consent line (by=target, no sig) becomes the owner's claim: stamped with its epoch, then signed over the canonical bytes. */
+export declare function signConsentLine(line: string, privateKeyPem: string, stamp: {
+    readonly epoch?: number;
+    readonly by: string;
+    readonly algorithm: string;
+}): Signed;
+export declare function verifiesOwnerLine(line: string, publicKeyPem: string, admitted: readonly string[]): boolean;
+export declare function verifiesFields(fields: Readonly<Record<string, string>>, publicKey: string, admitted: readonly string[]): boolean;
+export {};

package/dist/land/sign.js

@@ -0,0 +1,30 @@
+import { canonical, parse, parseForSigning, signedBytes, signedFieldsOf } from '@lapxo/topos/wire';
+import { signBytes, verifyBytes } from "../host/adapters/keys/ed25519.js";
+/** A consent line (by=target, no sig) becomes the owner's claim: stamped with its epoch, then signed over the canonical bytes. */
+export function signConsentLine(line, privateKeyPem, stamp) {
+    const got = parseForSigning(line);
+    if (got.kind !== 'fact')
+        return { kind: 'refuse', why: `REFUSE·accept not a claim line: ${got.why}` };
+    const fields = got.value.fields;
+    const scope = fields['scope'] ?? '?';
+    if (fields['sig'] !== undefined)
+        return { kind: 'refuse', why: `REFUSE·accept ${scope} is already signed` };
+    if (fields['by'] !== 'target') {
+        return { kind: 'refuse', why: `REFUSE·accept ${scope} is by=${fields['by'] ?? '∅'}; only by=target lines are signed` };
+    }
+    const covered = signedFieldsOf(fields, stamp.by);
+    if (stamp.epoch !== undefined)
+        covered['epoch'] = String(stamp.epoch);
+    return { kind: 'fact', line: canonical({ ...covered, sig: signBytes(signedBytes(covered), privateKeyPem, stamp.algorithm) }) };
+}
+export function verifiesOwnerLine(line, publicKeyPem, admitted) {
+    const got = parse(line);
+    if (got.kind !== 'fact')
+        return false;
+    const { sig, ...rest } = got.value.fields;
+    return typeof sig === 'string' && verifyBytes(signedBytes(rest), publicKeyPem, sig, admitted);
+}
+export function verifiesFields(fields, publicKey, admitted) {
+    const { sig, ...rest } = fields;
+    return typeof sig === 'string' && verifyBytes(signedBytes(rest), publicKey, sig, admitted);
+}

package/dist/land/vouched.d.ts

@@ -0,0 +1,21 @@
+import type { CoordinateRole } from '../fold/wire.ts';
+/** A location is a file or a directory; `x/*` names the directory `x/`. A deeper glob is not a location. */
+export declare function locationsOf(needs: string): {
+    readonly locations: readonly string[];
+    readonly refused: readonly string[];
+};
+/**
+ * The source coordinates under one location, by digest. A path whose role is not source is never walked, so nothing under
+ * it is read. A link is a coordinate whose bytes are its target; it is never followed.
+ */
+export declare function coordinatesOf(root: string, location: string, roleOf: (coordinate: string) => CoordinateRole): Map<string, string>;
+/** The law a witness file says it answers for: its own `witness=<law>` line, or its `"witness"` field. */
+export declare function witnessOf(root: string, coordinate: string): string | undefined;
+export declare const vouching: (standing: readonly string[]) => string;
+export declare const sourced: (standing: readonly string[]) => string;
+export declare const sourceOf: (line: string) => string | undefined;
+export declare function inside(path: string, location: string): boolean;
+export declare function vouchedCoordinates(store: string): Map<string, string>;
+export declare function everLanded(store: string): ReadonlySet<string>;
+export declare function hasVouchedTree(store: string): boolean;
+export declare function landCoordinates(store: string, present: ReadonlyMap<string, string>, gone: readonly string[], at: string): number;

package/dist/land/vouched.js

@@ -0,0 +1,112 @@
+import { createHash, join } from "../host/io.js";
+import { said, wordOf, wordsOf } from "../fold/wire.js";
+import { fieldOf } from "../fold/claims.js";
+import { point, region, within } from '@lapxo/obligations/field';
+import { canonical } from '@lapxo/topos/wire';
+import { land, ledgerLines } from "./ledger.js";
+import { lockStanding } from "../fold/keys.js";
+import { ownLock } from "../observe/runner.js";
+import { entriesIn, linkOf, observeFile, observeText, stampOf } from "../observe/files.js";
+/** A location is a file or a directory; `x/*` names the directory `x/`. A deeper glob is not a location. */
+export function locationsOf(needs) {
+    const locations = [];
+    const refused = [];
+    for (const raw of needs.split('|').map((n) => n.trim()).filter(Boolean)) {
+        const steps = raw.split('/').filter(Boolean);
+        while (steps[steps.length - 1] === '*' || steps[steps.length - 1] === '**')
+            steps.pop();
+        if (!steps.length || raw.includes('#') || steps.some((step) => step.includes('*'))) {
+            refused.push(raw);
+            continue;
+        }
+        locations.push(steps.join('/'));
+    }
+    return { locations, refused };
+}
+function digestOf(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+/**
+ * The source coordinates under one location, by digest. A path whose role is not source is never walked, so nothing under
+ * it is read. A link is a coordinate whose bytes are its target; it is never followed.
+ */
+export function coordinatesOf(root, location, roleOf) {
+    const out = new Map();
+    const visit = (rel) => {
+        if (roleOf(rel) !== 'source')
+            return;
+        const abs = join(root, rel);
+        const st = stampOf(abs);
+        if (!st)
+            return;
+        if (st.kind === 'link') {
+            out.set(rel, digestOf(`link:${linkOf(abs)}`));
+            return;
+        }
+        if (st.kind === 'dir') {
+            for (const name of entriesIn(abs).map((entry) => entry.name).sort())
+                visit(join(rel, name));
+            return;
+        }
+        if (st.kind === 'file')
+            out.set(rel, digestOf(Buffer.from(observeFile(abs) ?? new Uint8Array())));
+    };
+    visit(location.replace(/\/$/, ''));
+    return out;
+}
+/** The law a witness file says it answers for: its own `witness=<law>` line, or its `"witness"` field. */
+export function witnessOf(root, coordinate) {
+    if (stampOf(join(root, coordinate))?.kind !== 'file')
+        return undefined;
+    const text = observeText(join(root, coordinate)) ?? '';
+    return /^witness=([^\s]+)/m.exec(text)?.[1] ?? /"witness"\s*:\s*"([^"]+)"/.exec(text)?.[1];
+}
+function storeFamily(standing, coordinate) {
+    const names = said(ownLock(), coordinate);
+    if (!names.length)
+        throw new Error(`REFUSE·instrument ${coordinate} has no admitted declaration in the instrument lock`);
+    return wordsOf(standing, 'families').length ? wordOf(standing, 'families', names) : names[0];
+}
+export const vouching = (standing) => storeFamily(standing, 'store/vouches');
+export const sourced = (standing) => storeFamily(standing, 'store/source');
+export const sourceOf = (line) => (fieldOf(line, 'measure') === 'digest' && fieldOf(line, 'scope').includes('/') ? fieldOf(line, 'scope').slice(fieldOf(line, 'scope').indexOf('/') + 1) : undefined);
+export function inside(path, location) {
+    return within(point(path), region(location));
+}
+export function vouchedCoordinates(store) {
+    const out = new Map();
+    const standing = lockStanding(store);
+    if (!wordsOf(standing, 'states').length)
+        return out;
+    const absent = wordOf(standing, 'states', 'absent');
+    for (const line of ledgerLines(store, vouching(standing))) {
+        const path = sourceOf(line);
+        const value = fieldOf(line, 'value');
+        if (!path || !value)
+            continue;
+        if (value === absent)
+            out.delete(path);
+        else
+            out.set(path, value);
+    }
+    return out;
+}
+export function everLanded(store) {
+    const out = new Set();
+    for (const line of ledgerLines(store, vouching(lockStanding(store)))) {
+        const path = sourceOf(line);
+        if (path)
+            out.add(path);
+    }
+    return out;
+}
+export function hasVouchedTree(store) {
+    return ledgerLines(store, vouching(lockStanding(store))).length > 0;
+}
+export function landCoordinates(store, present, gone, at) {
+    const standing = lockStanding(store);
+    const line = (path, value) => canonical({
+        scope: `${sourced(standing)}/${path}`, role: 'writes', form: 'alphabet', measure: 'digest', value, by: 'land', at,
+    });
+    return land(store, vouching(standing), [...[...present].map(([path, value]) => line(path, value)), ...gone.map((path) => line(path, wordOf(standing, 'states', 'absent')))]).appended;
+}

package/dist/land/withdraw.d.ts

@@ -0,0 +1,14 @@
+interface Withdrawal {
+    /** The held lines the withdrawals take. */
+    readonly taken: readonly string[];
+    /** Taken lines whose scale is distributive: withdrawing them loses nothing and keeps nothing. */
+    readonly exact: readonly string[];
+    readonly inexact: readonly string[];
+    readonly open: readonly string[];
+}
+export declare function retractedTogether(signed: readonly string[]): readonly {
+    readonly withdraw: string;
+    readonly line: string;
+}[];
+export declare function withdrawal(withdraws: readonly string[], held: readonly string[]): Withdrawal;
+export {};

package/dist/land/withdraw.js

@@ -0,0 +1,24 @@
+import { ENVELOPE } from '@lapxo/topos/wire';
+import { fieldsOf } from "../fold/claims.js";
+import { declaredConfig as declared } from '@lapxo/topos/forms';
+/** A withdrawal takes every held line that states each field it states, its value and envelope aside. The signer's name is the envelope: a key whose coverage holds the scope takes a standing line of it, whoever signed that line. */
+function takes(withdraw, line) {
+    const w = fieldsOf(withdraw);
+    const f = fieldsOf(line);
+    return Object.keys(w).filter((k) => !ENVELOPE.has(k) && k !== 'value').every((k) => f[k] === w[k]);
+}
+export function retractedTogether(signed) {
+    const withdraws = signed.filter((line) => fieldsOf(line)['value'] === 'withdraw');
+    const claims = signed.filter((line) => fieldsOf(line)['value'] !== 'withdraw');
+    return withdraws.flatMap((withdraw) => claims.filter((line) => takes(withdraw, line)).map((line) => ({ withdraw, line })));
+}
+export function withdrawal(withdraws, held) {
+    const taken = held.filter((line) => fieldsOf(line)['value'] !== 'withdraw' && withdraws.some((w) => takes(w, line)));
+    const scaled = taken.map((line) => ({ line, got: declared(line) }));
+    return {
+        taken,
+        exact: scaled.filter((x) => x.got.distributive === true).map((x) => x.line),
+        inexact: scaled.filter((x) => x.got.distributive === false).map((x) => x.line),
+        open: scaled.filter((x) => x.got.distributive === null).map((x) => x.line),
+    };
+}

package/dist/observe/files.d.ts

@@ -0,0 +1,14 @@
+export declare const observeFile: (at: string) => Uint8Array | undefined;
+export declare const observeText: (at: string) => string | undefined;
+export declare const exists: (at: string) => boolean;
+export type Kind = 'file' | 'dir' | 'link' | 'other';
+export declare function stampOf(at: string): {
+    readonly kind: Kind;
+    readonly stamp: string;
+} | undefined;
+export declare const linkOf: (at: string) => string;
+export declare function entriesIn(at: string): readonly {
+    readonly name: string;
+    readonly dir: boolean;
+}[];
+export declare function coordinatesUnder(dir: string, root: string, into?: (step: string) => boolean): string[];

package/dist/observe/files.js

@@ -0,0 +1,68 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/**
+ * The one place the instrument reads the world: a coordinate's bytes, the entries of a directory, the coordinates under a place,
+ * a link's target and a coordinate's stamp. Every fold, render and landing asks here, so each reading is made once and named.
+ */
+const seen = new Map();
+/** A coordinate read once is kept by its stamp — its inode, size and time — and read again only when the stamp moves. */
+function bytesAt(at) {
+    const st = stampable(at);
+    if (st === undefined || st.isDirectory() || !existsSync(at))
+        return undefined;
+    const stamp = `${st.ino}-${st.size}-${st.mtimeMs}`;
+    const held = seen.get(at);
+    if (held?.stamp === stamp)
+        return held.bytes;
+    const bytes = readFileSync(at);
+    seen.set(at, { stamp, bytes });
+    return bytes;
+}
+export const observeFile = (at) => ((bytes) => (bytes === undefined ? undefined : new Uint8Array(bytes)))(bytesAt(at));
+export const observeText = (at) => bytesAt(at)?.toString('utf8');
+export const exists = (at) => existsSync(at);
+export function stampOf(at) {
+    const st = stampable(at);
+    if (!st)
+        return undefined;
+    const kind = st.isSymbolicLink() ? 'link' : st.isDirectory() ? 'dir' : st.isFile() ? 'file' : 'other';
+    return { kind, stamp: `${Math.floor(st.mtimeMs)}-${st.size}` };
+}
+/** A coordinate listed a moment ago can be gone before it is read: a landing renames its file into place. Gone is none. */
+function stampable(at) {
+    try {
+        return lstatSync(at);
+    }
+    catch {
+        return undefined;
+    }
+}
+export const linkOf = (at) => readlinkSync(at);
+export function entriesIn(at) {
+    if (!stampable(at)?.isDirectory())
+        return [];
+    return readdirSync(at, { withFileTypes: true }).map((entry) => ({ name: entry.name, dir: entry.isDirectory() }));
+}
+export function coordinatesUnder(dir, root, into = () => true) {
+    const out = [];
+    const name = (at) => relative(root, at).split(sep).join('/');
+    const walk = (at, kind) => {
+        if (kind === 'link')
+            return;
+        if (kind === 'file') {
+            out.push(name(at));
+            return;
+        }
+        if (kind !== 'dir' || !into(name(at)))
+            return;
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const here = join(at, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            walk(here, entry.isFile() ? 'file' : entry.isDirectory() ? 'dir' : 'other');
+        }
+    };
+    const st = stampable(dir);
+    walk(dir, !st ? 'other' : st.isSymbolicLink() ? 'link' : st.isDirectory() ? 'dir' : st.isFile() ? 'file' : 'other');
+    return out;
+}

package/dist/observe/identity.d.ts

@@ -0,0 +1,19 @@
+import type { Kind } from './run.ts';
+/** Where a reader's vectors lie: in its package, beside its source, under the name of its module, the folder the wire's vector family names. */
+export declare const vectorsOf: (module: string, standing: readonly string[]) => string;
+export declare const withoutVectors: (root: string, modules: readonly string[], standing: readonly string[]) => number;
+export declare function resetsOnEqualEmits(lines: readonly string[]): number;
+/** The executable keys the reader; its vector results describe only the cases measured. */
+export declare function identityOf(input: {
+    readonly store: string;
+    readonly root: string;
+    readonly speaker: string;
+    readonly module: string;
+    readonly kind: Kind;
+    readonly code: string;
+    readonly lineage: readonly string[];
+    readonly kept: readonly string[];
+}): {
+    readonly by: string;
+    readonly lines: readonly string[];
+};

package/dist/observe/identity.js

@@ -0,0 +1,61 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { canonical } from '@lapxo/topos/wire';
+import { bytesDigest } from "../fold/digests.js";
+import { fieldOf, selfName } from "../fold/claims.js";
+import { observeText } from "./files.js";
+import { runReader } from "./run.js";
+import { wordOf } from "../fold/wire.js";
+import { lockStanding } from "../fold/keys.js";
+/** Where a reader's vectors lie: in its package, beside its source, under the name of its module, the folder the wire's vector family names. */
+export const vectorsOf = (module, standing) => join(module.split('/')[0] ?? '', `${wordOf(standing, 'families', 'vector')}s`, `${basename(module).replace(/\.[^.]+$/, '')}.json`);
+export const withoutVectors = (root, modules, standing) => [...new Set(modules)].filter((module) => observeText(resolve(root, vectorsOf(module, standing))) === undefined).length;
+export function resetsOnEqualEmits(lines) {
+    const named = new Map();
+    for (const line of lines.filter((one) => fieldOf(one, 'measure') === 'emits')) {
+        const key = `${fieldOf(line, 'scope')} ${fieldOf(line, 'value')}`;
+        named.set(key, (named.get(key) ?? new Set()).add(fieldOf(line, 'at')));
+    }
+    return [...named.values()].filter((ats) => ats.size > 1).length;
+}
+function emitted(store, root, module, kind, cases) {
+    const laid = kind === 'process' ? mkdtempSync(join(tmpdir(), `${selfName()}-vectors-`)) : root;
+    try {
+        for (const one of kind === 'process' ? cases : []) {
+            for (const [name, text] of Object.entries(one.files ?? {})) {
+                mkdirSync(dirname(join(laid, one.place, name)), { recursive: true });
+                writeFileSync(join(laid, one.place, name), text);
+            }
+        }
+        const rows = runReader(resolve(root, module), laid, cases.map((one) => ({ place: one.place, ...(kind === 'js' ? { text: one.text ?? '' } : {}) })));
+        if (cases.length && rows.every((mine) => !mine.length))
+            return undefined;
+        const said = rows.map((mine) => mine.filter((row) => !/^(cost|derived|vector-memo)\//.test(row.scope)).map((row) => JSON.stringify(row)).sort());
+        return bytesDigest(store, new TextEncoder().encode(JSON.stringify(said))).replace(/^[^:]*:/, '');
+    }
+    finally {
+        if (laid !== root)
+            rmSync(laid, { recursive: true, force: true });
+    }
+}
+/** The executable keys the reader; its vector results describe only the cases measured. */
+export function identityOf(input) {
+    const text = observeText(resolve(input.root, vectorsOf(input.module, lockStanding(input.store))));
+    if (text === undefined)
+        return { by: input.code, lines: [] };
+    const short = (value) => bytesDigest(input.store, new TextEncoder().encode(value)).replace(/^[^:]*:/, '').slice(0, 12);
+    const key = short(`${input.code} ${short(text)}`);
+    const mine = input.kept.filter((line) => fieldOf(line, 'scope') === `reader/${input.module}`);
+    const known = mine.find((line) => fieldOf(line, 'measure') === 'extension' && fieldOf(line, 'at') === `place:${key}`);
+    if (known !== undefined && fieldOf(known, 'value') === input.code)
+        return { by: input.code, lines: [] };
+    const emits = emitted(input.store, input.root, input.module, input.kind, JSON.parse(text).cases ?? []);
+    if (emits === undefined)
+        return { by: input.code, lines: [] };
+    const by = input.code;
+    const line = (measure, value, at) => canonical({
+        scope: `reader/${input.module}`, role: 'writes', form: 'alphabet', measure, value, by: `${input.speaker}:${by}`, at: `place:${at}`,
+    });
+    return { by, lines: [line('extension', by, key), line('emits', emits, by)] };
+}

package/dist/observe/match.d.ts

@@ -0,0 +1 @@
+export declare const fits: (read: string, coordinate: string) => boolean;

package/dist/observe/match.js

@@ -0,0 +1,8 @@
+import * as wire from '@lapxo/topos/wire';
+const { matches } = wire;
+export const fits = (read, coordinate) => {
+    const glob = read.includes('@') ? read.slice(0, read.indexOf('@')) : read;
+    const [bare, tail] = coordinate.endsWith('/') ? [coordinate.slice(0, -1), '/'] : [coordinate, ''];
+    const steps = bare.split('/');
+    return steps.some((_, i) => matches(glob, `${steps.slice(i).join('/')}${tail}`));
+};