@polydeukes/core 0.6.0 → 0.7.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)
+- [판정기(`covenant` 모듈)](../../docs/reference/packages/polydeukes.ko.md#covenant-module)

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)
+- [The judge (`covenant` module)](../../docs/reference/packages/polydeukes.md#covenant-module)

package/dist/algebra.d.ts

@@ -172,3 +172,12 @@ export type Witnesses = readonly Witness[];
  * `location`, so a caller validating many declarations sees which one failed.
  */
 export declare function validateAlgebraDeclaration(input: unknown, location?: string): AlgebraDeclaration;
+/**
+ * `DeclarationChannel` — one evidence channel a declaration binds.
+ *
+ * `transcript` · `channel` · `command` · `actor` are what a live call carries and `changes`
+ * is what a finished change set carries, so the set a declaration reads decides which
+ * surfaces can observe it at all.
+ */
+export type DeclarationChannel = 'transcript' | 'channel' | 'command' | 'actor' | 'changes';
+export declare function declarationChannels(body: Omit<AlgebraDeclaration, 'discipline'>): DeclarationChannel[];

package/dist/algebra.js

@@ -5,7 +5,7 @@
  * 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 { sourceNames, 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';
@@ -436,3 +436,34 @@ export function validateAlgebraDeclaration(input, location = 'declaration') {
     validateMechanism(declaration, location);
     return declaration;
 }
+/** The fixed order of a derived channel list. */
+const DECLARATION_CHANNELS = [
+    'transcript',
+    'channel',
+    'command',
+    'actor',
+    'changes',
+];
+export function declarationChannels(body) {
+    const found = new Set();
+    const sources = isPlainObject(body.sources) ? body.sources : {};
+    for (const binding of Object.values(sources)) {
+        if (!isPlainObject(binding))
+            continue;
+        if ('transcript' in binding)
+            found.add('transcript');
+        if ('sidecar' in binding)
+            found.add('channel');
+    }
+    if (isPlainObject(body.scope) && body.scope.source === 'command')
+        found.add('command');
+    for (const name of sourceNames(body)) {
+        if (name === 'command')
+            found.add('command');
+        if (name === 'actor')
+            found.add('actor');
+        if (name === 'changes')
+            found.add('changes');
+    }
+    return DECLARATION_CHANNELS.filter((channel) => found.has(channel));
+}

package/dist/catalogue.d.ts

@@ -45,6 +45,13 @@ export type DerivedShape = {
 };
 /** Every name's spec. The `Record` type pins the keys to {@link MECHANISM_NAMES}. */
 export declare const MECHANISM_SHAPES: Record<MechanismName, MechanismShape>;
+/** Every source name the body and the valve read, in declaration order. */
+export declare function sourceNames(declaration: {
+    extract?: unknown;
+    witness?: {
+        extract?: unknown;
+    } | undefined;
+}): string[];
 /**
  * Read one declaration's shape from its syntax (pure).
  *

package/dist/catalogue.js

@@ -101,12 +101,19 @@ function quotedList(names) {
 function isTranscriptSource(binding) {
     return isPlainObject(binding) && binding.transcript === true;
 }
-/** The source names one extract block's `source` steps name, in declaration order. */
+/**
+ * The source names one extract block's `source` steps name, in declaration order.
+ *
+ * Tolerant of an unvalidated block: a pipeline that is not a list, or a step that is not an
+ * object, names nothing here and is refused by the grammar validator with its location.
+ */
 function sourceNamesOf(extract) {
-    if (extract === undefined)
+    if (!isPlainObject(extract))
         return [];
     const names = [];
     for (const steps of Object.values(extract)) {
+        if (!Array.isArray(steps))
+            continue;
         for (const step of steps) {
             if (isPlainObject(step) && step.op === 'source' && typeof step.of === 'string') {
                 names.push(step.of);
@@ -116,8 +123,9 @@ function sourceNamesOf(extract) {
     return names;
 }
 /** Every source name the body and the valve read, in declaration order. */
-function sourceNames(declaration) {
-    return [...sourceNamesOf(declaration.extract), ...sourceNamesOf(declaration.witness?.extract)];
+export function sourceNames(declaration) {
+    const witness = isPlainObject(declaration.witness) ? declaration.witness : undefined;
+    return [...sourceNamesOf(declaration.extract), ...sourceNamesOf(witness?.extract)];
 }
 /**
  * Read one declaration's shape from its syntax (pure).

package/dist/config.d.ts

@@ -95,8 +95,18 @@ export type PolydeukesConfig = {
         /** conventional default applies when omitted */
         logPath?: string;
     };
-    /** user-declared disciplines — validated here, compiled by the covenant package */
+    /**
+     * user-declared disciplines both surfaces observe — every entry whose declaration binds
+     * no evidence channel, plus the drafts. Validated here, compiled by the covenant package
+     */
     disciplines?: (DisciplineEntry | DisciplineDraft)[];
+    /**
+     * disciplines only the session surface observes — every entry binding at least one of
+     * `transcript` · `channel` · `command` · `actor` and never `changes`
+     */
+    sessionDisciplines?: DisciplineEntry[];
+    /** disciplines only the change-set surface observes — every entry binding `changes` */
+    changeSetDisciplines?: DisciplineEntry[];
     /**
      * TTL witness values for the covenant valve seam — consumed at assembly time,
      * validated here
@@ -141,6 +151,10 @@ export type ResolvedConfig = {
      * declared a `disciplines` array, holding exactly its judged entries in order.
      */
     disciplines?: DisciplineEntry[];
+    /** validated session-surface entries, present whenever the input declared the list */
+    sessionDisciplines?: DisciplineEntry[];
+    /** validated change-set-surface entries, present whenever the input declared the list */
+    changeSetDisciplines?: DisciplineEntry[];
     /** validated drafts in declaration order (absent when the input carries none) */
     drafts?: DisciplineDraft[];
     /** validated witness data, passed through verbatim (absent stays absent) */

package/dist/config.js

@@ -6,7 +6,7 @@
  * saw. It stays a pure function — no file I/O and no runtime dependencies: validation is
  * hand-rolled, and the published JSON Schema is a sibling artifact this source never reads.
  */
-import { validateAlgebraDeclaration } from './algebra.js';
+import { declarationChannels, validateAlgebraDeclaration, } from './algebra.js';
 import { isPlainObject } from './is-plain-object.js';
 import { ConfigValidationError, isNonEmptyString, isStringArray, rejectUnknownKeys, } from './validation.js';
 export { ConfigValidationError } from './validation.js';
@@ -21,6 +21,8 @@ const TOP_LEVEL_KEYS = new Set([
     'adapters',
     'telemetry',
     'disciplines',
+    'sessionDisciplines',
+    'changeSetDisciplines',
     'witness',
 ]);
 const PROFILE_KEYS = new Set(['productionGlob', 'testCmd']);
@@ -94,26 +96,66 @@ function validateDeclareEntry(entry, location) {
     }
     validateAlgebraDeclaration({ discipline: entry.id, ...block }, `${location} declare`);
 }
+/** The three list names an entry can be written in — also the destinations of a misplacement. */
+const DISCIPLINE_LISTS = ['disciplines', 'sessionDisciplines', 'changeSetDisciplines'];
+/** The channels only a live call carries; `changes` is the one only a change set carries. */
+const SESSION_CHANNELS = [
+    'transcript',
+    'channel',
+    'command',
+    'actor',
+];
 /**
- * Validate the `disciplines` array and split judged entries from drafts. Throws
+ * The list an entry's declaration belongs in, from the channels it binds — or `undefined`
+ * when it binds both a session channel and `changes`, which no surface observes at once.
+ */
+function listFor(channels) {
+    const readsSession = channels.some((channel) => SESSION_CHANNELS.includes(channel));
+    const readsChanges = channels.includes('changes');
+    if (readsSession && readsChanges)
+        return undefined;
+    if (readsSession)
+        return 'sessionDisciplines';
+    if (readsChanges)
+        return 'changeSetDisciplines';
+    return 'disciplines';
+}
+/**
+ * Refuse a judged entry written in a list the surface it needs does not read. The channels
+ * its declaration binds are the whole answer, so the message names them and the destination:
+ * an author who is told only that the placement is wrong meets the same error again.
+ */
+function checkPlacement(entry, list, location) {
+    const channels = declarationChannels(entry.declare);
+    const destination = listFor(channels);
+    if (destination === undefined) {
+        throw new ConfigValidationError(`${location} reads ${channels.join(', ')}: no surface observes both changes and a session channel`);
+    }
+    if (destination !== list) {
+        const reads = channels.length === 0 ? 'no evidence channel' : channels.join(', ');
+        throw new ConfigValidationError(`${location} reads ${reads}: it belongs in ${destination}`);
+    }
+}
+/**
+ * Validate one discipline list and split judged entries from drafts. Throws
  * {@link ConfigValidationError} naming the offending entry/key; the validated data passes
- * through verbatim, in declaration order.
+ * through verbatim, in declaration order. `seenIds` spans the three lists and the meta
+ * labels, so a label the telemetry space already carries is refused wherever it is written.
  */
-function validateDisciplines(disciplines) {
+function validateDisciplines(disciplines, list, seenIds) {
     if (!Array.isArray(disciplines)) {
-        throw new ConfigValidationError('disciplines must be an array');
+        throw new ConfigValidationError(`${list} must be an array`);
     }
     const judged = [];
     const drafts = [];
-    const seenIds = new Set();
     disciplines.forEach((entry, index) => {
         if (!isPlainObject(entry)) {
-            throw new ConfigValidationError(`disciplines[${index}] must be an object`);
+            throw new ConfigValidationError(`${list}[${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`);
+            throw new ConfigValidationError(`${list}[${index}].id must be a non-empty string`);
         }
-        const location = `disciplines[${index}] ('${entry.id}')`;
+        const location = `${list}[${index}] ('${entry.id}')`;
         if (seenIds.has(entry.id)) {
             throw new ConfigValidationError(`${location} duplicates the id of an earlier entry`);
         }
@@ -127,10 +169,20 @@ function validateDisciplines(disciplines) {
         // Selected by the marker's value, so an explicit `draft: undefined` is absence,
         // like every other optional key in this validator.
         if (entry.draft !== undefined) {
+            // A draft carries no declaration, so it binds no channel and there is nothing for a
+            // surface list to observe.
+            if (list !== 'disciplines') {
+                throw new ConfigValidationError(`${location} a draft belongs in disciplines`);
+            }
             drafts.push(validateDraft(entry, entry.id, location));
             return;
         }
         validateEntryHead(entry, location);
+        // Placement first: the derivation is syntactic, so an entry in the wrong list is told
+        // where it belongs rather than meeting a grammar error the move would not fix.
+        if (isPlainObject(entry.declare)) {
+            checkPlacement(entry, list, location);
+        }
         validateDeclareEntry(entry, location);
         judged.push(entry);
     });
@@ -250,7 +302,18 @@ export function defineConfig(config) {
     const resolvedLanguages = validateLanguages(config.languages);
     const protectedPaths = config.protectedPaths !== undefined ? validateProtectedPaths(config.protectedPaths) : undefined;
     const adapters = config.adapters !== undefined ? validateAdapters(config.adapters) : undefined;
-    const split = config.disciplines !== undefined ? validateDisciplines(config.disciplines) : undefined;
+    // One id space across the three lists and the meta labels: `explain` and every
+    // label-keyed telemetry reader index by the label alone.
+    const seenIds = new Set();
+    const split = config.disciplines !== undefined
+        ? validateDisciplines(config.disciplines, 'disciplines', seenIds)
+        : undefined;
+    const sessionDisciplines = config.sessionDisciplines !== undefined
+        ? validateDisciplines(config.sessionDisciplines, 'sessionDisciplines', seenIds).judged
+        : undefined;
+    const changeSetDisciplines = config.changeSetDisciplines !== undefined
+        ? validateDisciplines(config.changeSetDisciplines, 'changeSetDisciplines', seenIds).judged
+        : undefined;
     const disciplines = split?.judged;
     const drafts = split !== undefined && split.drafts.length > 0 ? split.drafts : undefined;
     const logPath = config.telemetry !== undefined ? validateTelemetry(config.telemetry) : undefined;
@@ -263,6 +326,8 @@ export function defineConfig(config) {
             logPath: logPath ?? DEFAULT_TELEMETRY_LOG_PATH,
         },
         ...(disciplines !== undefined && { disciplines }),
+        ...(sessionDisciplines !== undefined && { sessionDisciplines }),
+        ...(changeSetDisciplines !== undefined && { changeSetDisciplines }),
         ...(drafts !== undefined && { drafts }),
         ...(witness !== undefined && { witness }),
     };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { type AlgebraDeclaration, BINARY_COMBINATOR_NAMES, type BinaryStep, type ExtractBlock, type ExtractStep, RELATION_NAMES, type RelateEntry, type RelationDecl, type RelationName, type ScopeBlock, SUPPLY_POLICIES, type SupplyBlock, type UnaryStep, validateAlgebraDeclaration, type Witness, type WitnessBlock, type Witnesses, } from './algebra.ts';
+export { type AlgebraDeclaration, BINARY_COMBINATOR_NAMES, type BinaryStep, type DeclarationChannel, declarationChannels, type ExtractBlock, type ExtractStep, RELATION_NAMES, type RelateEntry, type RelationDecl, type RelationName, type ScopeBlock, SUPPLY_POLICIES, type SupplyBlock, type UnaryStep, validateAlgebraDeclaration, type Witness, type WitnessBlock, type Witnesses, } from './algebra.ts';
 export { AXIS_NAMES, type Axis, type DerivableDeclaration, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, type MechanismName, type MechanismShape, } from './catalogue.ts';
 export { type AlgebraDeclarationBody, ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, type DisciplineDraft, type DisciplineEntry, defineConfig, type EnforceLevel, type LanguageProfile, type PolydeukesConfig, type ResolvedConfig, type ResolvedLanguageProfile, } from './config.ts';
 export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.ts';
@@ -15,4 +15,4 @@ export { isPlainObject } from './is-plain-object.ts';
 export { normalizeProtectedPaths } from './protected-paths.ts';
 export { allFileChanges, type ChannelReader, type CovenantInput, type CovenantVerdict, type DispatchOutcome, type FileChange, parseInput, type SourceReader, verdictToExitCode, } from './protocol.ts';
 export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, type GainSummary, parseRecordLine, readRecords, runGain, SKIP_REASONS, type SkipReason, type TelemetryEvent, type TelemetryRecord, } from './telemetry.ts';
-export { type CanonicalTranscript, noopTranscript, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, } from './transcript.ts';
+export { type CanonicalTranscript, noopTranscript, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, transcriptFromSession, } from './transcript.ts';

package/dist/index.js

@@ -6,7 +6,7 @@
  * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { BINARY_COMBINATOR_NAMES, RELATION_NAMES, SUPPLY_POLICIES, validateAlgebraDeclaration, } from './algebra.js';
+export { BINARY_COMBINATOR_NAMES, declarationChannels, RELATION_NAMES, SUPPLY_POLICIES, validateAlgebraDeclaration, } from './algebra.js';
 export { AXIS_NAMES, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, } from './catalogue.js';
 export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, defineConfig, } from './config.js';
 export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.js';
@@ -15,4 +15,4 @@ export { isPlainObject } from './is-plain-object.js';
 export { normalizeProtectedPaths } from './protected-paths.js';
 export { allFileChanges, parseInput, verdictToExitCode, } from './protocol.js';
 export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, parseRecordLine, readRecords, runGain, SKIP_REASONS, } from './telemetry.js';
-export { noopTranscript, transcriptFromInput, } from './transcript.js';
+export { noopTranscript, transcriptFromInput, transcriptFromSession, } from './transcript.js';

package/dist/protocol.d.ts

@@ -91,6 +91,43 @@ export type CovenantInput = {
      * declaration's own supply policy.
      */
     actor?: Actor;
+    /**
+     * The host's tool roster — values, never vocabulary: `mutating` names the tools whose
+     * calls change a file, `shell` the ones carrying a command line, and `commandArgs` the
+     * argument keys that command line travels in. Absence leaves the runner on its own
+     * default roster.
+     */
+    tools?: {
+        mutating: string[];
+        shell: string[];
+        commandArgs: string[];
+    };
+    /**
+     * The evidence a live agent session carries that the repository's disk does not. Absence
+     * is the absence of a session; a session whose lists are empty is a host that named its
+     * evidence and could not deliver it.
+     *
+     * `evidencePath` is where that evidence was read from, so a surface can protect the file
+     * the session is judged from. `userMessages` carries `timestampMs` because a session can
+     * prove freshness a bare IR cannot, and `toolCalls` carries `succeeded` because a session
+     * can prove a call's outcome. `channels` is the host's own evidence channel text — a
+     * runner lifts it into the world it dispatches.
+     */
+    session?: {
+        evidencePath?: string;
+        userMessages: {
+            text: string;
+            timestampMs?: number;
+        }[];
+        toolCalls: {
+            name: string;
+            args?: Record<string, unknown>;
+            succeeded?: boolean;
+        }[];
+        channels?: {
+            sidecar?: string;
+        };
+    };
 };
 /**
  * `CovenantVerdict` — the result a covenant body produces.

package/dist/transcript.d.ts

@@ -64,3 +64,18 @@ export declare const noopTranscript: CanonicalTranscript;
  * being judged right now: they have not run, and a call can never be its own precedent.
  */
 export declare function transcriptFromInput(input: CovenantInput): CanonicalTranscript;
+/**
+ * Wrap a {@link CovenantInput}'s `session` as a {@link CanonicalTranscript}.
+ *
+ * Differs from {@link transcriptFromInput} on exactly the two facts a session proves and a
+ * bare IR cannot: `findUserMessages` carries `timestampMs` through, so a witness consumer
+ * can read freshness, and `findToolCalls` carries `succeeded` through, so a precedent
+ * consumer can read outcome. Both keys stay ABSENT where the session had none — a filled-in
+ * timestamp would open a valve from nothing, and a filled-in outcome would turn a call
+ * nobody observed into evidence. An absent `args` reads as `{}` because the transcript type
+ * requires the field.
+ *
+ * Order preserved; the input is never mutated, and every query returns fresh objects — args
+ * deep-copied — so consumers never hold live aliases into the shared IR.
+ */
+export declare function transcriptFromSession(session: NonNullable<CovenantInput['session']>): CanonicalTranscript;

package/dist/transcript.js

@@ -38,3 +38,29 @@ export function transcriptFromInput(input) {
             .map((call) => ({ name: call.name, args: structuredClone(call.args ?? {}) })),
     };
 }
+/**
+ * Wrap a {@link CovenantInput}'s `session` as a {@link CanonicalTranscript}.
+ *
+ * Differs from {@link transcriptFromInput} on exactly the two facts a session proves and a
+ * bare IR cannot: `findUserMessages` carries `timestampMs` through, so a witness consumer
+ * can read freshness, and `findToolCalls` carries `succeeded` through, so a precedent
+ * consumer can read outcome. Both keys stay ABSENT where the session had none — a filled-in
+ * timestamp would open a valve from nothing, and a filled-in outcome would turn a call
+ * nobody observed into evidence. An absent `args` reads as `{}` because the transcript type
+ * requires the field.
+ *
+ * Order preserved; the input is never mutated, and every query returns fresh objects — args
+ * deep-copied — so consumers never hold live aliases into the shared IR.
+ */
+export function transcriptFromSession(session) {
+    return {
+        findUserMessages: () => session.userMessages.map((message) => ({ ...message })),
+        findToolCalls: (name) => session.toolCalls
+            .filter((call) => name === undefined || call.name === name)
+            .map((call) => ({
+            name: call.name,
+            args: structuredClone(call.args ?? {}),
+            ...(call.succeeded === undefined ? {} : { succeeded: call.succeeded }),
+        })),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polydeukes/core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Alpha.",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "typescript": "7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/schema/polydeukes.schema.json

@@ -33,6 +33,18 @@
       "uniqueItems": true,
       "items": { "$ref": "#/$defs/discipline" }
     },
+    "sessionDisciplines": {
+      "description": "Disciplines only the session surface observes — every entry whose declaration binds a transcript, channel, command, or actor evidence channel. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
+    "changeSetDisciplines": {
+      "description": "Disciplines only the change-set surface observes — every entry whose declaration binds the changes source. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
     "witness": { "$ref": "#/$defs/witness" }
   },
   "$defs": {