@polydeukes/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyung Soo Seung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,32 @@
+<!-- markdownlint-disable MD013 -- npm renders this page; its prose is authored as single-line paragraphs. -->
+
+# @polydeukes/core
+
+**한국어** · [English](./README.md)
+
+> Polydeukes의 얇은 코어입니다. 도메인과 에이전트를 모르는 최소 기반 위에, AI 코딩 파트너와 함께 쓰는 규율(discipline) 프레임워크가 올라갑니다.
+
+**알파(alpha) 단계입니다.** 마일스톤 사이에 API가 바뀔 수 있습니다. 여기 구현되지 않은 부분은 저장소의 설계 문서가 기준입니다.
+
+## 여기 담긴 것
+
+아래 유닛은 청사진이 아니라 전부 구현되고 테스트된 상태입니다.
+
+- **약속(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` 키를 전부 검증하고, 나머지 키는 컨테이너 형태만(키가 정확히 하나인 평면 객체) 검증한 뒤 값은 그대로 넘겨 그 어휘를 가진 어댑터가 판정합니다.
+- **실패 정책 테이블.** 실패 유형별 fail-open과 fail-closed를 테이블 하나(`resolveFailMode`)가 정합니다. "판정 불가"는 언제나 차단입니다.
+- **보호 경로 정규화.** `normalizeProtectedPaths`가 선언된 `protectedPaths` 목록을 디스패처가 대조하는 리터럴 경로 문자열로 다듬습니다(공백 정리, 접두·접미 제거, 중복 제거). 어댑터 설정은 `adapters:` 네임스페이스 맵에 삽니다. 어댑터마다 객체 하나이며, 내용의 검증은 그 어댑터의 몫이고 코어는 그대로 넘깁니다.
+- **정규 대화 기록(canonical transcript) 이음새(seam).** 약속이 세션 이력을 물을 때 쓰는 질의 인터페이스 `CanonicalTranscript`입니다. 서브에이전트 호출, 사용자 메시지, 도구 호출(`findToolCalls`, 이름과 인자 모두 어댑터가 채우는 값)을 묻습니다. 기본값은 noop이라 주입받지 못한 소비자는 "아무 일도 없었다"로 수렴하고, 실제 대화 기록은 어댑터 뒤에 있습니다.
+
+## 불변식
+
+- **런타임 의존성 0.** 검증은 직접 작성했고, 배포되는 JSON Schema는 소스가 읽지 않는 별도 산출물입니다.
+- **에이전트·도구·언어 리터럴 없음.** 편집 도구의 동사나 테스트 러너의 이름은 config와 어댑터가 채우는 값이지, 이 패키지의 어휘가 아닙니다. 검증 기준의 grep 게이트가 이를 지킵니다.
+- **의존은 단방향.** 다른 `@polydeukes/*` 패키지는 core에만 의존하고, core는 그 무엇에도 의존하지 않습니다.
+
+아키텍처 청사진과 설계 근거는 [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,32 @@
+<!-- markdownlint-disable MD013 -- npm renders this page; its prose is authored as single-line paragraphs. -->
+
+# @polydeukes/core
+
+**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/core/README.ko.md)
+
+> The thin, domain- and agent-agnostic core of Polydeukes — a development *discipline* framework for building alongside an AI coding partner.
+
+**Alpha.** The API surface may move between milestones; for anything not landed here, the repository's design docs are the source of truth.
+
+## What lives here
+
+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.
+- **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.
+
+## Invariants
+
+- **Zero runtime dependencies.** Validation is hand-rolled; the published JSON Schema is a sibling artifact the source never reads.
+- **No agent, tool, or language literals.** Editor tool verbs and test-runner names are *values* supplied by configs and adapters, never part of this package's vocabulary — grep gates in the acceptance criteria keep it that way.
+- **One-way dependencies.** Every other `@polydeukes/*` package depends only on `core`; core depends on none of them.
+
+See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture blueprint and design rationale.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Config schema v2 + `defineConfig()` validator — config as data (CONFIG-04).
+ *
+ * This is the single settings surface the three areas share (covenant's `protectedPaths`,
+ * ledger's `testCmd`, memory's ticket pattern all reference this shape). Since schema v2 the
+ * input is pure JSON-representable data: `testCmd` is a `{scope}` template string, and
+ * `defineConfig` is the runtime validator for parsed unknown data (the CONFIG-03 loader feeds
+ * it values the compiler never saw). It stays a pure function — zero file I/O, zero runtime
+ * dependencies (hand-rolled validation; the published JSON Schema is a sibling artifact the
+ * source never reads).
+ */
+/** Conventional default telemetry log path (PRD §4.3) — local-only observation data. */
+export declare const DEFAULT_TELEMETRY_LOG_PATH = ".polydeukes/roi.log";
+/**
+ * `LanguageProfile` — the unit of the language axis (PRD §4.1).
+ *
+ * `testCmd` is a shell command template: every literal `{scope}` token is substituted at
+ * resolve time, and the core only carries the resulting string — it never interprets it.
+ */
+export type LanguageProfile = {
+    /** what counts as production source for this language — required */
+    productionGlob: string | string[];
+    /**
+     * shell command template that verifies the given scope — `{scope}` placeholders are
+     * substituted at resolve time; the core never interprets the resulting string
+     */
+    testCmd: string;
+};
+/**
+ * `DisciplineForbid` — the delta-family predicate value (COVENANT-10 §4.1).
+ *
+ * The string shorthand is equivalent to `{ added }`; `removed`/`present` directions are
+ * deferred (COVENANT-12) and rejected by validation.
+ */
+export type DisciplineForbid = string | {
+    added: string;
+};
+/**
+ * `DisciplineEntry` — one user-declared discipline (COVENANT-10 §4.1). Pure JSON data.
+ *
+ * Exactly one predicate key (`forbid` | `immutable` | `forbidCommand` |
+ * `requirePrecedent`) per entry; `in`/`except` scope the delta and context families.
+ * Compilation is the covenant package's job — the core validates compilability of regex
+ * strings but never executes them.
+ */
+export type DisciplineEntry = {
+    /** unique handle — telemetry label and verdict reason prefix */
+    id: string;
+    /** prose rationale, documentation only — never judged */
+    why?: string;
+    /** delta/context-family scope: glob(s) the file path must match (absent = every file change) */
+    in?: string | string[];
+    /** delta/context-family scope: glob(s) excluded after `in` */
+    except?: string | string[];
+    /** delta family — string shorthand = { added } */
+    forbid?: DisciplineForbid;
+    /** path family — its own glob is the scope */
+    immutable?: string | string[];
+    /** command family — regex over shell command strings */
+    forbidCommand?: string;
+    /** context-family trigger: added-direction delta regex (absent = every in-scope change) */
+    when?: string;
+    /**
+     * context family — the session evidence one edit requires beforehand. Exactly one
+     * evidence key. The core owns and fully validates `command`; every other key is
+     * adapter vocabulary whose value passes through verbatim (CONFIG-07 layering).
+     */
+    requirePrecedent?: Record<string, unknown>;
+};
+/**
+ * `PolydeukesConfig` — the input shape a user writes (PRD §4.1). JSON-serializable data.
+ *
+ * Language keys (`typescript`, `python`, …) are user *values*, not the core's vocabulary —
+ * no language or tool literal appears in the core source.
+ */
+export type PolydeukesConfig = {
+    /** IDE schema reference (CONFIG-03) — accepted and ignored, never part of the resolution */
+    $schema?: string;
+    /** language axis, first-class. keys are user values ('typescript', 'python', …) */
+    languages: Record<string, LanguageProfile>;
+    /** raw protected path patterns — normalization is CONFIG-02's job */
+    protectedPaths?: string[];
+    /**
+     * adapter namespaces (CONFIG-07) — keys are ecosystem values (never validated), each
+     * value is that adapter's own settings object, passed through verbatim (the vocabulary
+     * belongs to the adapter, whose own validator judges the contents)
+     */
+    adapters?: Record<string, Record<string, unknown>>;
+    telemetry?: {
+        /** conventional default applies when omitted (§4.3) */
+        logPath?: string;
+    };
+    /** user-declared disciplines — validated here, compiled by the covenant package */
+    disciplines?: DisciplineEntry[];
+    /**
+     * TTL witness values for the covenant valve seam (CONFIG-05) — consumed at
+     * assembly time, validated here
+     */
+    witness?: {
+        /**
+         * the agreed phrase a human types alone on a message's first line — quoting it
+         * mid-sentence is a mention, not an invocation (COVENANT-15). Non-empty after
+         * trimming; the value itself is free (provenance, not secrecy, is the defence)
+         */
+        token: string;
+        /** validity window in minutes from the user message's timestamp — finite and > 0 */
+        ttlMinutes: number;
+    };
+};
+/**
+ * `ResolvedLanguageProfile` — a {@link LanguageProfile} with its template compiled.
+ *
+ * Consumers keep the callable shape (`testCmd(scope)`), identical to schema v1 (LEDGER-05).
+ */
+export type ResolvedLanguageProfile = {
+    productionGlob: string | string[];
+    /** compiled from the template — consumers keep the callable shape (LEDGER-05) */
+    testCmd: (scope: string) => string;
+};
+/**
+ * `ResolvedConfig` — a validated config with defaults filled and templates compiled.
+ *
+ * Consumers (covenant/ledger/memory) read `telemetry.logPath` without optional handling.
+ */
+export type ResolvedConfig = {
+    languages: Record<string, ResolvedLanguageProfile>;
+    protectedPaths?: string[];
+    /** validated adapter namespaces, passed through verbatim (absent stays absent) */
+    adapters?: Record<string, Record<string, unknown>>;
+    telemetry: {
+        logPath: string;
+    };
+    /** validated discipline data, passed through verbatim (absent stays absent) */
+    disciplines?: DisciplineEntry[];
+    /** validated witness data, passed through verbatim (absent stays absent) */
+    witness?: {
+        token: string;
+        ttlMinutes: number;
+    };
+};
+/**
+ * `ConfigValidationError` — raised when a config fails structural validation (PRD §4.3).
+ *
+ * The message names the offending field path so the developer sees exactly what is wrong.
+ * This throw is a developer-time error (config authoring), a different axis from the
+ * covenant runtime's fail-closed exit code — a bad config should fail loud and early.
+ */
+export declare class ConfigValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate parsed unknown data as a {@link PolydeukesConfig} and return a
+ * {@link ResolvedConfig} with defaults filled and templates compiled (PRD §4.3).
+ * Pure — no file I/O.
+ *
+ * Throws {@link ConfigValidationError} (naming the offending field path) when the top level
+ * is not a plain object, any object level carries an unknown key, `languages` is
+ * missing/empty, any language's `productionGlob` is missing/empty, any `testCmd` is not a
+ * non-empty string template, `telemetry.logPath` is not a string, `protectedPaths` carries a
+ * non-string element, or `adapters` is not a map of plain-object namespaces.
+ */
+export declare function defineConfig(config: unknown): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,318 @@
+/**
+ * Config schema v2 + `defineConfig()` validator — config as data (CONFIG-04).
+ *
+ * This is the single settings surface the three areas share (covenant's `protectedPaths`,
+ * ledger's `testCmd`, memory's ticket pattern all reference this shape). Since schema v2 the
+ * input is pure JSON-representable data: `testCmd` is a `{scope}` template string, and
+ * `defineConfig` is the runtime validator for parsed unknown data (the CONFIG-03 loader feeds
+ * it values the compiler never saw). It stays a pure function — zero file I/O, zero runtime
+ * dependencies (hand-rolled validation; the published JSON Schema is a sibling artifact the
+ * source never reads).
+ */
+import { isPlainObject } from './is-plain-object.js';
+/** Conventional default telemetry log path (PRD §4.3) — local-only observation data. */
+export const DEFAULT_TELEMETRY_LOG_PATH = '.polydeukes/roi.log';
+/**
+ * `ConfigValidationError` — raised when a config fails structural validation (PRD §4.3).
+ *
+ * The message names the offending field path so the developer sees exactly what is wrong.
+ * This throw is a developer-time error (config authoring), a different axis from the
+ * covenant runtime's fail-closed exit code — a bad config should fail loud and early.
+ */
+export class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+/** The exact key vocabulary of each object level — anything else is a typo, rejected loudly. */
+const TOP_LEVEL_KEYS = new Set([
+    '$schema',
+    'languages',
+    'protectedPaths',
+    'adapters',
+    'telemetry',
+    'disciplines',
+    'witness',
+]);
+const PROFILE_KEYS = new Set(['productionGlob', 'testCmd']);
+const TELEMETRY_KEYS = new Set(['logPath']);
+const WITNESS_KEYS = new Set(['token', 'ttlMinutes']);
+const DISCIPLINE_KEYS = new Set([
+    'id',
+    'why',
+    'in',
+    'except',
+    'forbid',
+    'immutable',
+    'forbidCommand',
+    'when',
+    'requirePrecedent',
+]);
+const PREDICATE_KEYS = ['forbid', 'immutable', 'forbidCommand', 'requirePrecedent'];
+/** Predicate families that `in`/`except` may scope — delta and context (COVENANT-13 §4.1). */
+const SCOPED_PREDICATE_KEYS = new Set(['forbid', 'requirePrecedent']);
+/** Throw on the first key outside the allowed vocabulary, naming the key and its location. */
+function rejectUnknownKeys(record, allowed, location) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw new ConfigValidationError(`unknown key '${key}' in ${location}`);
+        }
+    }
+}
+/** True when the value is an array whose every element is a string. */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+/** True when the glob value is a present, non-empty string or a non-empty array of non-empty strings. */
+function isValidGlob(glob) {
+    if (typeof glob === 'string') {
+        return glob.length > 0;
+    }
+    if (Array.isArray(glob)) {
+        return glob.length > 0 && glob.every((entry) => typeof entry === 'string' && entry.length > 0);
+    }
+    return false;
+}
+/**
+ * Compile a `{scope}` template into the callable consumers use (PRD §4.2).
+ *
+ * Exactly the literal token `{scope}` is substituted, at every occurrence (`replaceAll`
+ * semantics). Other braces (`${VAR}`, `{a,b}`, `awk '{print}'`) are the shell's own
+ * vocabulary and pass through untouched.
+ */
+function compileTestCmd(template) {
+    // Callback form: a string replacement would interpret `$`-patterns ($$, $&, $`, $')
+    // via GetSubstitution, breaking literal insertion for scopes containing `$`.
+    return (scope) => template.replaceAll('{scope}', () => scope);
+}
+/** Throw unless the pattern string compiles with `new RegExp` — compilability only, never run. */
+function rejectUncompilableRegex(pattern, location) {
+    try {
+        new RegExp(pattern);
+    }
+    catch {
+        throw new ConfigValidationError(`${location} must be a compilable regular expression`);
+    }
+}
+/**
+ * Validate a context-family `requirePrecedent` value (COVENANT-13 §4.1).
+ *
+ * Evidence vocabulary is layered: the container (a flat object holding exactly one
+ * evidence key) is the core's, and so is the `command` key — a shell command is the
+ * agent-crossing surface, fully validated here. Every other key belongs to an adapter,
+ * whose own validator judges the value; the core passes it through verbatim and never
+ * inspects it (CONFIG-07 layering). An unrecognized evidence key fails closed at
+ * assembly time, not here.
+ */
+function validateRequirePrecedent(evidence, location) {
+    if (!isPlainObject(evidence)) {
+        throw new ConfigValidationError(`${location} requirePrecedent must be an object`);
+    }
+    const keys = Object.keys(evidence);
+    if (keys.length !== 1) {
+        throw new ConfigValidationError(`${location} requirePrecedent must have exactly one evidence key`);
+    }
+    if (keys[0] === 'command') {
+        const command = evidence.command;
+        if (typeof command !== 'string' || command.length === 0) {
+            throw new ConfigValidationError(`${location} requirePrecedent.command must be a non-empty string pattern`);
+        }
+        rejectUncompilableRegex(command, `${location} requirePrecedent.command`);
+    }
+}
+/**
+ * Validate the `disciplines` array (COVENANT-10 §4.1). Throws {@link ConfigValidationError}
+ * naming the offending entry/key; the validated data passes through verbatim.
+ */
+function validateDisciplines(disciplines) {
+    if (!Array.isArray(disciplines)) {
+        throw new ConfigValidationError('disciplines must be an array');
+    }
+    const seenIds = new Set();
+    disciplines.forEach((entry, index) => {
+        if (!isPlainObject(entry)) {
+            throw new ConfigValidationError(`disciplines[${index}] must be an object`);
+        }
+        if (typeof entry.id !== 'string' || entry.id.length === 0) {
+            throw new ConfigValidationError(`disciplines[${index}].id must be a non-empty string`);
+        }
+        const location = `disciplines[${index}] ('${entry.id}')`;
+        if (seenIds.has(entry.id)) {
+            throw new ConfigValidationError(`${location} duplicates the id of an earlier entry`);
+        }
+        seenIds.add(entry.id);
+        rejectUnknownKeys(entry, DISCIPLINE_KEYS, location);
+        if (entry.why !== undefined && typeof entry.why !== 'string') {
+            throw new ConfigValidationError(`${location} why must be a string`);
+        }
+        const predicates = PREDICATE_KEYS.filter((key) => entry[key] !== undefined);
+        if (predicates.length !== 1) {
+            throw new ConfigValidationError(`${location} must have exactly one predicate key ` +
+                `(forbid | immutable | forbidCommand | requirePrecedent)`);
+        }
+        const predicate = predicates[0];
+        if (!SCOPED_PREDICATE_KEYS.has(predicate) &&
+            (entry.in !== undefined || entry.except !== undefined)) {
+            throw new ConfigValidationError(`${location} allows in/except only on a forbid or requirePrecedent entry`);
+        }
+        // `when` is the context family's trigger; on any other family it would be dead data
+        // implying a trigger that is never applied.
+        if (entry.when !== undefined && predicate !== 'requirePrecedent') {
+            throw new ConfigValidationError(`${location} allows when only on a requirePrecedent entry`);
+        }
+        if (entry.in !== undefined && !isValidGlob(entry.in)) {
+            throw new ConfigValidationError(`${location} in must be a non-empty glob or glob array`);
+        }
+        if (entry.except !== undefined && !isValidGlob(entry.except)) {
+            throw new ConfigValidationError(`${location} except must be a non-empty glob or glob array`);
+        }
+        if (predicate === 'forbid') {
+            const forbid = entry.forbid;
+            if (typeof forbid === 'string') {
+                rejectUncompilableRegex(forbid, `${location} forbid`);
+            }
+            else if (isPlainObject(forbid)) {
+                // Only the { added } direction exists before COVENANT-12.
+                const keys = Object.keys(forbid);
+                if (keys.length !== 1 || keys[0] !== 'added' || typeof forbid.added !== 'string') {
+                    throw new ConfigValidationError(`${location} forbid object must have exactly one key 'added' with a string pattern`);
+                }
+                rejectUncompilableRegex(forbid.added, `${location} forbid.added`);
+            }
+            else {
+                throw new ConfigValidationError(`${location} forbid must be a string pattern or an { added } object`);
+            }
+        }
+        else if (predicate === 'immutable') {
+            if (!isValidGlob(entry.immutable)) {
+                throw new ConfigValidationError(`${location} immutable must be a non-empty glob or glob array`);
+            }
+        }
+        else if (predicate === 'forbidCommand') {
+            if (typeof entry.forbidCommand !== 'string') {
+                throw new ConfigValidationError(`${location} forbidCommand must be a string pattern`);
+            }
+            rejectUncompilableRegex(entry.forbidCommand, `${location} forbidCommand`);
+        }
+        else {
+            if (entry.when !== undefined) {
+                if (typeof entry.when !== 'string') {
+                    throw new ConfigValidationError(`${location} when must be a string pattern`);
+                }
+                if (entry.when.length === 0) {
+                    // An empty pattern matches at every position, so the trigger would fire on any
+                    // file that merely grows — reject it like every sibling pattern field.
+                    throw new ConfigValidationError(`${location} when must be a non-empty string pattern`);
+                }
+                rejectUncompilableRegex(entry.when, `${location} when`);
+            }
+            validateRequirePrecedent(entry.requirePrecedent, location);
+        }
+    });
+    return disciplines;
+}
+/**
+ * Validate parsed unknown data as a {@link PolydeukesConfig} and return a
+ * {@link ResolvedConfig} with defaults filled and templates compiled (PRD §4.3).
+ * Pure — no file I/O.
+ *
+ * Throws {@link ConfigValidationError} (naming the offending field path) when the top level
+ * is not a plain object, any object level carries an unknown key, `languages` is
+ * missing/empty, any language's `productionGlob` is missing/empty, any `testCmd` is not a
+ * non-empty string template, `telemetry.logPath` is not a string, `protectedPaths` carries a
+ * non-string element, or `adapters` is not a map of plain-object namespaces.
+ */
+export function defineConfig(config) {
+    if (!isPlainObject(config)) {
+        throw new ConfigValidationError('config must be a plain object');
+    }
+    rejectUnknownKeys(config, TOP_LEVEL_KEYS, 'config');
+    // `$schema` is an IDE schema reference (CONFIG-03): accepted, type-checked, and
+    // ignored — it never appears in the resolution output.
+    if (config.$schema !== undefined && typeof config.$schema !== 'string') {
+        throw new ConfigValidationError('$schema must be a string');
+    }
+    const languages = config.languages;
+    if (!isPlainObject(languages) || Object.keys(languages).length === 0) {
+        throw new ConfigValidationError('languages must be a non-empty object');
+    }
+    const resolvedLanguages = {};
+    for (const [key, profile] of Object.entries(languages)) {
+        if (!isPlainObject(profile)) {
+            throw new ConfigValidationError(`languages.${key} must be an object`);
+        }
+        rejectUnknownKeys(profile, PROFILE_KEYS, `languages.${key}`);
+        if (!isValidGlob(profile.productionGlob)) {
+            throw new ConfigValidationError(`languages.${key}.productionGlob must be a non-empty string or non-empty array of non-empty strings`);
+        }
+        if (typeof profile.testCmd === 'function') {
+            throw new ConfigValidationError(`languages.${key}.testCmd must be a string template (config-as-data v2) — ` +
+                `replace the function with e.g. 'your-runner {scope}'`);
+        }
+        if (typeof profile.testCmd !== 'string' || profile.testCmd.length === 0) {
+            throw new ConfigValidationError(`languages.${key}.testCmd must be a non-empty string template`);
+        }
+        resolvedLanguages[key] = {
+            productionGlob: profile.productionGlob,
+            testCmd: compileTestCmd(profile.testCmd),
+        };
+    }
+    if (config.protectedPaths !== undefined && !isStringArray(config.protectedPaths)) {
+        throw new ConfigValidationError('protectedPaths must be an array of strings');
+    }
+    let adapters;
+    if (config.adapters !== undefined) {
+        // Array first: the removed directory-list form deserves a migration hint, not a
+        // generic type error — and an EMPTY array must land here too, never pass as a map.
+        if (Array.isArray(config.adapters) || !isPlainObject(config.adapters)) {
+            throw new ConfigValidationError('adapters must be an object map of adapter namespaces — the directory-list form ' +
+                'was removed; move directories to protectedPaths');
+        }
+        for (const [name, namespace] of Object.entries(config.adapters)) {
+            if (!isPlainObject(namespace)) {
+                throw new ConfigValidationError(`adapters.${name} must be an object`);
+            }
+        }
+        adapters = config.adapters;
+    }
+    const disciplines = config.disciplines !== undefined ? validateDisciplines(config.disciplines) : undefined;
+    let logPath;
+    if (config.telemetry !== undefined) {
+        if (!isPlainObject(config.telemetry)) {
+            throw new ConfigValidationError('telemetry must be an object');
+        }
+        rejectUnknownKeys(config.telemetry, TELEMETRY_KEYS, 'telemetry');
+        if (config.telemetry.logPath !== undefined) {
+            if (typeof config.telemetry.logPath !== 'string') {
+                throw new ConfigValidationError('telemetry.logPath must be a string');
+            }
+            logPath = config.telemetry.logPath;
+        }
+    }
+    let witness;
+    if (config.witness !== undefined) {
+        if (!isPlainObject(config.witness)) {
+            throw new ConfigValidationError('witness must be an object');
+        }
+        rejectUnknownKeys(config.witness, WITNESS_KEYS, 'witness');
+        const { token, ttlMinutes } = config.witness;
+        if (typeof token !== 'string' || token.trim().length === 0) {
+            throw new ConfigValidationError('witness.token must be a non-empty string after trimming');
+        }
+        if (typeof ttlMinutes !== 'number' || !(Number.isFinite(ttlMinutes) && ttlMinutes > 0)) {
+            throw new ConfigValidationError('witness.ttlMinutes must be a finite number greater than 0');
+        }
+        witness = { token, ttlMinutes };
+    }
+    return {
+        languages: resolvedLanguages,
+        ...(config.protectedPaths !== undefined && { protectedPaths: config.protectedPaths }),
+        ...(adapters !== undefined && { adapters }),
+        telemetry: {
+            logPath: logPath ?? DEFAULT_TELEMETRY_LOG_PATH,
+        },
+        ...(disciplines !== undefined && { disciplines }),
+        ...(witness !== undefined && { witness }),
+    };
+}

package/dist/fail-policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * fail-policy — the failure-kind → fail-mode policy table (CORE-03).
+ *
+ * Pure and total: classifying a failure and mapping it to an exit code never
+ * performs I/O and never throws. The single source of truth for "which failures
+ * block and which pass through" lives here, not scattered across call sites.
+ */
+/** How a failure resolves: 'open' passes the call through, 'closed' blocks it. */
+export type FailMode = 'open' | 'closed';
+/**
+ * The registered failure kinds (PRD §4.1). Gate-integrity failures
+ * (evidence-absence / input-parse / undecidable-structure) fail closed;
+ * observability failures fail open so measurement loss never holds work hostage.
+ */
+export type FailureKind = 'evidence-absence' | 'input-parse' | 'undecidable-structure' | 'observability';
+/**
+ * Resolve a failure kind to its {@link FailMode} via the policy table.
+ *
+ * fail-closed default (PRD §5.2): any unregistered kind — including '' and
+ * prototype-pollution keys — resolves to 'closed'. "Cannot classify" means
+ * block. Pure and total (PRD §7): never throws, no I/O, no logging.
+ */
+export declare function resolveFailMode(kind: string): FailMode;
+/**
+ * Map a {@link FailMode} to the covenant protocol's exit code (PRD §4.2):
+ * 'open' → {@link EXIT_UPHOLD}, 'closed' → {@link EXIT_BREAK_BLOCKING}.
+ * Reuses CORE-01's constants — no independent numeric literals here.
+ */
+export declare function failModeToExitCode(mode: FailMode): 0 | 2;

package/dist/fail-policy.js

@@ -0,0 +1,37 @@
+/**
+ * fail-policy — the failure-kind → fail-mode policy table (CORE-03).
+ *
+ * Pure and total: classifying a failure and mapping it to an exit code never
+ * performs I/O and never throws. The single source of truth for "which failures
+ * block and which pass through" lives here, not scattered across call sites.
+ */
+import { EXIT_BREAK_BLOCKING, EXIT_UPHOLD } from './index.js';
+/**
+ * Policy table (PRD §4.1). Null-prototype so lookups can never reach
+ * Object.prototype members ('__proto__', 'toString', …) — those must resolve
+ * to the fail-closed default, not to an inherited function.
+ */
+const FAIL_POLICY = Object.assign(Object.create(null), {
+    'evidence-absence': 'closed',
+    'input-parse': 'closed',
+    'undecidable-structure': 'closed',
+    observability: 'open',
+});
+/**
+ * Resolve a failure kind to its {@link FailMode} via the policy table.
+ *
+ * fail-closed default (PRD §5.2): any unregistered kind — including '' and
+ * prototype-pollution keys — resolves to 'closed'. "Cannot classify" means
+ * block. Pure and total (PRD §7): never throws, no I/O, no logging.
+ */
+export function resolveFailMode(kind) {
+    return FAIL_POLICY[kind] ?? 'closed';
+}
+/**
+ * Map a {@link FailMode} to the covenant protocol's exit code (PRD §4.2):
+ * 'open' → {@link EXIT_UPHOLD}, 'closed' → {@link EXIT_BREAK_BLOCKING}.
+ * Reuses CORE-01's constants — no independent numeric literals here.
+ */
+export function failModeToExitCode(mode) {
+    return mode === 'open' ? EXIT_UPHOLD : EXIT_BREAK_BLOCKING;
+}