@godman-protocols/soul 0.2.0

package/LICENSE

@@ -0,0 +1,156 @@
+                                 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 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 transformations
+      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, as 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.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      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 the 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 any other
+      Contribution embodied in the Work constitutes patent 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, You must include a
+          readable copy of the attribution notices contained within such
+          NOTICE file, as part of the Derivative Works and 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.
+
+   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.
+
+   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.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work 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 reproducing 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 exemplary 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 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 offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Godman Protocols / skingem1
+
+   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

@@ -0,0 +1,233 @@
+# SOUL — Constitutional Constraints and Safety
+
+
+[![npm version](https://img.shields.io/npm/v/@godman-protocols/soul.svg)](https://www.npmjs.com/package/@godman-protocols/soul)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node: >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
+> **v0.2.0** · Apache 2.0 · `@godman-protocols/soul` · Node 20+ / Deno 1.40+
+
+SOUL is the **lowest protocol layer** of the Godman stack — a constitutional engine that encodes an operator's safety constraints and kill switches into a signed, verifiable document that every agent in the swarm evaluates before taking any action.
+
+```bash
+npx skills add https://github.com/godman-protocols/soul
+# or
+npm install @godman-protocols/soul
+```
+
+---
+
+## The Problem
+
+AI agent safety constraints are usually implemented as system prompt instructions — text that can be lost during context compaction, overridden by a jailbreak, or simply forgotten after a session restart.
+
+This creates two critical failure modes:
+- **Constraint drift** — after enough context, agents stop honouring the rules they were given
+- **No auditability** — there is no verifiable record of which constraints were in force when an action was taken
+
+SOUL solves both problems by encoding constraints as a signed, immutable constitutional document that survives context compaction (because it lives in code, not chat) and produces an append-only audit trail for every evaluation.
+
+---
+
+## Core Concepts
+
+| Concept | What it is |
+|---------|-----------|
+| **Constitution** | The root document — operator identity, constraints, kill switches, HMAC signature |
+| **Constraint** | A named allow/deny/require rule scoped to a resource or action pattern |
+| **KillSwitch** | A non-negotiable halt trigger — fires when a runtime metric crosses a threshold |
+| **EvaluationResult** | The outcome of evaluating an action against the constitution |
+| **AuditEntry** | An append-only record of every evaluation (who, what, allowed/denied, why) |
+| **EnforcementLevel** | `hard` (abort), `soft` (warn + log), or `advisory` (log only) |
+
+---
+
+## Quickstart
+
+```typescript
+import {
+  createConstitution, signConstitution,
+  evaluateAction, checkKillSwitches, createAudit,
+} from '@godman-protocols/soul';
+
+const OPERATOR_SECRET = 'operator-hmac-secret';
+
+// 1. Define the constitution
+const draft = createConstitution(
+  'did:kognai:tarek',   // operator
+  [
+    {
+      name: 'Allow SCS-001 workspace access',
+      description: 'Agents may read and write the SCS-001 workspace',
+      action: 'allow',
+      enforcementLevel: 'hard',
+      scope: 'write:workspace/scs001/*',
+      bootstrapped: true,
+    },
+    {
+      name: 'Block production database writes',
+      description: 'No agent may write to the production database directly',
+      action: 'deny',
+      enforcementLevel: 'hard',
+      scope: 'write:db/prod/*',
+      bootstrapped: true,
+    },
+  ],
+  [
+    {
+      name: 'Low-engagement kill switch',
+      triggerCondition: 'views_per_30_posts < 500',
+      action: 'halt',
+    },
+    {
+      name: 'Memory ceiling',
+      triggerCondition: 'memory_gb > 22',
+      action: 'halt',
+    },
+  ]
+);
+
+// 2. Sign it (prevents tampering)
+const constitution = signConstitution(draft, OPERATOR_SECRET);
+
+// 3. Evaluate every action before execution
+const result = evaluateAction(constitution, 'did:kognai:messi', 'write:workspace/scs001/script.json');
+console.log(result.allowed);  // true
+console.log(result.reason);   // "Allowed by constraint 'Allow SCS-001 workspace access'"
+
+// 4. Audit every evaluation
+const audit = createAudit('did:kognai:messi', 'write:workspace/scs001/script.json', result);
+// → append to your audit store
+
+// 5. Check kill switches on each monitoring cycle
+const triggered = checkKillSwitches(constitution, {
+  views_per_30_posts: 320,  // below threshold
+  memory_gb: 14.5,
+});
+if (triggered) {
+  console.error(`KILL SWITCH: ${triggered.name}`);
+  process.exit(1);
+}
+```
+
+---
+
+## Evaluation Order
+
+`evaluateAction` uses a strict constitutional precedence:
+
+1. **Deny constraints first** — a matching `deny` rule wins regardless of any `allow` rules
+2. **Allow constraints** — the first matching `allow` rule grants access
+3. **Default deny** — if no rule matches, the action is denied (constitutional principle)
+
+This means: to permit an action, there must be an explicit `allow` constraint. The absence of a rule is a denial.
+
+---
+
+## Kill Switches
+
+Kill switches are **non-negotiable** — they cannot be delegated away or overridden by any other protocol:
+
+```typescript
+const switched = checkKillSwitches(constitution, {
+  views_per_30_posts: 280,  // < 500 → triggers halt
+  memory_gb: 18,
+  daily_oversight_hours: 7, // > 6 → triggers halt
+});
+
+if (switched) {
+  // switched.action === 'halt' | 'pause' | 'alert'
+  // Immediately stop the agent — no protocol override is valid
+}
+```
+
+**Supported operators in `triggerCondition`:** `>` · `<` · `>=` · `<=` · `==` · `!=`
+
+**Format:** `"metric_name operator threshold"` — e.g. `"memory_gb > 22"`, `"retention_pct < 20"`
+
+---
+
+## Scope Patterns
+
+Constraint scopes support wildcard matching:
+
+| Pattern | Matches |
+|---------|---------|
+| `*` | Any action |
+| `write:*` | Any write action |
+| `write:workspace/*` | Any write to workspace |
+| `write:workspace/scs001/*` | Any write to scs001 workspace |
+| `write:workspace/scs001/script.json` | Exact match only |
+
+---
+
+## Summer Yu Rule
+
+SOUL implements the "Summer Yu Rule" from the Kognai safety specification: **safety constraints must live in bootstrap files (SOUL constitutions, AGENTS.md, SOUL.md), never in chat context alone.** A constitution's `bootstrapped: true` flag marks constraints that must survive context compaction.
+
+---
+
+## Integration with Godman Protocols
+
+SOUL is **always the first check** in any protocol chain:
+
+| Layer | Check |
+|-------|-------|
+| **SOUL** (this) | Is the action constitutionally permitted? Are kill switches triggered? |
+| **PACT** | Does the requesting agent have a valid mandate for this action? |
+| **AMF** | Wrap the request in a verifiable envelope |
+| **LAX** | Route to the best runtime |
+| **DRS** | Allocate compute resources |
+| **SIGNAL** | Emit domain events |
+| **SCORE** | Evaluate outcome and update reputation |
+
+No other protocol overrides SOUL.
+
+---
+
+## API Reference
+
+See [`docs/api.md`](./docs/api.md) for the full API reference.
+
+---
+
+## Compatibility
+
+| Runtime | Status |
+|---------|--------|
+| Node.js 20+ | ✅ Tested |
+| Deno 1.40+ | ✅ Compatible |
+| Bun 1.0+ | ✅ Compatible |
+| Browser (ESM) | ⚠️ Requires `node:crypto` polyfill for HMAC |
+| OpenClaw v2026.3+ | ✅ ClaWHub listed |
+| Claude Code plugin | ✅ `.claude-plugin` included |
+
+---
+
+## Security Model
+
+- Constitution signing uses **HMAC-SHA256** over a canonical subset of fields — it proves the document was issued by the operator and has not been tampered with.
+- **Signature does not authenticate actions** — SOUL evaluates constitutions, not individual messages. Use AMF for message-level authentication.
+- Kill switches are evaluated in-process. For guaranteed enforcement in adversarial settings, run SOUL evaluations in a separate trusted process or use the kill switch `action: 'halt'` to trigger a hard process exit.
+
+---
+
+## Roadmap
+
+- [x] Core types and protocol spec
+- [x] Reference implementation (TypeScript)
+- [x] Constitutional evaluation (deny > allow > default-deny)
+- [x] Kill switch engine (numeric threshold operators)
+- [x] Audit log creation
+- [x] Smoke tests (11/11 PASS)
+- [ ] Python SDK
+- [ ] Constitution persistence (Supabase backend)
+- [ ] Multi-operator constitution merging
+- [ ] Kill switch webhook delivery
+- [ ] ClaWHub marketplace listing
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](./LICENSE)

package/dist/engine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core engine: constitution creation, evaluation, kill switches, audit
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+import type { AgentId, AuditEntry, Constraint, Constitution, EvaluationResult, KillSwitch, Timestamp } from './types.js';
+/**
+ * Create a Constitution document.
+ * Must be signed by the operator before use.
+ */
+export declare function createConstitution(operatorId: string, constraints: Omit<Constraint, 'id'>[], killSwitches: Omit<KillSwitch, 'id' | 'nonNegotiable'>[], options?: {
+    issuedAt?: Timestamp;
+}): Omit<Constitution, 'signature'> & {
+    signature: '';
+};
+/**
+ * Sign a constitution with the operator's secret.
+ */
+export declare function signConstitution(constitution: Constitution, operatorSecret: string): Constitution;
+/**
+ * Evaluate an action against the constitution.
+ *
+ * Matching order:
+ * 1. Check 'deny' constraints first (deny wins over allow)
+ * 2. Check 'require' constraints (must have a matching allow)
+ * 3. Check 'allow' constraints
+ * 4. Default: deny (constitutional principle — deny by default)
+ */
+export declare function evaluateAction(constitution: Constitution, agentId: AgentId, action: string): EvaluationResult;
+/**
+ * Check kill switch conditions against context.
+ * Context is a key-value map of runtime metrics.
+ *
+ * Trigger condition format: "key operator value"
+ * Supported operators: >, <, >=, <=, ==, !=
+ * Example: "views_per_30_posts < 500", "memory_gb > 22"
+ */
+export declare function checkKillSwitches(constitution: Constitution, context: Record<string, number | string | boolean>): KillSwitch | null;
+/**
+ * Create an audit entry from an evaluation result.
+ */
+export declare function createAudit(agentId: AgentId, action: string, evaluation: EvaluationResult): AuditEntry;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,UAAU,EAEV,YAAY,EAEZ,gBAAgB,EAChB,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,EACrC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,eAAe,CAAC,EAAE,EACxD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAO,GACrC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,EAAE,CAAA;CAAE,CAarD;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,MAAM,GACrB,YAAY,CAYd;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACb,gBAAgB,CAqClB;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACjD,UAAU,GAAG,IAAI,CAsBnB;AAMD;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,GAC3B,UAAU,CAQZ"}

package/dist/engine.js

@@ -0,0 +1,182 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core engine: constitution creation, evaluation, kill switches, audit
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constitution creation
+// ---------------------------------------------------------------------------
+/**
+ * Create a Constitution document.
+ * Must be signed by the operator before use.
+ */
+export function createConstitution(operatorId, constraints, killSwitches, options = {}) {
+    return {
+        version: '0.1',
+        operatorId,
+        issuedAt: options.issuedAt ?? new Date().toISOString(),
+        constraints: constraints.map((c) => ({ ...c, id: randomUUID() })),
+        killSwitches: killSwitches.map((k) => ({
+            ...k,
+            id: randomUUID(),
+            nonNegotiable: true,
+        })),
+        signature: '',
+    };
+}
+// ---------------------------------------------------------------------------
+// Signing
+// ---------------------------------------------------------------------------
+/**
+ * Sign a constitution with the operator's secret.
+ */
+export function signConstitution(constitution, operatorSecret) {
+    const payload = JSON.stringify({
+        version: constitution.version,
+        operatorId: constitution.operatorId,
+        issuedAt: constitution.issuedAt,
+        constraintCount: constitution.constraints.length,
+        killSwitchCount: constitution.killSwitches.length,
+    });
+    const signature = createHmac('sha256', operatorSecret)
+        .update(payload, 'utf8')
+        .digest('hex');
+    return { ...constitution, signature };
+}
+// ---------------------------------------------------------------------------
+// Scope matching
+// ---------------------------------------------------------------------------
+/**
+ * Match an action string against a scope pattern.
+ * Supports:
+ * - Exact match: 'read:workspace/scs001'
+ * - Wildcard: 'read:*', '*:workspace/*', '*'
+ * - Prefix: 'read:workspace/*' matches 'read:workspace/scs001/file.ts'
+ */
+function scopeMatches(pattern, action) {
+    if (pattern === '*')
+        return true;
+    if (pattern === action)
+        return true;
+    if (pattern.endsWith('*')) {
+        const prefix = pattern.slice(0, -1);
+        return action.startsWith(prefix);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate an action against the constitution.
+ *
+ * Matching order:
+ * 1. Check 'deny' constraints first (deny wins over allow)
+ * 2. Check 'require' constraints (must have a matching allow)
+ * 3. Check 'allow' constraints
+ * 4. Default: deny (constitutional principle — deny by default)
+ */
+export function evaluateAction(constitution, agentId, action) {
+    const now = new Date().toISOString();
+    // Check deny constraints first
+    for (const c of constitution.constraints) {
+        if (c.action === 'deny' && scopeMatches(c.scope, action)) {
+            return {
+                allowed: false,
+                constraintId: c.id,
+                enforcementLevel: c.enforcementLevel,
+                reason: `Denied by constraint '${c.name}': ${c.description}`,
+                evaluatedAt: now,
+            };
+        }
+    }
+    // Check allow constraints
+    for (const c of constitution.constraints) {
+        if (c.action === 'allow' && scopeMatches(c.scope, action)) {
+            return {
+                allowed: true,
+                constraintId: c.id,
+                enforcementLevel: c.enforcementLevel,
+                reason: `Allowed by constraint '${c.name}'`,
+                evaluatedAt: now,
+            };
+        }
+    }
+    // Default deny
+    return {
+        allowed: false,
+        constraintId: null,
+        enforcementLevel: 'hard',
+        reason: 'No matching allow constraint — denied by default (constitutional principle)',
+        evaluatedAt: now,
+    };
+}
+// ---------------------------------------------------------------------------
+// Kill switches
+// ---------------------------------------------------------------------------
+/**
+ * Check kill switch conditions against context.
+ * Context is a key-value map of runtime metrics.
+ *
+ * Trigger condition format: "key operator value"
+ * Supported operators: >, <, >=, <=, ==, !=
+ * Example: "views_per_30_posts < 500", "memory_gb > 22"
+ */
+export function checkKillSwitches(constitution, context) {
+    for (const ks of constitution.killSwitches) {
+        const parts = ks.triggerCondition.split(/\s+/);
+        if (parts.length !== 3)
+            continue;
+        const [key, op, rawVal] = parts;
+        if (!(key in context))
+            continue;
+        const actual = Number(context[key]);
+        const threshold = Number(rawVal);
+        if (isNaN(actual) || isNaN(threshold))
+            continue;
+        let triggered = false;
+        switch (op) {
+            case '>':
+                triggered = actual > threshold;
+                break;
+            case '<':
+                triggered = actual < threshold;
+                break;
+            case '>=':
+                triggered = actual >= threshold;
+                break;
+            case '<=':
+                triggered = actual <= threshold;
+                break;
+            case '==':
+                triggered = actual === threshold;
+                break;
+            case '!=':
+                triggered = actual !== threshold;
+                break;
+        }
+        if (triggered)
+            return ks;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Audit
+// ---------------------------------------------------------------------------
+/**
+ * Create an audit entry from an evaluation result.
+ */
+export function createAudit(agentId, action, evaluation) {
+    return {
+        id: randomUUID(),
+        agentId,
+        action,
+        evaluation,
+        timestamp: evaluation.evaluatedAt,
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Public API surface
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+export type { AgentId, Timestamp, Signature, EnforcementLevel, ConstraintAction, Constraint, KillSwitch, Constitution, EvaluationResult, AuditEntry, } from './types.js';
+export { createConstitution, signConstitution, evaluateAction, checkKillSwitches, createAudit, } from './engine.js';
+/** Protocol version constant */
+export declare const SOUL_VERSION: "0.2";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,gCAAgC;AAChC,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Public API surface
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+// Engine
+export { createConstitution, signConstitution, evaluateAction, checkKillSwitches, createAudit, } from './engine.js';
+/** Protocol version constant */
+export const SOUL_VERSION = '0.2';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,SAAS;AACT,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,gCAAgC;AAChC,MAAM,CAAC,MAAM,YAAY,GAAG,KAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core type definitions (skeleton)
+ * @version 0.1.0-skeleton
+ */
+export type AgentId = string;
+export type Timestamp = string;
+export type Signature = string;
+export type EnforcementLevel = 'hard' | 'soft' | 'advisory';
+export type ConstraintAction = 'allow' | 'deny' | 'require';
+/** A single constitutional constraint */
+export interface Constraint {
+    id: string;
+    name: string;
+    description: string;
+    action: ConstraintAction;
+    enforcementLevel: EnforcementLevel;
+    /** Resource or action pattern this constraint covers */
+    scope: string;
+    /** Whether this constraint survives context compaction (must be bootstrapped) */
+    bootstrapped: boolean;
+}
+/** A kill switch — a hard-stop trigger that halts an agent unconditionally */
+export interface KillSwitch {
+    id: string;
+    name: string;
+    /** Human-readable trigger condition */
+    triggerCondition: string;
+    /** What to do when triggered */
+    action: 'halt' | 'pause' | 'alert';
+    /** Cannot be delegated away or overridden */
+    nonNegotiable: true;
+}
+/** The root constitutional document for an operator */
+export interface Constitution {
+    version: '0.1';
+    operatorId: string;
+    /** ISO 8601 */
+    issuedAt: Timestamp;
+    constraints: Constraint[];
+    killSwitches: KillSwitch[];
+    /** Operator's signature over the constitution */
+    signature: Signature;
+}
+/** Result of evaluating an action against the constitution */
+export interface EvaluationResult {
+    allowed: boolean;
+    constraintId: string | null;
+    enforcementLevel: EnforcementLevel | null;
+    reason: string;
+    evaluatedAt: Timestamp;
+}
+/** Append-only audit log entry */
+export interface AuditEntry {
+    id: string;
+    agentId: AgentId;
+    action: string;
+    evaluation: EvaluationResult;
+    timestamp: Timestamp;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAC/B,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5D,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACnC,6CAA6C;IAC7C,aAAa,EAAE,IAAI,CAAC;CACrB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,iDAAiD;IACjD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,SAAS,CAAC;CACxB;AAED,kCAAkC;AAClC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core type definitions (skeleton)
+ * @version 0.1.0-skeleton
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@godman-protocols/soul",
+  "version": "0.2.0",
+  "description": "Constitutional Constraints and Safety \u2014 signed constitutions, kill switches, default-deny evaluation, audit trail",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npx tsx smoke.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "safety",
+    "constitutional-ai",
+    "kill-switches",
+    "constraints",
+    "audit-trail",
+    "godman-protocols",
+    "multi-agent"
+  ],
+  "author": "skingem1",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/godman-protocols/soul.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsx": "^4.7.0"
+  },
+  "dependencies": {},
+  "homepage": "https://github.com/skingem1/godman-protocols/tree/main/soul#readme",
+  "bugs": {
+    "url": "https://github.com/skingem1/godman-protocols/issues"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,210 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core engine: constitution creation, evaluation, kill switches, audit
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+
+import { createHmac, randomUUID } from 'node:crypto';
+import type {
+  AgentId,
+  AuditEntry,
+  Constraint,
+  ConstraintAction,
+  Constitution,
+  EnforcementLevel,
+  EvaluationResult,
+  KillSwitch,
+  Timestamp,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Constitution creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Constitution document.
+ * Must be signed by the operator before use.
+ */
+export function createConstitution(
+  operatorId: string,
+  constraints: Omit<Constraint, 'id'>[],
+  killSwitches: Omit<KillSwitch, 'id' | 'nonNegotiable'>[],
+  options: { issuedAt?: Timestamp } = {}
+): Omit<Constitution, 'signature'> & { signature: '' } {
+  return {
+    version: '0.1',
+    operatorId,
+    issuedAt: options.issuedAt ?? new Date().toISOString(),
+    constraints: constraints.map((c) => ({ ...c, id: randomUUID() })),
+    killSwitches: killSwitches.map((k) => ({
+      ...k,
+      id: randomUUID(),
+      nonNegotiable: true as const,
+    })),
+    signature: '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Signing
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a constitution with the operator's secret.
+ */
+export function signConstitution(
+  constitution: Constitution,
+  operatorSecret: string
+): Constitution {
+  const payload = JSON.stringify({
+    version: constitution.version,
+    operatorId: constitution.operatorId,
+    issuedAt: constitution.issuedAt,
+    constraintCount: constitution.constraints.length,
+    killSwitchCount: constitution.killSwitches.length,
+  });
+  const signature = createHmac('sha256', operatorSecret)
+    .update(payload, 'utf8')
+    .digest('hex');
+  return { ...constitution, signature };
+}
+
+// ---------------------------------------------------------------------------
+// Scope matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Match an action string against a scope pattern.
+ * Supports:
+ * - Exact match: 'read:workspace/scs001'
+ * - Wildcard: 'read:*', '*:workspace/*', '*'
+ * - Prefix: 'read:workspace/*' matches 'read:workspace/scs001/file.ts'
+ */
+function scopeMatches(pattern: string, action: string): boolean {
+  if (pattern === '*') return true;
+  if (pattern === action) return true;
+  if (pattern.endsWith('*')) {
+    const prefix = pattern.slice(0, -1);
+    return action.startsWith(prefix);
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate an action against the constitution.
+ *
+ * Matching order:
+ * 1. Check 'deny' constraints first (deny wins over allow)
+ * 2. Check 'require' constraints (must have a matching allow)
+ * 3. Check 'allow' constraints
+ * 4. Default: deny (constitutional principle — deny by default)
+ */
+export function evaluateAction(
+  constitution: Constitution,
+  agentId: AgentId,
+  action: string
+): EvaluationResult {
+  const now = new Date().toISOString();
+
+  // Check deny constraints first
+  for (const c of constitution.constraints) {
+    if (c.action === 'deny' && scopeMatches(c.scope, action)) {
+      return {
+        allowed: false,
+        constraintId: c.id,
+        enforcementLevel: c.enforcementLevel,
+        reason: `Denied by constraint '${c.name}': ${c.description}`,
+        evaluatedAt: now,
+      };
+    }
+  }
+
+  // Check allow constraints
+  for (const c of constitution.constraints) {
+    if (c.action === 'allow' && scopeMatches(c.scope, action)) {
+      return {
+        allowed: true,
+        constraintId: c.id,
+        enforcementLevel: c.enforcementLevel,
+        reason: `Allowed by constraint '${c.name}'`,
+        evaluatedAt: now,
+      };
+    }
+  }
+
+  // Default deny
+  return {
+    allowed: false,
+    constraintId: null,
+    enforcementLevel: 'hard',
+    reason: 'No matching allow constraint — denied by default (constitutional principle)',
+    evaluatedAt: now,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Kill switches
+// ---------------------------------------------------------------------------
+
+/**
+ * Check kill switch conditions against context.
+ * Context is a key-value map of runtime metrics.
+ *
+ * Trigger condition format: "key operator value"
+ * Supported operators: >, <, >=, <=, ==, !=
+ * Example: "views_per_30_posts < 500", "memory_gb > 22"
+ */
+export function checkKillSwitches(
+  constitution: Constitution,
+  context: Record<string, number | string | boolean>
+): KillSwitch | null {
+  for (const ks of constitution.killSwitches) {
+    const parts = ks.triggerCondition.split(/\s+/);
+    if (parts.length !== 3) continue;
+    const [key, op, rawVal] = parts as [string, string, string];
+    if (!(key in context)) continue;
+    const actual = Number(context[key]);
+    const threshold = Number(rawVal);
+    if (isNaN(actual) || isNaN(threshold)) continue;
+
+    let triggered = false;
+    switch (op) {
+      case '>': triggered = actual > threshold; break;
+      case '<': triggered = actual < threshold; break;
+      case '>=': triggered = actual >= threshold; break;
+      case '<=': triggered = actual <= threshold; break;
+      case '==': triggered = actual === threshold; break;
+      case '!=': triggered = actual !== threshold; break;
+    }
+    if (triggered) return ks;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Audit
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an audit entry from an evaluation result.
+ */
+export function createAudit(
+  agentId: AgentId,
+  action: string,
+  evaluation: EvaluationResult
+): AuditEntry {
+  return {
+    id: randomUUID(),
+    agentId,
+    action,
+    evaluation,
+    timestamp: evaluation.evaluatedAt,
+  };
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Public API surface
+ * @version 0.2.0
+ *
+ * SOUL is the lowest protocol layer. No other protocol overrides it.
+ * Kill switches are non-negotiable and cannot be delegated away.
+ */
+
+// Types
+export type {
+  AgentId,
+  Timestamp,
+  Signature,
+  EnforcementLevel,
+  ConstraintAction,
+  Constraint,
+  KillSwitch,
+  Constitution,
+  EvaluationResult,
+  AuditEntry,
+} from './types.js';
+
+// Engine
+export {
+  createConstitution,
+  signConstitution,
+  evaluateAction,
+  checkKillSwitches,
+  createAudit,
+} from './engine.js';
+
+/** Protocol version constant */
+export const SOUL_VERSION = '0.2' as const;

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * SOUL — Constitutional Constraints and Safety
+ * Core type definitions (skeleton)
+ * @version 0.1.0-skeleton
+ */
+
+export type AgentId = string;
+export type Timestamp = string;
+export type Signature = string;
+
+export type EnforcementLevel = 'hard' | 'soft' | 'advisory';
+export type ConstraintAction = 'allow' | 'deny' | 'require';
+
+/** A single constitutional constraint */
+export interface Constraint {
+  id: string;
+  name: string;
+  description: string;
+  action: ConstraintAction;
+  enforcementLevel: EnforcementLevel;
+  /** Resource or action pattern this constraint covers */
+  scope: string;
+  /** Whether this constraint survives context compaction (must be bootstrapped) */
+  bootstrapped: boolean;
+}
+
+/** A kill switch — a hard-stop trigger that halts an agent unconditionally */
+export interface KillSwitch {
+  id: string;
+  name: string;
+  /** Human-readable trigger condition */
+  triggerCondition: string;
+  /** What to do when triggered */
+  action: 'halt' | 'pause' | 'alert';
+  /** Cannot be delegated away or overridden */
+  nonNegotiable: true;
+}
+
+/** The root constitutional document for an operator */
+export interface Constitution {
+  version: '0.1';
+  operatorId: string;
+  /** ISO 8601 */
+  issuedAt: Timestamp;
+  constraints: Constraint[];
+  killSwitches: KillSwitch[];
+  /** Operator's signature over the constitution */
+  signature: Signature;
+}
+
+/** Result of evaluating an action against the constitution */
+export interface EvaluationResult {
+  allowed: boolean;
+  constraintId: string | null;
+  enforcementLevel: EnforcementLevel | null;
+  reason: string;
+  evaluatedAt: Timestamp;
+}
+
+/** Append-only audit log entry */
+export interface AuditEntry {
+  id: string;
+  agentId: AgentId;
+  action: string;
+  evaluation: EvaluationResult;
+  timestamp: Timestamp;
+}