@polydeukes/core 0.6.0 → 0.6.1

package/README.ko.md

@@ -1,33 +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) 항목(항목마다 `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이라 주입받지 못한 소비자는 "아무 일도 없었다"로 수렴하고, 실제 대화 기록은 어댑터 뒤에 있습니다.
-
-## 불변식
-
-- **런타임 의존성 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,33 +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 (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.
-
-## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polydeukes/core",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Alpha.",
   "license": "MIT",
   "repository": {