@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/entities/store.js

@@ -0,0 +1,465 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityMergeError = void 0;
+exports.parseObservationRow = parseObservationRow;
+exports.createEntityNode = createEntityNode;
+exports.getEntityNode = getEntityNode;
+exports.listEntityNodes = listEntityNodes;
+exports.attachEntityAlias = attachEntityAlias;
+exports.listEntityAliases = listEntityAliases;
+exports.upsertEntityObservation = upsertEntityObservation;
+exports.upsertEntityObservations = upsertEntityObservations;
+exports.appendEntityTimelineEvent = appendEntityTimelineEvent;
+exports.resolveCanonicalEntityId = resolveCanonicalEntityId;
+exports.mergeEntityNodes = mergeEntityNodes;
+const node_crypto_1 = require("node:crypto");
+const db_manager_js_1 = require("../db-manager.js");
+const types_js_1 = require("./types.js");
+class EntityMergeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'EntityMergeError';
+    }
+}
+exports.EntityMergeError = EntityMergeError;
+const MAX_MERGE_CHAIN_DEPTH = 8;
+function now() {
+    return Date.now();
+}
+function normalizeSourceLocator(value) {
+    // Write empty-string as the null sentinel so SQLite UNIQUE can collapse null-like locators; parseObservationRow maps it back to null on read.
+    return value ?? '';
+}
+function requireStringField(row, field) {
+    if (typeof row[field] !== 'string' || row[field].length === 0) {
+        throw new Error(`Invalid entity observation row: ${field} must be a non-empty string`);
+    }
+    return row[field];
+}
+function optionalStringField(row, field) {
+    if (!Object.prototype.hasOwnProperty.call(row, field)) {
+        throw new Error(`Invalid entity observation row: ${field} must be present`);
+    }
+    if (row[field] === null) {
+        return null;
+    }
+    if (typeof row[field] !== 'string') {
+        throw new Error(`Invalid entity observation row: ${field} must be a string or null`);
+    }
+    return row[field];
+}
+function optionalStringFieldIfPresent(row, field) {
+    if (!Object.prototype.hasOwnProperty.call(row, field)) {
+        return undefined;
+    }
+    if (row[field] === null) {
+        return null;
+    }
+    if (typeof row[field] !== 'string') {
+        throw new Error(`Invalid entity observation row: ${field} must be a string or null`);
+    }
+    return row[field];
+}
+function optionalNumberField(row, field) {
+    if (!Object.prototype.hasOwnProperty.call(row, field)) {
+        throw new Error(`Invalid entity observation row: ${field} must be present`);
+    }
+    if (row[field] === null) {
+        return null;
+    }
+    if (typeof row[field] !== 'number') {
+        throw new Error(`Invalid entity observation row: ${field} must be a number or null`);
+    }
+    return row[field];
+}
+function parseObservationRow(row) {
+    const id = requireStringField(row, 'id');
+    const observationType = requireStringField(row, 'observation_type');
+    if (!types_js_1.ENTITY_OBSERVATION_TYPES.includes(observationType)) {
+        throw new Error(`Invalid entity observation row: observation_type=${observationType}`);
+    }
+    const entityKindHint = optionalStringField(row, 'entity_kind_hint');
+    if (entityKindHint !== null &&
+        !types_js_1.ENTITY_KINDS.includes(entityKindHint)) {
+        throw new Error(`Invalid entity observation row: entity_kind_hint=${entityKindHint}`);
+    }
+    const scopeKind = optionalStringField(row, 'scope_kind');
+    if (scopeKind === null) {
+        throw new Error('Invalid entity observation row: scope_kind must not be null');
+    }
+    if (!types_js_1.ENTITY_SCOPE_KINDS.includes(scopeKind)) {
+        throw new Error(`Invalid entity observation row: scope_kind=${scopeKind}`);
+    }
+    const createdAt = row.created_at;
+    if (typeof createdAt !== 'number') {
+        throw new Error('Invalid entity observation row: created_at must be a number');
+    }
+    let relatedSurfaceForms = [];
+    if (typeof row.related_surface_forms === 'string') {
+        try {
+            const parsed = JSON.parse(row.related_surface_forms);
+            if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== 'string')) {
+                throw new Error('parsed value is not a string[]');
+            }
+            relatedSurfaceForms = parsed;
+        }
+        catch (error) {
+            throw new Error(`Invalid entity observation row: related_surface_forms must be valid JSON string[] (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    else if (row.related_surface_forms !== undefined && row.related_surface_forms !== null) {
+        throw new Error('Invalid entity observation row: related_surface_forms must be a JSON string or null');
+    }
+    const sourceLocator = optionalStringFieldIfPresent(row, 'source_locator');
+    if (sourceLocator === undefined) {
+        throw new Error('Invalid entity observation row: source_locator must be present');
+    }
+    return {
+        id,
+        observation_type: observationType,
+        entity_kind_hint: entityKindHint,
+        surface_form: requireStringField(row, 'surface_form'),
+        normalized_form: requireStringField(row, 'normalized_form'),
+        lang: optionalStringField(row, 'lang'),
+        script: optionalStringField(row, 'script'),
+        context_summary: optionalStringField(row, 'context_summary'),
+        related_surface_forms: relatedSurfaceForms,
+        timestamp_observed: optionalNumberField(row, 'timestamp_observed'),
+        scope_kind: scopeKind,
+        scope_id: optionalStringField(row, 'scope_id'),
+        extractor_version: requireStringField(row, 'extractor_version'),
+        embedding_model_version: optionalStringField(row, 'embedding_model_version'),
+        source_connector: requireStringField(row, 'source_connector'),
+        source_locator: sourceLocator && sourceLocator.length > 0 ? sourceLocator : null,
+        source_raw_record_id: requireStringField(row, 'source_raw_record_id'),
+        created_at: createdAt,
+    };
+}
+async function createEntityNode(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const createdAt = now();
+    adapter
+        .prepare(`
+        INSERT INTO entity_nodes (
+          id, kind, preferred_label, status, scope_kind, scope_id, merged_into, created_at, updated_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(input.id, input.kind, input.preferred_label, input.status, input.scope_kind, input.scope_id, input.merged_into, createdAt, createdAt);
+    return {
+        ...input,
+        created_at: createdAt,
+        updated_at: createdAt,
+    };
+}
+function getEntityNode(id, adapter = (0, db_manager_js_1.getAdapter)()) {
+    const row = adapter.prepare('SELECT * FROM entity_nodes WHERE id = ?').get(id);
+    if (!row) {
+        return null;
+    }
+    return {
+        id: String(row.id),
+        kind: row.kind,
+        preferred_label: String(row.preferred_label),
+        status: row.status,
+        scope_kind: typeof row.scope_kind === 'string' ? row.scope_kind : null,
+        scope_id: typeof row.scope_id === 'string' ? row.scope_id : null,
+        merged_into: typeof row.merged_into === 'string' ? row.merged_into : null,
+        created_at: Number(row.created_at),
+        updated_at: Number(row.updated_at),
+    };
+}
+function listEntityNodes() {
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const rows = adapter
+        .prepare('SELECT * FROM entity_nodes ORDER BY created_at DESC')
+        .all();
+    return rows.map((row) => ({
+        id: String(row.id),
+        kind: row.kind,
+        preferred_label: String(row.preferred_label),
+        status: row.status,
+        scope_kind: typeof row.scope_kind === 'string' ? row.scope_kind : null,
+        scope_id: typeof row.scope_id === 'string' ? row.scope_id : null,
+        merged_into: typeof row.merged_into === 'string' ? row.merged_into : null,
+        created_at: Number(row.created_at),
+        updated_at: Number(row.updated_at),
+    }));
+}
+async function attachEntityAlias(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const createdAt = now();
+    adapter
+        .prepare(`
+        INSERT INTO entity_aliases (
+          id, entity_id, label, normalized_label, lang, script, label_type,
+          source_type, source_ref, confidence, status, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(input.id, input.entity_id, input.label, input.normalized_label, input.lang, input.script, input.label_type, input.source_type, input.source_ref, input.confidence, input.status, createdAt);
+    return {
+        ...input,
+        created_at: createdAt,
+    };
+}
+function listEntityAliases(entityId, adapter = (0, db_manager_js_1.getAdapter)()) {
+    const rows = adapter
+        .prepare('SELECT * FROM entity_aliases WHERE entity_id = ? ORDER BY created_at ASC')
+        .all(entityId);
+    return rows.map((row) => ({
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        label: String(row.label),
+        normalized_label: String(row.normalized_label),
+        lang: typeof row.lang === 'string' ? row.lang : null,
+        script: typeof row.script === 'string' ? row.script : null,
+        label_type: row.label_type,
+        source_type: String(row.source_type),
+        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
+        confidence: typeof row.confidence === 'number' ? row.confidence : null,
+        status: row.status,
+        created_at: Number(row.created_at),
+    }));
+}
+async function upsertEntityObservation(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const createdAt = now();
+    const normalizedSourceLocator = normalizeSourceLocator(input.source_locator);
+    adapter
+        .prepare(`
+        INSERT INTO entity_observations (
+          id, observation_type, entity_kind_hint, surface_form, normalized_form, lang, script,
+          context_summary, related_surface_forms, timestamp_observed, scope_kind, scope_id,
+          extractor_version, embedding_model_version, source_connector, source_locator,
+          source_raw_record_id, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(source_connector, source_locator, source_raw_record_id, observation_type)
+        DO UPDATE SET
+          entity_kind_hint = excluded.entity_kind_hint,
+          surface_form = excluded.surface_form,
+          normalized_form = excluded.normalized_form,
+          lang = excluded.lang,
+          script = excluded.script,
+          context_summary = excluded.context_summary,
+          related_surface_forms = excluded.related_surface_forms,
+          timestamp_observed = excluded.timestamp_observed,
+          scope_kind = excluded.scope_kind,
+          scope_id = excluded.scope_id,
+          extractor_version = excluded.extractor_version,
+          embedding_model_version = excluded.embedding_model_version,
+          source_locator = excluded.source_locator,
+          created_at = entity_observations.created_at
+      `)
+        .run(input.id, input.observation_type, input.entity_kind_hint, input.surface_form, input.normalized_form, input.lang, input.script, input.context_summary, JSON.stringify(input.related_surface_forms), input.timestamp_observed, input.scope_kind, input.scope_id, input.extractor_version, input.embedding_model_version, input.source_connector, normalizedSourceLocator, input.source_raw_record_id, createdAt);
+    const saved = adapter
+        .prepare(`
+        SELECT * FROM entity_observations
+        WHERE source_connector = ? AND source_locator = ? AND source_raw_record_id = ? AND observation_type = ?
+      `)
+        .get(input.source_connector, normalizedSourceLocator, input.source_raw_record_id, input.observation_type);
+    return parseObservationRow(saved);
+}
+async function upsertEntityObservations(inputs) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const observations = [];
+    const upsertOne = (input) => {
+        const normalizedSourceLocator = normalizeSourceLocator(input.source_locator);
+        const existing = adapter
+            .prepare(`
+          SELECT id FROM entity_observations
+          WHERE source_connector = ? AND source_locator = ? AND source_raw_record_id = ? AND observation_type = ?
+        `)
+            .get(input.source_connector, normalizedSourceLocator, input.source_raw_record_id, input.observation_type);
+        const createdAt = now();
+        adapter
+            .prepare(`
+          INSERT INTO entity_observations (
+            id, observation_type, entity_kind_hint, surface_form, normalized_form, lang, script,
+            context_summary, related_surface_forms, timestamp_observed, scope_kind, scope_id,
+            extractor_version, embedding_model_version, source_connector, source_locator,
+            source_raw_record_id, created_at
+          )
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(source_connector, source_locator, source_raw_record_id, observation_type)
+          DO UPDATE SET
+            entity_kind_hint = excluded.entity_kind_hint,
+            surface_form = excluded.surface_form,
+            normalized_form = excluded.normalized_form,
+            lang = excluded.lang,
+            script = excluded.script,
+            context_summary = excluded.context_summary,
+            related_surface_forms = excluded.related_surface_forms,
+            timestamp_observed = excluded.timestamp_observed,
+            scope_kind = excluded.scope_kind,
+            scope_id = excluded.scope_id,
+            extractor_version = excluded.extractor_version,
+            embedding_model_version = excluded.embedding_model_version,
+            source_locator = excluded.source_locator,
+            created_at = entity_observations.created_at
+        `)
+            .run(input.id, input.observation_type, input.entity_kind_hint, input.surface_form, input.normalized_form, input.lang, input.script, input.context_summary, JSON.stringify(input.related_surface_forms), input.timestamp_observed, input.scope_kind, input.scope_id, input.extractor_version, input.embedding_model_version, input.source_connector, normalizedSourceLocator, input.source_raw_record_id, createdAt);
+        const saved = adapter
+            .prepare(`
+          SELECT * FROM entity_observations
+          WHERE source_connector = ? AND source_locator = ? AND source_raw_record_id = ? AND observation_type = ?
+        `)
+            .get(input.source_connector, normalizedSourceLocator, input.source_raw_record_id, input.observation_type);
+        observations.push({
+            id: requireStringField(saved, 'id'),
+            created: !existing,
+        });
+    };
+    if ('transaction' in adapter && typeof adapter.transaction === 'function') {
+        const txResult = adapter.transaction(() => {
+            for (const input of inputs) {
+                upsertOne(input);
+            }
+        });
+        if (typeof txResult === 'function') {
+            txResult();
+        }
+        return observations;
+    }
+    for (const input of inputs) {
+        upsertOne(input);
+    }
+    return observations;
+}
+async function appendEntityTimelineEvent(input) {
+    if (!input.adapter) {
+        await (0, db_manager_js_1.initDB)();
+    }
+    const adapter = input.adapter ?? (0, db_manager_js_1.getAdapter)();
+    const eventId = input.event.id ?? `et_${(0, node_crypto_1.randomUUID)()}`;
+    const createdAt = input.event.created_at ?? now();
+    adapter
+        .prepare(`
+        INSERT INTO entity_timeline_events (
+          id, entity_id, event_type, role, valid_from, valid_to, observed_at,
+          source_ref, summary, details, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(eventId, input.event.entity_id, input.event.event_type, input.event.role ?? null, input.event.valid_from ?? null, input.event.valid_to ?? null, input.event.observed_at ?? null, input.event.source_ref ?? null, input.event.summary, input.event.details ?? null, createdAt);
+    return {
+        id: eventId,
+        entity_id: input.event.entity_id,
+        event_type: input.event.event_type,
+        role: input.event.role ?? null,
+        valid_from: input.event.valid_from ?? null,
+        valid_to: input.event.valid_to ?? null,
+        observed_at: input.event.observed_at ?? null,
+        source_ref: input.event.source_ref ?? null,
+        summary: input.event.summary,
+        details: input.event.details ?? null,
+        created_at: createdAt,
+    };
+}
+/**
+ * Walks the `entity_nodes.merged_into` chain from the given id and returns the
+ * terminal (unmerged) entity id. Detects cycles and caps depth. Read-only.
+ *
+ * Matches the read-time chain-walking approach described in the canonical
+ * entity ontology implementation plan.
+ */
+function resolveCanonicalEntityId(adapter, id) {
+    const seen = new Set();
+    let current = id;
+    for (let depth = 0; depth < MAX_MERGE_CHAIN_DEPTH; depth++) {
+        if (seen.has(current)) {
+            throw new EntityMergeError('entity.merge_chain_cycle', `Cycle detected in merged_into chain starting at ${id}`);
+        }
+        seen.add(current);
+        const row = adapter
+            .prepare('SELECT merged_into FROM entity_nodes WHERE id = ?')
+            .get(current);
+        if (!row) {
+            throw new EntityMergeError('entity.node_not_found', `Entity node ${current} not found while resolving canonical id for ${id}`);
+        }
+        if (!row.merged_into) {
+            return current;
+        }
+        current = row.merged_into;
+    }
+    throw new EntityMergeError('entity.merge_chain_too_deep', `merged_into chain exceeds depth ${MAX_MERGE_CHAIN_DEPTH} starting at ${id}`);
+}
+/**
+ * Marks `source_id` as merged into `target_id`, emits a timeline event, and
+ * inserts the entity_merge_actions audit row with both entity IDs populated.
+ *
+ * Intentionally NOT wrapped in its own transaction — the caller is expected
+ * to wrap the call in `adapter.transaction(...)` so the candidate status
+ * update and this merge land atomically (Policy B1, hard transaction).
+ *
+ * Validates: source != target, both exist, both active/unmerged, same kind,
+ * same scope. Throws `EntityMergeError` with a stable `code` on any violation.
+ */
+function mergeEntityNodes(input) {
+    const { adapter, source_id, target_id, actor_type, actor_id, reason, candidate_id, evidence_json, } = input;
+    if (!source_id || !target_id) {
+        throw new EntityMergeError('entity.merge_invalid_args', 'source_id and target_id are required');
+    }
+    if (source_id === target_id) {
+        throw new EntityMergeError('entity.merge_self', 'Cannot merge an entity into itself');
+    }
+    const source = adapter.prepare('SELECT * FROM entity_nodes WHERE id = ?').get(source_id);
+    if (!source) {
+        throw new EntityMergeError('entity.merge_source_not_found', `Source entity ${source_id} not found`);
+    }
+    const target = adapter.prepare('SELECT * FROM entity_nodes WHERE id = ?').get(target_id);
+    if (!target) {
+        throw new EntityMergeError('entity.merge_target_not_found', `Target entity ${target_id} not found`);
+    }
+    if (source.status === 'merged' || source.merged_into) {
+        throw new EntityMergeError('entity.merge_source_already_merged', `Source entity ${source_id} is already merged`);
+    }
+    if (target.status === 'merged' || target.merged_into) {
+        throw new EntityMergeError('entity.merge_target_already_merged', `Target entity ${target_id} is already merged`);
+    }
+    if (source.status === 'archived' || target.status === 'archived') {
+        throw new EntityMergeError('entity.merge_archived', 'Cannot merge archived entities');
+    }
+    if (source.kind !== target.kind) {
+        throw new EntityMergeError('entity.merge_kind_mismatch', `Cannot merge ${source.kind} into ${target.kind}`);
+    }
+    if (source.scope_kind !== target.scope_kind || source.scope_id !== target.scope_id) {
+        throw new EntityMergeError('entity.merge_scope_mismatch', `Cannot merge across scopes: ${source.scope_kind}/${source.scope_id ?? 'null'} vs ${target.scope_kind}/${target.scope_id ?? 'null'}`);
+    }
+    const mergedAt = now();
+    const mergeActionId = `mact_${(0, node_crypto_1.randomUUID)()}`;
+    const timelineEventId = `et_${(0, node_crypto_1.randomUUID)()}`;
+    adapter
+        .prepare(`UPDATE entity_nodes SET merged_into = ?, status = 'merged', updated_at = ? WHERE id = ?`)
+        .run(target_id, mergedAt, source_id);
+    adapter
+        .prepare(`
+        INSERT INTO entity_timeline_events (
+          id, entity_id, event_type, role, observed_at, source_ref, summary, details, created_at
+        )
+        VALUES (?, ?, 'merged', NULL, ?, ?, ?, ?, ?)
+      `)
+        .run(timelineEventId, source_id, mergedAt, candidate_id, `Merged into ${target_id}`, JSON.stringify({ target_entity_id: target_id, reason, actor_id, actor_type }), mergedAt);
+    adapter
+        .prepare(`
+        INSERT INTO entity_merge_actions (
+          id, action_type, source_entity_id, target_entity_id, candidate_id,
+          actor_type, actor_id, reason, evidence_json, created_at
+        )
+        VALUES (?, 'merge', ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(mergeActionId, source_id, target_id, candidate_id, actor_type, actor_id, reason, evidence_json, mergedAt);
+    return {
+        merge_action_id: mergeActionId,
+        timeline_event_id: timelineEventId,
+        merged_at: mergedAt,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/entities/types.d.ts

@@ -0,0 +1,162 @@
+export declare const ENTITY_KINDS: readonly ["project", "person", "organization", "work_item"];
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+export declare const ENTITY_ALIAS_LABEL_TYPES: readonly ["pref", "alt", "hidden", "source_native"];
+export type EntityAliasLabelType = (typeof ENTITY_ALIAS_LABEL_TYPES)[number];
+export declare const ENTITY_CANDIDATE_STATUSES: readonly ["pending", "auto_merged", "approved", "rejected", "deferred"];
+export type EntityCandidateStatus = (typeof ENTITY_CANDIDATE_STATUSES)[number];
+export declare const ENTITY_MERGE_ACTION_TYPES: readonly ["merge", "reject", "defer", "split"];
+export type EntityMergeActionType = (typeof ENTITY_MERGE_ACTION_TYPES)[number];
+export declare const ENTITY_SCOPE_KINDS: readonly ["project", "channel", "user", "global"];
+export type EntityScopeKind = (typeof ENTITY_SCOPE_KINDS)[number];
+export declare const ENTITY_NODE_STATUSES: readonly ["active", "merged", "archived"];
+export type EntityNodeStatus = (typeof ENTITY_NODE_STATUSES)[number];
+export declare const ENTITY_ALIAS_STATUSES: readonly ["active", "suppressed"];
+export type EntityAliasStatus = (typeof ENTITY_ALIAS_STATUSES)[number];
+export declare const ENTITY_OBSERVATION_TYPES: readonly ["generic", "author", "channel"];
+export type EntityObservationType = (typeof ENTITY_OBSERVATION_TYPES)[number];
+export declare const ENTITY_CANDIDATE_KINDS: readonly ["alias_to_entity", "entity_to_entity", "cluster"];
+export type EntityCandidateKind = (typeof ENTITY_CANDIDATE_KINDS)[number];
+export declare const ENTITY_ACTOR_TYPES: readonly ["system", "user", "agent"];
+export type EntityActorType = (typeof ENTITY_ACTOR_TYPES)[number];
+export declare const ENTITY_INGEST_RUN_STATUSES: readonly ["running", "complete", "failed"];
+export type EntityIngestRunStatus = (typeof ENTITY_INGEST_RUN_STATUSES)[number];
+export declare const ENTITY_INGEST_RUN_KINDS: readonly ["live", "replay", "backfill"];
+export type EntityIngestRunKind = (typeof ENTITY_INGEST_RUN_KINDS)[number];
+export declare const ENTITY_LINEAGE_CONTRIBUTION_KINDS: readonly ["seed", "merge_adopt", "manual_attach", "rollback_restore"];
+export type EntityLineageContributionKind = (typeof ENTITY_LINEAGE_CONTRIBUTION_KINDS)[number];
+export declare const ENTITY_LINEAGE_STATUSES: readonly ["active", "superseded", "rolled_back"];
+export type EntityLineageStatus = (typeof ENTITY_LINEAGE_STATUSES)[number];
+export declare const ENTITY_LINEAGE_CAPTURE_MODES: readonly ["direct", "backfilled"];
+export type EntityLineageCaptureMode = (typeof ENTITY_LINEAGE_CAPTURE_MODES)[number];
+export interface EntityNode {
+    id: string;
+    kind: EntityKind;
+    preferred_label: string;
+    status: EntityNodeStatus;
+    scope_kind: EntityScopeKind | null;
+    scope_id: string | null;
+    merged_into: string | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityAlias {
+    id: string;
+    entity_id: string;
+    label: string;
+    normalized_label: string;
+    lang: string | null;
+    script: string | null;
+    label_type: EntityAliasLabelType;
+    source_type: string;
+    source_ref: string | null;
+    confidence: number | null;
+    status: EntityAliasStatus;
+    created_at: number;
+}
+export interface EntityObservation {
+    id: string;
+    observation_type: EntityObservationType;
+    entity_kind_hint: EntityKind | null;
+    surface_form: string;
+    normalized_form: string;
+    lang: string | null;
+    script: string | null;
+    context_summary: string | null;
+    related_surface_forms: string[];
+    timestamp_observed: number | null;
+    scope_kind: EntityScopeKind;
+    scope_id: string | null;
+    extractor_version: string;
+    embedding_model_version: string | null;
+    source_connector: string;
+    source_locator: string | null;
+    source_raw_record_id: string;
+    created_at: number;
+}
+export interface EntityResolutionCandidate {
+    id: string;
+    candidate_kind: EntityCandidateKind;
+    left_ref: string;
+    right_ref: string;
+    status: EntityCandidateStatus;
+    score_total: number;
+    score_structural: number;
+    score_string: number;
+    score_context: number;
+    score_graph: number;
+    score_embedding: number;
+    rule_trace: string | null;
+    extractor_version: string;
+    embedding_model_version: string | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityLink {
+    id: string;
+    from_entity_id: string;
+    to_entity_id: string;
+    relation_type: string;
+    confidence: number;
+    source_basis: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityTimelineEvent {
+    id: string;
+    entity_id: string;
+    event_type: string;
+    role?: string | null;
+    valid_from: number | null;
+    valid_to: number | null;
+    observed_at: number | null;
+    source_ref: string | null;
+    summary: string;
+    details: string | null;
+    created_at: number;
+}
+export interface EntityMergeAction {
+    id: string;
+    action_type: EntityMergeActionType;
+    source_entity_id: string | null;
+    target_entity_id: string | null;
+    candidate_id: string | null;
+    actor_type: EntityActorType;
+    actor_id: string | null;
+    reason: string;
+    evidence_json: string;
+    created_at: number;
+}
+export interface EntityIngestRun {
+    id: string;
+    connector: string;
+    run_kind: EntityIngestRunKind;
+    status: EntityIngestRunStatus;
+    scope_key: string;
+    source_window_start: number | null;
+    source_window_end: number | null;
+    raw_count: number;
+    observation_count: number;
+    candidate_count: number;
+    reviewable_count: number;
+    audit_run_id: string | null;
+    audit_classification: 'improved' | 'stable' | 'regressed' | 'inconclusive' | null;
+    error_reason: string | null;
+    created_at: number;
+    completed_at: number | null;
+}
+export interface EntityLineageLink {
+    id: string;
+    canonical_entity_id: string;
+    entity_observation_id: string;
+    source_entity_id: string | null;
+    contribution_kind: EntityLineageContributionKind;
+    run_id: string | null;
+    candidate_id: string | null;
+    review_action_id: string | null;
+    status: EntityLineageStatus;
+    capture_mode: EntityLineageCaptureMode;
+    confidence: number;
+    created_at: number;
+    superseded_at: number | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/entities/types.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITY_LINEAGE_CAPTURE_MODES = exports.ENTITY_LINEAGE_STATUSES = exports.ENTITY_LINEAGE_CONTRIBUTION_KINDS = exports.ENTITY_INGEST_RUN_KINDS = exports.ENTITY_INGEST_RUN_STATUSES = exports.ENTITY_ACTOR_TYPES = exports.ENTITY_CANDIDATE_KINDS = exports.ENTITY_OBSERVATION_TYPES = exports.ENTITY_ALIAS_STATUSES = exports.ENTITY_NODE_STATUSES = exports.ENTITY_SCOPE_KINDS = exports.ENTITY_MERGE_ACTION_TYPES = exports.ENTITY_CANDIDATE_STATUSES = exports.ENTITY_ALIAS_LABEL_TYPES = exports.ENTITY_KINDS = void 0;
+exports.ENTITY_KINDS = ['project', 'person', 'organization', 'work_item'];
+exports.ENTITY_ALIAS_LABEL_TYPES = ['pref', 'alt', 'hidden', 'source_native'];
+exports.ENTITY_CANDIDATE_STATUSES = [
+    'pending',
+    'auto_merged',
+    'approved',
+    'rejected',
+    'deferred',
+];
+exports.ENTITY_MERGE_ACTION_TYPES = ['merge', 'reject', 'defer', 'split'];
+exports.ENTITY_SCOPE_KINDS = ['project', 'channel', 'user', 'global'];
+exports.ENTITY_NODE_STATUSES = ['active', 'merged', 'archived'];
+exports.ENTITY_ALIAS_STATUSES = ['active', 'suppressed'];
+exports.ENTITY_OBSERVATION_TYPES = ['generic', 'author', 'channel'];
+exports.ENTITY_CANDIDATE_KINDS = ['alias_to_entity', 'entity_to_entity', 'cluster'];
+exports.ENTITY_ACTOR_TYPES = ['system', 'user', 'agent'];
+exports.ENTITY_INGEST_RUN_STATUSES = ['running', 'complete', 'failed'];
+exports.ENTITY_INGEST_RUN_KINDS = ['live', 'replay', 'backfill'];
+exports.ENTITY_LINEAGE_CONTRIBUTION_KINDS = [
+    'seed',
+    'merge_adopt',
+    'manual_attach',
+    'rollback_restore',
+];
+exports.ENTITY_LINEAGE_STATUSES = ['active', 'superseded', 'rolled_back'];
+exports.ENTITY_LINEAGE_CAPTURE_MODES = ['direct', 'backfilled'];
+//# sourceMappingURL=types.js.map