aifastdb 3.8.9 → 3.10.0

package/dist/social-types.d.ts

@@ -29,6 +29,766 @@ export interface Relation {
     metadata: Record<string, unknown>;
     created_at: number;
 }
+/** Standard relation families for historical graph exploration. */
+export type HistoricalRelationFamily = 'kinship' | 'political' | 'event' | 'narrative' | 'evidence' | 'temporal' | 'spatial';
+/** Recommended entity types for historical graph ingestion. */
+export type HistoricalEntityType = 'person' | 'event' | 'document' | 'location' | 'date' | 'fact' | 'claim' | 'evidence' | 'organization' | 'office' | 'artifact';
+/** Standard direction selector for historical relation queries. */
+export type RelationDirection = 'outgoing' | 'incoming' | 'both';
+/** Canonical historical relation type names. */
+export declare const HISTORICAL_RELATION_TYPES: {
+    readonly participatedIn: "participated_in";
+    readonly involvesPerson: "involves_person";
+    readonly mentionedIn: "mentioned_in";
+    readonly describedIn: "described_in";
+    readonly sourceOf: "source_of";
+    readonly occurredAt: "occurred_at";
+    readonly occurredOn: "occurred_on";
+    readonly occurredInYear: "occurred_in_year";
+    readonly supportedBy: "supported_by";
+    readonly derivedFromClaim: "derived_from_claim";
+    readonly conflictsWith: "conflicts_with";
+    readonly sameAs: "same_as";
+    readonly aliasOf: "alias_of";
+    readonly servedUnder: "served_under";
+    readonly appointedBy: "appointed_by";
+    readonly recommendedBy: "recommended_by";
+    readonly alliedWith: "allied_with";
+    readonly opposedTo: "opposed_to";
+    readonly betrayed: "betrayed";
+    readonly rebelledAgainst: "rebelled_against";
+    readonly defeated: "defeated";
+    readonly killed: "killed";
+    readonly captured: "captured";
+    readonly predecessorOf: "predecessor_of";
+    readonly succeededBy: "succeeded_by";
+    readonly partOfCampaign: "part_of_campaign";
+    readonly narrativeParallel: "narrative_parallel";
+    readonly resembles: "resembles";
+};
+/** Standard metadata stored on historical relations. */
+export interface HistoricalRelationMetadata {
+    relationFamily?: HistoricalRelationFamily;
+    subtype?: string;
+    role?: string;
+    stance?: string;
+    side?: string;
+    narrativeWeight?: number;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+    evidenceIds?: string[];
+    claimId?: string;
+    canonicalFactId?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    confidence?: number;
+    isInferred?: boolean;
+    inferenceMethod?: string;
+    importBatchId?: string;
+    externalSource?: string;
+    [key: string]: unknown;
+}
+/** Input contract for writing a standardized historical relation. */
+export interface HistoricalRelationInput extends HistoricalRelationMetadata {
+    sourceId: string;
+    targetId: string;
+    relationType: string;
+    weight?: number;
+    bidirectional?: boolean;
+    deterministicKey?: string;
+    upsert?: boolean;
+}
+/** Shared filter contract for advanced historical relation queries. */
+export interface HistoricalRelationFilter {
+    relationTypes?: string[];
+    relationFamilies?: HistoricalRelationFamily[];
+    excludeRelationTypes?: string[];
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    minConfidence?: number;
+    isInferred?: boolean;
+    direction?: RelationDirection;
+    metadataMatch?: Record<string, unknown>;
+    offset?: number;
+    limit?: number;
+    includeRelatedEntities?: boolean;
+    includeTimeline?: boolean;
+    includeEvidence?: boolean;
+    includeClaims?: boolean;
+    includeFacts?: boolean;
+    includeChapters?: boolean;
+    includeConflictClusters?: boolean;
+    includeSourceBundle?: boolean;
+}
+/** Shared filter contract for historical path queries. */
+export interface HistoricalPathFilter extends HistoricalRelationFilter {
+    maxHops?: number;
+    bidirectionalSearch?: boolean;
+    includeInferred?: boolean;
+}
+/** Input contract for writing a standardized historical entity. */
+export interface HistoricalEntityInput {
+    entityId?: string;
+    deterministicKey?: string;
+    entityType: string;
+    name: string;
+    displayName?: string;
+    description?: string;
+    canonicalName?: string;
+    aliasNames?: string[];
+    timeLabel?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    sourceName?: string;
+    sourceRecordId?: string;
+    sourceUri?: string;
+    canonicalEntityId?: string;
+    upsert?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Input contract for writing a first-class historical claim node. */
+export interface HistoricalClaimInput {
+    entityId?: string;
+    deterministicKey?: string;
+    name: string;
+    displayName?: string;
+    description?: string;
+    canonicalName?: string;
+    aliasNames?: string[];
+    timeLabel?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    sourceName?: string;
+    sourceRecordId?: string;
+    sourceUri?: string;
+    canonicalEntityId?: string;
+    upsert?: boolean;
+    metadata?: Record<string, unknown>;
+    subjectEntityId?: string;
+    objectEntityId?: string;
+    relationType?: string;
+    evidenceIds?: string[];
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+    canonicalFactId?: string;
+}
+/** Input contract for writing a first-class historical fact node. */
+export interface HistoricalFactInput {
+    entityId?: string;
+    deterministicKey?: string;
+    name: string;
+    displayName?: string;
+    description?: string;
+    canonicalName?: string;
+    aliasNames?: string[];
+    timeLabel?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    sourceName?: string;
+    sourceRecordId?: string;
+    sourceUri?: string;
+    canonicalEntityId?: string;
+    upsert?: boolean;
+    metadata?: Record<string, unknown>;
+    subjectEntityId?: string;
+    objectEntityId?: string;
+    relationType?: string;
+    claimIds?: string[];
+    evidenceIds?: string[];
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+}
+/** Input contract for writing a first-class historical evidence node. */
+export interface HistoricalEvidenceInput {
+    entityId?: string;
+    deterministicKey?: string;
+    name: string;
+    displayName?: string;
+    description?: string;
+    canonicalName?: string;
+    aliasNames?: string[];
+    timeLabel?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    sourceName?: string;
+    sourceRecordId?: string;
+    sourceUri?: string;
+    canonicalEntityId?: string;
+    upsert?: boolean;
+    metadata?: Record<string, unknown>;
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+    referencedEntityIds?: string[];
+}
+/** Input contract for writing a historical conflict relation between claim/fact nodes. */
+export interface HistoricalConflictInput {
+    leftEntityId: string;
+    rightEntityId: string;
+    conflictLevel?: string;
+    conflictKind?: string;
+    evidenceIds?: string[];
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    confidence?: number;
+    deterministicKey?: string;
+    upsert?: boolean;
+}
+/** Shared filter contract for claim/fact/evidence historical node queries. */
+export interface ClaimFactEvidenceFilter {
+    subjectEntityId?: string;
+    objectEntityId?: string;
+    relationType?: string;
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    evidenceId?: string;
+    claimId?: string;
+    canonicalFactId?: string;
+    referencedEntityId?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    nameContains?: string;
+    limit?: number;
+}
+/** Import mode used by historical graph ingestion sessions. */
+export type ImportMode = 'full' | 'incremental' | 'patch';
+/** Lifecycle state for an import session. */
+export type ImportSessionStatus = 'open' | 'committed' | 'rolled_back' | 'failed';
+/** Conflict policy applied when upserting historical graph objects. */
+export type UpsertConflictPolicy = 'skip' | 'replace' | 'merge_metadata' | 'error';
+/** Merge strategy used when metadata is merged during upsert. */
+export type MetadataMergePolicy = 'prefer_existing' | 'prefer_incoming' | 'append_arrays_unique' | 'deep_merge_shallow_values';
+/** Item category returned in batch write results. */
+export type BatchItemType = 'entity' | 'relation' | 'claim' | 'fact' | 'evidence' | 'alias' | 'merge';
+/** Per-item status returned in batch write results. */
+export type BatchItemStatus = 'created' | 'updated' | 'skipped' | 'failed' | 'unchanged';
+/** Input for opening an import session. */
+export interface ImportSessionInput {
+    datasetKey?: string;
+    sourceName?: string;
+    importBatchId?: string;
+    mode?: ImportMode;
+    metadata?: Record<string, unknown>;
+}
+/** Logical import session metadata for historical graph ingestion. */
+export interface ImportSession {
+    sessionId: string;
+    datasetKey?: string;
+    sourceName?: string;
+    importBatchId?: string;
+    mode: ImportMode;
+    status: ImportSessionStatus;
+    startedAt: string;
+    committedAt?: string;
+    checkpointToken?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Resumable checkpoint emitted during batch ingestion. */
+export interface ImportCheckpoint {
+    sessionId: string;
+    checkpointToken: string;
+    lastEntityCursor?: string;
+    lastRelationCursor?: string;
+    processedItems: number;
+    createdItems: number;
+    updatedItems: number;
+    skippedItems: number;
+    failedItems: number;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+/** Per-item diagnostics returned by batch ingestion APIs. */
+export interface BatchItemResult {
+    index: number;
+    itemType: BatchItemType;
+    inputId?: string;
+    resolvedId?: string;
+    status: BatchItemStatus;
+    reasonCode?: string;
+    message?: string;
+    conflictPolicy?: UpsertConflictPolicy;
+    warnings?: string[];
+    diagnostics?: Record<string, unknown>;
+}
+/** Shared options for batch write ingestion APIs. */
+export interface BatchWriteOptions {
+    upsert?: boolean;
+    conflictPolicy?: UpsertConflictPolicy;
+    metadataMergePolicy?: MetadataMergePolicy;
+    autoCommit?: boolean;
+    emitCheckpointEvery?: number;
+    continueOnError?: boolean;
+    dedupeWithinBatch?: boolean;
+    validateOnly?: boolean;
+}
+/** Batch-level result returned by historical ingestion APIs. */
+export interface BatchWriteResult {
+    sessionId?: string;
+    batchId?: string;
+    success: boolean;
+    total: number;
+    created: number;
+    updated: number;
+    skipped: number;
+    failed: number;
+    unchanged: number;
+    checkpointToken?: string;
+    items: BatchItemResult[];
+    stats?: Record<string, number>;
+    warnings?: string[];
+}
+/** Entity hit returned by historical relation queries. */
+export interface RelatedEntityHit {
+    entity: Entity;
+    relation: Relation;
+    direction: RelationDirection;
+}
+/** Evidence lookup result for a relation. */
+export interface RelationEvidenceResult {
+    relation: Relation;
+    evidenceEntities: Entity[];
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+}
+/** Grouped claim/fact/evidence nodes for a source entity. */
+export interface SourceBundleResult {
+    sourceEntity: Entity;
+    claims: Entity[];
+    facts: Entity[];
+    evidenceEntities: Entity[];
+}
+export interface HistoricalSourceExcerptResult {
+    excerptId: string;
+    sourceEntity?: Entity | null;
+    sourceChapterId?: string;
+    sourceChapterTitle?: string;
+    sourceSpan?: string;
+    sourceQuote?: string;
+    relationIds: string[];
+    evidenceEntities: Entity[];
+    claimEntities: Entity[];
+    factEntities: Entity[];
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    supportCount: number;
+    reasonCodes: string[];
+}
+export interface HistoricalEvidenceContextSummaryResult {
+    excerptCount: number;
+    quotedExcerptCount: number;
+    sourceEntityCount: number;
+    relationCount: number;
+    evidenceCount: number;
+    claimCount: number;
+    factCount: number;
+}
+export interface HistoricalEvidenceContextResult {
+    targetEntity: Entity;
+    excerpts: HistoricalSourceExcerptResult[];
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    claimEntities: Entity[];
+    factEntities: Entity[];
+    summary: HistoricalEvidenceContextSummaryResult;
+    reasons: string[];
+}
+/** Aggregated entity-centered historical graph read model. */
+export interface EntityHistoryBundleResult {
+    entity: Entity;
+    relatedEntities: RelatedEntityHit[];
+    timeline: RelatedEntityHit[];
+    evidence: RelationEvidenceResult[];
+    claims: Entity[];
+    facts: Entity[];
+    chapters: RelatedEntityHit[];
+    conflictClusters: ConflictClusterResult[];
+    summary: EntityHistoryBundleSummaryResult;
+    sourceBundle?: SourceBundleResult | null;
+}
+export interface EntityHistoryBundleSummaryResult {
+    relatedEntityCount: number;
+    timelineCount: number;
+    evidenceCount: number;
+    claimCount: number;
+    factCount: number;
+    chapterCount: number;
+    conflictClusterCount: number;
+    hasSourceBundle: boolean;
+}
+export interface TimelineBucketResult {
+    bucketKey: string;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    hits: RelatedEntityHit[];
+    hitCount: number;
+}
+export interface HistoricalTimelineEventResult {
+    event: Entity;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    participantCount: number;
+    chapterCount: number;
+    evidenceCount: number;
+    claimCount: number;
+    factCount: number;
+    conflictClusterCount: number;
+}
+export interface HistoricalEventParticipantResult {
+    participant: Entity;
+    relation: Relation;
+    role?: string;
+    stance?: string;
+    side?: string;
+    narrativeWeight?: number;
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+}
+export interface HistoricalEntityEventRoleResult {
+    event: HistoricalTimelineEventResult;
+    relation: Relation;
+    role?: string;
+    stance?: string;
+    side?: string;
+    narrativeWeight?: number;
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+}
+export interface HistoricalActorInteractionResult {
+    counterpart: Entity;
+    interactionScore: number;
+    coEventCount: number;
+    conflictTouchCount: number;
+    sharedSourceCount: number;
+    timeOverlapScore: number;
+    directRelationCount: number;
+    relationTypes: string[];
+    sharedEventIds: string[];
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    reasons: string[];
+}
+export interface HistoricalInteractionSummaryStatsResult {
+    counterpartCount: number;
+    personCounterpartCount: number;
+    eventCounterpartCount: number;
+    directRelationCount: number;
+    coEventCount: number;
+    conflictTouchCount: number;
+    sharedSourceCount: number;
+    strongestInteractionScore: number;
+    averageInteractionScore: number;
+}
+export interface HistoricalInteractionSummaryResult {
+    anchorEntity: Entity;
+    interactions: HistoricalActorInteractionResult[];
+    strongestPersonInteraction?: HistoricalActorInteractionResult | null;
+    strongestEventInteraction?: HistoricalActorInteractionResult | null;
+    summary: HistoricalInteractionSummaryStatsResult;
+    reasons: string[];
+}
+export interface HistoricalActivityItemResult {
+    activityId: string;
+    activityType: string;
+    primaryEntity: Entity;
+    relatedEntities: Entity[];
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    relation?: Relation | null;
+    event?: HistoricalTimelineEventResult | null;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    importanceScore?: number | null;
+    conflictStatus?: string | null;
+    reasonCodes: string[];
+}
+export interface HistoricalActivityStreamSummaryResult {
+    activityCount: number;
+    eventCount: number;
+    relationCount: number;
+    claimCount: number;
+    factCount: number;
+    evidenceCount: number;
+    conflictCount: number;
+}
+export interface HistoricalActivityStreamResult {
+    anchorEntity?: Entity | null;
+    items: HistoricalActivityItemResult[];
+    summary: HistoricalActivityStreamSummaryResult;
+}
+export interface HistoricalEventImportanceScoreBreakdownResult {
+    participantScore: number;
+    chapterScore: number;
+    evidenceScore: number;
+    claimScore: number;
+    factScore: number;
+    conflictScore: number;
+    chronologyScore: number;
+}
+export interface HistoricalEventImportanceResult {
+    event: HistoricalTimelineEventResult;
+    score: number;
+    reasons: string[];
+    scoreBreakdown: HistoricalEventImportanceScoreBreakdownResult;
+}
+export interface HistoricalNarrativeOrderScoreBreakdownResult {
+    chronologyScore: number;
+    supportDensityScore: number;
+    excerptSignalScore: number;
+    narrativeSignalScore: number;
+    anchorRelevanceScore: number;
+}
+export interface HistoricalNarrativeOrderResult {
+    event: HistoricalTimelineEventResult;
+    score: number;
+    reasons: string[];
+    scoreBreakdown: HistoricalNarrativeOrderScoreBreakdownResult;
+}
+export interface HistoricalTimelineBucketResult {
+    bucketKey: string;
+    yearStart?: number;
+    yearEnd?: number;
+    timeLabel?: string;
+    dynasty?: string;
+    events: HistoricalTimelineEventResult[];
+    eventCount: number;
+    participantCount: number;
+}
+export interface AliasMergeResult {
+    canonicalEntity: Entity;
+    aliasEntity: Entity;
+    mergedAliasNames: string[];
+}
+export interface HistoricalProjectionSectionsResult {
+    relatedEntityIds: string[];
+    timelineEntityIds: string[];
+    claimIds: string[];
+    factIds: string[];
+    chapterIds: string[];
+    evidenceEntityIds: string[];
+    sourceEntityIds: string[];
+    conflictEntityIds: string[];
+    relationIds: string[];
+}
+export interface HistoricalGraphProjectionResult {
+    rootEntity: Entity;
+    entities: Entity[];
+    relations: Relation[];
+    timelineBuckets: TimelineBucketResult[];
+    summary: EntityHistoryBundleSummaryResult;
+    sections: HistoricalProjectionSectionsResult;
+}
+export interface HistoricalEntitySpotlightSummaryResult {
+    aliasCount: number;
+    kinshipRelationCount: number;
+    politicalRelationCount: number;
+    eventRelationCount: number;
+    chapterCount: number;
+    timelineCount: number;
+    conflictClusterCount: number;
+}
+export interface HistoricalEntitySpotlightResult {
+    entity: Entity;
+    canonicalEntity?: Entity | null;
+    aliasEntities: Entity[];
+    bundle: EntityHistoryBundleResult;
+    kinshipRelations: RelatedEntityHit[];
+    politicalRelations: RelatedEntityHit[];
+    eventRelations: RelatedEntityHit[];
+    summary: HistoricalEntitySpotlightSummaryResult;
+}
+export interface HistoricalEntitySearchFilter {
+    entityTypes?: string[];
+    canonicalEntityId?: string;
+    sourceEntityId?: string;
+    sourceChapterId?: string;
+    yearStart?: number;
+    yearEnd?: number;
+    dynasty?: string;
+    textQuery?: string;
+    offset?: number;
+    limit?: number;
+}
+export interface HistoricalNarrativeOrderFilter extends HistoricalEntitySearchFilter {
+    anchorEntityId?: string;
+}
+export interface HistoricalEntityRecommendationResult {
+    entity: Entity;
+    score: number;
+    reasons: string[];
+}
+/** Connected conflict component rooted at a claim/fact node. */
+export interface ConflictClusterResult {
+    anchorEntity: Entity;
+    clusterEntities: Entity[];
+    conflictRelations: Relation[];
+    relatedEntities: Entity[];
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    conflictLevels: string[];
+    conflictKinds: string[];
+    claimEntities: Entity[];
+    factEntities: Entity[];
+    claimConflictRelations: Relation[];
+    factConflictRelations: Relation[];
+    mixedConflictRelations: Relation[];
+    summary: ConflictClusterSummaryResult;
+}
+/** Summary view for a layered conflict cluster. */
+export interface ConflictClusterSummaryResult {
+    dominantLevel: string;
+    clusterEntityCount: number;
+    claimEntityCount: number;
+    factEntityCount: number;
+    claimConflictCount: number;
+    factConflictCount: number;
+    mixedConflictCount: number;
+    sourceEntityCount: number;
+    evidenceEntityCount: number;
+}
+export interface HistoricalConflictOverviewSummaryResult {
+    clusterCount: number;
+    claimEntityCount: number;
+    factEntityCount: number;
+    sourceEntityCount: number;
+    evidenceEntityCount: number;
+    dominantLevels: string[];
+    conflictKinds: string[];
+}
+export interface HistoricalConflictOverviewResult {
+    entity: Entity;
+    clusters: ConflictClusterResult[];
+    sourceEntities: Entity[];
+    evidenceEntities: Entity[];
+    summary: HistoricalConflictOverviewSummaryResult;
+}
+export interface HistoricalConflictScoreBreakdownResult {
+    structuralScore: number;
+    evidenceScore: number;
+    sourceScore: number;
+    factPriorityScore: number;
+    kindDiversityScore: number;
+    spreadScore: number;
+}
+export interface HistoricalConflictAdjudicationResult {
+    scope: string;
+    targetId: string;
+    score: number;
+    severity: string;
+    status: string;
+    recommendedAction: string;
+    reasons: string[];
+    scoreBreakdown: HistoricalConflictScoreBreakdownResult;
+}
+export interface HistoricalConflictAdjudicationContainerResult {
+    entity: Entity;
+    overview: HistoricalConflictOverviewResult;
+    overviewAssessment: HistoricalConflictAdjudicationResult;
+    clusterAssessments: HistoricalConflictAdjudicationResult[];
+}
+export interface HistoricalGraphDiagnosticIssueResult {
+    code: string;
+    severity: string;
+    message: string;
+    entityId?: string;
+    relationId?: string;
+}
+export interface HistoricalGraphDiagnosticsCountsResult {
+    historicalEntityCount: number;
+    historicalRelationCount: number;
+    personCount: number;
+    eventCount: number;
+    documentCount: number;
+    evidenceCount: number;
+    claimCount: number;
+    factCount: number;
+}
+export interface HistoricalGraphTimeCoverageResult {
+    datedEntityCount: number;
+    undatedEntityCount: number;
+    datedEventCount: number;
+    undatedEventCount: number;
+    datedRelationCount: number;
+    undatedRelationCount: number;
+}
+export interface HistoricalGraphIntegrityResult {
+    danglingRelationEndpointCount: number;
+    danglingSourceEntityRefCount: number;
+    danglingEvidenceRefCount: number;
+    danglingClaimRefCount: number;
+    danglingCanonicalEntityRefCount: number;
+    danglingCanonicalFactRefCount: number;
+}
+export interface HistoricalGraphMetadataCompletenessResult {
+    claimsMissingSubjectEntityCount: number;
+    claimsMissingRelationTypeCount: number;
+    factsMissingClaimIdsCount: number;
+    factsMissingEvidenceIdsCount: number;
+    evidenceMissingReferencedEntityIdsCount: number;
+    evidenceMissingSourceEntityCount: number;
+    relationsMissingRelationFamilyCount: number;
+}
+export interface HistoricalGraphMetricsSummaryResult {
+    totalRequests: number;
+    successfulWrites: number;
+    failedWrites: number;
+    rejectedRequests: number;
+    batchesFlushed: number;
+    batchDocuments: number;
+    avgQueueTimeUs: number;
+    avgWriteTimeUs: number;
+    entityCount: number;
+    relationCount: number;
+    queueFillRatio: number;
+}
+export interface HistoricalGraphDiagnosticsResult {
+    counts: HistoricalGraphDiagnosticsCountsResult;
+    timeCoverage: HistoricalGraphTimeCoverageResult;
+    integrity: HistoricalGraphIntegrityResult;
+    metadataCompleteness: HistoricalGraphMetadataCompletenessResult;
+    metrics: HistoricalGraphMetricsSummaryResult;
+    issues: HistoricalGraphDiagnosticIssueResult[];
+}
 /** Input for creating a person */
 export interface PersonInput {
     id?: string;
@@ -148,6 +908,22 @@ export interface AllPathsResult {
     paths: PathResult[];
     shortestHops: number;
 }
+/** Score breakdown for a ranked historical path candidate. */
+export interface HistoricalPathScoreBreakdownResult {
+    hopScore: number;
+    relationWeightScore: number;
+    confidenceScore: number;
+    provenanceScore: number;
+    chronologyScore: number;
+    inferredPenalty: number;
+}
+/** Ranked historical path candidate with scoring reasons. */
+export interface HistoricalPathRankingResult {
+    path: PathResult;
+    score: number;
+    reasons: string[];
+    scoreBreakdown: HistoricalPathScoreBreakdownResult;
+}
 /** Options for path finding */
 export interface PathOptions {
     maxHops?: number;
@@ -391,7 +1167,7 @@ export type NodeGroup = 'person' | 'company' | 'tag';
  * - belongs_to: 通用归属关系（已弃用，仅保留向后兼容）
  * - tagged: 标签关系（已弃用，请使用 has_tag）
  */
-export type EdgeRelationType = 'friend' | 'knows' | 'colleague' | 'classmate' | 'family' | 'mentor' | 'work_for' | 'has_tag' | 'has_skill' | 'has_interest' | 'owns' | 'belongs_to' | 'tagged';
+export type EdgeRelationType = 'friend' | 'knows' | 'colleague' | 'classmate' | 'family' | 'mentor' | 'work_for' | 'has_tag' | 'has_skill' | 'has_interest' | 'owns' | 'participated_in' | 'involves_person' | 'mentioned_in' | 'described_in' | 'source_of' | 'occurred_at' | 'occurred_on' | 'occurred_in_year' | 'supported_by' | 'derived_from_claim' | 'conflicts_with' | 'same_as' | 'alias_of' | 'served_under' | 'appointed_by' | 'recommended_by' | 'allied_with' | 'opposed_to' | 'betrayed' | 'rebelled_against' | 'defeated' | 'killed' | 'captured' | 'predecessor_of' | 'succeeded_by' | 'part_of_campaign' | 'narrative_parallel' | 'resembles' | 'belongs_to' | 'tagged';
 /** Node for graph visualization */
 export interface GraphNode {
     /** Unique node ID */