@ordinatio/entities 1.0.3 → 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,1509 @@
+import * as _ordinatio_errors from '@ordinatio/errors';
+import * as _prisma_client from '@prisma/client';
+import { PrismaClient, Prisma, ContactSource } from '@prisma/client';
+export { ContactSource, PrismaClient } from '@prisma/client';
+import { z } from 'zod';
+import * as _prisma_client_runtime_client from '@prisma/client/runtime/client';
+
+/**
+ * Callbacks injected by the consuming app for side effects.
+ * All optional — package works without them.
+ */
+interface MutationCallbacks {
+    logActivity?: (action: string, description: string, data?: Record<string, unknown>) => Promise<void>;
+    emitEvent?: (type: string, data: unknown) => Promise<void>;
+}
+/**
+ * Provides seed data for the agent knowledge base.
+ * Passed by the app so the package doesn't need app-specific data.
+ */
+interface SeedDataProvider {
+    getKnowledgeSeedData?: () => Array<{
+        entity: string;
+        field: string;
+        value: string;
+        label: string;
+        aliases: string[];
+        category: string | null;
+        metadata: Record<string, unknown> | null;
+        sortOrder: number;
+        source: string;
+    }>;
+}
+/**
+ * Callback for writing structured knowledge fields from notes.
+ */
+interface NoteKnowledgeCallbacks extends MutationCallbacks {
+    setEntityFields?: (entityType: string, entityId: string, fields: Record<string, unknown>, source: string, sourceId?: string, confidence?: number, setBy?: string) => Promise<void>;
+}
+/**
+ * Callback for human-in-the-loop validation of low-confidence writes.
+ */
+interface ValidationCallbacks {
+    requestValidation?: (entityType: string, entityId: string, field: string, value: unknown, confidence: number, existingValue?: unknown, existingConfidence?: number) => Promise<'accept' | 'reject' | 'defer'>;
+}
+/**
+ * Constraint declared on a field definition.
+ * Evaluated after every setEntityFields(). Advisory only — writes not blocked.
+ */
+interface FieldConstraint {
+    targetField: string;
+    operator: 'not_in' | 'in' | 'not_equal' | 'less_than' | 'greater_than' | 'regex';
+    values?: unknown[];
+    value?: unknown;
+    pattern?: string;
+    message: string;
+    severity: 'warning' | 'error';
+}
+/**
+ * Result of a constraint violation check.
+ */
+interface ConstraintViolation {
+    fieldKey: string;
+    constraintField: string;
+    operator: string;
+    actualValue: unknown;
+    constraintValue: unknown;
+    message: string;
+    severity: 'warning' | 'error';
+}
+/**
+ * Extended callbacks for observer-aware mutations.
+ */
+interface ObserverCallbacks extends MutationCallbacks {
+    onConstraintViolation?: (entityType: string, entityId: string, violations: ConstraintViolation[]) => Promise<void>;
+}
+/**
+ * Entity health report — aggregates completeness, freshness, conflicts, truth.
+ */
+interface EntityHealthReport {
+    entityType: string;
+    entityId: string;
+    completeness: number;
+    freshness: number;
+    conflictRate: number;
+    truthAverage: number;
+    overallScore: number;
+    staleFieldCount: number;
+    conflictCount: number;
+    filledFieldCount: number;
+    totalFieldCount: number;
+    warnings: string[];
+}
+/**
+ * Summary of health across all entities of a type.
+ */
+interface EntityTypeHealthSummary {
+    entityType: string;
+    entityCount: number;
+    avgCompleteness: number;
+    avgFreshness: number;
+    avgConflictRate: number;
+    avgOverallScore: number;
+    worstEntities: Array<{
+        entityId: string;
+        overallScore: number;
+    }>;
+    bestEntities: Array<{
+        entityId: string;
+        overallScore: number;
+    }>;
+}
+
+interface ErrorDiagnosis {
+    step: string;
+    check: string;
+}
+interface KnowledgeErrorDef {
+    code: string;
+    file: string;
+    function: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    recoverable: boolean;
+    description: string;
+    diagnosis: ErrorDiagnosis[];
+}
+interface AgentKnowledgeErrorEntry {
+    code: string;
+    file: string;
+    function: string;
+    httpStatus: number;
+    severity: 'warning' | 'error' | 'critical';
+    recoverable: boolean;
+    description: string;
+    diagnosis: string[];
+}
+declare const KNOWLEDGE_ERRORS: Record<string, KnowledgeErrorDef>;
+declare const AGENTKNOW_ERRORS: Record<string, AgentKnowledgeErrorEntry>;
+
+declare function knowledgeError(code: string, context?: Record<string, unknown>): _ordinatio_errors.OrdinatioError;
+declare function agentKnowledgeError(code: string, context?: Record<string, unknown>): _ordinatio_errors.OrdinatioError;
+declare class ContactNotFoundError extends Error {
+    constructor(id: string);
+}
+declare class ContactExistsError extends Error {
+    constructor(email: string);
+}
+declare class ContactAlreadyConvertedError extends Error {
+    constructor(id: string);
+}
+
+declare const ENTITY_TYPES: readonly ["client", "contact", "order"];
+declare const FIELD_DATA_TYPES: readonly ["text", "number", "date", "boolean", "enum", "multi-select"];
+declare const FIELD_STATUSES: readonly ["suggested", "approved", "dismissed", "merged"];
+declare const LEDGER_SOURCES: readonly ["manual", "note", "email", "agent", "ai-batch", "predicted"];
+declare const SEARCH_SOURCES: readonly ["search_bar", "agent_chat", "api"];
+declare const CreateFieldDefinitionSchema: z.ZodObject<{
+    entityType: z.ZodEnum<{
+        client: "client";
+        contact: "contact";
+        order: "order";
+    }>;
+    key: z.ZodString;
+    label: z.ZodString;
+    dataType: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        date: "date";
+        enum: "enum";
+        "multi-select": "multi-select";
+    }>;
+    category: z.ZodString;
+    enumOptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extractionHint: z.ZodOptional<z.ZodString>;
+    sortOrder: z.ZodDefault<z.ZodNumber>;
+    halfLifeDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type CreateFieldDefinitionInput = z.infer<typeof CreateFieldDefinitionSchema>;
+declare const UpdateFieldDefinitionSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    enumOptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extractionHint: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        suggested: "suggested";
+        approved: "approved";
+        dismissed: "dismissed";
+        merged: "merged";
+    }>>;
+    mergedIntoId: z.ZodOptional<z.ZodString>;
+    sortOrder: z.ZodOptional<z.ZodNumber>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    halfLifeDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    constraints: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        targetField: z.ZodString;
+        operator: z.ZodEnum<{
+            not_in: "not_in";
+            in: "in";
+            not_equal: "not_equal";
+            less_than: "less_than";
+            greater_than: "greater_than";
+            regex: "regex";
+        }>;
+        values: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        value: z.ZodOptional<z.ZodUnknown>;
+        pattern: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        severity: z.ZodEnum<{
+            warning: "warning";
+            error: "error";
+        }>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type UpdateFieldDefinitionInput = z.infer<typeof UpdateFieldDefinitionSchema>;
+declare const ListFieldDefinitionsQuery: z.ZodObject<{
+    entityType: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        contact: "contact";
+        order: "order";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        suggested: "suggested";
+        approved: "approved";
+        dismissed: "dismissed";
+        merged: "merged";
+    }>>;
+}, z.core.$strip>;
+type ListFieldDefinitionsQueryInput = z.infer<typeof ListFieldDefinitionsQuery>;
+declare const SetEntityFieldsSchema: z.ZodObject<{
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodDefault<z.ZodEnum<{
+        manual: "manual";
+        note: "note";
+        email: "email";
+        agent: "agent";
+        "ai-batch": "ai-batch";
+        predicted: "predicted";
+    }>>;
+    sourceId: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type SetEntityFieldsInput = z.infer<typeof SetEntityFieldsSchema>;
+declare const SearchByFieldsSchema: z.ZodObject<{
+    entityType: z.ZodEnum<{
+        client: "client";
+        contact: "contact";
+        order: "order";
+    }>;
+    filters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type SearchByFieldsInput = z.infer<typeof SearchByFieldsSchema>;
+declare const LogSearchQuerySchema: z.ZodObject<{
+    query: z.ZodString;
+    source: z.ZodEnum<{
+        search_bar: "search_bar";
+        agent_chat: "agent_chat";
+        api: "api";
+    }>;
+    userId: z.ZodOptional<z.ZodString>;
+    entityType: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        contact: "contact";
+        order: "order";
+    }>>;
+    resultCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type LogSearchQueryInput = z.infer<typeof LogSearchQuerySchema>;
+declare const FieldHistoryQuery: z.ZodObject<{
+    fieldId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type FieldHistoryQueryInput = z.infer<typeof FieldHistoryQuery>;
+
+declare function getFieldDefinitions(db: PrismaClient, entityType?: string, status?: string): Promise<{
+    fields: {
+        entityType: string;
+        key: string;
+        label: string;
+        dataType: string;
+        category: string;
+        enumOptions: Prisma.JsonValue | null;
+        extractionHint: string | null;
+        sortOrder: number;
+        halfLifeDays: number | null;
+        status: string;
+        mergedIntoId: string | null;
+        isActive: boolean;
+        constraints: Prisma.JsonValue | null;
+        id: string;
+        suggestedFrom: string | null;
+        occurrenceCount: number;
+        createdAt: Date;
+        updatedAt: Date;
+    }[];
+    grouped: Record<string, {
+        entityType: string;
+        key: string;
+        label: string;
+        dataType: string;
+        category: string;
+        enumOptions: Prisma.JsonValue | null;
+        extractionHint: string | null;
+        sortOrder: number;
+        halfLifeDays: number | null;
+        status: string;
+        mergedIntoId: string | null;
+        isActive: boolean;
+        constraints: Prisma.JsonValue | null;
+        id: string;
+        suggestedFrom: string | null;
+        occurrenceCount: number;
+        createdAt: Date;
+        updatedAt: Date;
+    }[]>;
+}>;
+declare function createFieldDefinition(db: PrismaClient, input: CreateFieldDefinitionInput, callbacks?: MutationCallbacks): Promise<{
+    entityType: string;
+    key: string;
+    label: string;
+    dataType: string;
+    category: string;
+    enumOptions: Prisma.JsonValue | null;
+    extractionHint: string | null;
+    sortOrder: number;
+    halfLifeDays: number | null;
+    status: string;
+    mergedIntoId: string | null;
+    isActive: boolean;
+    constraints: Prisma.JsonValue | null;
+    id: string;
+    suggestedFrom: string | null;
+    occurrenceCount: number;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+declare function updateFieldDefinition(db: PrismaClient, id: string, input: UpdateFieldDefinitionInput, callbacks?: MutationCallbacks): Promise<{
+    entityType: string;
+    key: string;
+    label: string;
+    dataType: string;
+    category: string;
+    enumOptions: Prisma.JsonValue | null;
+    extractionHint: string | null;
+    sortOrder: number;
+    halfLifeDays: number | null;
+    status: string;
+    mergedIntoId: string | null;
+    isActive: boolean;
+    constraints: Prisma.JsonValue | null;
+    id: string;
+    suggestedFrom: string | null;
+    occurrenceCount: number;
+    createdAt: Date;
+    updatedAt: Date;
+} | null>;
+declare function getFieldDefinitionById(db: PrismaClient, id: string): Promise<{
+    entityType: string;
+    key: string;
+    label: string;
+    dataType: string;
+    category: string;
+    enumOptions: Prisma.JsonValue | null;
+    extractionHint: string | null;
+    sortOrder: number;
+    halfLifeDays: number | null;
+    status: string;
+    mergedIntoId: string | null;
+    isActive: boolean;
+    constraints: Prisma.JsonValue | null;
+    id: string;
+    suggestedFrom: string | null;
+    occurrenceCount: number;
+    createdAt: Date;
+    updatedAt: Date;
+} | null>;
+
+declare function getEntityFields(db: PrismaClient, entityType: string, entityId: string): Promise<{
+    entries: ({
+        field: {
+            entityType: string;
+            key: string;
+            label: string;
+            dataType: string;
+            category: string;
+            enumOptions: _prisma_client_runtime_client.JsonValue | null;
+            extractionHint: string | null;
+            sortOrder: number;
+            halfLifeDays: number | null;
+            status: string;
+            mergedIntoId: string | null;
+            isActive: boolean;
+            constraints: _prisma_client_runtime_client.JsonValue | null;
+            id: string;
+            suggestedFrom: string | null;
+            occurrenceCount: number;
+            createdAt: Date;
+            updatedAt: Date;
+        };
+    } & {
+        entityType: string;
+        value: _prisma_client_runtime_client.JsonValue;
+        source: string;
+        sourceId: string | null;
+        confidence: _prisma_client_runtime_client.Decimal;
+        fieldId: string;
+        id: string;
+        createdAt: Date;
+        entityId: string;
+        setBy: string | null;
+        supersededAt: Date | null;
+    })[];
+    grouped: Record<string, {
+        fieldId: string;
+        key: string;
+        label: string;
+        dataType: string;
+        category: string;
+        value: unknown;
+        confidence: number;
+        source: string;
+        updatedAt: Date;
+    }[]>;
+}>;
+declare function setEntityFields(db: PrismaClient, entityType: string, entityId: string, fields: Record<string, unknown>, source: string, sourceId?: string, confidence?: number, setBy?: string, callbacks?: MutationCallbacks): Promise<{
+    written: {
+        key: string;
+        entryId: string;
+    }[];
+    skipped: string[];
+}>;
+declare function getFieldHistory(db: PrismaClient, entityType: string, entityId: string, fieldId?: string, limit?: number): Promise<({
+    field: {
+        entityType: string;
+        key: string;
+        label: string;
+        dataType: string;
+        category: string;
+        enumOptions: _prisma_client_runtime_client.JsonValue | null;
+        extractionHint: string | null;
+        sortOrder: number;
+        halfLifeDays: number | null;
+        status: string;
+        mergedIntoId: string | null;
+        isActive: boolean;
+        constraints: _prisma_client_runtime_client.JsonValue | null;
+        id: string;
+        suggestedFrom: string | null;
+        occurrenceCount: number;
+        createdAt: Date;
+        updatedAt: Date;
+    };
+} & {
+    entityType: string;
+    value: _prisma_client_runtime_client.JsonValue;
+    source: string;
+    sourceId: string | null;
+    confidence: _prisma_client_runtime_client.Decimal;
+    fieldId: string;
+    id: string;
+    createdAt: Date;
+    entityId: string;
+    setBy: string | null;
+    supersededAt: Date | null;
+})[]>;
+
+declare function searchByFields(db: PrismaClient, entityType: string, filters: Record<string, unknown>, limit?: number): Promise<{
+    entityIds: string[];
+    total: number;
+}>;
+declare function logSearchQuery(db: PrismaClient, input: LogSearchQueryInput): Promise<void>;
+declare function getWeekOfYear(date: Date): number;
+
+/**
+ * Reconstruct entity state at a point in time.
+ * Finds entries that were active at `timestamp`:
+ *   createdAt <= timestamp AND (supersededAt IS NULL OR supersededAt > timestamp)
+ * Groups by field key, takes most recent entry per field.
+ */
+declare function getKnowledgeAt(db: PrismaClient, entityType: string, entityId: string, timestamp: Date): Promise<{
+    fields: Record<string, {
+        value: unknown;
+        confidence: number;
+        source: string;
+        setAt: Date;
+    }>;
+}>;
+/**
+ * Single field value at a point in time.
+ */
+declare function getFieldValueAt(db: PrismaClient, entityType: string, entityId: string, fieldKey: string, timestamp: Date): Promise<{
+    value: unknown;
+    confidence: number;
+    source: string;
+    setAt: Date;
+} | null>;
+/**
+ * Timeline of all changes within a date range.
+ */
+declare function getKnowledgeTimeline(db: PrismaClient, entityType: string, entityId: string, from: Date, to: Date, limit?: number): Promise<Array<{
+    fieldKey: string;
+    value: unknown;
+    confidence: number;
+    source: string;
+    createdAt: Date;
+    supersededAt: Date | null;
+}>>;
+
+/**
+ * Source reliability weights.
+ * Higher = more trustworthy.
+ */
+declare const SOURCE_RELIABILITY: Record<string, number>;
+/**
+ * Recency factor: 1.0 for today, decays exponentially toward 0.
+ * Uses formula: exp(-age_days / maxAgeDays × 3) — reaches ~0.05 at maxAgeDays.
+ */
+declare function computeRecencyFactor(createdAt: Date, now?: Date, maxAgeDays?: number): number;
+/**
+ * Truth Score: weighted average of assertions.
+ * T_v = Σ(C_i × R_i × T_i) / Σ(C_i × R_i)
+ * where C_i = confidence, R_i = source reliability, T_i = recency
+ *
+ * Returns 0 if no assertions.
+ */
+declare function computeTruthScore(assertions: Array<{
+    confidence: number;
+    source: string;
+    createdAt: Date;
+    supersededAt: Date | null;
+}>, now?: Date): number;
+/**
+ * Entity complexity score: how "filled" is the entity's knowledge.
+ * Weighted: 60% category coverage + 40% field coverage.
+ */
+declare function computeComplexityScore(fieldsUsed: number, fieldsAvailable: number, categoriesUsed: number, maxCategories: number): number;
+/**
+ * Compute truth scores for all current (non-superseded) fields on an entity.
+ * DB wrapper that reads ledger entries + their history for truth calculation.
+ */
+declare function computeEntityTruthScores(db: PrismaClient, entityType: string, entityId: string): Promise<Record<string, {
+    truthScore: number;
+    confidence: number;
+    source: string;
+    assertions: number;
+}>>;
+
+/**
+ * Pure exponential decay: C_decayed = C_original × 0.5^(age_days / halfLifeDays)
+ */
+declare function computeDecayedConfidence(originalConfidence: number, createdAt: Date, halfLifeDays: number, now?: Date): number;
+/**
+ * Is the decayed confidence below threshold?
+ */
+declare function isStale(originalConfidence: number, createdAt: Date, halfLifeDays: number, threshold?: number, now?: Date): boolean;
+/**
+ * Get all stale fields for an entity.
+ * Only checks fields whose definitions have a non-null halfLifeDays.
+ */
+declare function getStaleFields(db: PrismaClient, entityType: string, entityId: string, threshold?: number): Promise<Array<{
+    fieldKey: string;
+    label: string;
+    originalConfidence: number;
+    decayedConfidence: number;
+    halfLifeDays: number;
+    lastUpdated: Date;
+    staleSinceDays: number;
+}>>;
+/**
+ * Agent-friendly staleness warnings.
+ */
+declare function formatStalenessWarnings(staleFields: Array<{
+    fieldKey: string;
+    label: string;
+    decayedConfidence: number;
+    staleSinceDays: number;
+}>): string[];
+
+/**
+ * Should this write be validated?
+ * Returns 'validate' when confidence is below threshold
+ * AND there's an existing higher-confidence value.
+ */
+declare function shouldBranch(newConfidence: number, existingConfidence?: number, threshold?: number): 'proceed' | 'validate';
+/**
+ * Set fields with branching logic.
+ * When confidence is low and existing data has higher confidence,
+ * requests human validation before writing.
+ */
+declare function setEntityFieldsWithBranching(db: PrismaClient, entityType: string, entityId: string, fields: Record<string, unknown>, source: string, confidence: number, options?: {
+    sourceId?: string;
+    setBy?: string;
+    branchingThreshold?: number;
+    callbacks?: MutationCallbacks;
+    validationCallbacks?: ValidationCallbacks;
+}): Promise<{
+    written: Array<{
+        key: string;
+        entryId: string;
+    }>;
+    skipped: string[];
+    deferred: Array<{
+        key: string;
+        reason: string;
+    }>;
+    validationRequested: Array<{
+        key: string;
+        value: unknown;
+        confidence: number;
+    }>;
+}>;
+
+interface EntityRelationship {
+    sourceEntityType: string;
+    sourceEntityId: string;
+    targetEntityType: string;
+    targetEntityId: string;
+    sharedFields: Array<{
+        fieldKey: string;
+        value: unknown;
+        sourceConfidence: number;
+        targetConfidence: number;
+    }>;
+    strength: number;
+}
+/**
+ * Pure: compute relationship strength from shared fields.
+ * strength = avg(srcConf × tgtConf) × (sharedCount / totalSourceFields)
+ */
+declare function computeRelationshipStrength(sharedFields: Array<{
+    sourceConfidence: number;
+    targetConfidence: number;
+}>, totalFieldsOnSource: number): number;
+/**
+ * Find entities related to a given entity via shared field values.
+ */
+declare function findRelatedEntities(db: PrismaClient, entityType: string, entityId: string, options?: {
+    targetEntityType?: string;
+    minSharedFields?: number;
+    minStrength?: number;
+    limit?: number;
+}): Promise<EntityRelationship[]>;
+/**
+ * Get all relationships for an entity (alias for findRelatedEntities with defaults).
+ */
+declare function getEntityRelationships(db: PrismaClient, entityType: string, entityId: string, limit?: number): Promise<EntityRelationship[]>;
+
+interface ConflictRule {
+    type: 'mutual_exclusion' | 'range_violation' | 'temporal_impossibility' | 'value_contradiction';
+    description: string;
+    fieldA: string;
+    fieldB?: string;
+    check: (valueA: unknown, valueB?: unknown) => boolean;
+}
+interface DetectedConflict {
+    rule: ConflictRule;
+    entityType: string;
+    entityId: string;
+    fieldA: {
+        key: string;
+        value: unknown;
+        confidence: number;
+        truthScore: number;
+    };
+    fieldB?: {
+        key: string;
+        value: unknown;
+        confidence: number;
+        truthScore: number;
+    };
+    severity: 'low' | 'medium' | 'high';
+    suggestion: string;
+}
+/**
+ * Default conflict rules — minimal starter set.
+ * App provides domain-specific rules via the `rules` parameter.
+ */
+declare const DEFAULT_CONFLICT_RULES: ConflictRule[];
+/**
+ * Pure: evaluate a single rule against field values.
+ */
+declare function evaluateConflictRule(rule: ConflictRule, fields: Record<string, {
+    value: unknown;
+    confidence: number;
+    truthScore: number;
+}>): DetectedConflict | null;
+/**
+ * Check entity for contradictions using provided rules.
+ */
+declare function detectConflicts(db: PrismaClient, entityType: string, entityId: string, rules?: ConflictRule[]): Promise<DetectedConflict[]>;
+/**
+ * Batch scan across all entities of a type for contradictions.
+ */
+declare function scanForConflicts(db: PrismaClient, entityType: string, rules?: ConflictRule[], limit?: number): Promise<Array<{
+    entityId: string;
+    conflicts: DetectedConflict[];
+}>>;
+
+/**
+ * Evaluate a single constraint against current entity state.
+ */
+declare function evaluateConstraint(constraint: FieldConstraint, entityFields: Record<string, unknown>): ConstraintViolation | null;
+/**
+ * Check all constraints for an entity by reading field definitions with constraints.
+ */
+declare function checkConstraints(db: PrismaClient, entityType: string, entityId: string): Promise<ConstraintViolation[]>;
+/**
+ * Fire observers after setEntityFields — check constraints and notify.
+ * Best-effort: never blocks the original write.
+ */
+declare function fireObservers(db: PrismaClient, entityType: string, entityId: string, writtenFields: string[], callbacks?: ObserverCallbacks): Promise<ConstraintViolation[]>;
+
+/**
+ * Analyze co-occurrence patterns across all entities of a type.
+ * For each value of fieldKeyA, what values of fieldKeyB co-occur?
+ *
+ * Returns: Map<valueA, Map<valueB, { count, total, rate }>>
+ */
+declare function buildCoOccurrenceMap(db: PrismaClient, entityType: string, fieldKeyA: string, fieldKeyB: string, minOccurrences?: number): Promise<Map<string, Map<string, {
+    count: number;
+    total: number;
+    rate: number;
+}>>>;
+
+interface GhostFieldPrediction {
+    fieldKey: string;
+    label: string;
+    predictedValue: unknown;
+    confidence: number;
+    basedOn: Array<{
+        fieldKey: string;
+        value: unknown;
+        coOccurrenceRate: number;
+    }>;
+    source: 'predicted';
+}
+/**
+ * Predict missing fields based on co-occurrence patterns.
+ * Finds fields the entity doesn't have yet, predicts values from correlated fields.
+ */
+declare function predictGhostFields(db: PrismaClient, entityType: string, entityId: string, options?: {
+    minConfidence?: number;
+    maxPredictions?: number;
+}): Promise<GhostFieldPrediction[]>;
+/**
+ * Write predictions to ledger with source='predicted', low confidence.
+ * Skips fields that already have a non-predicted value.
+ */
+declare function writeGhostFields(db: PrismaClient, entityType: string, entityId: string, predictions: GhostFieldPrediction[], callbacks?: MutationCallbacks): Promise<{
+    written: number;
+    skipped: number;
+}>;
+
+/**
+ * Pure: compute overall score from components.
+ * 0.4 × completeness + 0.3 × freshness + 0.2 × (1 - conflictRate) + 0.1 × truthAverage
+ */
+declare function computeOverallScore(completeness: number, freshness: number, conflictRate: number, truthAverage: number): number;
+/**
+ * Compute health for one entity.
+ */
+declare function computeEntityHealth(db: PrismaClient, entityType: string, entityId: string, conflictRules?: ConflictRule[]): Promise<EntityHealthReport>;
+/**
+ * Aggregate health across all entities of a type.
+ */
+declare function getEntityTypeHealth(db: PrismaClient, entityType: string, options?: {
+    limit?: number;
+    worstN?: number;
+    bestN?: number;
+}): Promise<EntityTypeHealthSummary>;
+
+declare const QueryKnowledgeSchema: z.ZodObject<{
+    entity: z.ZodString;
+    field: z.ZodOptional<z.ZodString>;
+    search: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type QueryKnowledgeInput = z.infer<typeof QueryKnowledgeSchema>;
+declare const CreateKnowledgeEntrySchema: z.ZodObject<{
+    entity: z.ZodString;
+    field: z.ZodString;
+    value: z.ZodString;
+    label: z.ZodString;
+    aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    sortOrder: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type CreateKnowledgeEntryInput = z.infer<typeof CreateKnowledgeEntrySchema>;
+declare const UpdateKnowledgeEntrySchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    sortOrder: z.ZodOptional<z.ZodNumber>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type UpdateKnowledgeEntryInput = z.infer<typeof UpdateKnowledgeEntrySchema>;
+declare const GetPreferencesSchema: z.ZodObject<{
+    entity: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+    field: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GetPreferencesInput = z.infer<typeof GetPreferencesSchema>;
+declare const SetPreferenceSchema: z.ZodObject<{
+    entity: z.ZodString;
+    field: z.ZodString;
+    value: z.ZodString;
+    label: z.ZodString;
+    conditions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    userId: z.ZodOptional<z.ZodString>;
+    priority: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type SetPreferenceInput = z.infer<typeof SetPreferenceSchema>;
+
+/**
+ * Query knowledge entries by entity, field, and optional NL search.
+ * Auto-seeds on first access if table is empty.
+ */
+declare function queryKnowledge(db: PrismaClient, input: QueryKnowledgeInput, seedProvider?: SeedDataProvider): Promise<{
+    label: string;
+    category: string | null;
+    value: string;
+    sortOrder: number;
+    isActive: boolean;
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    aliases: string[];
+    metadata: Prisma.JsonValue | null;
+}[]>;
+declare function createKnowledgeEntry(db: PrismaClient, input: CreateKnowledgeEntryInput): Promise<{
+    label: string;
+    category: string | null;
+    value: string;
+    sortOrder: number;
+    isActive: boolean;
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    aliases: string[];
+    metadata: Prisma.JsonValue | null;
+}>;
+declare function updateKnowledgeEntry(db: PrismaClient, id: string, input: UpdateKnowledgeEntryInput): Promise<{
+    label: string;
+    category: string | null;
+    value: string;
+    sortOrder: number;
+    isActive: boolean;
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    aliases: string[];
+    metadata: Prisma.JsonValue | null;
+}>;
+declare function deleteKnowledgeEntry(db: PrismaClient, id: string): Promise<{
+    label: string;
+    category: string | null;
+    value: string;
+    sortOrder: number;
+    isActive: boolean;
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    aliases: string[];
+    metadata: Prisma.JsonValue | null;
+}>;
+/**
+ * Seeds the AgentKnowledge table with default data if empty.
+ * Uses SeedDataProvider callback so package doesn't need app-specific data.
+ */
+declare function ensureKnowledgeDefaults(db: PrismaClient, seedProvider?: SeedDataProvider): Promise<void>;
+/**
+ * Reset knowledge to defaults: delete all seed entries and re-seed.
+ */
+declare function resetKnowledgeDefaults(db: PrismaClient, seedProvider?: SeedDataProvider): Promise<void>;
+/**
+ * Reset the seed-checked flag (for testing).
+ */
+declare function resetSeedCheck(): void;
+
+/**
+ * Get preferences for an entity, optionally filtered by userId.
+ * Returns org-wide (userId=null) + user-specific, sorted by priority desc.
+ */
+declare function getPreferences(db: PrismaClient, input: GetPreferencesInput): Promise<{
+    label: string;
+    value: string;
+    isActive: boolean;
+    userId: string | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    conditions: Prisma.JsonValue | null;
+    priority: number;
+}[]>;
+declare function setPreference(db: PrismaClient, input: SetPreferenceInput): Promise<{
+    label: string;
+    value: string;
+    isActive: boolean;
+    userId: string | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    conditions: Prisma.JsonValue | null;
+    priority: number;
+}>;
+declare function deletePreference(db: PrismaClient, id: string): Promise<{
+    label: string;
+    value: string;
+    isActive: boolean;
+    userId: string | null;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    field: string;
+    entity: string;
+    conditions: Prisma.JsonValue | null;
+    priority: number;
+}>;
+
+interface LogInteractionInput {
+    userId: string;
+    query: string;
+    toolsUsed?: string[];
+    sessionId?: string;
+}
+declare function logInteraction(db: PrismaClient, input: LogInteractionInput): Promise<{
+    query: string;
+    userId: string;
+    id: string;
+    createdAt: Date;
+    intent: string | null;
+    topic: string | null;
+    modules: string[];
+    toolsUsed: string[];
+    satisfied: boolean | null;
+    sessionId: string | null;
+}>;
+declare function markSatisfied(db: PrismaClient, id: string, satisfied: boolean): Promise<{
+    query: string;
+    userId: string;
+    id: string;
+    createdAt: Date;
+    intent: string | null;
+    topic: string | null;
+    modules: string[];
+    toolsUsed: string[];
+    satisfied: boolean | null;
+    sessionId: string | null;
+}>;
+declare function getTopicDistribution(db: PrismaClient, days?: number): Promise<{
+    topic: string;
+    count: number;
+    modules: string[];
+    tools: string[];
+}[]>;
+declare function getRecentInteractions(db: PrismaClient, userId: string, limit?: number): Promise<{
+    query: string;
+    userId: string;
+    id: string;
+    createdAt: Date;
+    intent: string | null;
+    topic: string | null;
+    modules: string[];
+    toolsUsed: string[];
+    satisfied: boolean | null;
+    sessionId: string | null;
+}[]>;
+declare function getInteractionCount(db: PrismaClient, days?: number): Promise<number>;
+
+declare function classifyIntent(query: string): string;
+declare function extractTopic(query: string): string | null;
+declare function extractModules(toolNames: string[]): string[];
+
+declare function analyzeAndSuggest(db: PrismaClient): Promise<number>;
+declare function getSuggestions(db: PrismaClient, status?: string): Promise<{
+    category: string;
+    status: string;
+    confidence: number;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    description: string;
+    evidence: string;
+    suggestedTools: string[];
+    queryCount: number;
+    dismissedBy: string | null;
+    dismissedAt: Date | null;
+}[]>;
+declare function dismissSuggestion(db: PrismaClient, id: string, userId: string): Promise<{
+    category: string;
+    status: string;
+    confidence: number;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    description: string;
+    evidence: string;
+    suggestedTools: string[];
+    queryCount: number;
+    dismissedBy: string | null;
+    dismissedAt: Date | null;
+}>;
+declare function approveSuggestion(db: PrismaClient, id: string): Promise<{
+    category: string;
+    status: string;
+    confidence: number;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string;
+    description: string;
+    evidence: string;
+    suggestedTools: string[];
+    queryCount: number;
+    dismissedBy: string | null;
+    dismissedAt: Date | null;
+}>;
+
+declare const AttachmentSchema: z.ZodObject<{
+    filename: z.ZodString;
+    mimeType: z.ZodString;
+    size: z.ZodNumber;
+    storagePath: z.ZodString;
+}, z.core.$strip>;
+type AttachmentInput = z.infer<typeof AttachmentSchema>;
+declare const CreateNoteSchema: z.ZodObject<{
+    content: z.ZodString;
+    contentHtml: z.ZodOptional<z.ZodString>;
+    isDraft: z.ZodDefault<z.ZodBoolean>;
+    source: z.ZodDefault<z.ZodEnum<{
+        MANUAL: "MANUAL";
+        AGENT: "AGENT";
+        SYSTEM: "SYSTEM";
+        QUOTE: "QUOTE";
+    }>>;
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        storagePath: z.ZodString;
+    }, z.core.$strip>>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type CreateNoteInput$1 = z.infer<typeof CreateNoteSchema>;
+declare const UpdateNoteSchema: z.ZodObject<{
+    content: z.ZodOptional<z.ZodString>;
+    contentHtml: z.ZodOptional<z.ZodString>;
+    isDraft: z.ZodOptional<z.ZodBoolean>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        storagePath: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type UpdateNoteInput$1 = z.infer<typeof UpdateNoteSchema>;
+declare const ListNotesQuery: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    isDraft: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, z.core.$strip>;
+type ListNotesQueryInput = z.infer<typeof ListNotesQuery>;
+
+interface CreateNoteInput {
+    entityType: string;
+    entityId: string;
+    content: string;
+    contentHtml?: string;
+    isDraft?: boolean;
+    authorId?: string | null;
+    source?: string;
+    attachments?: AttachmentInput[];
+    fields?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateNoteInput {
+    content?: string;
+    contentHtml?: string;
+    isDraft?: boolean;
+    attachments?: AttachmentInput[];
+    /** User ID performing the edit — recorded on the revision for audit. */
+    editedBy?: string;
+}
+interface ListNotesOptions {
+    entityType: string;
+    entityId: string;
+    limit?: number;
+    cursor?: string;
+    isDraft?: boolean;
+}
+declare function createNote(db: PrismaClient, input: CreateNoteInput, callbacks?: NoteKnowledgeCallbacks): Promise<{
+    attachments: {
+        id: string;
+        createdAt: Date;
+        size: number;
+        filename: string;
+        mimeType: string;
+        storagePath: string;
+        noteId: string;
+    }[];
+    author: {
+        id: string;
+        name: string;
+    } | null;
+} & {
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    clientId: string;
+    metadata: Prisma.JsonValue | null;
+    content: string;
+    contentHtml: string | null;
+    isDraft: boolean;
+    authorId: string | null;
+}>;
+declare function updateNote(db: PrismaClient, noteId: string, entityId: string, input: UpdateNoteInput, callbacks?: NoteKnowledgeCallbacks): Promise<({
+    attachments: {
+        id: string;
+        createdAt: Date;
+        size: number;
+        filename: string;
+        mimeType: string;
+        storagePath: string;
+        noteId: string;
+    }[];
+    author: {
+        id: string;
+        name: string;
+    } | null;
+    revisions: {
+        id: string;
+        content: string;
+        editedAt: Date;
+        editedBy: string | null;
+    }[];
+} & {
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    clientId: string;
+    metadata: Prisma.JsonValue | null;
+    content: string;
+    contentHtml: string | null;
+    isDraft: boolean;
+    authorId: string | null;
+}) | null>;
+declare function getNotes(db: PrismaClient, { entityId, limit, cursor, isDraft }: Omit<ListNotesOptions, 'entityType'> & {
+    entityId: string;
+}): Promise<{
+    items: ({
+        attachments: {
+            id: string;
+            createdAt: Date;
+            size: number;
+            filename: string;
+            mimeType: string;
+            storagePath: string;
+            noteId: string;
+        }[];
+        author: {
+            id: string;
+            name: string;
+        } | null;
+    } & {
+        source: string;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        clientId: string;
+        metadata: Prisma.JsonValue | null;
+        content: string;
+        contentHtml: string | null;
+        isDraft: boolean;
+        authorId: string | null;
+    })[];
+    nextCursor: string | undefined;
+    hasMore: boolean;
+}>;
+declare function deleteNote(db: PrismaClient, noteId: string, entityId: string): Promise<{
+    source: string;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    clientId: string;
+    metadata: Prisma.JsonValue | null;
+    content: string;
+    contentHtml: string | null;
+    isDraft: boolean;
+    authorId: string | null;
+} | null>;
+
+declare function getAllContacts(db: PrismaClient, options?: {
+    limit?: number;
+    offset?: number;
+    source?: ContactSource;
+    search?: string;
+    excludeConverted?: boolean;
+}): Promise<{
+    contacts: ({
+        _count: {
+            linkedEmails: number;
+        };
+        tags: ({
+            tag: {
+                id: string;
+                createdAt: Date;
+                updatedAt: Date;
+                name: string;
+                color: string;
+            };
+        } & {
+            id: string;
+            contactId: string;
+            tagId: string;
+            addedAt: Date;
+            addedBy: string | null;
+        })[];
+    } & {
+        email: string;
+        mergedIntoId: string | null;
+        source: _prisma_client.$Enums.ContactSource;
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        name: string | null;
+        phone: string | null;
+        convertedToClientId: string | null;
+        notes: string | null;
+        convertedAt: Date | null;
+        convertedBy: string | null;
+        mergedAt: Date | null;
+        mergedBy: string | null;
+    })[];
+    total: number;
+    limit: number;
+    offset: number;
+}>;
+declare function getContactById(db: PrismaClient, id: string): Promise<{
+    _count: {
+        linkedEmails: number;
+    };
+    tags: ({
+        tag: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            name: string;
+            color: string;
+        };
+    } & {
+        id: string;
+        contactId: string;
+        tagId: string;
+        addedAt: Date;
+        addedBy: string | null;
+    })[];
+    linkedEmails: {
+        status: _prisma_client.$Enums.EmailStatus;
+        id: string;
+        emailDate: Date;
+        subject: string;
+        snippet: string;
+    }[];
+} & {
+    email: string;
+    mergedIntoId: string | null;
+    source: _prisma_client.$Enums.ContactSource;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    phone: string | null;
+    convertedToClientId: string | null;
+    notes: string | null;
+    convertedAt: Date | null;
+    convertedBy: string | null;
+    mergedAt: Date | null;
+    mergedBy: string | null;
+}>;
+declare function getContactByEmail(db: PrismaClient, email: string): Promise<{
+    email: string;
+    mergedIntoId: string | null;
+    source: _prisma_client.$Enums.ContactSource;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    phone: string | null;
+    convertedToClientId: string | null;
+    notes: string | null;
+    convertedAt: Date | null;
+    convertedBy: string | null;
+    mergedAt: Date | null;
+    mergedBy: string | null;
+} | null>;
+declare function createContact(db: PrismaClient, params: {
+    email: string;
+    name?: string | null;
+    notes?: string | null;
+    source?: ContactSource;
+    fields?: Record<string, unknown>;
+}, callbacks?: NoteKnowledgeCallbacks): Promise<{
+    email: string;
+    mergedIntoId: string | null;
+    source: _prisma_client.$Enums.ContactSource;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    phone: string | null;
+    convertedToClientId: string | null;
+    notes: string | null;
+    convertedAt: Date | null;
+    convertedBy: string | null;
+    mergedAt: Date | null;
+    mergedBy: string | null;
+}>;
+declare function updateContact(db: PrismaClient, id: string, data: {
+    name?: string | null;
+    notes?: string | null;
+}): Promise<{
+    tags: ({
+        tag: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            name: string;
+            color: string;
+        };
+    } & {
+        id: string;
+        contactId: string;
+        tagId: string;
+        addedAt: Date;
+        addedBy: string | null;
+    })[];
+} & {
+    email: string;
+    mergedIntoId: string | null;
+    source: _prisma_client.$Enums.ContactSource;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    phone: string | null;
+    convertedToClientId: string | null;
+    notes: string | null;
+    convertedAt: Date | null;
+    convertedBy: string | null;
+    mergedAt: Date | null;
+    mergedBy: string | null;
+}>;
+declare function deleteContact(db: PrismaClient, id: string): Promise<{
+    success: boolean;
+}>;
+declare function findOrCreateContact(db: PrismaClient, email: string, name?: string | null, source?: ContactSource): Promise<{
+    email: string;
+    mergedIntoId: string | null;
+    source: _prisma_client.$Enums.ContactSource;
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    name: string | null;
+    phone: string | null;
+    convertedToClientId: string | null;
+    notes: string | null;
+    convertedAt: Date | null;
+    convertedBy: string | null;
+    mergedAt: Date | null;
+    mergedBy: string | null;
+}>;
+
+declare const CONTACT_FIELD_DEFINITIONS: readonly [{
+    readonly entityType: "contact";
+    readonly key: "preferred_contact_method";
+    readonly label: "Preferred Contact Method";
+    readonly dataType: "enum";
+    readonly category: "communication";
+    readonly enumOptions: readonly ["email", "phone", "text", "in-person"];
+    readonly sortOrder: 0;
+}, {
+    readonly entityType: "contact";
+    readonly key: "preferred_contact_time";
+    readonly label: "Preferred Contact Time";
+    readonly dataType: "text";
+    readonly category: "communication";
+    readonly extractionHint: "Time of day or day of week the contact prefers to be reached";
+    readonly sortOrder: 1;
+}, {
+    readonly entityType: "contact";
+    readonly key: "timezone";
+    readonly label: "Timezone";
+    readonly dataType: "text";
+    readonly category: "communication";
+    readonly sortOrder: 2;
+}, {
+    readonly entityType: "contact";
+    readonly key: "company";
+    readonly label: "Company";
+    readonly dataType: "text";
+    readonly category: "professional";
+    readonly sortOrder: 0;
+}, {
+    readonly entityType: "contact";
+    readonly key: "title";
+    readonly label: "Job Title";
+    readonly dataType: "text";
+    readonly category: "professional";
+    readonly sortOrder: 1;
+}, {
+    readonly entityType: "contact";
+    readonly key: "industry";
+    readonly label: "Industry";
+    readonly dataType: "text";
+    readonly category: "professional";
+    readonly sortOrder: 2;
+}, {
+    readonly entityType: "contact";
+    readonly key: "referral_source";
+    readonly label: "Referral Source";
+    readonly dataType: "text";
+    readonly category: "relationship";
+    readonly sortOrder: 0;
+}, {
+    readonly entityType: "contact";
+    readonly key: "relationship_type";
+    readonly label: "Relationship Type";
+    readonly dataType: "enum";
+    readonly category: "relationship";
+    readonly enumOptions: readonly ["prospect", "vendor", "partner", "personal", "other"];
+    readonly sortOrder: 1;
+}, {
+    readonly entityType: "contact";
+    readonly key: "last_interaction_notes";
+    readonly label: "Last Interaction Notes";
+    readonly dataType: "text";
+    readonly category: "relationship";
+    readonly extractionHint: "Brief summary of last meaningful interaction";
+    readonly sortOrder: 2;
+}];
+/**
+ * Seed contact field definitions into the database.
+ * Idempotent — skips existing keys via skipDuplicates.
+ * Returns the number of new definitions created.
+ */
+declare function seedContactFieldDefinitions(db: PrismaClient): Promise<number>;
+
+declare const CreateContactSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    source: z.ZodDefault<z.ZodEnum<{
+        MANUAL: "MANUAL";
+        EMAIL_SYNC: "EMAIL_SYNC";
+        AUTOMATION: "AUTOMATION";
+        IMPORT: "IMPORT";
+    }>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type CreateContactInput = z.infer<typeof CreateContactSchema>;
+declare const UpdateContactSchema: z.ZodObject<{
+    name: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    notes: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+type UpdateContactInput = z.infer<typeof UpdateContactSchema>;
+declare const ListContactsQuery: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    source: z.ZodOptional<z.ZodEnum<{
+        MANUAL: "MANUAL";
+        EMAIL_SYNC: "EMAIL_SYNC";
+        AUTOMATION: "AUTOMATION";
+        IMPORT: "IMPORT";
+    }>>;
+    search: z.ZodOptional<z.ZodString>;
+    excludeConverted: z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, z.core.$strip>;
+type ListContactsQueryInput = z.infer<typeof ListContactsQuery>;
+
+export { AGENTKNOW_ERRORS, type AgentKnowledgeErrorEntry, type AttachmentInput, AttachmentSchema, CONTACT_FIELD_DEFINITIONS, type ConflictRule, type ConstraintViolation, ContactAlreadyConvertedError, ContactExistsError, ContactNotFoundError, type CreateContactInput, CreateContactSchema, type CreateFieldDefinitionInput, CreateFieldDefinitionSchema, type CreateKnowledgeEntryInput, CreateKnowledgeEntrySchema, type CreateNoteInput$1 as CreateNoteInput, CreateNoteSchema, DEFAULT_CONFLICT_RULES, type DetectedConflict, ENTITY_TYPES, type EntityHealthReport, type EntityRelationship, type EntityTypeHealthSummary, FIELD_DATA_TYPES, FIELD_STATUSES, type FieldConstraint, FieldHistoryQuery, type FieldHistoryQueryInput, type GetPreferencesInput, GetPreferencesSchema, type GhostFieldPrediction, KNOWLEDGE_ERRORS, type KnowledgeErrorDef, LEDGER_SOURCES, ListContactsQuery, type ListContactsQueryInput, ListFieldDefinitionsQuery, type ListFieldDefinitionsQueryInput, ListNotesQuery, type ListNotesQueryInput, type LogSearchQueryInput, LogSearchQuerySchema, type MutationCallbacks, type NoteKnowledgeCallbacks, type ObserverCallbacks, type QueryKnowledgeInput, QueryKnowledgeSchema, SEARCH_SOURCES, SOURCE_RELIABILITY, type SearchByFieldsInput, SearchByFieldsSchema, type SeedDataProvider, type SetEntityFieldsInput, SetEntityFieldsSchema, type SetPreferenceInput, SetPreferenceSchema, type UpdateContactInput, UpdateContactSchema, type UpdateFieldDefinitionInput, UpdateFieldDefinitionSchema, type UpdateKnowledgeEntryInput, UpdateKnowledgeEntrySchema, type UpdateNoteInput$1 as UpdateNoteInput, UpdateNoteSchema, type ValidationCallbacks, agentKnowledgeError, analyzeAndSuggest, approveSuggestion, buildCoOccurrenceMap, checkConstraints, classifyIntent, computeComplexityScore, computeDecayedConfidence, computeEntityHealth, computeEntityTruthScores, computeOverallScore, computeRecencyFactor, computeRelationshipStrength, computeTruthScore, createContact, createFieldDefinition, createKnowledgeEntry, createNote, deleteContact, deleteKnowledgeEntry, deleteNote, deletePreference, detectConflicts, dismissSuggestion, ensureKnowledgeDefaults, evaluateConflictRule, evaluateConstraint, extractModules, extractTopic, findOrCreateContact, findRelatedEntities, fireObservers, formatStalenessWarnings, getAllContacts, getContactByEmail, getContactById, getEntityFields, getEntityRelationships, getEntityTypeHealth, getFieldDefinitionById, getFieldDefinitions, getFieldHistory, getFieldValueAt, getInteractionCount, getKnowledgeAt, getKnowledgeTimeline, getNotes, getPreferences, getRecentInteractions, getStaleFields, getSuggestions, getTopicDistribution, getWeekOfYear, isStale, knowledgeError, logInteraction, logSearchQuery, markSatisfied, predictGhostFields, queryKnowledge, resetKnowledgeDefaults, resetSeedCheck, scanForConflicts, searchByFields, seedContactFieldDefinitions, setEntityFields, setEntityFieldsWithBranching, setPreference, shouldBranch, updateContact, updateFieldDefinition, updateKnowledgeEntry, updateNote, writeGhostFields };