@letterblack/lbe-core 1.3.3 → 1.3.5

package/RELEASE_WORKSPACE_RULES.md

@@ -0,0 +1,110 @@
+# 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.
+```
+
+## 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/dist/cli/lbe.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli/main.js
-import fs29 from "fs";
-import path35 from "path";
+import fs30 from "fs";
+import path36 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/parseArgs.js
@@ -67,6 +67,7 @@ COMMANDS:
   logs      Print recent entries from central event log
   open-state  Open the central state directory in the file manager
   proof     Show latest proof result (--json for raw JSON, --public for redacted)
+  assert-consumer  Verify this project consumes LBE as an installed registry dependency
   help      Show this help message
 
 OPTIONS:
@@ -4143,6 +4144,160 @@ LBE Proof \u2014 ${workspace}`);
   return { found: true, result: proof.result, profile: proof.profile };
 }
 
+// src/cli/commands/assertConsumer.js
+import fs29 from "fs";
+import path35 from "path";
+import { createRequire } from "module";
+var PACKAGE_NAME = "@letterblack/lbe-core";
+var DEP_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies"
+];
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs29.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function addCheck2(checks, name, ok, details = {}) {
+  checks.push({ name, ok, ...details });
+  return ok;
+}
+function findDependencySpec(packageJson2) {
+  if (!packageJson2 || typeof packageJson2 !== "object") return null;
+  for (const section of DEP_SECTIONS) {
+    const value = packageJson2[section]?.[PACKAGE_NAME];
+    if (value !== void 0) {
+      return { section, spec: String(value) };
+    }
+  }
+  return null;
+}
+function classifyDependencySpec(spec) {
+  const raw = String(spec || "").trim();
+  const lower = raw.toLowerCase();
+  if (!raw) {
+    return { ok: false, reason: "EMPTY_DEPENDENCY_SPEC" };
+  }
+  const blockedPrefixes = [
+    "file:",
+    "link:",
+    "workspace:",
+    "git+",
+    "github:",
+    "git://",
+    "ssh://"
+  ];
+  for (const prefix of blockedPrefixes) {
+    if (lower.startsWith(prefix)) {
+      return { ok: false, reason: "LOCAL_OR_GIT_DEPENDENCY_SPEC", prefix };
+    }
+  }
+  if (/^[a-z]:[\\/]/i.test(raw) || raw.startsWith("./") || raw.startsWith("../")) {
+    return { ok: false, reason: "PATH_DEPENDENCY_SPEC" };
+  }
+  return { ok: true };
+}
+function findPackageRoot(startFile) {
+  let dir = fs29.statSync(startFile).isDirectory() ? startFile : path35.dirname(startFile);
+  while (true) {
+    const candidate = path35.join(dir, "package.json");
+    const pkg = readJson(candidate);
+    if (pkg?.name === PACKAGE_NAME) return dir;
+    const parent = path35.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function inspectPackageLock(root) {
+  const lockPath = path35.join(root, "package-lock.json");
+  const lock = readJson(lockPath);
+  if (!lock) return { present: false };
+  const packageEntry = lock.packages?.[`node_modules/${PACKAGE_NAME}`];
+  if (!packageEntry) return { present: true, packageEntryPresent: false };
+  const resolved = String(packageEntry.resolved || "");
+  const blockedResolved = packageEntry.link === true || resolved.startsWith("file:") || resolved.startsWith("git+") || resolved.startsWith("github:") || resolved.startsWith("ssh://") || /^[a-z]:[\\/]/i.test(resolved);
+  return {
+    present: true,
+    packageEntryPresent: true,
+    link: packageEntry.link === true,
+    resolved: resolved || null,
+    blockedResolved
+  };
+}
+function getInstalledPackagePath(root) {
+  return path35.join(root, "node_modules", ...PACKAGE_NAME.split("/"));
+}
+async function assertConsumerCommand(opts = {}) {
+  const root = path35.resolve(opts.root || process.cwd());
+  const packageJsonPath2 = path35.join(root, "package.json");
+  const packageJson2 = readJson(packageJsonPath2);
+  const checks = [];
+  addCheck2(checks, "project-package-json-present", Boolean(packageJson2), { path: packageJsonPath2 });
+  const dependency = findDependencySpec(packageJson2);
+  addCheck2(checks, "declares-lbe-package-dependency", Boolean(dependency), dependency || {});
+  const specCheck = dependency ? classifyDependencySpec(dependency.spec) : { ok: false, reason: "DEPENDENCY_NOT_DECLARED" };
+  addCheck2(checks, "dependency-spec-is-registry-package", specCheck.ok, {
+    spec: dependency?.spec || null,
+    reason: specCheck.reason || null,
+    blockedPrefix: specCheck.prefix || null
+  });
+  let resolvedEntry = null;
+  let resolvedRoot = null;
+  try {
+    const req = createRequire(path35.join(root, "package.json"));
+    resolvedEntry = req.resolve(PACKAGE_NAME);
+    resolvedRoot = findPackageRoot(resolvedEntry);
+  } catch (error) {
+    addCheck2(checks, "lbe-package-resolves-from-project", false, { message: error.message });
+  }
+  if (resolvedEntry) {
+    addCheck2(checks, "lbe-package-resolves-from-project", true, { resolvedEntry });
+  }
+  if (resolvedRoot) {
+    const stat = fs29.lstatSync(resolvedRoot);
+    addCheck2(checks, "lbe-package-is-not-symlink", !stat.isSymbolicLink(), { resolvedRoot });
+  } else {
+    addCheck2(checks, "lbe-package-is-not-symlink", false, { reason: "PACKAGE_ROOT_NOT_FOUND" });
+  }
+  const installedPackagePath = getInstalledPackagePath(root);
+  if (fs29.existsSync(installedPackagePath)) {
+    const installedStat = fs29.lstatSync(installedPackagePath);
+    addCheck2(checks, "installed-node_modules-package-is-not-symlink", !installedStat.isSymbolicLink(), {
+      installedPackagePath
+    });
+  } else {
+    addCheck2(checks, "installed-node_modules-package-is-not-symlink", false, {
+      installedPackagePath,
+      reason: "PACKAGE_NOT_INSTALLED_LOCALLY"
+    });
+  }
+  const lockInfo = inspectPackageLock(root);
+  if (lockInfo.present && lockInfo.packageEntryPresent) {
+    addCheck2(checks, "package-lock-does-not-link-local-lbe", !lockInfo.blockedResolved, lockInfo);
+  } else {
+    addCheck2(checks, "package-lock-does-not-link-local-lbe", true, lockInfo);
+  }
+  const ok = checks.every((check) => check.ok);
+  const result = {
+    ok,
+    command: "assert-consumer",
+    package: PACKAGE_NAME,
+    root,
+    classification: ok ? "consumer-project-using-installed-registry-dependency" : "not-proven-consumer-installed-dependency",
+    releaseClaimsAllowed: false,
+    message: ok ? "This project consumes LBE as an installed package dependency. This does not certify LBE release safety." : "This project is not proven to consume LBE only as an installed registry dependency.",
+    checks
+  };
+  console.log(JSON.stringify(result, null, 2));
+  if (!ok) {
+    process.exitCode = 7;
+  }
+}
+
 // src/cli/main.js
 function toBoolean4(value, defaultValue = false) {
   if (value === void 0) return defaultValue;
@@ -4152,9 +4307,9 @@ function toBoolean4(value, defaultValue = false) {
   if (normalized === "false" || normalized === "0" || normalized === "no") return false;
   return defaultValue;
 }
-var __dirname2 = path35.dirname(fileURLToPath3(import.meta.url));
-var packageJsonPath = path35.join(__dirname2, "../../package.json");
-var packageJson = JSON.parse(fs29.readFileSync(packageJsonPath, "utf-8"));
+var __dirname2 = path36.dirname(fileURLToPath3(import.meta.url));
+var packageJsonPath = path36.join(__dirname2, "../../package.json");
+var packageJson = JSON.parse(fs30.readFileSync(packageJsonPath, "utf-8"));
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("--version")) {
@@ -4177,7 +4332,7 @@ async function main() {
   try {
     if (opts["pub-key-file"]) {
       try {
-        opts["pub-key"] = fs29.readFileSync(path35.resolve(opts["pub-key-file"]), "utf-8").trim();
+        opts["pub-key"] = fs30.readFileSync(path36.resolve(opts["pub-key-file"]), "utf-8").trim();
       } catch (error) {
         console.error(`Error reading public key file: ${error.message}`);
         process.exit(1);
@@ -4185,7 +4340,7 @@ async function main() {
     }
     if (["verify", "dryrun", "run"].includes(command)) {
       const integrityStrict = toBoolean4(opts["integrity-strict"], false);
-      const integrityManifestPath = path35.resolve(opts["integrity-manifest"] || ".lbe/config/integrity.manifest.json");
+      const integrityManifestPath = path36.resolve(opts["integrity-manifest"] || ".lbe/config/integrity.manifest.json");
       const integrityResult = await performIntegrityCheck({
         strict: integrityStrict,
         manifestPath: integrityManifestPath
@@ -4246,6 +4401,9 @@ async function main() {
       case "proof":
         await proofCommand(opts);
         break;
+      case "assert-consumer":
+        await assertConsumerCommand(opts);
+        break;
       default:
         console.error(`Unknown command: ${command}`);
         printHelp(packageJson.version);

package/package.json

@@ -1,20 +1,20 @@
 {
-  "name": "@letterblack/lbe-core",
-  "version": "1.3.3",
+  "name": "@letterblack/lbe-core",
+  "version": "1.3.5",
   "description": "Local-first execution governance SDK for AI agents. Agents propose → Controller validates → Adapters execute.",
   "type": "module",
   "main": "index.js",
   "types": "types.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types.d.ts",
-      "default": "./index.js"
-    },
-    "./engine": "./runtime/engine.js",
-    "./adapters": "./src/adapters/index.js",
-    "./exec": "./exec/index.js",
-    "./hooks/register.cjs": "./dist/hooks/register.cjs"
-  },
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.js"
+    },
+    "./engine": "./runtime/engine.js",
+    "./adapters": "./src/adapters/index.js",
+    "./exec": "./exec/index.js",
+    "./hooks/register.cjs": "./dist/hooks/register.cjs"
+  },
   "bin": {
     "lbe": "bin/lbe.js"
   },
@@ -29,24 +29,25 @@
     "health": "node bin/lbe.js health --json true",
     "integrity:generate": "node bin/lbe.js integrity-generate",
     "integrity:check": "node bin/lbe.js integrity-check",
-    "build:engine": "node scripts/build-engine.js",
-    "build:public-sdk": "node scripts/build-public-sdk.mjs",
-    "build:public-exec": "node scripts/build-public-exec.mjs",
-    "build:package-runtime": "node scripts/build-package-runtime.mjs",
-    "proof": "node _proof.mjs",
-    "audit:public-docs": "node scripts/audit-public-docs.mjs",
-    "verify:package-runtime": "node scripts/verify-package-runtime.mjs",
-    "verify:public-exec": "npm run proof && npm run build:public-exec && node scripts/check-public-exec.mjs && cd release-exec && npm pack --dry-run",
-    "verify:public-sdk": "npm run build:public-sdk && node scripts/check-public-artifact.mjs && cd release-public && npm pack --dry-run",
-    "engine:check": "node scripts/check-engine.js",
-    "pack:check": "npm pack --dry-run",
-    "audit:verify": "node bin/lbe.js audit-verify",
-    "guard:mainhead": "node scripts/mainhead-guard.mjs",
-    "hooks:install": "node scripts/install-git-hooks.mjs",
-    "prepack": "npm run build:package-runtime",
-    "validate:all": "npm run guard:mainhead && npm run engine:check && npm run lint && npm run test",
-    "publish:release": "node scripts/publish.mjs"
-  },
+    "build:engine": "node scripts/build-engine.js",
+    "build:public-sdk": "node scripts/build-public-sdk.mjs",
+    "build:public-exec": "node scripts/build-public-exec.mjs",
+    "build:package-runtime": "node scripts/build-package-runtime.mjs",
+    "proof": "node _proof.mjs",
+    "audit:public-docs": "node scripts/audit-public-docs.mjs",
+    "verify:package-runtime": "node scripts/verify-package-runtime.mjs",
+    "assert-consumer": "node bin/lbe.js assert-consumer",
+    "verify:public-exec": "npm run proof && npm run build:public-exec && node scripts/check-public-exec.mjs && cd release-exec && npm pack --dry-run",
+    "verify:public-sdk": "npm run build:public-sdk && node scripts/check-public-artifact.mjs && cd release-public && npm pack --dry-run",
+    "engine:check": "node scripts/check-engine.js",
+    "pack:check": "npm pack --dry-run",
+    "audit:verify": "node bin/lbe.js audit-verify",
+    "guard:mainhead": "node scripts/mainhead-guard.mjs",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "prepack": "npm run build:package-runtime",
+    "validate:all": "npm run guard:mainhead && npm run engine:check && npm run lint && npm run test",
+    "publish:release": "node scripts/publish.mjs"
+  },
   "keywords": [
     "ai-governance",
     "execution-governance",

package/src/cli/commands/assertConsumer.js

@@ -0,0 +1,198 @@
+// src/cli/commands/assertConsumer.js
+// Guard that proves a consuming project is using LBE as an installed package,
+// not treating a copied/source repository as release authority.
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+const PACKAGE_NAME = '@letterblack/lbe-core';
+const DEP_SECTIONS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies'
+];
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function addCheck(checks, name, ok, details = {}) {
+  checks.push({ name, ok, ...details });
+  return ok;
+}
+
+function findDependencySpec(packageJson) {
+  if (!packageJson || typeof packageJson !== 'object') return null;
+
+  for (const section of DEP_SECTIONS) {
+    const value = packageJson[section]?.[PACKAGE_NAME];
+    if (value !== undefined) {
+      return { section, spec: String(value) };
+    }
+  }
+
+  return null;
+}
+
+function classifyDependencySpec(spec) {
+  const raw = String(spec || '').trim();
+  const lower = raw.toLowerCase();
+
+  if (!raw) {
+    return { ok: false, reason: 'EMPTY_DEPENDENCY_SPEC' };
+  }
+
+  const blockedPrefixes = [
+    'file:',
+    'link:',
+    'workspace:',
+    'git+',
+    'github:',
+    'git://',
+    'ssh://'
+  ];
+
+  for (const prefix of blockedPrefixes) {
+    if (lower.startsWith(prefix)) {
+      return { ok: false, reason: 'LOCAL_OR_GIT_DEPENDENCY_SPEC', prefix };
+    }
+  }
+
+  if (/^[a-z]:[\\/]/i.test(raw) || raw.startsWith('./') || raw.startsWith('../')) {
+    return { ok: false, reason: 'PATH_DEPENDENCY_SPEC' };
+  }
+
+  return { ok: true };
+}
+
+function findPackageRoot(startFile) {
+  let dir = fs.statSync(startFile).isDirectory() ? startFile : path.dirname(startFile);
+
+  while (true) {
+    const candidate = path.join(dir, 'package.json');
+    const pkg = readJson(candidate);
+    if (pkg?.name === PACKAGE_NAME) return dir;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function inspectPackageLock(root) {
+  const lockPath = path.join(root, 'package-lock.json');
+  const lock = readJson(lockPath);
+  if (!lock) return { present: false };
+
+  const packageEntry = lock.packages?.[`node_modules/${PACKAGE_NAME}`];
+  if (!packageEntry) return { present: true, packageEntryPresent: false };
+
+  const resolved = String(packageEntry.resolved || '');
+  const blockedResolved =
+    packageEntry.link === true ||
+    resolved.startsWith('file:') ||
+    resolved.startsWith('git+') ||
+    resolved.startsWith('github:') ||
+    resolved.startsWith('ssh://') ||
+    /^[a-z]:[\\/]/i.test(resolved);
+
+  return {
+    present: true,
+    packageEntryPresent: true,
+    link: packageEntry.link === true,
+    resolved: resolved || null,
+    blockedResolved
+  };
+}
+
+function getInstalledPackagePath(root) {
+  return path.join(root, 'node_modules', ...PACKAGE_NAME.split('/'));
+}
+
+export async function assertConsumerCommand(opts = {}) {
+  const root = path.resolve(opts.root || process.cwd());
+  const packageJsonPath = path.join(root, 'package.json');
+  const packageJson = readJson(packageJsonPath);
+  const checks = [];
+
+  addCheck(checks, 'project-package-json-present', Boolean(packageJson), { path: packageJsonPath });
+
+  const dependency = findDependencySpec(packageJson);
+  addCheck(checks, 'declares-lbe-package-dependency', Boolean(dependency), dependency || {});
+
+  const specCheck = dependency ? classifyDependencySpec(dependency.spec) : { ok: false, reason: 'DEPENDENCY_NOT_DECLARED' };
+  addCheck(checks, 'dependency-spec-is-registry-package', specCheck.ok, {
+    spec: dependency?.spec || null,
+    reason: specCheck.reason || null,
+    blockedPrefix: specCheck.prefix || null
+  });
+
+  let resolvedEntry = null;
+  let resolvedRoot = null;
+  try {
+    const req = createRequire(path.join(root, 'package.json'));
+    resolvedEntry = req.resolve(PACKAGE_NAME);
+    resolvedRoot = findPackageRoot(resolvedEntry);
+  } catch (error) {
+    addCheck(checks, 'lbe-package-resolves-from-project', false, { message: error.message });
+  }
+
+  if (resolvedEntry) {
+    addCheck(checks, 'lbe-package-resolves-from-project', true, { resolvedEntry });
+  }
+
+  if (resolvedRoot) {
+    const stat = fs.lstatSync(resolvedRoot);
+    addCheck(checks, 'lbe-package-is-not-symlink', !stat.isSymbolicLink(), { resolvedRoot });
+  } else {
+    addCheck(checks, 'lbe-package-is-not-symlink', false, { reason: 'PACKAGE_ROOT_NOT_FOUND' });
+  }
+
+  const installedPackagePath = getInstalledPackagePath(root);
+  if (fs.existsSync(installedPackagePath)) {
+    const installedStat = fs.lstatSync(installedPackagePath);
+    addCheck(checks, 'installed-node_modules-package-is-not-symlink', !installedStat.isSymbolicLink(), {
+      installedPackagePath
+    });
+  } else {
+    addCheck(checks, 'installed-node_modules-package-is-not-symlink', false, {
+      installedPackagePath,
+      reason: 'PACKAGE_NOT_INSTALLED_LOCALLY'
+    });
+  }
+
+  const lockInfo = inspectPackageLock(root);
+  if (lockInfo.present && lockInfo.packageEntryPresent) {
+    addCheck(checks, 'package-lock-does-not-link-local-lbe', !lockInfo.blockedResolved, lockInfo);
+  } else {
+    addCheck(checks, 'package-lock-does-not-link-local-lbe', true, lockInfo);
+  }
+
+  const ok = checks.every((check) => check.ok);
+  const result = {
+    ok,
+    command: 'assert-consumer',
+    package: PACKAGE_NAME,
+    root,
+    classification: ok
+      ? 'consumer-project-using-installed-registry-dependency'
+      : 'not-proven-consumer-installed-dependency',
+    releaseClaimsAllowed: false,
+    message: ok
+      ? 'This project consumes LBE as an installed package dependency. This does not certify LBE release safety.'
+      : 'This project is not proven to consume LBE only as an installed registry dependency.',
+    checks
+  };
+
+  console.log(JSON.stringify(result, null, 2));
+
+  if (!ok) {
+    process.exitCode = 7;
+  }
+}