@kaelio/ktx 0.13.0 → 0.14.0

package/dist/context/ingest/adapters/gdrive/normalize.js

@@ -0,0 +1,256 @@
+function escapeMarkdownText(value) {
+    return value.replace(/([*_~`])/g, '\\$1');
+}
+function normalizeInternalLinkTarget(prefix, target) {
+    const id = typeof target === 'string' ? target : target?.id;
+    if (!id?.trim()) {
+        return null;
+    }
+    return `#${prefix}-${id.trim()}`;
+}
+function resolveLinkHref(element) {
+    const link = element.textRun?.textStyle?.link;
+    const href = link?.url?.trim();
+    if (href) {
+        return href;
+    }
+    return (normalizeInternalLinkTarget('heading', link?.heading) ??
+        normalizeInternalLinkTarget('heading', link?.headingId) ??
+        normalizeInternalLinkTarget('bookmark', link?.bookmark) ??
+        normalizeInternalLinkTarget('bookmark', link?.bookmarkId) ??
+        null);
+}
+function normalizeTextRun(element) {
+    const content = element.textRun?.content ?? '';
+    const style = element.textRun?.textStyle;
+    let text = escapeMarkdownText(content.replace(/\r/g, ''));
+    if (!text && element.inlineObjectElement) {
+        return '[Embedded object]';
+    }
+    if (!text && element.pageBreak) {
+        return '\n---\n';
+    }
+    if (!text) {
+        return '';
+    }
+    const href = resolveLinkHref(element);
+    const isCode = style?.weightedFontFamily?.fontFamily === 'Courier New';
+    if (isCode) {
+        text = `\`${text.replace(/`/g, '\\`')}\``;
+    }
+    if (style?.bold) {
+        text = `**${text}**`;
+    }
+    if (style?.italic) {
+        text = `*${text}*`;
+    }
+    if (style?.underline) {
+        text = `<u>${text}</u>`;
+    }
+    if (style?.strikethrough) {
+        text = `~~${text}~~`;
+    }
+    if (href) {
+        text = `[${text}](${href.replace(/\)/g, '\\)')})`;
+    }
+    if (style?.baselineOffset === 'SUPERSCRIPT') {
+        text = `<sup>${text}</sup>`;
+    }
+    else if (style?.baselineOffset === 'SUBSCRIPT') {
+        text = `<sub>${text}</sub>`;
+    }
+    return text;
+}
+function paragraphText(paragraph) {
+    return (paragraph?.elements ?? [])
+        .map((element) => normalizeTextRun(element))
+        .join('')
+        .replace(/\n/g, '')
+        .trim();
+}
+function headingPrefix(namedStyleType) {
+    if (namedStyleType === 'TITLE') {
+        return '#';
+    }
+    if (namedStyleType === 'SUBTITLE') {
+        return '##';
+    }
+    if (!namedStyleType?.startsWith('HEADING_')) {
+        return null;
+    }
+    const level = Number.parseInt(namedStyleType.slice('HEADING_'.length), 10);
+    if (Number.isNaN(level) || level < 1) {
+        return null;
+    }
+    return '#'.repeat(Math.min(level, 6));
+}
+function isOrderedListLevel(level) {
+    const glyphType = level?.glyphType?.toUpperCase();
+    if (glyphType) {
+        return (glyphType.includes('NUMBER') ||
+            glyphType.includes('DECIMAL') ||
+            glyphType.includes('ALPHA') ||
+            glyphType.includes('ROMAN') ||
+            glyphType.includes('LATIN'));
+    }
+    const glyphSymbol = level?.glyphSymbol?.trim();
+    return glyphSymbol === '%0.' || glyphSymbol === '%0)' || glyphSymbol === '1.' || glyphSymbol === '1)';
+}
+function listPrefix(paragraph, lists) {
+    if (!paragraph.bullet) {
+        return null;
+    }
+    const level = Math.max(paragraph.bullet.nestingLevel ?? 0, 0);
+    const indent = '  '.repeat(level);
+    const listDefinition = paragraph.bullet.listId ? lists?.[paragraph.bullet.listId] : undefined;
+    const listLevel = listDefinition?.listProperties?.nestingLevels?.[level];
+    return `${indent}${isOrderedListLevel(listLevel) ? '1. ' : '- '}`;
+}
+function paragraphToMarkdown(paragraph, lists) {
+    const text = paragraphText(paragraph);
+    if (!text) {
+        return null;
+    }
+    const prefix = paragraph ? listPrefix(paragraph, lists) : null;
+    if (prefix) {
+        return `${prefix}${text}`;
+    }
+    const heading = headingPrefix(paragraph?.paragraphStyle?.namedStyleType);
+    if (heading) {
+        const headingLine = `${heading} ${text}`;
+        const headingId = paragraph?.paragraphStyle?.headingId?.trim();
+        return headingId ? `<a id="heading-${headingId}"></a>\n${headingLine}` : headingLine;
+    }
+    return text;
+}
+function normalizeTableCell(cell, lists) {
+    const blocks = normalizeStructuralElements(cell?.content ?? [], lists);
+    return blocks
+        .map((block) => block.replace(/\n/g, ' <br> '))
+        .join(' / ')
+        .replace(/\|/g, '\\|')
+        .trim();
+}
+function markdownTableDivider(columnCount) {
+    return `| ${Array.from({ length: columnCount }, () => '---').join(' | ')} |`;
+}
+function normalizeTable(table, lists) {
+    const rows = table?.tableRows ?? [];
+    const normalizedRows = rows
+        .map((row) => (row.tableCells ?? []).map((cell) => normalizeTableCell(cell, lists)))
+        .filter((cells) => cells.length > 0);
+    if (normalizedRows.length === 0) {
+        return [];
+    }
+    const columnCount = Math.max(...normalizedRows.map((cells) => cells.length));
+    const paddedRows = normalizedRows.map((cells) => Array.from({ length: columnCount }, (_, index) => cells[index] ?? ''));
+    const [header, ...body] = paddedRows;
+    const blocks = [`| ${header.join(' | ')} |`, markdownTableDivider(columnCount)];
+    for (const row of body) {
+        blocks.push(`| ${row.join(' | ')} |`);
+    }
+    return [blocks.join('\n')];
+}
+function normalizeStructuralElements(elements, lists) {
+    const blocks = [];
+    for (const element of elements) {
+        const line = paragraphToMarkdown(element.paragraph, lists);
+        if (line) {
+            blocks.push(line);
+            continue;
+        }
+        if (element.table) {
+            blocks.push(...normalizeTable(element.table, lists));
+        }
+    }
+    return blocks;
+}
+function headerFooterRoleMap(label, documentStyle) {
+    const roleMap = new Map();
+    const roleEntries = label === 'Headers'
+        ? [
+            [documentStyle?.defaultHeaderId, 'Default Header'],
+            [documentStyle?.firstPageHeaderId, 'First Page Header'],
+            [documentStyle?.evenPageHeaderId, 'Even Page Header'],
+        ]
+        : [
+            [documentStyle?.defaultFooterId, 'Default Footer'],
+            [documentStyle?.firstPageFooterId, 'First Page Footer'],
+            [documentStyle?.evenPageFooterId, 'Even Page Footer'],
+        ];
+    for (const [id, role] of roleEntries) {
+        const normalizedId = id?.trim();
+        if (!normalizedId || roleMap.has(normalizedId)) {
+            continue;
+        }
+        roleMap.set(normalizedId, role ?? normalizedId);
+    }
+    return roleMap;
+}
+function normalizeHeaderFooterMap(label, entries, lists, documentStyle) {
+    if (!entries) {
+        return null;
+    }
+    const ids = Object.keys(entries).sort();
+    const roles = headerFooterRoleMap(label, documentStyle);
+    const sections = [];
+    for (const id of ids) {
+        const blocks = normalizeStructuralElements(entries[id]?.content ?? [], lists);
+        if (blocks.length === 0) {
+            continue;
+        }
+        const title = roles.get(id) ?? `${label.slice(0, -1)} ${escapeMarkdownText(id)}`;
+        sections.push(`### ${title}\n\n${blocks.join('\n\n').trim()}`);
+    }
+    if (sections.length === 0) {
+        return null;
+    }
+    return `## ${label}\n\n${sections.join('\n\n').trim()}`;
+}
+function joinNonEmptySections(sections) {
+    const nonEmpty = sections.filter((section) => Boolean(section?.trim()));
+    if (nonEmpty.length === 0) {
+        return null;
+    }
+    return nonEmpty.join('\n\n').trim();
+}
+function flattenGoogleDocsTabs(tabs) {
+    if (!tabs?.length) {
+        return [];
+    }
+    const flattened = [];
+    for (const tab of tabs) {
+        flattened.push(tab);
+        flattened.push(...flattenGoogleDocsTabs(tab.childTabs));
+    }
+    return flattened;
+}
+function normalizeTab(tab, fallbackLists) {
+    const lists = tab.documentTab?.lists ?? fallbackLists;
+    const headerSection = normalizeHeaderFooterMap('Headers', tab.documentTab?.headers, lists, tab.documentTab?.documentStyle);
+    const bodySection = normalizeStructuralElements(tab.documentTab?.body?.content ?? [], lists).join('\n\n').trim();
+    const footerSection = normalizeHeaderFooterMap('Footers', tab.documentTab?.footers, lists, tab.documentTab?.documentStyle);
+    const content = joinNonEmptySections([headerSection, bodySection, footerSection]);
+    if (!content) {
+        return null;
+    }
+    const title = tab.tabProperties?.title?.trim();
+    if (!title) {
+        return content;
+    }
+    return [`# ${escapeMarkdownText(title)}`, content].join('\n\n').trim();
+}
+export function normalizeGoogleDocToMarkdown(document) {
+    const normalizedTabs = flattenGoogleDocsTabs(document.tabs)
+        .map((tab) => normalizeTab(tab, document.lists))
+        .filter((tab) => Boolean(tab));
+    if (normalizedTabs.length > 0) {
+        return normalizedTabs.join('\n\n').trim();
+    }
+    const bodySection = normalizeStructuralElements(document.body?.content ?? [], document.lists).join('\n\n').trim();
+    return (joinNonEmptySections([
+        normalizeHeaderFooterMap('Headers', document.headers, document.lists, document.documentStyle),
+        bodySection,
+        normalizeHeaderFooterMap('Footers', document.footers, document.lists, document.documentStyle),
+    ]) ?? '');
+}

package/dist/context/ingest/adapters/gdrive/types.d.ts

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+export declare const GDRIVE_SCOPES: readonly ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/documents.readonly"];
+export declare const GDRIVE_SOURCE_KEY = "gdrive";
+export declare const GDRIVE_DOC_MIME_TYPE = "application/vnd.google-apps.document";
+export declare const GDRIVE_FOLDER_MIME_TYPE = "application/vnd.google-apps.folder";
+export declare const gdrivePullConfigSchema: z.ZodObject<{
+    serviceAccountKey: z.ZodString;
+    folderId: z.ZodString;
+    recursive: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GdrivePullConfig = z.infer<typeof gdrivePullConfigSchema>;
+export declare const gdriveManifestSchema: z.ZodObject<{
+    source: z.ZodLiteral<"gdrive">;
+    folderId: z.ZodString;
+    recursive: z.ZodBoolean;
+    fetchedAt: z.ZodString;
+    fileCount: z.ZodNumber;
+    skipped: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        externalId: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type GdriveManifest = z.infer<typeof gdriveManifestSchema>;
+export declare const gdriveMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    path: z.ZodString;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    mimeType: z.ZodLiteral<"application/vnd.google-apps.document">;
+    folderId: z.ZodString;
+    drivePath: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    modifiedTime: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const gdriveServiceAccountKeySchema: z.ZodObject<{
+    client_email: z.ZodString;
+    private_key: z.ZodString;
+    project_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GdriveServiceAccountKey = z.infer<typeof gdriveServiceAccountKeySchema>;
+export interface GdriveFileRecord {
+    id: string;
+    name: string;
+    mimeType: string;
+    parents: string[];
+    webViewLink: string | null;
+    modifiedTime: string | null;
+}
+export interface GoogleDocsDocument {
+    documentId?: string;
+    title?: string;
+    body?: {
+        content?: GoogleDocsStructuralElement[];
+    };
+    documentStyle?: GoogleDocsDocumentStyle;
+    lists?: Record<string, GoogleDocsList>;
+    headers?: Record<string, GoogleDocsHeaderFooter>;
+    footers?: Record<string, GoogleDocsHeaderFooter>;
+    tabs?: GoogleDocsTab[];
+}
+export interface GoogleDocsList {
+    listProperties?: {
+        nestingLevels?: GoogleDocsListNestingLevel[];
+    };
+}
+interface GoogleDocsListNestingLevel {
+    glyphType?: string;
+    glyphSymbol?: string;
+}
+export interface GoogleDocsTab {
+    tabProperties?: {
+        tabId?: string;
+        title?: string;
+    };
+    childTabs?: GoogleDocsTab[];
+    documentTab?: {
+        body?: {
+            content?: GoogleDocsStructuralElement[];
+        };
+        documentStyle?: GoogleDocsDocumentStyle;
+        lists?: Record<string, GoogleDocsList>;
+        headers?: Record<string, GoogleDocsHeaderFooter>;
+        footers?: Record<string, GoogleDocsHeaderFooter>;
+    };
+}
+export interface GoogleDocsDocumentStyle {
+    defaultHeaderId?: string;
+    defaultFooterId?: string;
+    firstPageHeaderId?: string;
+    firstPageFooterId?: string;
+    evenPageHeaderId?: string;
+    evenPageFooterId?: string;
+}
+export interface GoogleDocsHeaderFooter {
+    headerId?: string;
+    footerId?: string;
+    content?: GoogleDocsStructuralElement[];
+}
+export interface GoogleDocsStructuralElement {
+    paragraph?: GoogleDocsParagraph;
+    table?: GoogleDocsTable;
+    sectionBreak?: unknown;
+}
+export interface GoogleDocsTable {
+    tableRows?: GoogleDocsTableRow[];
+}
+interface GoogleDocsTableRow {
+    tableCells?: GoogleDocsTableCell[];
+}
+export interface GoogleDocsTableCell {
+    content?: GoogleDocsStructuralElement[];
+}
+export interface GoogleDocsParagraph {
+    elements?: GoogleDocsParagraphElement[];
+    bullet?: {
+        listId?: string;
+        nestingLevel?: number;
+    };
+    paragraphStyle?: {
+        namedStyleType?: string;
+        headingId?: string;
+    };
+}
+export interface GoogleDocsLinkTarget {
+    id?: string;
+    tabId?: string;
+}
+export interface GoogleDocsParagraphElement {
+    textRun?: {
+        content?: string;
+        textStyle?: {
+            bold?: boolean;
+            italic?: boolean;
+            underline?: boolean;
+            strikethrough?: boolean;
+            link?: {
+                url?: string;
+                tabId?: string;
+                headingId?: string;
+                bookmarkId?: string;
+                heading?: GoogleDocsLinkTarget;
+                bookmark?: GoogleDocsLinkTarget;
+            };
+            weightedFontFamily?: {
+                fontFamily?: string;
+            };
+            baselineOffset?: 'SUPERSCRIPT' | 'SUBSCRIPT' | string;
+        };
+    };
+    inlineObjectElement?: unknown;
+    pageBreak?: unknown;
+}
+export {};

package/dist/context/ingest/adapters/gdrive/types.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+const GDRIVE_DOCS_SCOPE = 'https://www.googleapis.com/auth/documents.readonly';
+const GDRIVE_DRIVE_SCOPE = 'https://www.googleapis.com/auth/drive.readonly';
+export const GDRIVE_SCOPES = [GDRIVE_DRIVE_SCOPE, GDRIVE_DOCS_SCOPE];
+export const GDRIVE_SOURCE_KEY = 'gdrive';
+export const GDRIVE_DOC_MIME_TYPE = 'application/vnd.google-apps.document';
+export const GDRIVE_FOLDER_MIME_TYPE = 'application/vnd.google-apps.folder';
+export const gdrivePullConfigSchema = z.object({
+    serviceAccountKey: z.string().min(1),
+    folderId: z.string().min(1),
+    recursive: z.boolean().default(false),
+});
+export const gdriveManifestSchema = z.object({
+    source: z.literal(GDRIVE_SOURCE_KEY),
+    folderId: z.string().min(1),
+    recursive: z.boolean(),
+    fetchedAt: z.string().datetime(),
+    fileCount: z.number().int().nonnegative(),
+    skipped: z.array(z.object({ externalId: z.string(), reason: z.string() })).default([]),
+    warnings: z.array(z.string()).default([]),
+});
+export const gdriveMetadataSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    path: z.string(),
+    url: z.string().nullable().default(null),
+    mimeType: z.literal(GDRIVE_DOC_MIME_TYPE),
+    folderId: z.string(),
+    drivePath: z.array(z.string()).default([]),
+    modifiedTime: z.string().datetime().nullable().default(null),
+});
+export const gdriveServiceAccountKeySchema = z.object({
+    client_email: z.string().email(),
+    private_key: z.string().min(1),
+    project_id: z.string().min(1).optional(),
+});

package/dist/context/ingest/adapters/live-database/daemon-introspection.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { URL } from 'node:url';
+import { isKtxScanWarningCode } from '../../../scan/local-structural-artifacts.js';
 import { tableRefFromKey } from '../../../scan/table-ref.js';
 import { inferKtxDimensionType, normalizeKtxNativeType } from '../../../scan/type-normalization.js';
 const DEFAULT_SCHEMAS = ['public'];
@@ -147,7 +148,29 @@ function mapTable(raw) {
         foreignKeys: recordArray(raw.foreign_keys).map(mapForeignKey),
     };
 }
+function mapWarning(raw) {
+    const code = optionalString(raw.code);
+    // Drop codes Node cannot render, keeping the daemon and Node warning catalogs
+    // in parity rather than surfacing an unknown code downstream.
+    if (!code || !isKtxScanWarningCode(code))
+        return null;
+    const table = optionalString(raw.table);
+    const column = optionalString(raw.column);
+    return {
+        code,
+        message: requiredString(raw.message, 'warnings[].message'),
+        recoverable: raw.recoverable !== false,
+        ...(table ? { table } : {}),
+        ...(column ? { column } : {}),
+        ...(raw.metadata && typeof raw.metadata === 'object' && !Array.isArray(raw.metadata)
+            ? { metadata: recordValue(raw.metadata) }
+            : {}),
+    };
+}
 function mapDaemonSnapshot(raw, input) {
+    const warnings = recordArray(raw.warnings)
+        .map(mapWarning)
+        .filter((warning) => warning !== null);
     return {
         connectionId: requiredString(raw.connection_id, 'connection_id') || input.connectionId,
         driver: 'postgres',
@@ -155,6 +178,7 @@ function mapDaemonSnapshot(raw, input) {
         scope: { schemas: input.schemas },
         metadata: recordValue(raw.metadata),
         tables: recordArray(raw.tables).map(mapTable),
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
 function serializeTableScope(options) {

package/dist/context/ingest/adapters/live-database/fetch-report.d.ts

@@ -0,0 +1,8 @@
+import type { SourceFetchReport } from '../../types.js';
+/**
+ * Derives the fetch report from the staged `warnings.json`: objects that failed
+ * introspection become `skipped` entries so the run report, ingest summary, and
+ * `ktx status` can surface them. Returns null when nothing was skipped, keeping
+ * clean ingests free of an empty report.
+ */
+export declare function readLiveDatabaseFetchReport(stagedDir: string): Promise<SourceFetchReport | null>;

package/dist/context/ingest/adapters/live-database/fetch-report.js

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { LIVE_DATABASE_WARNINGS_FILE } from './stage.js';
+const OBJECT_SKIP_CODE = 'object_introspection_failed';
+/**
+ * Derives the fetch report from the staged `warnings.json`: objects that failed
+ * introspection become `skipped` entries so the run report, ingest summary, and
+ * `ktx status` can surface them. Returns null when nothing was skipped, keeping
+ * clean ingests free of an empty report.
+ */
+export async function readLiveDatabaseFetchReport(stagedDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(join(stagedDir, LIVE_DATABASE_WARNINGS_FILE), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const warnings = parsed && typeof parsed === 'object' && Array.isArray(parsed.warnings)
+        ? (parsed.warnings)
+        : [];
+    const skipped = warnings
+        .filter((warning) => warning.code === OBJECT_SKIP_CODE)
+        .map((warning) => ({
+        rawPath: '',
+        entityType: 'database_object',
+        entityId: typeof warning.table === 'string' ? warning.table : null,
+        severity: 'warning',
+        statusCode: null,
+        message: typeof warning.message === 'string' ? warning.message : 'introspection failed',
+        retryRecommended: false,
+    }));
+    if (skipped.length === 0) {
+        return null;
+    }
+    return { status: 'partial', retryRecommended: false, skipped, warnings: [] };
+}

package/dist/context/ingest/adapters/live-database/live-database.adapter.d.ts

@@ -1,4 +1,4 @@
-import type { ChunkResult, DiffSet, FetchContext, SourceAdapter } from '../../types.js';
+import type { ChunkResult, DiffSet, FetchContext, SourceAdapter, SourceFetchReport } from '../../types.js';
 import type { LiveDatabaseSourceAdapterDeps } from './types.js';
 export declare class LiveDatabaseSourceAdapter implements SourceAdapter {
     private readonly deps;
@@ -6,6 +6,7 @@ export declare class LiveDatabaseSourceAdapter implements SourceAdapter {
     readonly skillNames: string[];
     constructor(deps: LiveDatabaseSourceAdapterDeps);
     detect(stagedDir: string): Promise<boolean>;
+    readFetchReport(stagedDir: string): Promise<SourceFetchReport | null>;
     fetch(_pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
     chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
 }

package/dist/context/ingest/adapters/live-database/live-database.adapter.js

@@ -1,4 +1,6 @@
 import { chunkLiveDatabaseStagedDir } from './chunk.js';
+import { readLiveDatabaseFetchReport } from './fetch-report.js';
+import { assertLiveDatabaseScanOutcome } from './scan-outcome.js';
 import { detectLiveDatabaseStagedDir, writeLiveDatabaseSnapshot } from './stage.js';
 export class LiveDatabaseSourceAdapter {
     deps;
@@ -10,14 +12,19 @@ export class LiveDatabaseSourceAdapter {
     detect(stagedDir) {
         return detectLiveDatabaseStagedDir(stagedDir);
     }
+    readFetchReport(stagedDir) {
+        return readLiveDatabaseFetchReport(stagedDir);
+    }
     async fetch(_pullConfig, stagedDir, ctx) {
         const tableScope = ctx.tableScope;
         const snapshot = await this.deps.introspection.extractSchema(ctx.connectionId, { tableScope });
-        await writeLiveDatabaseSnapshot(stagedDir, {
+        const finalized = {
             ...snapshot,
             connectionId: ctx.connectionId,
             extractedAt: snapshot.extractedAt ?? (this.deps.now ?? (() => new Date()))().toISOString(),
-        });
+        };
+        assertLiveDatabaseScanOutcome({ connectionId: ctx.connectionId, scope: tableScope, snapshot: finalized });
+        await writeLiveDatabaseSnapshot(stagedDir, finalized);
     }
     chunk(stagedDir, diffSet) {
         return chunkLiveDatabaseStagedDir(stagedDir, diffSet);

package/dist/context/ingest/adapters/live-database/manifest.d.ts

@@ -64,6 +64,8 @@ export interface BuildLiveDatabaseManifestShardsResult {
 }
 export declare function mergeUsagePreservingExternal(existing: TableUsageOutput | undefined, incoming: TableUsageOutput | undefined): TableUsageOutput | undefined;
 /** @internal */
+export declare function buildTableRef(name: string, catalog: string | null, db: string | null): string;
+/** @internal */
 export declare function buildJoinsByTable(tableNames: Set<string>, joins: LiveDatabaseManifestJoinData[], preservedJoins: Map<string, LiveDatabaseManifestJoinEntry[]>, federatedSiblingTargets?: Set<string>): Map<string, LiveDatabaseManifestJoinEntry[]>;
 export declare function buildLiveDatabaseManifestShards(input: BuildLiveDatabaseManifestShardsInput): BuildLiveDatabaseManifestShardsResult;
 export {};

package/dist/context/ingest/adapters/live-database/manifest.js

@@ -73,7 +73,8 @@ function getShardKey(connectionType, catalog, db) {
         }
     }
 }
-function buildTableRef(name, catalog, db) {
+/** @internal */
+export function buildTableRef(name, catalog, db) {
     const parts = [];
     if (catalog) {
         parts.push(catalog);
@@ -154,7 +155,10 @@ export function buildLiveDatabaseManifestShards(input) {
     for (const table of input.tables) {
         const shardKey = getShardKey(input.connectionType, table.catalog, table.db);
         const shard = shards.get(shardKey) ?? { tables: {} };
-        const existingDescriptions = input.existingDescriptions?.get(table.name);
+        // Existing descriptions/usage are keyed by the fully-qualified ref so two
+        // same-named tables in different schemas never share an entry.
+        const fullRef = buildTableRef(table.name, table.catalog, table.db);
+        const existingDescriptions = input.existingDescriptions?.get(fullRef);
         const columns = table.columns.map((column) => {
             const manifestColumn = {
                 name: column.name,
@@ -173,14 +177,14 @@ export function buildLiveDatabaseManifestShards(input) {
             return manifestColumn;
         });
         const entry = {
-            table: buildTableRef(table.name, table.catalog, table.db),
+            table: fullRef,
             columns,
         };
         const tableDescriptions = mergeDescriptionsPreservingExternal(existingDescriptions?.table, table.descriptions);
         if (tableDescriptions) {
             entry.descriptions = tableDescriptions;
         }
-        const usage = mergeUsagePreservingExternal(input.existingUsage?.get(table.name), table.usage);
+        const usage = mergeUsagePreservingExternal(input.existingUsage?.get(fullRef), table.usage);
         if (usage) {
             entry.usage = usage;
         }

package/dist/context/ingest/adapters/live-database/scan-outcome.d.ts

@@ -0,0 +1,17 @@
+import { type KtxTableRefKey } from '../../../scan/table-ref.js';
+import type { KtxSchemaSnapshot } from '../../../scan/types.js';
+/**
+ * Enforces the partial-vs-total outcome rules for a live-database snapshot,
+ * uniformly for every connector. Outcomes follow from object counts, not a
+ * mode: a connection with at least one ingested object succeeds (any broken
+ * objects ride along as warnings); a connection where every introspected object
+ * failed, or a non-empty enabled_tables scope that matched nothing, raises a
+ * clear connection error instead of staging an empty layer that would later
+ * surface as the generic "did not recognize" message. A legitimately empty
+ * database (no scope, no objects) succeeds with an empty layer.
+ */
+export declare function assertLiveDatabaseScanOutcome(input: {
+    connectionId: string;
+    scope: ReadonlySet<KtxTableRefKey> | undefined;
+    snapshot: KtxSchemaSnapshot;
+}): void;