@letterblack/lbe-core 1.3.4 → 1.3.6

package/.githooks/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+node letterblack-sentinel/scripts/mainhead-guard.mjs

package/.githooks/pre-push

@@ -0,0 +1,2 @@
+#!/bin/sh
+node letterblack-sentinel/scripts/mainhead-guard.mjs

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## 1.3.6 — 2026-06-24
+
+### Fixed
+- Fixed internal linting errors preventing clean CI execution.
+- Restored and aligned the GitHub Actions release workflow.
+
+## 1.3.3 — 2026-06-23
+
+### Fixed
+- Rebuilt the docs-aligned release from a committed tree so the npm artifact
+  gitHead matches the release commit.
+
+## 1.3.2 — 2026-06-23
+
+### Fixed
+- Aligned the public README surfaces and release docs with the shipped
+  `@letterblack/lbe-core` package and current CLI commands.
+
+## 1.3.1 — 2026-06-23
+
+### Fixed
+- Re-aligned the release branch and published package lineage after the 1.3.0
+  tag/artifact mismatch was detected.
+
+## 1.3.0 — 2026-06-23
+
+### Added
+- Central local workspace state, proof summaries, and one-time import of legacy
+  `.lbe/events.jsonl` entries while preserving the original local log.
+
+## 1.2.0 — 2026-06-20
+
+### Added
+- **Real JS governance engine** — `createLBE()` now uses the full 7-gate validation pipeline (schema → key lifecycle → timestamp skew → rate limit → nonce replay → policy) with backup, rollback, and audit. Previously backed by a thin WASM wrapper.
+- **Observer mode** — `createLBE({ mode: 'observe' })` or `npx lbe observe`. All gates run silently, audit log is written, nothing is blocked. Default for new and half-built projects.
+- **Policy file** (`lbe.policy.json`) — human-readable rule store per project. Records `effect`, `type`, `pattern`, the original user message (`from`), and timestamp (`at`). Deny always wins over allow.
+- **New CLI commands:**
+  - `npx lbe observe` — switch to observer mode
+  - `npx lbe enforce` — switch to enforcement mode
+  - `npx lbe policy` — list all rules with source context
+- **Universal CLI interface** — non-JS projects (Python, Rust, Go, any language) can pipe JSON to `npx lbe execute`. Exit 0 = allowed, exit 1 = denied, exit 2 = error.
+- **Language-agnostic design** — WASM runtime path documented as the path to non-JS bindings. JS engine is the current production runtime.
+
+### Changed
+- `LBEResult` now includes `commandId`, `stage`, `risk`, `output` fields.
+- `LBEOptions` removes `policy_mode` / `timeout_ms` — these are managed by the governance engine internally.
+- `wrapTools().dispatch()` now returns `Promise<LBEResult>` (async) to match the real engine contract.
+- Types updated throughout to reflect observer mode result shape (`LBEObservedResult`).
+
+---
+
+## 1.0.4 — 2026-06-19
+
+### Removed
+- MCP execution surface — `lbe-mcp` command, MCP adapter, and configuration examples removed.  
+  An MCP server only offers LBE as one optional tool; agent hosts with native tools can act outside that boundary, so it cannot enforce the governance boundary. See `docs/decisions/ADR-001-remove-mcp-execution-surface.md`.
+- HTTP server surface — `lbe-serve` command and HTTP adapter removed.  
+  An HTTP endpoint replicates governance in a separate process and creates a second attack surface without guaranteeing the calling agent routes through it. See `docs/decisions/ADR-002-remove-http-server-surface.md`.
+
+### Changed
+- Established SDK-only product boundary: LBE ships as one local SDK and CLI embedded in the caller's application. No daemon, host platform, Docker deployment, or companion system. See `docs/decisions/ADR-003-sdk-only-product-boundary.md`.
+- Workspace pruned to SDK-only source; all optional execution surfaces removed from `src/`, `bin/`, and CI config.
+- Public package identity (`LBE_PUBLIC_PACKAGE_NAME`, `LBE_PUBLIC_PACKAGE_VERSION`) is now parameterised via environment variables in the build script.
+- Test command made portable across Node.js versions (no `--experimental-vm-modules` flag needed).
+
+### Public surface
+The public package (`@letterblack/lbe-sdk`) exports exactly one function:
+
+```ts
+export function execute(input: string): string;
+```
+
+No server, daemon, MCP surface, or optional execution layer ships in the public package.
+
+---
+
+## 1.0.3 and earlier
+
+Pre-release development. No public changelog maintained.

package/LICENSE

@@ -1 +1 @@
-SEE LICENSE IN LICENSE
+SEE LICENSE IN LICENSE

package/README.md

@@ -1,194 +1,182 @@
 # @letterblack/lbe-core
 
-LBE is local execution control for AI agents. It evaluates file and shell
-actions routed through its execution boundary and records local evidence.
-It is not an AI model, IDE, full OS sandbox, or cloud monitor.
+LBE Core is **local execution control for AI agents**.
 
-## Setup and workspace initialization
+It evaluates file and shell actions routed through its execution boundary, records local evidence, and returns an allow/deny/proof outcome before agent work is treated as complete.
+
+LBE is not an AI model, IDE, full OS sandbox, cloud monitor, or hosted control plane. It only controls actions that are routed through LBE.
+
+```text
+Agent wants to act
+        ↓
+LBE validates workspace, policy, target, and evidence
+        ↓
+allow / deny / weak proof / error
+        ↓
+Host executes only if LBE approved
+        ↓
+Audit and proof records are written locally
+```
+
+---
+
+## Recommended install
+
+Use the current clean release:
+
+```bash
+npm install @letterblack/lbe-core@1.3.5
+npx lbe init
+npx lbe assert-consumer
+npx lbe proof --public
+```
+
+`assert-consumer` confirms this project is using LBE as an installed package dependency.
+
+It does not certify LBE release safety.
+
+## Install and start
 
 ```bash
-npm install @letterblack/lbe-core
+npm install @letterblack/lbe-core@1.3.5
 npx lbe init
 npx lbe status
 npx lbe logs
-npx lbe open-state
-npx lbe proof
 npx lbe proof --public
+npx lbe open-state
 ```
 
-`npx lbe init` creates the workspace policy and state material in the central
-per-user folder keyed by workspace ID. `npx lbe status`, `logs`, and
-`open-state` read that local state, while `proof` writes the proof record and
-`--public` redacts sensitive proof details.
+Requires Node.js `>= 20.9.0`.
+
+Command summary:
 
-In v1.3, `.lbe/events.jsonl` remains local fallback truth and is imported once
-without changing the original file. Proof uses intent, target, file index, LBE
-events, and `proof/latest.json`. Central writes are best-effort, logs remain
-local, and non-inspectable targets may produce `WEAK_PROOF`.
+| Command | Purpose |
+|---|---|
+| `npx lbe init` | Initialize LBE state for the current workspace |
+| `npx lbe status` | Show workspace policy, state, and proof status |
+| `npx lbe logs` | Show recent local LBE audit events |
+| `npx lbe open-state` | Open the central local state folder for this workspace |
+| `npx lbe proof` | Show the latest private proof result |
+| `npx lbe proof --json` | Print the latest proof as JSON |
+| `npx lbe proof --public` | Print a redacted proof safe for public sharing |
+| `npx lbe status --all` | List known local workspaces from the workspace registry |
 
 ---
 
-LBE puts a local policy gate between what an AI agent proposes and what the
-system actually executes. Every action — file write, shell command, anything —
-is validated locally before it runs. No cloud service. No daemon.
-
-> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net) — every AI-generated script and automation command passes through it before touching a live project.
-
+## What LBE does
+
+LBE gives agent builders a local execution boundary:
+
+- validates requested file and shell actions before execution
+- keeps governed actions inside the intended workspace
+- records local audit evidence
+- tracks intent, target, file-index snapshots, and proof results
+- supports private proof and public/redacted proof output
+- preserves legacy `.lbe/events.jsonl` logs while using central local state
+
+Most systems ask only:
+
+```text
+Did the user approve this?
+```
+
+LBE asks a stricter question:
+
+```text
+Is this exact action allowed to reach the filesystem or terminal, and can we prove what happened?
+```
+
 ---
 
-## Install
+## Local state and proof
 
-```bash
-npm install @letterblack/lbe-core
+LBE keeps state locally in a central per-user state folder. Each workspace has a stable workspace ID and its own event log.
+
+In v1.3, an existing `.lbe/events.jsonl` remains local fallback truth and is imported into central state once. The source file is preserved.
+
+Proof combines:
+
+```text
+intent
+  ↓
+target
+  ↓
+file-index before action
+  ↓
+LBE audit event
+  ↓
+file-index after action
+  ↓
+proof/latest.json
 ```
 
-Requires Node.js ≥ 20.9.0.
-
----
-
-## Quick start
-
-```js
-import { execute } from '@letterblack/lbe-core';
-
-const request = {
-  version: '1.0',
-  request_id: 'req-001',
-  timestamp: Math.floor(Date.now() / 1000),
-  actor: { id: 'agent:local', role: 'agent' },
-  intent: { type: 'command', name: 'write_file', payload: { target: 'out.txt' } },
-  context: { workspace: process.cwd(), env: {}, history: [] },
-  constraints: { policy_mode: 'strict', timeout_ms: 5000 },
-  auth: { signature: '<host-signed>', nonce: '<unique-per-request>' }
-};
-
-const result = JSON.parse(execute(JSON.stringify(request)));
-// Approved:  { ok: true,  decision: 'allow', ... }
-// Blocked:   { ok: false, decision: 'deny',  error: { stage, message } }
-```
-
-`execute(input: string): string` — accepts JSON, returns JSON. The runtime validates and returns a decision. The host acts on the decision.
-
-### Request fields
-
-| Field | Required | Description |
-|---|---:|---|
-| `version` | Yes | `"1.0"` |
-| `request_id` | Yes | Caller-supplied unique identifier |
-| `timestamp` | Yes | Unix timestamp in seconds |
-| `actor` | Yes | `{ id, role }` — identity of the requesting agent |
-| `intent` | Yes | `{ type, name, payload }` — what the agent wants to do |
-| `context` | Yes | Workspace path and caller context |
-| `constraints` | Yes | `policy_mode` and `timeout_ms` |
-| `auth` | Yes | Host-supplied `signature` and `nonce` |
-
----
-
-## CLI reference
+Proof results:
 
-| Command | Purpose |
+| Result | Meaning |
 |---|---|
-| `npx lbe init` | Initialize the workspace policy and state material |
-| `npx lbe status` | Show the current workspace and proof status |
-| `npx lbe logs` | Inspect local evidence and event logs |
-| `npx lbe open-state` | Open the central local state folder |
-| `npx lbe proof` | Write the current proof record |
-| `npx lbe proof --public` | Write a redacted proof record for public surfaces |
-
----
-
-## How the gate pipeline works
-
-![LBE gate sequence — Request flows through Policy, Identity, and Scope gates before reaching Action. A rejected request is routed to denial before it reaches execution.](https://unpkg.com/@letterblack/lbe-exec/assets/lbe-gates.jpg)
-
-Every request enters a 7-gate pipeline. A failure at any gate returns a structured denial — the remaining gates are not evaluated.
-
-```
-[1] Schema         required fields and structural validity
-        ↓
-[2] Timestamp      permitted clock-skew window (±10 minutes)
-        ↓
-[3] Key lifecycle  trusted key, active, not expired
-        ↓
-[4] Signature      Ed25519 request authenticity
-        ↓
-[5] Rate limit     per-requester sliding-window limit
-        ↓
-[6] Nonce          single-use replay protection
-        ↓
-[7] Policy         configured authorization (deny-wins)
-        ↓
-  allow / deny / error — structured result returned to host
-```
-
-The WASM runtime owns all gate decisions. Your host receives the decision and acts on it. Nothing executes inside the runtime.
-
----
-
-## When a request is approved
-
-![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](https://unpkg.com/@letterblack/lbe-exec/assets/story-allow.jpg)
-
-1. The agent produces a signed action proposal.
-2. Identity is confirmed against a locally held key — no network call required.
-3. The project policy is evaluated. The action is approved.
-4. The host executes the write or command inside the allowed workspace.
-5. The audit chain is extended — every approved action appends a hash-linked entry to the local log, permanently verifiable, impossible to silently remove.
-6. A structured result returns: whether it succeeded, which rules matched, and the audit entry identifier.
-
-The application stays in control. @letterblack/lbe-core decides whether the action was permitted and hands the answer back. It does not execute for you.
-
----
-
-## When a request is blocked
-
-![Deny path — policy rejection before a governed action, shell untouched, filesystem unchanged, audit entry written, final state clean.](https://unpkg.com/@letterblack/lbe-exec/assets/story-deny.jpg)
-
-1. The agent proposes an action that is outside the permitted policy.
-2. The policy gate closes immediately. The WASM runtime stamps the request denied before any adapter is reached.
-3. The shell is untouched. The filesystem is unchanged.
-4. The denial is written to the immutable audit log — chain sealed, evidence preserved.
-
-No partial execution. No silent failures. Denial is a first-class outcome, not an error.
-
----
-
-## What this covers
-
-| Threat | Gate |
-|---|---|
-| Malformed or incomplete request | Schema |
-| Stale or replayed request | Timestamp + Nonce |
-| Tampered or expired key | Key lifecycle + Signature |
-| Excessive requests from one actor | Rate limit |
-| Action not permitted by project policy | Policy — deny-wins |
-| Agent writing outside project root | Scope check in host after decision |
-
----
-
-## What ships
-
-```
-dist/index.js               WebAssembly runtime loader and execute()
-dist/cli.js                 Local CLI (npx lbe)
-dist/lbe_engine.wasm        Verified runtime binary
-dist/wasm.lock.json         Runtime integrity lock (SHA-256 of wasm binary)
-assets/lbe-gates.jpg        Gate sequence diagram
-assets/story-allow.jpg      Approved-request storyboard
-assets/story-deny.jpg       Blocked-request storyboard
-assets/runtime-boundary.svg Runtime boundary diagram
-assets/lbe-gates.png        Gate sequence diagram (full resolution)
-assets/story-allow.png      Approved-request storyboard (full resolution)
-assets/story-deny.png       Blocked-request storyboard (full resolution)
-types.d.ts                  TypeScript declarations
-```
-
-At load time the runtime verifies `lbe_engine.wasm` against `wasm.lock.json`. A missing, modified, or swapped binary fails before any request is processed.
-
-Source code, controller implementation, adapters, tests, keys, and runtime state are not included.
-
----
-
+| `PASS` | Evidence is complete and actual changes match declared intent |
+| `FAIL` | Evidence violates intent, policy, or expected file changes |
+| `WEAK_PROOF` | Target evidence was uncertain or required user confirmation |
+
+Use:
+
+```bash
+npx lbe proof --public
+```
+
+for a redacted proof summary. Public proof redacts private paths, raw internal IDs, full diffs, hashes, and sensitive failure details.
+
+---
+
+## What ships
+
+The npm package ships the packaged runtime boundary, not the private source tree.
+
+```text
+bin/lbe.js                    CLI shim
+dist/cli/lbe.js               Bundled CLI runtime
+dist/hooks/register.cjs       Hook preload runtime
+dist/state/index.cjs          Packaged CJS state resolver
+dist/state/appendCentral.cjs  Packaged central JSONL append helper
+README.md
+Release-README.md
+CHANGELOG.md
+LICENSE
+package.json
+```
+
+The npm package must not include private implementation folders such as `src/core/**`, tests, local `.lbe/**` state, AppData state, diagnostic helpers, private keys, or workspace-local proof artifacts.
+
+---
+
 ## Limits
 
-This package validates requests routed through its runtime. It does not provide kernel-level process isolation, network-egress control, multi-tenant separation, or a hosted control plane.
+LBE controls only actions routed through its execution boundary.
+
+It does not provide:
+
+- kernel-level process isolation
+- network-egress control
+- multi-tenant separation
+- hosted monitoring
+- universal control over tools outside LBE's execution boundary
+
+Central writes are best-effort. Local logs remain local.
+
+---
+
+## Release status
+
+Current aligned release:
+
+```text
+@letterblack/lbe-core@1.3.5
+```
+
+Earlier `1.3.0`, `1.3.1`, `1.3.2`, and `1.3.3` builds are superseded by `1.3.5`.
+
+---
+
+## One-sentence summary
+
+LBE Core does not make the agent smarter. It makes the agent's execution path controlled, evidence-backed, and locally auditable.

package/RELEASE_WORKSPACE_RULES.md

@@ -0,0 +1,179 @@
+# LBE Release Workspace Rules
+
+This file defines what can and cannot be used as LBE release proof.
+
+## Release authority boundary
+
+Only the designated LBE release workspace may certify LBE release safety.
+
+A downstream project, integration lab, copied repository, downloaded folder, worktree, or consumer app is not release authority for LBE.
+
+Consumer projects may prove only their own integration behavior with the installed LBE package.
+
+They must not claim:
+
+- LBE release-ready
+- LBE published
+- full LBE proof passed
+- npm/GitHub release alignment
+- package release correctness
+
+## Consumer dependency rule
+
+Other projects must consume LBE as an installed package dependency from the public registry.
+
+Allowed consumer model:
+
+```bash
+npm install @letterblack/lbe-core
+npx lbe init
+npx lbe status
+npx lbe proof --public
+```
+
+Do not use a copied LBE source tree as the authority for consumer projects.
+
+Do not point consumer projects at LBE through:
+
+- `file:`
+- `link:`
+- `workspace:`
+- `git+`
+- `github:`
+- local relative paths
+- local absolute paths
+- symlinked `node_modules` packages
+
+## assert-consumer rule
+
+`npx lbe assert-consumer` is a downstream consumer-safety guard.
+
+It answers:
+
+- Is this project using `@letterblack/lbe-core` as an installed dependency?
+- Is this project accidentally pointing at a copied source tree, workspace link, git dependency, local path, or symlink?
+
+It must always report consumer status only.
+
+It is not release proof.
+
+It is not package provenance proof.
+
+It is not a substitute for:
+
+- full test suite
+- `npm run proof`
+- package runtime verification
+- packed tarball inspection
+- npm `gitHead` check
+- GitHub tag alignment
+- GitHub Release verification
+- fresh install smoke from the registry
+
+Expected classification for a valid consumer project:
+
+```txt
+consumer-project-using-installed-registry-dependency
+releaseClaimsAllowed: false
+```
+
+If a project passes `assert-consumer`, the only valid conclusion is:
+
+```txt
+This project consumes LBE from an installed package dependency.
+This does not certify LBE release safety.
+```
+
+## Release workflow stale-guard
+
+The release workflow is the authority for public repo sync and release automation.
+
+Agents must not manually patch the public `Letterblack-Sentinel` repo to make it look released.
+
+If the public repo is stale, the correct fix is:
+
+1. inspect the release workflow
+2. verify it targets the current package: `@letterblack/lbe-core`
+3. repair stale workflow steps
+4. run the workflow or its explicit `sync-public-only` mode
+5. verify public repo, tag, GitHub Release, npm `gitHead`, and fresh install smoke
+
+## Blocked stale workflow patterns
+
+Stop immediately if the workflow still treats these as the current release packages:
+
+```txt
+@letterblack/lbe-sdk
+@letterblack/lbe-exec
+```
+
+These may appear only as legacy/deprecated notes, not active publish/sync/release jobs.
+
+## Required workflow gates
+
+The workflow must include:
+
+```txt
+node --test
+npm run proof
+npm run audit:public-docs
+npm run verify:package-runtime
+npm pack --dry-run
+npm gitHead verification
+GitHub tag target verification
+fresh npm install smoke
+public repo sync
+sync-public-only mode for already-published versions
+```
+
+## Hard stop message
+
+If the workflow is stale, report exactly:
+
+```txt
+RELEASE WORKFLOW STALE — BLOCKED
+Do not publish manually.
+Do not sync the public repo manually.
+Fix workflow first.
+```
+
+## Agent report format
+
+Before touching release automation, report:
+
+```txt
+Release workflow classification:
+- Workflow path:
+- Active package target:
+- Old package targets present: yes/no
+- sync-public-only mode present: yes/no
+- npm gitHead verification present: yes/no
+- fresh install smoke present: yes/no
+- public repo sync present: yes/no
+- release workflow allowed: yes/no
+```
+
+## Hard stop conditions
+
+Stop and report if:
+
+- a consumer project is used to certify an LBE release
+- focused integration tests are used as release proof
+- a copied/lab workspace is treated as package authority
+- local path, git, workspace, or symlink dependencies are used for LBE in a consumer project
+- release claims are made without npm/GitHub/package provenance checks
+
+## Agent report format
+
+Before making any LBE-related release claim, report:
+
+```txt
+Workspace classification:
+- Path:
+- Type: LBE release workspace / consumer project / local lab / copied workspace / unknown
+- npm run proof available: yes/no
+- full suite exit code:
+- release claims allowed: yes/no
+```
+
+If the workspace is a consumer project, local lab, copied workspace, or unknown, release claims are not allowed.

package/Release-README.md

@@ -0,0 +1,67 @@
+# @letterblack/lbe-core
+
+**Release 1.3.6**
+
+LBE is local execution control for AI agents. It evaluates file and shell
+actions routed through its execution boundary, records local evidence, and
+returns an allow/deny outcome before the governed action runs.
+
+This release documents the decision-only package. If you need the in-process
+controller that performs governed file and shell operations, that is a separate
+legacy/internal surface.
+
+## Install and start
+
+```bash
+npm install @letterblack/lbe-core
+npx lbe init
+npx lbe status
+npx lbe logs
+npx lbe proof --public
+npx lbe open-state
+```
+
+`init` creates project policy material. `status` shows the local central state
+for the current workspace; `logs` reads its event history; `proof` shows the
+latest proof result; and `open-state` opens the central state folder.
+
+## Local state and proof
+
+LBE keeps state locally in a central per-user state folder. Each workspace has
+a stable workspace ID and its own event log. In v1.3, an existing
+`.lbe/events.jsonl` remains local fallback truth and is imported into central
+state once; the source file is preserved.
+
+Proof combines an intent, optional target, file index, LBE events, and
+`proof/latest.json`. Use `lbe proof --public` for a redacted proof summary.
+Non-inspectable targets can produce `WEAK_PROOF` rather than a stronger claim.
+
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `npx lbe init` | Create project-local policy and key state |
+| `npx lbe status` | Show workspace ID and central state paths |
+| `npx lbe logs` | Read the central event history |
+| `npx lbe open-state` | Open the local central state folder |
+| `npx lbe proof` | Show the latest proof result |
+| `npx lbe proof --public` | Show a redacted proof summary |
+
+## What ships
+
+```
+bin/lbe.js                   CLI entrypoint
+dist/cli/lbe.js              Packaged CLI runtime
+dist/hooks/register.cjs      Packaged hook bridge
+dist/state/index.cjs         Packaged central-state resolver
+dist/state/appendCentral.cjs Packaged central event appender
+```
+
+Source code, controller implementation, adapters, tests, keys, and runtime
+state are not included.
+
+## Limits
+
+Only actions routed through LBE are controlled. Central writes are best-effort,
+logs remain local, and LBE does not provide process isolation or network
+egress control.