@letterblack/lbe-core 1.3.28 → 1.3.29

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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

package/Release-README.md

@@ -1,6 +1,6 @@
 # @letterblack/lbe-core
 
-**Release 1.3.28**
+**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.28",
+  "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": "3ab9a74084e1e4f067d65223d4a3d632b3a8a3e7"
+  "gitHead": "d1d8fededb1326ecc1490e0be1edbe606a16e0fb"
 }

package/release/README.md

@@ -1,8 +1,77 @@
 # {{PACKAGE_NAME}}
 
-**Local execution control for AI agents.**
+**A local policy gate between what an AI agent proposes and what your system executes.**
 
-LBE sits between what an AI agent proposes and what your system executes. Every action is validated against a local policy before it runs. No cloud service. No daemon. Evidence stays on your machine.
+---
+
+## 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.
+
+You can prompt the agent to be careful. You can review outputs manually. But neither of those is enforcement.
+
+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.
+
+---
+
+## 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
+
+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.
+
+---
+
+## Why local-first
+
+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
+
+---
+
+## What it does
+
+```
+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
+```
+
+Your code stays in control. LBE makes the allow/deny decision and hands it back. It does not execute on your behalf.
+
+---
+
+## Use cases
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
 
 ---
 
@@ -19,16 +88,16 @@ Requires Node.js >= 20.9.0.
 ## Quick start
 
 ```bash
-npx lbe init      # create policy file in observer mode
+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 it works
+## How the gate pipeline works
 
-Every request passes through a 7-gate validation pipeline inside a local WASM runtime. If any gate fails, the request is denied before anything executes.
+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 structure
@@ -42,7 +111,7 @@ Every request passes through a 7-gate validation pipeline inside a local WASM ru
 allow / deny — structured result returned to your host
 ```
 
-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.
 
 ---
 
@@ -58,58 +127,43 @@ Your host receives the decision and acts on it. Nothing executes inside the runt
 | `npx lbe execute` | Validate a JSON proposal from stdin |
 | `npx lbe execute --input <file>` | Validate a JSON proposal from a file |
 
-Start in observer mode. Watch what your agent proposes. Add deny rules. Switch to enforce when you are confident in the policy.
-
----
-
-## Observer mode
-
-Not ready to block? `init` creates the policy in observer mode. LBE validates every request and writes audit entries — but nothing is blocked. You see exactly what the agent is doing before you decide what to deny.
-
-```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 if needed
-```
-
 ---
 
-## Validating a request
-
-`execute` accepts a JSON proposal on stdin or via `--input <file>` and returns a structured decision.
-
-```bash
-# from a file
-npx lbe execute --input proposal.json
+## Programmatic API
 
-# from stdin
-echo '{"version":"1.0",...}' | npx lbe execute
-```
+```js
+import { execute } from '{{PACKAGE_NAME}}';
 
-Exit code `0` = allowed. Exit code `1` = denied. Exit code `2` = bad input.
+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>' }
+};
 
-### Minimal request shape
+const result = JSON.parse(execute(JSON.stringify(proposal)));
 
-```json
-{
-  "version": "1.0",
-  "request_id": "req-001",
-  "timestamp": 1700000000,
-  "actor": { "id": "agent:local", "role": "agent" },
-  "intent": {
-    "type": "command",
-    "name": "write_file",
-    "payload": { "target": "out.txt" }
-  },
-  "context": { "workspace": "/your/project", "env": {}, "history": [] },
-  "constraints": { "policy_mode": "strict", "timeout_ms": 5000 },
-  "auth": { "signature": "<host-signed>", "nonce": "<unique-per-request>" }
+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);
 }
 ```
 
-### Decision response
+`execute(input: string): string` — synchronous, accepts JSON, returns JSON. The WASM runtime owns all gate decisions.
+
+### Decision responses
 
+Allowed:
 ```json
 {
   "ok": true,
@@ -119,6 +173,7 @@ Exit code `0` = allowed. Exit code `1` = denied. Exit code `2` = bad input.
 }
 ```
 
+Denied:
 ```json
 {
   "ok": false,
@@ -130,36 +185,47 @@ Exit code `0` = allowed. Exit code `1` = denied. Exit code `2` = bad input.
 
 ---
 
-## Programmatic API
+## Validating from the CLI
 
-```js
-import { execute } from '{{PACKAGE_NAME}}';
-
-const result = JSON.parse(execute(JSON.stringify(proposal)));
+```bash
+# from a file
+npx lbe execute --input proposal.json
 
-if (result.decision === 'allow') {
-  // safe to act
-} else {
-  // blocked — result.error has the gate and reason
-}
+# from stdin
+cat proposal.json | npx lbe execute
 ```
 
-`execute(input: string): string` — accepts JSON, returns JSON. Synchronous. The WASM runtime owns all gate decisions.
+Exit code `0` = allowed. Exit code `1` = denied. Exit code `2` = bad input.
+
+---
+
+## Observer mode
+
+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 in this package
 
 ```
-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)
+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 flow
 assets/story-deny.jpg       Blocked-request flow
 assets/runtime-boundary.svg Runtime boundary diagram
-types.d.ts             TypeScript declarations
+types.d.ts                  TypeScript declarations
 LICENSE
 ```
 
@@ -169,46 +235,26 @@ Source code, tests, keys, internal adapters, and workspace state are not include
 
 ---
 
-## Gate pipeline — approved request
-
-![LBE gate sequence — schema, timestamp, key, signature, rate limit, nonce, policy](./assets/lbe-gates.jpg)
-
-1. Agent produces a signed action proposal.
-2. Identity confirmed against a locally held key — no network call.
-3. Policy evaluated. Request approved.
-4. Host executes inside the allowed workspace.
-5. Audit entry appended to local hash-linked log.
-
----
-
-## Gate pipeline — denied request
-
-![Blocked-request flow — policy gate closes, nothing reaches execution](./assets/story-deny.jpg)
-
-1. Agent proposes an action outside the permitted policy.
-2. Policy gate closes. WASM runtime returns denied before any adapter runs.
-3. Shell untouched. Filesystem unchanged.
-4. Denial written to audit log — chain sealed.
-
-No partial execution. Denial is a first-class outcome.
-
----
-
 ## What LBE does not do
 
-- Kernel-level process isolation
-- Network-egress control
-- Multi-tenant separation
-- Cloud monitoring or hosted control plane
-- Universal control over tools not routed through LBE
+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
 
-LBE controls only actions that pass through its execution boundary.
+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
 
-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.
+- 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
 
 ---