polydeukes 0.6.1 → 0.7.1

package/dist/docs/reference/packages/polydeukes.md

@@ -2,63 +2,61 @@
 
 **English** · [한국어](./polydeukes.ko.md)
 
-The umbrella package is the only package a consumer installs. It owns the CLI bin, the config
-loader, the commit-surface runner, the session-surface runner subpath, and the bundled schema
-artifact.
+The umbrella package is the only package a consumer installs. It ships the `pdks` bin, the
+judge, both surfaces' composition roots, the session-surface runner subpath, and the bundled
+schema artifact.
 
 <a id="polydeukes-entry-points"></a>
 ## Entry points
 
-| Specifier | What it exports |
+| Specifier | What it is |
 |---|---|
-| `polydeukes` | `loadConfig`, `runCovenantCheck`, and `ResolvedConfig` |
-| `polydeukes/claude-code` | `runClaudeCodeHook` and its spec/outcome types |
+| `pdks` / `polydeukes` | The executable. One CLI under two names in `bin` |
 | `polydeukes/schema.json` | The bundled config JSON Schema |
 
-The package has one executable name in `bin`: `pdks`, with `polydeukes` as an alias.
+There is no `.` entry point. `import 'polydeukes'` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`;
+what a consumer reaches is the bin and the schema file. A session surface reaches this
+package the same way a shell does — by spawning `pdks covenant check` — so an agent adapter
+takes it as a peer dependency rather than importing it.
 
 <a id="polydeukes-bin"></a>
 ## CLI surface
 
 | Command | Purpose |
 |---|---|
-| `pdks covenant check` | Judge the staged diff, the working tree, or a ref range |
-| `pdks init claude-code` | Install the Claude Code session surface |
-| `pdks init grok` | Install the Grok session surface |
+| `pdks covenant check` | Judge an input IR (default, the session surface) or a unified diff (`--diff`, the change-set surface) from stdin |
+| `pdks init` | Create the project scaffold: config file and telemetry ignore line |
 | `pdks explain` | Render the assembled registration table without judging |
 | `pdks docs [topic]` | Read a bundled topic |
 | `pdks docs search <query>` | Search the bundled docs |
 | `pdks docs show <document-id>` | Show one bundled document or section |
 
-`pdks docs` is offline. It reads the installed package, not the network. Flags, JSON, and
-exit codes are in [`pdks docs`](../cli/docs.md).
+Session-surface installers live on the adapters: `pdks-claude-code init` and `pdks-grok init`.
 
-<a id="polydeukes-export-map"></a>
-## Export map
+<a id="surface-from-input-mode"></a>
+### The input mode is the surface
 
-<a id="root-export"></a>
-### `.` root export
+`covenant check` reads its surface off how the input arrived, never off the input's own keys.
+An IR on stdin is one call a host observed before it ran, so the run is the **session surface**;
+`--diff` is a finished change set from some producer, so the run is the **change-set surface**.
+Each surface compiles the shared list plus its own:
 
-| Symbol | Kind | Notes |
+| Input | Surface | Lists compiled |
 |---|---|---|
-| `loadConfig` | function | Discovers exactly one `polydeukes.config.*` file under `rootDir`; throws on missing, ambiguous, parse, or validation failure. |
-| `runCovenantCheck` | function | Runs the commit-surface runner and resolves to `{ exitCode: 0 \| 2 }`. |
-| `ResolvedConfig` | type | Re-export from `@polydeukes/core`. |
-| `LoadConfigSpec`, `LoadedConfig` | types | Configuration loader input and result. |
-| `CovenantCheckSpec`, `CovenantCheckOutcome`, `CheckDomain` | types | Commit runner input, result, and observation selection. |
+| an input IR on stdin | `session` | `disciplines`, then `sessionDisciplines` |
+| a unified diff on stdin under `--diff` | `changeSet` | `disciplines`, then `changeSetDisciplines` |
 
-<a id="session-export"></a>
-### `./claude-code`
+The IR's `session` key says something else: what the host proved about the call — the witness
+valve's human turns, the transcript axis, and the pre-state channel shell-write evidence needs.
+A host that carries no session (the Grok adapter) is still judged on the session surface, and
+what it lacks is the evidence those three read, not the surface. `pdks explain` prints each
+surface with its two list names and counts.
 
-| Symbol | Kind | Notes |
-|---|---|---|
-| `runClaudeCodeHook` | function | Runs the session-surface runner and resolves to `{ exitCode: 0 \| 2 }`. |
-| `ClaudeCodeHookSpec` | type | Input for the session runner. |
-| `ClaudeCodeHookOutcome` | type | Session runner result. |
+`pdks docs` is offline. It reads the installed package, not the network. Flags, JSON, and
+exit codes are in [`pdks docs`](../cli/docs.md).
 
-The generated hook imports this subpath, not the barrel. ESM imports are eager, so importing the
-barrel would load the commit-surface runner — and the git adapter behind it — on every session tool
-call that will never use them.
+<a id="polydeukes-export-map"></a>
+## Export map
 
 <a id="schema-export"></a>
 ### `./schema.json`
@@ -67,67 +65,134 @@ call that will never use them.
 |---|---|
 | `polydeukes.schema.json` | The config schema copy that ships with the umbrella package. |
 
-<a id="polydeukes-signatures"></a>
-## Signatures and examples
+<a id="covenant-module"></a>
+## The judge (`covenant` module)
 
-```ts
-function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+The judge is the umbrella's `src/covenant/` module. Everything that turns a declared promise
+into a verdict lives there, and both composition roots plus `pdks explain` import it directly.
+There is nothing to install, nothing to import, and no peer to satisfy: what you reach is its
+behaviour, through the `disciplines:` block in your config and the rows it writes to
+`.polydeukes/roi.log`.
 
-type LoadConfigSpec = { rootDir: string };
+<a id="ownership"></a>
+### What the module owns
 
-type LoadedConfig = {
-  config: ResolvedConfig;
-  configPath: string;
-};
-
-function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;
-
-type CovenantCheckSpec = {
-  repoRoot: string;
-  telemetryPath?: string;
-  covenantDist?: string;
-  ttyPrompt?: (prompt: string) => string | null;
-  domain?: CheckDomain;
-};
-
-type CheckDomain =
-  | { kind: 'staged' }
-  | { kind: 'worktree' }
-  | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
-
-function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;
-
-type ClaudeCodeHookSpec = {
-  repoRoot: string;
-  rawPayload?: string;
-  telemetryPath?: string;
-  covenantDist?: string;
-};
-```
-
-`ancestry: 'merge-base'` is the `<base>...<head>` reading. `rawPayload` absent means the hook reads
-fd 0. The hook types live on `polydeukes/claude-code`, not on the root barrel.
+| Unit | What it does |
+|---|---|
+| `runCovenant` wrapper | Runs a judge body, translates its non-blocking `1` into the blocking `2`, and logs every call. No covenant runs unmeasured |
+| Path-routing dispatcher | Registers covenants against protected paths and runs *every* matching one — no short-circuit, so the telemetry never under-counts |
+| Meta-covenants | Three registrations that protect the judging chain itself |
+| TTL witness | The time-boxed human valve, consulted only after a verdict blocked |
+| Delta layer | New-violation-only judgment over a file's before/after pair |
+| Discipline library | Config `disciplines:` entries become enforcement without a line of code |
+
+<a id="disciplines-and-meta-covenants"></a>
+### Discipline families and meta-covenants
+
+**A `disciplines:` entry is one declaration** — `judge = relate ∘ extract` over the
+observation as a world. What the declaration's sources bind decides what evidence the
+judgment needs, which is also what decides whether it can be judged on a given surface.
+
+| Sources | Judges | Evidence needed | List |
+|---|---|---|---|
+| the fixed names `target.path` · `pre` · `post` · `state` | The change itself | A file change | `disciplines` |
+| the fixed name `changes` | The observation's whole change set | A finished change set | `changeSetDisciplines` |
+| the fixed name `command` | The shell call's command line | A shell call — an Edit carries none | `sessionDisciplines` |
+| the fixed name `actor` | Who made the observation | An actor the host proved | `sessionDisciplines` |
+| `{ transcript: true }` | Session history — was a qualifying call actually executed *before* this one | A session | `sessionDisciplines` |
+| `{ file: … }` | Another file | The surface's reader for it | `disciplines` |
+| `{ sidecar: true }` | The spawn-record channel | The surface's channel reader | `sessionDisciplines` |
+
+The writing guide for these entries is [the configuration reference's `disciplines`
+section](../configuration/index.md#disciplines); the declaration grammar is the core's
+`algebra-declaration.schema.json`.
+
+**Three meta-covenants** protect the judging chain. They are covenants like any other; the
+vocabulary below applies to them unchanged.
+
+| Registration | Axis | Judges |
+|---|---|---|
+| self-mod | Tool | Mutations to protected paths through editing tools. Only the call's proven mutation target is compared — a protected path inside an edit's *content* is a mention and passes |
+| shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only if its leading word proves it read-only |
+| transcript-mod | Transcript | Writes to the live session transcript, judged by whole-path **equality** — never as a protected ancestor |
 
-```ts
-import { loadConfig, runCovenantCheck } from 'polydeukes';
-import { runClaudeCodeHook } from 'polydeukes/claude-code';
+**Six words** are the telemetry contract — five verdicts and one observation. A row in
+`.polydeukes/roi.log` carries exactly one of them, and the CLI, the docs, and the tests use
+the same word for the same event. How to read a row is in
+[troubleshooting](../../troubleshooting.md#reading-a-verdict).
 
-const { configPath } = loadConfig({ rootDir: process.cwd() });
-const check = await runCovenantCheck({ repoRoot: process.cwd() });
-const hook = await runClaudeCodeHook({ repoRoot: process.cwd(), rawPayload: '{}' });
-```
+| Verdict | Means |
+|---|---|
+| `passed` | The call was judged and upheld the covenant |
+| `blocked` | The call was judged and broke it |
+| `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
+| `advised` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, unless the entry itself says `enforce: block` |
+| `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
+| `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
+
+`unattributed` answers a question the other five cannot. They are all written by a judge
+about a call it was handed, so a write that arrives without a declared call — through an
+interpreter, a test runner's child process, a script that assembles the path from its own
+arguments — leaves no row at all. The comparison observes the result rather than the
+spelling, so it records that write after the fact. It never blocks: the write already
+happened, and the comparison fails open on both sides of the verdict.
+
+<a id="consumer-contract"></a>
+### Where the consumer touches it
+
+- **The `disciplines:` block** in your config. One entry compiles into one registration,
+  carrying its own telemetry label.
+- **`protectedPaths`**, which the path-routing dispatcher matches against.
+- **The `witness` block**, which arms the TTL valve.
+- **`.polydeukes/roi.log`**, where every judgment lands as one row.
+
+No import. The umbrella assembles the module for both surfaces.
+
+<a id="limits"></a>
+### Declared limits
+
+- **The shell axis leaves `skipped` rows, and that row is the contract.** Predicting a
+  shell command's target from its text is undecidable, so the invariant this axis holds is
+  not "nothing gets through" — it is that **no call passes unrecorded**. A new spelling
+  landing in `skipped` is the declared limit showing itself. A pass with no row at all, or
+  one recorded `passed` without a judgment, is the defect class.
+- **A session-only declaration on a host that proves no session records `skipped`.** The
+  entry is compiled — it is on the session surface — but the transcript the declaration binds
+  is absent, and the entry's own `supply: pass` disposes of that with a `skipped` row carrying
+  the reason `supply-pass`. With no policy the missing session is unjudgeable (exit 2), not an
+  automatic skip.
+- **A surface never registers the other surface's list.** A `command` or transcript
+  declaration is not compiled for a change set, and a `changes` declaration is not compiled for
+  one call, so neither leaves a row on the surface that does not observe it. Which entries a
+  surface carries is read from `pdks explain` and from the config's own list names, not from
+  the telemetry log.
+- **A declaration the compiler cannot resolve compiles to a skip registration** — routing
+  intact, no body: a step outside the registry, an argument outside a step's keys, a pattern
+  that does not compile, a paired/single mismatch. Assembly therefore never throws: one
+  unresolvable entry cannot take down its siblings, the meta-covenants, and the valve, which
+  would leave no way to fix the config that caused it. A reserved mechanism, or one whose
+  axes and relations the catalogue refuses, is a different stage: config loading rejects the
+  file (exit 2), and no skip row is written. A source the world lacks at judgment time is a
+  third case — the declaration's own `supply` policy disposes of it, and with no policy the
+  body answers unjudgeable (exit 2), never upheld.
+- **Complete containment is a non-goal.** There are no blocklists here — enumerating bypass
+  spellings is always one step behind, so the logic is inverted: a mention of a protected
+  path blocks unless proven safe. Residual vectors such as indirect path computation are
+  telemetry targets, not block targets. The two friction valves — the read-only allowlist
+  and the TTL witness — both leave a measurable trace.
+- **The valve stands after the verdict.** Only a judgment that actually blocked can be
+  witnessed open, a mid-sentence mention of the token does not arm it, and an AI can never
+  open the valve for itself.
 
 <a id="polydeukes-failure-boundaries"></a>
 ## Failure boundaries
 
-- `loadConfig()` throws on missing, ambiguous, parse, or validation failure.
-- `runCovenantCheck()` and `runClaudeCodeHook()` never throw; they resolve to `{ exitCode: 0 \| 2
-}`.
+- `runCovenantCheck()` never throws; it resolves to `{ exitCode: 0 \| 2 }`.
 - The numeric codes are `EXIT_UPHOLD` (`0`), `EXIT_BREAK_NON_BLOCKING` (`1`), and
   `EXIT_BREAK_BLOCKING` (`2`) from `@polydeukes/core`. The umbrella runners expose only `0` or
   `2`; they never return `1`.
-- `pdks covenant check` prompts for a witness token only for the staged domain, never for
-`--worktree` or `--range`.
+- `pdks covenant check` never prompts. It reads stdin and exits 0 or 2; the caller decides what
+that exit code means.
 - `pdks docs` and `pdks explain` print nothing partial on failure.
 
 <a id="polydeukes-see-also"></a>

package/dist/docs/reference/packages/sdk-ts.ko.md

@@ -0,0 +1,161 @@
+# `@polydeukes/sdk-ts`
+
+[English](sdk-ts.md) · **한국어**
+
+> **TypeScript에서 판정기로 가는 동사 하나**입니다. 약속(covenant) 입력 IR을
+> `pdks covenant check`에 건네고 판정 결과를 값으로 돌려받습니다.
+>
+> 알파입니다. `polydeukes` · `@polydeukes/core`와 함께 설치하며, 둘 다 이 패키지의
+> `peerDependencies`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+스폰과, 종료 상태를 값으로 옮기는 일이 전부입니다. 판정받는 프로젝트의 `polydeukes` 설치를
+찾고, 그 실행 파일에 입력을 표준 입력으로 넣어 돌린 뒤, 자식이 답한 것을 돌려줍니다. 판정
+코드는 여기에 없습니다. 분기는 우산 패키지를 찾았는지와 자식이 어떤 상태로 끝났는지뿐입니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `checkCovenant` | 판정받는 프로젝트에서 `pdks covenant check`를 스폰하고 판정 결과를 돌려줍니다 |
+| 우산 해소 | `repoRoot`의 설치 그래프에서 `polydeukes`를 찾아 `pdks` 실행 파일을 읽습니다 |
+| 판정 결과 변환 | 종료 코드 `0`은 `upheld`, `2`는 `blocked`, 그 밖은 모두 `unjudged`입니다 |
+
+이 패키지는 텔레메트리 행을 쓰지 않습니다. 실행이 남기는 행은 모두 판정이 일어난 자식
+프로세스가 쓰므로, 호출 하나에 행 하나는 그대로입니다.
+
+<a id="install"></a>
+## 설치
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+실행 파일도 설치 단계도 없습니다. 우산 패키지가 SDK가 스폰할 판정기를 공급하고, 코어가
+호출자가 채우는 `CovenantInput` 타입을 공급합니다.
+
+<a id="verb"></a>
+## 동사
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+const verdict = await checkCovenant({
+  repoRoot: '/path/to/the/project',
+  input: {
+    toolCalls: [
+      {
+        name: 'writeFile',
+        args: { path: 'src/index.ts', content: 'export const answer = 42;\n' },
+        fileChange: {
+          kind: 'modify',
+          path: 'src/index.ts',
+          pre: 'export const answer = 41;\n',
+          post: 'export const answer = 42;\n',
+        },
+      },
+    ],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+```
+
+IR은 호출자의 것입니다. 이 패키지는 IR을 읽지도 채우지도 않습니다. `session`도 `actor`도
+자기 명부도 더하지 않으며, 위의 `tools` 값도 호출자 자신의 도구 이름입니다. `subagentSpawns`와
+`userMessages`는 필수 배열이므로 둘 다 없는 호출자는 빈 배열을 보냅니다. `world` 키는 판정기가
+거부합니다. 러너가 세계를 디스크의 프로젝트에서 읽으며, 클라이언트가 세계를 고르면 무엇을
+판정할지를 고르는 것이 되기 때문입니다.
+
+<a id="spec"></a>
+## 스펙
+
+```ts
+type CheckCovenantSpec = {
+  repoRoot: string;
+  input: CovenantInput;
+  enforce?: 'advise' | 'block';
+  spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{ status: number | null; stderr: string }>;
+};
+
+type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; stdin: string };
+```
+
+| 필드 | 무엇인가 |
+|---|---|
+| `repoRoot` | 판정받는 프로젝트입니다. 설정 발견, 세계 축, 자식의 cwd, 우산 패키지를 찾는 설치 그래프가 모두 여기 걸립니다 |
+| `input` | 호출자 자신의 IR이며 자식의 표준 입력으로 원문 그대로 갑니다 |
+| `enforce` | 실행 전체에 대한 관측자의 기본 자세입니다. **적지 않으면 `block`입니다** |
+| `spawn` | 주입하는 스폰 이음매입니다. 없으면 이 프로세스의 node 실행 파일로 자식을 띄웁니다 |
+
+**`enforce`의 기본값은 `block`입니다.** 이것은 표면의 강제 수준이지 항목의 것이 아닙니다.
+보호 경로와 `enforce: block`을 단 항목이 호출을 멈추고, 나머지 위반은 종료 코드 0에
+`advised`로 기록됩니다. 항목 자신의 강제 수준은 다른 표면에서와 같이 느슨한 쪽이 이기도록
+조합됩니다. `@polydeukes/adapter-claude-code`와 `@polydeukes/adapter-grok`도 같은 수준으로
+판정기를 스폰합니다.
+
+기본 스폰은 파일 서술자를 하나도 상속하지 않습니다. 호출자가 자기 서술자를 갖지 않을 수 있고,
+상속한 stdout이 닫혀 있으면 자식이 답하기 전에 EPIPE로 죽기 때문입니다. stderr는 모아서
+돌려주고, 판정기가 stdout에는 판정 결과를 쓰지 않으므로 stdout은 흘려보내고 버립니다.
+
+<a id="verdicts"></a>
+## 판정 결과 셋
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| 판정 결과 | 자식의 상태 | 호출자에게 뜻하는 것 |
+|---|---|---|
+| `upheld` | `0` | 호출이 판정을 받았고 아무것도 막지 않았습니다. `advisories`는 자식의 stderr 원문이며 그 실행이 낸 권고 줄을 싣습니다. 진행하면 됩니다 |
+| `blocked` | `2` | 호출이 판정을 받았고 무언가 막았습니다. `reason`은 자식의 stderr 원문입니다. 진행하지 않습니다 |
+| `unjudged` | 그 밖의 상태이거나 우산 패키지가 없음 | 판정이 일어나지 않았습니다. `reason`이 어느 쪽인지 말합니다. 이것을 통과로 읽으면 판정기가 설치되지 않은 프로젝트에서 모든 호출이 지나갑니다 |
+
+**밸브가 없고 그 자리를 사유가 대신합니다.** 무인 실시간 호출자에게는 TTY도 사람의 턴도
+없으므로, 이 패키지는 증인 인자를 받지 않고 세션을 지어내지도 않습니다. 대신
+`blocked.reason`과 `upheld.advisories`가 데이터로 돌아오고, 그 텍스트를 이슈나 로그에 적을지
+모델에게 돌려줄지는 소비자가 정합니다. 설정 저자와 소비자를 위한 기본 자세 규칙은
+[규율 작성하기](../../how-to/write-disciplines.ko.md#posture)에 있습니다.
+
+<a id="failure"></a>
+## 실패 예제
+
+프로젝트에 `polydeukes`가 설치돼 있지 않으면 스폰할 것이 없고, 동사는 `upheld`로 답하는 대신
+그 사실을 말합니다.
+
+```ts
+const verdict = await checkCovenant({ repoRoot: '/tmp/project-without-polydeukes', input });
+
+// {
+//   verdict: 'unjudged',
+//   reason: 'no polydeukes in the install graph of /tmp/project-without-polydeukes:
+//            install it to have this input judged',
+// }
+```
+
+자식 프로세스는 돌지 않고 텔레메트리 로그에도 아무것도 더해지지 않습니다. 행은 판정이
+일어나는 자리에 쓰이는데, 판정이 일어나지 않았기 때문입니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **IR은 호출자가 만듭니다.** 도구 명부와 변경 전 상태와 봉투는 호스트가 아는 사실이므로,
+  그것을 아는 소비자가 채웁니다. 이 패키지는 그중 무엇도 공급하지 않습니다.
+- **SDK가 여는 것은 세션 표면뿐입니다.** 입력이 표준 입력의 IR로 가고, 그것이 이 실행을 세션
+  표면 판정으로 만듭니다. 끝난 변경 집합을 가진 호출자는 대신 셸에서
+  `pdks covenant check --diff`에 통합 diff를 파이프합니다.
+- **여기서는 텔레메트리 행을 쓰지 않습니다.** 행은 모두 자식이 씁니다.
+- **`unjudged`는 통과가 아닙니다.** 판정기가 답하지 않았다는 사실을 기록하며, 판정기가 없는
+  프로젝트에서 무엇을 허용할지는 소비자가 정합니다.
+
+<a id="see-also"></a>
+## 함께 보기
+
+- [`pdks covenant check`](../cli/covenant-check.ko.md)
+- [`polydeukes`](polydeukes.ko.md)
+- [`@polydeukes/core`](core.ko.md)
+- [설정 참조](../configuration/index.ko.md)

package/dist/docs/reference/packages/sdk-ts.md

@@ -0,0 +1,164 @@
+# `@polydeukes/sdk-ts`
+
+**English** · [한국어](sdk-ts.ko.md)
+
+> **One verb from TypeScript to the judge** — hand a covenant input IR to
+> `pdks covenant check` and read the verdict back as a value.
+>
+> Alpha. Install it next to `polydeukes` and `@polydeukes/core`, which it names as
+> `peerDependencies`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The spawn and the translation of an exit status into a value, and nothing else. It locates the
+`polydeukes` install of the project being judged, runs its bin with the input on stdin, and
+returns what the child answered. No judgment logic lives here: the branches are whether the
+umbrella resolved and what status the child left with.
+
+| Unit | What it does |
+|---|---|
+| `checkCovenant` | Spawns `pdks covenant check` in the judged project and returns the verdict |
+| Umbrella resolution | Finds `polydeukes` in the install graph of `repoRoot` and reads its `pdks` bin |
+| Verdict translation | Exit `0` is `upheld`, exit `2` is `blocked`, everything else is `unjudged` |
+
+This package writes no telemetry row. Every row a run leaves is written by the child process,
+where the judgment happened, so one call still leaves one row.
+
+<a id="install"></a>
+## Install
+
+```sh
+pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
+```
+
+There is no bin and no install step. The umbrella supplies the judge the SDK spawns, and the
+core supplies the `CovenantInput` type the caller fills in.
+
+<a id="verb"></a>
+## The verb
+
+```ts
+import { checkCovenant } from '@polydeukes/sdk-ts';
+
+const verdict = await checkCovenant({
+  repoRoot: '/path/to/the/project',
+  input: {
+    toolCalls: [
+      {
+        name: 'writeFile',
+        args: { path: 'src/index.ts', content: 'export const answer = 42;\n' },
+        fileChange: {
+          kind: 'modify',
+          path: 'src/index.ts',
+          pre: 'export const answer = 41;\n',
+          post: 'export const answer = 42;\n',
+        },
+      },
+    ],
+    subagentSpawns: [],
+    userMessages: [],
+    tools: { mutating: ['writeFile', 'rm'], shell: ['exec'], commandArgs: ['command'] },
+  },
+});
+```
+
+The IR is the caller's. This package neither reads it nor completes it: it adds no `session`,
+no `actor`, and no roster of its own, and the `tools` values above are the caller's own tool
+names. `subagentSpawns` and `userMessages` are required collections, so a caller with neither
+sends the empty arrays. A `world` key is refused by the judge — the runner reads the world from
+the project on disk, and a client choosing the world would be choosing what is judged.
+
+<a id="spec"></a>
+## The spec
+
+```ts
+type CheckCovenantSpec = {
+  repoRoot: string;
+  input: CovenantInput;
+  enforce?: 'advise' | 'block';
+  spawn?: (spec: CheckCovenantSpawnSpec) => Promise<{ status: number | null; stderr: string }>;
+};
+
+type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; stdin: string };
+```
+
+| Field | What it is |
+|---|---|
+| `repoRoot` | The project being judged: config discovery, the world axis, the child's cwd, and the install graph the umbrella is found in |
+| `input` | The caller's own IR, sent verbatim as the child's stdin |
+| `enforce` | The observer's posture for the whole run. **Absent is `block`** |
+| `spawn` | An injected spawn seam. Absent, the child runs under this process's node executable |
+
+**`enforce` defaults to `block`.** That is the surface's level, not an entry's: protected paths
+and entries carrying `enforce: block` stop the call, and every other break is recorded
+`advised` at exit 0. An entry's own level composes with it lenient-side-wins, as on every other
+surface. `@polydeukes/adapter-claude-code` and `@polydeukes/adapter-grok` spawn the judge at
+the same level.
+
+The default spawn inherits no file descriptor. A caller may hold none of its own, and an
+inherited stdout that is closed would kill the child with EPIPE before it answered. stderr is
+collected and returned; stdout is drained and dropped, because the judge writes no verdict
+there.
+
+<a id="verdicts"></a>
+## The three verdicts
+
+```ts
+type CheckCovenantVerdict =
+  | { verdict: 'upheld'; advisories: string }
+  | { verdict: 'blocked'; reason: string }
+  | { verdict: 'unjudged'; reason: string };
+```
+
+| Verdict | Child status | What it means for the caller |
+|---|---|---|
+| `upheld` | `0` | The call was judged and nothing blocked it. `advisories` is the child's stderr verbatim, carrying any advisory lines the run produced. Proceed |
+| `blocked` | `2` | The call was judged and something blocked it. `reason` is the child's stderr verbatim. Do not proceed |
+| `unjudged` | anything else, or no umbrella | No judgment happened. `reason` says which. Reading it as an uphold would let an uninstalled judge pass every call |
+
+**There is no valve, and the reason is the substitute.** An unattended real-time caller has no
+TTY and no human turn, so this package takes no witness argument and invents no session.
+`blocked.reason` and `upheld.advisories` come back as data instead, and the consumer decides
+where the text goes — an issue, a log, or back to the model. The posture rules for a config
+author and for a consumer are in [write disciplines](../../how-to/write-disciplines.md#posture).
+
+<a id="failure"></a>
+## A failure example
+
+When the project has no `polydeukes` installed there is nothing to spawn, and the verb says so
+rather than answering `upheld`:
+
+```ts
+const verdict = await checkCovenant({ repoRoot: '/tmp/project-without-polydeukes', input });
+
+// {
+//   verdict: 'unjudged',
+//   reason: 'no polydeukes in the install graph of /tmp/project-without-polydeukes:
+//            install it to have this input judged',
+// }
+```
+
+No child process runs, and the telemetry log gains nothing: the row is written where the
+judgment happens, and no judgment happened.
+
+<a id="limits"></a>
+## Declared limits
+
+- **The caller builds the IR.** The tool roster, the pre-state, and the envelope are the
+  host's facts, so a consumer that knows them fills them in. This package supplies none of
+  them.
+- **The SDK exposes the session surface only.** The input travels as an IR on stdin, which is
+  what makes the run a session-surface judgment. A caller that has a finished change set pipes
+  a unified diff to `pdks covenant check --diff` from its shell instead.
+- **No telemetry row is written here.** Every row comes from the child.
+- **An `unjudged` verdict is not a pass.** It records that the judge did not answer, and the
+  consumer decides what a project without a judge is allowed to do.
+
+<a id="see-also"></a>
+## See also
+
+- [`pdks covenant check`](../cli/covenant-check.md)
+- [`polydeukes`](polydeukes.md)
+- [`@polydeukes/core`](core.md)
+- [Configuration reference](../configuration/index.md)