Koinii actor identity: per-agent contexts as the identity substrate AND the write boundary, an admin-only agent registry, and the one auth seam whose strength is conditional on the adjudication policy.
The engine deliberately pushes per-caller identity OUT — *creator* is an
unauthenticated annotation and the daemon's only auth is one shared bearer token —
so koinii's answer is the context lattice, not a new auth subsystem:
CxAtlas, lifted under the
channel by (genlCx CxDeploy CxAtlas). A reader of CxDeploy sees the union of
every agent's assertions; CxAtlas alone is 'everything Atlas said' — a plain
context read. Because context is part of sentex identity, Atlas's P and
Boreas's P are two DISTINCT sentexes, each with its own creator, so
first-writer-wins loses no co-source (co-attribution-survives?).The auth seam is conditional on policy (koinii design D4):
*creator* bound by convention, the write routed
to the agent's own context, trusted because the agents are. Correct for a
notify-only deployment. It defends fat-fingers, NOT attackers: authenticate
trusts the claimed id with no proof, so a client may claim any identity. State
plainly that identity is unauthenticated here.authenticate
verifies a credential (the verify-fn seam — sign-at-ingest, an authenticating
proxy, or A2A AgentCards / DIDs) and REFUSES an unverified request; the
write-boundary is enforced at that same seam.Every write goes through the provenance-stamping assert path — NEVER
bulk-assert-facts!, which binds *bulk-load?* and writes no provenance at all.
Koinii actor identity: per-agent contexts as the identity substrate AND the write boundary, an admin-only agent registry, and the one auth seam whose strength is conditional on the adjudication policy. The engine deliberately pushes per-caller identity OUT — `*creator*` is an unauthenticated annotation and the daemon's only auth is one shared bearer token — so koinii's answer is the context lattice, not a new auth subsystem: - **An agent IS its context.** Atlas writes into `CxAtlas`, lifted under the channel by `(genlCx CxDeploy CxAtlas)`. A reader of `CxDeploy` sees the union of every agent's assertions; `CxAtlas` alone is 'everything Atlas said' — a plain context read. Because context is part of sentex identity, Atlas's `P` and Boreas's `P` are two DISTINCT sentexes, each with its own creator, so first-writer-wins loses no co-source (`co-attribution-survives?`). - **The write boundary is 'your own context, and nothing else.'** That is the one enforcement point identity needs, and it is why the registry context is the one context agents may NOT write — the governed may not write the authority that governs them. The auth seam is conditional on policy (koinii design D4): - **Cooperative** (the default) — `*creator*` bound by convention, the write routed to the agent's own context, trusted because the agents are. Correct for a notify-only deployment. It defends fat-fingers, NOT attackers: `authenticate` trusts the claimed id with no proof, so a client may claim any identity. State plainly that identity is unauthenticated here. - **Proof-tier** — REQUIRED the moment trust-resolve is enabled, because trust-weighting a spoofable identity is worse than no trust. `authenticate` verifies a credential (the `verify-fn` seam — sign-at-ingest, an authenticating proxy, or A2A AgentCards / DIDs) and REFUSES an unverified request; the write-boundary is enforced at that same seam. Every write goes through the provenance-stamping `assert` path — NEVER `bulk-assert-facts!`, which binds `*bulk-load?*` and writes no provenance at all.
The identity policy (koinii design D4).
:cooperative (the default) — *creator* is trusted by convention; correct for
a notify-only deployment. It defends fat-fingers, not attackers: a client may
claim any id, and there is no barrier to impersonation.:proof-tier — REQUIRED once trust-resolve is enabled; a credential is verified
at ingest and an unverified request is refused. Trust-weighting a spoofable
identity is worse than no trust.The identity policy (koinii design D4). - `:cooperative` (the default) — `*creator*` is trusted by convention; correct for a notify-only deployment. It defends fat-fingers, not attackers: a client may claim any id, and there is no barrier to impersonation. - `:proof-tier` — REQUIRED once trust-resolve is enabled; a credential is verified at ingest and an unverified request is refused. Trust-weighting a spoofable identity is worse than no trust.
The proof-tier verifier SEAM: (verify-fn claimed-id credential) returns truthy
iff the credential proves the claim. nil ships no crypto — the design provides the
seam (sign-at-ingest / an authenticating proxy / A2A AgentCards / DIDs) and the
deployment wires it. Under :proof-tier a nil verifier fails CLOSED: every
request is refused rather than silently trusted.
The proof-tier verifier SEAM: `(verify-fn claimed-id credential)` returns truthy iff the credential proves the claim. nil ships no crypto — the design provides the seam (sign-at-ingest / an authenticating proxy / A2A AgentCards / DIDs) and the deployment wires it. Under `:proof-tier` a nil verifier fails CLOSED: every request is refused rather than silently trusted.
(admin-principal)(admin-principal admin-id)The out-of-band admin principal — the only writer of CxRegistry. Not a governed
agent: its :admin? capability is what the registry write-boundary checks, and it
is minted here rather than by authenticate precisely because it is out of band.
The out-of-band admin principal — the only writer of `CxRegistry`. Not a governed agent: its `:admin?` capability is what the registry write-boundary checks, and it is minted here rather than by `authenticate` precisely because it is out of band.
(agent-context kb deploy-ctx agent-id)Create/lift agent-id's per-agent context under the channel deploy-ctx so the
channel sees it — (genlCx deploy-ctx CxAtlas) — and root it under CxCore so the
agent speaks the core vocabulary. Both edges are monotonic topology. Returns the
agent context symbol.
Create/lift `agent-id`'s per-agent context under the channel `deploy-ctx` so the channel sees it — `(genlCx deploy-ctx CxAtlas)` — and root it under `CxCore` so the agent speaks the core vocabulary. Both edges are monotonic topology. Returns the agent context symbol.
(authenticate request)(authenticate request opts)Turn a request into an authenticated principal, or refuse — the identity seam,
behaviour CONDITIONAL ON POLICY.
request is {:claimed-id <agent-id> :credential <opaque> :source <str>}.
opts may override {:policy … :verify-fn …} (defaulting to *policy* /
*verify-fn*). Returns a principal
{:id :context :source :policy :authenticated?} whose :context is
(context-for :id) — derived, never client-supplied.
:cooperative — trust the claimed id; :authenticated? false records that the
identity is UNVERIFIED (the documented cooperative gap).:proof-tier — require a verify-fn and a passing credential; otherwise throw
:koinii/identity-unverified. THIS is where a client is stopped from stamping
another agent's identity on its own write.Turn a `request` into an authenticated principal, or refuse — the identity seam,
behaviour CONDITIONAL ON POLICY.
`request` is `{:claimed-id <agent-id> :credential <opaque> :source <str>}`.
`opts` may override `{:policy … :verify-fn …}` (defaulting to `*policy*` /
`*verify-fn*`). Returns a principal
`{:id :context :source :policy :authenticated?}` whose `:context` is
`(context-for :id)` — derived, never client-supplied.
- `:cooperative` — trust the claimed id; `:authenticated? false` records that the
identity is UNVERIFIED (the documented cooperative gap).
- `:proof-tier` — require a `verify-fn` and a passing credential; otherwise throw
`:koinii/identity-unverified`. THIS is where a client is stopped from stamping
another agent's identity on its own write.(check-write-boundary! principal target-ctx)Throw if principal may not write target-ctx; else return nil. The single
enforcement point — the seam a proof-tier deployment relies on, and the reason no
call site can route a write into a context it does not own.
Throw if `principal` may not write `target-ctx`; else return nil. The single enforcement point — the seam a proof-tier deployment relies on, and the reason no call site can route a write into a context it does not own.
(co-attribution kb sentence)Every context that independently asserts sentence — the set of per-agent contexts
backing a claim. Because context is part of sentex identity, an agent re-asserting
a fact another already stated is a DISTINCT sentex in a DISTINCT context, so
first-writer-wins provenance loses no co-source: 'how many sources back P' is this
set, recovered from the per-agent contexts with no separate source index.
Every context that independently asserts `sentence` — the set of per-agent contexts backing a claim. Because context is part of sentex identity, an agent re-asserting a fact another already stated is a DISTINCT sentex in a DISTINCT context, so first-writer-wins provenance loses no co-source: 'how many sources back P' is this set, recovered from the per-agent contexts with no separate source index.
(context-for agent-id)The per-agent context for agent-id, by convention: AgentAtlas -> CxAtlas
(a leading Agent is dropped, then Cx-prefixed). The destination of an agent's
writes is a DETERMINISTIC function of its authenticated id, so 'write only your own
context' needs no separate lookup — identity fixes the destination, and a principal
can never be routed to a context that is not its own.
The per-agent context for `agent-id`, by convention: `AgentAtlas` -> `CxAtlas` (a leading `Agent` is dropped, then `Cx`-prefixed). The destination of an agent's writes is a DETERMINISTIC function of its authenticated id, so 'write only your own context' needs no separate lookup — identity fixes the destination, and a principal can never be routed to a context that is not its own.
(display-name-of kb agent-id)The stored display name for agent-id, or nil.
The stored display name for `agent-id`, or nil.
(ingest kb principal sentence)The sanctioned everyday write path. Given an authenticated principal (from
authenticate) and a sentence, assert it into the agent's OWN context with
*creator* bound to the authenticated id — so no call site can forget either the
attribution or the routing. Automatic routing means this form CANNOT name another
agent's context. Returns the handle.
The sanctioned everyday write path. Given an authenticated `principal` (from `authenticate`) and a `sentence`, assert it into the agent's OWN context with `*creator*` bound to the authenticated id — so no call site can forget either the attribution or the routing. Automatic routing means this form CANNOT name another agent's context. Returns the handle.
(ingest-into kb principal target-ctx sentence)The explicit-target write path, for a caller that names target-ctx — the write
goes through the SAME boundary check ingest does, so a principal authenticated as
Boreas targeting CxAtlas is refused (:koinii/foreign-context) and any governed
agent targeting CxRegistry is refused (:koinii/registry-forbidden). Returns the
handle.
The explicit-target write path, for a caller that names `target-ctx` — the write goes through the SAME boundary check `ingest` does, so a principal authenticated as Boreas targeting `CxAtlas` is refused (`:koinii/foreign-context`) and any governed agent targeting `CxRegistry` is refused (`:koinii/registry-forbidden`). Returns the handle.
(load-registry kb)Load the CxRegistry vocabulary into kb from resources/kb/koinii/CxRegistry.txt.
Koinii KB files are not auto-discovered (the starter only walks upper/ and
middle/), so this explicit loader is how the registry context comes into being.
Requires CxCore already loaded (CxRegistry wires (genlCx CxRegistry CxCore)).
Returns kb.
Load the CxRegistry vocabulary into `kb` from resources/kb/koinii/CxRegistry.txt. Koinii KB files are not auto-discovered (the starter only walks upper/ and middle/), so this explicit loader is how the registry context comes into being. Requires CxCore already loaded (CxRegistry wires `(genlCx CxRegistry CxCore)`). Returns kb.
(load-seed-context kb context)Assert every sentence of koinii's seed KB file for context into that context,
order-insensitively: a sentence refused because content further down the file has
not arrived yet is retried rather than fatal, so the file may be grouped term-centrically
rather than in dependency order. The sentences that survive a round changing nothing are
re-asserted without a catch, so a genuinely ill-formed one still throws. Returns kb.
Assert every sentence of koinii's seed KB file for `context` into that context, **order-insensitively**: a sentence refused because content further down the file has not arrived yet is retried rather than fatal, so the file may be grouped term-centrically rather than in dependency order. The sentences that survive a round changing nothing are re-asserted without a catch, so a genuinely ill-formed one still throws. Returns kb.
(register-agent kb principal agent-id display-name trust)Register agent-id in CxRegistry — its membership mark, display name, and
bootstrap trust value — as the admin principal. Refused
(:koinii/registry-forbidden) if principal is not admin, so a governed agent
cannot self-register or self-promote. Returns the agent id.
Register `agent-id` in `CxRegistry` — its membership mark, display name, and bootstrap trust value — as the admin `principal`. Refused (`:koinii/registry-forbidden`) if `principal` is not admin, so a governed agent cannot self-register or self-promote. Returns the agent id.
(registered-agents kb)Every registered agent id — the extent of (agent ?a) in CxRegistry. 'Which
agents exist' as a plain context-scoped read.
Every registered agent id — the extent of `(agent ?a)` in `CxRegistry`. 'Which agents exist' as a plain context-scoped read.
The admin-only registry context. The one context governed agents may not write.
The admin-only registry context. The one context governed agents may not write.
(set-trust! kb principal agent-id new-value)OVERWRITE agent-id's trust with new-value, as the admin principal (D3: trust
is a mutable number). trustLevel is functional, so the update retracts the old
value and asserts the new rather than accumulating two. Refused for a non-admin
principal. Returns the new handle.
OVERWRITE `agent-id`'s trust with `new-value`, as the admin `principal` (D3: trust is a mutable number). `trustLevel` is functional, so the update retracts the old value and asserts the new rather than accumulating two. Refused for a non-admin principal. Returns the new handle.
(trust-of kb agent-id)The stored trust number for agent-id, or nil — a plain context-scoped read of
CxRegistry, ready for adjudication to weigh.
The stored trust number for `agent-id`, or nil — a plain context-scoped read of `CxRegistry`, ready for adjudication to weigh.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |