@polydeukes/core 0.5.0 → 0.6.1

package/README.ko.md

@@ -1,32 +1,50 @@
-<!-- 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
+# `@polydeukes/core`
+
+[English](./README.md) · **한국어**
+
+`core` 패키지는 공통 어휘를 정의합니다. 판정기와 어댑터가 함께 쓰는 약속(covenant)
+프로토콜, 설정 검증, 텔레메트리 도우미, 공유 타입을 제공합니다.
+
+<a id="overview"></a>
+## 개요
+
+공개 계약 심볼은 다음과 같습니다.
+
+- `defineConfig`
+- `parseInput`
+- `verdictToExitCode`
+- `normalizeProtectedPaths`
+- `appendRecordFailOpen`
+- `readRecords`
+- `noopTranscript`
+- `ResolvedConfig`
+- `CovenantInput`
+- `CovenantVerdict`
+- `EXIT_UPHOLD`
+- `EXIT_BREAK_NON_BLOCKING`
+- `EXIT_BREAK_BLOCKING`
+
+<a id="examples"></a>
+## 예제
+
+```ts
+import { defineConfig, parseInput } from '@polydeukes/core';
+
+const config = defineConfig({
+  languages: {
+    typescript: {
+      productionGlob: 'packages/*/src/**/*.ts',
+      testCmd: 'pnpm --filter {scope} test',
+    },
+  },
+});
+
+const payload = parseInput('{"toolCalls":[],"subagentSpawns":[],"userMessages":[]}');
+```
+
+<a id="see-also"></a>
+## 같이 보기
+
+- [`@polydeukes/core` 패키지 레퍼런스](../../docs/reference/packages/core.ko.md)
+- [`설정 레퍼런스`](../../docs/reference/configuration/index.ko.md)
+- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.ko.md)

package/README.md

@@ -1,32 +1,50 @@
-<!-- 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
+# `@polydeukes/core`
+
+**English** · [한국어](./README.ko.md)
+
+The core package is the vocabulary layer. It exports the covenant protocol, config validation,
+telemetry helpers, and shared types used by the judge and adapters.
+
+<a id="overview"></a>
+## Overview
+
+Public contract symbols include:
+
+- `defineConfig`
+- `parseInput`
+- `verdictToExitCode`
+- `normalizeProtectedPaths`
+- `appendRecordFailOpen`
+- `readRecords`
+- `noopTranscript`
+- `ResolvedConfig`
+- `CovenantInput`
+- `CovenantVerdict`
+- `EXIT_UPHOLD`
+- `EXIT_BREAK_NON_BLOCKING`
+- `EXIT_BREAK_BLOCKING`
+
+<a id="examples"></a>
+## Examples
+
+```ts
+import { defineConfig, parseInput } from '@polydeukes/core';
+
+const config = defineConfig({
+  languages: {
+    typescript: {
+      productionGlob: 'packages/*/src/**/*.ts',
+      testCmd: 'pnpm --filter {scope} test',
+    },
+  },
+});
+
+const payload = parseInput('{"toolCalls":[],"subagentSpawns":[],"userMessages":[]}');
+```
+
+<a id="see-also"></a>
+## See also
+
+- [`@polydeukes/core` package reference](../../docs/reference/packages/core.md)
+- [`Configuration reference`](../../docs/reference/configuration/index.md)
+- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.md)

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;