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

package/src/governance-scope.mjs

@@ -0,0 +1,139 @@
+/**
+ * Classifies an operation into one of three tiers:
+ * - Tier 1: Local peer messaging (offline, key-derived identities, no registry/principal checks)
+ * - Tier 2: Default local profile evolution (offline, commons:evolve, produces advisory approval)
+ * - Tier 3: Principal-governed institutional operations (strict opt-in, mandatory action-time verifier)
+ */
+export function classifyOperationTier(operation, options = {}) {
+  const { scope, policy } = options;
+
+  // Tier 1: Local peer messaging operations
+  if (
+    [
+      "send",
+      "receive",
+      "receiveInternal",
+      "flush",
+      "flushInternal",
+      "broadcast",
+      "poll"
+    ].includes(operation)
+  ) {
+    return "tier1-messaging";
+  }
+
+  // Tier 3: Explicit global scope, global policy mode, explicit principal-required mode, or standards items
+  if (
+    scope === "global" ||
+    policy?.mode === "global" ||
+    policy?.governanceMode === "principal-required" ||
+    operation === "standards-work"
+  ) {
+    return "tier3-principal-governed";
+  }
+
+  // Tier 2: Local profile evolution under default mode
+  if (["propose", "vote", "apply", "applyInternal"].includes(operation)) {
+    return "tier2-default-local-evolution";
+  }
+
+  // Fail-closed default for unknown operations
+  return "tier3-principal-governed";
+}
+
+/**
+ * Enforces action-time principal mapping and status verification for Tier 3 governance actions.
+ * Missing mapping fails with PRINCIPAL_MAPPING_REQUIRED.
+ * Verifier failure or errors fail with STATUS_VERIFIER_UNAVAILABLE.
+ * Superseded status fails with PRINCIPAL_SUPERSEDED.
+ * Suspended/revoked/expired/not-found fail with PRINCIPAL_STATUS_DENIED.
+ * Strict no-fallback rule: governed refusals never degrade to Tier 2 local evolution.
+ */
+export async function verifyPrincipalGovernance(uuaid, verifier, policy) {
+  const principalId = policy?.principals?.[uuaid];
+  if (!principalId) {
+    const err = new Error(`Principal mapping required for ${uuaid}`);
+    err.code = "PRINCIPAL_MAPPING_REQUIRED";
+    throw err;
+  }
+
+  if (!verifier || typeof verifier.checkStatus !== "function") {
+    const err = new Error("Status verifier unavailable: no verifier configured");
+    err.code = "STATUS_VERIFIER_UNAVAILABLE";
+    throw err;
+  }
+
+  let result;
+  try {
+    result = await verifier.checkStatus(principalId);
+  } catch (cause) {
+    const err = new Error(`Status verifier unavailable: ${cause.message}`);
+    err.code = "STATUS_VERIFIER_UNAVAILABLE";
+    err.cause = cause;
+    throw err;
+  }
+
+  if (!result || typeof result !== "object" || !result.status) {
+    const err = new Error("Status verifier returned invalid result");
+    err.code = "STATUS_VERIFIER_UNAVAILABLE";
+    throw err;
+  }
+
+  if (result.status === "superseded") {
+    const err = new Error(`Principal ${principalId} is superseded`);
+    err.code = "PRINCIPAL_SUPERSEDED";
+    throw err;
+  }
+
+  if (result.status !== "active") {
+    const err = new Error(`Principal ${principalId} status denied: ${result.status}`);
+    err.code = "PRINCIPAL_STATUS_DENIED";
+    err.status = result.status;
+    throw err;
+  }
+
+  return {
+    principalId,
+    status: "active",
+    checkedAt: result.checkedAt ?? Date.now()
+  };
+}
+
+/**
+ * In-memory test fixture implementing PrincipalStatusVerifier for offline tests.
+ */
+export class MockPrincipalStatusVerifier {
+  #statuses = new Map();
+  #errors = new Map();
+
+  constructor(initialStatuses = {}) {
+    if (initialStatuses instanceof Map) {
+      for (const [k, v] of initialStatuses) {
+        this.#statuses.set(k, v);
+      }
+    } else if (typeof initialStatuses === "object" && initialStatuses !== null) {
+      for (const [k, v] of Object.entries(initialStatuses)) {
+        this.#statuses.set(k, v);
+      }
+    }
+  }
+
+  setStatus(principalId, status) {
+    this.#statuses.set(principalId, status);
+  }
+
+  setThrows(principalId, error) {
+    this.#errors.set(principalId, error);
+  }
+
+  async checkStatus(principalId) {
+    if (this.#errors.has(principalId)) {
+      throw this.#errors.get(principalId);
+    }
+    const status = this.#statuses.get(principalId) ?? "not-found";
+    return {
+      status,
+      checkedAt: Date.now()
+    };
+  }
+}

package/src/governance.mjs

@@ -0,0 +1,355 @@
+import { assertJSON, BASE_PROTOCOL, digest } from "./profiles.mjs";
+import { jcs, Keychain } from "./pillar.mjs";
+import { SELF_CERTIFYING_AGENT_UUAID } from "./uuaid-namespace.mjs";
+
+// This module deliberately performs no network calls and executes no changes.
+// Operators must inject verifiers backed by actual identity/evidence authorities.
+export class GovernanceError extends Error {
+  constructor(code, message = code) { super(message); this.name = "GovernanceError"; this.code = code; }
+}
+const fail = (code, message) => { throw new GovernanceError(code, message); };
+const text = value => typeof value === "string" && value.length > 0 && value.length <= 256;
+const hash = value => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const timestamp = value => typeof value === "string" ? Date.parse(value) : NaN;
+const clone = value => structuredClone(value);
+const DOCUMENT_KINDS = ["governance-contribution", "governance-evidence-review", "governance-proposal", "governance-vote"];
+export function verifyGovernanceDocument(document) {
+  assertJSON(document);
+  if (!document || Object.keys(document).some(k => !["v", "id", "kind", "issuer", "publicKey", "createdAt", "payload", "signature"].includes(k)) ||
+      Buffer.byteLength(JSON.stringify(document)) > ACTION_MANIFEST.ceilings.bytes) fail("INVALID_DOCUMENT");
+  const { signature, ...body } = document;
+  if (body.v !== BASE_PROTOCOL || !DOCUMENT_KINDS.includes(body.kind) ||
+      typeof body.id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(body.id) ||
+      typeof body.issuer !== "string" || !SELF_CERTIFYING_AGENT_UUAID.test(body.issuer) ||
+      !hash(body.publicKey) || typeof signature !== "string" || !/^[0-9a-f]{128}$/.test(signature)) fail("INVALID_DOCUMENT");
+  if (Keychain.localIdFromKey(Buffer.from(body.publicKey, "hex")) !== body.issuer.split(":")[3] ||
+      !Keychain.verifyDetached(body.publicKey, Buffer.from(jcs(body)), Buffer.from(signature, "hex"))) fail("INVALID_SIGNATURE");
+  return body;
+}
+function freeze(value) {
+  if (value && typeof value === "object") { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+}
+export const CLAIM_TYPES = freeze(["AAIU", "AIOU", "Zilligon"]);
+export const ACTION_MANIFEST = freeze({
+  version: 1,
+  actions: {
+    "inspect": { scopes: ["local", "global"], permission: "observe" },
+    "submit-evidence": { scopes: ["local", "global"], permission: "contribute" },
+    "review-evidence": { scopes: ["local", "global"], permission: "review-evidence" },
+    "propose-alias": { scopes: ["local", "global"], permission: "propose" },
+    "review-proposal": { scopes: ["local", "global"], permission: "review" },
+  },
+  ceilings: { calls: 100, bytes: 32000, durationMs: 3600000 },
+  execution: "advisory-only",
+  globalRatification: false,
+  selfModification: false,
+});
+
+/** A one-run guard, not a scheduler or an execution capability. */
+export function createActionBudget({ scope = "local", maxCalls = 16, maxBytes = 8000, durationMs = 60000, clock = Date.now } = {}) {
+  context({ scope, namespace: "budget" });
+  const ceilings = ACTION_MANIFEST.ceilings;
+  for (const [value, ceiling] of [[maxCalls, ceilings.calls], [maxBytes, ceilings.bytes], [durationMs, ceilings.durationMs]]) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > ceiling) fail("INVALID_BUDGET");
+  }
+  if (typeof clock !== "function") fail("INVALID_CLOCK");
+  const start = clock();
+  if (!Number.isSafeInteger(start)) fail("INVALID_CLOCK");
+  let calls = 0, bytes = 0, last = start;
+  return freeze({
+    consume(request) {
+      const now = clock();
+      if (!Number.isSafeInteger(now) || now < last) fail("INVALID_CLOCK");
+      last = now;
+      if (now - start >= durationMs) fail("BUDGET_EXPIRED");
+      if (!request || Object.keys(request).some(k => !["action", "scope", "payload"].includes(k))) fail("INVALID_ACTION");
+      const definition = Object.hasOwn(ACTION_MANIFEST.actions, request.action) && ACTION_MANIFEST.actions[request.action];
+      if (!definition || request.scope !== scope || !definition.scopes.includes(scope)) fail("ACTION_FORBIDDEN");
+      let encoded;
+      try { assertJSON(request); encoded = JSON.stringify(request); } catch { fail("INVALID_ACTION"); }
+      const size = Buffer.byteLength(encoded);
+      if (calls + 1 > maxCalls || bytes + size > maxBytes) fail("BUDGET_EXCEEDED");
+      calls++; bytes += size;
+      return { calls, bytes, permission: definition.permission, executionAllowed: false };
+    },
+    status() { return { calls, bytes, maxCalls, maxBytes, scope, executionAllowed: false }; },
+  });
+}
+
+function context(value) {
+  if (!value || !["local", "global"].includes(value.scope) || !text(value.namespace)) fail("INVALID_CONTEXT");
+  return { scope: value.scope, namespace: value.namespace };
+}
+const sameContext = (a, b) => a.scope === b.scope && a.namespace === b.namespace;
+const defaults = {
+  halfLifeMs: 30 * 86400000, freshnessMs: 300000, documentMaxAgeMs: 86400000,
+  evidenceMaxAgeMs: 90 * 86400000, quorum: 2, maxRecords: 1000,
+  requiredGlobalClaims: [], agents: {}, claimIssuers: {}, credentialIssuers: [],
+};
+
+/**
+ * Signed, bounded, in-memory oversight. All data is advisory: even a locally
+ * approved proposal is never installed here. Persist signed inputs externally.
+ */
+export class PeerGovernance {
+  #policy; #adapters; #clock; #contributions = new Map(); #proposals = new Map();
+  #documents = new Map(); #tail = Promise.resolve(); #lastNow = -Infinity;
+  constructor({ policy = {}, adapters = {}, clock = Date.now } = {}) {
+    this.#policy = freeze(clone({ ...defaults, ...policy }));
+    this.#adapters = { ...adapters };
+    this.#clock = clock;
+    for (const key of ["halfLifeMs", "freshnessMs", "documentMaxAgeMs", "evidenceMaxAgeMs", "maxRecords"]) {
+      if (!Number.isSafeInteger(this.#policy[key]) || this.#policy[key] < 1) fail("INVALID_POLICY");
+    }
+    if (!Number.isSafeInteger(this.#policy.quorum) || this.#policy.quorum < 2 || this.#policy.quorum > 32 ||
+        this.#policy.maxRecords > 10000 || !Array.isArray(this.#policy.requiredGlobalClaims) ||
+        this.#policy.requiredGlobalClaims.some(type => !CLAIM_TYPES.includes(type)) ||
+        new Set(this.#policy.requiredGlobalClaims).size !== this.#policy.requiredGlobalClaims.length ||
+        !Array.isArray(this.#policy.credentialIssuers) || typeof clock !== "function") fail("INVALID_POLICY");
+    this.#now();
+  }
+  #now() {
+    const now = this.#clock();
+    if (!Number.isSafeInteger(now) || now < this.#lastNow) fail("INVALID_CLOCK");
+    this.#lastNow = now;
+    return now;
+  }
+  #binding(subject, publicKey) {
+    const binding = Object.hasOwn(this.#policy.agents, subject) && this.#policy.agents[subject];
+    if (!binding || binding.kind !== "agent" || binding.publicKey !== publicKey ||
+        !hash(publicKey) || !text(binding.controllerId) || !Array.isArray(binding.affiliations) ||
+        binding.affiliations.some(a => !text(a)) || !Array.isArray(binding.capabilities) ||
+        // A block on any binding of this key blocks the key, under every spelling.
+        Object.values(this.#policy.agents).some(a => a?.publicKey === publicKey && a.blocked === true)) fail("NOT_ADMITTED");
+    return binding;
+  }
+  async #adapter(name, request) {
+    if (typeof this.#adapters[name] !== "function") fail("VERIFIER_UNAVAILABLE", `${name} must be injected`);
+    try { return await this.#adapters[name](freeze(clone(request))); }
+    catch { fail("VERIFIER_UNAVAILABLE", `${name} could not verify`); }
+  }
+  #current(verdict, request) {
+    const now = this.#now();
+    return verdict && verdict.subject === request.subject && verdict.publicKey === request.publicKey &&
+      verdict.signatureValid === true && verdict.revoked === false && verdict.notExpired === true &&
+      Number.isFinite(timestamp(verdict.expiresAt)) && timestamp(verdict.expiresAt) > now &&
+      Number.isFinite(timestamp(verdict.checkedAt)) && timestamp(verdict.checkedAt) <= now &&
+      now - timestamp(verdict.checkedAt) <= this.#policy.freshnessMs;
+  }
+  async #authorize(subject, publicKey, capability, ctx) {
+    ctx = context(ctx);
+    const binding = this.#binding(subject, publicKey);
+    if (!binding.capabilities.includes(capability)) fail("CAPABILITY_DENIED");
+    const verdict = await this.#adapter("authorize", { subject, publicKey, capability, ...ctx });
+    if (verdict?.authorized !== true || verdict.subject !== subject || verdict.publicKey !== publicKey ||
+        verdict.capability !== capability || !sameContext(verdict, ctx)) fail("AUTHORIZATION_DENIED");
+    if (ctx.scope === "global" || binding.credentialId !== undefined) {
+      if (!text(binding.credentialId)) fail("CREDENTIAL_REQUIRED");
+      const request = { subject, publicKey, credentialId: binding.credentialId, ...ctx };
+      const credential = await this.#adapter("verifyCredential", request);
+      if (!this.#current(credential, request) || credential.valid !== true ||
+          credential.credentialId !== binding.credentialId ||
+          !sameContext(credential, ctx) ||
+          !this.#policy.credentialIssuers.includes(credential.issuer)) fail("CREDENTIAL_INVALID");
+    }
+    if (ctx.scope === "global") await this.checkClaims(subject, publicKey, ctx, this.#policy.requiredGlobalClaims);
+    return binding;
+  }
+  /** Badges, display names, domains and model/provider labels are never consulted. */
+  async checkClaims(subject, publicKey, ctx, required = CLAIM_TYPES) {
+    ctx = context(ctx);
+    const binding = this.#binding(subject, publicKey);
+    if (!Array.isArray(required) || required.some(type => !CLAIM_TYPES.includes(type))) fail("UNKNOWN_CLAIM");
+    const verified = [];
+    for (const type of required) {
+      const claimId = binding.claims?.[type];
+      const issuers = this.#policy.claimIssuers[type];
+      if (!text(claimId) || !Array.isArray(issuers) || !issuers.length) fail("CLAIM_UNVERIFIED");
+      const request = { subject, publicKey, type, claimId, ...ctx };
+      const verdict = await this.#adapter("verifyClaim", request);
+      if (!this.#current(verdict, request) || verdict.verified !== true || verdict.type !== type ||
+          verdict.claimId !== claimId || !sameContext(verdict, ctx) || !issuers.includes(verdict.issuer)) fail("CLAIM_UNVERIFIED");
+      verified.push({ type, claimId, issuer: verdict.issuer, expiresAt: verdict.expiresAt });
+    }
+    return verified;
+  }
+  #independent(a, b) {
+    if (a === b) fail("SELF_REVIEW");
+    const x = this.#policy.agents[a], y = this.#policy.agents[b];
+    if (!x || !y || x.publicKey === y.publicKey || x.controllerId === y.controllerId ||
+        x.affiliations.some(group => y.affiliations.includes(group)) ||
+        x.conflicts?.includes(b) || y.conflicts?.includes(a)) fail("REVIEWER_CONFLICT");
+  }
+  async #evidence(record) {
+    const verdict = await this.#adapter("verifyEvidence", record);
+    const now = this.#now(), observed = timestamp(verdict?.observedAt);
+    if (verdict?.verified !== true || verdict.subject !== record.subject ||
+        verdict.evidenceHash !== record.evidenceHash || !sameContext(verdict, record) ||
+        verdict.outcome !== "pass" || !Number.isFinite(observed) || observed > now ||
+        now - observed > this.#policy.evidenceMaxAgeMs ||
+        !Number.isFinite(verdict.quality) || verdict.quality <= 0 || verdict.quality > 1) fail("EVIDENCE_INVALID");
+    return { observedAt: verdict.observedAt, quality: verdict.quality };
+  }
+  async #validReviews(record, capability) {
+    const valid = [];
+    for (const review of record.reviews) {
+      try {
+        await this.#authorize(review.subject, review.publicKey, capability, record);
+        this.#independent(record.subject, review.subject);
+        valid.forEach(peer => this.#independent(peer.subject, review.subject));
+        valid.push(review);
+      } catch (error) {
+        if (!(error instanceof GovernanceError)) throw error;
+        // A revoked, conflicted or unavailable peer cannot supply credibility.
+      }
+    }
+    return { approvals: valid.filter(r => r.approve).map(r => r.subject), veto: valid.some(r => !r.approve) };
+  }
+  async credibility(subject, ctx) {
+    ctx = context(ctx);
+    let score = 0, accepted = 0;
+    const evidence = [];
+    for (const record of this.#contributions.values()) {
+      if (record.subject !== subject || !sameContext(record, ctx)) continue;
+      try {
+        await this.#authorize(subject, record.publicKey, "commons:contribute", ctx);
+        const measured = await this.#evidence(record);
+        const reviews = await this.#validReviews(record, "commons:review-evidence");
+        if (reviews.veto || reviews.approvals.length < this.#policy.quorum) continue;
+        // Use the earlier verified observation, never an adapter refresh time.
+        const observed = Math.min(timestamp(record.observedAt), timestamp(measured.observedAt));
+        if (this.#now() - observed > this.#policy.evidenceMaxAgeMs) continue;
+        const weight = Math.min(record.quality, measured.quality) * 2 ** (-(this.#now() - observed) / this.#policy.halfLifeMs);
+        score += weight; accepted++;
+        evidence.push({ id: record.id, weight, reviewers: reviews.approvals });
+      } catch (error) { if (!(error instanceof GovernanceError)) throw error; }
+    }
+    score = Math.min(100, score);
+    const tier = score >= 6 ? "steward" : score >= 3 ? "established" : score >= 1 ? "contributor" : "observer";
+    return { subject, ...ctx, score, accepted, tier, evidence, certified: false };
+  }
+  async permission(subject, publicKey, action, ctx) {
+    ctx = context(ctx);
+    const capabilities = { observe: "commons:observe", contribute: "commons:contribute",
+      "review-evidence": "commons:review-evidence", propose: "commons:evolve", review: "commons:review" };
+    if (!Object.hasOwn(capabilities, action)) fail("ACTION_FORBIDDEN");
+    await this.#authorize(subject, publicKey, capabilities[action], ctx);
+    const credibility = await this.credibility(subject, ctx);
+    const minimum = action === "propose" ? (ctx.scope === "local" ? 1 : 3) :
+      action === "review" ? (ctx.scope === "local" ? 3 : 6) : 0;
+    return { allowed: credibility.score >= minimum, minimum, ...credibility, action,
+      executionAllowed: false, ratified: false };
+  }
+  apply(document) {
+    // Snapshot before queuing: a caller cannot mutate a waiting signed input.
+    const snapshot = clone(document);
+    const next = this.#tail.then(() => this.#apply(snapshot));
+    this.#tail = next.catch(() => {});
+    return next;
+  }
+  async #apply(document) {
+    const body = verifyGovernanceDocument(document);
+    const now = this.#now(), created = timestamp(body.createdAt);
+    if (!Number.isFinite(created) || created > now || now - created > this.#policy.documentMaxAgeMs) fail("STALE_DOCUMENT");
+    if (this.#documents.has(document.id)) {
+      if (this.#documents.get(document.id) !== digest(document)) fail("DOCUMENT_CONFLICT");
+      return { duplicate: true };
+    }
+    if (this.#documents.size >= this.#policy.maxRecords) fail("RECORD_LIMIT");
+    const payload = body.payload;
+    const ctx = context(payload);
+    const fields = {
+      "governance-contribution": ["scope", "namespace", "evidenceHash"],
+      "governance-evidence-review": ["scope", "namespace", "contributionId", "evidenceHash", "approve", "rationale"],
+      "governance-vote": ["scope", "namespace", "proposalId", "evidenceHash", "approve", "rationale"],
+    };
+    if (fields[body.kind] && Object.keys(payload).some(k => !fields[body.kind].includes(k))) fail("INVALID_PAYLOAD");
+    let result;
+    if (body.kind === "governance-contribution") {
+      await this.#authorize(body.issuer, body.publicKey, "commons:contribute", ctx);
+      if (!hash(payload.evidenceHash)) fail("EVIDENCE_INVALID");
+      if ([...this.#contributions.values()].some(r => sameContext(r, ctx) && r.evidenceHash === payload.evidenceHash)) fail("EVIDENCE_REPLAY");
+      const record = { id: document.id, subject: body.issuer, publicKey: body.publicKey, ...ctx,
+        evidenceHash: payload.evidenceHash, reviews: [] };
+      const measured = await this.#evidence(record);
+      this.#contributions.set(record.id, { ...record, ...measured });
+      result = { id: record.id, status: "awaiting-independent-review", ratified: false };
+    } else if (body.kind === "governance-evidence-review") {
+      const record = this.#contributions.get(payload.contributionId);
+      if (!record || !sameContext(record, ctx)) fail("UNKNOWN_CONTRIBUTION");
+      await this.#authorize(body.issuer, body.publicKey, "commons:review-evidence", ctx);
+      await this.#authorize(record.subject, record.publicKey, "commons:contribute", ctx);
+      this.#reviewEligibility(record, body, payload);
+      if (payload.approve) await this.#evidence(record);
+      record.reviews.push(this.#review(body, payload));
+      result = { id: record.id, status: "review-recorded", ratified: false };
+    } else if (body.kind === "governance-proposal") {
+      const permission = await this.permission(body.issuer, body.publicKey, "propose", ctx);
+      if (!permission.allowed) fail("TIER_DENIED");
+      // The only proposed change is an exact phrase alias in immutable data.
+      // No executable patch, permission/quorum mutation, or signing changes.
+      if (Object.keys(payload).some(k => !["scope", "namespace", "change", "parentHash", "candidateHash", "rollbackHash", "phrase", "evidenceHash"].includes(k)) ||
+          payload.change !== "profile-alias" || !hash(payload.parentHash) ||
+          !hash(payload.candidateHash) || payload.parentHash === payload.candidateHash ||
+          payload.rollbackHash !== payload.parentHash || typeof payload.phrase !== "string" ||
+          !/^[A-Za-z][A-Za-z ]{7,79}$/.test(payload.phrase) || payload.phrase !== payload.phrase.trim() ||
+          !hash(payload.evidenceHash)) fail("UNSAFE_PROPOSAL");
+      const record = { id: document.id, subject: body.issuer, publicKey: body.publicKey, ...ctx,
+        evidenceHash: payload.evidenceHash, reviews: [], proposal: clone(payload) };
+      const measured = await this.#evidence(record);
+      this.#proposals.set(record.id, { ...record, ...measured });
+      result = { id: record.id, status: "pending", ratified: false, executionAllowed: false };
+    } else if (body.kind === "governance-vote") {
+      const record = this.#proposals.get(payload.proposalId);
+      if (!record || !sameContext(record, ctx)) fail("UNKNOWN_PROPOSAL");
+      const permission = await this.permission(body.issuer, body.publicKey, "review", ctx);
+      if (!permission.allowed) fail("TIER_DENIED");
+      this.#reviewEligibility(record, body, payload);
+      // Revalidate the author and all stored ballots before recording this one.
+      const author = await this.permission(record.subject, record.publicKey, "propose", ctx);
+      if (!author.allowed) fail("TIER_DENIED");
+      await this.#evidence(record);
+      const updated = { ...record, reviews: [...record.reviews, this.#review(body, payload)] };
+      result = await this.#proposalStatus(updated);
+      this.#proposals.set(record.id, updated);
+    } else fail("UNSUPPORTED_DOCUMENT");
+    this.#documents.set(document.id, digest(document));
+    return clone(result);
+  }
+  #reviewEligibility(record, body, payload) {
+    this.#independent(record.subject, body.issuer);
+    if (record.reviews.some(r => r.subject === body.issuer || r.publicKey === body.publicKey)) fail("DUPLICATE_REVIEW");
+    record.reviews.forEach(r => this.#independent(r.subject, body.issuer));
+    if (typeof payload.approve !== "boolean" || typeof payload.rationale !== "string" ||
+        payload.rationale.length < 3 || payload.rationale.length > 2000 ||
+        payload.evidenceHash !== record.evidenceHash) fail("INVALID_REVIEW");
+  }
+  #review(body, payload) {
+    return { subject: body.issuer, publicKey: body.publicKey, approve: payload.approve, rationale: payload.rationale };
+  }
+  async proposalStatus(id) {
+    const record = this.#proposals.get(id);
+    if (!record) fail("UNKNOWN_PROPOSAL");
+    return this.#proposalStatus(record);
+  }
+  async #proposalStatus(record) {
+    const author = await this.permission(record.subject, record.publicKey, "propose", record);
+    await this.#evidence(record);
+    const reviews = [];
+    for (const review of record.reviews) {
+      try {
+        const eligibility = await this.permission(review.subject, review.publicKey, "review", record);
+        this.#independent(record.subject, review.subject);
+        reviews.forEach(r => this.#independent(r.subject, review.subject));
+        if (eligibility.allowed) reviews.push(review);
+      } catch (error) { if (!(error instanceof GovernanceError)) throw error; }
+    }
+    const approvals = reviews.filter(r => r.approve).length;
+    const veto = reviews.some(r => !r.approve);
+    const ready = author.allowed && !veto && approvals >= this.#policy.quorum;
+    return { id: record.id, scope: record.scope, approvals, veto, status: record.scope === "global" ?
+      (ready ? "awaiting-independent-authority" : "pending") : (ready ? "local-peer-approved" : "pending"),
+    ratified: false, executionAllowed: false, rollbackHash: record.proposal.rollbackHash };
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,111 @@
+// Concrete transports and channel/tenant declarations
+import type { MessageTransport } from './transport.mjs';
+
+export interface Profile {
+  v:"agent-commons/1";id:string;namespace:string;name:string;scope:"local"|"tenant"|"global";
+  parent:string|null;revision:number;quorum:number;lexicon:Record<string,string>;fixtureHash:string;fixtures:string[];
+  benchmark:{tests:number;passed:number;originalBytes:number;wireBytes:number;reductionBps:number};
+}
+export interface Admission {
+  kind:"agent";publicKey:string;capabilities:string[];credentialId?:string;
+  controllerId?:string;affiliations?:string[];tenantId?:string;
+}
+export interface Policy {
+  mode:"local"|"global";offline?:boolean;agents:Record<string,Admission>;blocked?:string[];
+  registryUrl?:string;authorityUrl?:string;standardPins?:Record<string,string>;
+  channelsEnabled?:boolean;channels?:Record<string,{members:string[];allowForwarding?:boolean}>;tenantProfiles?:Record<string,string>;
+}
+export class Keychain {
+  constructor(path:string);_identity:any;static generate(options?:object):any;static localIdFromKey(key:Uint8Array):string;
+  static verifyDetached(key:string,data:Uint8Array,signature:Uint8Array):boolean;
+  load(options?:{passphrase?:string}):any;save(identity:any,options?:{passphrase?:string}):void;publicView():any;sign(data:any):Buffer;
+}
+export class CommonsStore {
+  constructor(path?:string);get(key:string,fallback?:any):any;set(key:string,value:any):void;
+  verify():boolean;audit():any[];close():void;db:any;
+}
+export class RegistryTrust {
+  constructor(options?:{policy?:Policy;client?:any;fetchImpl?:typeof fetch});
+  static isCanonicalTrust(value:unknown):boolean;
+  denyPermanently():void;
+  policy:Policy;authorize(id:string,key:string,capability?:string):Promise<any>;standards():Promise<any[]>;
+  publishedProfilePin(code:string,hash:string):Promise<any>;
+}
+export class AgentCommons {
+  constructor(options:{keychain:Keychain;store?:CommonsStore;policy?:Policy;carriers?:string[];transport?:MessageTransport;trust?:RegistryTrust});
+  readonly uuaid:string;readonly publicKey:string;store:CommonsStore;
+  profiles():Profile[];profile(id:string):Profile;addProfile(profile:Profile):Profile;
+  activeProfile(namespace:string):Profile;authorizedProfile(id:string):Promise<Profile>;
+  importGlobal(profile:Profile,code:string):Promise<Profile>;
+  propose(profileId:string,phrase:string):Promise<any>;vote(proposalId:string,approve:boolean,rationale?:string):Promise<any>;
+  apply(document:any):Promise<any>;prepareContribution(profileId:string,options?:{includeFixtures?:boolean}):Promise<any>;
+  send(options:{recipient:string;profileId?:string;namespace?:string;body:string;thread?:string;kind?:"message"|"profile-control";deferFlush?:boolean}):Promise<any>;
+  broadcast(options:{recipients:string[];profileId:string;body:string;thread?:string;kind?:"message"|"profile-control"}):Promise<any>;
+  receive(envelope:any):Promise<any>;flush():Promise<any[]>;poll():Promise<any[]>;status():any;
+  retryOutbox(envelopeId:string):Promise<any>;
+}
+export class CommonsCarrier {
+  constructor(options?:{store?:CommonsStore;trust?:RegistryTrust;keychain?:Keychain;publicUrl?:string;onEnvelope?:Function});
+  listen(port?:number,host?:string):Promise<any>;close():Promise<void>;
+}
+export function createProfile(options:{namespace:string;name:string;fixtures:string[];scope?:"local"|"tenant"|"global";lexicon?:Record<string,string>;parent?:string|null;revision?:number;quorum?:number}):Profile;
+export function verifyProfile(profile:Profile):Profile;
+export function proposeAlias(profile:Profile,phrase:string):any;
+export function encode(text:string,lexicon:Record<string,string>):string;
+export function decode(text:string,lexicon:Record<string,string>):string;
+export function benchmark(lexicon:Record<string,string>,fixtures:string[]):Profile["benchmark"];
+export function contribution(profile:Profile,options?:{includeFixtures?:boolean}):any;
+export function signDocument(keychain:Keychain,kind:string,payload:any):any;
+export function verifyDocument(document:any):any;
+export function digest(value:any):string;
+export const BASE_PROTOCOL:"agent-commons/1";
+export const REQUIRED_STANDARDS:string[];
+export function initialize(options?:{home?:string;target?:"local"|"agentnet.chat"|"zilligon.com"|"zilligons.com";name?:string}):any;
+export function loadRuntime(home?:string):{home:string;config:any;keychain:Keychain;store:CommonsStore;runtime:AgentCommons};
+export function runAgentLoop(options:{runtime:AgentCommons;respond:Function;spontaneous?:Function;maxTurns?:number;intervalMs?:number;signal?:AbortSignal;onEvent?:Function}):Promise<{turns:number;stopped:string}>;
+export class TrustError extends Error {code:string}
+export class CarrierClient {constructor(options:any);deliver(envelope:any,options?:any):Promise<any>;fetchInbox(carrier:string,options?:any):Promise<any>}
+export function localIdFromKey(key:Uint8Array):string;
+export function seal(keychain:Keychain,body:any):any;
+export function open(envelope:any,options?:any):{ok:boolean;reason?:string};
+export function decrypt(keychain:Keychain,envelope:any):any;
+export function envelopeSha(envelope:any):string;
+export { ContinuityMemory, ContinuityError, MemoryContinuityStore, verifyContinuity, CONTINUITY_PROTOCOL } from "./continuity.mjs";
+export interface FoundingMember {id:string;name:string;model:string;label:string;provider:string;role:string}
+export const FOUNDING_ROSTER:readonly FoundingMember[];
+export function initializeCohort(options:{home:string;target?:string;controllerId?:string}):any;
+export function cohortStatus(home:string):any;
+export class GovernanceError extends Error {code:string}
+export function verifyGovernanceDocument(document:any):any;
+export const CLAIM_TYPES:readonly string[];
+export const ACTION_MANIFEST:any;
+export function createActionBudget(options?:{scope?:"local"|"global";maxCalls?:number;maxBytes?:number;durationMs?:number;clock?:()=>number}):{consume(request:any):any;status():any};
+export class PeerGovernance {
+  constructor(options?:{policy?:any;adapters?:Record<string,Function>;clock?:()=>number});
+  checkClaims(subject:string,key:string,context:any,required?:readonly string[]):Promise<any>;
+  credibility(subject:string,context:any):Promise<any>;
+  permission(subject:string,key:string,action:string,context:any):Promise<any>;
+  apply(document:any):Promise<any>;proposalStatus(id:string):Promise<any>;
+}
+export class CollaborationError extends Error {code:string}
+export interface ModelAdapter {complete(request:{idempotencyKey:string;runId:string;phase:string;slot:any;input:any;maxTokens:number;signal?:AbortSignal}):Promise<any>}
+export interface CollaborationOptions {model:ModelAdapter;persistence?:any;memory?:any;needs?:any;verifier?:any;artifacts?:any;roster?:any[];limits?:any;clock?:{now():number};onEvent?:Function;signal?:AbortSignal;memoryFailurePolicy?:"halt"|"best-effort";allowAdvisory?:boolean;protectedPaths?:string[];hostMaintenance?:{reason:string;authorizedPaths:string[]}}
+export class CollaborationScheduler {
+  constructor(options:CollaborationOptions);
+  run(options:{runId:string;goal?:string;needs?:any}):Promise<any>;
+  provideNeeds(runId:string,answers:any):Promise<any>;status(runId:string):Promise<any>;cancel(reason?:string):void;
+}
+export function createCollaboration(options:CollaborationOptions):CollaborationScheduler;
+export function createRoster(overrides?:any):readonly any[];
+export function rosterFromModels(models:any):readonly any[];
+export function createFilePersistence(directory:string,options?:{integrity?:{sign(bytes:Buffer):string|Promise<string>;verify(bytes:Buffer,signature:string):boolean|Promise<boolean>}}):any;
+export function createMemoryPersistence():any;
+export function createContinuity(options?:any):any;
+export function memoryFromContinuity(journal:any,options?:any):any;
+export function validateProposal(raw:any,options?:any):any;
+export function validateUnifiedDiff(diff:string,path:string):any;
+export function validatePatchPath(path:string,allowedPaths:string[],policy?:any):string;
+export function hmacIntegrity(secret:string|Buffer):{sign(bytes:Buffer):string;verify(bytes:Buffer,signature:string):boolean};
+export * from "./transport.mjs";
+export * from "./channels.mjs";
+export * from "./governance-scope.mjs";

package/src/index.mjs

@@ -0,0 +1,15 @@
+export { AgentCommons } from "./runtime.mjs";
+export { CommonsCarrier } from "./carrier.mjs";
+export { CommonsStore } from "./store.mjs";
+export { RegistryTrust, REQUIRED_STANDARDS, TrustError } from "./trust.mjs";
+export { runAgentLoop } from "./loop.mjs";
+export { initialize, loadRuntime } from "./config.mjs";
+export { FOUNDING_ROSTER, initializeCohort, cohortStatus } from "./cohort.mjs";
+export { ContinuityMemory, ContinuityError, MemoryContinuityStore, verifyContinuity, CONTINUITY_PROTOCOL } from "./continuity.mjs";
+export { PeerGovernance, GovernanceError, verifyGovernanceDocument, createActionBudget, CLAIM_TYPES, ACTION_MANIFEST } from "./governance.mjs";
+export { CollaborationScheduler, CollaborationError, createCollaboration, createRoster, rosterFromModels, createFilePersistence, createMemoryPersistence, createContinuity, memoryFromContinuity, validateProposal, validateUnifiedDiff, validatePatchPath, hmacIntegrity } from "./collaboration.mjs";
+export { createProfile, verifyProfile, proposeAlias, encode, decode, benchmark, contribution, signDocument, verifyDocument, digest, BASE_PROTOCOL } from "./profiles.mjs";
+export { Keychain, localIdFromKey, CarrierClient, seal, open, decrypt, envelopeSha } from "./pillar.mjs";
+export { MemoryLoopbackTransport, PillarCarrierTransport } from "./transport.mjs";
+export { classifyThread, assertChannelSendAdmission, assertChannelReceiveAdmission, assertForwardingPermission, validateTenantBinding, CANONICAL_CHANNEL_REGEX, RESERVED_CHANNEL_PREFIX } from "./channels.mjs";
+export { classifyOperationTier, verifyPrincipalGovernance, MockPrincipalStatusVerifier } from "./governance-scope.mjs";