@vorionsys/runtime 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `@vorionsys/runtime` will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.2] - 2026-02-17
+
+### Changed
+- Standardized package metadata for npm publish
+
+## [0.1.1] - 2025-02-11
+
+### Changed
+
+- TrustFacade trust tier names and score ranges now derived from `@vorionsys/shared-constants` (single source of truth for the 8-tier trust model).
+- Improved trust-facade types to export `sharedScoreToTier` from shared-constants.
+
+### Fixed
+
+- Gate trust cache correctly handles admission expiration checks.
+
+## [0.1.0] - 2025-01-31
+
+### Added
+
+- **TrustFacade** -- Unified trust interface combining Gate Trust (admission control) and Dynamic Trust (per-action authorization).
+  - `admit()` -- one-time agent registration with observation-tier-based scoring.
+  - `authorize()` -- per-action authorization with <50ms latency target.
+  - `fullCheck()` -- combined admission + authorization in a single call.
+  - `recordSignal()` -- asymmetric trust signal processing (10:1 loss-to-gain ratio).
+  - `revoke()` -- immediate agent revocation with cache invalidation.
+  - Observation tiers (BLACK_BOX / GRAY_BOX / WHITE_BOX) with trust score ceilings.
+  - Decision tiers (GREEN / YELLOW / RED) with tier-appropriate constraints and refinements.
+- **ProofCommitter** -- Zero-latency cryptographic proof system.
+  - Synchronous SHA-256 hash commitment (<1ms hot path).
+  - Async Merkle-tree batching with configurable buffer size and flush interval.
+  - Optional Ed25519 signing for batch integrity.
+  - `InMemoryProofStore` for testing and development.
+- **IntentPipeline** -- End-to-end intent orchestration.
+  - Full lifecycle: Intent -> Gate Check -> Authorization -> Execution -> Proof.
+  - Pluggable execution handlers per action type.
+  - Automatic trust signal recording on execution outcomes.
+  - Quick `check()` for authorization-only queries.
+  - Built-in metrics (totalIntents, allowRate, avgProcessingTimeMs).
+- **SQLiteProofStore** -- Persistent proof storage with WAL mode and prepared statements.
+- **SQLiteTrustStore** -- Persistent agent trust records and signal history with WAL mode.
+- **Logger** -- pino-based logger with pretty-printing in development.
+- Subpath exports for tree-shakeable imports (`/trust-facade`, `/proof-committer`, `/intent-pipeline`, `/stores`).
+
+[0.1.1]: https://github.com/vorionsys/vorion/compare/@vorionsys/runtime@0.1.0...@vorionsys/runtime@0.1.1
+[0.1.0]: https://github.com/vorionsys/vorion/releases/tag/@vorionsys/runtime@0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Vorion
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,6 +1,8 @@
 # @vorionsys/runtime
 
-Orchestration layer for AI agent governance. Combines Gate Trust (admission control) and Dynamic Trust (real-time scoring) into a unified, fast decision system.
+Orchestration layer for AI agent governance, built on the [Vorion](https://github.com/vorionsys/vorion) trust framework and aligned with the BASIS (Baseline Authority for Safe & Interoperable Systems) specification.
+
+Combines **Gate Trust** (one-time admission control) and **Dynamic Trust** (per-action real-time scoring) into a unified, fast decision system with cryptographic proof of every governance decision.
 
 ## Installation
 
@@ -8,55 +10,118 @@ Orchestration layer for AI agent governance. Combines Gate Trust (admission cont
 npm install @vorionsys/runtime
 ```
 
+**Peer dependencies** (optional, enhance functionality):
+
+```bash
+npm install @vorionsys/atsf-core @vorionsys/contracts
+```
+
 ## Quick Start
 
 ```typescript
-import { createTrustFacade } from '@vorionsys/runtime';
+import {
+  createTrustFacade,
+  createProofCommitter,
+  createIntentPipeline,
+} from '@vorionsys/runtime';
 
+// 1. Create the trust facade (Gate Trust + Dynamic Trust)
 const facade = createTrustFacade();
 
-// Admit an agent (Gate Trust)
+// 2. Create the proof committer (cryptographic audit trail)
+const committer = createProofCommitter();
+
+// 3. Wire them together with the intent pipeline
+const pipeline = createIntentPipeline(facade, committer);
+
+// 4. Admit an agent (Gate Trust - "the door")
 const admission = await facade.admit({
   agentId: 'agent-123',
   name: 'DataProcessor',
-  capabilities: ['read:*', 'write:documents'],
+  capabilities: ['read:data', 'write:reports'],
   observationTier: 'GRAY_BOX',
 });
 
-// Authorize an action (Dynamic Trust)
+console.log(admission.admitted);          // true
+console.log(admission.initialScore);      // 200 (GRAY_BOX initial)
+console.log(admission.observationCeiling); // 800
+
+// 5. Authorize an action (Dynamic Trust - "the handshake")
 const auth = await facade.authorize('agent-123', {
   type: 'read',
-  resource: 'documents/report.pdf',
+  resource: 'data/users',
 });
 
 if (auth.allowed) {
-  // Action permitted - execute with constraints
-  console.log('Tier:', auth.tier);
-  console.log('Constraints:', auth.constraints);
+  console.log('Decision tier:', auth.tier);         // 'GREEN'
+  console.log('Constraints:', auth.constraints);    // { timeoutMs, maxOperations, ... }
 }
 ```
 
-## Features
+## What It Provides
+
+| Component | Purpose |
+|---|---|
+| **TrustFacade** | Unified API combining gate trust (admission) and dynamic trust (per-action authorization) with an 8-tier trust model (T0-T7) |
+| **ProofCommitter** | Zero-latency synchronous hash commitment (<1ms) with async Merkle-tree batching and optional Ed25519 signing |
+| **IntentPipeline** | End-to-end orchestration: Intent -> Gate Check -> Authorization -> Execution -> Proof |
+| **SQLiteProofStore** | Persistent proof storage backed by better-sqlite3 with WAL mode |
+| **SQLiteTrustStore** | Persistent agent trust records and signal history backed by better-sqlite3 |
+| **InMemoryProofStore** | In-memory proof store for testing and development |
+
+## Core Concepts
+
+### Trust Tiers (T0-T7)
+
+Agents are assigned a numeric trust score (0-1000) that maps to one of eight tiers:
+
+| Tier | Name | Score Range |
+|------|------|-------------|
+| T0 | Untrusted | 0-99 |
+| T1 | Provisional | 100-199 |
+| T2 | Basic | 200-349 |
+| T3 | Monitored | 350-499 |
+| T4 | Standard | 500-649 |
+| T5 | Trusted | 650-799 |
+| T6 | Elevated | 800-899 |
+| T7 | Autonomous | 900-1000 |
+
+### Observation Tiers
+
+Agent visibility determines the maximum trust score (ceiling) an agent can achieve:
+
+- **BLACK_BOX** -- Opaque internals, ceiling at 500 (max T3)
+- **GRAY_BOX** -- Partial visibility, ceiling at 800 (max T5)
+- **WHITE_BOX** -- Full visibility, ceiling at 1000 (max T7)
+
+### Decision Tiers
+
+Every authorization returns one of three decision tiers:
+
+- **GREEN** -- Allowed with standard constraints
+- **YELLOW** -- Allowed with additional constraints and refinement options
+- **RED** -- Denied
 
-- **TrustFacade**: Unified API combining gate trust and dynamic trust
-- **ProofCommitter**: Zero-latency proof event batching and commitment
-- **IntentPipeline**: Orchestrated intent processing with pluggable handlers
-- **SQLite Stores**: Persistent trust and proof stores backed by better-sqlite3
-- **Trust Signals**: Record success/failure signals that update agent trust scores
-- **Configurable**: Full configuration for thresholds, timeouts, and behavior
+### Asymmetric Trust Dynamics
+
+Trust is hard to earn and easy to lose. Decay and recovery dynamics are policy-configurable, preventing rapid trust escalation while enforcing accountability.
 
 ## Subpath Imports
 
+Each major component is available as a subpath import:
+
 ```typescript
-// Core facade
-import { createTrustFacade, TrustFacade } from '@vorionsys/runtime';
-import { createTrustFacade } from '@vorionsys/runtime/trust-facade';
+// Root -- all exports
+import { createTrustFacade, createProofCommitter, createIntentPipeline } from '@vorionsys/runtime';
+
+// Trust facade only
+import { createTrustFacade, TrustFacade } from '@vorionsys/runtime/trust-facade';
 
-// Intent pipeline
-import { createIntentPipeline } from '@vorionsys/runtime/intent-pipeline';
+// Proof committer only
+import { createProofCommitter, ProofCommitter } from '@vorionsys/runtime/proof-committer';
 
-// Proof committer
-import { createProofCommitter } from '@vorionsys/runtime/proof-committer';
+// Intent pipeline only
+import { createIntentPipeline, IntentPipeline } from '@vorionsys/runtime/intent-pipeline';
 
 // Persistent stores
 import { createSQLiteProofStore, createSQLiteTrustStore } from '@vorionsys/runtime/stores';
@@ -66,80 +131,397 @@ import { createSQLiteProofStore, createSQLiteTrustStore } from '@vorionsys/runti
 
 ### TrustFacade
 
-The primary API for agent governance:
+The primary API for agent governance. Implements the `TrustGate` interface.
 
 ```typescript
+import { createTrustFacade, type TrustFacadeConfig } from '@vorionsys/runtime';
+
 const facade = createTrustFacade({
-  // All config is optional with sensible defaults
+  // All fields are optional with sensible defaults
+  gateTrustCacheTtlMs: 3600000,       // Cache gate trust results for 1 hour
+  maxAuthorizationLatencyMs: 50,       // Target latency for authorize()
+  useAtsfForPersistence: true,         // Use ATSF-core for persistence
+  useA3iForDynamics: true,             // Use A3I for trust dynamics
+  primaryScoreSource: 'atsf',          // Primary source for trust scores
 });
+```
 
-// Admit agent (gate trust check)
-const admission = await facade.admit(credentials);
-// { admitted: boolean, tier: TrustTier, score: number, ... }
+#### `facade.admit(agent: AgentCredentials): Promise<AdmissionResult>`
 
-// Authorize action (dynamic trust check)
-const auth = await facade.authorize(agentId, action);
-// { allowed: boolean, tier: DecisionTier, reason: string, constraints: Constraints }
+Gate trust check -- called once at agent registration. Result is cached.
 
-// Full check (admit + authorize in one call)
-const result = await facade.fullCheck(credentials, action);
+```typescript
+const result = await facade.admit({
+  agentId: 'agent-123',
+  name: 'My Agent',
+  capabilities: ['read:data', 'write:reports'],
+  observationTier: 'WHITE_BOX',       // 'BLACK_BOX' | 'GRAY_BOX' | 'WHITE_BOX'
+  metadata: { version: '1.0' },       // optional
+});
+
+// AdmissionResult:
+// {
+//   admitted: boolean,
+//   initialTier: TrustTier,         // 0-7
+//   initialScore: number,           // e.g. 300 for WHITE_BOX
+//   observationCeiling: number,     // e.g. 1000 for WHITE_BOX
+//   capabilities: string[],
+//   expiresAt: Date,
+//   reason?: string,                // set when admitted === false
+// }
+```
 
-// Record trust signal
-await facade.recordSignal(agentId, {
-  type: 'success',
-  source: 'sdk',
-  weight: 0.1,
+#### `facade.authorize(agentId: string, action: Action): Promise<AuthorizationResult>`
+
+Dynamic trust check -- called on every action. Must be fast (<50ms target).
+
+```typescript
+const auth = await facade.authorize('agent-123', {
+  type: 'read',              // 'read' | 'write' | 'delete' | 'execute' | ...
+  resource: 'data/users',
+  context: { limit: 100 },   // optional
 });
+
+// AuthorizationResult:
+// {
+//   allowed: boolean,
+//   tier: DecisionTier,            // 'GREEN' | 'YELLOW' | 'RED'
+//   currentScore: number,
+//   currentTier: TrustTier,
+//   constraints?: Constraints,     // timeoutMs, maxOperations, resourceLimits
+//   refinements?: Refinement[],    // YELLOW decisions include refinement options
+//   reason: string,
+//   latencyMs: number,
+// }
 ```
 
+#### `facade.fullCheck(agent: AgentCredentials, action: Action): Promise<FullCheckResult>`
+
+Combined admission + authorization in a single call. Useful for first-time agent interactions.
+
+```typescript
+const result = await facade.fullCheck(agentCredentials, action);
+
+// FullCheckResult:
+// {
+//   admission: AdmissionResult,
+//   authorization?: AuthorizationResult,  // only present if admission.admitted === true
+// }
+```
+
+#### `facade.recordSignal(signal: TrustSignal): Promise<void>`
+
+Record a trust signal that updates the agent's dynamic trust score.
+
+```typescript
+await facade.recordSignal({
+  agentId: 'agent-123',
+  type: 'success',            // 'success' | 'failure' | 'violation' | 'neutral'
+  weight: 0.5,                // 0-1
+  source: 'execution-engine',
+  context: { intentId: '...' },  // optional
+});
+```
+
+#### `facade.getScore(agentId: string): Promise<number | null>`
+
+Returns the current trust score, or `null` if the agent is unknown.
+
+#### `facade.getTier(agentId: string): Promise<TrustTier | null>`
+
+Returns the current trust tier (0-7), or `null` if the agent is unknown.
+
+#### `facade.revoke(agentId: string, reason: string): Promise<void>`
+
+Revoke an agent's admission. Clears cached trust data and prevents future authorizations until re-admitted.
+
+---
+
 ### ProofCommitter
 
-Zero-latency proof event batching:
+Zero-latency cryptographic proof system. Synchronous hash commitment on the hot path (<1ms), with asynchronous Merkle-tree batching on the cold path.
 
 ```typescript
+import { createProofCommitter, type ProofCommitterConfig } from '@vorionsys/runtime';
+
 const committer = createProofCommitter({
-  batchSize: 100,
-  flushIntervalMs: 5000,
+  maxBufferSize: 100,        // Auto-flush when buffer reaches this size
+  flushIntervalMs: 100,      // Periodic flush interval
+  enableSigning: false,      // Enable Ed25519 signing
+  privateKey: undefined,     // Base64-encoded Ed25519 private key (required if signing enabled)
 });
+```
+
+#### `committer.commit(event: ProofEvent): string`
 
-// Commit proof events (batched automatically)
-committer.commit(proofEvent);
+Synchronous hot-path commitment. Returns a commitment ID. Target: <1ms.
 
-// Force flush
-await committer.flush();
+```typescript
+const commitmentId = committer.commit({
+  type: 'intent_submitted',   // ProofEventType
+  entityId: 'agent-123',
+  payload: { action: 'read', resource: 'data/users' },
+  timestamp: Date.now(),
+  correlationId: 'corr-456',  // optional, for linking related events
+});
 ```
 
+**ProofEventType values:** `'intent_submitted'` | `'decision_made'` | `'execution_started'` | `'execution_completed'` | `'trust_signal'` | `'agent_admitted'` | `'agent_revoked'` | `'parity_violation'`
+
+#### `committer.flush(): Promise<void>`
+
+Force-flush the buffer. Builds a Merkle tree, optionally signs, and persists to the proof store.
+
+#### `committer.stop(): Promise<void>`
+
+Flush remaining events and stop the periodic flush timer. Call this on shutdown.
+
+#### `committer.getCommitment(commitmentId: string): Promise<ProofCommitment | null>`
+
+Retrieve a commitment from the store by ID.
+
+#### `committer.getCommitmentsForEntity(entityId: string): Promise<ProofCommitment[]>`
+
+Retrieve all commitments for a given entity (agent, intent, etc.).
+
+#### `committer.verifyCommitment(commitment: ProofCommitment): boolean`
+
+Verify a commitment's SHA-256 hash matches the original event.
+
+#### `committer.getMetrics()`
+
+Returns `{ totalCommitments, totalBatches, avgFlushTimeMs, bufferSize }`.
+
+#### `committer.getBufferSize(): number`
+
+Returns the number of uncommitted events in the buffer.
+
+---
+
 ### IntentPipeline
 
-Orchestrated intent processing:
+Orchestrates the full agent intent lifecycle: **Intent -> Gate Check -> Authorization -> Execution -> Proof**.
+
+```typescript
+import { createIntentPipeline, type IntentPipelineConfig } from '@vorionsys/runtime';
+
+const pipeline = createIntentPipeline(trustFacade, proofCommitter, {
+  verboseLogging: false,       // Enable detailed logging
+  timeoutMs: 5000,             // Maximum processing time
+  autoRecordSignals: true,     // Auto-record trust signals on execution
+});
+```
+
+#### `pipeline.registerHandler(actionType: string, handler: ExecutionHandler): void`
+
+Register an execution handler for an action type.
 
 ```typescript
-const pipeline = createIntentPipeline({
-  handlers: [myHandler],
+pipeline.registerHandler('read', async (intent, context) => {
+  // Execute the intent
+  const data = await myDatabase.query(intent.action.resource);
+  return { success: true, result: data };
+});
+
+pipeline.registerHandler('write', async (intent, context) => {
+  try {
+    await myDatabase.write(intent.action.resource, intent.metadata);
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
 });
+```
+
+#### `pipeline.submit(credentials: AgentCredentials, action: Action, metadata?: Record<string, unknown>): Promise<IntentResult>`
 
-const result = await pipeline.process(intent);
-// { allowed: boolean, decision: Decision, proofId: string }
+Submit an intent for full processing (gate check, authorization, execution, proof).
+
+```typescript
+const result = await pipeline.submit(
+  {
+    agentId: 'agent-123',
+    name: 'DataProcessor',
+    capabilities: ['read:data'],
+    observationTier: 'GRAY_BOX',
+  },
+  { type: 'read', resource: 'data/users' },
+  { limit: 50 },  // optional metadata
+);
+
+// IntentResult:
+// {
+//   intentId: string,
+//   allowed: boolean,
+//   tier: DecisionTier,          // 'GREEN' | 'YELLOW' | 'RED'
+//   reason: string,
+//   commitmentId: string,        // proof commitment ID
+//   constraints?: string[],
+//   processingTimeMs: number,
+// }
 ```
 
+#### `pipeline.check(credentials: AgentCredentials, action: Action): Promise<{ allowed, tier, reason }>`
+
+Quick authorization check without execution.
+
+#### `pipeline.getMetrics()`
+
+Returns `{ totalIntents, allowedIntents, deniedIntents, avgProcessingTimeMs, allowRate }`.
+
+#### `pipeline.flushProofs(): Promise<void>`
+
+Flush all pending proof commitments.
+
+#### `pipeline.stop(): Promise<void>`
+
+Stop the pipeline and flush remaining proofs.
+
+---
+
 ### Persistent Stores
 
+SQLite-backed stores for production use. Both use WAL mode by default for better write concurrency.
+
+#### SQLiteProofStore
+
 ```typescript
-import { createSQLiteProofStore, createSQLiteTrustStore } from '@vorionsys/runtime/stores';
+import { createSQLiteProofStore } from '@vorionsys/runtime/stores';
+
+const proofStore = createSQLiteProofStore({
+  dbPath: './data/proofs.db',   // Use ':memory:' for in-memory
+  walMode: true,                // default: true
+});
+
+// Pass to ProofCommitter
+const committer = createProofCommitter({ maxBufferSize: 100 }, proofStore);
+
+// Query proofs
+const commitment = await proofStore.getCommitment('commitment-id');
+const batch = await proofStore.getBatch('batch-id');
+const entityProofs = await proofStore.getCommitmentsForEntity('agent-123');
+
+// Housekeeping
+proofStore.getStats();  // { batches: number, commitments: number }
+proofStore.close();     // Close DB connection on shutdown
+```
+
+#### SQLiteTrustStore
+
+```typescript
+import { createSQLiteTrustStore } from '@vorionsys/runtime/stores';
+
+const trustStore = createSQLiteTrustStore({
+  dbPath: './data/trust.db',    // Use ':memory:' for in-memory
+  walMode: true,                // default: true
+});
+
+// Save/retrieve agent trust records
+await trustStore.saveAgent(agentRecord);
+const agent = await trustStore.getAgent('agent-123');
+
+// Update scores
+await trustStore.updateScore('agent-123', 450, 3);
+
+// Revoke
+await trustStore.revokeAgent('agent-123', 'Policy violation');
+
+// Record and query trust signals
+await trustStore.recordSignal(signalRecord);
+const signals = await trustStore.getSignals('agent-123', 50);
 
-// Proof store
-const proofStore = createSQLiteProofStore({ path: './data/proofs.db' });
+// List active agents
+const agents = await trustStore.listActiveAgents();
 
-// Trust store
-const trustStore = createSQLiteTrustStore({ path: './data/trust.db' });
+// Housekeeping
+trustStore.getStats();  // { agents, activeAgents, signals }
+trustStore.close();
+```
+
+#### InMemoryProofStore
+
+```typescript
+import { InMemoryProofStore } from '@vorionsys/runtime';
+
+const store = new InMemoryProofStore();
+// Same ProofStore interface, useful for testing
+store.getStats();  // { batches: number, commitments: number }
+store.clear();     // Reset all data
+```
+
+---
+
+### Logger
+
+```typescript
+import { createLogger } from '@vorionsys/runtime';
+
+const logger = createLogger({
+  component: 'my-component',
+  level: 'debug',  // optional, defaults to LOG_LEVEL env var or 'info'
+});
+```
+
+Uses [pino](https://github.com/pinojs/pino) with pretty-printing in non-production environments.
+
+## Full Example: Intent Pipeline
+
+```typescript
+import {
+  createTrustFacade,
+  createProofCommitter,
+  createIntentPipeline,
+  createSQLiteProofStore,
+} from '@vorionsys/runtime';
+
+// Set up persistent proof storage
+const proofStore = createSQLiteProofStore({ dbPath: './data/proofs.db' });
+
+// Create the governance stack
+const facade = createTrustFacade();
+const committer = createProofCommitter({ maxBufferSize: 50 }, proofStore);
+const pipeline = createIntentPipeline(facade, committer, {
+  autoRecordSignals: true,
+});
+
+// Register execution handlers
+pipeline.registerHandler('read', async (intent) => {
+  const data = await fetchData(intent.action.resource);
+  return { success: true, result: data };
+});
+
+// Submit an intent
+const result = await pipeline.submit(
+  {
+    agentId: 'data-agent',
+    name: 'Data Agent',
+    capabilities: ['read:data'],
+    observationTier: 'GRAY_BOX',
+  },
+  { type: 'read', resource: 'data/reports' },
+);
+
+if (result.allowed) {
+  console.log(`Intent ${result.intentId} processed in ${result.processingTimeMs}ms`);
+  console.log(`Decision: ${result.tier}, Proof: ${result.commitmentId}`);
+} else {
+  console.log(`Denied: ${result.reason}`);
+}
+
+// Graceful shutdown
+await pipeline.stop();
+proofStore.close();
 ```
 
 ## TypeScript
 
+All types are exported from the root entry point:
+
 ```typescript
 import type {
-  TrustFacadeConfig,
+  // Trust Facade
   TrustGate,
+  TrustFacadeConfig,
   AgentCredentials,
   AdmissionResult,
   Action,
@@ -148,21 +530,47 @@ import type {
   TrustSignal,
   TrustTier,
   DecisionTier,
+  ObservationTier,
   Constraints,
+  Refinement,
+
+  // Proof Committer
   ProofEvent,
+  ProofEventType,
+  ProofCommitment,
+  ProofBatch,
   ProofCommitterConfig,
   ProofStore,
+
+  // Intent Pipeline
   Intent,
   IntentResult,
+  PipelineContext,
   IntentPipelineConfig,
   ExecutionHandler,
+
+  // Stores
   SQLiteProofStoreConfig,
   SQLiteTrustStoreConfig,
   TrustStore,
   AgentTrustRecord,
+  TrustSignalRecord,
+
+  // Logger
+  LoggerOptions,
 } from '@vorionsys/runtime';
 ```
 
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (peer dependency)
+
 ## License
 
-MIT
+[Apache-2.0](./LICENSE)
+
+## Links
+
+- [Vorion Monorepo](https://github.com/vorionsys/vorion)
+- [BASIS Specification](https://github.com/vorionsys/vorion/tree/main/docs) -- Baseline Authority for Safe & Interoperable Systems

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vorionsys/runtime",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Vorion Runtime - Orchestration layer for AI agent governance",
   "publishConfig": {
     "access": "public"
@@ -31,19 +31,23 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
-    "clean": "rm -rf dist"
+    "clean": "rimraf dist"
   },
   "dependencies": {
-    "@vorionsys/shared-constants": "*",
+    "@vorionsys/shared-constants": "^1.0.1",
     "better-sqlite3": "^11.0.0",
     "pino": "^9.0.0",
     "pino-pretty": "^11.0.0"
@@ -73,15 +77,23 @@
     "trust",
     "governance",
     "runtime",
-    "vorion"
+    "vorion",
+    "basis",
+    "safety",
+    "orchestration",
+    "proof",
+    "audit"
   ],
   "author": "Vorion <team@vorion.org>",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/voriongit/vorion.git",
+    "url": "git+https://github.com/vorionsys/vorion.git",
     "directory": "packages/runtime"
   },
+  "bugs": {
+    "url": "https://github.com/vorionsys/vorion/issues"
+  },
   "homepage": "https://vorion.org",
   "engines": {
     "node": ">=18.0.0"