@zhin.js/harness 0.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/harness",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "description": "ADR 0048 Agent Harness: actors, mail, engagements, attenuated authority, budgets and the guard kernel",
   "type": "module",
   "main": "./lib/index.js",
@@ -13,12 +13,12 @@
   },
   "files": [
     "lib",
-    "src"
+    "README.md"
   ],
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/database": "1.1.6"
+    "@zhin.js/database": "1.1.7"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/authority.ts

@@ -1,194 +0,0 @@
-/**
- * ADR 0048 §3.4 invariant 1 — authority is only ever attenuated.
- *
- * Effective authority of a delegatee = delegator authority ∩ the narrowing
- * declared at hand-off ∩ the delegatee agent's ceiling. Every function here is
- * pure: inputs are never mutated and every returned object is frozen.
- */
-import {
-  ALL,
-  TRUST_LEVELS,
-  intersectScopes,
-  scopeHas,
-  scopeWithin,
-  type ActorId,
-  type AgentCeiling,
-  type AgentName,
-  type Authority,
-  type AuthorityNarrowing,
-  type EgressScope,
-  type NameScope,
-  type Principal,
-  type TrustLevel,
-} from './contracts.js';
-
-// ---------------------------------------------------------------------------
-// Trust
-// ---------------------------------------------------------------------------
-
-function trustRank(level: TrustLevel): number {
-  const rank = TRUST_LEVELS.indexOf(level);
-  if (rank < 0) throw new TypeError(`Unknown trust level: ${String(level)}`);
-  return rank;
-}
-
-function isTrustLevel(value: unknown): value is TrustLevel {
-  return typeof value === 'string' && (TRUST_LEVELS as readonly string[]).includes(value);
-}
-
-/** Negative when `a` is lower than `b`, 0 when equal, positive when higher. Throws on unknown levels. */
-export function compareTrust(a: TrustLevel, b: TrustLevel): number {
-  return trustRank(a) - trustRank(b);
-}
-
-/** The lowest of the given levels. Throws when called with none. */
-export function minTrust(...levels: readonly TrustLevel[]): TrustLevel {
-  if (levels.length === 0) throw new TypeError('minTrust requires at least one level');
-  let lowest = levels[0];
-  for (const level of levels) {
-    if (compareTrust(level, lowest) < 0) lowest = level;
-  }
-  trustRank(lowest);
-  return lowest;
-}
-
-// ---------------------------------------------------------------------------
-// Construction
-// ---------------------------------------------------------------------------
-
-function freezeScope(scope: NameScope): NameScope {
-  return intersectScopes(scope, ALL);
-}
-
-function freezePrincipal(principal: Principal): Principal {
-  return Object.freeze({
-    kind: principal.kind,
-    id: principal.id,
-    trust: principal.trust,
-    ...(principal.venue ? { venue: Object.freeze({ kind: principal.venue.kind, id: principal.venue.id }) } : {}),
-  });
-}
-
-function freezeEgress(network: boolean, hosts: NameScope): EgressScope {
-  return Object.freeze({ network, hosts: freezeScope(hosts) });
-}
-
-function dedupe(ids: readonly string[]): readonly string[] {
-  return Object.freeze([...new Set(ids)]);
-}
-
-/**
- * Authority of an engagement's root mail: what the principal may do through
- * this agent. Approvers are the human principal first, then configured ids.
- */
-export function rootAuthority(
-  principal: Principal,
-  ceiling: AgentCeiling,
-  options: { readonly approvers?: readonly string[] } = {},
-): Authority {
-  const approvers = [...(principal.kind === 'human' ? [principal.id] : []), ...(options.approvers ?? [])];
-  return Object.freeze({
-    principal: freezePrincipal(principal),
-    trust: minTrust(principal.trust, ceiling.maxTrust),
-    tools: freezeScope(ceiling.tools),
-    contacts: freezeScope(ceiling.contacts),
-    egress: freezeEgress(ceiling.egress.network, ceiling.egress.hosts),
-    approvers: dedupe(approvers),
-    chain: Object.freeze([]) as readonly ActorId[],
-  });
-}
-
-/**
- * Derives the authority handed to `target` by actor `via`. Never widens: a
- * narrowing asking for more than the parent just gets the intersection.
- * Principal and approvers are carried over unchanged.
- */
-export function attenuate(
-  parent: Authority,
-  narrowing: AuthorityNarrowing,
-  target: AgentCeiling,
-  via: ActorId,
-): Authority {
-  const tools = intersectScopes(intersectScopes(parent.tools, narrowing.tools ?? ALL), target.tools);
-  const contacts = intersectScopes(intersectScopes(parent.contacts, narrowing.contacts ?? ALL), target.contacts);
-  const trust = minTrust(parent.trust, narrowing.trust ?? parent.trust, target.maxTrust);
-  const network = parent.egress.network && (narrowing.egress?.network ?? true) && target.egress.network;
-  const hosts = intersectScopes(
-    intersectScopes(parent.egress.hosts, narrowing.egress?.hosts ?? ALL),
-    target.egress.hosts,
-  );
-  return Object.freeze({
-    principal: freezePrincipal(parent.principal),
-    trust,
-    tools,
-    contacts,
-    egress: freezeEgress(network, hosts),
-    approvers: Object.freeze([...parent.approvers]),
-    chain: Object.freeze([...parent.chain, via]),
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Verification (called by the guard kernel)
-// ---------------------------------------------------------------------------
-
-function sameJson(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
-  if (Array.isArray(a) !== Array.isArray(b)) return false;
-  const aKeys = Object.keys(a).filter((key) => (a as Record<string, unknown>)[key] !== undefined);
-  const bKeys = Object.keys(b).filter((key) => (b as Record<string, unknown>)[key] !== undefined);
-  if (aKeys.length !== bKeys.length) return false;
-  return aKeys.every(
-    (key) =>
-      Object.prototype.hasOwnProperty.call(b, key) &&
-      sameJson((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
-  );
-}
-
-function sameList(a: readonly string[], b: readonly string[]): boolean {
-  return a.length === b.length && a.every((value, index) => value === b[index]);
-}
-
-/**
- * `true` iff `child` is a single, valid attenuation step from `parent`:
- * same principal and approvers, no wider trust / tools / contacts / egress,
- * and a chain that extends the parent's by exactly one actor.
- */
-export function isAttenuationOf(child: Authority, parent: Authority): boolean {
-  if (!isTrustLevel(child.trust) || !isTrustLevel(parent.trust)) return false;
-  if (!isTrustLevel(child.principal.trust)) return false;
-  if (!sameJson(child.principal, parent.principal)) return false;
-  if (!sameList(child.approvers, parent.approvers)) return false;
-  if (compareTrust(child.trust, parent.trust) > 0) return false;
-  if (compareTrust(child.trust, child.principal.trust) > 0) return false;
-  if (!scopeWithin(child.tools, parent.tools)) return false;
-  if (!scopeWithin(child.contacts, parent.contacts)) return false;
-  if (child.egress.network && !parent.egress.network) return false;
-  if (!scopeWithin(child.egress.hosts, parent.egress.hosts)) return false;
-  if (child.chain.length !== parent.chain.length + 1) return false;
-  return parent.chain.every((actor, index) => child.chain[index] === actor);
-}
-
-// ---------------------------------------------------------------------------
-// Queries
-// ---------------------------------------------------------------------------
-
-/** Agent name of an actor id: the part before `#`. */
-export function agentOf(actor: ActorId): AgentName {
-  const hash = actor.indexOf('#');
-  return hash < 0 ? actor : actor.slice(0, hash);
-}
-
-export function canCall(authority: Authority, tool: string): boolean {
-  return scopeHas(authority.tools, tool);
-}
-
-/** Takes an agent name; use `agentOf(actor)` for actor ids. */
-export function canContact(authority: Authority, agentName: AgentName): boolean {
-  return scopeHas(authority.contacts, agentName);
-}
-
-export function allowsHost(authority: Authority, host: string): boolean {
-  return authority.egress.network && scopeHas(authority.egress.hosts, host);
-}

package/src/budget.ts

@@ -1,181 +0,0 @@
-/**
- * In-memory conserved budget ledger (ADR 0048 §3.4 invariant 2).
- *
- * Semantics, per budget key:
- * - consumed(g)  = g.ownSpent + Σ rolledUp(closed child), where
- *                  rolledUp(c) = min(consumed(c), granted(c)).
- *                  Overspend beyond a grant stays visible on that grant's own
- *                  snapshot but never inflates the parent's accounting, so
- *                  a subtree can never consume more than it was granted
- *                  from above (conservation).
- * - reserved(g)  = Σ granted(c) over OPEN children c.
- * - remaining(g) = granted(g) - consumed(g) - reserved(g)  (may go negative
- *                  after an overspending charge).
- * - Snapshot: `spent` = consumed(g) (own + closed children), `reservedForChildren`
- *   = reserved(g), `remaining` as above.
- *
- * grant(): requested keys above the parent's remaining fail whole with
- * `budget_exceeded` (no partial grant, no clamping). Omitted keys default to
- * floor(parent remaining / 2), never below 0. The child's granted amount is
- * reserved on the parent immediately.
- *
- * charge(): always records the usage on an open grant; reports
- * `budget_exceeded` (with the exhausted keys) when any remaining < 0.
- *
- * close(): closes open descendants first (deepest first), then the grant.
- * The parent's reservation is released and the child's consumed amount is
- * rolled up, i.e. unspent returns to the parent. Idempotent.
- */
-import {
-  BUDGET_KEYS,
-  type BudgetAmounts,
-  type BudgetKey,
-  type BudgetLedger,
-  type BudgetResult,
-  type BudgetSnapshot,
-  type GrantId,
-} from './contracts.js';
-
-type Mutable = { -readonly [K in BudgetKey]: number };
-
-interface Node {
-  readonly id: GrantId;
-  readonly parent?: Node;
-  readonly granted: BudgetAmounts;
-  readonly ownSpent: Mutable;
-  readonly rolledUp: Mutable;
-  readonly children: Node[];
-  closed: boolean;
-}
-
-type FailCode = 'budget_exceeded' | 'grant_closed' | 'unknown_grant' | 'invalid_amount';
-
-const zero = (): Mutable => ({ modelCalls: 0, tokens: 0, wallMs: 0, sideEffects: 0 });
-const valid = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0;
-
-export interface InMemoryBudgetLedgerOptions {
-  readonly idFactory?: () => GrantId;
-}
-
-export class InMemoryBudgetLedger implements BudgetLedger {
-  private readonly nodes = new Map<GrantId, Node>();
-  private readonly idFactory: () => GrantId;
-
-  constructor(options: InMemoryBudgetLedgerOptions = {}) {
-    let n = 0;
-    this.idFactory = options.idFactory ?? (() => `g${++n}`);
-  }
-
-  openRoot(amounts: BudgetAmounts): GrantId {
-    for (const k of BUDGET_KEYS) {
-      if (!valid(amounts?.[k])) throw new TypeError(`invalid budget amount for ${k}: ${String(amounts?.[k])}`);
-    }
-    return this.create(undefined, { ...amounts }).id;
-  }
-
-  grant(parentId: GrantId, request: Partial<BudgetAmounts>): BudgetResult<GrantId> {
-    const parent = this.nodes.get(parentId);
-    if (!parent) return fail('unknown_grant', `unknown grant ${parentId}`);
-    if (parent.closed) return fail('grant_closed', `grant ${parentId} is closed`);
-    const bad = invalidKey(request);
-    if (bad) return fail('invalid_amount', `invalid amount for ${bad}`);
-    const rem = this.remaining(parent);
-    const exhausted = BUDGET_KEYS.filter((k) => request[k] !== undefined && (request[k] as number) > rem[k]);
-    if (exhausted.length > 0) {
-      return fail('budget_exceeded', `requested more than parent remaining for: ${exhausted.join(', ')}`, exhausted);
-    }
-    const amounts = zero();
-    for (const k of BUDGET_KEYS) amounts[k] = request[k] ?? Math.max(0, Math.floor(rem[k] / 2));
-    return { ok: true, value: this.create(parent, amounts).id };
-  }
-
-  charge(grantId: GrantId, usage: Partial<BudgetAmounts>): BudgetResult<BudgetSnapshot> {
-    const node = this.nodes.get(grantId);
-    if (!node) return fail('unknown_grant', `unknown grant ${grantId}`);
-    const bad = invalidKey(usage);
-    if (bad) return fail('invalid_amount', `invalid amount for ${bad}`);
-    if (node.closed) return fail('grant_closed', `grant ${grantId} is closed`);
-    for (const k of BUDGET_KEYS) node.ownSpent[k] += usage[k] ?? 0;
-    const rem = this.remaining(node);
-    const exhausted = BUDGET_KEYS.filter((k) => rem[k] < 0);
-    if (exhausted.length > 0) {
-      return fail('budget_exceeded', `budget exceeded for: ${exhausted.join(', ')}`, exhausted);
-    }
-    return { ok: true, value: this.snap(node) };
-  }
-
-  close(grantId: GrantId): BudgetResult<BudgetSnapshot> {
-    const node = this.nodes.get(grantId);
-    if (!node) return fail('unknown_grant', `unknown grant ${grantId}`);
-    this.closeNode(node);
-    return { ok: true, value: this.snap(node) };
-  }
-
-  snapshot(grantId: GrantId): BudgetSnapshot | undefined {
-    const node = this.nodes.get(grantId);
-    return node ? this.snap(node) : undefined;
-  }
-
-  private create(parent: Node | undefined, granted: BudgetAmounts): Node {
-    const id = this.idFactory();
-    const node: Node = { id, parent, granted, ownSpent: zero(), rolledUp: zero(), children: [], closed: false };
-    this.nodes.set(id, node);
-    parent?.children.push(node);
-    return node;
-  }
-
-  private closeNode(node: Node): void {
-    if (node.closed) return;
-    for (const child of node.children) this.closeNode(child);
-    node.closed = true;
-    if (node.parent) {
-      const consumed = this.consumed(node);
-      for (const k of BUDGET_KEYS) node.parent.rolledUp[k] += Math.min(consumed[k], node.granted[k]);
-    }
-  }
-
-  private consumed(node: Node): Mutable {
-    const out = zero();
-    for (const k of BUDGET_KEYS) out[k] = node.ownSpent[k] + node.rolledUp[k];
-    return out;
-  }
-
-  private reserved(node: Node): Mutable {
-    const out = zero();
-    for (const c of node.children) if (!c.closed) for (const k of BUDGET_KEYS) out[k] += c.granted[k];
-    return out;
-  }
-
-  private remaining(node: Node): Mutable {
-    const c = this.consumed(node);
-    const r = this.reserved(node);
-    const out = zero();
-    for (const k of BUDGET_KEYS) out[k] = node.granted[k] - c[k] - r[k];
-    return out;
-  }
-
-  private snap(node: Node): BudgetSnapshot {
-    return Object.freeze({
-      grantId: node.id,
-      ...(node.parent ? { parentId: node.parent.id } : {}),
-      granted: Object.freeze({ ...node.granted }),
-      spent: Object.freeze(this.consumed(node)),
-      reservedForChildren: Object.freeze(this.reserved(node)),
-      remaining: Object.freeze(this.remaining(node)),
-      closed: node.closed,
-    });
-  }
-}
-
-function invalidKey(amounts: Partial<BudgetAmounts>): BudgetKey | undefined {
-  if (amounts === null || typeof amounts !== 'object') return BUDGET_KEYS[0];
-  return BUDGET_KEYS.find((k) => amounts[k] !== undefined && !valid(amounts[k]));
-}
-
-function fail(
-  code: FailCode,
-  message: string,
-  exhausted?: readonly BudgetKey[],
-): { readonly ok: false; readonly code: FailCode; readonly exhausted?: readonly BudgetKey[]; readonly message: string } {
-  return exhausted ? { ok: false, code, exhausted, message } : { ok: false, code, message };
-}