latticesql 4.1.0 → 4.2.0

package/dist/index.d.cts

@@ -1468,6 +1468,16 @@ interface EmbeddingsConfig {
      * Lattice never calls a model itself.
      */
     modelId?: string;
+    /**
+     * Optional opt-in cap on the no-index fallback scan. When the in-process cosine
+     * scan (used only when no native vector index exists for a table) would read
+     * more than this many stored chunk vectors, `searchByEmbedding` throws
+     * `EmbeddingScanTooLargeError` instead of loading them all into memory. OFF by
+     * default (unbounded scan — historical behavior). Lattice never silently
+     * truncates the scan: a partial cosine scan returns incomplete, wrong results,
+     * so it fails loudly and tells you to add a pgvector index or raise the cap.
+     */
+    maxScanChunks?: number;
 }
 /**
  * Options for `Lattice.search()`.
@@ -2519,6 +2529,18 @@ declare class EmbeddingDimensionMismatchError extends Error {
     readonly found: number;
     constructor(table: string, expected: number, found: number);
 }
+/**
+ * Thrown by `searchByEmbedding` when the no-index fallback cosine scan would read
+ * more stored chunk vectors than the configured `maxScanChunks`. The scan is
+ * never silently truncated (that would return incomplete, wrong results) — it
+ * fails loudly so the caller adds a native vector index or raises the cap.
+ */
+declare class EmbeddingScanTooLargeError extends Error {
+    readonly table: string;
+    readonly found: number;
+    readonly limit: number;
+    constructor(table: string, found: number, limit: number);
+}
 /**
  * Search rows by semantic similarity. Uses a native vector index (pgvector) when
  * one exists for the table; otherwise an in-process cosine scan over the stored
@@ -6691,6 +6713,16 @@ interface GuiServerHandle {
     port: number;
     url: string;
     close: () => Promise<void>;
+    /**
+     * Resolves when the active workspace's background owner-side convergence (cloud
+     * RLS / member grants, incl. the `_lattice_gui_meta` read-grant) has settled.
+     * Opening a cloud workspace returns immediately and convergence runs unawaited
+     * (see {@link ActiveDb.converged}); a test that acts AS A MEMBER right after the
+     * owner opens MUST await this, or the member render can race the grant and fail
+     * with "permission denied for table _lattice_gui_meta". The GUI never needs it;
+     * resolves immediately for a non-cloud / virgin workspace.
+     */
+    whenConverged: () => Promise<void>;
 }
 declare function startGuiServer(options: StartGuiServerOptions): Promise<GuiServerHandle>;
 
@@ -6758,4 +6790,331 @@ declare class FileSourceKeyStore implements SourceKeyStore {
     private encodeFile;
 }
 
-export { ALL_PROVENANCE_FIELDS, type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type AggregateFunction, type AggregateHaving, type AggregateOptions, type AggregateResult, type AggregateSpec, type ApplyWriteResult, type AudienceRowCtx, type AuditEvent, type AutoUpdateResult, type BacklinkSignal, type BelongsToRelation, type BelongsToSource, type BenchmarkOptions, type BenchmarkReport, type BenchmarkScale, type BlobMetadata, BoundedReadError, type BuiltinTemplateName, CLOUD_SETTING_SYSTEM_PROMPT, CLOUD_SETTING_WORKSPACE_LOGO, CLOUD_SETTING_WORKSPACE_LOGO_ETAG, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ChunkedMigrationOptions, type ChunkedMigrationResult, type ChunkerFn, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CloudS3Secret, ComputedColumnCycleError, type ComputedColumnSpec, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSignal, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_MAX_NODES, DEFAULT_TYPE_ALIASES, type DiagnoseOptions, type DiscoveredTable, EMBEDDINGS_TABLE, EmbeddingDimensionMismatchError, type EmbeddingRefreshResult, 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 EvalQuery, type EvalRegression, type ExtensionAvailability, type ExtractEdgesSpec, type ExtractedObject, FileSourceKeyStore, type FileSourceKeyStoreOptions, type FilesRow, type Filter, type FilterAnd, type FilterExpr, type FilterOp, type FilterOr, FoldCache, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type GraphBoostOptions, type GraphBoostResult, type GraphEdge, type GraphNode, type GraphTraversalResult, type GuiServerHandle, type HasManyRelation, type HasManySource, type HealthIssueKind, type HealthSeverity, type HybridScoreBreakdown, type HybridSearchOptions, type HybridSearchResult, InMemorySourceKeyStore, InMemoryStateStore, type InitOptions, LEGACY_MEMBER_GROUP, LOCAL_DB_RELPATH, type LatencyStats, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, MAX_TRAVERSAL_DEPTH, type ManyToManySource, type MarkdownTableColumn, type MaterializedRollupSpec, type MigrateResult, type Migration, type MigrationCheckpoint, type MigrationOptions, type MigrationProgress, type MigrationResult, type MigrationStatus, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type Observation, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PerQueryEval, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, ProgressThrottle, type ProvenanceConfig, type ProvenanceField, ProvenanceImmutableError, type QueryOptions, type QueryPageOptions, type QueryPageResult, type QueryProjection, READ_ONLY_HEADER, ROOT_DIRNAME, type RankingOptions, type ReadOnlyHeaderOptions, type RecencySignal, type ReconcileOptions, type ReconcileResult, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RefreshEmbeddingsOptions, type Relation, type RelevanceLabel, type RemoteBlobStore, type RenderHooks, type RenderOptions, type RenderProgress, type RenderProgressCallback, type RenderProgressKind, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type RerankCandidate, type RerankScore, type RerankerFn, type ResolveOptions, type RetrievalEvalOptions, type RetrievalEvalSummary, type RetrievalHealthIssue, type RetrievalHealthReport, type RetrievalHealthSpec, type RetrievalSlo, type Retriever, type RetryOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type RewardSignal, type RollupFunction, type Row, type RowVisibilityDefault, type S3Config, type S3StoreConfig, S3UnavailableError, S3_SECRET_TABLE, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SemanticChunkerOptions, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SloViolation, type SourceHandle, type SourceKeyStore, type SourceMetadata, type SourceQueryOptions, SourceShreddedError, type StartGuiServerOptions, type StopFn, type StorageAdapter, type SyncResult, TRUST_COLUMNS, type TableDefinition, type TableHealth, type TablePolicy, type TemplateRenderSpec, type TextChunk, type TraversalDirection, type TraversalNode, type TraversalOptions, type TrustConfig, type TrustState, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VectorHit, type Viewer, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, activeWorkspaceLabel, addEdge, addEdges, addWorkspace, adoptNativeEntities, allComputedDeps, analyticsEnabled, applyChunkedMigration, applyReranker, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, audiencePredicate, audienceViewSql, autoFtsColumns, autoUpdate, backfillOwnership, backlinkBoost, benchmarkRetrieval, buildVectorIndex, canManageRoles, checkSlos, chunkText, classifyLinks, cloudRlsInstalled, computeColumns, computedColumnDdl, computedColumnOrder, concatRowText, configDir, contentHash, cosineSimilarity, crawlUrl, createReadOnlyHeader, createS3Store, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, detectRetrievalRegressions, diagnoseRetrieval, discoverCloudTables, dropVectorIndex, enableAudienceView, enableChangelogRls, enableRlsForTable, encrypt, enrichKnowledge, ensureCheckpointTable, ensureEdgesTable, ensureEmbeddingsTable, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, evaluateRetrieval, extractEdgesFromColumn, extractObjects, filePresignSql, findLatticeRoot, fixSchemaConflicts, foldEntity, formatHealthReport, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateMemberPassword, generateWriteEntryId, getActiveWorkspace, getCloudSetting, getDbCredential, getMigrationCheckpoint, getOrCreateMasterKey, getTablePolicy, getWorkspace, grantPresignerToMemberGroup, graphAdjacencyBoost, hasFilePresigner, hasFtsIndex, hasVectorIndex, hashFile, hybridSearch, importLegacyUserConfig, installCloudRls, installCloudSettings, installFilePresigner, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isRetryableDbError, isRowAudience, latencyStats, listDbCredentials, listMigrationCheckpoints, listNativeBindings, listTokens, listWorkspaces, loadColumnPolicy, manifestPath, markdownTable, memberGroupFor, memberRoleName, migrateLatticeData, neighbors, observationVisible, observationsFromChange, openTargetLatticeForMigration, openUnderSource, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, percentile, probeCloud, provenanceColumns, providerForUrl, provisionMemberRole, rankingBoost, readIdentity, readManifest, readPreferences, readRegistry, readToken, recencyBoost, referenceLocalFile, referenceUrl, refreshEmbeddings, regenerateAudienceViewFromDb, registerNativeEntities, registryPath, removeEdge, removeEmbedding, resolveActiveS3Config, resolveLatticeRoot, resolveProvenanceFields, resolveSource, resolveTrustDefault, resolveWorkspacePaths, resumeMigration, revertMigration, revokeMemberRole, rewardBoost, rollupColumnDdl, rootConfigDir, s3Key, saveDbCredential, saveDbCredentialForTeam, sealUnderSource, searchByEmbedding, searchVectorIndex, secureCloud, seedColumnPolicyFromYaml, semanticChunker, setActiveWorkspace, setCloudS3Secret, setCloudSetting, setColumnAudience, setRowVisibility, setTableDefaultVisibility, setTableNeverShare, shredSource, slugify, startGuiServer, storeEmbedding, summarizeText, tableNeedsAudienceView, toSafeDirName, traverse, truncate, validateEntryId, vectorIndexAvailable, vectorIndexName, withRetry, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };
+/**
+ * Types for the structured-source importer: turning a parsed JSON source into a
+ * proposed Lattice schema (entities, dimensions, linkages) that the user reviews
+ * before anything is written. The inference step ({@link inferSchema}) returns a
+ * {@link ProposedSchema}; the user approves (optionally trims) it; the
+ * materialize step creates the tables, rows, and junctions from it.
+ *
+ * Derived / computed values are intentionally NOT modeled here — they belong to a
+ * later dashboard→Lattice write-back feature, not source ingestion.
+ */
+/** Canonical column types we infer from JSON values. Maps onto Lattice field types. */
+type InferredType = 'integer' | 'real' | 'boolean' | 'date' | 'datetime' | 'text';
+interface InferredColumn {
+    /** Normalized snake_case column name. */
+    name: string;
+    /** Original JSON key (may differ from {@link name}). */
+    sourceKey: string;
+    type: InferredType;
+}
+/**
+ * A relationship inferred between two entities (or an entity and a normalized
+ * dimension). Reported with match counts + a confidence so the user can judge it
+ * before approving — links are never applied silently.
+ */
+interface InferredLinkage {
+    kind: 'many-to-many' | 'many-to-one' | 'dimension';
+    /** Entity table the reference lives on (normalized name). */
+    fromEntity: string;
+    /** Source JSON key on the entity holding the reference value(s). */
+    fromField: string;
+    /** Target entity/dimension table (normalized name). */
+    toEntity: string;
+    /** Natural-key column on the target used to resolve a reference value. */
+    toKey: string;
+    /** Junction table name (many-to-many + dimension links). */
+    junction?: string;
+    /** Distinct reference values that resolve to a target row. */
+    matched: number;
+    /** Distinct reference values that do NOT resolve (reported, never fatal). */
+    unresolved: number;
+    /** 0..1 — share of distinct reference values that resolved. */
+    confidence: number;
+}
+interface InferredEntity {
+    /** Normalized snake_case table name. */
+    name: string;
+    /** Original top-level JSON key. */
+    sourceKey: string;
+    /** Scalar columns only — array/linkage fields and dimension-extracted columns are excluded. */
+    columns: InferredColumn[];
+    /** Natural-key column name (normalized), or null = keyless (surrogate id + content-hash dedup). */
+    naturalKey: string | null;
+    /** Original JSON key for the natural key (un-normalized), or null. Used to read source records. */
+    naturalKeySource: string | null;
+    rowCount: number;
+    /** True when reconstructed from `<key>` (array of arrays) + `<key>Cols` (column dictionary). */
+    columnar: boolean;
+}
+interface InferredDimension {
+    /** Dimension table name (e.g. `industry`). */
+    name: string;
+    /** Source column key the values come from. */
+    sourceField: string;
+    /** Entities that contribute values to this dimension. */
+    fromEntities: string[];
+    distinctValues: number;
+}
+interface ProposedSchema {
+    entities: InferredEntity[];
+    dimensions: InferredDimension[];
+    linkages: InferredLinkage[];
+    /** Top-level keys not imported (derived rollups, meta, scalars, column dictionaries). */
+    skipped: {
+        key: string;
+        reason: string;
+    }[];
+}
+/**
+ * An entity recognized as a reconstructable projection of another (a "master")
+ * table — its rows are contained in the master, filtered by one column. It is
+ * materialized as a read-only DB VIEW (`master WHERE filterColumn = filterValue`)
+ * rather than a duplicate table.
+ */
+interface DetectedView {
+    /** The view's name (normalized) — the original tab/entity. */
+    name: string;
+    /** The master entity (normalized) this view projects from. */
+    master: string;
+    /** Master column the view filters on (normalized). */
+    filterColumn: string;
+    /** The value `filterColumn` equals for this view. */
+    filterValue: string;
+    /** Number of master rows that matched (the view's row count). */
+    matchedRows: number;
+}
+
+/**
+ * Re-extract the raw source records for an entity from the parsed JSON — handling
+ * the columnar case (`<key>` array-of-arrays + `<key>Cols` dictionary). Shared by
+ * the inference step and the materialize step so both read records identically.
+ */
+declare function sourceRecords(data: Record<string, unknown>, entity: {
+    sourceKey: string;
+    columnar: boolean;
+}): Record<string, unknown>[];
+/** Lower-snake-case a JSON key into a safe SQL identifier. */
+declare function normalizeName(key: string): string;
+/** Infer a column type from a set of values (nulls ignored). Defaults to text. */
+declare function inferFieldType(values: unknown[]): InferredType;
+interface InferOptions {
+    /** Override the inferred entity → table name (sourceKey → name). */
+    rename?: Record<string, string>;
+}
+declare function inferSchema(data: Record<string, unknown>, opts?: InferOptions): ProposedSchema;
+
+/**
+ * Materialize an approved {@link ProposedSchema} into a Lattice workspace: create
+ * the entity + dimension tables and the junctions, then load the rows (deduped)
+ * and the links. Lattice becomes the system of record — the schema is persisted
+ * to the workspace config so it survives a restart.
+ *
+ * Rows go through {@link Lattice.seed} (upsert by natural/content key → dedup +
+ * idempotent re-apply). Junctions are written directly so the link column names
+ * are fully controlled (`<entity>_id`).
+ */
+interface MaterializeCtx {
+    db: Lattice;
+    /** Workspace config path. When set, the schema is persisted here (canonical). */
+    configPath?: string | null;
+}
+/**
+ * What to materialize:
+ * - `schema`   — table structures + the deduped dimension values (the taxonomy /
+ *   "dictionary") + views. No entity rows, no links.
+ * - `contents` — the entity rows + their links, into tables that already exist
+ *   (created idempotently if missing). No dimension values, no views.
+ * - `both`     — schema + contents (the default).
+ */
+type ImportMode = 'schema' | 'contents' | 'both';
+/** A live step in the import pipeline, for streaming progress to the UI. */
+interface ImportProgress {
+    phase: 'parse' | 'infer' | 'detect' | 'entities' | 'dimensions' | 'links' | 'views' | 'done';
+    message: string;
+    table?: string;
+    count?: number;
+}
+interface MaterializeOptions {
+    /** Which parts to materialize (default `both`). */
+    mode?: ImportMode;
+    /**
+     * Called as each step completes — drives the live pipeline view. May return a
+     * promise; it is awaited, so a streaming caller can yield to the event loop
+     * (flushing the socket) between steps. Without that yield, a synchronous DB
+     * (SQLite) runs the whole import in one tick and the progress batches.
+     */
+    onProgress?: (p: ImportProgress) => void | Promise<void>;
+    /**
+     * Point-in-time snapshot date (ISO `YYYY-MM-DD`). When set, every entity + link
+     * row is stamped with `as_of` and the row identity includes it, so re-importing
+     * the same model at a new date APPENDS a dated snapshot (the prior one is kept)
+     * and links resolve within each snapshot. Dimensions (the shared taxonomy) are
+     * not dated. Omitted ⇒ the import is undated (re-import upserts in place).
+     */
+    asOf?: string | null;
+    /**
+     * Per-row snapshot date: the (normalized) name of a column whose value dates
+     * each row individually, so one file can carry many periods. When set, each
+     * row's `as_of` is read from this column (parsed per row), falling back to
+     * {@link asOf} when a row's value isn't a date; applied to every entity that
+     * has a column of this name. Identity + link resolution fold in the per-row
+     * date exactly as the file-level {@link asOf} does.
+     */
+    asOfColumn?: string | null;
+}
+interface MaterializeResult {
+    mode: ImportMode;
+    /** The file-level snapshot date stamped on the rows, or null. */
+    asOf: string | null;
+    /** The per-row date column used (each row dated from it), or null. */
+    asOfColumn: string | null;
+    tablesCreated: string[];
+    rowsByTable: Record<string, number>;
+    links: {
+        junction: string;
+        created: number;
+        unresolved: number;
+    }[];
+    /** Read-only views created for detected projections (master filtered by a column). */
+    views: {
+        name: string;
+        master: string;
+        rows: number;
+    }[];
+}
+declare function materializeImport(ctx: MaterializeCtx, data: Record<string, unknown>, plan: ProposedSchema, views?: DetectedView[], opts?: MaterializeOptions): Promise<MaterializeResult>;
+
+/**
+ * "As of" (snapshot date) detection for an import. The date drives how dated
+ * snapshots are kept, so detection is deliberately a *suggestion* layer: many
+ * signals each produce a ranked {@link AsOfCandidate} with evidence, the best is
+ * prefilled, and the user confirms or overrides. Worst case (no signal) is a
+ * blank field — never a silent wrong guess.
+ *
+ * Signals, strongest first:
+ *   - in-content phrase ("as of <date>", "period ended <date>") — the document says it
+ *   - in-content bare date (a date in the title/preamble or extracted text)
+ *   - file name date ("… 3.31.26.xlsx")
+ * Each is file-type-agnostic: a caller feeds text snippets (Excel preamble, JSON
+ * meta, extracted PDF text, …) + the file name, and the scanner does the rest.
+ */
+interface AsOfCandidate {
+    /** ISO `YYYY-MM-DD`. */
+    date: string;
+    /** Where it came from (for the UI + ranking). */
+    source: 'content' | 'filename' | 'column' | 'metadata' | 'llm';
+    /** 0..1 — higher wins. */
+    confidence: number;
+    /** Human-readable justification, shown next to the prefilled field. */
+    evidence: string;
+}
+/**
+ * Parse a single cell/field value into an ISO date, or null. Handles a `Date`
+ * (exceljs hands back `Date` objects for date-typed cells) and date-bearing
+ * strings ("2026-03-31", "3/31/26", "March 31, 2026"). Used to read a per-row
+ * "as of" column. A bare number is ignored — an Excel serial is already a `Date`
+ * by the time we see it, and a loose number is far more likely an amount.
+ */
+declare function parseCellDate(value: unknown): string | null;
+interface AsOfInputs {
+    fileName?: string;
+    /** Text snippets to scan, each with a label (e.g. "title", "extracted text"). */
+    texts?: {
+        label: string;
+        text: string;
+    }[];
+}
+/** Gather + rank as-of candidates from all inputs (best first, deduped by date). */
+declare function detectAsOfCandidates(inputs: AsOfInputs): AsOfCandidate[];
+/** Convenience: the single best-guess date from a file name, or null. */
+declare function detectAsOf(fileName: string): string | null;
+
+/**
+ * Detect a per-row "as of" DATE COLUMN — so one file can carry many periods
+ * (each row dated by its own column value) instead of a single file-level
+ * snapshot date. Like {@link detectAsOfCandidates}, this is a *suggestion* layer:
+ * ranked candidates with evidence; the user confirms or declines. Picking one
+ * makes the import stamp each row's `as_of` from that column (see
+ * `materializeImport`'s `asOfColumn` option) rather than one date for the file.
+ */
+
+interface AsOfColumnCandidate {
+    /** Entity (table) the column lives on. */
+    entity: string;
+    /** Normalized column name (matches an entity's {@link InferredColumn} `name`). */
+    column: string;
+    /** 0..1 — higher wins. */
+    confidence: number;
+    /** Distinct dates seen (>1 ⇒ genuinely multiple periods in one file). */
+    distinctDates: number;
+    /** Human-readable justification, shown next to the option. */
+    evidence: string;
+}
+declare function detectAsOfColumns(data: Record<string, unknown>, plan: ProposedSchema): AsOfColumnCandidate[];
+
+/**
+ * Match an inferred import schema against the tables already in a workspace, so
+ * a re-uploaded file is recognized as a NEW PERIOD of a document already
+ * imported — not a brand-new set of tables. Each inferred entity is fingerprinted
+ * by its column-name set and matched to the best existing table by containment
+ * (robust to added columns + renames of a few columns). When enough of the upload
+ * maps onto existing tables, it's a "known document": the importer can stamp it
+ * as a dated snapshot into those tables instead of creating duplicates.
+ *
+ * Pure + dependency-free (takes a plain list of existing tables, not a `Lattice`)
+ * so it's unit-testable and reusable from any door (import panel + assistant).
+ */
+
+interface ExistingTable {
+    name: string;
+    columns: string[];
+}
+interface EntityMatch {
+    /** Inferred entity name (from the new upload). */
+    from: string;
+    /** Existing table it matches. */
+    to: string;
+    /** 0..1 — share of the inferred entity's columns present in the existing table. */
+    overlap: number;
+}
+interface SchemaMatch {
+    /** Per-entity matches above the threshold (best existing table for each). */
+    matches: EntityMatch[];
+    /** Rename map (inferred name → existing table name) for names that differ. */
+    rename: Record<string, string>;
+    matchedCount: number;
+    totalEntities: number;
+    /**
+     * True when enough of the upload maps onto existing tables to treat it as a
+     * re-import of a document already in the workspace (i.e. a new dated snapshot).
+     */
+    isKnownDocument: boolean;
+}
+/**
+ * Match the inferred {@link ProposedSchema} against the workspace's existing
+ * tables. `existing` should already exclude native/system tables (the caller has
+ * the registry); junctions/dimensions are harmless — their tiny signatures won't
+ * reach the threshold against a real data entity.
+ */
+declare function matchSchemaToExisting(existing: ExistingTable[], plan: ProposedSchema): SchemaMatch;
+/**
+ * Apply a {@link SchemaMatch} rename map to a plan + its views, so materialize
+ * writes into the matched existing tables. Names absent from the map pass through
+ * unchanged (dimensions, unmatched entities). Linkage `toEntity` may be a
+ * dimension; renaming only hits names in the map, so dimensions are untouched.
+ */
+declare function renameEntities(plan: ProposedSchema, views: DetectedView[], rename: Record<string, string>): {
+    plan: ProposedSchema;
+    views: DetectedView[];
+};
+
+declare function excelToRecords(absPath: string): Promise<Record<string, unknown[]>>;
+
+declare function dedupeAndDetectViews(plan: ProposedSchema, data: Record<string, unknown>): {
+    plan: ProposedSchema;
+    views: DetectedView[];
+};
+
+export { ALL_PROVENANCE_FIELDS, type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type AggregateFunction, type AggregateHaving, type AggregateOptions, type AggregateResult, type AggregateSpec, type ApplyWriteResult, type AsOfCandidate, type AsOfColumnCandidate, type AsOfInputs, type AudienceRowCtx, type AuditEvent, type AutoUpdateResult, type BacklinkSignal, type BelongsToRelation, type BelongsToSource, type BenchmarkOptions, type BenchmarkReport, type BenchmarkScale, type BlobMetadata, BoundedReadError, type BuiltinTemplateName, CLOUD_SETTING_SYSTEM_PROMPT, CLOUD_SETTING_WORKSPACE_LOGO, CLOUD_SETTING_WORKSPACE_LOGO_ETAG, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ChunkedMigrationOptions, type ChunkedMigrationResult, type ChunkerFn, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CloudS3Secret, ComputedColumnCycleError, type ComputedColumnSpec, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSignal, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_MAX_NODES, DEFAULT_TYPE_ALIASES, type DetectedView, type DiagnoseOptions, type DiscoveredTable, EMBEDDINGS_TABLE, EmbeddingDimensionMismatchError, type EmbeddingRefreshResult, EmbeddingScanTooLargeError, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityMatch, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type EvalQuery, type EvalRegression, type ExistingTable, type ExtensionAvailability, type ExtractEdgesSpec, type ExtractedObject, FileSourceKeyStore, type FileSourceKeyStoreOptions, type FilesRow, type Filter, type FilterAnd, type FilterExpr, type FilterOp, type FilterOr, FoldCache, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type GraphBoostOptions, type GraphBoostResult, type GraphEdge, type GraphNode, type GraphTraversalResult, type GuiServerHandle, type HasManyRelation, type HasManySource, type HealthIssueKind, type HealthSeverity, type HybridScoreBreakdown, type HybridSearchOptions, type HybridSearchResult, type ImportMode, type ImportProgress, InMemorySourceKeyStore, InMemoryStateStore, type InferredColumn, type InferredDimension, type InferredEntity, type InferredLinkage, type InferredType, type InitOptions, LEGACY_MEMBER_GROUP, LOCAL_DB_RELPATH, type LatencyStats, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, MAX_TRAVERSAL_DEPTH, type ManyToManySource, type MarkdownTableColumn, type MaterializeCtx, type MaterializeOptions, type MaterializeResult, type MaterializedRollupSpec, type MigrateResult, type Migration, type MigrationCheckpoint, type MigrationOptions, type MigrationProgress, type MigrationResult, type MigrationStatus, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type Observation, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PerQueryEval, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, ProgressThrottle, type ProposedSchema, type ProvenanceConfig, type ProvenanceField, ProvenanceImmutableError, type QueryOptions, type QueryPageOptions, type QueryPageResult, type QueryProjection, READ_ONLY_HEADER, ROOT_DIRNAME, type RankingOptions, type ReadOnlyHeaderOptions, type RecencySignal, type ReconcileOptions, type ReconcileResult, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RefreshEmbeddingsOptions, type Relation, type RelevanceLabel, type RemoteBlobStore, type RenderHooks, type RenderOptions, type RenderProgress, type RenderProgressCallback, type RenderProgressKind, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type RerankCandidate, type RerankScore, type RerankerFn, type ResolveOptions, type RetrievalEvalOptions, type RetrievalEvalSummary, type RetrievalHealthIssue, type RetrievalHealthReport, type RetrievalHealthSpec, type RetrievalSlo, type Retriever, type RetryOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type RewardSignal, type RollupFunction, type Row, type RowVisibilityDefault, type S3Config, type S3StoreConfig, S3UnavailableError, S3_SECRET_TABLE, SQLiteAdapter, type SchemaEntity, type SchemaMatch, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SemanticChunkerOptions, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SloViolation, type SourceHandle, type SourceKeyStore, type SourceMetadata, type SourceQueryOptions, SourceShreddedError, type StartGuiServerOptions, type StopFn, type StorageAdapter, type SyncResult, TRUST_COLUMNS, type TableDefinition, type TableHealth, type TablePolicy, type TemplateRenderSpec, type TextChunk, type TraversalDirection, type TraversalNode, type TraversalOptions, type TrustConfig, type TrustState, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VectorHit, type Viewer, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, activeWorkspaceLabel, addEdge, addEdges, addWorkspace, adoptNativeEntities, allComputedDeps, analyticsEnabled, applyChunkedMigration, applyReranker, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, audiencePredicate, audienceViewSql, autoFtsColumns, autoUpdate, backfillOwnership, backlinkBoost, benchmarkRetrieval, buildVectorIndex, canManageRoles, checkSlos, chunkText, classifyLinks, cloudRlsInstalled, computeColumns, computedColumnDdl, computedColumnOrder, concatRowText, configDir, contentHash, cosineSimilarity, crawlUrl, createReadOnlyHeader, createS3Store, createSQLiteStateStore, decrypt, dedupeAndDetectViews, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, detectAsOf, detectAsOfCandidates, detectAsOfColumns, detectRetrievalRegressions, diagnoseRetrieval, discoverCloudTables, dropVectorIndex, enableAudienceView, enableChangelogRls, enableRlsForTable, encrypt, enrichKnowledge, ensureCheckpointTable, ensureEdgesTable, ensureEmbeddingsTable, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, evaluateRetrieval, excelToRecords, extractEdgesFromColumn, extractObjects, filePresignSql, findLatticeRoot, fixSchemaConflicts, foldEntity, formatHealthReport, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateMemberPassword, generateWriteEntryId, getActiveWorkspace, getCloudSetting, getDbCredential, getMigrationCheckpoint, getOrCreateMasterKey, getTablePolicy, getWorkspace, grantPresignerToMemberGroup, graphAdjacencyBoost, hasFilePresigner, hasFtsIndex, hasVectorIndex, hashFile, hybridSearch, importLegacyUserConfig, inferFieldType, inferSchema, installCloudRls, installCloudSettings, installFilePresigner, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isRetryableDbError, isRowAudience, latencyStats, listDbCredentials, listMigrationCheckpoints, listNativeBindings, listTokens, listWorkspaces, loadColumnPolicy, manifestPath, markdownTable, matchSchemaToExisting, materializeImport, memberGroupFor, memberRoleName, migrateLatticeData, neighbors, normalizeName, observationVisible, observationsFromChange, openTargetLatticeForMigration, openUnderSource, organizeSource, parseCellDate, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, percentile, probeCloud, provenanceColumns, providerForUrl, provisionMemberRole, rankingBoost, readIdentity, readManifest, readPreferences, readRegistry, readToken, recencyBoost, referenceLocalFile, referenceUrl, refreshEmbeddings, regenerateAudienceViewFromDb, registerNativeEntities, registryPath, removeEdge, removeEmbedding, renameEntities, resolveActiveS3Config, resolveLatticeRoot, resolveProvenanceFields, resolveSource, resolveTrustDefault, resolveWorkspacePaths, resumeMigration, revertMigration, revokeMemberRole, rewardBoost, rollupColumnDdl, rootConfigDir, s3Key, saveDbCredential, saveDbCredentialForTeam, sealUnderSource, searchByEmbedding, searchVectorIndex, secureCloud, seedColumnPolicyFromYaml, semanticChunker, setActiveWorkspace, setCloudS3Secret, setCloudSetting, setColumnAudience, setRowVisibility, setTableDefaultVisibility, setTableNeverShare, shredSource, slugify, sourceRecords, startGuiServer, storeEmbedding, summarizeText, tableNeedsAudienceView, toSafeDirName, traverse, truncate, validateEntryId, vectorIndexAvailable, vectorIndexName, withRetry, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };