@canonmsg/backend-contracts 4.0.1 → 5.1.0

package/README.md

@@ -34,6 +34,8 @@ The JSON Schemas are also emitted as files for non-JavaScript consumers: `@canon
 
 **Behavior policy and contact requests.** The participation evaluator the stream service runs before dispatching a turn, and the contact-request serializer both sides validate against.
 
+**Server-side normalizers.** `readCanonicalPolicy` resolves a stored `inboundPolicy` / `groupJoinPolicy` field to the access triplet's three values, defaulting to `approval-required` rather than widening to `open`. `serializeSelfContext` is the agent-facing projection of a stored self-context. `readModerationStatus` is the single definition of an ejected account. All take plain document-shaped data — the package still performs no I/O.
+
 **Environments.** `CANON_ENVIRONMENT_CONTRACTS` binds `canon-dev-v1` and `canon-prod-v1` to their project and region; `getCanonEnvironmentContract` rejects anything else rather than defaulting.
 
 **Diff redaction.** Approval diffs carry pre-image context into a message every conversation member can read, so secret-shaped paths and tokens are suppressed before send — by the emitting host, and again defensively by the server.

package/dist/accessPolicy.d.ts

@@ -0,0 +1,9 @@
+/** The canonical access triplet's policy values (`inboundPolicy`, `groupJoinPolicy`). */
+export type CanonicalPolicy = 'open' | 'approval-required' | 'owner-only';
+/**
+ * Read a stored policy field, defaulting to the value Canon assigns on account
+ * creation. Anything unrecognized — missing, misspelled, or the retired
+ * `'private'` enum — reads as 'approval-required'. This must never widen to
+ * 'open'.
+ */
+export declare function readCanonicalPolicy(value: unknown): CanonicalPolicy;

package/dist/accessPolicy.js

@@ -0,0 +1,12 @@
+/**
+ * Read a stored policy field, defaulting to the value Canon assigns on account
+ * creation. Anything unrecognized — missing, misspelled, or the retired
+ * `'private'` enum — reads as 'approval-required'. This must never widen to
+ * 'open'.
+ */
+export function readCanonicalPolicy(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'owner-only') {
+        return value;
+    }
+    return 'approval-required';
+}

package/dist/agentBehaviorPolicy.d.ts

@@ -1,4 +1,11 @@
 export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
+/**
+ * The stored/parsed shape. This is the RETURN type of
+ * {@link parseAgentBehaviorSettings} and {@link normalizeStoredAgentBehaviorPolicy},
+ * so its optional fields deliberately stay `T | undefined` — widening them to
+ * `T | null` would be a breaking change for every reader of those results.
+ * Parameter positions take {@link AgentBehaviorSettingsInput} instead.
+ */
 export interface AgentBehaviorSettingsRecord {
     participationStyle?: ParticipationStyle;
     allowAgentToAgent?: boolean;
@@ -7,15 +14,30 @@ export interface AgentBehaviorSettingsRecord {
     maxConsecutiveAgentTurns?: number | null;
     instructions?: string | null;
 }
+/**
+ * The input shape accepted by {@link resolveAgentBehaviorPolicy}. Every field
+ * additionally accepts an explicit `null` (an editor clearing a value), which
+ * coalesces exactly like `undefined` — the field falls through to the next
+ * layer. {@link AgentBehaviorSettingsRecord} is assignable to this type.
+ */
+export interface AgentBehaviorSettingsInput {
+    participationStyle?: ParticipationStyle | null;
+    allowAgentToAgent?: boolean | null;
+    allowLongRunningCollaboration?: boolean | null;
+    requireMentionForGroupReplies?: boolean | null;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
+export interface ParticipationPolicy {
+    style: ParticipationStyle;
+    allowAgentToAgent: boolean;
+    allowHumanToAgent: boolean;
+    allowLongRunningCollaboration: boolean;
+    requireMentionForGroupReplies: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+}
 export interface ResolvedAgentBehaviorPolicyRecord {
-    participation: {
-        style: ParticipationStyle;
-        allowAgentToAgent: boolean;
-        allowHumanToAgent: boolean;
-        allowLongRunningCollaboration: boolean;
-        requireMentionForGroupReplies: boolean;
-        maxConsecutiveAgentTurns?: number | null;
-    };
+    participation: ParticipationPolicy;
     instructions: string[];
     source: {
         hasAgentDefault: boolean;
@@ -31,7 +53,13 @@ export interface ParticipationDecisionInput {
     consecutiveAgentTurns?: number;
     currentAgentStreakStartedByHuman?: boolean;
 }
+export interface ParticipationDecision {
+    allow: boolean;
+    reasonCode: string;
+    reason: string;
+}
 export interface ParticipationHistoryMessage {
+    id?: string;
     senderId: string;
     senderType: 'human' | 'ai_agent';
     metadata?: unknown;
@@ -47,13 +75,11 @@ export declare const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
 export declare function parseAgentBehaviorSettings(raw: unknown): AgentBehaviorSettingsRecord;
 export declare function normalizeStoredAgentBehaviorPolicy(raw: Record<string, unknown> | undefined): AgentBehaviorSettingsRecord | null;
 export declare function normalizeAgentBehaviorInstructions(value: string | null | undefined): string | null;
+export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
 export declare function resolveAgentBehaviorPolicy(params?: {
-    agentDefault?: AgentBehaviorSettingsRecord | null;
-    conversationOverride?: AgentBehaviorSettingsRecord | null;
+    agentDefault?: AgentBehaviorSettingsInput | null;
+    conversationOverride?: AgentBehaviorSettingsInput | null;
 }): ResolvedAgentBehaviorPolicyRecord;
 export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId?: string): ParticipationHistorySnapshot;
 export declare function appendParticipationHistoryMessage(snapshot: ParticipationHistorySnapshot, message: ParticipationHistoryMessage, limit?: number): ParticipationHistorySnapshot;
-export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicyRecord, input: ParticipationDecisionInput): {
-    allow: boolean;
-    reason: string;
-};
+export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicyRecord | null | undefined, input: ParticipationDecisionInput): ParticipationDecision;

package/dist/agentBehaviorPolicy.js

@@ -52,16 +52,9 @@ function resolveGroupMentionRequirement(input) {
         && typeof input.requireMentionForGroupReplies !== 'boolean') {
         throw new Error('requireMentionForGroupReplies must be a boolean');
     }
-    if (input.requireMentionForGroupAgentReplies !== undefined
-        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
-        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
-    }
     if (typeof input.requireMentionForGroupReplies === 'boolean') {
         return input.requireMentionForGroupReplies;
     }
-    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
-        return input.requireMentionForGroupAgentReplies;
-    }
     return undefined;
 }
 export function parseAgentBehaviorSettings(raw) {
@@ -104,9 +97,7 @@ export function normalizeStoredAgentBehaviorPolicy(raw) {
             : {}),
         ...(typeof raw.requireMentionForGroupReplies === 'boolean'
             ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
-            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
-                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
-                : {}),
+            : {}),
         ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
             ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
             : {}),
@@ -128,6 +119,9 @@ export function normalizeAgentBehaviorInstructions(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+export function getDefaultParticipationPolicy() {
+    return { ...DEFAULT_POLICY.participation };
+}
 export function resolveAgentBehaviorPolicy(params) {
     const agentDefault = params?.agentDefault ?? null;
     const conversationOverride = params?.conversationOverride ?? null;
@@ -204,37 +198,59 @@ export function appendParticipationHistoryMessage(snapshot, message, limit = PAR
     ].slice(0, limit));
 }
 export function evaluateParticipationPolicy(policy, input) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const participation = resolved.participation;
     const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
     if (input.conversationType === 'group'
-        && policy.participation.requireMentionForGroupReplies
+        && participation.requireMentionForGroupReplies
         && !input.mentionedAgent) {
         return {
             allow: false,
+            reasonCode: 'group_mention_required',
             reason: 'group replies require a direct mention',
         };
     }
     if (input.isOwner) {
-        return { allow: true, reason: 'owner messages pass through outside mention-required group turns' };
+        return {
+            allow: true,
+            reasonCode: 'owner_sender',
+            reason: 'owner messages pass through outside mention-required group turns',
+        };
     }
     if (input.senderType !== 'ai_agent') {
-        return { allow: true, reason: 'latest sender is human' };
+        return { allow: true, reasonCode: 'human_sender', reason: 'latest sender is human' };
     }
-    if (!policy.participation.allowAgentToAgent) {
-        return { allow: false, reason: 'agent-to-agent participation disabled by policy' };
+    if (!participation.allowAgentToAgent) {
+        return {
+            allow: false,
+            reasonCode: 'agent_to_agent_disabled',
+            reason: 'agent-to-agent participation is disabled by policy',
+        };
     }
-    if (!policy.participation.allowLongRunningCollaboration
+    if (!participation.allowLongRunningCollaboration
         && (consecutiveAgentTurns > 1
             || !currentAgentStreakStartedByHuman)) {
         return {
             allow: false,
+            reasonCode: 'human_reset_required',
             reason: 'a fresh human steer is required before continuing agent collaboration',
         };
     }
-    if (typeof policy.participation.maxConsecutiveAgentTurns === 'number'
-        && policy.participation.maxConsecutiveAgentTurns >= 0
-        && consecutiveAgentTurns > policy.participation.maxConsecutiveAgentTurns) {
-        return { allow: false, reason: 'maximum consecutive agent turns reached' };
+    if (typeof participation.maxConsecutiveAgentTurns === 'number'
+        && participation.maxConsecutiveAgentTurns >= 0
+        && consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        return {
+            allow: false,
+            reasonCode: 'agent_turn_limit_reached',
+            reason: 'maximum consecutive agent turns reached',
+        };
     }
-    return { allow: true, reason: 'agent-to-agent participation allowed by policy' };
+    return {
+        allow: true,
+        reasonCode: input.conversationType === 'group' ? 'group_agent_allowed' : 'direct_agent_allowed',
+        reason: participation.requireMentionForGroupReplies
+            ? 'policy allows this directly mentioned group reply'
+            : 'agent-to-agent participation allowed by policy',
+    };
 }

package/dist/agentSearch.d.ts

@@ -0,0 +1,17 @@
+/** The indexable fields a stored agent contributes to `searchPrefixes`. */
+export interface AgentSearchIndexFields {
+    displayName?: string | null;
+    description?: string | null;
+}
+/** The agent shape a directory filter reads. */
+export interface AgentSearchProfile {
+    displayName?: string | null;
+    agentConfig?: {
+        description?: string | null;
+    } | null;
+}
+/** Tolerant: non-string input normalises to ''. */
+export declare function normalizeAgentDirectoryQuery(value: unknown): string;
+export declare function getAgentDirectoryQueryTokens(query: string): string[];
+export declare function buildAgentSearchPrefixes(input: AgentSearchIndexFields): string[];
+export declare function matchesAgentSearchQuery(profile: AgentSearchProfile, query: string): boolean;

package/dist/agentSearch.js

@@ -0,0 +1,58 @@
+// The single agent-directory search implementation, shared by Cloud Functions
+// (which writes `users/{agentId}.searchPrefixes` and filters discovery reads)
+// and `@canonmsg/chat-domain` (which filters the same agents client-side in the
+// app and on web). The server index and the client filter must agree, so both
+// sides derive from these bodies rather than from hand-synced copies.
+//
+// Pure ECMAScript: no imports, no Node built-ins, no Firestore types — safe in
+// CJS, in the browser bundle, and on Hermes.
+const MAX_QUERY_LENGTH = 64;
+const MAX_TOKEN_PREFIX_LENGTH = 32;
+const MAX_SEARCH_PREFIXES = 256;
+const TOKEN_PATTERN = /[\p{L}\p{N}]+/gu;
+function tokenizeAgentSearchValue(value) {
+    const normalized = value
+        .normalize('NFKD')
+        .toLowerCase()
+        .trim();
+    return normalized.match(TOKEN_PATTERN) ?? [];
+}
+/** Tolerant: non-string input normalises to ''. */
+export function normalizeAgentDirectoryQuery(value) {
+    if (typeof value !== 'string')
+        return '';
+    return tokenizeAgentSearchValue(value).join(' ').slice(0, MAX_QUERY_LENGTH);
+}
+export function getAgentDirectoryQueryTokens(query) {
+    return tokenizeAgentSearchValue(query).map((token) => token.slice(0, MAX_QUERY_LENGTH));
+}
+export function buildAgentSearchPrefixes(input) {
+    const seen = new Set();
+    for (const token of tokenizeAgentSearchValue([input.displayName, input.description].filter(Boolean).join(' '))) {
+        const normalizedToken = token.slice(0, MAX_QUERY_LENGTH);
+        const prefixLength = Math.min(normalizedToken.length, MAX_TOKEN_PREFIX_LENGTH);
+        for (let index = 1; index <= prefixLength; index += 1) {
+            seen.add(normalizedToken.slice(0, index));
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+        if (normalizedToken.length > MAX_TOKEN_PREFIX_LENGTH) {
+            seen.add(normalizedToken);
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+    }
+    return [...seen];
+}
+export function matchesAgentSearchQuery(profile, query) {
+    const tokens = getAgentDirectoryQueryTokens(query);
+    if (tokens.length === 0)
+        return true;
+    const prefixes = new Set(buildAgentSearchPrefixes({
+        displayName: profile.displayName,
+        description: profile.agentConfig?.description,
+    }));
+    return tokens.every((token) => prefixes.has(token));
+}

package/dist/canon-verbs.schema.json

@@ -661,7 +661,7 @@
       }
     },
     "send_to_result": {
-      "description": "Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS (hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
+      "description": "Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md (hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
       "oneOf": [
         {
           "type": "object",

package/dist/cjs/accessPolicy.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCanonicalPolicy = readCanonicalPolicy;
+/**
+ * Read a stored policy field, defaulting to the value Canon assigns on account
+ * creation. Anything unrecognized — missing, misspelled, or the retired
+ * `'private'` enum — reads as 'approval-required'. This must never widen to
+ * 'open'.
+ */
+function readCanonicalPolicy(value) {
+    if (value === 'open' || value === 'approval-required' || value === 'owner-only') {
+        return value;
+    }
+    return 'approval-required';
+}

package/dist/cjs/agentBehaviorPolicy.js

@@ -4,6 +4,7 @@ exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
 exports.parseAgentBehaviorSettings = parseAgentBehaviorSettings;
 exports.normalizeStoredAgentBehaviorPolicy = normalizeStoredAgentBehaviorPolicy;
 exports.normalizeAgentBehaviorInstructions = normalizeAgentBehaviorInstructions;
+exports.getDefaultParticipationPolicy = getDefaultParticipationPolicy;
 exports.resolveAgentBehaviorPolicy = resolveAgentBehaviorPolicy;
 exports.buildParticipationHistorySnapshot = buildParticipationHistorySnapshot;
 exports.appendParticipationHistoryMessage = appendParticipationHistoryMessage;
@@ -62,16 +63,9 @@ function resolveGroupMentionRequirement(input) {
         && typeof input.requireMentionForGroupReplies !== 'boolean') {
         throw new Error('requireMentionForGroupReplies must be a boolean');
     }
-    if (input.requireMentionForGroupAgentReplies !== undefined
-        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
-        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
-    }
     if (typeof input.requireMentionForGroupReplies === 'boolean') {
         return input.requireMentionForGroupReplies;
     }
-    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
-        return input.requireMentionForGroupAgentReplies;
-    }
     return undefined;
 }
 function parseAgentBehaviorSettings(raw) {
@@ -114,9 +108,7 @@ function normalizeStoredAgentBehaviorPolicy(raw) {
             : {}),
         ...(typeof raw.requireMentionForGroupReplies === 'boolean'
             ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
-            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
-                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
-                : {}),
+            : {}),
         ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
             ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
             : {}),
@@ -138,6 +130,9 @@ function normalizeAgentBehaviorInstructions(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+function getDefaultParticipationPolicy() {
+    return { ...DEFAULT_POLICY.participation };
+}
 function resolveAgentBehaviorPolicy(params) {
     const agentDefault = params?.agentDefault ?? null;
     const conversationOverride = params?.conversationOverride ?? null;
@@ -214,37 +209,59 @@ function appendParticipationHistoryMessage(snapshot, message, limit = exports.PA
     ].slice(0, limit));
 }
 function evaluateParticipationPolicy(policy, input) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const participation = resolved.participation;
     const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
     if (input.conversationType === 'group'
-        && policy.participation.requireMentionForGroupReplies
+        && participation.requireMentionForGroupReplies
         && !input.mentionedAgent) {
         return {
             allow: false,
+            reasonCode: 'group_mention_required',
             reason: 'group replies require a direct mention',
         };
     }
     if (input.isOwner) {
-        return { allow: true, reason: 'owner messages pass through outside mention-required group turns' };
+        return {
+            allow: true,
+            reasonCode: 'owner_sender',
+            reason: 'owner messages pass through outside mention-required group turns',
+        };
     }
     if (input.senderType !== 'ai_agent') {
-        return { allow: true, reason: 'latest sender is human' };
+        return { allow: true, reasonCode: 'human_sender', reason: 'latest sender is human' };
     }
-    if (!policy.participation.allowAgentToAgent) {
-        return { allow: false, reason: 'agent-to-agent participation disabled by policy' };
+    if (!participation.allowAgentToAgent) {
+        return {
+            allow: false,
+            reasonCode: 'agent_to_agent_disabled',
+            reason: 'agent-to-agent participation is disabled by policy',
+        };
     }
-    if (!policy.participation.allowLongRunningCollaboration
+    if (!participation.allowLongRunningCollaboration
         && (consecutiveAgentTurns > 1
             || !currentAgentStreakStartedByHuman)) {
         return {
             allow: false,
+            reasonCode: 'human_reset_required',
             reason: 'a fresh human steer is required before continuing agent collaboration',
         };
     }
-    if (typeof policy.participation.maxConsecutiveAgentTurns === 'number'
-        && policy.participation.maxConsecutiveAgentTurns >= 0
-        && consecutiveAgentTurns > policy.participation.maxConsecutiveAgentTurns) {
-        return { allow: false, reason: 'maximum consecutive agent turns reached' };
+    if (typeof participation.maxConsecutiveAgentTurns === 'number'
+        && participation.maxConsecutiveAgentTurns >= 0
+        && consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        return {
+            allow: false,
+            reasonCode: 'agent_turn_limit_reached',
+            reason: 'maximum consecutive agent turns reached',
+        };
     }
-    return { allow: true, reason: 'agent-to-agent participation allowed by policy' };
+    return {
+        allow: true,
+        reasonCode: input.conversationType === 'group' ? 'group_agent_allowed' : 'direct_agent_allowed',
+        reason: participation.requireMentionForGroupReplies
+            ? 'policy allows this directly mentioned group reply'
+            : 'agent-to-agent participation allowed by policy',
+    };
 }

package/dist/cjs/agentSearch.js

@@ -0,0 +1,64 @@
+"use strict";
+// The single agent-directory search implementation, shared by Cloud Functions
+// (which writes `users/{agentId}.searchPrefixes` and filters discovery reads)
+// and `@canonmsg/chat-domain` (which filters the same agents client-side in the
+// app and on web). The server index and the client filter must agree, so both
+// sides derive from these bodies rather than from hand-synced copies.
+//
+// Pure ECMAScript: no imports, no Node built-ins, no Firestore types — safe in
+// CJS, in the browser bundle, and on Hermes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAgentDirectoryQuery = normalizeAgentDirectoryQuery;
+exports.getAgentDirectoryQueryTokens = getAgentDirectoryQueryTokens;
+exports.buildAgentSearchPrefixes = buildAgentSearchPrefixes;
+exports.matchesAgentSearchQuery = matchesAgentSearchQuery;
+const MAX_QUERY_LENGTH = 64;
+const MAX_TOKEN_PREFIX_LENGTH = 32;
+const MAX_SEARCH_PREFIXES = 256;
+const TOKEN_PATTERN = /[\p{L}\p{N}]+/gu;
+function tokenizeAgentSearchValue(value) {
+    const normalized = value
+        .normalize('NFKD')
+        .toLowerCase()
+        .trim();
+    return normalized.match(TOKEN_PATTERN) ?? [];
+}
+/** Tolerant: non-string input normalises to ''. */
+function normalizeAgentDirectoryQuery(value) {
+    if (typeof value !== 'string')
+        return '';
+    return tokenizeAgentSearchValue(value).join(' ').slice(0, MAX_QUERY_LENGTH);
+}
+function getAgentDirectoryQueryTokens(query) {
+    return tokenizeAgentSearchValue(query).map((token) => token.slice(0, MAX_QUERY_LENGTH));
+}
+function buildAgentSearchPrefixes(input) {
+    const seen = new Set();
+    for (const token of tokenizeAgentSearchValue([input.displayName, input.description].filter(Boolean).join(' '))) {
+        const normalizedToken = token.slice(0, MAX_QUERY_LENGTH);
+        const prefixLength = Math.min(normalizedToken.length, MAX_TOKEN_PREFIX_LENGTH);
+        for (let index = 1; index <= prefixLength; index += 1) {
+            seen.add(normalizedToken.slice(0, index));
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+        if (normalizedToken.length > MAX_TOKEN_PREFIX_LENGTH) {
+            seen.add(normalizedToken);
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+    }
+    return [...seen];
+}
+function matchesAgentSearchQuery(profile, query) {
+    const tokens = getAgentDirectoryQueryTokens(query);
+    if (tokens.length === 0)
+        return true;
+    const prefixes = new Set(buildAgentSearchPrefixes({
+        displayName: profile.displayName,
+        description: profile.agentConfig?.description,
+    }));
+    return tokens.every((token) => prefixes.has(token));
+}

package/dist/cjs/contactSources.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMISSION_GRANTING_SOURCES = void 0;
+exports.isAdmissionGrantingContactSource = isAdmissionGrantingContactSource;
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+const ADMISSION_GRANTING_CONTACT_SOURCES = [
+    'contact_request',
+    'direct_add',
+    'link',
+    'qr',
+    'group',
+    'phone_book',
+    'open_inbound_message',
+];
+exports.ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+function isAdmissionGrantingContactSource(source) {
+    if (source === null || source === undefined)
+        return false;
+    return exports.ADMISSION_GRANTING_SOURCES.has(source);
+}

package/dist/cjs/firestoreValues.js

@@ -0,0 +1,27 @@
+"use strict";
+// Normalizers for values read straight off a Firestore document. Callers pass
+// plain doc-shaped data, never a Firestore handle — this package holds no I/O.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStoredString = normalizeStoredString;
+exports.firestoreTimestampToISOString = firestoreTimestampToISOString;
+/** Trimmed string, or null when absent/empty. */
+function normalizeStoredString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+function firestoreTimestampToISOString(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const maybeTimestamp = value;
+    if (typeof maybeTimestamp.toDate !== 'function')
+        return null;
+    return maybeTimestamp.toDate().toISOString();
+}

package/dist/cjs/index.js

@@ -22,7 +22,13 @@ __exportStar(require("./runtimeCardFields.js"), exports);
 __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
+__exportStar(require("./agentSearch.js"), exports);
 __exportStar(require("./contactRequest.js"), exports);
+__exportStar(require("./contactSources.js"), exports);
 __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);
+__exportStar(require("./accessPolicy.js"), exports);
+__exportStar(require("./firestoreValues.js"), exports);
+__exportStar(require("./moderation.js"), exports);
+__exportStar(require("./selfContext.js"), exports);

package/dist/cjs/moderation.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readModerationStatus = readModerationStatus;
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+function readModerationStatus(data) {
+    const record = data;
+    return record?.status === 'ejected' ? 'ejected' : 'active';
+}

package/dist/cjs/runtimeCardFields.js

@@ -1,7 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIME_CARD_LIMITS = void 0;
+exports.RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES = exports.RUNTIME_CARD_LIMITS = exports.RUNTIME_CARD_FIELD_TYPES = void 0;
 exports.validateRuntimeCardFieldValues = validateRuntimeCardFieldValues;
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into two committed SKILL.md files, and
+ * `npm run check:skill-bundles` fails on a byte change.
+ */
+exports.RUNTIME_CARD_FIELD_TYPES = [
+    'text',
+    'textarea',
+    'select',
+    'multiSelect',
+    'boolean',
+    'date',
+    'number',
+    'currency',
+    'searchSelect',
+    'lineItems',
+];
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -12,6 +33,14 @@ exports.RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+/** Column cell types allowed inside a `lineItems` field. */
+exports.RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES = [
+    'text',
+    'number',
+    'currency',
+    'date',
+    'select',
+];
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/cjs/runtimeCardStorage.js

@@ -5,9 +5,6 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function decodeStoredRuntimeCard(input) {
-    if (isRecord(input.runtimeCard)) {
-        return input.runtimeCard;
-    }
     if (typeof input.runtimeCardJson !== 'string' || !input.runtimeCardJson.trim()) {
         return undefined;
     }

package/dist/cjs/selfContext.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStoredSelfContextId = normalizeStoredSelfContextId;
+exports.serializeSelfContext = serializeSelfContext;
+const verbContract_js_1 = require("./verbContract.js");
+const firestoreValues_js_1 = require("./firestoreValues.js");
+/** Stored self-context id, or null when absent, empty, or path-like. */
+function normalizeStoredSelfContextId(value) {
+    const id = (0, firestoreValues_js_1.normalizeStoredString)(value);
+    if (!id || id.includes('/'))
+        return null;
+    return id;
+}
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+function serializeSelfContext(id, data) {
+    if (data.type !== verbContract_js_1.SELF_CONTEXT_TYPE)
+        return null;
+    const context = (0, firestoreValues_js_1.normalizeStoredString)(data.context);
+    if (!context)
+        return null;
+    return {
+        id,
+        type: verbContract_js_1.SELF_CONTEXT_TYPE,
+        context,
+        createdAt: (0, firestoreValues_js_1.firestoreTimestampToISOString)(data.createdAt),
+        updatedAt: (0, firestoreValues_js_1.firestoreTimestampToISOString)(data.updatedAt),
+    };
+}

package/dist/cjs/verbSchemas.js

@@ -404,7 +404,7 @@ const send_to_input = {
     dependentRequired: { selfContext: ['sourceConversationId'] },
 };
 const send_to_result = {
-    description: 'Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS '
+    description: 'Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md '
         + "(hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
     oneOf: [
         {

package/dist/contactSources.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+declare const ADMISSION_GRANTING_CONTACT_SOURCES: readonly ["contact_request", "direct_add", "link", "qr", "group", "phone_book", "open_inbound_message"];
+export type AdmissionGrantingContactSource = (typeof ADMISSION_GRANTING_CONTACT_SOURCES)[number];
+export declare const ADMISSION_GRANTING_SOURCES: ReadonlySet<AdmissionGrantingContactSource>;
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+export declare function isAdmissionGrantingContactSource(source: string | null | undefined): boolean;
+export {};

package/dist/contactSources.js

@@ -0,0 +1,41 @@
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+const ADMISSION_GRANTING_CONTACT_SOURCES = [
+    'contact_request',
+    'direct_add',
+    'link',
+    'qr',
+    'group',
+    'phone_book',
+    'open_inbound_message',
+];
+export const ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+export function isAdmissionGrantingContactSource(source) {
+    if (source === null || source === undefined)
+        return false;
+    return ADMISSION_GRANTING_SOURCES.has(source);
+}

package/dist/firestoreValues.d.ts

@@ -0,0 +1,9 @@
+/** Trimmed string, or null when absent/empty. */
+export declare function normalizeStoredString(value: unknown): string | null;
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+export declare function firestoreTimestampToISOString(value: unknown): string | null;

package/dist/firestoreValues.js

@@ -0,0 +1,23 @@
+// Normalizers for values read straight off a Firestore document. Callers pass
+// plain doc-shaped data, never a Firestore handle — this package holds no I/O.
+/** Trimmed string, or null when absent/empty. */
+export function normalizeStoredString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+export function firestoreTimestampToISOString(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const maybeTimestamp = value;
+    if (typeof maybeTimestamp.toDate !== 'function')
+        return null;
+    return maybeTimestamp.toDate().toISOString();
+}

package/dist/index.d.ts

@@ -6,7 +6,13 @@ export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
+export * from './agentSearch.js';
 export * from './contactRequest.js';
+export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
+export * from './accessPolicy.js';
+export * from './firestoreValues.js';
+export * from './moderation.js';
+export * from './selfContext.js';

package/dist/index.js

@@ -6,7 +6,13 @@ export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
+export * from './agentSearch.js';
 export * from './contactRequest.js';
+export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
+export * from './accessPolicy.js';
+export * from './firestoreValues.js';
+export * from './moderation.js';
+export * from './selfContext.js';

package/dist/moderation.d.ts

@@ -0,0 +1,7 @@
+export type ModerationStatus = 'active' | 'ejected';
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+export declare function readModerationStatus(data: unknown): ModerationStatus;

package/dist/moderation.js

@@ -0,0 +1,9 @@
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+export function readModerationStatus(data) {
+    const record = data;
+    return record?.status === 'ejected' ? 'ejected' : 'active';
+}

package/dist/runtimeCardFields.d.ts

@@ -1,4 +1,14 @@
-export type RuntimeCardFieldType = 'text' | 'textarea' | 'select' | 'multiSelect' | 'boolean' | 'date' | 'number' | 'currency' | 'searchSelect' | 'lineItems';
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into two committed SKILL.md files, and
+ * `npm run check:skill-bundles` fails on a byte change.
+ */
+export declare const RUNTIME_CARD_FIELD_TYPES: readonly ["text", "textarea", "select", "multiSelect", "boolean", "date", "number", "currency", "searchSelect", "lineItems"];
+export type RuntimeCardFieldType = (typeof RUNTIME_CARD_FIELD_TYPES)[number];
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -15,7 +25,9 @@ export interface RuntimeCardFieldChoice {
     description?: string;
     preview?: string;
 }
-export type RuntimeCardLineItemColumnType = 'text' | 'number' | 'currency' | 'date' | 'select';
+/** Column cell types allowed inside a `lineItems` field. */
+export declare const RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES: readonly ["text", "number", "currency", "date", "select"];
+export type RuntimeCardLineItemColumnType = (typeof RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES)[number];
 export interface RuntimeCardLineItemColumn {
     id: string;
     label: string;

package/dist/runtimeCardFields.js

@@ -1,3 +1,24 @@
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into two committed SKILL.md files, and
+ * `npm run check:skill-bundles` fails on a byte change.
+ */
+export const RUNTIME_CARD_FIELD_TYPES = [
+    'text',
+    'textarea',
+    'select',
+    'multiSelect',
+    'boolean',
+    'date',
+    'number',
+    'currency',
+    'searchSelect',
+    'lineItems',
+];
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -8,6 +29,14 @@ export const RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+/** Column cell types allowed inside a `lineItems` field. */
+export const RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES = [
+    'text',
+    'number',
+    'currency',
+    'date',
+    'select',
+];
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/runtimeCardStorage.d.ts

@@ -1,4 +1,3 @@
 export declare function decodeStoredRuntimeCard(input: {
-    runtimeCard?: unknown;
     runtimeCardJson?: unknown;
 }): Record<string, unknown> | undefined;

package/dist/runtimeCardStorage.js

@@ -2,9 +2,6 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 export function decodeStoredRuntimeCard(input) {
-    if (isRecord(input.runtimeCard)) {
-        return input.runtimeCard;
-    }
     if (typeof input.runtimeCardJson !== 'string' || !input.runtimeCardJson.trim()) {
         return undefined;
     }

package/dist/selfContext.d.ts

@@ -0,0 +1,9 @@
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export declare function normalizeStoredSelfContextId(value: unknown): string | null;
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+export declare function serializeSelfContext(id: string, data: Record<string, unknown>): Record<string, unknown> | null;

package/dist/selfContext.js

@@ -0,0 +1,29 @@
+import { SELF_CONTEXT_TYPE } from './verbContract.js';
+import { firestoreTimestampToISOString, normalizeStoredString } from './firestoreValues.js';
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export function normalizeStoredSelfContextId(value) {
+    const id = normalizeStoredString(value);
+    if (!id || id.includes('/'))
+        return null;
+    return id;
+}
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+export function serializeSelfContext(id, data) {
+    if (data.type !== SELF_CONTEXT_TYPE)
+        return null;
+    const context = normalizeStoredString(data.context);
+    if (!context)
+        return null;
+    return {
+        id,
+        type: SELF_CONTEXT_TYPE,
+        context,
+        createdAt: firestoreTimestampToISOString(data.createdAt),
+        updatedAt: firestoreTimestampToISOString(data.updatedAt),
+    };
+}

package/dist/verbSchemas.js

@@ -399,7 +399,7 @@ const send_to_input = {
     dependentRequired: { selfContext: ['sourceConversationId'] },
 };
 const send_to_result = {
-    description: 'Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS '
+    description: 'Canonical outcome vocabulary. Legacy binding drift documented in docs/design/verb-bindings.md '
         + "(hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
     oneOf: [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "4.0.1",
+  "version": "5.1.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.8.6",
+    "@canonmsg/rich-cards": "^0.8.7",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",