@kozou/core 0.0.1 → 0.1.0

package/dist/loadUIHints.d.ts

@@ -0,0 +1,16 @@
+import { type UIHints } from './types/ui-hints.js';
+export declare class KozouUIHintsError extends Error {
+    readonly filePath: string;
+    readonly issues: {
+        path: string;
+        message: string;
+        line?: number;
+    }[];
+    constructor(message: string, filePath: string, issues: {
+        path: string;
+        message: string;
+        line?: number;
+    }[]);
+}
+export declare function loadUIHints(filePath: string): Promise<UIHints>;
+//# sourceMappingURL=loadUIHints.d.ts.map

package/dist/loadUIHints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadUIHints.d.ts","sourceRoot":"","sources":["../src/loadUIHints.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAElE,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;gBAElE,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE;CAO7D;AAMD,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAuCpE"}

package/dist/loadUIHints.js

@@ -0,0 +1,50 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { parseDocument } from 'yaml';
+import { ZodError } from 'zod';
+import { uiHintsSchema } from './types/ui-hints.js';
+export class KozouUIHintsError extends Error {
+    filePath;
+    issues;
+    constructor(message, filePath, issues) {
+        super(message);
+        this.name = 'KozouUIHintsError';
+        this.filePath = filePath;
+        this.issues = issues;
+    }
+}
+// Codex N2: by default the error message only includes the file basename.
+// The absolute path is kept on KozouUIHintsError.filePath; callers can decide
+// whether to surface it in debug logs. This prevents user-environment paths
+// from leaking through CLI / MCP error responses.
+export async function loadUIHints(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    const fileLabel = basename(filePath);
+    const doc = parseDocument(content, { prettyErrors: true });
+    if (doc.errors.length > 0) {
+        const issues = doc.errors.map((e) => ({
+            path: '<yaml>',
+            message: e.message,
+            line: e.linePos?.[0]?.line,
+        }));
+        throw new KozouUIHintsError(`YAML parse error (${fileLabel}): ${doc.errors.length} issue(s)`, filePath, issues);
+    }
+    const json = doc.toJS();
+    if (json === null || json === undefined) {
+        return uiHintsSchema.parse({});
+    }
+    try {
+        return uiHintsSchema.parse(json);
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            const issues = err.issues.map((issue) => ({
+                path: issue.path.join('.') || '<root>',
+                message: issue.message,
+            }));
+            throw new KozouUIHintsError(`UIHints validation error (${fileLabel}): ${issues.length} issue(s)`, filePath, issues);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=loadUIHints.js.map

package/dist/loadUIHints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadUIHints.js","sourceRoot":"","sources":["../src/loadUIHints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAElE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,QAAQ,CAAS;IACjB,MAAM,CAAqD;IACpE,YACE,OAAe,EACf,QAAgB,EAChB,MAA0D;QAE1D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,0EAA0E;AAC1E,8EAA8E;AAC9E,4EAA4E;AAC5E,kDAAkD;AAClD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB;IAChD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAErC,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpC,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;SAC3B,CAAC,CAAC,CAAC;QACJ,MAAM,IAAI,iBAAiB,CACzB,qBAAqB,SAAS,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,WAAW,EAChE,QAAQ,EACR,MAAM,CACP,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACxC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ;gBACtC,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC,CAAC;YACJ,MAAM,IAAI,iBAAiB,CACzB,6BAA6B,SAAS,MAAM,MAAM,CAAC,MAAM,WAAW,EACpE,QAAQ,EACR,MAAM,CACP,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/parseCommentTags.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetType } from './types/context.js';
+export type ParsedComment = {
+    body: string;
+    ai: string[];
+    widget: WidgetType | null;
+    policy: string[];
+};
+export declare function parseCommentTags(comment: string | null): ParsedComment;
+//# sourceMappingURL=parseCommentTags.d.ts.map

package/dist/parseCommentTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseCommentTags.d.ts","sourceRoot":"","sources":["../src/parseCommentTags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAoBrD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAMF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CA+CtE"}

package/dist/parseCommentTags.js

@@ -0,0 +1,62 @@
+const KNOWN_WIDGETS = new Set([
+    'text',
+    'textarea',
+    'number',
+    'boolean',
+    'date',
+    'datetime',
+    'enum-select',
+    'relation-select',
+    'json',
+    'image-url',
+    'uuid',
+    'currency',
+]);
+const KNOWN_TAGS = new Set(['ai', 'widget', 'policy']);
+const TAG_RE = /^\s*@([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/;
+function isWidgetType(value) {
+    return KNOWN_WIDGETS.has(value);
+}
+export function parseCommentTags(comment) {
+    const result = { body: '', ai: [], widget: null, policy: [] };
+    if (comment === null || comment === '')
+        return result;
+    const lines = comment.split('\n');
+    const bodyLines = [];
+    for (const line of lines) {
+        const match = TAG_RE.exec(line);
+        if (!match) {
+            bodyLines.push(line);
+            continue;
+        }
+        const tag = match[1].toLowerCase();
+        const value = match[2].trim();
+        if (tag === 'ai') {
+            result.ai.push(value);
+            bodyLines.push(line);
+            continue;
+        }
+        if (tag === 'widget') {
+            if (isWidgetType(value)) {
+                result.widget = value;
+            }
+            else {
+                console.warn(`[@kozou/core] parseCommentTags: invalid @widget value "${value}" (skip)`);
+                result.widget = null;
+            }
+            continue;
+        }
+        if (tag === 'policy') {
+            result.policy.push(value);
+            bodyLines.push(line);
+            continue;
+        }
+        if (!KNOWN_TAGS.has(tag)) {
+            console.warn(`[@kozou/core] parseCommentTags: unknown tag "@${tag}" (forward compat: kept in body)`);
+            bodyLines.push(line);
+        }
+    }
+    result.body = bodyLines.join('\n').replace(/\s+$/, '');
+    return result;
+}
+//# sourceMappingURL=parseCommentTags.js.map

package/dist/parseCommentTags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseCommentTags.js","sourceRoot":"","sources":["../src/parseCommentTags.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAA4B,IAAI,GAAG,CAAa;IACjE,MAAM;IACN,UAAU;IACV,QAAQ;IACR,SAAS;IACT,MAAM;IACN,UAAU;IACV,aAAa;IACb,iBAAiB;IACjB,MAAM;IACN,WAAW;IACX,MAAM;IACN,UAAU;CACX,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvD,MAAM,MAAM,GAAG,2CAA2C,CAAC;AAS3D,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,aAAa,CAAC,GAAG,CAAC,KAAmB,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,MAAM,MAAM,GAAkB,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC7E,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IAEtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;QAE/B,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CACV,0DAA0D,KAAK,UAAU,CAC1E,CAAC;gBACF,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;YACvB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,CACV,iDAAiD,GAAG,kCAAkC,CACvF,CAAC;YACF,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types/adapter.d.ts

@@ -0,0 +1,45 @@
+export interface DataAdapter {
+    /** List records (pagination, search, sort) */
+    list(resource: string, params: ListParams): Promise<ListResult>;
+    /** Fetch a single record */
+    get(resource: string, id: string | number): Promise<Record<string, unknown>>;
+    /** Create a record */
+    create(resource: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Update a record */
+    update(resource: string, id: string | number, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Delete a record */
+    delete(resource: string, id: string | number): Promise<void>;
+    /** Lightweight search used by relation-select (returns label / search fields only) */
+    searchRelation(resource: string, params: SearchRelationParams): Promise<RelationOption[]>;
+}
+export type ListParams = {
+    /** Free-text search query (v0.1 is `ilike`-based) */
+    search?: string;
+    /** Per-column filters; values are forwarded verbatim */
+    filters?: Record<string, unknown>;
+    sort?: SortSpec[];
+    /** 1-based page index */
+    page?: number;
+    pageSize?: number;
+};
+export type SortSpec = {
+    field: string;
+    order: 'asc' | 'desc';
+};
+export type ListResult = {
+    rows: Record<string, unknown>[];
+    total: number;
+    page: number;
+    pageSize: number;
+};
+export type SearchRelationParams = {
+    query: string;
+    labelField: string;
+    searchFields: string[];
+    limit?: number;
+};
+export type RelationOption = {
+    id: string | number;
+    label: string;
+};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/types/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEhE,4BAA4B;IAC5B,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE7E,sBAAsB;IACtB,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEpC,sBAAsB;IACtB,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEpC,sBAAsB;IACtB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D,sFAAsF;IACtF,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC"}

package/dist/types/adapter.js

@@ -0,0 +1,8 @@
+// DataAdapter interface as defined in Kozou v0.1 spec §4.4.
+//
+// In v0.1 the first concrete adapter ships under @kozou/core. Defining a
+// pluggable boundary up front lets v0.2's `@kozou/api` slot in as a
+// non-breaking change (see end of Kozou v0.1 spec §4.4). For the concrete
+// adapter implementation names, refer to Kozou v0.1 spec §4.4.
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/types/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,yEAAyE;AACzE,oEAAoE;AACpE,0EAA0E;AAC1E,+DAA+D"}

package/dist/types/context.d.ts

@@ -0,0 +1,105 @@
+import type { RawTable, RawView } from './raw.js';
+/** Output of core.buildSchemaContext; input to MCP / UI. */
+export type SchemaContext = {
+    meta: {
+        serverVersion: string;
+        builtAt: string;
+        sourceSchemas: string[];
+    };
+    tables: TableContext[];
+    views: ViewContext[];
+    enums: EnumContext[];
+    /** Domain concepts derived from views (in v0.1, every view is a concept) */
+    concepts: ConceptContext[];
+};
+export type TableContext = {
+    schema: string;
+    name: string;
+    /** "schema.name" */
+    qualifiedName: string;
+    /** Order: UI Hints > first line of COMMENT > name */
+    label: string;
+    /** Full COMMENT body (plain, with @ai/@widget/@policy tags stripped) */
+    description: string | null;
+    /** Lines from the COMMENT that start with `@ai:` */
+    aiDescription: string | null;
+    primaryKey: string[];
+    /** From UI Hints; otherwise a heuristic (Kozou v0.1 spec §6.5) */
+    displayField: string | null;
+    columns: ColumnContext[];
+    relations: RelationContext[];
+    /** Raw record kept for downstream consumers */
+    rawTable: RawTable;
+};
+export type ColumnContext = {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+    defaultExpr: string | null;
+    isPrimaryKey: boolean;
+    isForeignKey: boolean;
+    label: string;
+    description: string | null;
+    aiDescription: string | null;
+    /** Order: UI Hints > @widget: tag > heuristic (Kozou v0.1 spec §6.4) */
+    widget: WidgetType;
+    /** Values extracted from CHECK constraints, or PostgreSQL ENUM members */
+    enumValues: string[] | null;
+    /** Sourced from UI Hints */
+    readonly: boolean;
+};
+/** Widget domain for Kozou v0.1 spec §6.4. */
+export type WidgetType = 'text' | 'textarea' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum-select' | 'relation-select' | 'json' | 'image-url' | 'uuid' | 'currency';
+export type RelationContext = {
+    /** Column on this side of the relation (v0.1 limits this to 1) */
+    field: string;
+    references: {
+        schema: string;
+        table: string;
+        column: string;
+    };
+    /** v0.1 supports only these two */
+    cardinality: 'many-to-one' | 'one-to-one';
+    /** From the FK's COMMENT */
+    meaning: string | null;
+};
+export type ViewContext = {
+    schema: string;
+    name: string;
+    qualifiedName: string;
+    label: string;
+    description: string | null;
+    aiDescription: string | null;
+    /** First paragraph of the COMMENT */
+    purpose: string | null;
+    columns: ColumnContext[];
+    underlyingTables: {
+        schema: string;
+        name: string;
+    }[];
+    /** Raw record kept for downstream consumers (e.g. MCP describe_view.definition) */
+    rawView: RawView;
+};
+export type EnumContext = {
+    schema: string;
+    name: string;
+    values: string[];
+    description: string | null;
+};
+/** v0.1: ConceptContext is a thin wrapper around ViewContext. See end of Kozou v0.1 spec §4.2. */
+export type ConceptContext = {
+    /** Matches ViewContext.name */
+    name: string;
+    label: string;
+    description: string | null;
+    /** Hard-coded "VIEW" in v0.1, with room to grow (e.g. "FUNCTION") */
+    kind: 'VIEW';
+    /** Suggested query path: targets the VIEW can be joined to */
+    joinSuggestions: {
+        table: string;
+        on: string;
+    }[];
+    /** @ai: lines from the COMMENT */
+    aiNotes: string[];
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/types/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"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"}

package/dist/types/context.js

@@ -0,0 +1,7 @@
+// SchemaContext type definitions per Kozou v0.1 spec §4.2.
+//
+// This is the output contract of @kozou/core.buildSchemaContext and the
+// input contract for @kozou/mcp and @kozou/svelte-ui. Per Kozou v0.1 spec
+// §0, the code is the source of truth.
+export {};
+//# sourceMappingURL=context.js.map

package/dist/types/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,uCAAuC"}

package/dist/types/raw.d.ts

@@ -0,0 +1,89 @@
+/** introspect output: the raw structural information pulled from PostgreSQL. */
+export type RawIntrospection = {
+    /** PostgreSQL server version, e.g. "16.2" */
+    serverVersion: string;
+    /** When introspect ran (ISO 8601) */
+    introspectedAt: string;
+    /** Target schemas (default: ["public"]) */
+    schemas: string[];
+    tables: RawTable[];
+    views: RawView[];
+    enums: RawEnum[];
+    /** v0.1 collects these but uses them sparingly in UI/MCP */
+    functions: RawFunction[];
+};
+export type RawTable = {
+    schema: string;
+    name: string;
+    comment: string | null;
+    columns: RawColumn[];
+    /** Array of column names */
+    primaryKey: string[];
+    foreignKeys: RawForeignKey[];
+    checks: RawCheck[];
+    indexes: RawIndex[];
+};
+export type RawColumn = {
+    name: string;
+    /** e.g. "uuid", "text", "numeric(12,2)", "timestamptz" */
+    dataType: string;
+    /** information_schema.columns.udt_name */
+    udtName: string;
+    nullable: boolean;
+    defaultExpr: string | null;
+    comment: string | null;
+    /** Ordinal position (1-based, from information_schema.columns) */
+    position: number;
+};
+export type RawForeignKey = {
+    name: string;
+    /** Column name(s) on the referencing (this) side */
+    columns: string[];
+    referencedSchema: string;
+    referencedTable: string;
+    referencedColumns: string[];
+    onDelete: FkAction;
+    onUpdate: FkAction;
+    comment: string | null;
+};
+export type FkAction = 'NO ACTION' | 'RESTRICT' | 'CASCADE' | 'SET NULL' | 'SET DEFAULT';
+export type RawCheck = {
+    name: string;
+    /** Raw CHECK expression, e.g. "status IN ('for_sale', 'reserved', 'sold')" */
+    expression: string;
+};
+export type RawIndex = {
+    name: string;
+    columns: string[];
+    unique: boolean;
+};
+export type RawView = {
+    schema: string;
+    name: string;
+    comment: string | null;
+    /** Inferred columns of the VIEW (with their own COMMENTs) */
+    columns: RawColumn[];
+    /** Underlying tables resolved by parsing the view definition where possible */
+    underlyingTables: {
+        schema: string;
+        name: string;
+    }[];
+    /** pg_views.definition */
+    definition: string;
+};
+export type RawEnum = {
+    schema: string;
+    name: string;
+    values: string[];
+};
+export type RawFunction = {
+    schema: string;
+    name: string;
+    returnType: string;
+    arguments: {
+        name: string;
+        type: string;
+    }[];
+    comment: string | null;
+};
+//# sourceMappingURL=raw.d.ts.map

package/dist/types/raw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../../src/types/raw.ts"],"names":[],"mappings":"AAOA,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,4DAA4D;IAC5D,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAChB,WAAW,GACX,UAAU,GACV,SAAS,GACT,UAAU,GACV,aAAa,CAAC;AAElB,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6DAA6D;IAC7D,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,+EAA+E;IAC/E,gBAAgB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC"}

package/dist/types/raw.js

@@ -0,0 +1,8 @@
+// RawIntrospection type definitions per Kozou v0.1 spec §4.1. This is the
+// output contract of @kozou/introspect.
+//
+// Per Kozou v0.1 spec §0, this file is the source of truth on the code
+// side; when type changes diverge from the spec, the same PR must update
+// Kozou v0.1 spec.
+export {};
+//# sourceMappingURL=raw.js.map

package/dist/types/raw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.js","sourceRoot":"","sources":["../../src/types/raw.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,wCAAwC;AACxC,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,mBAAmB"}