@polydeukes/core 0.5.0 → 0.6.1

package/dist/algebra.js

@@ -0,0 +1,438 @@
+/**
+ * `algebra.ts` — the shape of one algebra declaration: five blocks, a closed relation
+ * position, a closed binary combinator position, and an open unary extraction vocabulary.
+ *
+ * The module knows no judgment. It runs no extraction and evaluates no relation; the
+ * kernel expansion laws quoted on each relation branch below are comments, never code.
+ */
+import { validateMechanism } from './catalogue.js';
+import { isPlainObject } from './is-plain-object.js';
+import { FIXED_SOURCE_NAMES } from './source-names.js';
+import { ConfigValidationError, isNonEmptyString, isStringArray, rejectUncompilableRegex, rejectUnknownKeys, } from './validation.js';
+/** The relation position, closed. This tuple is the single source of the list. */
+export const RELATION_NAMES = [
+    'empty',
+    'nonEmpty',
+    'equal',
+    'subset',
+    'implies',
+    'ordered',
+    'unchanged',
+];
+/** The binary world-combining position, closed. Anything else is a unary step. */
+export const BINARY_COMBINATOR_NAMES = ['union', 'onlyIn', 'intersect'];
+/**
+ * What a missing source does: refuse the declaration, let it pass unjudged, or read the
+ * absence as an empty item list and judge on.
+ */
+export const SUPPLY_POLICIES = ['error', 'pass', 'empty'];
+/**
+ * The paired source name. `empty` is a property of a single source: `state` holds a
+ * before/after pair that only `unchanged` reads, and an absent pair is not a pair of empties.
+ */
+const PAIRED_SOURCE_NAME = 'state';
+/** The kind position of a `sources` entry, closed. Each entry carries exactly one of them. */
+export const SOURCE_KINDS = ['file', 'sidecar', 'transcript'];
+const DECLARATION_KEYS = new Set([
+    'discipline',
+    'mechanism',
+    'scope',
+    'sources',
+    'supply',
+    'extract',
+    'relate',
+    'witness',
+]);
+const SCOPE_KEYS = new Set([
+    'source',
+    'include',
+    'exclude',
+    'excludeIgnoreCase',
+]);
+const RELATE_ENTRY_KEYS = new Set([
+    'id',
+    'relation',
+    'message',
+    'messageBySide',
+]);
+const MESSAGE_BY_SIDE_KEYS = new Set(['left', 'right']);
+const WITNESS_KEYS = new Set(['extract', 'relate']);
+/** The argument keys each relation branch admits, `op` included. */
+const RELATION_KEYS = {
+    empty: new Set(['op', 'of']),
+    nonEmpty: new Set(['op', 'of']),
+    equal: new Set(['op', 'of']),
+    subset: new Set(['op', 'of', 'in']),
+    implies: new Set(['op', 'of', 'requires']),
+    ordered: new Set(['op', 'of', 'strict']),
+    unchanged: new Set(['op', 'of']),
+};
+const COMBINATOR_KEYS = {
+    union: new Set(['op', 'of']),
+    onlyIn: new Set(['op', 'of', 'notIn']),
+    intersect: new Set(['op', 'of']),
+};
+function isCombinatorName(op) {
+    return BINARY_COMBINATOR_NAMES.includes(op);
+}
+/** The names a rejection message lists so the author sees what is admitted. */
+function quotedList(names) {
+    return names.map((name) => `'${name}'`).join(', ');
+}
+/**
+ * The source names a scope regex can be read over: the fixed names whose value is a string,
+ * plus this declaration's own `file` bindings. `changes` is a list and `state` a pair, and a
+ * channel is the surface's JSON text — a regex over any of them matches nothing, so a
+ * declaration scoped on one is refused here rather than answering zero worlds at runtime.
+ */
+const STRING_VALUED_FIXED_SOURCES = ['target.path', 'pre', 'post', 'command'];
+function validateScope(scope, sources, location) {
+    if (!isPlainObject(scope)) {
+        throw new ConfigValidationError(`${location} scope must be an object`);
+    }
+    rejectUnknownKeys(scope, SCOPE_KEYS, `${location} scope`);
+    if (!isNonEmptyString(scope.source)) {
+        throw new ConfigValidationError(`${location} scope.source must be a non-empty string`);
+    }
+    const binding = isPlainObject(sources) ? sources[scope.source] : undefined;
+    const isFileSource = isPlainObject(binding) && typeof binding.file === 'string';
+    if (!STRING_VALUED_FIXED_SOURCES.includes(scope.source) && !isFileSource) {
+        throw new ConfigValidationError(`${location} scope.source '${scope.source}' is not a string-valued source; scope admits ${quotedList(STRING_VALUED_FIXED_SOURCES)}, or a file source`);
+    }
+    for (const key of ['include', 'exclude']) {
+        const patterns = scope[key];
+        if (patterns === undefined)
+            continue;
+        if (!isStringArray(patterns)) {
+            throw new ConfigValidationError(`${location} scope.${key} must be an array of strings`);
+        }
+        for (const pattern of patterns) {
+            rejectUncompilableRegex(pattern, `${location} scope.${key}`);
+        }
+    }
+    if (scope.excludeIgnoreCase !== undefined && typeof scope.excludeIgnoreCase !== 'boolean') {
+        throw new ConfigValidationError(`${location} scope.excludeIgnoreCase must be a boolean`);
+    }
+}
+/**
+ * Validate one `sources` entry's path: a repo-relative string the supply layer can join
+ * onto the root. `..` is rejected as a whole SEGMENT, so a name that merely contains two
+ * dots (`a..b`) stays legal while `a/../b` cannot climb out of the repository.
+ */
+function validateSourceFile(file, location) {
+    if (!isNonEmptyString(file)) {
+        throw new ConfigValidationError(`${location}.file must be a non-empty string`);
+    }
+    if (file.startsWith('/')) {
+        throw new ConfigValidationError(`${location}.file must be a repo-relative path, not '${file}'`);
+    }
+    if (file.split('/').includes('..')) {
+        throw new ConfigValidationError(`${location}.file carries a '..' segment: '${file}'`);
+    }
+}
+function validateSources(sources, location) {
+    if (!isPlainObject(sources)) {
+        throw new ConfigValidationError(`${location}.sources must be an object`);
+    }
+    for (const [name, entry] of Object.entries(sources)) {
+        if (name.length === 0) {
+            throw new ConfigValidationError(`${location}.sources carries an empty source name`);
+        }
+        if (FIXED_SOURCE_NAMES.includes(name)) {
+            throw new ConfigValidationError(`${location}.sources.${name} shadows the world's own source of that name — the fixed names are ${quotedList(FIXED_SOURCE_NAMES)}`);
+        }
+        const where = `${location}.sources.${name}`;
+        if (!isPlainObject(entry)) {
+            throw new ConfigValidationError(`${where} must be an object naming one kind`);
+        }
+        const kinds = Object.keys(entry).filter((key) => SOURCE_KINDS.includes(key));
+        if (kinds.length !== 1) {
+            throw new ConfigValidationError(`${where} must name exactly one kind, one of ${quotedList(SOURCE_KINDS)}`);
+        }
+        rejectUnknownKeys(entry, new Set(SOURCE_KINDS), where);
+        const kind = kinds[0];
+        if (kind === 'sidecar' || kind === 'transcript') {
+            // The marker carries no information beyond the kind, so anything but the literal
+            // `true` would be a value the supply layer has to interpret.
+            if (entry[kind] !== true) {
+                throw new ConfigValidationError(`${where}.${kind} must be the literal true`);
+            }
+            continue;
+        }
+        validateSourceFile(entry.file, where);
+    }
+}
+/**
+ * Validate the `supply` block: every key names a source this declaration can be missing.
+ *
+ * The universe of source names is the fixed seven plus whatever `sources` binds, and it is
+ * closed, so a key outside it is a name nothing supplies — a misspelling whose policy never
+ * applies while the real source falls to the default.
+ */
+function validateSupply(supply, sources, location) {
+    if (!isPlainObject(supply)) {
+        throw new ConfigValidationError(`${location} supply must be an object`);
+    }
+    const declared = isPlainObject(sources) ? Object.keys(sources) : [];
+    for (const [source, policy] of Object.entries(supply)) {
+        if (!FIXED_SOURCE_NAMES.includes(source) && !declared.includes(source)) {
+            const bindings = declared.length === 0 ? 'and this declaration binds none' : `or ${quotedList(declared)}`;
+            throw new ConfigValidationError(`${location} supply names the source '${source}', which is neither one of ${quotedList(FIXED_SOURCE_NAMES)} ${bindings}`);
+        }
+        if (!SUPPLY_POLICIES.includes(policy)) {
+            throw new ConfigValidationError(`${location} supply.${source} is '${String(policy)}' — must be one of ${quotedList(SUPPLY_POLICIES)}`);
+        }
+        if (policy === 'empty' && source === PAIRED_SOURCE_NAME) {
+            throw new ConfigValidationError(`${location} supply.${source}: 'empty' does not apply to the paired source — it holds a before/after pair, and an absent pair is not two empty states`);
+        }
+    }
+}
+/**
+ * Validate one pipeline step and return the extract names it references.
+ *
+ * Combinator discrimination is name-first, shape-second: a step named by one of the three
+ * is read as that combinator whatever its arguments, so a reserved name can never leak into
+ * the open unary vocabulary. A name outside the three that references two extractions
+ * (an array `of`, or a `notIn`) is an unknown combinator, not a unary step.
+ */
+function validateStep(step, location) {
+    if (!isPlainObject(step)) {
+        throw new ConfigValidationError(`${location} must be an object`);
+    }
+    if (!isNonEmptyString(step.op)) {
+        throw new ConfigValidationError(`${location} op must be a non-empty string`);
+    }
+    const op = step.op;
+    if (!isCombinatorName(op)) {
+        if (Array.isArray(step.of) || step.notIn !== undefined) {
+            throw new ConfigValidationError(`${location} op '${op}' references two extractions but is not one of ${quotedList(BINARY_COMBINATOR_NAMES)}`);
+        }
+        return [];
+    }
+    rejectUnknownKeys(step, COMBINATOR_KEYS[op], `${location} (${op})`);
+    if (op === 'onlyIn') {
+        if (!isNonEmptyString(step.of) || !isNonEmptyString(step.notIn)) {
+            throw new ConfigValidationError(`${location} '${op}' takes a string 'of' and a string 'notIn'`);
+        }
+        if (step.of === step.notIn) {
+            throw new ConfigValidationError(`${location} '${op}' names '${step.of}' on both sides — the result is always empty`);
+        }
+        return [step.of, step.notIn];
+    }
+    const pair = step.of;
+    if (!isStringArray(pair) || pair.length !== 2 || !pair.every(isNonEmptyString)) {
+        throw new ConfigValidationError(`${location} '${op}' takes 'of' as two extract names`);
+    }
+    const [left, right] = pair;
+    if (left === right) {
+        throw new ConfigValidationError(`${location} '${op}' names '${left}' on both sides — the result is that extraction itself`);
+    }
+    return [left, right];
+}
+/** Validate one extract block, returning each pipeline's outgoing references. */
+function validateExtract(extract, location, label) {
+    if (!isPlainObject(extract)) {
+        throw new ConfigValidationError(`${location} ${label} must be an object`);
+    }
+    const references = new Map();
+    for (const [name, steps] of Object.entries(extract)) {
+        const where = `${location} ${label}.${name}`;
+        if (!Array.isArray(steps) || steps.length === 0) {
+            throw new ConfigValidationError(`${where} must be a non-empty array of steps`);
+        }
+        const outgoing = [];
+        steps.forEach((step, index) => {
+            const referenced = validateStep(step, `${where}[${index}]`);
+            if (referenced.length > 0 && index !== 0) {
+                throw new ConfigValidationError(`${where}[${index}] a combinator stands only as the first step of a pipeline`);
+            }
+            outgoing.push(...referenced);
+        });
+        references.set(name, outgoing);
+    }
+    return references;
+}
+/** Validate the relation and return the extract names it references. */
+function validateRelation(relation, location) {
+    if (!isPlainObject(relation)) {
+        throw new ConfigValidationError(`${location} relation must be an object`);
+    }
+    const op = relation.op;
+    if (typeof op !== 'string' || !RELATION_NAMES.includes(op)) {
+        throw new ConfigValidationError(`${location} relation op is '${String(op)}' — must be one of ${quotedList(RELATION_NAMES)}`);
+    }
+    const name = op;
+    rejectUnknownKeys(relation, RELATION_KEYS[name], `${location} relation (${name})`);
+    if (name === 'equal') {
+        const pair = relation.of;
+        if (!isStringArray(pair) || pair.length !== 2 || !pair.every(isNonEmptyString)) {
+            throw new ConfigValidationError(`${location} relation equal takes 'of' as two extract names`);
+        }
+        const [left, right] = pair;
+        if (left === right) {
+            throw new ConfigValidationError(`${location} relation equal names '${left}' on both sides — it can never break`);
+        }
+        return { op: name, refs: [left, right] };
+    }
+    if (!isNonEmptyString(relation.of)) {
+        throw new ConfigValidationError(`${location} relation ${name} needs 'of' as an extract name`);
+    }
+    const refs = [relation.of];
+    if (name === 'subset') {
+        if (!isNonEmptyString(relation.in)) {
+            throw new ConfigValidationError(`${location} relation subset needs 'in' as an extract name`);
+        }
+        refs.push(relation.in);
+    }
+    if (name === 'implies') {
+        if (!isNonEmptyString(relation.requires)) {
+            throw new ConfigValidationError(`${location} relation implies needs 'requires' as an extract name`);
+        }
+        refs.push(relation.requires);
+    }
+    if (name === 'ordered' && relation.strict !== undefined && typeof relation.strict !== 'boolean') {
+        throw new ConfigValidationError(`${location} relation ordered strict must be a boolean`);
+    }
+    return { op: name, refs };
+}
+/** Validate one entry; `ids` accumulates across the body and the witness block. */
+function validateRelateEntry(entry, location, known, ids) {
+    if (!isPlainObject(entry)) {
+        throw new ConfigValidationError(`${location} must be an object`);
+    }
+    rejectUnknownKeys(entry, RELATE_ENTRY_KEYS, location);
+    if (!isNonEmptyString(entry.id)) {
+        throw new ConfigValidationError(`${location} id must be a non-empty string`);
+    }
+    const id = entry.id;
+    if (ids.has(id)) {
+        throw new ConfigValidationError(`${location} duplicates the entry id '${id}'`);
+    }
+    ids.add(id);
+    const { op, refs } = validateRelation(entry.relation, `${location} '${id}'`);
+    for (const name of refs) {
+        if (!known.has(name)) {
+            throw new ConfigValidationError(`${location} '${id}' references '${name}', which no extract in scope defines`);
+        }
+    }
+    const hasMessage = entry.message !== undefined;
+    const hasBySide = entry.messageBySide !== undefined;
+    if (hasMessage === hasBySide) {
+        throw new ConfigValidationError(`${location} '${id}' needs exactly one of 'message' and 'messageBySide'`);
+    }
+    if (hasMessage && !isNonEmptyString(entry.message)) {
+        throw new ConfigValidationError(`${location} '${id}' message must be a non-empty string`);
+    }
+    if (hasBySide) {
+        if (op !== 'equal') {
+            throw new ConfigValidationError(`${location} '${id}' carries messageBySide on ${op} — only equal has two sides`);
+        }
+        const bySide = entry.messageBySide;
+        if (!isPlainObject(bySide)) {
+            throw new ConfigValidationError(`${location} '${id}' messageBySide must be an object`);
+        }
+        rejectUnknownKeys(bySide, MESSAGE_BY_SIDE_KEYS, `${location} '${id}' messageBySide`);
+        if (!isNonEmptyString(bySide.left) || !isNonEmptyString(bySide.right)) {
+            throw new ConfigValidationError(`${location} '${id}' messageBySide needs a non-empty 'left' and 'right'`);
+        }
+    }
+}
+function validateRelate(relate, location, known, ids) {
+    if (!Array.isArray(relate) || relate.length === 0) {
+        throw new ConfigValidationError(`${location} relate must be a non-empty array`);
+    }
+    relate.forEach((entry, index) => {
+        validateRelateEntry(entry, `${location} relate[${index}]`, known, ids);
+    });
+}
+/**
+ * Refuse a combinator reference that does not resolve, and any cycle it takes part in.
+ *
+ * A self-edge is the shortest cycle, so a plain existence check passes it; only the
+ * reachability walk below finds either that or a two-pipeline loop.
+ */
+function checkExtractGraph(references, known, location) {
+    for (const [name, outgoing] of references) {
+        for (const target of outgoing) {
+            if (!known.has(target)) {
+                throw new ConfigValidationError(`${location} '${name}' references '${target}', which no extract defines`);
+            }
+        }
+    }
+    const visiting = new Set();
+    const settled = new Set();
+    const walk = (name) => {
+        if (settled.has(name))
+            return;
+        if (visiting.has(name)) {
+            throw new ConfigValidationError(`${location} '${name}' takes part in a reference cycle`);
+        }
+        visiting.add(name);
+        for (const target of references.get(name) ?? []) {
+            walk(target);
+        }
+        visiting.delete(name);
+        settled.add(name);
+    };
+    for (const name of references.keys()) {
+        walk(name);
+    }
+}
+/**
+ * Validate one algebra declaration's shape, returning it unchanged.
+ *
+ * Every violation throws {@link ConfigValidationError} with a message starting at
+ * `location`, so a caller validating many declarations sees which one failed.
+ */
+export function validateAlgebraDeclaration(input, location = 'declaration') {
+    if (!isPlainObject(input)) {
+        throw new ConfigValidationError(`${location} must be an object`);
+    }
+    rejectUnknownKeys(input, DECLARATION_KEYS, location);
+    if (!isNonEmptyString(input.discipline)) {
+        throw new ConfigValidationError(`${location} discipline must be a non-empty string`);
+    }
+    if (!isNonEmptyString(input.mechanism)) {
+        throw new ConfigValidationError(`${location} mechanism must be a non-empty string`);
+    }
+    if (input.sources !== undefined)
+        validateSources(input.sources, location);
+    if (input.scope !== undefined)
+        validateScope(input.scope, input.sources, location);
+    if (input.supply !== undefined)
+        validateSupply(input.supply, input.sources, location);
+    if (input.extract === undefined) {
+        throw new ConfigValidationError(`${location} needs an extract block`);
+    }
+    const bodyReferences = validateExtract(input.extract, location, 'extract');
+    const bodyNames = new Set(bodyReferences.keys());
+    checkExtractGraph(bodyReferences, bodyNames, `${location} extract`);
+    const ids = new Set();
+    if (input.relate === undefined) {
+        throw new ConfigValidationError(`${location} needs a relate array`);
+    }
+    validateRelate(input.relate, location, bodyNames, ids);
+    if (input.witness !== undefined) {
+        const witness = input.witness;
+        if (!isPlainObject(witness)) {
+            throw new ConfigValidationError(`${location} witness must be an object`);
+        }
+        rejectUnknownKeys(witness, WITNESS_KEYS, `${location} witness`);
+        // The witness sees the body's extract names as well as its own; the body never sees
+        // the witness's.
+        const witnessReferences = witness.extract === undefined
+            ? new Map()
+            : validateExtract(witness.extract, location, 'witness.extract');
+        for (const name of witnessReferences.keys()) {
+            if (bodyNames.has(name)) {
+                throw new ConfigValidationError(`${location} witness.extract '${name}' shadows the body extract of the same name — the two blocks share one namespace`);
+            }
+        }
+        const witnessNames = new Set([...bodyNames, ...witnessReferences.keys()]);
+        checkExtractGraph(witnessReferences, witnessNames, `${location} witness.extract`);
+        validateRelate(witness.relate, `${location} witness`, witnessNames, ids);
+    }
+    const declaration = input;
+    validateMechanism(declaration, location);
+    return declaration;
+}

package/dist/catalogue.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `catalogue.ts` — the eighteen judgment-mechanism names and the shape each one admits.
+ *
+ * A mechanism name is a coordinate the machine checks, not a label: {@link deriveShape}
+ * reads a declaration's shape from its syntax alone — which sources its `source` steps
+ * name, which relations its body relates, whether it carries a witness block — and
+ * {@link validateMechanism} refuses a declaration whose derived shape falls outside the
+ * spec of the name it carries. Nothing here runs an extraction or opens a world.
+ */
+import type { AlgebraDeclaration, RelationName } from './algebra.ts';
+/** The four axes a declaration can read, closed. This tuple is the single source of the list. */
+export declare const AXIS_NAMES: readonly ['change', 'actor', 'world', 'history'];
+/** One of the four axes — the closed vocabulary of the axis position. */
+export type Axis = (typeof AXIS_NAMES)[number];
+/** The judgment mechanisms, closed. A name outside this tuple is refused, never coerced. */
+export declare const MECHANISM_NAMES: readonly ['pairing', 'companion', 'monotonic-order', 'fingerprint-sync', 'producer-owned', 'self-absolution-ban', 'actor-scope', 'precedent', 'phase-order', 'turn-locality', 'stated-ground', 'controlled-vocabulary', 'naming', 'added-only', 'one-way-marker', 'delegated-scope', 'scoped-valve', 'forbidden-command'];
+/** One of the eighteen mechanism names. */
+export type MechanismName = (typeof MECHANISM_NAMES)[number];
+/**
+ * What one mechanism name admits: the axes it may read, the relations it may relate, and
+ * the structural markers it requires.
+ *
+ * `requiresWitness` asks for the valve block; `scopeSource` pins what the declaration may
+ * scope on; `reserved` names what will define the name, and stands in place of a
+ * shape — a reserved name admits no declaration at all.
+ */
+export type MechanismShape = {
+    axes: ReadonlySet<Axis>;
+    relations: ReadonlySet<RelationName>;
+    requiresWitness?: true;
+    scopeSource?: 'target.path' | 'command';
+    reserved?: string;
+};
+/**
+ * The blocks {@link deriveShape} reads. A declaration names itself with its `discipline`,
+ * and an entry under `declare` names itself with the entry id instead — the shape is the
+ * same either way, so the derivation takes the blocks rather than the whole document.
+ */
+export type DerivableDeclaration = Pick<AlgebraDeclaration, 'extract' | 'relate' | 'sources' | 'witness'>;
+/** The derived shape of one declaration: what its syntax says it reads and relates. */
+export type DerivedShape = {
+    axes: ReadonlySet<Axis>;
+    relations: ReadonlySet<RelationName>;
+    witness: boolean;
+};
+/** Every name's spec. The `Record` type pins the keys to {@link MECHANISM_NAMES}. */
+export declare const MECHANISM_SHAPES: Record<MechanismName, MechanismShape>;
+/**
+ * Read one declaration's shape from its syntax (pure).
+ *
+ * The axis of a source name is where the name comes from: the fixed name `actor` is the
+ * actor axis and the other six fixed names the change axis, a name the declaration's own
+ * `sources` block binds is the world axis unless the binding is of the transcript kind,
+ * which is the history axis. A name that is neither is refused by
+ * {@link validateMechanism} — skipping it would derive the empty set, which is a subset of
+ * every spec, and an axis-restricted name would load on a typo. The witness block's
+ * `extract` reads a world too, so its source steps count; its `relate` does not, because the
+ * valve's relation is not the judgment's.
+ */
+export declare function deriveShape(declaration: DerivableDeclaration): DerivedShape;
+/**
+ * Check the declaration's `mechanism` against the catalogue (throws on a mismatch).
+ *
+ * The order is the author's repair order: an unknown name first (nothing else is
+ * meaningful without a spec), then the reserved name, then the structural markers, then
+ * the axes and relations the derived shape must stay inside. Membership is subset, not
+ * equality — a name admitting two relations accepts a declaration using one of them.
+ */
+export declare function validateMechanism(declaration: AlgebraDeclaration, location: string): void;