@lapxo/topos 0.1.0

package/dist/wire/line.js

@@ -0,0 +1,118 @@
+import { abstain, fact, refuse } from "./outcome.js";
+import { boundOf } from "./values.js";
+export const PROTOCOL = 'bound-lock/1';
+const NEEDS_QUOTE = /[ ="\n\\]/;
+function escape(value) {
+    if (!NEEDS_QUOTE.test(value))
+        return value;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+}
+function unescape(token) {
+    if (!token.startsWith('"'))
+        return NEEDS_QUOTE.test(token) ? null : token;
+    if (token.length < 2 || !token.endsWith('"'))
+        return null;
+    const body = token.slice(1, -1);
+    let out = '';
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c !== '\\') {
+            if (c === '"')
+                return null;
+            out += c;
+            continue;
+        }
+        const next = body[i + 1];
+        if (next === '"')
+            out += '"';
+        else if (next === '\\')
+            out += '\\';
+        else if (next === 'n')
+            out += '\n';
+        else
+            return null;
+        i += 1;
+    }
+    return out;
+}
+const UTF8 = new TextEncoder();
+export function byBytes(a, b) {
+    const x = UTF8.encode(a);
+    const y = UTF8.encode(b);
+    for (let i = 0; i < x.length && i < y.length; i++) {
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    }
+    return x.length - y.length;
+}
+/* NO UNICODE NORMALISATION — NFC and NFD are two scopes until a bridge. */
+const unwritten = (fields) => fields['form'] === 'interval' && fields['value'] !== undefined && fields['value'] !== 'withdraw' && boundOf('interval', fields['value']) === null;
+export function canonical(fields, version = '1') {
+    if (unwritten(fields))
+        throw new Error(`REFUSE·wire canonical: \`${fields['value']}\` is no interval the wire writes: two ends, each decimal or *`);
+    const keys = Object.keys(fields).sort(byBytes);
+    const tokens = keys.map((k) => `${k}=${escape(fields[k])}`);
+    return [`${PROTOCOL.split('/')[0]}/${version}`, ...tokens].join(' ');
+}
+export function signedBytes(fields, version = '1') {
+    const { sig: _sig, ...rest } = fields;
+    return canonical(rest, version);
+}
+const ABSENT = '-';
+export function parse(text) {
+    if (text.includes('\n')) {
+        return refuse('a line is one line — a newline in a value must be escaped as `\\n`');
+    }
+    const space = text.indexOf(' ');
+    const envelope = space === -1 ? text : text.slice(0, space);
+    const [name, version] = envelope.split('/');
+    if (name !== PROTOCOL.split('/')[0] || !version) {
+        return refuse(`no \`bound-lock/<v>\` envelope — found \`${envelope.slice(0, 24)}\``);
+    }
+    if (version !== PROTOCOL.split('/')[1]) {
+        return abstain(`\`bound-lock/${version}\` is a version this reader does not know`);
+    }
+    const fields = {};
+    for (const token of tokensOf(space === -1 ? '' : text.slice(space + 1))) {
+        if (token === null)
+            return refuse('a quoted value is not closed');
+        const at = token.indexOf('=');
+        if (at <= 0)
+            return refuse(`\`${token.slice(0, 24)}\` is not \`key=value\``);
+        const key = token.slice(0, at);
+        if (key in fields)
+            return refuse(`\`${key}\` appears twice — one line, one value per key`);
+        const value = unescape(token.slice(at + 1));
+        if (value === null)
+            return refuse(`\`${key}\` has an escaping this format does not define`);
+        if (value !== ABSENT)
+            fields[key] = value;
+    }
+    if (unwritten(fields))
+        return refuse(`\`${fields['value']}\` is no interval the wire reads: two ends, each decimal or *`);
+    return fact({ version, fields });
+}
+function* tokensOf(rest) {
+    let at = 0;
+    while (at < rest.length) {
+        while (rest[at] === ' ')
+            at += 1;
+        if (at >= rest.length)
+            return;
+        let end = at;
+        let quoted = false;
+        while (end < rest.length && (quoted || rest[end] !== ' ')) {
+            if (rest[end] === '\\' && quoted)
+                end += 1;
+            else if (rest[end] === '"')
+                quoted = !quoted;
+            end += 1;
+        }
+        if (quoted) {
+            yield null;
+            return;
+        }
+        yield rest.slice(at, end);
+        at = end;
+    }
+}

package/dist/wire/measures.d.ts

@@ -0,0 +1,2 @@
+/** The readings of a measure combined as the measure says; one this table names no combination for is refused when it is more than one. */
+export declare function combine(measure: string, values: readonly number[]): number;

package/dist/wire/measures.js

@@ -0,0 +1,13 @@
+import { intervals } from '@lapxo/obligations';
+const READINGS = intervals(-Infinity, Infinity);
+/** How the readings of one measure combine when a line reads more than one of them: counts, sizes and showings add up; a longest is the longest. */
+const COMBINATIONS = { count: 'sum', size: 'sum', shown: 'sum', longest: 'max' };
+/** The readings of a measure combined as the measure says; one this table names no combination for is refused when it is more than one. */
+export function combine(measure, values) {
+    const how = COMBINATIONS[measure];
+    if (how === 'max')
+        return values.reduce((held, one) => READINGS.join(held, { lo: -Infinity, hi: one }), { lo: -Infinity, hi: 0 }).hi;
+    if (how === 'sum' || values.length <= 1)
+        return values.reduce((sum, one) => sum + one, 0);
+    throw new Error(`REFUSE·measure ${measure}: ${values.length} readings and no combination the wire names for them`);
+}

package/dist/wire/names.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The format's own names, spelled once: the extension every file of the format carries, and the three files it names
+ * by it.
+ */
+export declare const EXTENSION = ".bound";
+export declare const LOCK = "TARGET.bound";
+export declare const CAPSULE = "capsule.bound";
+export declare const RECEIPTS = "receipts.bound";

package/dist/wire/names.js

@@ -0,0 +1,8 @@
+/**
+ * The format's own names, spelled once: the extension every file of the format carries, and the three files it names
+ * by it.
+ */
+export const EXTENSION = '.bound';
+export const LOCK = `TARGET${EXTENSION}`;
+export const CAPSULE = `capsule${EXTENSION}`;
+export const RECEIPTS = `receipts${EXTENSION}`;

package/dist/wire/outcome.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Three arms, and there is no fourth. Isolated so the line kernel
+ * does not import the rest of the wire.
+ */
+export type Outcome<T> = {
+    readonly kind: 'fact';
+    readonly value: T;
+} | {
+    readonly kind: 'abstain';
+    readonly why: string;
+} | {
+    readonly kind: 'refuse';
+    readonly why: string;
+    readonly named?: string;
+};
+export declare const fact: <T>(value: T) => Outcome<T>;
+export declare const abstain: <T>(why: string) => Outcome<T>;
+export declare const refuse: <T>(why: string, named?: string) => Outcome<T>;

package/dist/wire/outcome.js

@@ -0,0 +1,3 @@
+export const fact = (value) => ({ kind: 'fact', value });
+export const abstain = (why) => ({ kind: 'abstain', why });
+export const refuse = (why, named) => ({ kind: 'refuse', why, ...(named === undefined ? {} : { named }) });

package/dist/wire/sig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A signature is a value, not an act: `<algorithm>:<raw>` over the canonical bytes of every other field of a claim,
+ * with the signer named. The algorithm is named by the digest of its definition, never by a name of its era, so no
+ * alphabet of algorithms is closed here: which ones a wire admits, and from which epoch, is a signed line of its lock.
+ * The raw part never holds a colon, so the last colon parts them; a digest may carry its own.
+ */
+interface SignatureValue {
+    readonly algorithm: string;
+    readonly raw: string;
+}
+export declare function formatSignature(algorithm: string, raw: string): string;
+export declare function parseSignature(value: string): SignatureValue | null;
+/** The fields a signature covers: every field but the signature itself, with the signer named. */
+export declare function signedFieldsOf(fields: Readonly<Record<string, string>>, signer: string): Record<string, string>;
+export {};

package/dist/wire/sig.js

@@ -0,0 +1,15 @@
+export function formatSignature(algorithm, raw) {
+    return `${algorithm}:${raw}`;
+}
+export function parseSignature(value) {
+    const colon = value.lastIndexOf(':');
+    if (colon <= 0 || colon === value.length - 1)
+        return null;
+    return { algorithm: value.slice(0, colon), raw: value.slice(colon + 1) };
+}
+/** The fields a signature covers: every field but the signature itself, with the signer named. */
+export function signedFieldsOf(fields, signer) {
+    const covered = { ...fields, by: signer };
+    delete covered['sig'];
+    return covered;
+}

package/dist/wire/spec.d.ts

@@ -0,0 +1,28 @@
+import { PROTOCOL } from './index.ts';
+export interface Request {
+    readonly protocol: typeof PROTOCOL;
+    readonly verb: 'describe' | 'read' | 'render';
+    readonly rootScope: string;
+    readonly files: readonly {
+        readonly place: string;
+        readonly text: string;
+    }[];
+    readonly held?: readonly (readonly [string, string])[];
+    readonly region?: string;
+    readonly at?: number;
+    readonly name?: string;
+    readonly lines?: readonly string[];
+    readonly reads?: readonly string[];
+    readonly shape?: string;
+    readonly regions?: Readonly<Record<string, {
+        readonly lines: readonly string[];
+        readonly receipts: readonly string[];
+    }>>;
+}
+export interface Response {
+    readonly protocol: typeof PROTOCOL;
+    readonly kind: 'fact' | 'abstain' | 'refuse';
+    readonly claims?: readonly unknown[];
+    readonly lines?: readonly string[];
+    readonly why?: string;
+}

package/dist/wire/spec.js

@@ -0,0 +1 @@
+export {};

package/dist/wire/types.d.ts

@@ -0,0 +1,73 @@
+import type { Method, MeasureForm as Form } from '@lapxo/obligations';
+import type { Poset, MeetSemilattice, JoinSemilattice, Lattice } from '@lapxo/obligations/lattice';
+export type { Method, Form, Poset, MeetSemilattice, JoinSemilattice, Lattice };
+export { PROTOCOL } from './line.ts';
+import { PROTOCOL } from './line.ts';
+type Measure = {
+    readonly id: string;
+    readonly unit?: string;
+    readonly exist?: readonly string[];
+} & ({
+    readonly form: 'ladder';
+    readonly levels: readonly string[];
+} | {
+    readonly form: 'alphabet';
+    readonly tokens: readonly string[];
+} | {
+    readonly form: 'continuous';
+    readonly lo: number | null;
+    readonly hi: number | null;
+});
+export type Bound = {
+    readonly kind: 'band';
+    readonly floor: string;
+    readonly ceiling: string;
+} | {
+    readonly kind: 'enumerated';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'interval';
+    readonly lo: number | null;
+    readonly hi: number | null;
+};
+type Multiplicity = 'one' | 'many' | 'unknown';
+interface Reference {
+    readonly rel: 'within' | 'copies' | 'derives';
+    readonly to: readonly string[];
+    readonly by: 'inferred' | 'declared';
+}
+interface Authority {
+    readonly author: string;
+    readonly scopePrefix: string;
+    readonly signature?: string;
+}
+interface Support {
+    readonly observed: number;
+    readonly supporters: number;
+    readonly method: Method;
+    readonly channel: string;
+    readonly control: 'ok' | 'UNRELIABLE';
+    readonly excludedRatio?: number;
+}
+export interface Claim {
+    readonly scope: string;
+    readonly measure: string;
+    readonly bound: Bound;
+    readonly role: 'writes' | 'reads' | 'demands';
+    readonly by: string;
+    readonly at: string;
+    readonly unit?: string;
+    readonly epoch?: string;
+    readonly multiplicity?: Multiplicity;
+    readonly reference?: Reference | null;
+    readonly support?: Support;
+    readonly extra?: Readonly<Record<string, string>>;
+}
+export interface Lock {
+    readonly protocol: typeof PROTOCOL;
+    readonly measures?: readonly Measure[];
+    readonly claims?: readonly Claim[];
+    readonly authorities?: readonly Authority[];
+}
+export type { Outcome } from './outcome.ts';
+export { fact, abstain, refuse } from './outcome.ts';

package/dist/wire/types.js

@@ -0,0 +1,2 @@
+export { PROTOCOL } from "./line.js";
+export { fact, abstain, refuse } from "./outcome.js";

package/dist/wire/values.d.ts

@@ -0,0 +1,23 @@
+import type { Bound } from './types.ts';
+export declare function unpipe(value: string): readonly string[] | null;
+/**
+ * A number as the wire writes it, the only spelling it reads: decimal digits, a minus when negative and a fraction
+ * when it has one, never an exponent, a hex prefix, a leading dot or padding. The digits are the shortest that read
+ * back to the number, so a second head in any language writes the same bytes; a number that is not finite has none.
+ */
+export declare function decimal(n: number): string;
+export interface FormGrammar {
+    readonly form: string;
+    readonly parse: (value: string) => Bound | null;
+}
+export declare function boundOf(form: string, value: string, grammars?: readonly FormGrammar[]): Bound | null;
+export declare const BOUND_FORMS: readonly string[];
+export declare const REF_RELATIONS: readonly ["within", "copies", "derives"];
+export interface Refusal {
+    readonly kind: 'refuse';
+    readonly scope: string;
+    readonly measure: string;
+    readonly why: string;
+    readonly witness: string;
+    readonly at?: string;
+}

package/dist/wire/values.js

@@ -0,0 +1,80 @@
+export function unpipe(value) {
+    const out = [];
+    let at = '';
+    for (let i = 0; i < value.length; i++) {
+        const c = value[i];
+        if (c === '\\') {
+            const next = value[i + 1];
+            if (next !== '|' && next !== '\\')
+                return null;
+            at += next;
+            i += 1;
+        }
+        else if (c === '|') {
+            out.push(at);
+            at = '';
+        }
+        else {
+            at += c;
+        }
+    }
+    out.push(at);
+    return out;
+}
+const OPEN = '*';
+const num = (s) => {
+    if (!/^-?\d+(\.\d+)?$/.test(s))
+        return null;
+    const n = Number(s);
+    return isFinite(n) ? n : null;
+};
+/**
+ * A number as the wire writes it, the only spelling it reads: decimal digits, a minus when negative and a fraction
+ * when it has one, never an exponent, a hex prefix, a leading dot or padding. The digits are the shortest that read
+ * back to the number, so a second head in any language writes the same bytes; a number that is not finite has none.
+ */
+export function decimal(n) {
+    if (!isFinite(n))
+        throw new Error(`REFUSE·wire decimal: \`${n}\` is not a finite number`);
+    const got = /^(-?)(\d)(?:\.(\d+))?e([+-])(\d+)$/.exec(String(n));
+    if (got === null)
+        return String(n);
+    const [, sign = '', lead = '', rest = '', ahead = '', exp = '0'] = got;
+    return ahead === '+' ? `${sign}${lead}${rest}${'0'.repeat(Number(exp) - rest.length)}` : `${sign}0.${'0'.repeat(Number(exp) - 1)}${lead}${rest}`;
+}
+/**
+ * The forms this reader parses, each with the grammar that reads its value. The alphabet of forms is what these
+ * implement — never a list kept beside them, which the lock could move and the list could not.
+ */
+const GRAMMARS = {
+    interval: (value) => {
+        const at = value.indexOf('..');
+        if (at < 0)
+            return null;
+        const lo = value.slice(0, at);
+        const hi = value.slice(at + 2);
+        const l = lo === OPEN ? null : num(lo);
+        const h = hi === OPEN ? null : num(hi);
+        if ((lo !== OPEN && l === null) || (hi !== OPEN && h === null))
+            return null;
+        return { kind: 'interval', lo: l, hi: h };
+    },
+    alphabet: (value) => {
+        const values = unpipe(value);
+        return values === null ? null : { kind: 'enumerated', values };
+    },
+    ladder: (value) => {
+        const parts = unpipe(value);
+        if (parts === null || parts.length !== 2)
+            return null;
+        return { kind: 'band', floor: parts[0] ?? '', ceiling: parts[1] ?? '' };
+    },
+};
+export function boundOf(form, value, grammars) {
+    const extra = Array.isArray(grammars) ? grammars.find((g) => g.form === form) : undefined;
+    if (extra)
+        return extra.parse(value);
+    return GRAMMARS[form]?.(value) ?? null;
+}
+export const BOUND_FORMS = Object.keys(GRAMMARS);
+export const REF_RELATIONS = ['within', 'copies', 'derives'];

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@lapxo/topos",
+  "version": "0.1.0",
+  "description": "Bound's SDK: the wire, the forms, the contract and the shell you build a world with — a reader of any source or a renderer of any artefact, in an afternoon.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lapxo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lapxo/topos.git"
+  },
+  "keywords": [
+    "topos",
+    "lock",
+    "wire",
+    "capsule"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/readers/index.d.ts",
+      "default": "./dist/readers/index.js"
+    },
+    "./authority": {
+      "types": "./dist/authority/index.d.ts",
+      "default": "./dist/authority/index.js"
+    },
+    "./capsule": {
+      "types": "./dist/capsule/index.d.ts",
+      "default": "./dist/capsule/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "default": "./dist/contract/index.js"
+    },
+    "./forms": {
+      "types": "./dist/forms/index.d.ts",
+      "default": "./dist/forms/index.js"
+    },
+    "./readers": {
+      "types": "./dist/readers/index.d.ts",
+      "default": "./dist/readers/index.js"
+    },
+    "./wire": {
+      "types": "./dist/wire/index.d.ts",
+      "default": "./dist/wire/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "TARGET.bound"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "@lapxo/obligations": "^0.3.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}