Discoverable entity

@kindgi/specs/discoverable.schema.json, schema version 1.1.0.

Marks an entity (chat, conversation, document, artifact, memo, playbook, tool) as searchable via the cross-history retrieval API. The framework handles embedding via a configured provider; retrieval is always policy-scoped (owner / team / project / org / tenant). Deletion cascades to embeddings + retrieval caches.

• entityId (string, required): ID of the entity being made discoverable.
• entityKind ("chat" | "conversation" | "document" | "artifact" | "memo" | "playbook" | "tool" | "agent" | "flow" | "note", required)
• scope (DiscoverabilityScope, required)
• tags (array of string): Tags to filter retrieval by (e.g. 'customer:acme', 'topic:billing').
• title (string): Human-readable title used in search UIs.
• summary (string): Optional pre-computed summary used as a second-tier retrieval index (embed summaries + link to full content).
• content (object): Content to index. May be inline string or a blob reference. If absent, the retrieval layer derives content from the entity by kind.
• contentRef (string): Optional blob reference for large content. Format: 'blob://<provider>/<bucket>/<key>'.
• embeddingConfig (object)
  • model (string): Embedding model id, as a registered embedding provider reports it (describe().model). Router picks based on tenant policy if absent.
  • chunker ("turn-aware" | "sliding-window" | "recursive" | "semantic"): Chunking strategy. 'turn-aware' is the correct default for chats and conversations (context-preserving); documents use 'recursive' or 'sliding-window'.
  • chunkSize (integer)
  • chunkOverlap (integer)
• retention (object)
  • keepUntil (string (date-time))
  • keepDays (integer)
  • legalHold (boolean)
• declaredAt (string (date-time))

Definitions

DiscoverabilityScope

• tenantId (string, required)
• visibility ("owner-only" | "team" | "project" | "org" | "public", required): Who can retrieve this entity via search. 'owner-only' = declaring user only. 'team' = members of a specified team (added in schema-version 1.1.0). 'project' = anyone with policy access to the project. 'org' = anyone in the org with the appropriate role. 'public' = anyone in the tenant. Policy engine enforces at retrieval time regardless of this hint.
• userId (string): Required if visibility = 'owner-only'.
• teamId (string): Required if visibility = 'team'. Added in schema-version 1.1.0.
• projectId (string): Required if visibility = 'project'.
• orgId (string): Required if visibility = 'org'.
• allowedRoles (array of string): Additional role gate applied on top of visibility (e.g. 'admin-only', 'compliance-only').