latticesql 1.16.4 → 2.0.0

package/dist/index.d.cts

@@ -746,6 +746,16 @@ interface LatticeOptions {
      * backends, or pre-opened connections.
      */
     adapter?: StorageAdapter;
+    /**
+     * When true, `render()` skips both the full-table read and the file write
+     * for tables registered without a `render` spec — those compile to a no-op
+     * that would only emit an empty `.schema-only/<table>.md`. Off by default,
+     * preserving the original behavior (the table is still scanned and an empty
+     * schema-only file written). Enable this to avoid reading large tables off
+     * the wire just to produce empty files. Tables with an explicit `render`
+     * (or `outputFile`) are unaffected.
+     */
+    renderSkipsEmpty?: boolean;
 }
 /**
  * Retention policy for the change log.
@@ -1720,6 +1730,12 @@ declare class Lattice {
     private _registerTable;
     defineMulti(name: string, def: MultiTableDefinition): this;
     defineEntityContext(table: string, def: EntityContextDefinition): this;
+    /**
+     * Register or REPLACE an entity context (overwrites instead of throwing on a
+     * redefine — see {@link SchemaManager.redefineEntityContext}). Used to refresh
+     * a canonical context at runtime after a related schema change.
+     */
+    redefineEntityContext(table: string, def: EntityContextDefinition): this;
     /**
      * All entity contexts currently registered on this Lattice — both those
      * declared in `lattice.config.yml` and those added programmatically via
@@ -4080,4 +4096,293 @@ declare function isPostgresUrl(url: string): boolean;
  */
 declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;
 
-export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CONFIG_SUBDIR, type ChangeEntry, type ChangelogOptions, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DirectRegisterResult, type EmbeddingsConfig, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type FilesRow, type Filter, type FilterOp, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, type InviteResponse, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type MemberSummary, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RedeemResponse, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RegisterResponse, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, SQLiteAdapter, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceMetadata, type SourceQueryOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TeamConnection, type TeamSummary, TeamsClient, TeamsHttpError, type TemplateRenderSpec, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, autoFtsColumns, autoUpdate, configDir, contentHash, createReadOnlyHeader, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, encrypt, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, findLatticeRoot, fixSchemaConflicts, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateWriteEntryId, getActiveWorkspace, getDbCredential, getOrCreateMasterKey, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, manifestPath, markdownTable, migrateLatticeData, normalizeEntityFiles, openTargetLatticeForMigration, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, registerDirectViaPostgres, registerNativeEntities, registryPath, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, rootConfigDir, saveDbCredential, saveDbCredentialForTeam, setActiveWorkspace, slugify, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };
+/** A content block in the Anthropic message format used here. */
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+interface LlmMessage {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+interface ToolUse {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface TurnResult {
+    stopReason: string;
+    text: string;
+    toolUses: ToolUse[];
+}
+/** Minimal tool shape passed to the model (decoupled from the GUI tool catalog). */
+interface LlmTool {
+    name: string;
+    description?: string;
+    input_schema: unknown;
+}
+interface TurnParams {
+    model: string;
+    system: string;
+    messages: LlmMessage[];
+    tools: LlmTool[];
+    /** Called with each streamed text delta. */
+    onText: (delta: string) => void;
+}
+/** The slice of the Anthropic client the AI features depend on. */
+interface LlmClient {
+    runTurn(params: TurnParams): Promise<TurnResult>;
+}
+/**
+ * How to authenticate to Anthropic: a raw API key, or an OAuth Bearer token
+ * (from a connected Claude subscription). `betaHeader` carries an optional
+ * `anthropic-beta` value (sourced from env for the OAuth path — not hardcoded).
+ */
+interface ClaudeAuth {
+    apiKey?: string | undefined;
+    authToken?: string | undefined;
+    betaHeader?: string | undefined;
+}
+
+/** Generate a 1-2 sentence description of a document's text. */
+declare function summarizeText(client: LlmClient, text: string, name: string): Promise<string>;
+/** A candidate record an ingested file might relate to. */
+interface CatalogRecord {
+    id: string;
+    label: string;
+}
+interface CatalogEntity {
+    table: string;
+    description?: string;
+    records: CatalogRecord[];
+}
+interface ClassifyMatch {
+    table: string;
+    id: string;
+}
+/** Extract the first ```json fenced block (or a bare array) and parse it. */
+declare function parseMatches(raw: string, catalog: CatalogEntity[]): ClassifyMatch[];
+/** An existing entity the extractor may reuse: its name + column names. */
+interface SchemaEntity {
+    table: string;
+    columns: string[];
+}
+/** A structured object the document represents, to create + link the file to. */
+interface ExtractedObject {
+    /** Target entity (snake_case). May be new — see {@link isNew}. */
+    entity: string;
+    /** True when {@link entity} should be created (it isn't in the schema yet). */
+    isNew: boolean;
+    /** Columns for a new entity (snake_case); ignored when reusing one. */
+    columns: string[];
+    /** Column → value for the row to create. */
+    values: Record<string, string>;
+    /** Short human label for the object. */
+    label: string;
+}
+/** Parse + sanitize the extractor's JSON. Caps at 3 objects; drops invalid ones. */
+declare function parseObjects(raw: string): ExtractedObject[];
+/**
+ * Ask the model to extract the structured objects a document represents, given
+ * the user's current schema. Reuses existing entities or proposes new ones.
+ * Best-effort; returns [] on any failure. The caller decides (by aggressiveness)
+ * whether to materialize them and gates new-entity creation.
+ */
+declare function extractObjects(client: LlmClient, text: string, name: string, existing: SchemaEntity[], temperature?: number): Promise<ExtractedObject[]>;
+/**
+ * Ask the model which catalog records the document relates to. Returns only
+ * matches that validate against the supplied catalog (no hallucinated ids).
+ */
+declare function classifyLinks(client: LlmClient, text: string, name: string, catalog: CatalogEntity[]): Promise<ClassifyMatch[]>;
+
+/**
+ * The context organizer. Given an ingested source (a `files` row's text), it
+ * sorts it into the user's OWN schema by default — summarizing it and linking
+ * it to the existing records it relates to — and creates a new knowledge
+ * object ONLY when nothing in the user's schema fits. Every action is an
+ * ordinary, user-editable row, and the result carries a plain-language
+ * {@link OrganizeResult.message} the caller can show ("…created a new note…
+ * you can change this anytime").
+ *
+ * AI-gated: with no {@link OrganizeOptions.client} (no key/auth configured),
+ * it is a no-op (`skipped: true`) and writes nothing.
+ */
+interface OrganizeOptions {
+    /** The `files` row id being organized. */
+    fileId: string;
+    /** Extracted text of the source. */
+    text: string;
+    /** Original file/source name. */
+    name: string;
+    /** The user's existing records the source may relate to. */
+    catalog: CatalogEntity[];
+    /** LLM client. `null` ⇒ AI disabled ⇒ no-op. */
+    client: LlmClient | null;
+    /**
+     * Junction table that records a (file → row) link. Must have columns
+     * `file_id`, `table_name`, `row_id`, `relevance`. Default `'file_links'`.
+     */
+    linkTable?: string;
+    /**
+     * Table to create a fallback knowledge object in when nothing fits. Must
+     * have `title` + `body` columns. Default `'notes'`.
+     */
+    fallbackTable?: string;
+    /** Create a fallback object when nothing was attached. Default `true`. */
+    createIfNecessary?: boolean;
+    /**
+     * Host-supplied linker: attach the file to an existing record and return
+     * `true` if a link was actually created. Defaults to inserting into
+     * {@link linkTable}. The GUI supplies junction-table linking here.
+     */
+    linkExisting?: (match: ClassifyMatch) => Promise<boolean>;
+    /**
+     * Host-supplied fallback creator: create a new knowledge object and return
+     * its `{ table, id }`, or `null` to skip creation. Defaults to inserting into
+     * {@link fallbackTable}.
+     */
+    createFallback?: (title: string, body: string) => Promise<{
+        table: string;
+        id: string;
+    } | null>;
+}
+interface OrganizedLink {
+    table: string;
+    id: string;
+}
+interface OrganizedCreation {
+    table: string;
+    id: string;
+    title: string;
+}
+interface OrganizeResult {
+    /** True when AI was disabled (no client) — nothing was written. */
+    skipped: boolean;
+    /** The 1–2 sentence description (empty when skipped). */
+    description: string;
+    /** Existing records the source was linked to. */
+    linked: OrganizedLink[];
+    /** New knowledge objects created because nothing fit. */
+    created: OrganizedCreation[];
+    /** Plain-language summary for the user (empty when skipped). */
+    message: string;
+}
+declare function organizeSource(db: Lattice, opts: OrganizeOptions): Promise<OrganizeResult>;
+
+/**
+ * Fetch a URL and extract readable text from it. For HTML, uses Mozilla
+ * Readability (the article-extraction algorithm) with a stripped-DOM fallback;
+ * for non-HTML text types, returns the raw text. SSRF-guarded. Network access
+ * is injectable (`opts.fetcher`) so callers/tests can stub it.
+ *
+ * This is the back-end crawler behind cloud references — record a URL with
+ * `referenceUrl`, then `crawlUrl` to fill `extracted_text` for the organizer.
+ */
+interface CrawlResult {
+    url: string;
+    title: string;
+    text: string;
+    excerpt: string;
+    mime: string;
+    byteLength: number;
+}
+interface CrawlOptions {
+    fetcher?: typeof fetch;
+    allowPrivate?: boolean;
+    maxBytes?: number;
+    timeoutMs?: number;
+    userAgent?: string;
+    /**
+     * Disable the Playwright JS-render fallback (used when the static HTML yields
+     * little text and Playwright is installed). Default false. The fallback
+     * degrades silently when Playwright or a browser is absent.
+     */
+    noJs?: boolean;
+}
+declare function crawlUrl(rawUrl: string, opts?: CrawlOptions): Promise<CrawlResult>;
+
+/**
+ * The enrich pass: when a knowledge object (e.g. a `notes` row the organizer
+ * created) has accumulated several linked sources but only a thin body, this
+ * synthesizes the sources into a single coherent body and updates the row — but
+ * only if the result is genuinely better than what's there. AI-gated: a no-op
+ * without an LLM client.
+ *
+ * It operates over the same generic link table the organizer writes
+ * (`file_links`: file_id, table_name, row_id), so it stays schema-agnostic.
+ */
+interface EnrichOptions {
+    client: LlmClient | null;
+    /** Table holding the knowledge objects to enrich. Default `'notes'`. */
+    knowledgeTable?: string;
+    /** Column on the knowledge object holding its prose body. Default `'body'`. */
+    bodyColumn?: string;
+    /** Generic (file → row) link table. Default `'file_links'`. */
+    linkTable?: string;
+    /** Table holding the source files. Default `'files'`. */
+    sourceTable?: string;
+    /** Column on the source table holding extracted text. Default `'extracted_text'`. */
+    sourceTextColumn?: string;
+    /** Minimum linked sources before an object is eligible. Default `2`. */
+    minSources?: number;
+    /** A body shorter than this many chars is considered "thin". Default `500`. */
+    thinBodyChars?: number;
+    /** Cap on objects enriched per pass. Default `40`. */
+    maxObjects?: number;
+}
+interface EnrichResult {
+    /** True when AI was disabled — nothing was examined or written. */
+    skipped: boolean;
+    /** Ids of knowledge objects whose body was rewritten. */
+    enriched: string[];
+    /** How many eligible objects were examined. */
+    examined: number;
+}
+declare function enrichKnowledge(db: Lattice, opts: EnrichOptions): Promise<EnrichResult>;
+
+interface VisionSenderInput {
+    media_type: string;
+    data: string;
+    prompt: string;
+    model: string;
+}
+interface VisionOptions {
+    model?: string;
+    prompt?: string;
+    /** Cap on the normalized JPEG size (bytes). Default ~1.4 MB. */
+    maxBytes?: number;
+    /** Injectable model call (test seam). Defaults to a real Anthropic vision call. */
+    sender?: (input: VisionSenderInput) => Promise<string>;
+}
+declare function describeImage(auth: ClaudeAuth, path: string, opts?: VisionOptions): Promise<string>;
+interface PdfSenderInput {
+    data: string;
+    prompt: string;
+    model: string;
+}
+interface PdfOptions {
+    model?: string;
+    prompt?: string;
+    /** Max PDF size sent to the model (bytes). Default 30 MB (API limit ~32 MB). */
+    maxBytes?: number;
+    /** Injectable model call (test seam). Defaults to a real Anthropic document call. */
+    sender?: (input: PdfSenderInput) => Promise<string>;
+}
+/**
+ * Read a PDF with Claude's native document support — works on text PDFs AND
+ * scanned/image-only PDFs (no text layer), which `markitdown` cannot extract.
+ * AI-gated; the model call is injectable for tests.
+ */
+declare function describePdf(auth: ClaudeAuth, path: string, opts?: PdfOptions): Promise<string>;
+
+export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DirectRegisterResult, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type ExtractedObject, type FilesRow, type Filter, type FilterOp, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, type InviteResponse, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, type ManyToManySource, type MarkdownTableColumn, type MemberSummary, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RedeemResponse, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RegisterResponse, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceMetadata, type SourceQueryOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TeamConnection, type TeamSummary, TeamsClient, TeamsHttpError, type TemplateRenderSpec, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, autoFtsColumns, autoUpdate, classifyLinks, configDir, contentHash, crawlUrl, createReadOnlyHeader, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, encrypt, enrichKnowledge, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, extractObjects, findLatticeRoot, fixSchemaConflicts, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateWriteEntryId, getActiveWorkspace, getDbCredential, getOrCreateMasterKey, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, manifestPath, markdownTable, migrateLatticeData, normalizeEntityFiles, openTargetLatticeForMigration, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, registerDirectViaPostgres, registerNativeEntities, registryPath, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, rootConfigDir, saveDbCredential, saveDbCredentialForTeam, setActiveWorkspace, slugify, summarizeText, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };

package/dist/index.d.ts

@@ -746,6 +746,16 @@ interface LatticeOptions {
      * backends, or pre-opened connections.
      */
     adapter?: StorageAdapter;
+    /**
+     * When true, `render()` skips both the full-table read and the file write
+     * for tables registered without a `render` spec — those compile to a no-op
+     * that would only emit an empty `.schema-only/<table>.md`. Off by default,
+     * preserving the original behavior (the table is still scanned and an empty
+     * schema-only file written). Enable this to avoid reading large tables off
+     * the wire just to produce empty files. Tables with an explicit `render`
+     * (or `outputFile`) are unaffected.
+     */
+    renderSkipsEmpty?: boolean;
 }
 /**
  * Retention policy for the change log.
@@ -1720,6 +1730,12 @@ declare class Lattice {
     private _registerTable;
     defineMulti(name: string, def: MultiTableDefinition): this;
     defineEntityContext(table: string, def: EntityContextDefinition): this;
+    /**
+     * Register or REPLACE an entity context (overwrites instead of throwing on a
+     * redefine — see {@link SchemaManager.redefineEntityContext}). Used to refresh
+     * a canonical context at runtime after a related schema change.
+     */
+    redefineEntityContext(table: string, def: EntityContextDefinition): this;
     /**
      * All entity contexts currently registered on this Lattice — both those
      * declared in `lattice.config.yml` and those added programmatically via
@@ -4080,4 +4096,293 @@ declare function isPostgresUrl(url: string): boolean;
  */
 declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;
 
-export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CONFIG_SUBDIR, type ChangeEntry, type ChangelogOptions, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DirectRegisterResult, type EmbeddingsConfig, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type FilesRow, type Filter, type FilterOp, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, type InviteResponse, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type ManyToManySource, type MarkdownTableColumn, type MemberSummary, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type OrderBySpec, type ParseError, type ParseResult, type ParsedConfig, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RedeemResponse, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RegisterResponse, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, SQLiteAdapter, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceMetadata, type SourceQueryOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TeamConnection, type TeamSummary, TeamsClient, TeamsHttpError, type TemplateRenderSpec, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, autoFtsColumns, autoUpdate, configDir, contentHash, createReadOnlyHeader, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, encrypt, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, findLatticeRoot, fixSchemaConflicts, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateWriteEntryId, getActiveWorkspace, getDbCredential, getOrCreateMasterKey, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, manifestPath, markdownTable, migrateLatticeData, normalizeEntityFiles, openTargetLatticeForMigration, parseConfigFile, parseConfigString, parseMarkdownEntries, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, registerDirectViaPostgres, registerNativeEntities, registryPath, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, rootConfigDir, saveDbCredential, saveDbCredentialForTeam, setActiveWorkspace, slugify, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };
+/** A content block in the Anthropic message format used here. */
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+interface LlmMessage {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+interface ToolUse {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface TurnResult {
+    stopReason: string;
+    text: string;
+    toolUses: ToolUse[];
+}
+/** Minimal tool shape passed to the model (decoupled from the GUI tool catalog). */
+interface LlmTool {
+    name: string;
+    description?: string;
+    input_schema: unknown;
+}
+interface TurnParams {
+    model: string;
+    system: string;
+    messages: LlmMessage[];
+    tools: LlmTool[];
+    /** Called with each streamed text delta. */
+    onText: (delta: string) => void;
+}
+/** The slice of the Anthropic client the AI features depend on. */
+interface LlmClient {
+    runTurn(params: TurnParams): Promise<TurnResult>;
+}
+/**
+ * How to authenticate to Anthropic: a raw API key, or an OAuth Bearer token
+ * (from a connected Claude subscription). `betaHeader` carries an optional
+ * `anthropic-beta` value (sourced from env for the OAuth path — not hardcoded).
+ */
+interface ClaudeAuth {
+    apiKey?: string | undefined;
+    authToken?: string | undefined;
+    betaHeader?: string | undefined;
+}
+
+/** Generate a 1-2 sentence description of a document's text. */
+declare function summarizeText(client: LlmClient, text: string, name: string): Promise<string>;
+/** A candidate record an ingested file might relate to. */
+interface CatalogRecord {
+    id: string;
+    label: string;
+}
+interface CatalogEntity {
+    table: string;
+    description?: string;
+    records: CatalogRecord[];
+}
+interface ClassifyMatch {
+    table: string;
+    id: string;
+}
+/** Extract the first ```json fenced block (or a bare array) and parse it. */
+declare function parseMatches(raw: string, catalog: CatalogEntity[]): ClassifyMatch[];
+/** An existing entity the extractor may reuse: its name + column names. */
+interface SchemaEntity {
+    table: string;
+    columns: string[];
+}
+/** A structured object the document represents, to create + link the file to. */
+interface ExtractedObject {
+    /** Target entity (snake_case). May be new — see {@link isNew}. */
+    entity: string;
+    /** True when {@link entity} should be created (it isn't in the schema yet). */
+    isNew: boolean;
+    /** Columns for a new entity (snake_case); ignored when reusing one. */
+    columns: string[];
+    /** Column → value for the row to create. */
+    values: Record<string, string>;
+    /** Short human label for the object. */
+    label: string;
+}
+/** Parse + sanitize the extractor's JSON. Caps at 3 objects; drops invalid ones. */
+declare function parseObjects(raw: string): ExtractedObject[];
+/**
+ * Ask the model to extract the structured objects a document represents, given
+ * the user's current schema. Reuses existing entities or proposes new ones.
+ * Best-effort; returns [] on any failure. The caller decides (by aggressiveness)
+ * whether to materialize them and gates new-entity creation.
+ */
+declare function extractObjects(client: LlmClient, text: string, name: string, existing: SchemaEntity[], temperature?: number): Promise<ExtractedObject[]>;
+/**
+ * Ask the model which catalog records the document relates to. Returns only
+ * matches that validate against the supplied catalog (no hallucinated ids).
+ */
+declare function classifyLinks(client: LlmClient, text: string, name: string, catalog: CatalogEntity[]): Promise<ClassifyMatch[]>;
+
+/**
+ * The context organizer. Given an ingested source (a `files` row's text), it
+ * sorts it into the user's OWN schema by default — summarizing it and linking
+ * it to the existing records it relates to — and creates a new knowledge
+ * object ONLY when nothing in the user's schema fits. Every action is an
+ * ordinary, user-editable row, and the result carries a plain-language
+ * {@link OrganizeResult.message} the caller can show ("…created a new note…
+ * you can change this anytime").
+ *
+ * AI-gated: with no {@link OrganizeOptions.client} (no key/auth configured),
+ * it is a no-op (`skipped: true`) and writes nothing.
+ */
+interface OrganizeOptions {
+    /** The `files` row id being organized. */
+    fileId: string;
+    /** Extracted text of the source. */
+    text: string;
+    /** Original file/source name. */
+    name: string;
+    /** The user's existing records the source may relate to. */
+    catalog: CatalogEntity[];
+    /** LLM client. `null` ⇒ AI disabled ⇒ no-op. */
+    client: LlmClient | null;
+    /**
+     * Junction table that records a (file → row) link. Must have columns
+     * `file_id`, `table_name`, `row_id`, `relevance`. Default `'file_links'`.
+     */
+    linkTable?: string;
+    /**
+     * Table to create a fallback knowledge object in when nothing fits. Must
+     * have `title` + `body` columns. Default `'notes'`.
+     */
+    fallbackTable?: string;
+    /** Create a fallback object when nothing was attached. Default `true`. */
+    createIfNecessary?: boolean;
+    /**
+     * Host-supplied linker: attach the file to an existing record and return
+     * `true` if a link was actually created. Defaults to inserting into
+     * {@link linkTable}. The GUI supplies junction-table linking here.
+     */
+    linkExisting?: (match: ClassifyMatch) => Promise<boolean>;
+    /**
+     * Host-supplied fallback creator: create a new knowledge object and return
+     * its `{ table, id }`, or `null` to skip creation. Defaults to inserting into
+     * {@link fallbackTable}.
+     */
+    createFallback?: (title: string, body: string) => Promise<{
+        table: string;
+        id: string;
+    } | null>;
+}
+interface OrganizedLink {
+    table: string;
+    id: string;
+}
+interface OrganizedCreation {
+    table: string;
+    id: string;
+    title: string;
+}
+interface OrganizeResult {
+    /** True when AI was disabled (no client) — nothing was written. */
+    skipped: boolean;
+    /** The 1–2 sentence description (empty when skipped). */
+    description: string;
+    /** Existing records the source was linked to. */
+    linked: OrganizedLink[];
+    /** New knowledge objects created because nothing fit. */
+    created: OrganizedCreation[];
+    /** Plain-language summary for the user (empty when skipped). */
+    message: string;
+}
+declare function organizeSource(db: Lattice, opts: OrganizeOptions): Promise<OrganizeResult>;
+
+/**
+ * Fetch a URL and extract readable text from it. For HTML, uses Mozilla
+ * Readability (the article-extraction algorithm) with a stripped-DOM fallback;
+ * for non-HTML text types, returns the raw text. SSRF-guarded. Network access
+ * is injectable (`opts.fetcher`) so callers/tests can stub it.
+ *
+ * This is the back-end crawler behind cloud references — record a URL with
+ * `referenceUrl`, then `crawlUrl` to fill `extracted_text` for the organizer.
+ */
+interface CrawlResult {
+    url: string;
+    title: string;
+    text: string;
+    excerpt: string;
+    mime: string;
+    byteLength: number;
+}
+interface CrawlOptions {
+    fetcher?: typeof fetch;
+    allowPrivate?: boolean;
+    maxBytes?: number;
+    timeoutMs?: number;
+    userAgent?: string;
+    /**
+     * Disable the Playwright JS-render fallback (used when the static HTML yields
+     * little text and Playwright is installed). Default false. The fallback
+     * degrades silently when Playwright or a browser is absent.
+     */
+    noJs?: boolean;
+}
+declare function crawlUrl(rawUrl: string, opts?: CrawlOptions): Promise<CrawlResult>;
+
+/**
+ * The enrich pass: when a knowledge object (e.g. a `notes` row the organizer
+ * created) has accumulated several linked sources but only a thin body, this
+ * synthesizes the sources into a single coherent body and updates the row — but
+ * only if the result is genuinely better than what's there. AI-gated: a no-op
+ * without an LLM client.
+ *
+ * It operates over the same generic link table the organizer writes
+ * (`file_links`: file_id, table_name, row_id), so it stays schema-agnostic.
+ */
+interface EnrichOptions {
+    client: LlmClient | null;
+    /** Table holding the knowledge objects to enrich. Default `'notes'`. */
+    knowledgeTable?: string;
+    /** Column on the knowledge object holding its prose body. Default `'body'`. */
+    bodyColumn?: string;
+    /** Generic (file → row) link table. Default `'file_links'`. */
+    linkTable?: string;
+    /** Table holding the source files. Default `'files'`. */
+    sourceTable?: string;
+    /** Column on the source table holding extracted text. Default `'extracted_text'`. */
+    sourceTextColumn?: string;
+    /** Minimum linked sources before an object is eligible. Default `2`. */
+    minSources?: number;
+    /** A body shorter than this many chars is considered "thin". Default `500`. */
+    thinBodyChars?: number;
+    /** Cap on objects enriched per pass. Default `40`. */
+    maxObjects?: number;
+}
+interface EnrichResult {
+    /** True when AI was disabled — nothing was examined or written. */
+    skipped: boolean;
+    /** Ids of knowledge objects whose body was rewritten. */
+    enriched: string[];
+    /** How many eligible objects were examined. */
+    examined: number;
+}
+declare function enrichKnowledge(db: Lattice, opts: EnrichOptions): Promise<EnrichResult>;
+
+interface VisionSenderInput {
+    media_type: string;
+    data: string;
+    prompt: string;
+    model: string;
+}
+interface VisionOptions {
+    model?: string;
+    prompt?: string;
+    /** Cap on the normalized JPEG size (bytes). Default ~1.4 MB. */
+    maxBytes?: number;
+    /** Injectable model call (test seam). Defaults to a real Anthropic vision call. */
+    sender?: (input: VisionSenderInput) => Promise<string>;
+}
+declare function describeImage(auth: ClaudeAuth, path: string, opts?: VisionOptions): Promise<string>;
+interface PdfSenderInput {
+    data: string;
+    prompt: string;
+    model: string;
+}
+interface PdfOptions {
+    model?: string;
+    prompt?: string;
+    /** Max PDF size sent to the model (bytes). Default 30 MB (API limit ~32 MB). */
+    maxBytes?: number;
+    /** Injectable model call (test seam). Defaults to a real Anthropic document call. */
+    sender?: (input: PdfSenderInput) => Promise<string>;
+}
+/**
+ * Read a PDF with Claude's native document support — works on text PDFs AND
+ * scanned/image-only PDFs (no text layer), which `markitdown` cannot extract.
+ * AI-gated; the model call is injectable for tests.
+ */
+declare function describePdf(auth: ClaudeAuth, path: string, opts?: PdfOptions): Promise<string>;
+
+export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DirectRegisterResult, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type ExtractedObject, type FilesRow, type Filter, type FilterOp, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, type InviteResponse, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, type ManyToManySource, type MarkdownTableColumn, type MemberSummary, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RedeemResponse, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RegisterResponse, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceMetadata, type SourceQueryOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TeamConnection, type TeamSummary, TeamsClient, TeamsHttpError, type TemplateRenderSpec, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, autoFtsColumns, autoUpdate, classifyLinks, configDir, contentHash, crawlUrl, createReadOnlyHeader, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, encrypt, enrichKnowledge, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, extractObjects, findLatticeRoot, fixSchemaConflicts, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateWriteEntryId, getActiveWorkspace, getDbCredential, getOrCreateMasterKey, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, manifestPath, markdownTable, migrateLatticeData, normalizeEntityFiles, openTargetLatticeForMigration, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, registerDirectViaPostgres, registerNativeEntities, registryPath, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, rootConfigDir, saveDbCredential, saveDbCredentialForTeam, setActiveWorkspace, slugify, summarizeText, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };