@letterblack/lbe-core 1.3.1 → 1.3.2

package/CHANGELOG.md

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

package/README.md

@@ -10,7 +10,7 @@ control direct actions outside its execution boundary.
 ## Install and start
 
 ```bash
-npm install @letterblack/lbe-sdk
+npm install @letterblack/lbe-core
 npx lbe init
 npx lbe status
 npx lbe logs
@@ -44,8 +44,8 @@ egress control.
 # Internal source workspace
 
 This workspace is not the public npm package. It contains readable source,
-tests, and release tooling. The public package is generated into
-`release-public/` as `@letterblack/lbe-sdk`.
+tests, and release tooling. The public package is generated into
+`release-public/` as `@letterblack/lbe-core`.
 
 Every AI action passes through a local gate before it can execute.
 
@@ -93,7 +93,7 @@ pushes this private source repository, its history, or its internal files.
 
 Set `PUBLIC_REPO_TOKEN` and `NPM_TOKEN` as Actions secrets in this repository.
 The former needs Contents read/write permission to the public repository; the
-latter needs npm publish permission for `@letterblack/lbe-sdk`. Push a matching
+latter needs npm publish permission for `@letterblack/lbe-core`. Push a matching
 `v<package-version>` tag from current `main` to release automatically, or run
 the workflow manually with the same tag value. The workflow verifies the
 artifact and tests first, publishes npm, replaces the public repository working
@@ -140,8 +140,8 @@ npm install @letterblack/lbe-core
 
 Public users install:
 
-```bash
-npm install @letterblack/lbe-sdk
+```bash
+npm install @letterblack/lbe-core
 ```
 
 Requires Node.js ≥ 20.9.0.
@@ -171,7 +171,7 @@ cat input.json | npx lbe execute
 
 ```js
 import crypto from 'node:crypto';
-import { execute } from '@letterblack/lbe-sdk';
+import { execute } from '@letterblack/lbe-core';
 
 const buildRequest = (name, payload = {}) => ({
     version: '1.0',
@@ -188,9 +188,9 @@ const output = execute(JSON.stringify(buildRequest('status')));
 console.log(JSON.parse(output));
 ```
 
-The public contract is `execute(input: string): string`. This repo still
-contains the private source package and its internal SDK helpers below, but the
-published surface is the generated `@letterblack/lbe-sdk` package.
+The public contract is `execute(input: string): string`. This repo still
+contains the private source package and its internal SDK helpers below, but the
+published surface is the generated `@letterblack/lbe-core` package.
 
 ---
 
@@ -402,7 +402,7 @@ The controller is the only authority. Adapters execute — they do not decide.
 
 ## Public SDK surface
 
-The published package (`@letterblack/lbe-sdk`) exposes one function:
+The published package (`@letterblack/lbe-core`) exposes one function:
 
 ```ts
 export function execute(input: string): string;
@@ -427,7 +427,7 @@ interface LBEExecuteOutput {
 
 These helpers exist in `@letterblack/lbe-core` (this package) for
 repository development and testing. They are **not** exported from the public
-`@letterblack/lbe-sdk` package.
+`@letterblack/lbe-core` package.
 
 ### `sandbox(root, opts?)` → `{ write, read, patch, lbe }`
 

package/Release-README.md

@@ -1,13 +1,17 @@
-# {{PACKAGE_NAME}}
+# @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.
+actions routed through its execution boundary, records local evidence, and
+returns an allow/deny outcome before the governed action runs.
 
-## Setup
+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 {{PACKAGE_NAME}}
+npm install @letterblack/lbe-core
 npx lbe init
 npx lbe status
 npx lbe logs
@@ -15,325 +19,47 @@ npx lbe proof --public
 npx lbe open-state
 ```
 
-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.
+`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.
 
-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`.
+## Limits
 
----
-
-AI agents are starting to touch real files, terminals, tools, projects, and production workflows.
-
-The risky part is not only what the model thinks.
-
-The risky part is what happens **after the agent decides to act**.
-
-LBE is a local execution boundary for AI agents. It sits between an agent and the workspace, validates the requested action, applies policy, records evidence, and returns a structured allow/deny result before anything reaches the filesystem, terminal, or tool layer.
-
-```text
-Agent wants to act
-        ↓
-LBE validates identity, scope, replay, rate limits, and policy
-        ↓
-allow / deny / error
-        ↓
-Host executes only if LBE approved
-        ↓
-Audit evidence is written locally
-```
-
-No hosted service. No cloud control plane. No remote dependency.
-
-> **Used in production:** LBE is the safety engine inside [Letterblack for After Effects](https://letterblack.net), where AI-generated scripts and automation commands are checked before touching a live creative project.
-
----
-
-## The problem LBE is built for
-
-A user asks an agent to do one thing:
-
-```text
-"Move the Save button 20px to the right."
-```
-
-The agent may correctly understand the task, but still attempt extra actions:
-
-```text
-edit settings-panel.jsx       expected
-edit navbar.jsx               unexpected
-edit sidebar.jsx              unexpected
-run shell command             unexpected
-```
-
-Most systems treat this as:
-
-```text
-agent output → approval dialog → execution
-```
-
-LBE treats approval as only one signal.
-
-```text
-user claim      is not truth
-agent claim     is not truth
-approval dialog is not truth
-runtime evidence is truth
-```
-
-LBE asks a different question before execution:
-
-```text
-Is this action authentic?
-Is it fresh, or replayed?
-Is the requester allowed?
-Is the target inside scope?
-Does policy allow it?
-Can the result be audited?
-```
-
-That is the execution boundary.
-
----
-
-## What LBE is not
-
-LBE is **not** another AI agent framework.
-
-It does not replace:
-
-- the model
-- the IDE
-- the chat UI
-- Git
-- human review
-- an OS sandbox
-
-Git can revert source history after a change. Approval dialogs ask a human for permission. LBE exists earlier in the chain: between the agent's proposed action and the actual execution path.
-
----
-
-## What LBE does
-
-| Need | What LBE provides |
-|---|---|
-| Stop blind execution | Local allow/deny gate before execution |
-| Avoid random tool access | Structured action proposal instead of direct tool calls |
-| Verify requester identity | Signed requests, trusted keys, nonce checks |
-| Block stale/replayed actions | Timestamp and single-use nonce validation |
-| Enforce project rules | Local deny-wins policy evaluation |
-| Understand what happened | Hash-linked audit log |
-| Integrate without cloud | Runs locally through SDK / CLI / runtime package |
-
----
-
-## Package choice
-
-| I want… | Package |
-|---|---|
-| LBE to handle file writes and shell commands for me | `@letterblack/lbe-exec` |
-| Just the allow/deny decision — my app executes after approval | `{{PACKAGE_NAME}}` |
-
-This package documents the SDK boundary. For the in-process controller that performs governed file and shell operations, use `@letterblack/lbe-exec`.
-
----
-
-## Install
-
-```bash
-npm install {{PACKAGE_NAME}}
-```
-
-Requires Node.js >= 20.9.0.
-
-For the full local execution controller:
-
-```bash
-npm install @letterblack/lbe-exec
-npx lbe init
-```
-
----
-
-## Quick start: decision boundary
-
-```js
-import { execute } from '{{PACKAGE_NAME}}';
-
-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)));
-
-if (result.ok && result.decision === 'allow') {
-  // Host executes the action here.
-  // The SDK decides; your host acts.
-}
-```
-
-`execute(input: string): string` accepts JSON and returns JSON. The SDK validates and returns a decision. It does not perform the file write or shell command itself.
-
----
-
-## Observer mode
-
-Not ready to block yet? Start in observer mode.
-
-Observer mode validates and logs requests as if enforcement were active, but does not block. This lets you see what the agent is doing before deciding what to deny.
-
-```bash
-npx lbe init      # create project-local policy and key state
-npx lbe observe   # advisory / log-only mode
-npx lbe enforce   # blocking mode
-```
-
----
-
-## CLI reference
-
-| Command | Purpose |
-|---|---|
-| `npx lbe init` | Create project-local policy and key state |
-| `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 required files are present and readable |
-| `npx lbe audit-verify` | Verify the audit log hash chain |
-
----
-
-## Gate pipeline
-
-![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.](assets/lbe-gates.png)
-
-Every request enters the same local gate pipeline. A failure at any gate returns a structured denial. The remaining gates are not evaluated.
-
-```text
-[1] Schema         required fields and structural validity
-        ↓
-[2] Timestamp      permitted clock-skew window
-        ↓
-[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
-```
-
-The WASM runtime owns the gate decisions. The host receives the decision and acts on it.
-
----
-
-## Approved path
-
-![Happy path — agent proposes action, identity confirmed, policy approved, governed write executed, audit chain extended, result returned to app.](assets/story-allow.png)
-
-1. Agent or host creates a signed action proposal.
-2. LBE verifies request structure, identity, freshness, nonce, rate limit, and policy.
-3. The result is `allow`.
-4. The host executes the write or command inside the allowed workspace.
-5. A hash-linked audit entry records the decision and result.
-6. The host receives structured evidence: decision, matched rules, result, and audit identifier.
-
----
-
-## Blocked path
-
-![Deny path — policy rejection before a governed action, shell untouched, filesystem unchanged, audit entry written, final state clean.](assets/story-deny.png)
-
-1. Agent attempts an action that is malformed, stale, replayed, unsigned, too frequent, or not allowed by policy.
-2. LBE returns `deny` before any adapter is reached.
-3. The shell is untouched.
-4. The filesystem is unchanged.
-5. The denial is written to the audit chain.
-
-Denial is not a crash. It is a valid controlled outcome.
-
----
-
-## What this covers
-
-| Threat / failure mode | Gate / mechanism |
-|---|---|
-| Malformed or incomplete request | Schema |
-| Stale request | Timestamp |
-| Replayed request | Nonce |
-| Unknown or expired key | Key lifecycle |
-| Tampered request | Signature |
-| Request burst from one actor | Rate limit |
-| Action not permitted by project rules | Policy |
-| Agent writing outside project root | Host scope check after decision |
-| Later dispute over what happened | Hash-linked audit log |
-
----
-
-## What ships
-
-```text
-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 in this package.
-
----
-
-## Limits
-
-LBE validates requests routed through its runtime. It is not a kernel-level sandbox and does not provide OS process isolation, network-egress control, multi-tenant separation, or a hosted control plane.
-
-If a tool writes directly to disk outside the LBE execution boundary, that write
-is outside this package's control. Place LBE on the execution path between the
-agent and the tools it uses.
-
----
-
-## One-sentence summary
-
-LBE does not make the agent smarter. It makes the agent's execution path controlled, evidence-backed, and locally auditable.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-core",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Local-first execution governance SDK for AI agents. Agents propose → Controller validates → Adapters execute.",
   "type": "module",
   "main": "index.js",