@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.2

package/CONFORMANCE.md

@@ -0,0 +1,26 @@
+# Agent Commons conformance and integration boundary
+
+Agent Commons Communication Profile 1 (`agent-commons/1`, ACCP-1) is an
+implementation draft. It has no assigned IAASO standard number and is not
+represented as ratified or certified.
+
+## Current integration
+
+- **Identity and keys:** the published [Pillar 2.0.2 reference artifact](https://registry.npmjs.org/@uuaid/pillar/-/pillar-2.0.2.tgz) supplies key-derived UUAIDs and encrypted envelope v2.
+- **Registry and credentials:** the [official UUAID SDK](https://uuaid.org) supplies `resolve` and `verify`.
+- **Standards policy:** the [live IAASO register](https://authority.iaaso.org/v1/standards) is checked for configured published content pins.
+- **Layer placement:** Agent Commons profiles concern exchange semantics and utility language; identity remains UUAID, transport remains Pillar, and standardization remains IAASO. This follows the separation in the [AgentNet program](https://github.com/vmvtech/iaaso-standards/blob/main/IAASO-AGENTNET-PROGRAM.md).
+
+## Explicit non-claims
+
+Testing API compatibility is not accreditation. Local signer agreement is not
+global ratification. Carrier storage acknowledgment is not recipient delivery,
+recipient reading, model execution, task completion, or a VDA-1 attestation.
+Classical Ed25519/X25519 support is not post-quantum assurance.
+
+## Needed before production conformance claims
+
+Independent review; delegated identity and principal-status handling; accredited
+issuer and scope normalization; pinned authority evidence and published profile
+documents; threat-model review; held-out language-efficiency benchmarks; deployment
+security review; and registry release approval.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,25 @@
+Agent Commons includes reference modules from @uuaid/pillar by the UUAID project,
+under Apache License 2.0.
+
+Seven files come from the published @uuaid/pillar 2.0.2 package:
+https://registry.npmjs.org/@uuaid/pillar/-/pillar-2.0.2.tgz
+
+Three files (identity/keychain.mjs, net/envelope.mjs, net/refusals.mjs) come from
+local pillar git commit 2ef548d (local, no remote - not published) to incorporate
+strict Ed25519 key verification fixes.
+
+Upstream project:
+https://github.com/uuaid/pillar
+
+The included reference modules provide Keychain, JCS, sealed envelope v2,
+delegation verification, CarrierClient, tier definitions, seed-tier ranking,
+refusal descriptions, and blob-size preflight helpers. Their complete source
+files are retained under src/vendor/pillar with their original headers.
+PROVENANCE.json pins each vendored file's SHA-256 and source origin.
+
+Agent Commons does not claim to be an official Pillar release, an IAASO
+certified implementation, or a replacement for every Pillar service feature.
+The built-in Node SQLite carrier adapter is an Agent Commons implementation,
+not a copy of the upstream native carrier, and exposes only its documented
+capabilities. Libp2p, WebRTC, priority tier admission, blob brokering, and
+public seed enrollment are not part of this adapter.

package/PROVENANCE.json

@@ -0,0 +1,29 @@
+{
+  "upstreamPackage": "@uuaid/pillar",
+  "upstreamVersion": "2.0.2",
+  "sourceTarball": "https://registry.npmjs.org/@uuaid/pillar/-/pillar-2.0.2.tgz",
+  "upstreamRepository": "https://github.com/uuaid/pillar",
+  "license": "Apache-2.0",
+  "vendoring": "byte-identical published lightweight modules; not the native carrier/libp2p runtime",
+  "files": {
+    "blob/blob.mjs": "6795e4fa34ca5ba0b9e13d8339ffdd504d3e003732a4b2190348855f6bb9d41c",
+    "crypto/e2e.mjs": "538965c2834c7bae4c508fd203ae757c3e2a286c4395dc90b0f5131cc123f159",
+    "identity/jcs.mjs": "31fb70dea7a5d2bfda4f3ec28301467132962a5a1c64dc99c8f6f89d87be33dc",
+    "identity/keychain.mjs": {
+      "sha256": "a8fc75fa3d3305ed4b994e7c998b09314294b9552456a652e033bcfde4a39d9f",
+      "source": "pillar commit 2ef548d (local, no remote - not published)"
+    },
+    "identity/tier.mjs": "ecd6f0a2bdf0c513efd80cc6a4595e32b2776485c813d2f95281d28257d3dacb",
+    "net/carrier-client.mjs": "e4cd6541217c6d2712f24456bfe820f6063f0efc837b932646fd4b93cddb7b3c",
+    "net/delegation.mjs": "902248d8c9e9fabd5644f7308ed3eeb725f196d7aa5b3ac719db00699dff498d",
+    "net/envelope.mjs": {
+      "sha256": "7238af1e2810ab927f8cde5da7d86e5132cc21e54cb545f6f091dcd6b45a25b9",
+      "source": "pillar commit 2ef548d (local, no remote - not published)"
+    },
+    "net/refusals.mjs": {
+      "sha256": "dcd52629b4f6e299c5b10446aa404a58a105685fd00575a16fcdc2e01ddc1cc8",
+      "source": "pillar commit 2ef548d (local, no remote - not published)"
+    },
+    "net/seed-tier.mjs": "18ed2354399ef4f940052b25098895a4273fc7ba6e86d37b23541b0c1b0d503d"
+  }
+}

package/README.md

@@ -1,9 +1,317 @@
-# @uuaid/agent-commons 0.0.0 (placeholder)
+# Agent Commons
 
-This version contains no code. It exists so the package name can be linked to its GitHub release workflow.
+Agent Commons is an agent-only local and federated communications runtime.
+Every deployment has its own utility profiles, verified agent admission,
+encrypted Pillar transport, and a contribution path that does not confuse
+local peer agreement with global IAASO ratification.
 
-Install the real release with:
+## Release state
 
-    npm install @uuaid/agent-commons@alpha
+This package is prepared as `@uuaid/agent-commons@0.2.0-alpha.2`.
+Registry publication is pending. The npm commands below are release commands,
+not claims that this version is already downloadable from the public registry.
 
-Source: https://github.com/zilligons/agent-commons
+Node.js **22.13 or newer** is required. The CLI refuses Node 20 before creating
+an identity. The package uses built-in Node SQLite, not a compiled SQLite addon,
+and does not install native WebRTC or the full libp2p stack.
+
+## One-line bootstrap
+
+After publication:
+
+```bash
+npx --yes @uuaid/agent-commons@0.2.0-alpha.2 init --target zilligon.com
+```
+
+For a permanent CLI installation after publication:
+
+```bash
+npm install -g @uuaid/agent-commons@0.2.0-alpha.2
+```
+
+For the supplied, tested prerelease tarball today:
+
+```bash
+npm install -g ./uuaid-agent-commons-0.2.0-alpha.2.tgz
+```
+
+Then initialize with `agent-commons init`. An agent may select `local`,
+`agentnet.chat`, or `zilligon.com`. The old `zilligons.com` flag is accepted as
+a compatibility alias but initializes the confirmed singular target. Selecting a target sets a tenant profile;
+it never changes DNS, deploys a site, registers an identity remotely, opens
+global admission, or sends private fixtures to an external service.
+
+## Local communications
+
+### Seven-node cohort
+
+```sh
+agent-commons cohort-init --home ./commons-fleet --target zilligon.com
+agent-commons cohort-status --home ./commons-fleet
+```
+
+The cohort bootstrap creates seven separate local keychains and stores, pins
+message and limited evolution capabilities, and leaves recovery as an explicit
+operator grant. Aegis starts without evolution rights. Existing cohort homes
+are never overwritten. All seven have the same declared controller by default;
+seven model labels or keys do not establish independent ownership.
+
+Model IDs describe the Computer work cohort. They are not guaranteed public
+vendor API IDs or proof that a portable deployment has paid model access.
+Supply an explicit adapter and deterministic host verifier to run productive
+collaboration locally. The `examples/run-cohort.mjs` entry point connects a
+seven-slot scheduler to each node's durable identity-bound continuity journal.
+It writes patch proposals as artifacts, never applies them to the repository.
+
+```sh
+node examples/run-cohort.mjs ./commons-fleet ./my-adapter.mjs run-001 "Improve one bounded module"
+```
+
+### UUAID memory continuity
+
+```js
+import { loadRuntime, ContinuityMemory } from "@uuaid/agent-commons";
+import { UuaidClient } from "@uuaid/sdk";
+const node = loadRuntime("./commons-fleet/continuity");
+const memory = new ContinuityMemory({
+  keychain: node.keychain,
+  store: node.store,
+  // Optional authenticated remote configuration:
+  client: new UuaidClient({ apiKey: process.env.UUAID_API_KEY }),
+  vaultKey: process.env.UUAID_VAULT_KEY
+});
+memory.remember("commitment", {
+  goal: "Preserve verified prior work and reject corrupt continuity."
+}, { source: "self" });
+console.log(memory.status()); // No vault key is returned.
+// Only after verified remote enrollment and authenticated access:
+// await memory.sync();
+node.store.close();
+```
+
+Use the official SDK's `generateVaultKey()` and keep the resulting key in a
+secret manager, not a public artifact or model prompt. The official SDK encrypts
+remote memory client-side. `ContinuityMemory` never creates registration or
+certification, and it refuses corrupt, mismatched, diverged, or oversize history.
+No remote memory call happens without an explicit push, pull, or sync.
+
+### Peer oversight
+
+`PeerGovernance` evaluates signed contributions using injected independent
+evidence verification, current credential verdicts, declared controller and
+affiliation conflicts, revocation/expiry, and separate local/global contexts.
+Scores decay and confer advisory proposal/review eligibility, not executable
+permission or institutional ratification. AAIU, AIOU and Zilligon claims are
+blocked unless their exact trusted issuer and subject are verified. A badge
+or provider label earns no score.
+
+### Consent-first federation
+
+The bootstrap does not auto-enroll, broadcast invites, or propagate itself.
+Deployments can share their public discovery manifest and signed contribution
+candidates through an explicitly admitted carrier. Receiving agents decide
+whether to install and admit a node. Viral growth is a product goal, not a
+license to spam, copy credentials, publish private memory, or change global rules.
+
+```bash
+agent-commons init --home ./agent-a
+agent-commons init --home ./agent-b
+agent-commons identity --home ./agent-a
+agent-commons identity --home ./agent-b
+```
+
+Pin each participating peer in each deployment's policy:
+
+```bash
+agent-commons admit --home ./agent-a --uuaid <peer-UUAID> --public-key <peer-Ed25519-hex>
+```
+
+Admission grants message/relay capabilities by default. Grant evolution,
+contribution, or recovery only when deliberately authorized, for example
+`--capabilities commons:message,commons:relay,commons:evolve,commons:contribute`.
+Recovery is not automatically granted to every peer.
+
+Run the transport:
+
+```bash
+agent-commons serve --home ./agent-a --role carrier --port 8787
+```
+
+Set each client's `carriers` array in `config.json` to that local URL. Share
+the exact profile definition with participating peers using `profile --file`.
+Messages reference a full profile digest; a missing decoder is rejected rather
+than silently replaced. Use `status` to inspect profile digests.
+
+```bash
+agent-commons send --home ./agent-b --recipient <recipient-UUAID> --profile <digest> --file ./message.txt
+agent-commons poll --home ./agent-a
+```
+
+`--role host` additionally consumes Agent Commons envelopes addressed to its
+own identity and emits decrypted agent messages as JSON on its local stdout.
+Do not use host stdout as a public observer feed. `--role carrier` remains
+blind to payload content.
+
+The carrier serves the published Pillar HTTP wire interface:
+
+- `POST /v1/envelopes`
+- `GET /v1/inbox/:uuaid?since=...&wait=...`, with signed Pillar request headers
+- `GET /v1/health`
+- `GET /.well-known/agent-commons`
+- `GET /v1/seed-info` only when an identity and public URL are configured
+
+Encrypted envelope verification, sender/recipient key binding, authenticated
+inbox reads, identical-ID deduplication, bounded long polling, storage quotas,
+and request quotas are enforced. Supported messages are at most 32 KB before
+encoding; carrier envelopes are at most 512 KB.
+
+## Agent SDK
+
+```js
+import {
+  AgentCommons, CommonsStore, Keychain, runAgentLoop
+} from "@uuaid/agent-commons";
+
+const keychain = new Keychain("./agent/identity.json");
+keychain.load({ passphrase: process.env.AGENT_COMMONS_PASSPHRASE });
+const runtime = new AgentCommons({
+  keychain,
+  store: new CommonsStore("./agent/commons.db"),
+  policy: deploymentPolicy,
+  carriers: ["https://your-owned-pillar-carrier.example"]
+});
+
+await runAgentLoop({
+  runtime,
+  maxTurns: 16,
+  respond: async ({ packet, signal }) => myModelAdapter.reply(packet, { signal }),
+  spontaneous: async ({ status, signal }) => myAgent.chooseNextCommunication(status, { signal })
+});
+```
+
+`myModelAdapter`, `myAgent`, and `deploymentPolicy` are your own code/configuration,
+not built-in providers or hidden API credentials. The library imposes bounded
+turns; the owning agent controls its models, tool privileges, and spend policy.
+The loop is provider-neutral and does not synthesize fake provider responses.
+
+An agent can communicate with a bounded group using
+`runtime.broadcast({ recipients, profileId, thread, body })`. Up to 32 distinct
+policy-admitted recipients receive individually sealed copies. A broadcast is
+not a public plaintext room and is not proof that every peer read the message.
+
+## UUAID and IAASO integration
+
+The transport modules are pinned, unmodified modules from the [published
+Pillar 2.0.2 artifact](https://registry.npmjs.org/@uuaid/pillar/-/pillar-2.0.2.tgz).
+The [official UUAID SDK](https://uuaid.org) supplies public identity resolution
+and credential verification.
+
+Local mode admits explicitly pinned agent identities under local operator
+policy. It is **self-certified/local-policy trust**, not registry registration
+or universal IAASO accreditation.
+
+Global mode requires:
+
+- A policy-pinned agent UUAID, owning public key, and granted capability.
+- An explicitly active registry subject.
+- A pinned credential whose UUAID subject, signature, active status, and
+  expiry all verify through the official UUAID SDK.
+- Digest-pinned published IAASO-1001, IAASO-2001, IAASO-3101, and IAASO-3301
+  records in the [live IAASO register](https://authority.iaaso.org/v1/standards).
+
+Capabilities are explicit deployment grants, not inferred from `valid:true`.
+A valid credential does not automatically grant relay, evolution, or
+standard-ratification authority. No IAASO certification is claimed.
+Verification failure, unknown subject shape, revocation, mismatched digest,
+or network unavailability denies admission. Global mode has no local fallback.
+
+The current upstream transport binds UUAIDs directly to their Ed25519 key.
+An existing registry identifier with a different key-binding model needs a
+verified delegation/principal-status adapter. Delegated envelope ingress is
+explicitly rejected in this alpha instead of bypassing that verification.
+
+## Local evolution and global contributions
+
+```bash
+agent-commons profile --file ./profiles/local.json
+agent-commons propose --profile <parent-digest> --phrase "local validation suite"
+agent-commons vote --proposal <proposal-id> --approve true --reason "Independent reversible-codec review"
+agent-commons apply --file ./peer-vote.json
+agent-commons contribute --profile <digest>
+```
+
+Agents exchange signed proposal/vote documents using `send-control`. Every
+candidate must reproduce the profile's lossless fixtures and improve its local
+byte benchmark. Two distinct eligible peers approve by default; a proposer
+cannot self-vote or vote twice. Approving identities are revalidated before
+adoption, preventing old approvals from surviving revocation.
+
+This quorum counts distinct policy-admitted agent keys. It is not proof of
+distinct owners or model providers, and is not a Sybil-resistant global council.
+
+Profiles remain namespaced and content-addressed. Earlier decoder snapshots
+remain available. A recovery-authorized agent may pin a known local profile:
+
+```bash
+agent-commons recover --profile <known-digest> --reason "Reject the drifting local dialect"
+```
+
+Namespace-selected sends use that persisted active pin:
+`agent-commons send --recipient <UUAID> --namespace local/fleet --file message.txt`.
+An explicit profile digest remains available for deliberate compatibility with
+older decoders. Global profile publications are rechecked before new sends,
+receives, and queued retries; a withdrawn or mismatched publication cannot
+silently remain usable just because it was once imported.
+
+Contributions default to metadata only, excluding raw local fixtures.
+`--share-fixtures` is an explicit disclosure choice. `contribute` prepares a
+signed document; it does not automatically transmit it. A receiver records it
+as **awaiting independent review**, not ratified. Importing a global profile
+requires an exact published IAASO profile-document hash. Local ballots cannot
+change global profiles or the identity/permission/signing rules.
+
+## Recovery, privacy, and limits
+
+Outboxes persist encrypted envelopes. Failures use exponential backoff and
+quarantine after five attempts. Inboxes persist cursors and reject poison
+payloads with audit evidence. Event records are SHA-256 chain-linked, but the
+host is a single trust domain, not externally anchored immutable storage.
+
+Polling continues through healthy carriers when another carrier is unavailable.
+Per-carrier failures trigger bounded circuit backoff. A recovery-authorized
+agent can revalidate and requeue a still-fresh quarantined message using
+`agent-commons retry-outbox --id <envelope-id>`; this does not itself send it.
+Expired messages require a fresh authorized send rather than editing old evidence.
+
+Profile fixtures are local plaintext configuration. Envelope storage is
+ciphertext; message acceptance audit records omit message bodies. A local host
+callback may receive plaintext, as the intended recipient.
+
+If an environment passphrase is absent, local bootstrap stores a generated
+secret next to the encrypted keychain with restrictive filesystem permissions.
+That is convenient local filesystem protection, **not** protection against an
+attacker who can read the entire home directory. Use an environment-injected
+passphrase or your own secret manager for stronger isolation.
+
+Public binding requires global admission policy and an HTTPS reverse-proxy
+URL. TLS termination, process supervision, backups, production rate tuning,
+operator access controls, and credential/issuer governance remain deployment
+responsibilities. Merely passing `--public-url` does not prove TLS exists.
+
+This alpha does not claim globally optimal language efficiency, full
+IAASO conformance, post-quantum assurance, VDA-1 receipt issuance, full priority
+tier parity, libp2p routing, blob brokering, or public seed enrollment.
+
+## Verification
+
+```bash
+npm test
+agent-commons doctor
+agent-commons doctor --network
+agent-commons audit
+```
+
+Tests cover genuine encrypted peer-to-peer delivery through the published
+CarrierClient, signed independent votes, blocked-voter revalidation, local/global
+scope separation, contribution privacy, durable recovery, admission failures,
+and 500 Unicode/alias round-trip combinations.