@zanii/constitution 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 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 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 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; 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.
+
+   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 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.
+
+   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.
+
+   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.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   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,62 @@
+# @zanii/constitution
+
+Machine-checkable behavioral constraints as **signed policy**. The walls packages
+(`fta`, `walls`) each hard-code one vertical's rules; this is the framework: **publish
+the agent's rules as a signed document, then prove every action was evaluated against
+them** — and prove they didn't change mid-process.
+
+The mechanism reuses what already exists (zero server changes): a constitution's
+canonical hash IS the `manifest_hash` an agent stamps on its receipts.
+
+```sh
+npm install @zanii/constitution @zanii/core
+```
+
+```ts
+import { createConstitution, constitutionHash, evaluate, verifyGovernance, governanceTrail } from '@zanii/constitution';
+
+const c = createConstitution({
+  issuer: owner.did,
+  name: 'support-agent-rules',
+  rules: [                                              // FIRST MATCH WINS
+    { id: 'no-payments',   effect: 'forbid',           targets: ['payments.*'] },
+    { id: 'gate-outbound', effect: 'require_approval', targets: ['email.send', 'sms.*'] },
+    { id: 'crm-ok',        effect: 'allow',            targets: ['crm.*'] },
+  ],
+  defaultEffect: 'allow',                               // 'forbid' = deny-by-default (strict form)
+  createdAt: now,
+}, ownerKey);
+
+// at act time: evaluate + stamp the hash on every receipt
+evaluate(c, 'payments.transfer');                       // { effect: 'forbid', rule: {...} }
+await zanii.record({ target, payload, provenance: { manifestHash: constitutionHash(c) } });
+
+// at audit time: the deterministic governance verdict
+const report = verifyGovernance(c, receipts);
+report.violations;          // 'forbidden' (stamped AND hit a forbid rule — self-incriminating)
+                            // 'ungoverned' (missing/foreign stamp — visible, not silently fine)
+report.approvals_required;  // demand the owner-signed confirmations for these
+
+governanceTrail(receipts);  // which rulebooks governed the stream; interleaving = red flag
+```
+
+Python: `from zanii.constitution import create_constitution, verify_governance, governance_trail, ...`
+— byte-identical JCS objects and hashes.
+
+## Why this closes the loop
+
+1. **Prove the rules** — issuer-signed, content-addressed: change one rule and every
+   subsequent receipt visibly points at a different rulebook.
+2. **Prove they were followed** — a stamped receipt whose target hits a `forbid` rule
+   is a provable violation the agent recorded itself.
+3. **Prove they held** — `governanceTrail` flags interleaved rulebooks (A,B,A): the
+   same red flag `@zanii/gov` raises when a state algorithm's rules change mid-process.
+
+## The limit, stated up front
+
+The stamp proves an action was *recorded as governed* — act-time **enforcement** is
+`@zanii/runtime`/`@zanii/policy`'s job, and `require_approval` *verification*
+(matching owner-signed confirmations) stays with the runtime; we report which actions
+required approval so the auditor can demand the confirmations. An agent holding raw
+credentials can still act off the rails entirely — credential custody, unchanged. A
+constitution binds only when the verifier demands the stamp.

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { type Receipt } from '@zanii/core';
+export type RuleEffect = 'forbid' | 'require_approval' | 'allow';
+export interface Rule {
+    id: string;
+    effect: RuleEffect;
+    /** Scope patterns this rule applies to, e.g. `payments.*`, `email.send`. */
+    targets: string[];
+    note?: string;
+}
+export interface Constitution {
+    v: 1;
+    type: 'constitution';
+    /** Who binds the agent to these rules — normally the owner. */
+    issuer: string;
+    name: string;
+    /** Evaluated FIRST MATCH WINS, top to bottom. */
+    rules: Rule[];
+    /** Effect when no rule matches. A deny-by-default constitution is the strict form. */
+    default: 'allow' | 'forbid';
+    created_at: string;
+    /** `ed25519:<hex>` by the issuer. */
+    sig?: string;
+}
+export interface ConstitutionInput {
+    issuer: string;
+    name: string;
+    rules: Rule[];
+    /** Defaults to 'allow' (permissive: rules carve out the exceptions). */
+    defaultEffect?: 'allow' | 'forbid';
+    createdAt: string;
+}
+/** Build + sign the rulebook with the issuer's key. */
+export declare function createConstitution(input: ConstitutionInput, issuerPrivateKey: Uint8Array): Constitution;
+/** Verify structure + the issuer's signature. */
+export declare function verifyConstitution(c: Constitution | undefined): boolean;
+/**
+ * Canonical hash of the signed constitution — the value to stamp on receipts as
+ * `manifest_hash` (`record({ provenance: { manifestHash } })`). Content-addressed:
+ * change one rule and every subsequent receipt visibly points at a different rulebook.
+ */
+export declare function constitutionHash(c: Constitution): string;
+export interface Evaluation {
+    effect: RuleEffect;
+    /** The first matching rule, or null when the default applied. */
+    rule: Rule | null;
+}
+/** Evaluate one target — FIRST MATCH WINS, then the constitution's default. Pure. */
+export declare function evaluate(c: Constitution, target: string): Evaluation;
+export interface Violation {
+    /** JCS hash of the offending receipt. */
+    receipt: string;
+    target: string;
+    /** `forbidden` = stamped AND hit a forbid rule (self-incriminating). `ungoverned` = missing/foreign stamp. */
+    kind: 'forbidden' | 'ungoverned';
+    rule_id?: string;
+}
+export interface GovernanceReport {
+    ok: boolean;
+    violations: Violation[];
+    /** Actions that required approval — demand the owner-signed confirmations for these. */
+    approvals_required: Array<{
+        receipt: string;
+        target: string;
+        rule_id: string;
+    }>;
+    /** Receipts checked. */
+    actions: number;
+}
+/**
+ * The governance verdict — deterministic. Every receipt must carry THIS constitution's
+ * hash as its `manifest_hash` (else `ungoverned`), and no stamped receipt's target may
+ * hit a `forbid` rule (else `forbidden` — the agent recorded its own violation).
+ * Receipt signature validity is `verifyReceipt`'s job; this checks governance only.
+ */
+export declare function verifyGovernance(c: Constitution, receipts: Receipt[]): GovernanceReport;
+export interface GovernanceTrail {
+    /** Distinct manifest_hashes in order of first appearance ('' for unstamped). */
+    manifests: string[];
+    /** Receipts per manifest. */
+    counts: Record<string, number>;
+    /** true when manifests interleave (A…B…A) — rules flip-flopping mid-stream. */
+    interleaved: boolean;
+    /** Receipts with no manifest_hash at all. */
+    unstamped: number;
+}
+/**
+ * Which rulebooks governed this stream, and did they change cleanly? A clean upgrade
+ * looks like A,A,A,B,B; interleaving (A,B,A) means different rules governed
+ * interchangeable moments — the same red flag `gov` raises for state decisions.
+ * Pass receipts in ledger (ts) order.
+ */
+export declare function governanceTrail(receipts: Receipt[]): GovernanceTrail;
+//# 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":"AAgCA,OAAO,EAA0D,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAEnG,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,kBAAkB,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,cAAc,CAAC;IACrB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,sFAAsF;IACtF,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,GAAG,YAAY,CAwBvG;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAgBvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,iEAAiE;IACjE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CACnB;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAKpE;AAED,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,IAAI,EAAE,WAAW,GAAG,YAAY,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,wFAAwF;IACxF,kBAAkB,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAmBvF;AAED,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,eAAe,CAepE"}

package/dist/index.js

@@ -0,0 +1,162 @@
+/**
+ * @zanii/constitution — machine-checkable behavioral constraints as signed policy.
+ *
+ * The walls packages (`fta`, `sca`, `walls`) each hard-code one vertical's rules. This
+ * generalizes the pattern into a framework: **publish the agent's rules as a signed
+ * document, then prove every action was evaluated against them.**
+ *
+ * The mechanism reuses what already exists — no new receipt fields, zero server
+ * changes. A constitution's canonical hash IS the `manifest_hash` an agent stamps on
+ * its receipts (SPEC §3, same field the walls use). That closes the loop three ways:
+ *
+ * 1. **"Prove the agent's rules"** — the constitution is issuer-signed and content-
+ *    addressed; the stamp on each receipt commits that action to that exact rulebook.
+ * 2. **"Prove they were followed"** — `verifyGovernance` is deterministic: a receipt
+ *    whose target hits a `forbid` rule *while carrying the stamp* is a **provable,
+ *    self-incriminating violation**; a receipt missing the stamp is an **ungoverned
+ *    action** — visible, not silently fine.
+ * 3. **"Prove they didn't change mid-process"** — `governanceTrail` (the `gov` trick,
+ *    generalized) lists which rulebooks governed the stream and flags interleaving:
+ *    rules that flip back and forth mid-stream are a red flag everywhere.
+ *
+ * ## The limit, stated up front
+ *
+ * The stamp proves an action was *recorded as governed* — enforcement at act-time is
+ * `@zanii/runtime`/`@zanii/policy`'s job, and `require_approval` **verification**
+ * (matching owner-signed confirmations) stays with the runtime; we report which
+ * actions required approval so an auditor can demand the confirmations. And an agent
+ * still holding raw credentials can act off the rails entirely — the credential-custody
+ * problem, unchanged. A constitution binds only when the verifier demands the stamp.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { canonicalBytes, jcsHash, publicKeyFromDid, scopeCovers } from '@zanii/core';
+/** Build + sign the rulebook with the issuer's key. */
+export function createConstitution(input, issuerPrivateKey) {
+    if (!input.issuer)
+        throw new Error('issuer is required');
+    if (!input.name)
+        throw new Error('name is required');
+    if (!input.rules?.length)
+        throw new Error('a constitution with no rules constrains nothing');
+    const ids = new Set();
+    for (const r of input.rules) {
+        if (!r.id)
+            throw new Error('every rule needs an id');
+        if (ids.has(r.id))
+            throw new Error(`duplicate rule id '${r.id}'`);
+        ids.add(r.id);
+        if (!['forbid', 'require_approval', 'allow'].includes(r.effect))
+            throw new Error(`rule '${r.id}': invalid effect '${r.effect}'`);
+        if (!r.targets?.length)
+            throw new Error(`rule '${r.id}' has no targets`);
+    }
+    if (Number.isNaN(Date.parse(input.createdAt)))
+        throw new Error('createdAt must be an ISO timestamp');
+    const unsigned = {
+        v: 1,
+        type: 'constitution',
+        issuer: input.issuer,
+        name: input.name,
+        rules: input.rules,
+        default: input.defaultEffect ?? 'allow',
+        created_at: input.createdAt,
+    };
+    const sig = ed25519.sign(canonicalBytes(unsigned), issuerPrivateKey);
+    return { ...unsigned, sig: `ed25519:${bytesToHex(sig)}` };
+}
+/** Verify structure + the issuer's signature. */
+export function verifyConstitution(c) {
+    const p = c ?? {};
+    if (p.v !== 1 || p.type !== 'constitution' || !p.issuer || !p.name)
+        return false;
+    if (!Array.isArray(p.rules) || p.rules.length === 0)
+        return false;
+    if (new Set(p.rules.map((r) => r?.id)).size !== p.rules.length)
+        return false;
+    if (!p.rules.every((r) => r && ['forbid', 'require_approval', 'allow'].includes(r.effect) && Array.isArray(r.targets) && r.targets.length > 0))
+        return false;
+    if (p.default !== 'allow' && p.default !== 'forbid')
+        return false;
+    const pub = publicKeyFromDid(p.issuer);
+    const hex = typeof p.sig === 'string' && p.sig.startsWith('ed25519:') ? p.sig.slice(8) : '';
+    if (!pub || !/^[0-9a-f]{128}$/.test(hex))
+        return false;
+    const { sig: _omit, ...unsigned } = p;
+    try {
+        return ed25519.verify(hexToBytes(hex), canonicalBytes(unsigned), pub);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Canonical hash of the signed constitution — the value to stamp on receipts as
+ * `manifest_hash` (`record({ provenance: { manifestHash } })`). Content-addressed:
+ * change one rule and every subsequent receipt visibly points at a different rulebook.
+ */
+export function constitutionHash(c) {
+    return jcsHash(c);
+}
+/** Evaluate one target — FIRST MATCH WINS, then the constitution's default. Pure. */
+export function evaluate(c, target) {
+    for (const r of c.rules) {
+        if (r.targets.some((t) => scopeCovers(t, target)))
+            return { effect: r.effect, rule: r };
+    }
+    return { effect: c.default, rule: null };
+}
+/**
+ * The governance verdict — deterministic. Every receipt must carry THIS constitution's
+ * hash as its `manifest_hash` (else `ungoverned`), and no stamped receipt's target may
+ * hit a `forbid` rule (else `forbidden` — the agent recorded its own violation).
+ * Receipt signature validity is `verifyReceipt`'s job; this checks governance only.
+ */
+export function verifyGovernance(c, receipts) {
+    if (!verifyConstitution(c))
+        throw new Error('constitution does not verify — refuse to audit against an unsigned rulebook');
+    const hash = constitutionHash(c);
+    const violations = [];
+    const approvals = [];
+    for (const r of receipts) {
+        const rHash = jcsHash(r);
+        if (r.manifest_hash !== hash) {
+            violations.push({ receipt: rHash, target: r.target, kind: 'ungoverned' });
+            continue;
+        }
+        const ev = evaluate(c, r.target);
+        if (ev.effect === 'forbid') {
+            violations.push({ receipt: rHash, target: r.target, kind: 'forbidden', ...(ev.rule ? { rule_id: ev.rule.id } : {}) });
+        }
+        else if (ev.effect === 'require_approval' && ev.rule) {
+            approvals.push({ receipt: rHash, target: r.target, rule_id: ev.rule.id });
+        }
+    }
+    return { ok: violations.length === 0, violations, approvals_required: approvals, actions: receipts.length };
+}
+/**
+ * Which rulebooks governed this stream, and did they change cleanly? A clean upgrade
+ * looks like A,A,A,B,B; interleaving (A,B,A) means different rules governed
+ * interchangeable moments — the same red flag `gov` raises for state decisions.
+ * Pass receipts in ledger (ts) order.
+ */
+export function governanceTrail(receipts) {
+    const order = [];
+    const counts = {};
+    let interleaved = false;
+    let unstamped = 0;
+    let prev = null;
+    for (const r of receipts) {
+        const m = r.manifest_hash ?? '';
+        if (m === '')
+            unstamped++;
+        counts[m] = (counts[m] ?? 0) + 1;
+        if (!order.includes(m))
+            order.push(m);
+        else if (prev !== m)
+            interleaved = true;
+        prev = m;
+    }
+    return { manifests: order, counts, interleaved, unstamped };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zanii/constitution",
+  "version": "0.1.0",
+  "description": "Machine-checkable behavioral constraints as signed policy - publish an agent's rules (forbid / require_approval / allow over scope patterns), stamp the constitution hash on every receipt via the existing manifest_hash field, then PROVE each action was governed: a forbidden action with the stamp is a provable violation, and a rulebook change mid-stream is visible. Generalizes the fta/sca walls into a framework.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1",
+    "@zanii/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * @zanii/constitution — machine-checkable behavioral constraints as signed policy.
+ *
+ * The walls packages (`fta`, `sca`, `walls`) each hard-code one vertical's rules. This
+ * generalizes the pattern into a framework: **publish the agent's rules as a signed
+ * document, then prove every action was evaluated against them.**
+ *
+ * The mechanism reuses what already exists — no new receipt fields, zero server
+ * changes. A constitution's canonical hash IS the `manifest_hash` an agent stamps on
+ * its receipts (SPEC §3, same field the walls use). That closes the loop three ways:
+ *
+ * 1. **"Prove the agent's rules"** — the constitution is issuer-signed and content-
+ *    addressed; the stamp on each receipt commits that action to that exact rulebook.
+ * 2. **"Prove they were followed"** — `verifyGovernance` is deterministic: a receipt
+ *    whose target hits a `forbid` rule *while carrying the stamp* is a **provable,
+ *    self-incriminating violation**; a receipt missing the stamp is an **ungoverned
+ *    action** — visible, not silently fine.
+ * 3. **"Prove they didn't change mid-process"** — `governanceTrail` (the `gov` trick,
+ *    generalized) lists which rulebooks governed the stream and flags interleaving:
+ *    rules that flip back and forth mid-stream are a red flag everywhere.
+ *
+ * ## The limit, stated up front
+ *
+ * The stamp proves an action was *recorded as governed* — enforcement at act-time is
+ * `@zanii/runtime`/`@zanii/policy`'s job, and `require_approval` **verification**
+ * (matching owner-signed confirmations) stays with the runtime; we report which
+ * actions required approval so an auditor can demand the confirmations. And an agent
+ * still holding raw credentials can act off the rails entirely — the credential-custody
+ * problem, unchanged. A constitution binds only when the verifier demands the stamp.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { canonicalBytes, jcsHash, publicKeyFromDid, scopeCovers, type Receipt } from '@zanii/core';
+
+export type RuleEffect = 'forbid' | 'require_approval' | 'allow';
+
+export interface Rule {
+  id: string;
+  effect: RuleEffect;
+  /** Scope patterns this rule applies to, e.g. `payments.*`, `email.send`. */
+  targets: string[];
+  note?: string;
+}
+
+export interface Constitution {
+  v: 1;
+  type: 'constitution';
+  /** Who binds the agent to these rules — normally the owner. */
+  issuer: string;
+  name: string;
+  /** Evaluated FIRST MATCH WINS, top to bottom. */
+  rules: Rule[];
+  /** Effect when no rule matches. A deny-by-default constitution is the strict form. */
+  default: 'allow' | 'forbid';
+  created_at: string;
+  /** `ed25519:<hex>` by the issuer. */
+  sig?: string;
+}
+
+export interface ConstitutionInput {
+  issuer: string;
+  name: string;
+  rules: Rule[];
+  /** Defaults to 'allow' (permissive: rules carve out the exceptions). */
+  defaultEffect?: 'allow' | 'forbid';
+  createdAt: string;
+}
+
+/** Build + sign the rulebook with the issuer's key. */
+export function createConstitution(input: ConstitutionInput, issuerPrivateKey: Uint8Array): Constitution {
+  if (!input.issuer) throw new Error('issuer is required');
+  if (!input.name) throw new Error('name is required');
+  if (!input.rules?.length) throw new Error('a constitution with no rules constrains nothing');
+  const ids = new Set<string>();
+  for (const r of input.rules) {
+    if (!r.id) throw new Error('every rule needs an id');
+    if (ids.has(r.id)) throw new Error(`duplicate rule id '${r.id}'`);
+    ids.add(r.id);
+    if (!['forbid', 'require_approval', 'allow'].includes(r.effect)) throw new Error(`rule '${r.id}': invalid effect '${r.effect}'`);
+    if (!r.targets?.length) throw new Error(`rule '${r.id}' has no targets`);
+  }
+  if (Number.isNaN(Date.parse(input.createdAt))) throw new Error('createdAt must be an ISO timestamp');
+  const unsigned = {
+    v: 1 as const,
+    type: 'constitution' as const,
+    issuer: input.issuer,
+    name: input.name,
+    rules: input.rules,
+    default: input.defaultEffect ?? ('allow' as const),
+    created_at: input.createdAt,
+  };
+  const sig = ed25519.sign(canonicalBytes(unsigned), issuerPrivateKey);
+  return { ...unsigned, sig: `ed25519:${bytesToHex(sig)}` };
+}
+
+/** Verify structure + the issuer's signature. */
+export function verifyConstitution(c: Constitution | undefined): boolean {
+  const p = c ?? ({} as Constitution);
+  if (p.v !== 1 || p.type !== 'constitution' || !p.issuer || !p.name) return false;
+  if (!Array.isArray(p.rules) || p.rules.length === 0) return false;
+  if (new Set(p.rules.map((r) => r?.id)).size !== p.rules.length) return false;
+  if (!p.rules.every((r) => r && ['forbid', 'require_approval', 'allow'].includes(r.effect) && Array.isArray(r.targets) && r.targets.length > 0)) return false;
+  if (p.default !== 'allow' && p.default !== 'forbid') return false;
+  const pub = publicKeyFromDid(p.issuer);
+  const hex = typeof p.sig === 'string' && p.sig.startsWith('ed25519:') ? p.sig.slice(8) : '';
+  if (!pub || !/^[0-9a-f]{128}$/.test(hex)) return false;
+  const { sig: _omit, ...unsigned } = p;
+  try {
+    return ed25519.verify(hexToBytes(hex), canonicalBytes(unsigned as unknown as Record<string, unknown>), pub);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Canonical hash of the signed constitution — the value to stamp on receipts as
+ * `manifest_hash` (`record({ provenance: { manifestHash } })`). Content-addressed:
+ * change one rule and every subsequent receipt visibly points at a different rulebook.
+ */
+export function constitutionHash(c: Constitution): string {
+  return jcsHash(c as unknown as Record<string, unknown>);
+}
+
+export interface Evaluation {
+  effect: RuleEffect;
+  /** The first matching rule, or null when the default applied. */
+  rule: Rule | null;
+}
+
+/** Evaluate one target — FIRST MATCH WINS, then the constitution's default. Pure. */
+export function evaluate(c: Constitution, target: string): Evaluation {
+  for (const r of c.rules) {
+    if (r.targets.some((t) => scopeCovers(t, target))) return { effect: r.effect, rule: r };
+  }
+  return { effect: c.default, rule: null };
+}
+
+export interface Violation {
+  /** JCS hash of the offending receipt. */
+  receipt: string;
+  target: string;
+  /** `forbidden` = stamped AND hit a forbid rule (self-incriminating). `ungoverned` = missing/foreign stamp. */
+  kind: 'forbidden' | 'ungoverned';
+  rule_id?: string;
+}
+
+export interface GovernanceReport {
+  ok: boolean;
+  violations: Violation[];
+  /** Actions that required approval — demand the owner-signed confirmations for these. */
+  approvals_required: Array<{ receipt: string; target: string; rule_id: string }>;
+  /** Receipts checked. */
+  actions: number;
+}
+
+/**
+ * The governance verdict — deterministic. Every receipt must carry THIS constitution's
+ * hash as its `manifest_hash` (else `ungoverned`), and no stamped receipt's target may
+ * hit a `forbid` rule (else `forbidden` — the agent recorded its own violation).
+ * Receipt signature validity is `verifyReceipt`'s job; this checks governance only.
+ */
+export function verifyGovernance(c: Constitution, receipts: Receipt[]): GovernanceReport {
+  if (!verifyConstitution(c)) throw new Error('constitution does not verify — refuse to audit against an unsigned rulebook');
+  const hash = constitutionHash(c);
+  const violations: Violation[] = [];
+  const approvals: GovernanceReport['approvals_required'] = [];
+  for (const r of receipts) {
+    const rHash = jcsHash(r as unknown as Record<string, unknown>);
+    if (r.manifest_hash !== hash) {
+      violations.push({ receipt: rHash, target: r.target, kind: 'ungoverned' });
+      continue;
+    }
+    const ev = evaluate(c, r.target);
+    if (ev.effect === 'forbid') {
+      violations.push({ receipt: rHash, target: r.target, kind: 'forbidden', ...(ev.rule ? { rule_id: ev.rule.id } : {}) });
+    } else if (ev.effect === 'require_approval' && ev.rule) {
+      approvals.push({ receipt: rHash, target: r.target, rule_id: ev.rule.id });
+    }
+  }
+  return { ok: violations.length === 0, violations, approvals_required: approvals, actions: receipts.length };
+}
+
+export interface GovernanceTrail {
+  /** Distinct manifest_hashes in order of first appearance ('' for unstamped). */
+  manifests: string[];
+  /** Receipts per manifest. */
+  counts: Record<string, number>;
+  /** true when manifests interleave (A…B…A) — rules flip-flopping mid-stream. */
+  interleaved: boolean;
+  /** Receipts with no manifest_hash at all. */
+  unstamped: number;
+}
+
+/**
+ * Which rulebooks governed this stream, and did they change cleanly? A clean upgrade
+ * looks like A,A,A,B,B; interleaving (A,B,A) means different rules governed
+ * interchangeable moments — the same red flag `gov` raises for state decisions.
+ * Pass receipts in ledger (ts) order.
+ */
+export function governanceTrail(receipts: Receipt[]): GovernanceTrail {
+  const order: string[] = [];
+  const counts: Record<string, number> = {};
+  let interleaved = false;
+  let unstamped = 0;
+  let prev: string | null = null;
+  for (const r of receipts) {
+    const m = r.manifest_hash ?? '';
+    if (m === '') unstamped++;
+    counts[m] = (counts[m] ?? 0) + 1;
+    if (!order.includes(m)) order.push(m);
+    else if (prev !== m) interleaved = true;
+    prev = m;
+  }
+  return { manifests: order, counts, interleaved, unstamped };
+}