@agenticprimitives/identity-directory 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @agenticprimitives/identity-directory
+
+An **evidence-backed read model** over canonical agents and their facets — the
+read side of the identity stack ([ADR-0015](../../docs/architecture/decisions/0015-identity-directory-is-an-evidence-backed-read-model.md);
+[spec 223](../../specs/223-identity-directory.md)).
+
+It answers *"which agent(s) does this name / credential / OIDC subject resolve to,
+and on what evidence?"* — keyed on `CanonicalAgentId` (CAIP-10), with provenance +
+assurance on every association. It is **not an authority**: it accelerates
+discovery; the consumer re-reads on-chain for custody decisions.
+
+## Ports + adapters
+
+The core declares the ports; the implementations live in
+[`@agenticprimitives/identity-directory-adapters`](../identity-directory-adapters):
+
+```
+NamingPort      forward/reverse name ↔ agent (wraps agent-naming)
+OnChainReadPort resolveAgent / credentialsOf — readContract only, NEVER getLogs
+IndexerPort     agentsByCredential / agentsByOidcSubject — the "indexed registry" home
+```
+
+## Usage
+
+```ts
+import { createDirectory } from '@agenticprimitives/identity-directory';
+import { makeAdapters } from '@agenticprimitives/identity-directory-adapters'; // (separate pkg)
+
+const dir = createDirectory(makeAdapters({ /* viem client, naming, indexer */ }));
+const r = await dir.resolveByCredential(principal); // 0 | 1 | many agents, each with evidence
+```
+
+## Doctrine (load-bearing)
+
+- **No fallback** ([ADR-0013](../../docs/architecture/decisions/0013-no-silent-fallbacks.md)):
+  one mechanism per query; a `null`/empty port result is terminal.
+- **No `eth_getLogs`** ([ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)):
+  indexed reads go through `IndexerPort`.
+- **Indexer proposes, on-chain confirms:** `resolveByCredential` /
+  `resolveByOidcSubject` upgrade to `onchain-confirmed` only when the credential is
+  in the agent's *current* on-chain set — a revoked credential is dropped.
+- **Not an authority** ([ADR-0015](../../docs/architecture/decisions/0015-identity-directory-is-an-evidence-backed-read-model.md)):
+  resolution output never grants custody or value.
+
+## Convergence
+
+`Resolution.agents.length` is the convergence cardinality the broker (spec 224)
+branches on: **0** → bootstrap, **1** → the common case, **many** → disambiguate.

package/dist/directory.d.ts

@@ -0,0 +1,5 @@
+import type { Assurance } from '@agenticprimitives/types';
+import { type DirectoryPorts, type DirectoryOpts, type IdentityDirectory } from './types';
+export declare function createDirectory(ports: DirectoryPorts, opts?: DirectoryOpts): IdentityDirectory;
+export type { Assurance };
+//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAyC,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACjG,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAOvB,MAAM,SAAS,CAAC;AAMjB,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,GAAE,aAAkB,GAAG,iBAAiB,CA8FlG;AAGD,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/directory.js

@@ -0,0 +1,112 @@
+// createDirectory — composes the ports into the query API (spec 223 §6/§7).
+//
+// Discipline (load-bearing):
+//   - No fallback (ADR-0013): each query uses ONE mechanism; a null/empty result
+//     is terminal — never an escalation to a second port.
+//   - Authoritative-port designation (audit P2-4): for session-relevant queries
+//     (credential / oidc) the IndexerPort only PROPOSES candidates; the
+//     OnChainReadPort is authoritative — a candidate is only `onchain-confirmed`
+//     if the credential is in the agent's CURRENT on-chain set. A credential
+//     revoked on-chain (spec 221) is dropped, never riding a stale index edge
+//     (audit P1-3).
+//   - Not an authority (ADR-0015): the directory accelerates discovery; it never
+//     grants anything. The broker re-reads on-chain for custody decisions.
+import { buildEvent, nowIso } from '@agenticprimitives/audit';
+import { CLASS, PREDICATE } from '@agenticprimitives/ontology';
+import { maxAssurance, } from './types';
+function oidcPrincipal(iss, sub) {
+    return { kind: 'oidc', id: `${iss}#${sub}`, assurance: 'asserted' };
+}
+export function createDirectory(ports, opts = {}) {
+    const auditSink = opts.auditSink;
+    async function emit(action, subjectId, predicate, resultCount) {
+        if (!auditSink)
+            return;
+        try {
+            await auditSink.write(buildEvent({
+                action,
+                outcome: 'success',
+                actor: { type: 'system', id: 'identity-directory' },
+                subject: { type: CLASS.Agent, id: subjectId },
+                context: { predicate, resultCount },
+            }));
+        }
+        catch {
+            /* audit is fail-soft; never block a read on the sink */
+        }
+    }
+    /**
+     * For each candidate link, CONFIRM the principal is in the agent's current
+     * on-chain credential set. Confirmed → `onchain-confirmed` (with both the
+     * indexer evidence and the on-chain confirmation evidence). Unconfirmed
+     * (revoked / stale / never-real) → dropped.
+     */
+    async function confirmCandidates(links, principal) {
+        const out = [];
+        for (const link of links) {
+            // Authoritative membership CHECK (isCustodian/isTrustee), not enumeration.
+            if (!(await ports.onChain.confirmsCredential(link.agent, principal)))
+                continue; // not currently a custodian → drop
+            const evidence = [
+                {
+                    source: 'indexer',
+                    assurance: link.assurance,
+                    observedAt: link.observedAt ?? nowIso(),
+                    ref: link.ref,
+                    blockNumber: link.blockNumber,
+                },
+                {
+                    source: 'onchain',
+                    assurance: 'onchain-confirmed',
+                    observedAt: nowIso(),
+                    ref: `credentialsOf:${link.agent}`,
+                },
+            ];
+            out.push({ id: link.agent, evidence, assurance: maxAssurance(evidence.map((e) => e.assurance)) });
+        }
+        return out;
+    }
+    return {
+        async resolveByName(name) {
+            const id = await ports.naming.forward(name);
+            // null is THE answer (no such name) — never escalate to another port (ADR-0013).
+            if (!id) {
+                await emit('identity-directory.resolveByName', name, PREDICATE.resolvesTo, 0);
+                return { agents: [] };
+            }
+            const evidence = [
+                { source: 'naming', assurance: 'onchain-read', observedAt: nowIso(), ref: name },
+            ];
+            await emit('identity-directory.resolveByName', name, PREDICATE.resolvesTo, 1);
+            return { agents: [{ id, evidence, assurance: 'onchain-read' }] };
+        },
+        async resolveByCredential(principal) {
+            const links = await ports.indexer.agentsByCredential(principal);
+            const agents = await confirmCandidates(links, principal);
+            await emit('identity-directory.resolveByCredential', `${principal.kind}:${principal.id}`, PREDICATE.controls, agents.length);
+            return { agents };
+        },
+        async resolveByOidcSubject(iss, sub) {
+            const links = await ports.indexer.agentsByOidcSubject(iss, sub);
+            const agents = await confirmCandidates(links, oidcPrincipal(iss, sub));
+            await emit('identity-directory.resolveByOidcSubject', `${iss}#${sub}`, PREDICATE.controls, agents.length);
+            return { agents };
+        },
+        async agent(id) {
+            if (!(await ports.onChain.exists(id)))
+                return null;
+            // Composition (NOT fallback): existence + reverse name are different facets
+            // of the SAME agent, each from its declared port. (Credential enumeration is
+            // not an on-chain primitive — confirmation is per-credential via the membership
+            // check; a full credential list, if ever needed, is an indexer concern.)
+            const name = await ports.naming.reverse(id);
+            const evidence = [
+                { source: 'onchain', assurance: 'onchain-read', observedAt: nowIso(), ref: `exists:${id}` },
+            ];
+            if (name)
+                evidence.push({ source: 'naming', assurance: 'onchain-read', observedAt: nowIso(), ref: name });
+            return { id, facets: { name: name ?? undefined }, evidence };
+        },
+    };
+}
+//# sourceMappingURL=directory.js.map

package/dist/directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { EvidenceSource, Evidence, AgentWithEvidence, Resolution, AgentView, EvidenceLink, OnChainReadPort, NamingPort, IndexerPort, DirectoryPorts, DirectoryOpts, IdentityDirectory, } from './types';
+export { ASSURANCE_ORDER, compareAssurance, maxAssurance } from './types';
+export { createDirectory } from './directory';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,YAAY,EACV,cAAc,EACd,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// @agenticprimitives/identity-directory — evidence-backed read model (spec 223).
+//
+// Public surface: the domain model, the ports (implemented in
+// identity-directory-adapters), the assurance ordering, and createDirectory.
+//
+// See:
+//   - capability.manifest.json — boundary (types + audit + ontology only)
+//   - ../../specs/223-identity-directory.md — the contract
+//   - ../../docs/architecture/decisions/0015-identity-directory-is-an-evidence-backed-read-model.md
+export { ASSURANCE_ORDER, compareAssurance, maxAssurance } from './types';
+export { createDirectory } from './directory';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,8DAA8D;AAC9D,6EAA6E;AAC7E,EAAE;AACF,OAAO;AACP,0EAA0E;AAC1E,2DAA2D;AAC3D,oGAAoG;AAiBpG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+import type { CanonicalAgentId, Assurance, CredentialPrincipal } from '@agenticprimitives/types';
+export type { CanonicalAgentId, Assurance, CredentialPrincipal };
+/** Which source asserted an association. */
+export type EvidenceSource = 'naming' | 'onchain' | 'indexer';
+/**
+ * Provenance for an asserted association (spec 223 §4). `blockNumber` is present
+ * and load-bearing for `onchain-read` evidence so a consumer can enforce a
+ * max-staleness bound (audit P1-3) — a credential revoked on-chain must not ride
+ * a stale read.
+ */
+export interface Evidence {
+    source: EvidenceSource;
+    observedAt: string;
+    assurance: Assurance;
+    /** Opaque source reference (name, tx, index key, "credentialsOf:<id>", …). */
+    ref: string;
+    /** Required for `onchain-read`/`onchain-confirmed`; the block the read reflects. */
+    blockNumber?: bigint;
+}
+/** An agent in a Resolution, with its provenance + the effective assurance. */
+export interface AgentWithEvidence {
+    id: CanonicalAgentId;
+    evidence: Evidence[];
+    /** Highest assurance across `evidence`. */
+    assurance: Assurance;
+}
+/** The result of a resolution query. Convergence cardinality is `agents.length`. */
+export interface Resolution {
+    agents: AgentWithEvidence[];
+}
+/** A view of one agent + provenance (from `agent(id)`). */
+export interface AgentView {
+    id: CanonicalAgentId;
+    facets: {
+        name?: string;
+    };
+    evidence: Evidence[];
+}
+/**
+ * A candidate link from a (non-authoritative) IndexerPort. The directory
+ * CONFIRMS it against the authoritative on-chain read before treating it as
+ * `onchain-confirmed` (audit P2-4 / P1-3).
+ */
+export interface EvidenceLink {
+    agent: CanonicalAgentId;
+    assurance: Assurance;
+    ref: string;
+    observedAt?: string;
+    blockNumber?: bigint;
+}
+/**
+ * Authoritative on-chain reads. `readContract` only — NEVER `eth_getLogs`.
+ *
+ * Shaped around what the custody/account contracts actually expose: membership
+ * CHECKS (`isCustodian`/`isTrustee`), not credential enumeration. So confirmation
+ * is `confirmsCredential` (a check), not a `credentialsOf` (a list) — the on-chain
+ * surface has no "list this agent's credentials" getter.
+ */
+export interface OnChainReadPort {
+    /** Does this agent exist as a deployed account on this chain? */
+    exists(id: CanonicalAgentId): Promise<boolean>;
+    /** Authoritative: is `principal` CURRENTLY a control credential of `id`? */
+    confirmsCredential(id: CanonicalAgentId, principal: CredentialPrincipal): Promise<boolean>;
+}
+/** Wraps `agent-naming`. The adapter lifts `Address → CanonicalAgentId` by binding a chainId. */
+export interface NamingPort {
+    forward(name: string): Promise<CanonicalAgentId | null>;
+    reverse(id: CanonicalAgentId): Promise<string | null>;
+}
+/** The home for "indexed registry" reads (HCS-2 *indexed* → here, never a log walk). */
+export interface IndexerPort {
+    agentsByCredential(principal: CredentialPrincipal): Promise<EvidenceLink[]>;
+    agentsByOidcSubject(iss: string, sub: string): Promise<EvidenceLink[]>;
+}
+export interface DirectoryPorts {
+    naming: NamingPort;
+    onChain: OnChainReadPort;
+    indexer: IndexerPort;
+}
+import type { AuditSink } from '@agenticprimitives/audit';
+export interface DirectoryOpts {
+    /** Injectable clock (ms). Defaults to Date.now. */
+    now?: () => number;
+    /** Optional sink — a `identity-directory.resolve` event is emitted per query. */
+    auditSink?: AuditSink;
+}
+/** The directory query API (spec 223 §6). */
+export interface IdentityDirectory {
+    resolveByName(name: string): Promise<Resolution>;
+    /** Session-relevant: indexer proposes, on-chain CONFIRMS (audit P2-4/P1-3). */
+    resolveByCredential(principal: CredentialPrincipal): Promise<Resolution>;
+    resolveByOidcSubject(iss: string, sub: string): Promise<Resolution>;
+    agent(id: CanonicalAgentId): Promise<AgentView | null>;
+}
+/** Ordered low→high. Consumers (e.g. the broker session-issuance floor) compare on this. */
+export declare const ASSURANCE_ORDER: readonly Assurance[];
+/** Negative / 0 / positive like a comparator. */
+export declare function compareAssurance(a: Assurance, b: Assurance): number;
+/** The highest assurance across a non-empty list (defaults to 'unverified' if empty). */
+export declare function maxAssurance(values: Assurance[]): Assurance;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEjG,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,CAAC;AAEjE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,gBAAgB,CAAC;IACrB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,gBAAgB,CAAC;IACrB,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAED,iGAAiG;AACjG,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAED,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5E,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjD,+EAA+E;IAC/E,mBAAmB,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACzE,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpE,KAAK,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CACxD;AAID,4FAA4F;AAC5F,eAAO,MAAM,eAAe,EAAE,SAAS,SAAS,EAKtC,CAAC;AAEX,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAEnE;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAI3D"}

package/dist/types.js

@@ -0,0 +1,27 @@
+// Domain model + ports for the identity directory (spec 223).
+//
+// The directory is a READ MODEL keyed on CanonicalAgentId. Every association it
+// returns carries Evidence (provenance + assurance). It is NOT an authority
+// (ADR-0015), uses no eth_getLogs (ADR-0012), and never falls back between
+// mechanisms (ADR-0013).
+// ─── Assurance ordering ───────────────────────────────────────────────
+/** Ordered low→high. Consumers (e.g. the broker session-issuance floor) compare on this. */
+export const ASSURANCE_ORDER = [
+    'unverified',
+    'asserted',
+    'onchain-read',
+    'onchain-confirmed',
+];
+/** Negative / 0 / positive like a comparator. */
+export function compareAssurance(a, b) {
+    return ASSURANCE_ORDER.indexOf(a) - ASSURANCE_ORDER.indexOf(b);
+}
+/** The highest assurance across a non-empty list (defaults to 'unverified' if empty). */
+export function maxAssurance(values) {
+    let best = 'unverified';
+    for (const v of values)
+        if (compareAssurance(v, best) > 0)
+            best = v;
+    return best;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,2EAA2E;AAC3E,yBAAyB;AAsHzB,yEAAyE;AAEzE,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAyB;IACnD,YAAY;IACZ,UAAU;IACV,cAAc;IACd,mBAAmB;CACX,CAAC;AAEX,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAAC,CAAY,EAAE,CAAY;IACzD,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,IAAI,IAAI,GAAc,YAAY,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,gBAAgB,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC;YAAE,IAAI,GAAG,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agenticprimitives/identity-directory",
+  "version": "0.1.0-alpha.2",
+  "description": "Evidence-backed read model over canonical agents and their facets (ADR-0015 / spec 223). Declares the ports (NamingPort / OnChainReadPort / IndexerPort) + the query API with provenance + assurance. Not an authority; no eth_getLogs; no fallback. Adapters live in identity-directory-adapters.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/identity-directory"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/identity-directory",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@agenticprimitives/audit": "workspace:*",
+    "@agenticprimitives/ontology": "workspace:*",
+    "@agenticprimitives/types": "workspace:*"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "identity",
+    "directory",
+    "read-model",
+    "knowledge-graph",
+    "agentic"
+  ]
+}

package/spec.md

@@ -0,0 +1,16 @@
+# Spec — @agenticprimitives/identity-directory
+
+The authoritative spec is [`specs/223-identity-directory.md`](../../specs/223-identity-directory.md)
+(domain model, ports, query API + convergence, doctrine compliance, phased plan).
+
+Decision record: [ADR-0015 — identity-directory is an evidence-backed read model](../../docs/architecture/decisions/0015-identity-directory-is-an-evidence-backed-read-model.md).
+Conforms to the ontology in [spec 225](../../specs/225-ontology.md); keys on the
+CAIP-10 `CanonicalAgentId` of [ADR-0016](../../docs/architecture/decisions/0016-canonical-agent-id-is-the-sso-subject.md).
+
+This file is the per-package pointer required by `check:package-docs`; do not
+duplicate the spec here — edit spec 223.
+
+> Reconciliation note: spec 223 §5 sketched an `OidcPort`; OIDC *verification*
+> lives in `connect-auth` (ADR-0017), so the directory core ships three ports
+> (Naming / OnChainRead / Indexer) and `resolveByOidcSubject(iss, sub)` takes an
+> already-verified subject. The broker wires connect-auth → directory.