@flyingrobots/graft 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-06-24
+
+### Added
+
+- **Colorful prose projection seam**: buffer-native projections can now opt into
+  a `ProseProjectionProvider`, and Graft exports a Colorful CLI adapter for
+  hosts that want `.txt` buffers projected through `colorful ir -` from
+  `colorful >= 0.2.1`. The projector validates `colorful.syntax/v1`, the pinned
+  vocabulary hash, the source content hash, and UTF-8 byte ranges before
+  returning normal Graft syntax spans, paragraph/sentence outlines, and jump
+  tables. MCP `file_outline` and large-file `safe_read` calls now use that
+  adapter when `colorful >= 0.2.1` is available on `PATH`, while unsupported
+  `.txt` behavior remains unchanged when no projector is configured or the CLI
+  is unavailable.
+- **Structural basis kind for unpinned committed history**: structural-history
+  schema v0.2 adds `UNPINNED_COMMITTED` so committed git-warp readings with no
+  `ref` and no `head` no longer masquerade as `GIT_REF` rows with a null
+  `refName`. Wesley-generated declarations, LE-binary codecs, manifest hashes,
+  the Echo package descriptor, and generated-model parity tests now pin that
+  `GIT_REF` means a named ref basis.
+- **Generated-model parity for structural readings** (slice 4, last
+  Graft-only pre-Echo slice): `src/echo/structural-reading-generated-model.ts`
+  maps git-warp-backed `StructuralReadingResult` values onto the
+  Wesley-generated `StructuralReading`/`StructuralReadingEvidence`/
+  `StructuralBasis` triple and back, loss-free. Ids and payload digests are
+  sha256 over canonical JSON (deterministic, no clock, no randomness); the
+  mapping refuses to emit `ECHO_NATIVE` from translated substrates with a
+  typed error naming the `fallback_translated_is_not_native_continuum`
+  invariant, and the reverse path raises typed obstructions for
+  generated-only enum values, digest mismatches, and mismatched pairs.
+  Parity fixtures prove `graft_dead_symbols` and the `graft_review`
+  reference-count path produce deep-equal output through the
+  generated-model round-trip. Public behavior is unchanged.
+
+### Changed
+
+- **Release security floor**: release packaging now resolves Vite and Hono to
+  patched versions required by the release security gate.
+- **Graft-managed workspace registry hardening**: workspace observation now
+  serializes first-time installation ID creation, fails closed when managed
+  storage cannot be made private, rejects symlinked or unsafe registry storage
+  records before reading them, quarantines unsupported registry metadata instead
+  of reusing it, rejects malformed installation IDs, recovers stale first-time
+  installation locks, caps remote collection during daemon authorization, strips
+  userinfo from scp-like and malformed URL-style remote URLs, preserves spaces
+  in daemon-collected remote paths, serializes concurrent first workspace
+  observation, and only lets observations without explicit repository evidence
+  reuse unknown incarnations that have no durable cache or history attachments.
+  Strong same-path replacement evidence now quarantines the prior incarnation
+  directory before advancing the workspace pointer.
+- **Workspace-store contract taxonomy**: Slice 0 conformance failure codes are
+  now all included in the frozen `errorTaxonomy`, and the contract test rejects
+  covered conformance rows whose failure codes are absent from that taxonomy.
+
+## [0.9.0] - 2026-06-10
+
+### Added
+
+- **Fake Echo-shaped TypeScript witness**: Graft proves its Echo-facing seam
+  before any real Echo runtime exists. The canonical schema gains its first
+  Intent (`recordGitWarpImportBatch`), Wesley 0.0.5 emits LE-binary var
+  codecs (`src/generated/graft-structural-history.codec.generated.ts`), and
+  a new app-safe stack — `EchoKernelTransport` byte seam, EINT v1 +
+  canonical-CBOR envelope codec, typed structural-history client, and an
+  Echo-backed `StructuralReadingPort` adapter mapping Echo's
+  `ContractObstructionKind` taxonomy into Graft freshness/residual posture —
+  is exercised end to end by a deterministic fake transport. The fake
+  mirrors Echo's wire-level authority enforcement (`FORBIDDEN_CONTROL_INTENT`
+  for the reserved control op id), and guard tests keep the Echo adapter out
+  of production contexts. No public surface changes.
+- **Structural-history Echo package descriptor**: Graft now carries a
+  deterministic descriptor for the structural-history package it expects Echo
+  to host later, with repo-root-relative schema and generated-artifact
+  identities, descriptor-only Echo posture, and a local drift check wired into
+  `pnpm schema:structural-history:check`.
+- **Structural history schema authority**: Graft now carries a canonical
+  `schemas/graft-structural-history.graphql` schema with Wesley-generated
+  TypeScript contracts and a deterministic artifact drift check, establishing
+  the schema-first Echo migration boundary without changing Echo or Wesley.
+- **Structural source span invariants**: The canonical structural-history schema
+  now rejects source spans whose end offsets or present end lines precede their
+  starts.
+- **Opened workspace paths**: MCP sessions can now call `workspace_open` to
+  open another git worktree path, activate it by default, and inspect opened
+  paths through `workspace_list_opened` without adding per-tool `cwd` routing.
+- **Symbol history locations**: `graft_blame` and `graft symbol history`
+  now carry per-version path and available line-range facts from WARP symbol
+  timelines without adding a second `code_show` history response shape.
+
+### Changed
+
+- **Structural history generation gate**: `pnpm schema:structural-history:check`
+  now requires a configured Wesley CLI, verifies the pinned CLI version and L1
+  registry hash, regenerates the TypeScript artifact from GraphQL, and
+  byte-compares it with the committed generated file. CI and release workflows
+  install Wesley from a pinned release commit before running the check, and
+  `pnpm release:check` includes the same gate.
+- **Structural reading boundary**: `graft_review` impact counts and
+  `graft_dead_symbols` now read through a Graft-owned
+  `StructuralReadingPort` with explicit `echo-native`,
+  `git-warp-imported`, and `fallback-translated` evidence labels, preserving
+  existing public response shapes while preventing current git-warp readings
+  from masquerading as Echo-native witnesshood.
+
+### Fixed
+
+- **Structural reading residual posture**: Reference-count readings now
+  report a partial residual posture when committed import-scan fallback
+  evidence is unavailable after a zero-count WARP graph reading.
+
+### Security
+
+- **Dependency audit posture**: Patched audited transitive dependencies through
+  pnpm overrides for `brace-expansion` and `qs`, preserving a clean release
+  security gate.
+
 ## [0.8.0] - 2026-05-13
 
 ### Added

package/GUIDE.md

@@ -18,7 +18,7 @@ Manually enforce policies or inspect structural history from your terminal.
 ### 3. Shared Daemon Mode
 Run the central execution authority for multi-repo work and persistent monitors.
 - **Run**: `npx @flyingrobots/graft daemon`
-- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_authorize` / `workspace_bind`)
+- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_open`)
 - **Read**: [Architecture](./ARCHITECTURE.md) (Daemon section)
 
 ## Big Picture: System Orchestration
@@ -33,9 +33,9 @@ Graft is a tiered governor. It manages the context burden across three layers:
 
 - [ ] **I am setting up a new project**: Start with `README.md` Quick Start.
 - [ ] **I am configuring Claude Code**: Use `npx graft init --write-claude-hooks`.
-- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect explicit `workspace_authorize` then `workspace_bind`.
+- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect `workspace_open` as the normal agent-facing path.
 - [ ] **I am debugging a structural diff**: Use `npx graft struct diff --json`.
-- [ ] **I am contributing to Graft**: Read `METHOD.md` and `docs/BEARING.md`.
+- [ ] **I am contributing to Graft**: Read `CONTRIBUTING.md`, `METHOD.md`, and [docs/github-issues-mirroring.md](./docs/github-issues-mirroring.md).
 
 ## Rule of Thumb
 
@@ -49,5 +49,10 @@ If you need to know "what's true right now," use [docs/BEARING.md](./docs/BEARIN
 
 If you are just starting, use the [README.md](./README.md) and the setup instructions in [docs/SETUP.md](./docs/SETUP.md).
 
+If you are reporting a bug or feature idea as a newcomer, use
+[GitHub Issues](https://github.com/flyingrobots/graft/issues). Issues are
+the public discovery surface; execution details stay in Method backlog and
+design packets.
+
 ---
 **The goal is inevitably. Every feature is defined by its tests.**

package/README.md

@@ -2,117 +2,141 @@
 
 A context governor for coding agents. Graft enforces read policy so agents consume the smallest structurally correct view of a codebase instead of dumping raw files into their context window.
 
-Graft is designed for the operator who demands precision and the architect who needs a stable foundation for agentic work. It scales from simple policy-aware reads to high-fidelity causal provenance tracking across multi-session worktrees. Parser-backed structural views currently cover JavaScript, TypeScript, Rust, GraphQL, Python, Go, JSON, TOML, YAML, and Markdown.
-
 [![npm version](https://img.shields.io/npm/v/@flyingrobots/graft)](https://www.npmjs.com/package/@flyingrobots/graft)
 
 ![Graft demo](./docs/assets/graft.svg)
 
-## Why Graft?
-
-Unlike simple file-scraping tools, Graft treats the repository as a layered worldline of code structure and causal activity.
-
-- **Policy-Enforced Reads**: Automatically degrades large files to structural outlines and jump tables. Refuses binaries, secrets, and lockfiles with machine-readable reasons.
-- **Machine-Readable Contracts**: Responses carry versioned `_schema` metadata and decision receipts so agents can reason about outcomes without scraping prose.
-- **Structural Memory**: Uses WARP (Structural Worldline Memory) to track AST evolution across Git commits. Query what changed structurally without reading a single byte of source code.
-- **Causal Provenance**: Tracks the *why* behind structural changes by logging read, stage, and transition activity into strand-scoped causal workspaces.
-- **Industrial-Grade Daemon**: A same-user local runtime that manages multi-repo authorization, background indexing, and shared-machine worker pools.
+---
 
-## Quick Start
+## TL;DR — Up and Running in 30 Seconds
 
-Graft has three official entry points:
+**What it is**: Graft sits between your AI coding agent and the filesystem. Instead of dumping entire files into the context window, it returns the minimum structurally correct view — full content for small files, AST-derived outlines for large ones, hard refusals for secrets and binaries. Tool responses carry receipts so agents know exactly how much context they've consumed.
 
-- **API** for direct in-process integration
-- **CLI** for operator and debugging workflows
-- **MCP** for agent transport integration
+**Why you want it**: Agents that read files naively fill their context window with lockfiles, minified output, and 2,000-line modules they only needed 10 lines of. Graft fixes that automatically.
 
-### 1. Bootstrap a Repo
-Scaffold `.graftignore`, setup git hooks, and seed agent instructions.
 ```bash
+# Install and bootstrap your repo
 npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
-```
 
-### 2. Repo-Local Stdio MCP
-This is the simplest per-repo path for most clients. The current
-checkout is the authority, and there is no separate workspace binding
-step.
-```bash
+# Start serving (MCP over stdio — point your agent at this)
 npx @flyingrobots/graft serve
+
+# Or try a governed read from the CLI right now
+npx @flyingrobots/graft read safe src/app.ts
 ```
 
-### 3. Standalone CLI
-Enforce policy on a single read or inspect structural history.
+That's it. `init` scaffolds `.graftignore`, appends agent read guidance, and writes the client config requested by the flags you pass. `serve` starts listening on stdio. Your agent calls `safe_read` instead of reading files directly, and Graft handles the rest.
+
+---
+
+## The Problem
+
+AI coding agents read files the same way a first-year developer does: grab the whole thing, every time. A 2,000-line module goes straight into the context window. So does the lockfile. So does the compiled output. So does the `.env`.
+
+Context windows are finite. Once they fill up, the agent starts forgetting what it already read. Performance degrades. Hallucinations increase. You burn tokens on noise.
+
+Graft sits between the agent and the filesystem and enforces a simple rule: **return the minimum structurally correct view**.
+
+- Small file? Full content.
+- Large file? A structural outline — function names, signatures, line ranges. The agent can drill in with a range read if it needs a specific function body.
+- Binary, secret, or lockfile? Hard refusal with a machine-readable reason code and a suggested alternative.
+
+Tool responses carry receipts: bytes consumed, bytes avoided, session depth, policy decision. Agents can self-regulate. Operators can audit.
+
+---
+
+## Why Graft?
+
+- **Parser-backed outlines.** Outlines come from Tree-Sitter ASTs, not heuristic line-scanning. Function signatures, class hierarchies, and jump tables are structurally accurate across JavaScript, TypeScript, Rust, Python, Go, GraphQL, JSON, TOML, YAML, Markdown, and more.
+
+- **Machine-readable contracts.** Tool responses carry versioned `_schema` metadata and decision receipts. Agents reason about outcomes without scraping prose. Receipts accumulate cumulative session stats so agents know when they're burning budget.
+
+- **Structural memory across Git history.** WARP (Structural Worldline Memory) is the current git-warp-backed structural history layer. Query what changed structurally — which symbols were added, removed, or renamed — without dumping source into the agent context. Graft is converging on a `StructuralReadingPort` boundary so Echo can become the primary causal-history substrate after parity is proven.
+
+- **Session governance.** The `GovernorTracker` watches for anti-patterns: runaway tool loops, late-session large reads, edit/bash thrash. Tripwire signals surface in receipts so agents and operators can act before context is exhausted.
+
+- **Industrial-grade daemon.** A same-user local runtime manages multi-repo authorization, persistent monitors, and shared worker pools. Current git-warp contexts stay warm in memory across sessions, while the public contract is moving behind substrate-neutral structural-history ports.
+
+---
+
+## Three Official Entry Points
+
+Graft exposes capabilities through three official product entry points: CLI, MCP, and API. MCP has two runtimes: repo-local stdio for a single checkout and daemon-backed stdio for multi-repo sessions.
+
+### 1. CLI — Operator and Debugging Workflows
+
 ```bash
 npx @flyingrobots/graft read safe src/app.ts
-npx @flyingrobots/graft review --base HEAD~1
-npx @flyingrobots/graft review cooldown --pr 48
 npx @flyingrobots/graft struct since HEAD~3
 npx @flyingrobots/graft struct dead-symbols --limit 20
 npx @flyingrobots/graft symbol history createUser --path src/users.ts
+npx @flyingrobots/graft review --base HEAD~1
+npx @flyingrobots/graft review cooldown --pr 48
 ```
 
-### 4. Direct Library API
-Embed Graft in-process when you want direct access without MCP transport
-or CLI process orchestration.
-```ts
-import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
+Stateless. Print and exit. Good for scripting, spot-checking policy decisions, and inspecting structural history.
 
-const graft = createRepoLocalGraft({ cwd: process.cwd() });
-const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
+### 2. MCP — Agent Sessions
+
+#### Repo-Local Stdio
+
+The simplest path for single-repo agent work. The current checkout is the authority. No workspace binding required.
+
+```bash
+npx @flyingrobots/graft serve
+```
+
+Point your MCP client at this process. Graft speaks JSON-RPC over stdin/stdout. The same binary auto-detects non-TTY stdio and enters serve mode automatically — so `npx @flyingrobots/graft` with no arguments works as an MCP server when piped.
+
+#### Daemon-Backed Stdio
+
+A persistent same-user runtime for long-running or multi-repo agent work. Current git-warp contexts stay warm between sessions and persistent monitors can keep structural history current.
+
+```bash
+# Start the daemon explicitly
+npx @flyingrobots/graft daemon
+
+# Or let the stdio bridge auto-start/connect to the daemon
+npx @flyingrobots/graft serve --runtime daemon
 ```
 
-This uses the same repo-local core as the CLI and MCP server, but it
-lets host tools call Graft directly inside the same process.
+Daemon sessions start unbound. The normal agent flow is:
+
+1. `workspace_open` with the target repo's `cwd`; in daemon mode this authorizes the workspace before opening it.
+2. Optionally `workspace_list_opened` to inspect active workspaces
+3. Use repository-scoped tools: `safe_read`, `file_outline`, `graft_diff`, etc.
 
-When you want a direct repo-local read surface instead of tool receipts,
-use the workspace API:
+For explicit control-plane posture, use `workspace_authorize` followed by `workspace_bind`.
+
+See [docs/SETUP.md](./docs/SETUP.md) for client-specific bootstrap and daemon control-plane configuration.
+
+### 3. API — In-Process Integration
+
+Embed Graft directly when you want structural reads or syntax data without spawning a subprocess or going through MCP transport.
+
+**Governed repo reads** (same policy enforcement as MCP, no receipts):
 ```ts
 import { createRepoWorkspace } from "@flyingrobots/graft";
 
 const workspace = await createRepoWorkspace({ cwd: process.cwd() });
-const first = await workspace.safeRead({ path: "src/app.ts" });
-const second = await workspace.safeRead({ path: "src/app.ts" });
-const outline = await workspace.fileOutline({ path: "src/app.ts" });
+const result = await workspace.safeRead({ path: "src/app.ts" });
+// result.projection: "content" | "outline" | "refused" | "cache_hit" | "diff"
 ```
 
-This exposes the same governed repo-local read behavior that the MCP
-surface uses for `safe_read`, `file_outline`, `read_range`, and
-`changed_since`, but without going through MCP receipts at all.
+**In-process tool calls with receipts** (full MCP behavior, no subprocess):
+```ts
+import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
+
+const graft = createRepoLocalGraft({ cwd: process.cwd() });
+const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
+```
 
-For close editor integration, use the buffer-native surface directly:
+**Editor-native syntax highlighting** (Tree-Sitter WASM, no I/O, viewport-aware):
 ```ts
-import {
-  createProjectionBundle,
-  createStructuredBuffer,
-  ensureParserReady,
-} from "@flyingrobots/graft";
+import { createProjectionBundle, ensureParserReady } from "@flyingrobots/graft";
 
 await ensureParserReady();
 
-const buffer = createStructuredBuffer("src/app.tsx", liveEditorText, {
-  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
-});
-
-try {
-  const spans = buffer.syntaxSpans({
-    viewport: {
-      start: { row: 0, column: 0 },
-      end: { row: 80, column: 0 },
-    },
-  });
-  const context = buffer.nodeAt({ row: 24, column: 12 });
-  const rename = buffer.renamePreview({
-    position: { row: 24, column: 12 },
-    nextName: "nextValue",
-  });
-
-  // Every warm result now carries the basis it was derived from.
-  console.log(spans.basis, context.kind, rename.edits.length);
-} finally {
-  buffer.dispose();
-}
-
-// createProjectionBundle owns the temporary StructuredBuffer lifecycle.
 const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
   basis: { kind: "editor_head", headId: "head-42", tick: 17 },
   viewport: {
@@ -120,41 +144,51 @@ const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
     end: { row: 80, column: 0 },
   },
 });
-
-console.log(bundle.parseStatus.status);
+// bundle.syntax.spans — highlight ranges for the visible viewport only
 ```
 
-### 5. Shared Daemon Runtime
-Start the same-user execution authority for multi-session or multi-repo
-work.
+`createProjectionBundle` owns the WASM buffer lifecycle internally. Use `createStructuredBuffer` directly if you need to hold a buffer across multiple operations and manage `dispose()` yourself.
+
+---
+
+## Quick Start
+
 ```bash
-npx @flyingrobots/graft daemon
+# 1. Bootstrap the repo: scaffold .graftignore, seed agent instructions
+npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
+
+# 2. Start serving (repo-local stdio MCP)
+npx @flyingrobots/graft serve
 ```
 
-Daemon sessions start `unbound`. If your client connects through the
-daemon instead of repo-local stdio, the first repo-scoped flow is:
+## Contributing with public visibility
 
-1. `workspace_authorize` for the target repo/worktree
-2. `workspace_bind` for the active daemon session
-3. then use repository-scoped tools such as `safe_read`
+For bugs, capability requests, and ideas, start at
+[GitHub Issues](https://github.com/flyingrobots/graft/issues).
+That queue is the public view for priorities and discussion. Internal execution and design rigor still lives in
+`docs/method/backlog/` and `docs/design/` so details remain deterministic for contributors.
 
-Use [docs/SETUP.md](./docs/SETUP.md) for the exact client bootstrap and
-daemon control-plane posture.
+---
 
 ## Documentation
 
-- **[North Star](./NORTHSTAR.md)**: Long-term stack position and Continuum-shaped structural reading direction.
-- **[Guide](./GUIDE.md)**: Orientation, the fast path, and agent bootstrap.
-- **[Setup Guide](./docs/SETUP.md)**: Client-specific MCP setup, daemon posture, and workspace binding.
-- **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into the pipeline, worldlines, and daemon mechanics.
-- **[Architecture](./ARCHITECTURE.md)**: The authoritative structural reference (Ports, Adapters, WARP).
-- **[Public API Contract](./docs/public-api.md)**: The semver-public root import surface and stability policy.
-- **[Repo Topology](./docs/repo-topology.md)**: Where API, CLI, MCP, and the core live in the source tree.
-- **[Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md)**: Current API / CLI / MCP baseline and peer posture.
-- **[Security Model](./docs/strategy/security-model.md)**: Same-user daemon trust boundaries, authz, and observability posture.
-- **[Causal Provenance](./docs/strategy/causal-provenance.md)**: Transport sessions, causal workspaces, strands, and handoff truth.
-- **[Vision](./docs/VISION.md)**: Core tenets and the provenance-aware mission.
-- **[Method](./METHOD.md)**: Repo work doctrine and the cycle loop.
+| Document | What it covers |
+|----------|---------------|
+| [Technical Teardown](./docs/TECHNICAL_TEARDOWN.md) | Zero-to-hero deep dive: entry points, golden paths, data schemas, policy engine, WARP, session governance, trade-offs |
+| [Guide](./GUIDE.md) | Orientation, the fast path, and agent bootstrap |
+| [Setup Guide](./docs/SETUP.md) | Client-specific MCP setup, daemon posture, and workspace binding |
+| [Advanced Guide](./ADVANCED_GUIDE.md) | Pipeline internals, worldlines, and daemon mechanics |
+| [Architecture](./ARCHITECTURE.md) | Authoritative structural reference: Ports, Adapters, WARP |
+| [Public API Contract](./docs/public-api.md) | Semver-public root import surface and stability policy |
+| [Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md) | API / CLI / MCP feature baseline and peer posture |
+| [Repo Topology](./docs/repo-topology.md) | Where API, CLI, MCP, and core live in the source tree |
+| [Security Model](./docs/strategy/security-model.md) | Same-user daemon trust boundaries, authz, and observability |
+| [Causal Provenance](./docs/strategy/causal-provenance.md) | Transport sessions, causal workspaces, strands, and handoff truth |
+| [North Star](./NORTHSTAR.md) | Long-term stack position and Continuum-shaped direction |
+| [Vision](./docs/VISION.md) | Core tenets and the provenance-aware mission |
+| [Method](./METHOD.md) | Repo work doctrine and the cycle loop |
+| [Issue visibility and backlog mapping](./docs/github-issues-mirroring.md) | Public issue triage plus internal backlog synchronization |
 
 ---
+
 Built with precision by [FLYING ROBOTS](https://github.com/flyingrobots)

package/dist/adapters/colorful-cli-prose-projector.d.ts

@@ -0,0 +1,13 @@
+import type { ProcessRunner } from "../ports/process-runner.js";
+import type { ProseProjectionProvider } from "../operations/colorful-prose-projection.js";
+export declare const COLORFUL_CLI_MINIMUM_VERSION = "0.2.1";
+export interface CreateColorfulCliProseProjectorOptions {
+    readonly processRunner: ProcessRunner;
+    readonly cwd: string;
+    readonly command?: string | undefined;
+    readonly includeMarkdown?: boolean | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly maxBufferBytes?: number | undefined;
+}
+export declare function createColorfulCliProseProjector(options: CreateColorfulCliProseProjectorOptions): ProseProjectionProvider;
+//# sourceMappingURL=colorful-cli-prose-projector.d.ts.map

package/dist/adapters/colorful-cli-prose-projector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorful-cli-prose-projector.d.ts","sourceRoot":"","sources":["../../src/adapters/colorful-cli-prose-projector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAKhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAE1F,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AA4BD,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C,uBAAuB,CAgEzB"}

package/dist/adapters/colorful-cli-prose-projector.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { isColorfulProsePath, projectColorfulIr, } from "../operations/colorful-prose-projection.js";
+export const COLORFUL_CLI_MINIMUM_VERSION = "0.2.1";
+function sha256ContentHash(source) {
+    return `sha256:${createHash("sha256").update(source).digest("hex")}`;
+}
+function parseSemver(value) {
+    const match = /\b(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\b/u.exec(value);
+    if (match === null) {
+        return null;
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function versionAtLeast(actual, minimum) {
+    for (let index = 0; index < minimum.length; index += 1) {
+        const actualPart = actual[index] ?? 0;
+        const minimumPart = minimum[index] ?? 0;
+        if (actualPart > minimumPart) {
+            return true;
+        }
+        if (actualPart < minimumPart) {
+            return false;
+        }
+    }
+    return true;
+}
+export function createColorfulCliProseProjector(options) {
+    const command = options.command ?? "colorful";
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const maxBufferBytes = options.maxBufferBytes ?? 8 * 1024 * 1024;
+    const minimumVersion = parseSemver(COLORFUL_CLI_MINIMUM_VERSION);
+    let versionSupported;
+    const supportsMinimumVersion = () => {
+        if (versionSupported !== undefined) {
+            return versionSupported;
+        }
+        const result = options.processRunner.run({
+            command,
+            args: ["--version"],
+            cwd: options.cwd,
+            timeoutMs,
+            maxBufferBytes: Math.min(maxBufferBytes, 64 * 1024),
+        });
+        if (result.error !== undefined || result.status !== 0 || minimumVersion === null) {
+            versionSupported = false;
+            return versionSupported;
+        }
+        const actualVersion = parseSemver(`${result.stdout}\n${result.stderr}`);
+        versionSupported = actualVersion !== null && versionAtLeast(actualVersion, minimumVersion);
+        return versionSupported;
+    };
+    return {
+        project(input) {
+            if (!isColorfulProsePath(input.path, { includeMarkdown: options.includeMarkdown })) {
+                return null;
+            }
+            if (!supportsMinimumVersion()) {
+                return null;
+            }
+            const source = Buffer.from(input.content, "utf8");
+            const result = options.processRunner.run({
+                command,
+                args: ["ir", "-"],
+                cwd: options.cwd,
+                stdin: input.content,
+                timeoutMs,
+                maxBufferBytes,
+            });
+            if (result.error !== undefined || result.status !== 0) {
+                return null;
+            }
+            let ir;
+            try {
+                ir = JSON.parse(result.stdout);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "unknown parse error";
+                throw new Error(`Colorful CLI returned invalid JSON: ${message}`, { cause: error });
+            }
+            return projectColorfulIr({
+                path: input.path,
+                source,
+                sourceHash: sha256ContentHash(source),
+                ir,
+            });
+        },
+    };
+}
+//# sourceMappingURL=colorful-cli-prose-projector.js.map

package/dist/adapters/colorful-cli-prose-projector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorful-cli-prose-projector.js","sourceRoot":"","sources":["../../src/adapters/colorful-cli-prose-projector.ts"],"names":[],"mappings":"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"}

package/dist/adapters/fake-echo-kernel-transport.d.ts

@@ -0,0 +1,33 @@
+import { type EchoKernelTransport } from "../ports/echo-kernel-transport.js";
+export interface FakeDeadSymbolFixture {
+    readonly name: string;
+    readonly kind: string;
+    readonly filePath: string;
+    readonly exported: boolean;
+    readonly removedInCommit: string;
+}
+export interface FakeSymbolReferenceFixture {
+    readonly symbol: string;
+    readonly filePath: string;
+    readonly referenceCount: number;
+    readonly referencingFiles: readonly string[];
+}
+export interface FakeQueryObstructionFixture {
+    readonly code: string;
+    readonly message: string;
+    readonly recovery?: string;
+}
+export interface FakeEchoFixture {
+    readonly basisId?: string;
+    readonly deadSymbols?: readonly FakeDeadSymbolFixture[];
+    readonly symbolReferences?: readonly FakeSymbolReferenceFixture[];
+    readonly rejectImportBatchIds?: readonly string[];
+    readonly admissionObstructedBatchIds?: readonly string[];
+    readonly queryObstruction?: FakeQueryObstructionFixture;
+    readonly retainedEvidencePosture?: "retained" | "missing" | "obstructed";
+}
+export interface CreateFakeEchoKernelTransportOptions {
+    readonly fixture?: FakeEchoFixture;
+}
+export declare function createFakeEchoKernelTransport(options?: CreateFakeEchoKernelTransportOptions): EchoKernelTransport;
+//# sourceMappingURL=fake-echo-kernel-transport.d.ts.map

package/dist/adapters/fake-echo-kernel-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-echo-kernel-transport.d.ts","sourceRoot":"","sources":["../../src/adapters/fake-echo-kernel-transport.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,mCAAmC,CAAC;AA0B3C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAClE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IACxD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;CAC1E;AAED,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAkDD,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,oCAAyC,GACjD,mBAAmB,CA6JrB"}