@helmetfire-labs/cartridge-common 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,206 @@
+# @helmetfire-labs/cartridge-common
+
+Shared logging, error boundaries, trace helpers, durable reducer runtime, and trust infrastructure for AgentRuntime cartridges.
+
+This is a **library**, not a service. It provides the building blocks that all cartridges use for structured logging, error handling, multi-agent state isolation, and auditable state management.
+
+## Philosophy
+
+Every cartridge is a process with a behavioral contract. It declares what it does (action schema), what it's allowed to do (process policy), and how its state changes over time (reducer). All three are cryptographically bound — the action log is hash-chained, the policy is signed at write time, and the verifier can replay any cartridge's history to prove correctness.
+
+Infrastructure cartridges never expose admin APIs. The operator reads logs and edits config — the Conversational Control Plane. Trust is earned through observable behavior: verified action logs, policy compliance, and operator attestation feed a scoring engine that automates tier promotion from T0 (untrusted) through T5 (community-verified).
+
+## Install
+
+```bash
+npm install @helmetfire-labs/cartridge-common
+```
+
+## Exports
+
+### Logging & Observability
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `logEvent`, `LogEventOpts` | `logger` | Structured log event emitter |
+| `TAGS`, `isValidTag`, `TagKey`, `TagValue` | `tags` | Standard tag constants and validation |
+| `ACTIONS`, `ActionKey`, `ActionValue` | `actions` | Standard action verb constants |
+| `generateTraceId`, `extractTraceId`, `traceMetadata`, `extractHop`, `NO_TRACE` | `trace` | Trace ID generation and propagation |
+| `extractShape` | `shape` | Error shape extraction |
+| `withErrorBoundary`, `classifyError`, `ERROR_SHAPES`, `ErrorShapeKey` | `errors` | Error boundary wrapper and classification |
+
+### Namespace Scope (Multi-Agent State Isolation)
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `extractNamespace`, `ScopedStateManager` | `namespace` | Multi-agent namespace isolation |
+| `ScopeMode`, `CrossNamespacePolicy`, `NamespaceScopeConfig`, `NamespaceInfo` | `namespace` | Namespace type definitions |
+
+### Durable Reducer Runtime
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `sha256`, `hashState`, `hashLine` | `durable-reducer` | Cryptographic hashing for state and action logs |
+| `DurableReducer`, `DurableActionLogEntry`, `VerifyResult`, `VerifyFailure` | `durable-reducer` | Reducer types and verification result types |
+| `DurableDispatcher`, `DispatcherConfig` | `durable-dispatcher` | Persistent dispatcher with hash-chained action logging |
+| `verify` | `verify` | Replay-based action log verification |
+| `containerReducer`, `containerActionSchema`, `ContainerStatus`, `ContainerState`, `ContainerAction` | `container-reducer` | Built-in reducer for container lifecycle |
+
+### Action Schemas
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `defineActionSchema`, `action`, `writeActionSchema`, `getSchemaHash`, `validateAction` | `action-schema` | Schema definition, validation, and persistence |
+| `ActionSchema`, `ActionVariant`, `FieldType` | `action-schema` | Schema type definitions |
+
+### Process Policy
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `hashPolicy`, `writePolicy`, `readPolicy`, `verifyPolicy` | `policy` | Cryptographically-verified process policy lifecycle |
+| `isNetworkAllowed`, `isFilesystemAllowed`, `isSpawnAllowed` | `policy` | Runtime permission checks |
+| `DEFAULT_POLICY`, `INSTALL_POLICY` | `policy` | Standard policy presets |
+| `CartridgePolicy`, `FilesystemPolicy`, `NetworkPolicy`, `NetworkEndpoint`, `ProcessPolicy`, `PolicyVerifyResult` | `policy` | Policy type definitions |
+
+### Trust Tiers & Scoring
+
+| Export | Module | Description |
+|--------|--------|-------------|
+| `evaluateTrust`, `checkT3`, `checkT4` | `trust-tiers` | Automated trust tier evaluation (T0–T5) |
+| `TrustTier`, `TierCheck`, `TrustAssessment` | `trust-tiers` | Trust tier type definitions |
+| `computeTrustDelta`, `applyDecay`, `updateTrustScore`, `computeTrustBadge`, `badgeLabel` | `trust-score` | T5 consensus trust scoring engine |
+| `countAnchorConsistency`, `recencyWeight`, `getOperatorWeight`, `initialTrustScoreState` | `trust-score` | Scoring utilities and initial state |
+| `OperatorTier`, `TrustBadge`, `TrustSignal`, `TrustScoreState`, `AnchorConsistencyInput` | `trust-score` | Scoring type definitions |
+
+## Durable Reducer Runtime
+
+The reducer runtime gives every cartridge an auditable, replay-verifiable state machine.
+
+```typescript
+import {
+  DurableDispatcher,
+  containerReducer,
+  type ContainerState,
+  type ContainerAction,
+} from "@helmetfire-labs/cartridge-common";
+
+// Create a dispatcher — persists hash-chained action.log
+const dispatcher = new DurableDispatcher<ContainerState, ContainerAction>({
+  reducer: containerReducer,
+  configDir: "./config",
+  skipProjection: true, // don't write clear.json (incremental integration)
+});
+
+// Dispatch typed actions — each entry gets a stateHash binding
+dispatcher.dispatch({ type: "start", name: "registry", pid: 1234, timestamp: Date.now() });
+
+// Verify the log — replays all actions and checks hash chain integrity
+import { verify } from "@helmetfire-labs/cartridge-common";
+const result = await verify(containerReducer, "./config/action.log");
+// result.ok === true if the log is tamper-free
+```
+
+### Action Schemas
+
+Define typed, validated action schemas for your reducer:
+
+```typescript
+import { defineActionSchema, action } from "@helmetfire-labs/cartridge-common";
+
+const schema = defineActionSchema("my-cartridge", [
+  action("init", { name: "string" }),
+  action("update", { value: "number", reason: "string?" }),  // ? = optional
+  action("reset"),
+]);
+```
+
+## Process Policy
+
+Self-declared, cryptographically-verified permissions for cartridge sandboxing:
+
+```typescript
+import { writePolicy, verifyPolicy, isNetworkAllowed } from "@helmetfire-labs/cartridge-common";
+
+// Write a signed policy to config/
+await writePolicy("./config", {
+  filesystem: { read: ["./data/**"], write: ["./state/**"], deny: ["/etc/**"] },
+  network: { allow: [{ host: "api.example.com", port: 443 }], denyAll: false },
+  process: { allowSpawn: false, allowedCommands: [] },
+});
+
+// Verify policy hasn't been tampered with
+const result = await verifyPolicy("./config");
+// result.ok === true
+
+// Runtime permission checks
+isNetworkAllowed(policy, "api.example.com", 443); // true
+```
+
+## Namespace Scope (Multi-Agent State Isolation)
+
+When multiple agents connect to the same SSE MCP tool server, each agent needs its own isolated state. The supervisor assigns each agent a namespace via `?ns=<name>` on the SSE URL. Agents never control their own namespace — the supervisor asserts the identity.
+
+```typescript
+import { extractNamespace, ScopedStateManager } from "@helmetfire-labs/cartridge-common";
+
+const state = new ScopedStateManager({
+  mode: "isolated",      // "isolated" | "shared" | "hybrid"
+  crossNamespace: "allow" // "allow" | "log" | "deny"
+}, "brw");
+
+const ns = extractNamespace(req.url); // e.g. "claude" from ?ns=claude
+state.registerSession(transport.sessionId, ns);
+const store = state.getStore(transport.sessionId, "view_page");
+```
+
+### Scope Modes
+
+| Mode | Behavior |
+|------|----------|
+| `isolated` | Each agent gets its own state partition |
+| `shared` | All agents share one state pool, `ns` tracks attribution |
+| `hybrid` | Some tools isolated, some shared (configured via `sharedTools`) |
+
+### Cross-Namespace Policy
+
+| Policy | Behavior |
+|--------|----------|
+| `allow` | No enforcement (default, for development) |
+| `log` | Access permitted but logged with attribution |
+| `deny` | Access rejected, escalation requires attributed override |
+
+## Standard Tags
+
+| Key | Tag | Cartridge |
+|-----|-----|-----------|
+| `mutex` | `mtx` | mcp-mutex |
+| `semaphore` | `sem` | mcp-semaphore |
+| `readonly` | `rdo` | mcp-readonly |
+| `retry` | `rty` | mcp-retry |
+| `timeout` | `tmo` | mcp-timeout |
+| `circuitBreaker` | `brk` | mcp-circuit-breaker |
+| `router` | `rtr` | mcp-router |
+| `cache` | `cch` | mcp-cache |
+| `auth` | `aut` | mcp-auth |
+| `transform` | `tfm` | mcp-transform |
+| `sanitize` | `san` | mcp-sanitize |
+| `webhook` | `whk` | mcp-webhook |
+| `cron` | `crn` | mcp-cron |
+| `audit` | `aud` | mcp-audit |
+| `relay` | `rly` | mcp-relay |
+| `mock` | `mck` | mcp-mock |
+| `shadow` | `shd` | mcp-shadow |
+| `bridge` | `brg` | mcp-bridge |
+| `tee` | `tee` | mcp-tee |
+| `approval` | `apv` | mcp-approval |
+| `verify` | `vfy` | mcp-verify |
+| `browser` | `brw` | tools-browser |
+| `namespace` | `nsp` | namespace scope |
+
+## Build
+
+```bash
+npm run build       # compile TypeScript
+npm run typecheck   # type-check only
+npm test            # run tests (239 tests)
+```

package/dist/action-schema.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Action schema — runtime-inspectable declaration of a cartridge's action types.
+ *
+ * TypeScript types are erased at runtime. The action schema bridges this gap:
+ * cartridge authors declare their action variants as data (not just types),
+ * and the schema generator outputs action-schema.json for the marketplace.
+ *
+ * The schema serves three purposes:
+ *   1. Marketplace declaration — "here are the actions this cartridge can take"
+ *   2. Verification input — auditors know what action types to expect
+ *   3. Population consensus — the registry compares action distributions
+ *
+ * Usage:
+ *   const schema = defineActionSchema("container", [
+ *     action("start", { ts: "number" }),
+ *     action("ready", { pid: "number", port: "number?", ts: "number" }),
+ *     action("stop", { reason: "string", ts: "number" }),
+ *     // ...
+ *   ]);
+ *
+ *   writeActionSchema(configDir, schema);
+ *   // → config/action-schema.json
+ *
+ * Patent M: Reducer-Based Auditable Cartridge Runtime
+ */
+export type FieldType = "string" | "number" | "boolean" | "string?" | "number?" | "boolean?" | "unknown";
+export interface ActionVariant {
+    /** The discriminant value (e.g. "start", "stop", "crash") */
+    type: string;
+    /** Field name → type. Every variant implicitly has `type: string`. */
+    fields: Record<string, FieldType>;
+    /** Human-readable description of what this action represents */
+    description?: string;
+}
+export interface ActionSchema {
+    /** Schema format version */
+    version: 1;
+    /** Cartridge/reducer name */
+    name: string;
+    /** All declared action variants */
+    actions: ActionVariant[];
+    /** SHA-256 of the canonical JSON representation (for identity binding) */
+    hash: string;
+    /** When this schema was generated */
+    generatedAt: number;
+}
+/**
+ * Declare a single action variant.
+ */
+export declare function action(type: string, fields: Record<string, FieldType>, description?: string): ActionVariant;
+/**
+ * Build a complete action schema from declared variants.
+ * Computes the hash over the canonical representation (sorted, no whitespace).
+ */
+export declare function defineActionSchema(name: string, actions: ActionVariant[]): ActionSchema;
+/**
+ * Write action-schema.json to the cartridge's config/ directory.
+ */
+export declare function writeActionSchema(configDir: string, schema: ActionSchema): void;
+/**
+ * Get just the hash of a schema (for embedding in static.json).
+ */
+export declare function getSchemaHash(schema: ActionSchema): string;
+/**
+ * Validate that an action payload conforms to a declared schema.
+ * Returns null if valid, or an error string if not.
+ */
+export declare function validateAction(actionPayload: {
+    type: string;
+    [key: string]: unknown;
+}, schema: ActionSchema): string | null;

package/dist/action-schema.js

@@ -0,0 +1,94 @@
+/**
+ * Action schema — runtime-inspectable declaration of a cartridge's action types.
+ *
+ * TypeScript types are erased at runtime. The action schema bridges this gap:
+ * cartridge authors declare their action variants as data (not just types),
+ * and the schema generator outputs action-schema.json for the marketplace.
+ *
+ * The schema serves three purposes:
+ *   1. Marketplace declaration — "here are the actions this cartridge can take"
+ *   2. Verification input — auditors know what action types to expect
+ *   3. Population consensus — the registry compares action distributions
+ *
+ * Usage:
+ *   const schema = defineActionSchema("container", [
+ *     action("start", { ts: "number" }),
+ *     action("ready", { pid: "number", port: "number?", ts: "number" }),
+ *     action("stop", { reason: "string", ts: "number" }),
+ *     // ...
+ *   ]);
+ *
+ *   writeActionSchema(configDir, schema);
+ *   // → config/action-schema.json
+ *
+ * Patent M: Reducer-Based Auditable Cartridge Runtime
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { sha256 } from "./durable-reducer.js";
+// ── Builder ─────────────────────────────────────────────────────────────────
+/**
+ * Declare a single action variant.
+ */
+export function action(type, fields, description) {
+    return { type, fields, description };
+}
+/**
+ * Build a complete action schema from declared variants.
+ * Computes the hash over the canonical representation (sorted, no whitespace).
+ */
+export function defineActionSchema(name, actions) {
+    // Sort actions by type for canonical ordering
+    const sorted = [...actions].sort((a, b) => a.type.localeCompare(b.type));
+    // Canonical representation for hashing (no whitespace, sorted keys)
+    const canonical = JSON.stringify({ name, actions: sorted });
+    const hash = sha256(canonical);
+    return {
+        version: 1,
+        name,
+        actions: sorted,
+        hash,
+        generatedAt: Date.now(),
+    };
+}
+// ── Persistence ─────────────────────────────────────────────────────────────
+/**
+ * Write action-schema.json to the cartridge's config/ directory.
+ */
+export function writeActionSchema(configDir, schema) {
+    const filePath = resolve(configDir, "action-schema.json");
+    writeFileSync(filePath, JSON.stringify(schema, null, 2), "utf-8");
+}
+/**
+ * Get just the hash of a schema (for embedding in static.json).
+ */
+export function getSchemaHash(schema) {
+    return schema.hash;
+}
+// ── Validation ──────────────────────────────────────────────────────────────
+/**
+ * Validate that an action payload conforms to a declared schema.
+ * Returns null if valid, or an error string if not.
+ */
+export function validateAction(actionPayload, schema) {
+    const variant = schema.actions.find(a => a.type === actionPayload.type);
+    if (!variant) {
+        return `unknown action type: "${actionPayload.type}" (declared: ${schema.actions.map(a => a.type).join(", ")})`;
+    }
+    for (const [field, fieldType] of Object.entries(variant.fields)) {
+        const value = actionPayload[field];
+        const isOptional = fieldType.endsWith("?");
+        const baseType = fieldType.replace("?", "");
+        if (value === undefined || value === null) {
+            if (!isOptional) {
+                return `missing required field "${field}" on action "${actionPayload.type}"`;
+            }
+            continue;
+        }
+        if (baseType !== "unknown" && typeof value !== baseType) {
+            return `field "${field}" on action "${actionPayload.type}": expected ${baseType}, got ${typeof value}`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=action-schema.js.map

package/dist/action-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.js","sourceRoot":"","sources":["../src/action-schema.ts"],"names":[],"mappings":"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"}

package/dist/actions.d.ts

@@ -30,6 +30,10 @@ export declare const ACTIONS: {
     readonly pending: "pending";
     readonly approved: "approved";
     readonly rejected: "rejected";
+    readonly verify: "verify";
+    readonly mismatch: "mismatch";
+    readonly signed: "signed";
+    readonly anchored: "anchored";
 };
 export type ActionKey = keyof typeof ACTIONS;
 export type ActionValue = (typeof ACTIONS)[ActionKey];

package/dist/actions.js

@@ -39,5 +39,10 @@ export const ACTIONS = {
     pending: 'pending',
     approved: 'approved',
     rejected: 'rejected',
+    // Verification
+    verify: 'verify',
+    mismatch: 'mismatch',
+    signed: 'signed',
+    anchored: 'anchored',
 };
 //# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IAExB,UAAU;IACV,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,EAAE,EAAE,IAAI;IACR,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAElB,QAAQ;IACR,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IAEd,kBAAkB;IAClB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IAEtB,QAAQ;IACR,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IAEtB,OAAO;IACP,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAElB,YAAY;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACZ,CAAC"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IAExB,UAAU;IACV,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,EAAE,EAAE,IAAI;IACR,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAElB,QAAQ;IACR,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IAEd,kBAAkB;IAClB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IAEtB,QAAQ;IACR,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IAEtB,OAAO;IACP,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAElB,YAAY;IACZ,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAEhB,WAAW;IACX,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IAEpB,eAAe;IACf,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/container-reducer.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Container lifecycle reducer — the first DurableReducer adopter.
+ *
+ * Extracts the container state machine (previously implicit in Container.ts
+ * and ContainerManager.ts) into a pure, testable function. Every legal
+ * container lifecycle transition is one case in the switch. Illegal
+ * transitions return the input state unchanged.
+ *
+ * State machine:
+ *
+ *                          start
+ *  ┌──────────┐   ────────────────── ▶ ┌──────────┐
+ *  │ stopped  │                        │ starting │
+ *  └──────────┘                        └──────────┘
+ *       ▲                                │         │
+ *       │                        ready   │    err  │
+ *       │                                ▼         ▼
+ *       │                            ┌─────────┐  ┌─────────┐
+ *       │                            │ running │  │ crashed │
+ *       │ ◀──── stop/kill ───────────│         │◀─┘         │
+ *       │                            └─────────┘            │
+ *       │                              │  │  ▲              │
+ *       │                     freeze   │  │  └──────────────┘
+ *       │                              ▼  │ thaw
+ *       │                            ┌─────────┐
+ *       │ ◀──── stop/kill ───────────│ frozen  │
+ *       │                            └─────────┘
+ *       │
+ *       │        health_fail         ┌────────────┐
+ *       │ ◀──── stop/kill ───────────│health-fail │
+ *       │                            └────────────┘
+ *       │                              ▲
+ *       │                              │ health_fail (consecutive)
+ *       │                              │
+ *       └──────────────────────────── running
+ *                                      │
+ *                                      │ throttle
+ *                                      ▼
+ *                                    ┌───────────┐
+ *                                    │ throttled │
+ *                                    └───────────┘
+ *
+ * Patent M: Reducer-Based Auditable Cartridge Runtime
+ */
+import type { DurableReducer } from "./durable-reducer.js";
+import { type ActionSchema } from "./action-schema.js";
+export type ContainerStatus = "stopped" | "starting" | "running" | "crashed" | "frozen" | "throttled" | "health-failing";
+export interface ContainerState {
+    status: ContainerStatus;
+    pid: number | null;
+    port: number | null;
+    muted: boolean;
+    startedAt: number | null;
+    updatedAt: number;
+}
+export type ContainerAction = {
+    type: "start";
+    ts: number;
+} | {
+    type: "ready";
+    pid: number;
+    port?: number;
+    ts: number;
+} | {
+    type: "stop";
+    reason: string;
+    ts: number;
+} | {
+    type: "crash";
+    exitCode: number;
+    signal?: string;
+    ts: number;
+} | {
+    type: "freeze";
+    ts: number;
+} | {
+    type: "thaw";
+    ts: number;
+} | {
+    type: "kill";
+    reason: string;
+    ts: number;
+} | {
+    type: "health_fail";
+    consecutive: number;
+    ts: number;
+} | {
+    type: "health_recover";
+    ts: number;
+} | {
+    type: "mute";
+    ts: number;
+} | {
+    type: "unmute";
+    ts: number;
+} | {
+    type: "throttle";
+    ts: number;
+} | {
+    type: "unthrottle";
+    ts: number;
+};
+export declare const containerReducer: DurableReducer<ContainerState, ContainerAction>;
+export declare const containerActionSchema: ActionSchema;