iranti 0.2.51 → 0.3.2

package/dist/src/sdk/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetStaffEventEmitter = exports.getStaffEventEmitter = exports.setStaffEventEmitter = exports.buildStaffEvent = exports.NoopEventEmitter = exports.Iranti = void 0;
+exports.resetStaffEventEmitter = exports.getStaffEventEmitter = exports.setStaffEventEmitter = exports.buildStaffEvent = exports.NoopEventEmitter = exports.Iranti = exports.ProtocolViolationError = void 0;
 require("dotenv/config");
 const client_1 = require("../library/client");
 const staffEventEmitter_1 = require("../lib/staffEventEmitter");
@@ -19,8 +19,37 @@ const relationships_1 = require("../library/relationships");
 const agent_registry_1 = require("../library/agent-registry");
 const entity_resolution_1 = require("../library/entity-resolution");
 const autoRemember_1 = require("../lib/autoRemember");
+const issueFacts_1 = require("../lib/issueFacts");
 const mock_1 = require("../lib/providers/mock");
+const protocolEnforcement_1 = require("../lib/protocolEnforcement");
+Object.defineProperty(exports, "ProtocolViolationError", { enumerable: true, get: function () { return protocolEnforcement_1.ProtocolViolationError; } });
 const client_2 = require("../generated/prisma/client");
+const sessionLedger_1 = require("../lib/sessionLedger");
+function normalizeDbApplicationToken(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const normalized = trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9:_-]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return normalized || undefined;
+}
+function deriveDbApplicationName(config) {
+    const explicit = normalizeDbApplicationToken(config.dbApplicationName);
+    if (explicit) {
+        return explicit.slice(0, 63);
+    }
+    const source = normalizeDbApplicationToken(config.sessionLedgerSource);
+    const host = normalizeDbApplicationToken(config.sessionLedgerHost);
+    const agentId = normalizeDbApplicationToken(config.sessionLedgerAgentId);
+    const parts = ['iranti', source, host ?? agentId].filter((part) => Boolean(part));
+    if (parts.length === 1) {
+        return undefined;
+    }
+    return parts.join(':').slice(0, 63);
+}
 // ─── Entity Parsing ──────────────────────────────────────────────────────────
 function parseEntity(entity) {
     if (!entity || typeof entity !== 'string') {
@@ -143,11 +172,22 @@ function mapArchiveResult(result) {
 class Iranti {
     constructor(config = {}) {
         this.config = config;
+        this.protocolTracker = new protocolEnforcement_1.AgentProtocolTracker();
+        this.sessionLedgerContext = {
+            source: config.sessionLedgerSource?.trim() || undefined,
+            host: typeof config.sessionLedgerHost === 'string'
+                ? (config.sessionLedgerHost.trim() || null)
+                : (config.sessionLedgerHost ?? null),
+            agentId: config.sessionLedgerAgentId?.trim() || undefined,
+        };
         const connectionString = config.connectionString ?? process.env.DATABASE_URL;
         if (!connectionString) {
             throw new Error('connectionString is required. Provide it in config or set DATABASE_URL environment variable.');
         }
-        (0, client_1.initDb)(connectionString);
+        (0, client_1.initDb)(connectionString, {
+            applicationName: deriveDbApplicationName(config),
+            max: config.dbPoolMax,
+        });
         if (config.llmProvider) {
             process.env.LLM_PROVIDER = config.llmProvider;
         }
@@ -159,6 +199,107 @@ class Iranti {
             (0, staffEventRegistry_1.setStaffEventEmitter)(config.staffEventEmitter);
         }
     }
+    protocolMode() {
+        return this.config.protocolEnforcement ?? 'off';
+    }
+    protocolAgentId() {
+        return this.sessionLedgerContext.agentId?.trim() || undefined;
+    }
+    checkProtocol(operation, requirements) {
+        const mode = this.protocolMode();
+        if (mode === 'off')
+            return;
+        const agentId = this.protocolAgentId();
+        if (!agentId)
+            return;
+        const violation = this.protocolTracker.check(agentId, operation, requirements);
+        if (!violation)
+            return;
+        if (mode === 'warn') {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId,
+                source: 'sdk',
+                reason: violation.code,
+                level: 'audit',
+                metadata: {
+                    operation,
+                    protocolViolation: violation,
+                },
+            });
+            return;
+        }
+        throw new protocolEnforcement_1.ProtocolViolationError(violation);
+    }
+    syncMemoryUseCompliance(agentId, compliance) {
+        const ignoredMemoryIssue = compliance?.issues.find((issue) => issue.code === 'ignored_injected_memory');
+        if (ignoredMemoryIssue?.severity === 'error') {
+            this.protocolTracker.markMemoryUseAcknowledgementRequired(agentId);
+            return;
+        }
+        this.protocolTracker.clearMemoryUseAcknowledgementRequired(agentId);
+    }
+    consumeDiscoveryBudget(operation) {
+        if (this.protocolMode() === 'off')
+            return;
+        const agentId = this.protocolAgentId();
+        if (!agentId)
+            return;
+        if (['query', 'history', 'queryAll', 'search', 'related', 'related_deep', 'who_knows'].includes(operation)) {
+            this.protocolTracker.notifyDiscoveryConsumed(agentId);
+        }
+    }
+    setSessionLedgerContext(context) {
+        if ('source' in context) {
+            this.sessionLedgerContext.source = typeof context.source === 'string'
+                ? (context.source.trim() || undefined)
+                : undefined;
+        }
+        if ('host' in context) {
+            this.sessionLedgerContext.host = typeof context.host === 'string'
+                ? (context.host.trim() || null)
+                : (context.host ?? null);
+        }
+        if ('agentId' in context) {
+            this.sessionLedgerContext.agentId = typeof context.agentId === 'string'
+                ? (context.agentId.trim() || undefined)
+                : undefined;
+        }
+    }
+    buildSessionLedgerContext() {
+        if (!this.sessionLedgerContext.source && !this.sessionLedgerContext.host && !this.sessionLedgerContext.agentId) {
+            return undefined;
+        }
+        return {
+            source: this.sessionLedgerContext.source,
+            host: this.sessionLedgerContext.host ?? null,
+            agentId: this.sessionLedgerContext.agentId,
+        };
+    }
+    emitLedgerEvent(event) {
+        const context = this.buildSessionLedgerContext();
+        const metadata = event.metadata && typeof event.metadata === 'object'
+            ? { ...event.metadata }
+            : {};
+        if (context?.host) {
+            metadata.host = context.host;
+        }
+        (0, staffEventRegistry_1.getStaffEventEmitter)().emit({
+            ...event,
+            agentId: context?.agentId && (!event.agentId || event.agentId === 'sdk')
+                ? context.agentId
+                : event.agentId,
+            source: context?.source ?? event.source,
+            metadata,
+        });
+    }
+    async noteRediscoveryEvidence() {
+        const agentId = this.protocolAgentId();
+        if (!agentId)
+            return;
+        await (0, registry_1.getAttendant)(agentId).noteDiscoveryOccurred();
+    }
     // ── Write ───────────────────────────────────────────────────────────────
     async write(input) {
         if (input.confidence < 0 || input.confidence > 100) {
@@ -186,7 +327,10 @@ class Iranti {
             validFrom: input.validFrom,
             validUntil: input.validUntil ?? undefined,
             requestId: input.requestId,
+            properties: input.properties,
         });
+        await (0, registry_1.getAttendant)(input.agent).notifyWriteOccurred();
+        this.protocolTracker.clearMemoryUseAcknowledgementRequired(input.agent);
         return {
             action: result.action,
             key: input.key,
@@ -195,6 +339,9 @@ class Iranti {
             inputEntity: input.entity,
         };
     }
+    async writeIssue(input) {
+        return this.write((0, issueFacts_1.buildIssueFactWrite)(input));
+    }
     // ── Ingest ──────────────────────────────────────────────────────────────
     async ingest(input) {
         const { entityType, entityId } = parseEntity(input.entity);
@@ -206,6 +353,8 @@ class Iranti {
             confidence: input.confidence,
             createdBy: input.agent,
         });
+        await (0, registry_1.getAttendant)(input.agent).notifyWriteOccurred();
+        this.protocolTracker.clearMemoryUseAcknowledgementRequired(input.agent);
         return {
             extractedCandidates: result.extractedCandidates,
             written: result.written,
@@ -222,11 +371,16 @@ class Iranti {
     }
     // ── Handshake ───────────────────────────────────────────────────────────
     async handshake(input) {
-        const attendant = (0, registry_1.getAttendant)(resolveAgentId(input, 'handshake'));
-        return attendant.handshake({
+        const agentId = resolveAgentId(input, 'handshake');
+        const attendant = (0, registry_1.getAttendant)(agentId);
+        const result = await attendant.handshake({
             task: input.task,
             recentMessages: input.recentMessages,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
+        this.protocolTracker.markHandshake(agentId);
+        this.syncMemoryUseCompliance(agentId, result.compliance);
+        return result;
     }
     // ── Reconvene ───────────────────────────────────────────────────────────
     async reconvene(agentId, input) {
@@ -234,34 +388,42 @@ class Iranti {
         return attendant.reconvene({
             task: input.task,
             recentMessages: input.recentMessages,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async checkpoint(input) {
-        const attendant = (0, registry_1.getAttendant)(resolveAgentId(input, 'checkpoint'));
-        return attendant.checkpoint({
+        const agentId = resolveAgentId(input, 'checkpoint');
+        const attendant = (0, registry_1.getAttendant)(agentId);
+        const result = await attendant.checkpoint({
             task: input.task,
             recentMessages: input.recentMessages,
             checkpoint: input.checkpoint,
             sessionId: input.sessionId,
             heartbeatAt: input.heartbeatAt,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
+        this.protocolTracker.clearMemoryUseAcknowledgementRequired(agentId);
+        return result;
     }
     async resumeSession(input) {
         const attendant = (0, registry_1.getAttendant)(resolveAgentId(input, 'resumeSession'));
         return attendant.resumeSession({
             sessionId: input.sessionId,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async completeSession(input) {
         const attendant = (0, registry_1.getAttendant)(resolveAgentId(input, 'completeSession'));
         return attendant.completeSession({
             sessionId: input.sessionId,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async abandonSession(input) {
         const attendant = (0, registry_1.getAttendant)(resolveAgentId(input, 'abandonSession'));
         return attendant.abandonSession({
             sessionId: input.sessionId,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async inspectSession(input) {
@@ -269,6 +431,7 @@ class Iranti {
         return attendant.inspectSession({
             task: input.task,
             recentMessages: input.recentMessages,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async listSessions(input = {}) {
@@ -279,7 +442,7 @@ class Iranti {
             const checkpoint = raw?.sessionCheckpoint ?? null;
             if (!checkpoint)
                 return null;
-            return (0, AttendantInstance_1.summarizeSessionState)(entry.entityId, checkpoint, typeof raw?.briefGeneratedAt === 'string' ? raw.briefGeneratedAt : undefined);
+            return (0, AttendantInstance_1.summarizeSessionState)(entry.entityId, checkpoint, typeof raw?.briefGeneratedAt === 'string' ? raw.briefGeneratedAt : undefined, raw?.compliance ?? null);
         })
             .filter((entry) => Boolean(entry));
         if (input.operatorState) {
@@ -294,88 +457,203 @@ class Iranti {
         }
         return sessions;
     }
+    async listSessionLedger(input = {}) {
+        return (0, sessionLedger_1.querySessionLedger)(input);
+    }
     getAttendant(agentId) {
         return (0, registry_1.getAttendant)(agentId);
     }
     // ── Query ───────────────────────────────────────────────────────────────
     async query(entity, key, options = {}) {
+        this.checkProtocol('query', { handshake: true, attend: true });
         const resolved = await resolveQueryEntity(entity);
         const personalRecallCandidates = (isPersonalEntityString(entity) && (0, autoRemember_1.isPersonalMemoryKey)(key)
             ? (0, autoRemember_1.getPersonalRecallEntities)(entity)
             : [])
             .filter((candidate) => candidate !== resolved.canonicalEntity);
-        if (options.asOf) {
-            const current = await (0, queries_1.findEntry)({ entityType: resolved.entityType, entityId: resolved.entityId, key });
-            const currentMatches = current && !current.isProtected && current.validFrom <= options.asOf;
-            if (currentMatches) {
-                await (0, queries_1.recordKnowledgeEntryAccess)([current.id]);
-                return {
-                    found: true,
-                    value: current.valueRaw,
-                    summary: current.valueSummary,
-                    confidence: current.confidence,
-                    source: current.source,
-                    validFrom: current.validFrom,
-                    validUntil: current.validUntil,
-                    contested: false,
-                    fromArchive: false,
-                    archivedReason: null,
-                    resolutionState: null,
-                    resolutionOutcome: null,
-                    resolvedEntity: resolved.canonicalEntity,
-                    inputEntity: entity,
-                };
-            }
-            const historical = await (0, queries_1.findArchiveAsOf)({ entityType: resolved.entityType, entityId: resolved.entityId, key }, options.asOf, {
-                includeExpired: options.includeExpired,
-                includeContested: options.includeContested,
-            });
-            if (historical) {
-                return {
-                    found: true,
-                    ...mapArchiveResult(historical),
-                    resolvedEntity: resolved.canonicalEntity,
-                    inputEntity: entity,
-                };
+        try {
+            if (options.asOf) {
+                const current = await (0, queries_1.findEntry)({ entityType: resolved.entityType, entityId: resolved.entityId, key });
+                const currentMatches = current && !current.isProtected && current.validFrom <= options.asOf;
+                if (currentMatches) {
+                    this.consumeDiscoveryBudget('query');
+                    await (0, queries_1.recordKnowledgeEntryAccess)([current.id]);
+                    this.emitLedgerEvent({
+                        staffComponent: 'Attendant',
+                        actionType: 'query_executed',
+                        agentId: 'sdk',
+                        source: 'sdk',
+                        entityType: resolved.entityType,
+                        entityId: resolved.entityId,
+                        key,
+                        reason: 'query_exact_current',
+                        level: 'audit',
+                        metadata: {
+                            found: true,
+                            fromArchive: false,
+                            asOf: options.asOf.toISOString(),
+                        },
+                    });
+                    await this.noteRediscoveryEvidence();
+                    return {
+                        found: true,
+                        value: current.valueRaw,
+                        summary: current.valueSummary,
+                        confidence: current.confidence,
+                        source: current.source,
+                        validFrom: current.validFrom,
+                        validUntil: current.validUntil,
+                        contested: false,
+                        fromArchive: false,
+                        archivedReason: null,
+                        resolutionState: null,
+                        resolutionOutcome: null,
+                        resolvedEntity: resolved.canonicalEntity,
+                        inputEntity: entity,
+                    };
+                }
+                const historical = await (0, queries_1.findArchiveAsOf)({ entityType: resolved.entityType, entityId: resolved.entityId, key }, options.asOf, {
+                    includeExpired: options.includeExpired,
+                    includeContested: options.includeContested,
+                });
+                if (historical) {
+                    this.consumeDiscoveryBudget('query');
+                    this.emitLedgerEvent({
+                        staffComponent: 'Attendant',
+                        actionType: 'query_executed',
+                        agentId: 'sdk',
+                        source: 'sdk',
+                        entityType: resolved.entityType,
+                        entityId: resolved.entityId,
+                        key,
+                        reason: 'query_historical_match',
+                        level: 'audit',
+                        metadata: {
+                            found: true,
+                            fromArchive: true,
+                            asOf: options.asOf.toISOString(),
+                        },
+                    });
+                    await this.noteRediscoveryEvidence();
+                    return {
+                        found: true,
+                        ...mapArchiveResult(historical),
+                        resolvedEntity: resolved.canonicalEntity,
+                        inputEntity: entity,
+                    };
+                }
+                this.emitLedgerEvent({
+                    staffComponent: 'Attendant',
+                    actionType: 'query_executed',
+                    agentId: 'sdk',
+                    source: 'sdk',
+                    entityType: resolved.entityType,
+                    entityId: resolved.entityId,
+                    key,
+                    reason: 'query_historical_miss',
+                    level: 'audit',
+                    metadata: {
+                        found: false,
+                        fromArchive: true,
+                        asOf: options.asOf.toISOString(),
+                    },
+                });
+                await this.noteRediscoveryEvidence();
+                return { found: false, resolvedEntity: resolved.canonicalEntity, inputEntity: entity };
             }
-            return { found: false, resolvedEntity: resolved.canonicalEntity, inputEntity: entity };
-        }
-        const primaryEntry = await (0, queries_1.findEntry)({ entityType: resolved.entityType, entityId: resolved.entityId, key });
-        let entry = primaryEntry;
-        let resolvedEntity = resolved.canonicalEntity;
-        if ((!entry || entry.isProtected) && personalRecallCandidates.length > 0) {
-            for (const candidate of personalRecallCandidates) {
-                const fallback = await resolveQueryEntity(candidate);
-                const fallbackEntry = await (0, queries_1.findEntry)({ entityType: fallback.entityType, entityId: fallback.entityId, key });
-                if (fallbackEntry && !fallbackEntry.isProtected) {
-                    entry = fallbackEntry;
-                    resolvedEntity = fallback.canonicalEntity;
-                    break;
+            const primaryEntry = await (0, queries_1.findEntry)({ entityType: resolved.entityType, entityId: resolved.entityId, key });
+            let entry = primaryEntry;
+            const resolvedEntity = resolved.canonicalEntity;
+            let usedFallback = false;
+            if ((!entry || entry.isProtected) && personalRecallCandidates.length > 0) {
+                for (const candidate of personalRecallCandidates) {
+                    const fallback = await resolveQueryEntity(candidate);
+                    const fallbackEntry = await (0, queries_1.findEntry)({ entityType: fallback.entityType, entityId: fallback.entityId, key });
+                    if (fallbackEntry && !fallbackEntry.isProtected) {
+                        entry = fallbackEntry;
+                        usedFallback = true;
+                        break;
+                    }
                 }
             }
+            if (!entry || entry.isProtected) {
+                this.emitLedgerEvent({
+                    staffComponent: 'Attendant',
+                    actionType: 'query_executed',
+                    agentId: 'sdk',
+                    source: 'sdk',
+                    entityType: resolved.entityType,
+                    entityId: resolved.entityId,
+                    key,
+                    reason: personalRecallCandidates.length > 0 ? 'query_personal_fallback_miss' : 'query_exact_miss',
+                    level: 'audit',
+                    metadata: {
+                        found: false,
+                        resolvedEntity,
+                        inputEntity: entity,
+                    },
+                });
+                await this.noteRediscoveryEvidence();
+                return { found: false, resolvedEntity, inputEntity: entity };
+            }
+            await (0, queries_1.recordKnowledgeEntryAccess)([entry.id]);
+            this.consumeDiscoveryBudget('query');
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'query_executed',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType: entry.entityType,
+                entityId: entry.entityId,
+                key,
+                reason: usedFallback ? 'query_personal_fallback_match' : 'query_exact_match',
+                level: 'audit',
+                metadata: {
+                    found: true,
+                    resolvedEntity,
+                    inputEntity: entity,
+                },
+            });
+            await this.noteRediscoveryEvidence();
+            return {
+                found: true,
+                value: entry.valueRaw,
+                summary: entry.valueSummary,
+                confidence: entry.confidence,
+                source: entry.source,
+                validFrom: entry.validFrom,
+                validUntil: entry.validUntil,
+                contested: false,
+                fromArchive: false,
+                archivedReason: null,
+                resolutionState: null,
+                resolutionOutcome: null,
+                resolvedEntity,
+                inputEntity: entity,
+            };
         }
-        if (!entry || entry.isProtected) {
-            return { found: false, resolvedEntity, inputEntity: entity };
+        catch (error) {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType: resolved.entityType,
+                entityId: resolved.entityId,
+                key,
+                reason: 'query_failed',
+                level: 'audit',
+                metadata: {
+                    operation: 'query',
+                    inputEntity: entity,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
         }
-        await (0, queries_1.recordKnowledgeEntryAccess)([entry.id]);
-        return {
-            found: true,
-            value: entry.valueRaw,
-            summary: entry.valueSummary,
-            confidence: entry.confidence,
-            source: entry.source,
-            validFrom: entry.validFrom,
-            validUntil: entry.validUntil,
-            contested: false,
-            fromArchive: false,
-            archivedReason: null,
-            resolutionState: null,
-            resolutionOutcome: null,
-            resolvedEntity,
-            inputEntity: entity,
-        };
     }
     async history(entity, key, options = {}) {
+        this.checkProtocol('history', { handshake: true, attend: true });
         const resolved = await resolveQueryEntity(entity);
         const [archiveRows, current] = await Promise.all([
             (0, queries_1.findArchiveHistory)({ entityType: resolved.entityType, entityId: resolved.entityId, key }, {
@@ -412,14 +690,18 @@ class Iranti {
                 resolutionOutcome: null,
             });
         }
+        this.consumeDiscoveryBudget('history');
         return history.sort((a, b) => a.validFrom.getTime() - b.validFrom.getTime());
     }
     // ── Query All ───────────────────────────────────────────────────────────
     async queryAll(entity) {
+        this.checkProtocol('queryAll', { handshake: true, attend: true });
         const resolved = await resolveQueryEntity(entity);
         const entries = await (0, queries_1.findEntriesByEntity)(resolved.entityType, resolved.entityId);
         const visibleEntries = entries.filter((e) => !e.isProtected);
         await (0, queries_1.recordKnowledgeEntryAccess)(visibleEntries.map((entry) => entry.id));
+        this.consumeDiscoveryBudget('queryAll');
+        await this.noteRediscoveryEvidence();
         return visibleEntries
             .map((e) => ({
             key: e.key,
@@ -431,31 +713,69 @@ class Iranti {
     }
     // ── Maintenance ─────────────────────────────────────────────────────────
     async search(input) {
+        this.checkProtocol('search', { handshake: true, attend: true });
         if (!input.query || typeof input.query !== 'string' || input.query.trim().length === 0) {
             throw new Error('query is required for search().');
         }
-        const rows = await (0, queries_1.searchEntriesHybrid)({
-            query: input.query.trim(),
-            limit: input.limit,
-            entityType: input.entityType,
-            entityId: input.entityId,
-            lexicalWeight: input.lexicalWeight,
-            vectorWeight: input.vectorWeight,
-            minScore: input.minScore,
-        });
-        return rows.map((row) => ({
-            id: row.id,
-            entity: `${row.entityType}/${row.entityId}`,
-            key: row.key,
-            value: row.valueRaw,
-            summary: row.valueSummary,
-            confidence: row.confidence,
-            source: row.source,
-            validUntil: row.validUntil,
-            lexicalScore: row.lexicalScore,
-            vectorScore: row.vectorScore,
-            score: row.score,
-        }));
+        try {
+            const rows = await (0, queries_1.searchEntriesHybrid)({
+                query: input.query.trim(),
+                limit: input.limit,
+                entityType: input.entityType,
+                entityId: input.entityId,
+                lexicalWeight: input.lexicalWeight,
+                vectorWeight: input.vectorWeight,
+                minScore: input.minScore,
+            });
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'search_executed',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType: input.entityType,
+                entityId: input.entityId,
+                reason: 'hybrid_search',
+                level: 'audit',
+                metadata: {
+                    queryPreview: input.query.trim().slice(0, 120),
+                    resultCount: rows.length,
+                    minScore: input.minScore ?? null,
+                },
+            });
+            this.consumeDiscoveryBudget('search');
+            await this.noteRediscoveryEvidence();
+            return rows.map((row) => ({
+                id: row.id,
+                entity: `${row.entityType}/${row.entityId}`,
+                key: row.key,
+                value: row.valueRaw,
+                summary: row.valueSummary,
+                confidence: row.confidence,
+                source: row.source,
+                validUntil: row.validUntil,
+                lexicalScore: row.lexicalScore,
+                vectorScore: row.vectorScore,
+                score: row.score,
+            }));
+        }
+        catch (error) {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType: input.entityType,
+                entityId: input.entityId,
+                reason: 'search_failed',
+                level: 'audit',
+                metadata: {
+                    operation: 'search',
+                    queryPreview: input.query.trim().slice(0, 120),
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
     }
     async runMaintenance() {
         return (0, archivist_1.runArchivist)();
@@ -473,14 +793,90 @@ class Iranti {
             createdBy: options.createdBy,
             properties: options.properties,
         });
+        await (0, registry_1.getAttendant)(options.createdBy).notifyWriteOccurred();
+        this.protocolTracker.clearMemoryUseAcknowledgementRequired(options.createdBy);
     }
     async getRelated(entity) {
+        this.checkProtocol('related', { handshake: true, attend: true });
         const { entityType, entityId } = parseEntity(entity);
-        return (0, relationships_1.getRelated)(entityType, entityId);
+        try {
+            const result = await (0, relationships_1.getRelated)(entityType, entityId);
+            this.consumeDiscoveryBudget('related');
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'related_executed',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'relationship_lookup',
+                level: 'audit',
+                metadata: {
+                    resultCount: result.length,
+                },
+            });
+            await this.noteRediscoveryEvidence();
+            return result;
+        }
+        catch (error) {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'related_failed',
+                level: 'audit',
+                metadata: {
+                    operation: 'related',
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
     }
     async getRelatedDeep(entity, depth = 2) {
+        this.checkProtocol('related_deep', { handshake: true, attend: true });
         const { entityType, entityId } = parseEntity(entity);
-        return (0, relationships_1.getRelatedDeep)(entityType, entityId, depth);
+        try {
+            const result = await (0, relationships_1.getRelatedDeep)(entityType, entityId, depth);
+            this.consumeDiscoveryBudget('related_deep');
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'related_deep_executed',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'relationship_lookup_deep',
+                level: 'audit',
+                metadata: {
+                    resultCount: result.length,
+                    depth,
+                },
+            });
+            await this.noteRediscoveryEvidence();
+            return result;
+        }
+        catch (error) {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'related_deep_failed',
+                level: 'audit',
+                metadata: {
+                    operation: 'related_deep',
+                    depth,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
     }
     // ── Agent Registry ──────────────────────────────────────────────────────
     async registerAgent(profile) {
@@ -490,8 +886,44 @@ class Iranti {
         return (0, agent_registry_1.getAgent)(agentId);
     }
     async whoKnows(entity) {
+        this.checkProtocol('who_knows', { handshake: true, attend: true });
         const { entityType, entityId } = parseEntity(entity);
-        return (0, agent_registry_1.whoKnows)(entityType, entityId);
+        try {
+            const result = await (0, agent_registry_1.whoKnows)(entityType, entityId);
+            this.consumeDiscoveryBudget('who_knows');
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'whoknows_executed',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'agent_contribution_lookup',
+                level: 'audit',
+                metadata: {
+                    resultCount: result.length,
+                },
+            });
+            await this.noteRediscoveryEvidence();
+            return result;
+        }
+        catch (error) {
+            this.emitLedgerEvent({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: 'sdk',
+                source: 'sdk',
+                entityType,
+                entityId,
+                reason: 'whoknows_failed',
+                level: 'audit',
+                metadata: {
+                    operation: 'whoknows',
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
     }
     async listAgents() {
         return (0, agent_registry_1.listAgents)();
@@ -502,6 +934,7 @@ class Iranti {
     // ── Context Window Observation ────────────────────────────────────────────
     async observe(input) {
         const agentId = resolveAgentId(input, 'observe');
+        this.checkProtocol('observe', { handshake: true });
         if (input.entityHints !== undefined) {
             if (!Array.isArray(input.entityHints)) {
                 throw new Error('entityHints must be an array of "entityType/entityId" strings.');
@@ -518,10 +951,14 @@ class Iranti {
             currentContext: input.currentContext,
             maxFacts: input.maxFacts,
             entityHints: input.entityHints,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
     }
     async attend(input) {
         const agentId = resolveAgentId(input, 'attend');
+        if (input.phase === 'pre-response') {
+            this.checkProtocol('attend', { postResponse: true });
+        }
         if (input.entityHints !== undefined) {
             if (!Array.isArray(input.entityHints)) {
                 throw new Error('entityHints must be an array of "entityType/entityId" strings.');
@@ -534,13 +971,24 @@ class Iranti {
             }
         }
         const attendant = (0, registry_1.getAttendant)(agentId);
-        return attendant.attend({
+        const result = await attendant.attend({
             currentContext: input.currentContext,
             maxFacts: input.maxFacts,
             entityHints: input.entityHints,
             latestMessage: input.latestMessage,
             forceInject: input.forceInject,
+            suppressEvents: input.suppressEvents,
+            phase: input.phase,
+            ledgerContext: this.buildSessionLedgerContext(),
         });
+        if (result.bootstrap?.handshakePerformed) {
+            this.protocolTracker.markHandshake(agentId);
+        }
+        this.protocolTracker.markAttend(agentId, input.phase);
+        if (input.phase === 'post-response') {
+            this.syncMemoryUseCompliance(agentId, result.compliance);
+        }
+        return result;
     }
     // ── Mock Configuration (dev/test only) ──────────────────────────────────
     configureMock(config) {