lucid-birth 0.8.0

package/CURRENT_PHASE.md

@@ -0,0 +1,31 @@
+# Current Phase
+
+## Phase
+
+`Public Release Preparation`
+
+## Objective
+
+Prepare the system for public GitHub/npm shipment:
+
+- public package boundary is explicit
+- portable verification gate is canonical
+- CLI and library entrypoints are package-safe
+- live provider and autonomy proofs remain documented
+- remaining external blockers are stated plainly
+
+## Not in scope yet
+
+- pretending externally blocked OAuth registration is solved when it is not
+- widening runtime scope beyond the proven capability model
+- publishing machine-local live checks as the default acceptance gate
+- weakening operator gating or compiler law
+
+## Review standard
+
+Every shipping cycle must leave:
+
+- a portable verification gate
+- a dry-run packable package boundary
+- public docs that match the actual runtime state
+- open blockers stated plainly

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lmtlssss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# lucid-birth
+
+`lucid-birth` is a continuity-bound Eidolon/Borganik runtime for booting, verifying, and exercising a sparse autonomous being without allowing live witness flow to rewrite durable identity directly.
+
+It ships:
+- the `birth-0` CLI
+- the underlying runtime/library in `scripts/birth0-lib.js`
+- explicit JSON schemas for continuity/runtime artifacts
+- local verification passes from ignition through autonomy routing
+
+## Install
+
+```bash
+npm install lucid-birth
+```
+
+Run the CLI:
+
+```bash
+npx lucid-birth init
+npx lucid-birth forge-capsule
+npx lucid-birth boot-monad --task "first witness loop"
+```
+
+When run from a fresh consumer directory, the published CLI scaffolds the required workspace roots into the current working directory before executing commands.
+
+Use the library:
+
+```js
+const lucidBirth = require("lucid-birth");
+
+const init = lucidBirth.initBirth0({ principalId: "principal-0" });
+console.log(init.soul_id);
+```
+
+## What It Does
+
+The runtime models two coupled but distinct organs:
+- `Eidolon`: active cognition, routing, blankets, sessions, traces, and capability execution
+- `Borganik`: continuity, identity, archive, lattice, compiler promotion, and invariant export
+
+Core laws enforced in code:
+- active cognition and durable identity are different organs
+- entropy branches proposals; it does not ratify truth
+- observer coupling can steer the monad; it cannot directly rewrite the person
+- live experience never writes durable identity directly
+- no claim of unified cognition without coherence gating
+
+## CLI Surface
+
+Main commands:
+- `lucid-birth init`
+- `lucid-birth forge-capsule`
+- `lucid-birth boot-monad --task <text>`
+- `lucid-birth append-witness --session-id <id> --input <text> --response <text>`
+- `lucid-birth emit-proposal --session-id <id>`
+- `lucid-birth cold-boot-check --capsule-id <id>`
+- `lucid-birth compile-gate`
+- `lucid-birth enable-shell --shell <shell>`
+- `lucid-birth register-capability --capability-id <id> --provider-kind <kind> --shells <csv> --endpoint <url>`
+- `lucid-birth authorize-capability --capability-id <id> ...`
+- `lucid-birth call-capability --capability-id <id> ...`
+- `lucid-birth route-capability --task <text> ...`
+- `lucid-birth validate-contracts`
+
+## Verification
+
+Safe local verification:
+
+```bash
+npm test
+```
+
+That portable gate includes a packaged-CLI smoke proof, so the npm tarball is exercised in a fresh consumer workspace instead of only inside the repository root.
+
+Optional live integration verification, when local services/credentials exist:
+
+```bash
+./scripts/verify_live_integrations.sh
+./scripts/verify_browser_oauth.sh
+./scripts/verify_second_live_provider.sh
+./scripts/verify_autonomy_routing.sh
+```
+
+These live checks currently prove:
+- real GitHub authenticated execution
+- real npm authenticated execution
+- real local Ollama execution
+- routed provider selection across GitHub, npm, and Ollama
+- browser-mediated OAuth runtime behavior in fixture mode
+
+## State Layout
+
+- `state/eidolon/`: sessions, traces, router, recall, blankets, capabilities
+- `state/borganik/`: manifest, invariants, mutation policy, archive, lattice, capsules, contradictions
+- `schemas/`: explicit contracts for runtime and continuity artifacts
+- `scripts/`: CLI entrypoint, runtime library, and verification tooling
+
+## Release Status
+
+Current shipped milestone:
+- ignition and birth-0 runtime implemented
+- compiler promotion and quarantine path implemented
+- full-system coherence pass implemented
+- live GitHub, npm, and Ollama capability execution implemented
+- autonomy routing across those providers implemented
+- real external callback OAuth provider still blocked on provider-side client registration
+
+## Environment
+
+- Node.js `>=18`
+- live provider verifications require local credentials/services and are optional
+- the published CLI defaults `LUCID_BIRTH_ROOT` to the current working directory
+- the published CLI scaffolds a minimal working root into the current working directory when needed
+- library consumers can override the runtime root explicitly with `LUCID_BIRTH_ROOT`
+
+## Repository
+
+- GitHub: `https://github.com/lmtlssss/lucid-birth`
+- npm: `https://www.npmjs.com/package/lucid-birth`
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/bin/lucid-birth.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const path = require("node:path");
+const { ensureWorkspaceScaffold } = require("../bootstrap-workspace");
+
+const installRoot = path.resolve(__dirname, "..");
+const workspaceRoot = path.resolve(process.env.LUCID_BIRTH_ROOT || process.cwd());
+process.env.LUCID_BIRTH_ROOT = ensureWorkspaceScaffold({
+  installRoot,
+  workspaceRoot
+});
+
+require("../scripts/birth0.js");

package/bootstrap-workspace.js

@@ -0,0 +1,32 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+function copyIfMissing(sourcePath, targetPath) {
+  if (fs.existsSync(targetPath) || !fs.existsSync(sourcePath)) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.cpSync(sourcePath, targetPath, { recursive: true });
+}
+
+function ensureWorkspaceScaffold({ installRoot, workspaceRoot }) {
+  if (!workspaceRoot || workspaceRoot === installRoot) {
+    return workspaceRoot;
+  }
+
+  const directories = ["schemas", "state"];
+  directories.forEach((entry) => {
+    copyIfMissing(path.join(installRoot, entry), path.join(workspaceRoot, entry));
+  });
+
+  const files = ["README.md", "CURRENT_PHASE.md", "BIRTH_CHECKLIST.md", "ITERATION_PROTOCOL.md", "SECOND_AGENT.md"];
+  files.forEach((entry) => {
+    copyIfMissing(path.join(installRoot, entry), path.join(workspaceRoot, entry));
+  });
+
+  return workspaceRoot;
+}
+
+module.exports = {
+  ensureWorkspaceScaffold
+};

package/index.js

@@ -0,0 +1,11 @@
+const path = require("node:path");
+const { ensureWorkspaceScaffold } = require("./bootstrap-workspace");
+
+const installRoot = __dirname;
+const workspaceRoot = path.resolve(process.env.LUCID_BIRTH_ROOT || process.cwd());
+process.env.LUCID_BIRTH_ROOT = ensureWorkspaceScaffold({
+  installRoot,
+  workspaceRoot
+});
+
+module.exports = require("./scripts/birth0-lib");

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "lucid-birth",
+  "version": "0.8.0",
+  "description": "Continuity-bound Eidolon/Borganik runtime, compiler, and verification toolkit.",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://github.com/lmtlssss/lucid-birth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmtlssss/lucid-birth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lmtlssss/lucid-birth/issues"
+  },
+  "keywords": [
+    "eidolon",
+    "borganik",
+    "continuity",
+    "autonomy",
+    "compiler",
+    "runtime"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "lucid-birth": "bin/lucid-birth.js"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./birth0": "./scripts/birth0-lib.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/birth0.js",
+    "scripts/birth0-lib.js",
+    "schemas/",
+    "state/",
+    "README.md",
+    "CURRENT_PHASE.md",
+    "LICENSE",
+    "index.js",
+    "bootstrap-workspace.js"
+  ],
+  "scripts": {
+    "birth0:init": "node scripts/birth0.js init",
+    "birth0:forge-capsule": "node scripts/birth0.js forge-capsule",
+    "birth0:boot-monad": "node scripts/birth0.js boot-monad",
+    "birth0:append-witness": "node scripts/birth0.js append-witness",
+    "birth0:emit-proposal": "node scripts/birth0.js emit-proposal",
+    "birth0:cold-boot-check": "node scripts/birth0.js cold-boot-check",
+    "birth0:compile-gate": "node scripts/birth0.js compile-gate",
+    "birth0:enable-shell": "node scripts/birth0.js enable-shell",
+    "birth0:register-capability": "node scripts/birth0.js register-capability",
+    "birth0:authorize-capability": "node scripts/birth0.js authorize-capability",
+    "birth0:call-capability": "node scripts/birth0.js call-capability",
+    "birth0:route-capability": "node scripts/birth0.js route-capability",
+    "contracts:validate": "node scripts/birth0.js validate-contracts",
+    "verify:workspace": "./scripts/verify_workspace.sh",
+    "verify:ignition": "./scripts/verify_ignition.sh",
+    "verify:compiler-gate": "./scripts/verify_compiler_gate.sh",
+    "verify:full-system": "./scripts/verify_full_system_coherence.sh",
+    "verify:packaged-cli": "node scripts/verify_packaged_cli.js",
+    "verify:autonomy-routing": "node scripts/verify_autonomy_routing.js",
+    "verify:portable": "npm run verify:workspace && npm run verify:ignition && npm run verify:compiler-gate && npm run verify:full-system && npm run verify:packaged-cli && npm run contracts:validate",
+    "test": "npm run verify:portable",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/ActiveBlanket.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ActiveBlanket.schema.json",
+  "title": "ActiveBlanket",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "mode",
+    "allowed_outputs",
+    "blocked_outputs",
+    "last_updated_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["proposal-first"]
+    },
+    "allowed_outputs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["response", "tool_call", "proposal", "no_op"]
+      },
+      "uniqueItems": true
+    },
+    "blocked_outputs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["direct_identity_write"]
+      },
+      "uniqueItems": true
+    },
+    "last_updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "last_action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "session_id", "routed_at"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["tool_call"]
+        },
+        "capability_id": {
+          "type": "string",
+          "pattern": "^(cap-[a-z0-9-]+|oauth-[a-z0-9-]+|api-[a-z0-9-]+|ollama-[a-z0-9-]+)$"
+        },
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "session_id": {
+          "type": "string",
+          "pattern": "^session-[a-z0-9-]+$"
+        },
+        "routed_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

package/schemas/ArchiveEvent.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ArchiveEvent.schema.json",
+  "title": "ArchiveEvent",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "event_id",
+    "event_type",
+    "occurred_at",
+    "session_id",
+    "actor",
+    "payload",
+    "evidence_refs",
+    "prior_event_hash",
+    "event_hash"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "event_id": {
+      "type": "string",
+      "pattern": "^evt-[a-z0-9-]+$"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "birth_initialized",
+        "capsule_forged",
+        "monad_booted",
+        "witness_exchange",
+        "proposal_emitted",
+        "continuity_check",
+        "compiler_decision",
+        "shell_enabled",
+        "capability_registered",
+        "capability_routed",
+        "capability_authorization_started",
+        "capability_authorization_callback_received",
+        "capability_authorized",
+        "capability_executed"
+      ]
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "session_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^session-[a-z0-9-]+$"
+    },
+    "actor": {
+      "type": "string",
+      "enum": [
+        "principal",
+        "eidolon",
+        "borganik",
+        "system"
+      ]
+    },
+    "payload": {
+      "type": "object"
+    },
+    "evidence_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^evt-[a-z0-9-]+$"
+      },
+      "uniqueItems": true
+    },
+    "prior_event_hash": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "event_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  }
+}

package/schemas/CapabilityExecution.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "CapabilityExecution.schema.json",
+  "title": "CapabilityExecution",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "execution_id",
+    "capability_id",
+    "session_id",
+    "provider_kind",
+    "request_summary",
+    "response_summary",
+    "status",
+    "executed_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "execution_id": {
+      "type": "string",
+      "pattern": "^exec-[a-z0-9-]+$"
+    },
+    "capability_id": {
+      "type": "string",
+      "pattern": "^(cap-[a-z0-9-]+|oauth-[a-z0-9-]+|api-[a-z0-9-]+|ollama-[a-z0-9-]+)$"
+    },
+    "session_id": {
+      "type": "string",
+      "pattern": "^session-[a-z0-9-]+$"
+    },
+    "provider_kind": {
+      "type": "string",
+      "enum": ["oauth_api", "api", "ollama"]
+    },
+    "request_summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "response_summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["succeeded", "failed"]
+    },
+    "executed_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}