IF Commons GitHub

Identity agents

0040Active

0040-identity-agent · owner if · domain data

Requirements

FR-001checkpassing

An agent MUST be a principal with its autonomy level, its purpose, what it is built with, the risk at or above which its calls need an approval, how deep a delegation it may act in, and optionally a sponsor and how many runs it may have at once.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity.test.ts: on three engines an agent has an owner, versions that are pinned, tool grants, runs under delegations with the chain kept, budgets that are one per meter and window, calls that are one per index, and approvals bound to arguments

Proved by: data/suite/identity.test.ts

Written in: data/models/identity-agent/mod.ts

Tests: passed: suite/identity.test.ts on three engines an agent has an owner, versions that are pinned, tool grants, runs under

FR-002checkpassing

An agent version MUST pin the provider, the model, the model's snapshot, the hash of the prompt and the hash of the tool manifest, be unique by agent and label, and say where it is (candidate, approved, active, retired or revoked); and the model MUST hold no prompt, no argument and no secret in the clear.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity.test.ts: on three engines an agent has an owner, versions that are pinned, tool grants, runs under delegations with the chain kept, budgets that are one per meter and window, calls that are one per index, and approvals bound to arguments; suite/identity.test.ts: no concept of any module holds a secret, a prompt or raw arguments in the clear, every concept that holds a secret is restricted, and an agent's provenance and its calls are kept as pinned versions and hashes

Proved by: data/suite/identity.test.ts

Written in: data/models/identity-agent/mod.ts

Tests: passed: suite/identity.test.ts no concept of any module holds a secret, a prompt or raw arguments in the clear, every con; passed: suite/identity.test.ts on three engines an agent has an owner, versions that are pinned, tool grants, runs under

FR-003checkpassing

A tool MUST say the permission a call needs, its risk and its side effect, and a tool grant MUST give a tool to an agent once, with an optional condition on the call, whether it needs approval and how many calls a run may make.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity.test.ts: on three engines an agent has an owner, versions that are pinned, tool grants, runs under delegations with the chain kept, budgets that are one per meter and window, calls that are one per index, and approvals bound to arguments

Proved by: data/suite/identity.test.ts

Written in: data/models/identity-agent/mod.ts

Tests: passed: suite/identity.test.ts on three engines an agent has an owner, versions that are pinned, tool grants, runs under

FR-004checkpassing

A run MUST say its agent, its version, its tenant, who started it, the delegation it acts under and the run that started it; a tool call MUST be one for an index of a run, with what was decided about it, a hash of its arguments and its tokens and cost; a budget MUST be one for an agent or delegation or run and a meter and a window, with its limit, what is used and a version that makes two updates unable to both win; and an approval MUST say the action, a hash of the arguments, who may approve, its status and its expiry, and be kept a year.

Enforced (check): .github: cd commons/data && bun run verify — suite/identity.test.ts: on three engines an agent has an owner, versions that are pinned, tool grants, runs under delegations with the chain kept, budgets that are one per meter and window, calls that are one per index, and approvals bound to arguments; suite/identity.test.ts: no concept of any module holds a secret, a prompt or raw arguments in the clear, every concept that holds a secret is restricted, and an agent's provenance and its calls are kept as pinned versions and hashes

Proved by: data/suite/identity.test.ts

Written in: data/models/identity-agent/mod.ts

Tests: passed: suite/identity.test.ts no concept of any module holds a secret, a prompt or raw arguments in the clear, every con; passed: suite/identity.test.ts on three engines an agent has an owner, versions that are pinned, tool grants, runs under

Out of scope

  • The operations that do the business of this module: a later specification, run by the operations runtime (0031).
  • How a decision is made from these tables: the decision engine is a later specification.

Edge cases

  • A kind of principal that has no table of its own in this module: it is held by the principal and its roles alone, per FR-001.
  • DuckDB loads this schema and can read it, and cannot update a row that another row refers to; operations that change principals, runs or delegations are for PostgreSQL and SQLite, per FR-001.

Assumptions

  • The application makes identifiers, hashes and timestamps; the database stores them and refuses what the constraints say.

Open questions

OQ-1open question

The constraints that governance cannot say (acyclic hierarchies, a subtype row only for a principal of its kind) are checks of the operations and of invariant queries, not of the schema.

Key entities

  • Agents - what this module holds, as its requirements say.

Success criteria

SC-001success criterion

A project composes this module only when it needs it, and the database refuses what the requirements say it must refuse.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, models/identity-agent/mod

Titles, headings, exports, tables, columns and requirements. Esc closes.