@polydeukes/core 0.4.0 → 0.6.0

package/README.ko.md

@@ -14,7 +14,8 @@
 
 - **약속(covenant) 프로토콜.** 모든 약속이 말하는 계약입니다. 입력은 stdin-JSON(`CovenantInput`, `parseInput`)으로 들어오고 판정은 exit code로 나갑니다. 약속 본체는 `0`(지켜짐)과 `1`(어겨짐, 비차단)만 내고, `1`을 차단인 `2`로 바꾸는 일은 래퍼의 몫입니다. 파싱은 fail-closed라서 판정할 수 없는 입력은 조용히 통과하는 대신 `2`로 끝납니다. 각 도구 호출은 선택적으로 자기 `fileChange` 증거를 싣습니다. 판별 유니온(discriminated union, `create`/`modify`/`delete`, 삭제도 1급)으로 표현되는 에이전트 중립 증거를 어댑터가 각자의 원천(가상 적용, git blob)에서 채우므로, 델타 판정이 디스크를 만지지 않습니다. 귀속이 필요 없는 소비자는 `allFileChanges`로 평면 순회합니다.
 - **ROI 텔레메트리.** append 전용 라인 수집기(`appendRecord`, `readRecords`)와 `gain` 집계(`runGain`)입니다. 모든 패키지가 공유 fail-open 래퍼(`appendRecordFailOpen`)를 거쳐 이 수집기 하나로 기록합니다. 관측은 fail-open이라서 기록 실패가 판정을 바꾸지 않습니다.
-- **config 스키마 v2, 설정은 데이터.** `defineConfig(unknown)`가 파싱된 yml/json 데이터를 검증합니다. 미지의 키는 이 패키지가 소유하는 층위에서 오류로 거부됩니다. 오타가 규율을 조용히 꺼 버리면 안 되기 때문입니다. 어댑터 네임스페이스 안쪽의 내용은 그 어댑터가 검증합니다. `testCmd`는 `{scope}` 템플릿 문자열이고, 호출형 함수로 컴파일되어 돌아옵니다. 같은 계약의 JSON Schema가 `@polydeukes/core/schema.json`으로 배포되며, 검증기와의 동치는 계약 테스트가 강제합니다. 스키마에 `disciplines:`가 추가됐습니다. 사용자가 선언하는 규율(discipline) 항목(`forbid` / `immutable` / `forbidCommand` / `requirePrecedent`, 항목당 술어 정확히 하나)을 순수 데이터로 검증하고, 컴파일은 covenant 패키지가 맡습니다. `requirePrecedent`의 증거 어휘는 `adapters:`와 같은 방식으로 계층이 나뉩니다. 셸 명령은 에이전트를 넘나드는 표면이라 코어가 `command` 키를 전부 검증하고, 나머지 키는 컨테이너 형태만(키가 정확히 하나인 평면 객체) 검증한 뒤 값은 그대로 넘겨 그 어휘를 가진 어댑터가 판정합니다.
+- **config 스키마 v2, 설정은 데이터.** `defineConfig(unknown)`가 파싱된 yml/json 데이터를 검증합니다. 미지의 키는 이 패키지가 소유하는 층위에서 오류로 거부됩니다. 오타가 규율을 조용히 꺼 버리면 안 되기 때문입니다. 어댑터 네임스페이스 안쪽의 내용은 그 어댑터가 검증합니다. `testCmd`는 `{scope}` 템플릿 문자열이고, 호출형 함수로 컴파일되어 돌아옵니다. 같은 계약의 JSON Schema가 `@polydeukes/core/schema.json`으로 배포되며, 검증기와의 동치는 계약 테스트가 강제합니다. 스키마에 `disciplines:`가 추가됐습니다. 사용자가 선언하는 규율(discipline) 항목(항목마다 `declare` 블록 하나, 또는 `draft`)을 순수 데이터로 검증하고, 컴파일은 covenant 패키지가 맡습니다.
+- **대수 선언 스키마(`ALGEBRA-01`).** `validateAlgebraDeclaration(unknown)`이 선언 하나의 형상을 검사하고 데이터 그대로 돌려줍니다. 판정은 `judge = relate ∘ extract`이고 블록은 `scope` · `supply` · `extract` · `relate` · `witness` 다섯입니다. 관계(relation) 자리는 일곱 이름으로, 이진 결합자(combinator) 자리는 셋으로 닫혀 있고, 단항 추출(extract) 어휘는 열려 있습니다. 같은 계약의 JSON Schema가 `@polydeukes/core/algebra-declaration.schema.json`으로 배포되며 동치는 같은 방식의 계약 테스트가 강제합니다. 코어는 형상만 검증합니다. 추출을 실행하지도 관계를 평가하지도 않으며, 엔진(`ALGEBRA-02`)이 서기 전까지 `disciplines:`는 이 블록을 받지 않습니다.
 - **실패 정책 테이블.** 실패 유형별 fail-open과 fail-closed를 테이블 하나(`resolveFailMode`)가 정합니다. "판정 불가"는 언제나 차단입니다.
 - **보호 경로 정규화.** `normalizeProtectedPaths`가 선언된 `protectedPaths` 목록을 디스패처가 대조하는 리터럴 경로 문자열로 다듬습니다(공백 정리, 접두·접미 제거, 중복 제거). 어댑터 설정은 `adapters:` 네임스페이스 맵에 삽니다. 어댑터마다 객체 하나이며, 내용의 검증은 그 어댑터의 몫이고 코어는 그대로 넘깁니다.
 - **정규 대화 기록(canonical transcript) 이음새(seam).** 약속이 세션 이력을 물을 때 쓰는 질의 인터페이스 `CanonicalTranscript`입니다. 서브에이전트 호출, 사용자 메시지, 도구 호출(`findToolCalls`, 이름과 인자 모두 어댑터가 채우는 값)을 묻습니다. 기본값은 noop이라 주입받지 못한 소비자는 "아무 일도 없었다"로 수렴하고, 실제 대화 기록은 어댑터 뒤에 있습니다.

package/README.md

@@ -14,7 +14,8 @@ Every unit below is landed and tested — not blueprint:
 
 - **Covenant protocol** — the contract every covenant (a deterministic, mutually binding promise) speaks: input arrives as stdin-JSON (`CovenantInput`, `parseInput`), verdicts leave as exit codes. A covenant body only ever emits `0` (upheld) or `1` (broken, non-blocking); translating `1` into the blocking `2` is the wrapper's job. Parsing is fail-closed — an unjudgeable payload resolves to `2`, never to a silent pass. Each tool call optionally carries its own `fileChange` — agent-neutral evidence as a discriminated union (`create`/`modify`/`delete`, deletion first-class) adapters fill from their own sources (virtual apply, git blobs) so delta judgments never touch disk; `allFileChanges` flattens it for consumers that need no attribution.
 - **ROI telemetry** — a single append-only, line-oriented collector (`appendRecord`, `readRecords`) plus the `gain` aggregation (`runGain`). Every package writes through this one collector — via `appendRecordFailOpen`, the shared fail-open wrapper. Observation is fail-open: a logging failure never changes a verdict.
-- **Config schema v2 (config as data)** — `defineConfig(unknown)` validates parsed yml/json data. Unknown keys are rejected loudly at the level this package owns (a typo must not silently disable a discipline) while an adapter namespace's contents are its own adapter's to validate, `testCmd` is a `{scope}` template string compiled into a callable, and the matching JSON Schema ships as `@polydeukes/core/schema.json` — held equivalent to the validator by a contract test. The schema now includes `disciplines:` — user-declared discipline entries (`forbid` / `immutable` / `forbidCommand` / `requirePrecedent`, exactly one predicate each) validated here as pure data and compiled by the covenant package. `requirePrecedent`'s evidence vocabulary is layered the way `adapters:` is: the core fully validates the `command` key (a shell command is the agent-crossing surface) and validates only the container shape of every other key — a flat object holding exactly one key — passing the value through verbatim for its owning adapter to judge.
+- **Config schema v2 (config as data)** — `defineConfig(unknown)` validates parsed yml/json data. Unknown keys are rejected loudly at the level this package owns (a typo must not silently disable a discipline) while an adapter namespace's contents are its own adapter's to validate, `testCmd` is a `{scope}` template string compiled into a callable, and the matching JSON Schema ships as `@polydeukes/core/schema.json` — held equivalent to the validator by a contract test. The schema now includes `disciplines:` — user-declared discipline entries (one `declare` block each, or a `draft`) validated here as pure data and compiled by the covenant package.
+- **Algebra declaration schema (`ALGEBRA-01`)** — `validateAlgebraDeclaration(unknown)` checks the shape of one declaration (`judge = relate ∘ extract`: `scope` · `sources` · `supply` · `extract` · `relate` · `witness` blocks — `sources` binds a name to a repo-relative file outside the target, its kind position closed to `file`; a relation position closed to seven names, a binary combinator position closed to three, an open unary extraction vocabulary) and returns it as data. The matching JSON Schema ships as `@polydeukes/core/algebra-declaration.schema.json`, held equivalent by the same kind of contract test. The core validates shape only — it runs no extraction and evaluates no relation; `disciplines:` does not accept these blocks until the engine lands (`ALGEBRA-02`).
 - **Fail policy table** — one table (`resolveFailMode`) decides fail-open vs fail-closed per failure kind; "cannot judge" always means block.
 - **Protected-path normalization** — `normalizeProtectedPaths` turns the declared `protectedPaths` list into the literal path strings the dispatcher matches on (trim, prefix/suffix strip, dedupe). Adapter settings live in the `adapters:` namespace map — one object per adapter, contents validated by that adapter, passed through the core verbatim.
 - **Canonical transcript seam** — `CanonicalTranscript` is the query interface covenants use to ask about session history: subagent invocations, user messages, and tool calls (`findToolCalls`, whose name and args are adapter-supplied values). The default is a noop, so an uninjected consumer converges on "nothing happened"; real transcripts stay behind adapters.

package/dist/algebra.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `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.
+ */
+/** The relation position, closed. This tuple is the single source of the list. */
+export declare const RELATION_NAMES: readonly ['empty', 'nonEmpty', 'equal', 'subset', 'implies', 'ordered', 'unchanged'];
+/** One of the seven relation names — the closed vocabulary of the relation position. */
+export type RelationName = (typeof RELATION_NAMES)[number];
+/** The binary world-combining position, closed. Anything else is a unary step. */
+export declare const BINARY_COMBINATOR_NAMES: readonly ['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 declare const SUPPLY_POLICIES: readonly ['error', 'pass', 'empty'];
+/** The kind position of a `sources` entry, closed. Each entry carries exactly one of them. */
+export declare const SOURCE_KINDS: readonly ['file', 'sidecar', 'transcript'];
+/**
+ * `RelationDecl` — the relation position of one relate entry, one branch per name.
+ *
+ * Every name references extract names declared in the same declaration; `equal` is the
+ * only two-sided branch. The kernel expansion quoted on each branch is a comment — the
+ * engine owns the semantics, this module only the shape.
+ */
+export type RelationDecl = 
+/** `empty` — the extraction produced no element. The primitive. */
+{
+    op: 'empty';
+    of: string;
+}
+/** `nonEmpty` — expands to ¬empty. */
+ | {
+    op: 'nonEmpty';
+    of: string;
+}
+/** `equal` — expands to subset in both directions; the only two-sided relation. */
+ | {
+    op: 'equal';
+    of: [string, string];
+}
+/** `subset` — `of` ⊆ `in`. The primitive. */
+ | {
+    op: 'subset';
+    of: string;
+    in: string;
+}
+/** `implies` — expands to a subset of the two key projections. */
+ | {
+    op: 'implies';
+    of: string;
+    requires: string;
+}
+/** `ordered` — adjacent pairs are monotone; `strict` forbids equal neighbours. */
+ | {
+    op: 'ordered';
+    of: string;
+    strict?: boolean;
+}
+/** `unchanged` — expands to equal over the keys the two states share. */
+ | {
+    op: 'unchanged';
+    of: string;
+};
+/** A binary world combinator — the closed step kind that joins two extractions. */
+export type BinaryStep = {
+    op: 'union';
+    of: [string, string];
+} | {
+    op: 'onlyIn';
+    of: string;
+    notIn: string;
+} | {
+    op: 'intersect';
+    of: [string, string];
+};
+/** Open vocabulary — a name outside the three combinators; its arguments pass through. */
+export type UnaryStep = {
+    op: string;
+    [arg: string]: unknown;
+};
+/** One pipeline step: an open unary step or a closed binary combinator. */
+export type ExtractStep = UnaryStep | BinaryStep;
+/** The `extract` block — named pipelines, each a non-empty step list. */
+export type ExtractBlock = Record<string, ExtractStep[]>;
+/** The `scope` block — which calls a declaration applies to, by constant regex over a source. */
+export type ScopeBlock = {
+    source: string;
+    include?: string[];
+    exclude?: string[];
+    excludeIgnoreCase?: boolean;
+};
+/** One supply policy — the closed value position of a `supply` entry. */
+export type SupplyPolicy = (typeof SUPPLY_POLICIES)[number];
+/**
+ * The `supply` block — per source name, what its absence does: `error` refuses, `pass` skips,
+ * `empty` reads the absence as an empty item list and judges on.
+ */
+export type SupplyBlock = Record<string, SupplyPolicy>;
+/**
+ * The `sources` block — per source name, what outside the target it stands for.
+ *
+ * A `file` path is repo-relative and the supply layer joins it onto the root, which is why an
+ * absolute path and a `..` segment are refused here rather than at read time. A `sidecar`
+ * binding names a channel the surface supplies and a `transcript` binding the session's
+ * conversation history; the location of either is the host's fact, not the declaration's, so
+ * the value is the marker `true` and never a path.
+ */
+export type SourcesBlock = Record<string, {
+    file: string;
+} | {
+    sidecar: true;
+} | {
+    transcript: true;
+}>;
+/**
+ * `RelateEntry` — one (extract name, relation) pairing with its break text.
+ *
+ * Exactly one of `message` and `messageBySide`; the latter only on `equal`, the one relation
+ * with two sides.
+ */
+export type RelateEntry = {
+    id: string;
+    relation: RelationDecl;
+} & ({
+    message: string;
+} | {
+    messageBySide: {
+        left: string;
+        right: string;
+    };
+});
+/**
+ * `WitnessBlock` — the valve standing after the verdict: its own extract pipelines and relate
+ * entries in the same grammar. It sees the body's extract names; the body never sees its.
+ */
+export type WitnessBlock = {
+    extract?: ExtractBlock;
+    relate: RelateEntry[];
+};
+/**
+ * `AlgebraDeclaration` — one judgment written as data, `judge = relate ∘ extract`.
+ *
+ * Pure JSON shape validated by {@link validateAlgebraDeclaration}; `mechanism` names the
+ * catalogue entry whose shape the declaration must match.
+ */
+export type AlgebraDeclaration = {
+    discipline: string;
+    mechanism: string;
+    scope?: ScopeBlock;
+    sources?: SourcesBlock;
+    supply?: SupplyBlock;
+    extract: ExtractBlock;
+    relate: RelateEntry[];
+    witness?: WitnessBlock;
+};
+/** One element for which the relation does not hold. The engine fixes the rest of the shape. */
+export type Witness = {
+    readonly value: unknown;
+};
+/**
+ * An empty list means the relation holds. The order preserves the extraction's input
+ * order — the premise on which two surfaces reach the same verdict.
+ */
+export type Witnesses = readonly Witness[];
+/**
+ * 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 declare function validateAlgebraDeclaration(input: unknown, location?: string): AlgebraDeclaration;

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;
+}