@letterblack/lbe-core 1.3.27 → 1.3.29

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.3.29 — 2026-06-25
+
+### Changed
+- Expanded public mirror README with problem statement, target audience, use cases, why-local-first rationale, and scope boundaries. Previously documented only the technical surface.
+
+## 1.3.28 — 2026-06-25
+
+### Fixed
+- Fixed public mirror README source: updated `release/README.md` (the template read by `build-public-sdk.mjs`) instead of `release-public/README.md` which is overwritten at build time. README now accurately documents the 6 real CLI commands, programmatic API, request/response shape, and package contents.
+
 ## 1.3.27 — 2026-06-25
 
 ### Changed

package/Release-README.md

@@ -1,6 +1,6 @@
 # @letterblack/lbe-core
 
-**Release 1.3.27**
+**Release 1.3.29**
 
 LBE is local execution control for AI agents. It evaluates file and shell
 actions routed through its execution boundary, records local evidence, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-core",
-  "version": "1.3.27",
+  "version": "1.3.29",
   "description": "Local-first execution governance SDK for AI agents. Agents propose → Controller validates → Adapters execute.",
   "type": "module",
   "main": "index.js",
@@ -74,5 +74,5 @@
   "directories": {
     "doc": "docs"
   },
-  "gitHead": "ecbc939f1941fb1a349a8a1c94e458845bd30488"
+  "gitHead": "d1d8fededb1326ecc1490e0be1edbe606a16e0fb"
 }

package/release/README.md

@@ -1,216 +1,261 @@
 # {{PACKAGE_NAME}}
 
-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.
+**A local policy gate between what an AI agent proposes and what your system executes.**
 
-## Setup
+---
 
-```bash
-npm install {{PACKAGE_NAME}}
-npx lbe init
-npx lbe status
-npx lbe logs
-npx lbe proof --public
-npx lbe open-state
-```
+## The problem
+
+AI agents write files, run shell commands, call APIs, and modify state. Most of the time they do the right thing. But they have no built-in execution boundary. When a model hallucinates a path, over-reaches its scope, or gets manipulated by injected instructions, there is nothing between the agent's decision and your filesystem.
 
-State is stored locally in a central per-user folder, keyed by workspace ID.
-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`; `--public` redacts sensitive proof details.
+You can prompt the agent to be careful. You can review outputs manually. But neither of those is enforcement.
 
-LBE controls only actions routed through its execution boundary. Central writes
-are best-effort, logs remain local, and non-inspectable targets may produce
-`WEAK_PROOF`.
+LBE is enforcement. Every action the agent proposes is validated against a local policy before it runs. If the policy says no, the action does not execute — regardless of what the model decided.
 
 ---
 
-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.
+## Who this is for
+
+- **Developers building AI coding assistants** that write, move, or delete files on behalf of users
+- **Developers building automation tools** where an AI generates shell commands or file operations
+- **Teams integrating LLMs into existing applications** that need an audit trail and a hard execution boundary
+- **Anyone who wants to know exactly what an AI agent did** and be able to prove it, not just trust it
 
-> **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.
+You do not need to be building a safety product. If your application lets an AI agent touch the filesystem or run commands, you need an execution boundary. LBE is that boundary.
 
 ---
 
-## Which package do you need?
+## Why local-first
 
-| I want… | Package |
-|---|---|
-| LBE to handle file writes and shell commands for me (full controller) | `@letterblack/lbe-exec` |
-| Just the allow/deny decision — I'll execute it myself | `@letterblack/lbe-sdk` ← you are here |
+No cloud service. No daemon. No API key. The runtime is a verified WASM binary that runs in your process. Policy is a local JSON file. Evidence stays on your machine.
+
+This matters because:
+- It works offline and in airgapped environments
+- No external service can go down and break your enforcement
+- Sensitive file paths and workspace context never leave the machine
+- Latency is microseconds, not network round-trips
+- You own the policy — no vendor decides what is allowed
 
 ---
 
-## Install
+## What it does
 
-```bash
-npm install {{PACKAGE_NAME}}
+```
+Agent proposes an action
+        ↓
+LBE validates it through a 7-gate pipeline
+        ↓
+allow / deny — structured result returned to your host
+        ↓
+Host executes only if LBE approved
+        ↓
+Audit entry written to a local hash-linked log
 ```
 
-Requires Node.js ≥ 20.9.0.
+Your code stays in control. LBE makes the allow/deny decision and hands it back. It does not execute on your behalf.
 
 ---
 
-## Quick start
+## Use cases
 
-```js
-import { execute } from '{{PACKAGE_NAME}}';
+**AI coding assistant**
+The agent wants to write `src/auth.js`. LBE checks: is this path inside the allowed workspace? Is the operation type permitted? Does the policy allow file writes for this actor? Only if all gates pass does your host write the file.
 
-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>' }
-};
+**Shell command gating**
+The agent proposes `rm -rf ./build`. Your policy allows `rm` inside `./build` but denies recursive deletes outside it. LBE returns deny before the command reaches the shell.
 
-const result = JSON.parse(execute(JSON.stringify(request)));
-// Approved:  { ok: true,  decision: 'allow', ... }
-// Blocked:   { ok: false, decision: 'deny',  error: { stage, message } }
-```
+**Scope enforcement**
+You want the agent to only touch files in `./generated/`. Write one policy rule. LBE denies every write outside that path, automatically, on every request, without you reviewing each one.
 
-`execute(input: string): string` — accepts JSON, returns JSON. The runtime validates and returns a decision. The host acts on the decision.
+**Audit and proof**
+Every allowed and denied action is written to a local hash-linked audit log. The chain is tamper-evident — removing or modifying an entry breaks the chain and is detectable. You can prove what the agent did, in order, with cryptographic evidence.
 
-### 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` |
+**Observer mode for new projects**
+Not sure what your agent is doing? Start in observer mode. Every request is validated and logged exactly as it would be in enforcement — but nothing is blocked. Watch the patterns. Write policy rules. Switch to enforce when you are confident.
 
 ---
 
-## Observer mode — start here
-
-Not ready to block? Start in observer mode. Every request is fully validated and logged exactly as it would be in enforcement — but nothing is blocked. Watch what the agent is doing before you decide what to deny.
+## Install
 
 ```bash
-npx lbe init      # create lbe.policy.json in observer mode
-npx lbe enforce   # switch to blocking
-npx lbe observe   # switch back to advisory
+npm install {{PACKAGE_NAME}}
 ```
 
+Requires Node.js >= 20.9.0.
+
 ---
 
-## CLI reference
+## Quick start
 
-| Command | Purpose |
-|---|---|
-| `npx lbe init` | Create project-local policy and key state in observer mode |
-| `npx lbe policy-add` | Add a rule to the active policy |
-| `npx lbe observe` | Set advisory (log-only) mode |
-| `npx lbe enforce` | Set blocking mode |
-| `npx lbe run` | Validate and execute a proposal from `--in <file>` |
-| `npx lbe verify` | Validate a proposal without executing |
-| `npx lbe dryrun` | Validate and simulate without executing |
-| `npx lbe health` | Check all required files are present and readable |
-| `npx lbe audit-verify` | Verify the audit log hash chain |
+```bash
+npx lbe init      # create lbe.policy.json in observer mode
+npx lbe status    # show current policy and workspace state
+npx lbe enforce   # switch to blocking mode when ready
+```
 
 ---
 
 ## 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.
+Every request passes through 7 gates inside the WASM runtime. If any gate fails, the request is denied and the remaining gates are not evaluated.
 
 ```
-[1] Schema         required fields and structural validity
-        ↓
-[2] Timestamp      permitted clock-skew window (±10 minutes)
-        ↓
+[1] Schema         required fields and structure
+[2] Timestamp      clock-skew within ±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 rules — deny always wins
         ↓
-[7] Policy         configured authorization (deny-wins)
-        ↓
-  allow / deny / error — structured result returned to host
+allow / deny — structured result returned to your host
 ```
 
-The WASM runtime owns all gate decisions. Your host receives the decision and acts on it. Nothing executes inside the runtime.
+A failure at gate 2 never reaches gate 7. A denied request never reaches your execution layer.
 
 ---
 
-## When a request is approved
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `npx lbe init` | Create `lbe.policy.json` in observer mode |
+| `npx lbe status` | Show policy mode, rules, and workspace state |
+| `npx lbe policy` | Print the current policy file |
+| `npx lbe observe` | Switch to advisory mode — logs but does not block |
+| `npx lbe enforce` | Switch to blocking mode — denies policy violations |
+| `npx lbe execute` | Validate a JSON proposal from stdin |
+| `npx lbe execute --input <file>` | Validate a JSON proposal from a file |
+
+---
+
+## Programmatic API
+
+```js
+import { execute } from '{{PACKAGE_NAME}}';
 
-![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)
+const proposal = {
+  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: 'src/output.js' }
+  },
+  context: { workspace: process.cwd(), env: {}, history: [] },
+  constraints: { policy_mode: 'strict', timeout_ms: 5000 },
+  auth: { signature: '<host-signed>', nonce: '<unique-per-request>' }
+};
 
-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.
+const result = JSON.parse(execute(JSON.stringify(proposal)));
 
-The application stays in control. {{PACKAGE_NAME}} decides whether the action was permitted and hands the answer back. It does not execute for you.
+if (result.decision === 'allow') {
+  // LBE approved — safe to execute
+} else {
+  // LBE denied — result.error has the gate and reason
+  console.error(result.error.stage, result.error.message);
+}
+```
+
+`execute(input: string): string` — synchronous, accepts JSON, returns JSON. The WASM runtime owns all gate decisions.
+
+### Decision responses
+
+Allowed:
+```json
+{
+  "ok": true,
+  "decision": "allow",
+  "request_id": "req-001",
+  "result": { "type": "allowed" }
+}
+```
+
+Denied:
+```json
+{
+  "ok": false,
+  "decision": "deny",
+  "request_id": "req-001",
+  "error": { "stage": "policy", "message": "rule:deny_outside_workspace" }
+}
+```
 
 ---
 
-## When a request is blocked
+## Validating from the CLI
 
-![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)
+```bash
+# from a file
+npx lbe execute --input proposal.json
 
-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.
+# from stdin
+cat proposal.json | npx lbe execute
+```
 
-No partial execution. No silent failures. Denial is a first-class outcome, not an error.
+Exit code `0` = allowed. Exit code `1` = denied. Exit code `2` = bad input.
 
 ---
 
-## What this covers
+## Observer mode
 
-| 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 |
+Not ready to block? Start here.
+
+`npx lbe init` creates the policy in observer mode. Every request is fully validated and logged — exactly as it would be in enforcement — but nothing is blocked. You see exactly what the agent is doing before you write your first deny rule.
+
+```bash
+npx lbe init       # observer mode on by default
+npx lbe status     # confirm mode: observe
+npx lbe enforce    # block when ready
+npx lbe observe    # back to advisory any time
+```
 
 ---
 
-## What ships
+## What ships in this package
 
 ```
-dist/index.js               WebAssembly runtime loader and execute()
-dist/cli.js                 Local CLI (npx lbe)
+dist/index.js               WebAssembly runtime loader — exports execute()
+dist/cli.js                 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/story-allow.jpg      Approved-request flow
+assets/story-deny.jpg       Blocked-request flow
 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
+LICENSE
 ```
 
 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.
+Source code, tests, keys, internal adapters, and workspace state are not included.
+
+---
+
+## What LBE does not do
+
+LBE is not a sandbox, container, or OS-level isolation layer. It controls only the actions that your host routes through it.
+
+- Does not provide kernel-level process isolation
+- Does not control network egress
+- Does not prevent the agent from calling external APIs directly
+- Does not provide multi-tenant separation
+- Does not run a hosted control plane
+
+If the agent calls the filesystem directly without going through your host code, LBE does not see it. LBE governs actions that are explicitly routed through the `execute()` boundary.
 
 ---
 
 ## 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.
+- Central writes are best-effort
+- Local logs remain local
+- Non-inspectable targets may produce `WEAK_PROOF`
+- Rate and nonce state is per-process unless you supply a shared database path
+
+---
 
-For an in-process controller with file operations, shell, and policy management built in, see `@letterblack/lbe-exec`.
+**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.