@indexnetwork/protocol 6.12.0-rc.403.1 → 6.13.22-rc.405.1

package/dist/participant-agents/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * participant-agents — domain-first module root.
+ *
+ * Re-exports the curated public surface.  Other modules inside the
+ * participant-agents capability import directly from
+ * participant-agents/domain, participant-agents/application, or
+ * participant-agents/ports; this barrel is for cross-capability consumers
+ * that must go through the participant-agents public surface.
+ *
+ * IND-548: canonical home for agent registration, permission-aware behaviour,
+ * and dispatch contracts previously spread across agent/,
+ * shared/interfaces/agent.interface.ts, and
+ * shared/interfaces/agent-dispatcher.interface.ts.
+ *
+ * Legacy paths:
+ * - agent/* — thin compatibility shims pointing to participant-agents/application
+ * - shared/interfaces/agent.interface.ts — re-exports from participant-agents/domain
+ *   and participant-agents/ports
+ * - shared/interfaces/agent-dispatcher.interface.ts — re-exports from
+ *   participant-agents/ports
+ * - capabilities/participant-agents.tools.port.ts — re-exports AgentToolDeps
+ *   from participant-agents/ports
+ */
+export * from "./public/index.js";

package/dist/participant-agents/index.js

@@ -0,0 +1,24 @@
+/**
+ * participant-agents — domain-first module root.
+ *
+ * Re-exports the curated public surface.  Other modules inside the
+ * participant-agents capability import directly from
+ * participant-agents/domain, participant-agents/application, or
+ * participant-agents/ports; this barrel is for cross-capability consumers
+ * that must go through the participant-agents public surface.
+ *
+ * IND-548: canonical home for agent registration, permission-aware behaviour,
+ * and dispatch contracts previously spread across agent/,
+ * shared/interfaces/agent.interface.ts, and
+ * shared/interfaces/agent-dispatcher.interface.ts.
+ *
+ * Legacy paths:
+ * - agent/* — thin compatibility shims pointing to participant-agents/application
+ * - shared/interfaces/agent.interface.ts — re-exports from participant-agents/domain
+ *   and participant-agents/ports
+ * - shared/interfaces/agent-dispatcher.interface.ts — re-exports from
+ *   participant-agents/ports
+ * - capabilities/participant-agents.tools.port.ts — re-exports AgentToolDeps
+ *   from participant-agents/ports
+ */
+export * from "./public/index.js";

package/dist/participant-agents/ports/agent.dispatcher.port.d.ts

@@ -0,0 +1,25 @@
+/**
+ * participant-agents/ports — AgentDispatcher dispatch port.
+ *
+ * Re-exports the canonical agent dispatcher contract from shared/interfaces.
+ *
+ * ## Why re-export instead of defining here?
+ *
+ * The negotiation capability imports AgentDispatcher and NegotiationTurnPayload
+ * from shared/interfaces/agent-dispatcher.interface.ts.  If this file defined
+ * the types and shared/interfaces became a shim pointing here, a cycle would
+ * form through the module graph:
+ *
+ *   agent.dispatcher.port (participant-agents) → capabilities/negotiation.facade
+ *   (the facade is expanded by cycle-baseline to its impl targets) →
+ *   negotiation.graph.ts → shared/interfaces/agent-dispatcher.interface.ts
+ *   (shim) → participant-agents/ports/index.ts → agent.dispatcher.port
+ *
+ * The solution is to leave shared/interfaces/agent-dispatcher.interface.ts as
+ * the authoritative file and surface its types through the participant-agents
+ * ports boundary via re-export.
+ *
+ * IND-548: participant-agents/ports re-exports the dispatcher contract
+ * established in shared/interfaces/agent-dispatcher.interface.ts.
+ */
+export type { AgentDispatcher, AgentDispatchResult, NegotiationTurnPayload, } from '../../shared/interfaces/agent-dispatcher.interface.js';

package/dist/participant-agents/ports/agent.dispatcher.port.js

@@ -0,0 +1 @@
+export {};

package/dist/participant-agents/ports/agent.repository.port.d.ts

@@ -0,0 +1,118 @@
+/**
+ * participant-agents/ports — AgentDatabase persistence port.
+ *
+ * Injected boundary for agent registry persistence.  Implemented by the
+ * host application and passed into the protocol layer at the composition root.
+ *
+ * IND-548: extracted from shared/interfaces/agent.interface.ts into the
+ * participant-agents capability's dedicated ports layer.
+ */
+import type { AgentRecord, AgentTransportRecord, AgentPermissionRecord, AgentWithRelations, CreateAgentInput, CreateTransportInput, GrantPermissionInput } from "../domain/index.js";
+/**
+ * Database adapter interface for agent registry operations.
+ *
+ * Handles CRUD for agents, their transports, and permission grants.
+ * Implemented by the host application (backend) and injected into the
+ * protocol layer via constructor injection at the composition root.
+ */
+export interface AgentDatabase {
+    /**
+     * Creates a new agent record.
+     * @param input - Agent creation parameters.
+     * @returns The persisted agent record.
+     */
+    createAgent(input: CreateAgentInput): Promise<AgentRecord>;
+    /**
+     * Retrieves an agent by its ID.
+     * @param agentId - The agent UUID.
+     * @returns The agent record, or null if not found.
+     */
+    getAgent(agentId: string): Promise<AgentRecord | null>;
+    /**
+     * Retrieves an agent along with its transports and permissions.
+     * @param agentId - The agent UUID.
+     * @returns The agent with relations, or null if not found.
+     */
+    getAgentWithRelations(agentId: string): Promise<AgentWithRelations | null>;
+    /**
+     * Updates mutable fields on an agent.
+     * @param agentId - The agent UUID.
+     * @param updates - Partial set of fields to update.
+     * @returns The updated agent record, or null if not found.
+     */
+    updateAgent(agentId: string, updates: Partial<Pick<AgentRecord, 'name' | 'description' | 'status' | 'metadata'>>): Promise<AgentRecord | null>;
+    /**
+     * Deletes an agent and its associated transports and permissions.
+     * @param agentId - The agent UUID.
+     */
+    deleteAgent(agentId: string): Promise<void>;
+    /**
+     * Lists all agents owned by a user, including their relations.
+     * @param userId - The owner's user ID.
+     * @returns Array of agents with transports and permissions.
+     */
+    listAgentsForUser(userId: string): Promise<AgentWithRelations[]>;
+    /**
+     * Creates a transport channel for an agent.
+     * @param input - Transport creation parameters.
+     * @returns The persisted transport record.
+     */
+    createTransport(input: CreateTransportInput): Promise<AgentTransportRecord>;
+    /**
+     * Deletes a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    deleteTransport(transportId: string): Promise<void>;
+    /**
+     * Increments the failure counter for a transport channel.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportFailure(transportId: string): Promise<void>;
+    /**
+     * Resets the failure counter for a transport channel after a successful delivery.
+     * @param transportId - The transport UUID.
+     */
+    recordTransportSuccess(transportId: string): Promise<void>;
+    /**
+     * Grants a permission to an agent for a given user and scope.
+     * @param input - Permission grant parameters.
+     * @returns The persisted permission record.
+     */
+    grantPermission(input: GrantPermissionInput): Promise<AgentPermissionRecord>;
+    /**
+     * Revokes a permission by its ID.
+     * @param permissionId - The permission UUID.
+     */
+    revokePermission(permissionId: string): Promise<void>;
+    /**
+     * Checks whether an agent holds a specific permission for a user.
+     * @param agentId - The agent UUID.
+     * @param userId - The user whose permission is being checked.
+     * @param action - The action string to verify (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction; defaults to global if omitted.
+     * @returns True if the permission exists, false otherwise.
+     */
+    hasPermission(agentId: string, userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<boolean>;
+    /**
+     * Returns all agents authorized for a user and action, optionally within a scope.
+     * @param userId - The user to check authorization for.
+     * @param action - The action string (e.g. `"read"`, `"write"`).
+     * @param scope - Optional scope restriction.
+     * @returns Array of authorized agents with their relations.
+     */
+    findAuthorizedAgents(userId: string, action: string, scope?: {
+        type: 'global' | 'node' | 'network';
+        id?: string;
+    }): Promise<AgentWithRelations[]>;
+    /**
+     * Returns the well-known IDs for built-in system agents.
+     * @returns Object mapping system agent roles to their fixed UUIDs.
+     */
+    getSystemAgentIds(): {
+        chatOrchestrator: string;
+        negotiator: string;
+    };
+}

package/dist/participant-agents/ports/agent.repository.port.js

@@ -0,0 +1,10 @@
+/**
+ * participant-agents/ports — AgentDatabase persistence port.
+ *
+ * Injected boundary for agent registry persistence.  Implemented by the
+ * host application and passed into the protocol layer at the composition root.
+ *
+ * IND-548: extracted from shared/interfaces/agent.interface.ts into the
+ * participant-agents capability's dedicated ports layer.
+ */
+export {};

package/dist/participant-agents/ports/agent.tools.port.d.ts

@@ -0,0 +1,24 @@
+/**
+ * participant-agents/ports — AgentToolDeps tool host port.
+ *
+ * Narrow port type consumed by createAgentTools. The host provides an
+ * optional AgentDatabase so agent registration tools are compiled only
+ * when the database adapter is wired at the composition root.
+ *
+ * NOTE: This type is intentionally defined inline (not derived via Pick from
+ * ToolRegistryCompositionDeps in shared/agent/tool.helpers.ts) to avoid a
+ * module cycle. ToolRegistryCompositionDeps imports AgentDatabase from
+ * shared/interfaces/agent.interface.ts, which after IND-548 forwards to
+ * participant-agents/ports — creating a cycle back here.
+ *
+ * Structural equivalence with ToolRegistryCompositionDeps.agentDatabase is
+ * preserved: both have type `AgentDatabase | undefined`.
+ *
+ * IND-548: extracted from capabilities/participant-agents.tools.port.ts
+ * into the participant-agents capability's dedicated ports layer.
+ */
+import type { AgentDatabase } from './agent.repository.port.js';
+/** Host capabilities consumed by participant-agent registry tools. */
+export type AgentToolDeps = {
+    agentDatabase?: AgentDatabase;
+};

package/dist/participant-agents/ports/agent.tools.port.js

@@ -0,0 +1,20 @@
+/**
+ * participant-agents/ports — AgentToolDeps tool host port.
+ *
+ * Narrow port type consumed by createAgentTools. The host provides an
+ * optional AgentDatabase so agent registration tools are compiled only
+ * when the database adapter is wired at the composition root.
+ *
+ * NOTE: This type is intentionally defined inline (not derived via Pick from
+ * ToolRegistryCompositionDeps in shared/agent/tool.helpers.ts) to avoid a
+ * module cycle. ToolRegistryCompositionDeps imports AgentDatabase from
+ * shared/interfaces/agent.interface.ts, which after IND-548 forwards to
+ * participant-agents/ports — creating a cycle back here.
+ *
+ * Structural equivalence with ToolRegistryCompositionDeps.agentDatabase is
+ * preserved: both have type `AgentDatabase | undefined`.
+ *
+ * IND-548: extracted from capabilities/participant-agents.tools.port.ts
+ * into the participant-agents capability's dedicated ports layer.
+ */
+export {};

package/dist/participant-agents/ports/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * participant-agents/ports — injected dependency contracts.
+ *
+ * Re-exports the narrow port types that the participant-agents module
+ * declares as explicit injected boundaries.  Consumers import these to
+ * wire host implementations without depending on the application layer.
+ *
+ * ## Port groups
+ *
+ * ### Persistence port
+ * - AgentDatabase — agent CRUD, transport management, permission grants.
+ *
+ * ### Dispatch port
+ * - AgentDispatcher — negotiation turn dispatch (external poller + fallback).
+ * - AgentDispatchResult — dispatch outcome discriminated union.
+ * - NegotiationTurnPayload — full context sent to the dispatched agent.
+ *
+ * ### Tool host port
+ * - AgentToolDeps — host capabilities for registration/permission tools.
+ *
+ * IND-548: canonical ports surface for the participant-agents capability.
+ * Legacy paths:
+ *   - shared/interfaces/agent.interface.ts → re-exports AgentDatabase from here
+ *   - shared/interfaces/agent-dispatcher.interface.ts → re-exports from here
+ *   - capabilities/participant-agents.tools.port.ts → re-exports AgentToolDeps from here
+ */
+export type { AgentDatabase } from "./agent.repository.port.js";
+export type { AgentDispatcher, AgentDispatchResult, NegotiationTurnPayload, } from "./agent.dispatcher.port.js";
+export type { AgentToolDeps } from "./agent.tools.port.js";

package/dist/participant-agents/ports/index.js

@@ -0,0 +1,27 @@
+/**
+ * participant-agents/ports — injected dependency contracts.
+ *
+ * Re-exports the narrow port types that the participant-agents module
+ * declares as explicit injected boundaries.  Consumers import these to
+ * wire host implementations without depending on the application layer.
+ *
+ * ## Port groups
+ *
+ * ### Persistence port
+ * - AgentDatabase — agent CRUD, transport management, permission grants.
+ *
+ * ### Dispatch port
+ * - AgentDispatcher — negotiation turn dispatch (external poller + fallback).
+ * - AgentDispatchResult — dispatch outcome discriminated union.
+ * - NegotiationTurnPayload — full context sent to the dispatched agent.
+ *
+ * ### Tool host port
+ * - AgentToolDeps — host capabilities for registration/permission tools.
+ *
+ * IND-548: canonical ports surface for the participant-agents capability.
+ * Legacy paths:
+ *   - shared/interfaces/agent.interface.ts → re-exports AgentDatabase from here
+ *   - shared/interfaces/agent-dispatcher.interface.ts → re-exports from here
+ *   - capabilities/participant-agents.tools.port.ts → re-exports AgentToolDeps from here
+ */
+export {};

package/dist/participant-agents/public/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * participant-agents/public — curated public surface of the participant-agents capability.
+ *
+ * Re-exports stable contracts from domain, application, and ports.
+ * Runtime adapter creation (tool factories) is accessible here for package
+ * consumers; internal module details (persona definitions, prompt builders,
+ * graph state) remain private to the application layer.
+ *
+ * ## Boundary
+ *
+ * References only participant-agents/domain, participant-agents/application,
+ * and participant-agents/ports.  Never imports from runtime/foreground, host
+ * implementations, or other capability internals.
+ *
+ * ## Intentionally excluded from public surface
+ *
+ * The following are application-internal or runtime-owned:
+ * - ChatGraphFactory, ChatPersonaConfig, ChatPersona — runtime graph wiring;
+ *   consumers should import via capabilities/participant-agents.facade.ts.
+ * - Persona constants (ORCHESTRATOR_PERSONA_ID, SIGNAL_PERSONA, etc.) — chat
+ *   runtime internals; import from capabilities/participant-agents.facade.ts.
+ * - ChatTitleGenerator, ChatSummarizer, etc. — runtime tool composition; import
+ *   via capabilities/participant-agents.facade.ts.
+ *
+ * ## Foreground adapters (participant-directed, authenticated)
+ *
+ * - `createAgentTools` — registration, permission grant/revoke, listing, CRUD
+ *   MCP tools for authenticated agent management paths.
+ *
+ * IND-548: canonical public surface for the participant-agents capability.
+ * Legacy paths (capabilities/participant-agents.facade.ts) re-export from here
+ * for the agent-registry portion of the facade.
+ */
+export type { AgentRecord, AgentTransportRecord, AgentPermissionRecord, AgentWithRelations, CreateAgentInput, CreateTransportInput, GrantPermissionInput, } from "../domain/index.js";
+export { SYSTEM_AGENT_IDS } from "../domain/index.js";
+export type { AgentDatabase } from "../ports/index.js";
+export type { AgentDispatcher, AgentDispatchResult, NegotiationTurnPayload, } from "../ports/index.js";
+export type { AgentToolDeps } from "../ports/index.js";
+export { createAgentTools } from "../application/index.js";

package/dist/participant-agents/public/index.js

@@ -0,0 +1,36 @@
+/**
+ * participant-agents/public — curated public surface of the participant-agents capability.
+ *
+ * Re-exports stable contracts from domain, application, and ports.
+ * Runtime adapter creation (tool factories) is accessible here for package
+ * consumers; internal module details (persona definitions, prompt builders,
+ * graph state) remain private to the application layer.
+ *
+ * ## Boundary
+ *
+ * References only participant-agents/domain, participant-agents/application,
+ * and participant-agents/ports.  Never imports from runtime/foreground, host
+ * implementations, or other capability internals.
+ *
+ * ## Intentionally excluded from public surface
+ *
+ * The following are application-internal or runtime-owned:
+ * - ChatGraphFactory, ChatPersonaConfig, ChatPersona — runtime graph wiring;
+ *   consumers should import via capabilities/participant-agents.facade.ts.
+ * - Persona constants (ORCHESTRATOR_PERSONA_ID, SIGNAL_PERSONA, etc.) — chat
+ *   runtime internals; import from capabilities/participant-agents.facade.ts.
+ * - ChatTitleGenerator, ChatSummarizer, etc. — runtime tool composition; import
+ *   via capabilities/participant-agents.facade.ts.
+ *
+ * ## Foreground adapters (participant-directed, authenticated)
+ *
+ * - `createAgentTools` — registration, permission grant/revoke, listing, CRUD
+ *   MCP tools for authenticated agent management paths.
+ *
+ * IND-548: canonical public surface for the participant-agents capability.
+ * Legacy paths (capabilities/participant-agents.facade.ts) re-export from here
+ * for the agent-registry portion of the facade.
+ */
+export { SYSTEM_AGENT_IDS } from "../domain/index.js";
+// ── Application: foreground adapter tools ─────────────────────────────────────
+export { createAgentTools } from "../application/index.js";

package/dist/participant-context/application/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * participant-context/application — orchestrators, factories, and service classes.
+ *
+ * Re-exports the orchestration tier of the participant-context capability:
+ * graph factories (LangGraph compilations), LLM service classes, and utility
+ * helpers that belong to the application layer.  These are the building blocks
+ * that foreground and ambient adapters compose to implement use cases.
+ *
+ * Boundary: application-layer only.  Imports from participant-context/domain,
+ * participant-context/ports, and shared/ infrastructure — never from runtime/,
+ * host implementations, or capability facades.
+ *
+ * ## Foreground use cases (onboarding / explicit enrichment)
+ *
+ * - {@link EnrichmentGraphFactory} — compiles the enrichment pipeline graph
+ *   (scrape → decompose-premises → generate-profile → write-profile).
+ *   Invoked by the foreground shell for `preview_profile`, `confirm_profile`,
+ *   and `enrich_from_url` tools.
+ * - {@link PremiseGraphFactory} — compiles the premise lifecycle graph
+ *   (analyze → embed → dedupe → persist → index → assign-networks).
+ *   Invoked by the foreground shell for premise CRUD tools.
+ * - {@link UserContextGenerator} — synthesizes network-scoped context paragraphs
+ *   and the global identity paragraph from the active premise set.
+ *   Called by the background context-refresh adapter after premise mutations.
+ *
+ * ## Ambient use cases (scrape / decompose / regenerate / index)
+ *
+ * - {@link PremiseDecomposer} — decomposes free-text or scraped input into atomic
+ *   premises.  Used inside EnrichmentGraphFactory (decompose-premises node) and
+ *   standalone by the background decompose adapter.
+ * - {@link PremiseAnalyzer} — Speech Act classification and felicity scoring.
+ *   Used inside PremiseGraphFactory (analyze node).
+ * - {@link PremiseIndexer} — scores premise relevance to a network index.
+ *   Used inside PremiseGraphFactory (assign-networks node).
+ * - {@link EnrichmentGenerator} — generates a structured profile from user account
+ *   data via the enrichment generate-mode LLM pipeline.
+ *
+ * ## HyDE (Hypothetical Document Embeddings)
+ *
+ * HyDE is a protocol-owned technology binding that produces hypothetical
+ * embedding documents for semantic retrieval.  The HyDE sub-capability is
+ * participant-context-adjacent: it transforms participant context (premise text,
+ * profile summary) into search-optimized representations.
+ *
+ * - {@link HydeGraphFactory} — compiles the full HyDE pipeline graph.
+ * - {@link HydeGenerator} — generates hypothetical documents from a source text
+ *   and a lens label.
+ * - {@link LensInferrer} — infers retrieval lenses from a source text and optional
+ *   profile context.
+ * - {@link HydeValidator} — validates generated hypothetical documents against
+ *   prompt-injection and out-of-scope risks.
+ *
+ * IND-545: canonical application home for participant-context orchestrators
+ * previously spread across premise/, context/, enrichment/, and shared/hyde/.
+ */
+export { PremiseGraphFactory } from "../../premise/premise.graph.js";
+export { PremiseDecomposer, type PremiseDecomposerOutput, type DecomposedPremise, type ExistingPremiseRef, } from "../../premise/premise.decomposer.js";
+export { PremiseAnalyzer, type PremiseAnalyzerOutput, } from "../../premise/premise.analyzer.js";
+export { PremiseIndexer, type PremiseIndexerOutput, } from "../../premise/premise.indexer.js";
+export { EnrichmentGraphFactory, type CompiledPremiseGraph, } from "../../enrichment/enrichment.graph.js";
+export { EnrichmentGenerator, type GeneratedProfile } from "../../enrichment/enrichment.generator.js";
+export { shouldEnrichGhostDisplayNameFromParallel, isEnrichedNameMeaningful, } from "../../enrichment/enrichment.enricher.js";
+export { createEnrichmentTools } from "../../enrichment/enrichment.tools.js";
+export { createPremiseTools } from "../../premise/premise.tools.js";
+export { UserContextGenerator } from "../../context/context.generator.js";
+export { HydeGraphFactory, type HydeLensInferrerLike, type HydeGeneratorLike, type HydeValidatorLike, type HydeGraphOptions, } from "../../shared/hyde/hyde.graph.js";
+export { HydeGenerator, type HydeGeneratorOutput, type HydeGenerateInput, } from "../../shared/hyde/hyde.generator.js";
+export { LensInferrer, type LensInferenceInput, type LensInferenceOutput, FRAME_SYSTEM_PROMPT, FrameResponseSchema, } from "../../shared/hyde/lens.inferrer.js";
+export { HydeValidator, type HydeValidationDocument, type HydeValidationInput, type HydeValidationVerdict, type HydeValidationOutput, HydeValidationResponseSchema, buildHydeValidationPrompt, } from "../../shared/hyde/hyde.validator.js";
+export { computeHydeSourceTextHash, selectHydeDocumentsForGeneration } from "../../shared/hyde/hyde.documents.js";
+export { getHydeGenerationMode, type HydeGenerationMode, HYDE_FRAME_GENERATION_VERSION, } from "../../shared/hyde/hyde.env.js";
+export { HYDE_DEFAULT_CACHE_TTL, HYDE_CORPUS_PROMPTS, } from "../../shared/hyde/hyde.strategies.js";
+export { type HydeSourceFrame, HydeSourceFrameSchema, type HydeFrameRole, type HydeFrameHardConstraint, type HydeFrameNamedEntity, type HydeFrameVocabulary, HYDE_HARD_CONSTRAINT_TYPES, HYDE_NAMED_ENTITY_TYPES, } from "../../shared/hyde/hyde.frame.js";

package/dist/participant-context/application/index.js

@@ -0,0 +1,83 @@
+/**
+ * participant-context/application — orchestrators, factories, and service classes.
+ *
+ * Re-exports the orchestration tier of the participant-context capability:
+ * graph factories (LangGraph compilations), LLM service classes, and utility
+ * helpers that belong to the application layer.  These are the building blocks
+ * that foreground and ambient adapters compose to implement use cases.
+ *
+ * Boundary: application-layer only.  Imports from participant-context/domain,
+ * participant-context/ports, and shared/ infrastructure — never from runtime/,
+ * host implementations, or capability facades.
+ *
+ * ## Foreground use cases (onboarding / explicit enrichment)
+ *
+ * - {@link EnrichmentGraphFactory} — compiles the enrichment pipeline graph
+ *   (scrape → decompose-premises → generate-profile → write-profile).
+ *   Invoked by the foreground shell for `preview_profile`, `confirm_profile`,
+ *   and `enrich_from_url` tools.
+ * - {@link PremiseGraphFactory} — compiles the premise lifecycle graph
+ *   (analyze → embed → dedupe → persist → index → assign-networks).
+ *   Invoked by the foreground shell for premise CRUD tools.
+ * - {@link UserContextGenerator} — synthesizes network-scoped context paragraphs
+ *   and the global identity paragraph from the active premise set.
+ *   Called by the background context-refresh adapter after premise mutations.
+ *
+ * ## Ambient use cases (scrape / decompose / regenerate / index)
+ *
+ * - {@link PremiseDecomposer} — decomposes free-text or scraped input into atomic
+ *   premises.  Used inside EnrichmentGraphFactory (decompose-premises node) and
+ *   standalone by the background decompose adapter.
+ * - {@link PremiseAnalyzer} — Speech Act classification and felicity scoring.
+ *   Used inside PremiseGraphFactory (analyze node).
+ * - {@link PremiseIndexer} — scores premise relevance to a network index.
+ *   Used inside PremiseGraphFactory (assign-networks node).
+ * - {@link EnrichmentGenerator} — generates a structured profile from user account
+ *   data via the enrichment generate-mode LLM pipeline.
+ *
+ * ## HyDE (Hypothetical Document Embeddings)
+ *
+ * HyDE is a protocol-owned technology binding that produces hypothetical
+ * embedding documents for semantic retrieval.  The HyDE sub-capability is
+ * participant-context-adjacent: it transforms participant context (premise text,
+ * profile summary) into search-optimized representations.
+ *
+ * - {@link HydeGraphFactory} — compiles the full HyDE pipeline graph.
+ * - {@link HydeGenerator} — generates hypothetical documents from a source text
+ *   and a lens label.
+ * - {@link LensInferrer} — infers retrieval lenses from a source text and optional
+ *   profile context.
+ * - {@link HydeValidator} — validates generated hypothetical documents against
+ *   prompt-injection and out-of-scope risks.
+ *
+ * IND-545: canonical application home for participant-context orchestrators
+ * previously spread across premise/, context/, enrichment/, and shared/hyde/.
+ */
+// ── Premise graph ─────────────────────────────────────────────────────────────
+export { PremiseGraphFactory } from "../../premise/premise.graph.js";
+// ── Premise service classes ───────────────────────────────────────────────────
+export { PremiseDecomposer, } from "../../premise/premise.decomposer.js";
+export { PremiseAnalyzer, } from "../../premise/premise.analyzer.js";
+export { PremiseIndexer, } from "../../premise/premise.indexer.js";
+// ── Enrichment graph + service classes ───────────────────────────────────────
+export { EnrichmentGraphFactory, } from "../../enrichment/enrichment.graph.js";
+export { EnrichmentGenerator } from "../../enrichment/enrichment.generator.js";
+export { shouldEnrichGhostDisplayNameFromParallel, isEnrichedNameMeaningful, } from "../../enrichment/enrichment.enricher.js";
+// ── Tool factories (foreground adapters) ──────────────────────────────────────
+// These are foreground adapter entry points consumed by runtime/foreground
+// composition.  They accept compiled graphs and host deps through the tool-dep
+// ports and produce LangChain-compatible tool arrays.
+export { createEnrichmentTools } from "../../enrichment/enrichment.tools.js";
+export { createPremiseTools } from "../../premise/premise.tools.js";
+// ── Context synthesis ─────────────────────────────────────────────────────────
+export { UserContextGenerator } from "../../context/context.generator.js";
+// ── HyDE graph + service classes ─────────────────────────────────────────────
+export { HydeGraphFactory, } from "../../shared/hyde/hyde.graph.js";
+export { HydeGenerator, } from "../../shared/hyde/hyde.generator.js";
+export { LensInferrer, FRAME_SYSTEM_PROMPT, FrameResponseSchema, } from "../../shared/hyde/lens.inferrer.js";
+export { HydeValidator, HydeValidationResponseSchema, buildHydeValidationPrompt, } from "../../shared/hyde/hyde.validator.js";
+// ── HyDE utilities ────────────────────────────────────────────────────────────
+export { computeHydeSourceTextHash, selectHydeDocumentsForGeneration } from "../../shared/hyde/hyde.documents.js";
+export { getHydeGenerationMode, HYDE_FRAME_GENERATION_VERSION, } from "../../shared/hyde/hyde.env.js";
+export { HYDE_DEFAULT_CACHE_TTL, HYDE_CORPUS_PROMPTS, } from "../../shared/hyde/hyde.strategies.js";
+export { HydeSourceFrameSchema, HYDE_HARD_CONSTRAINT_TYPES, HYDE_NAMED_ENTITY_TYPES, } from "../../shared/hyde/hyde.frame.js";

package/dist/participant-context/domain/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * participant-context/domain — pure participant-context contracts.
+ *
+ * Value types, graph-state shapes, and domain model types that define the
+ * participant-context capability's domain language.
+ * No LLM calls, no LangGraph edges, no host-adapter imports.
+ *
+ * ## Domain model
+ *
+ * A **Premise** is an atomic self-descriptive proposition asserted by a
+ * participant about themselves (e.g. "I am a machine learning researcher").
+ * Premises carry:
+ *   - **Assertion**: the raw text of the proposition.
+ *   - **Provenance**: how the premise was produced (explicit user assertion,
+ *     social integration scrape, or auto-generation from account data) plus
+ *     a confidence score derived from felicity conditions.
+ *   - **Validity**: the time window during which the premise is considered
+ *     current, plus a `volatile` flag marking it for automatic retraction
+ *     when its `validUntil` window elapses.
+ *   - **Analysis**: Speech Act classification (DECLARATIVE | ASSERTIVE) and
+ *     felicity scores (authority, sincerity, clarity) recorded at creation time.
+ *
+ * ## Provenance invariants
+ *
+ * - `source: 'explicit'` — user typed or confirmed the premise directly in chat.
+ * - `source: 'integration'` — derived from a social/external data source; the
+ *   `sourceId` identifies the `user_socials` record that was the source of truth.
+ * - `source: 'generated'` — auto-produced from account data via the enrichment
+ *   generate-mode; no specific social record is the source.
+ * - `confidence` is derived from average felicity scores when the PremiseAnalyzer
+ *   runs; it falls back to 1.0 when no analysis is available (explicit tier).
+ *
+ * ## Validity / regeneration invariants
+ *
+ * - `volatile: false` (assertive tier default) — premise persists until explicitly
+ *   retracted by the participant or an update operation.
+ * - `volatile: true` (contextual tier default) — premise is automatically retracted
+ *   by the background refresh job once `validUntil` has elapsed.
+ * - Regeneration (triggered by the ambient enrichment adapter) replaces stale
+ *   integration-sourced premises when the social source is re-scraped; it MUST
+ *   NOT touch `source: 'explicit'` premises created by the participant directly.
+ * - Context synthesis (UserContextGenerator) is triggered after premise writes and
+ *   should treat the resulting paragraph as a derived projection — never as a source
+ *   of truth for premise recovery.
+ *
+ * ## Policy separation
+ *
+ * - **Foreground adapters** (onboarding preview/confirm, explicit enrichment):
+ *   managed by the foreground shell (runtime/foreground). They compose the
+ *   EnrichmentGraphFactory and PremiseGraphFactory and pass the compiled graphs
+ *   through the tool-dependency ports.
+ * - **Ambient adapters** (scrape/decompose, regeneration, indexing, representation
+ *   refresh): managed by the background runtime shell. They are the consumers of
+ *   PremiseGraphFactory and EnrichmentGraphFactory in queue-worker mode.
+ * - **Cache/enrichment/scraper/model/embedding integrations**: remain injected
+ *   ports (see participant-context/ports) or protocol-owned technology bindings
+ *   in shared/agent and shared/hyde.
+ *
+ * IND-545: canonical home for participant-context domain contracts previously
+ * spread across premise/, context/, enrichment/, and shared/hyde/.
+ * Legacy paths remain as compatibility re-exports pointing here.
+ */
+export { PremiseGraphState } from "../../premise/premise.state.js";
+export { EnrichmentGraphState } from "../../enrichment/enrichment.state.js";
+export { HydeGraphState, type HydeDocumentState, type HydeDocumentOrigin, type HydeValidationStatus, } from "../../shared/hyde/hyde.state.js";
+export type { UserContextInput, IncrementalContextInput, GlobalContextInput, GlobalIncrementalContextInput, UserContextResult, } from "../../context/context.generator.js";
+export type { PremiseAssertion, PremiseProvenance, PremiseAnalysis, PremiseValidity, PremiseRecord, } from "../../shared/interfaces/database.interface.js";