@lucern/contracts 0.1.1-alpha.1 → 0.1.2-alpha.2

package/src/topic-scope.contract.ts

@@ -1,9 +0,0 @@
-/**
- * @lucern/contracts — topic-scope compat shim
- *
- * This file moved to ./v1/topics/v1.ts during EK-16 T1 PR 2.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts/v1/topics" directly.
- */
-
-export * from "./v1/topics/v1";

package/src/topics/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Topics API Contract v1
- *
- * Defines the public surface for topic operations:
- * create, update, tree traversal, coverage analysis.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};

package/src/v1/agents/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Agents v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};

package/src/v1/beliefs/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Beliefs v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};

package/src/v1/evidence/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Evidence v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};

package/src/v1/graph/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Graph v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};

package/src/v1/ontologies/v1.ts

@@ -1,276 +0,0 @@
-/**
- * @lucern/contracts — OntologiesV1 namespace (resource contracts)
- *
- * Ontology Matching Engine — L0 entity type classification and similarity scoring.
- * Provides bigram-based text similarity for matching free text against
- * ontology entity types. Domain-agnostic: works identically for companies,
- * molecules, code modules, or any tenant-defined entity vocabulary.
- *
- * Moved from src/ontology-matching.contract.ts in EK-16 T1 PR 2.
- * Compat shim remains at the old path until the Lucern 1.0.0 cut.
- */
-
-import {
-  bigramTokenize,
-  jaccardSimilarity,
-  prepareLexicalQuery,
-  scoreLexicalSignals,
-  wordOverlapScore,
-  wordTokenize,
-} from "../../text-matching.contract";
-
-// =============================================================================
-// TYPES
-// =============================================================================
-
-/** An entity type definition from a resolved ontology version. */
-export type OntologyEntityType = {
-  value: string;
-  label: string;
-  description?: string;
-  subtypes?: Array<{ value: string; label: string; description?: string }>;
-};
-
-/** A scored match between input text and an entity type. */
-export type EntityTypeMatch = {
-  entityType: string;
-  label: string;
-  score: number;
-  reason: string;
-};
-
-/** A candidate entity node that can be matched against a target node. */
-export type EntityMatchCandidate = {
-  nodeId: string;
-  entityType: string;
-  title: string;
-  canonicalText: string;
-  connectedBeliefCount: number;
-  connectedEvidenceCount: number;
-};
-
-/** A scored entity match with suggested bridge edge type. */
-export type EntityConnectionMatch = {
-  entityNodeId: string;
-  entityType: string;
-  title: string;
-  score: number;
-  suggestedEdgeType: string;
-  reason: string;
-};
-
-// =============================================================================
-// ENTITY TYPE SCORING
-// =============================================================================
-
-/** Weights for combining scoring signals. */
-const MATCH_WEIGHTS = {
-  tokenOverlap: 0.35,
-  bigramSimilarity: 0.25,
-  wordOverlap: 0.2,
-  descriptionBonus: 0.2,
-} as const;
-
-/**
- * Score how well input text matches a single entity type definition.
- * Combines bigram Jaccard similarity, word overlap, and description matching.
- */
-export function scoreEntityTypeMatch(
-  inputText: string,
-  entityType: OntologyEntityType
-): EntityTypeMatch {
-  const preparedQuery = prepareLexicalQuery(inputText);
-  const labelText = `${entityType.label} ${entityType.value}`;
-
-  const tokenScore = scoreLexicalSignals(preparedQuery, [
-    { text: labelText, weight: 1, strategy: "tokenOverlap" },
-  ]);
-
-  // Score against the type label (primary signal)
-  const labelBigrams = bigramTokenize(entityType.label);
-  const bigramScore = jaccardSimilarity(preparedQuery.bigrams, labelBigrams);
-
-  // Word overlap with label + value
-  const labelWords = wordTokenize(labelText);
-  const wordScore = wordOverlapScore(preparedQuery.words, labelWords);
-
-  // Description matching bonus (if description exists)
-  let descScore = 0;
-  if (entityType.description) {
-    descScore = scoreLexicalSignals(preparedQuery, [
-      { text: entityType.description, weight: 1, strategy: "tokenOverlap" },
-    ]);
-  }
-
-  // Check subtypes for additional matches
-  let subtypeBonus = 0;
-  if (entityType.subtypes && entityType.subtypes.length > 0) {
-    for (const subtype of entityType.subtypes) {
-      const subtypeScore = scoreLexicalSignals(preparedQuery, [
-        {
-          text: `${subtype.label} ${subtype.value} ${subtype.description || ""}`,
-          weight: 1,
-          strategy: "tokenOverlap",
-        },
-      ]);
-      subtypeBonus = Math.max(subtypeBonus, subtypeScore * 0.3); // up to 30% subtype bonus
-    }
-  }
-
-  const score = Math.min(
-    1.0,
-    tokenScore * MATCH_WEIGHTS.tokenOverlap +
-      bigramScore * MATCH_WEIGHTS.bigramSimilarity +
-      wordScore * MATCH_WEIGHTS.wordOverlap +
-      descScore * MATCH_WEIGHTS.descriptionBonus +
-      subtypeBonus
-  );
-
-  // Generate human-readable reason
-  const reasons: string[] = [];
-  if (tokenScore > 0.3) {
-    reasons.push(`stem match: ${(tokenScore * 100).toFixed(0)}%`);
-  }
-  if (bigramScore > 0.3) {
-    reasons.push(`text similarity: ${(bigramScore * 100).toFixed(0)}%`);
-  }
-  if (wordScore > 0.3) {
-    reasons.push(`word match: ${(wordScore * 100).toFixed(0)}%`);
-  }
-  if (descScore > 0.2) {
-    reasons.push("description match");
-  }
-  if (subtypeBonus > 0.05) {
-    reasons.push("subtype match");
-  }
-  const reason = reasons.length > 0 ? reasons.join(", ") : "low similarity";
-
-  return {
-    entityType: entityType.value,
-    label: entityType.label,
-    score,
-    reason,
-  };
-}
-
-/**
- * Rank all entity types in an ontology against input text.
- * Returns matches sorted by score (descending), filtered to score > minScore.
- */
-export function rankEntityTypeMatches(
-  inputText: string,
-  entityTypes: OntologyEntityType[],
-  options?: { minScore?: number; limit?: number }
-): EntityTypeMatch[] {
-  const minScore = options?.minScore ?? 0.05;
-  const limit = options?.limit ?? 10;
-
-  const matches = entityTypes
-    .map((et) => scoreEntityTypeMatch(inputText, et))
-    .filter((m) => m.score >= minScore)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, limit);
-
-  return matches;
-}
-
-// =============================================================================
-// ENTITY DISCOVERY SCORING
-// =============================================================================
-
-/**
- * Score how well a node's text matches an entity candidate.
- * Used by discover_entity_connections to suggest missing bridge edges.
- */
-export function scoreEntityConnection(
-  nodeText: string,
-  candidate: EntityMatchCandidate,
-  options?: { connectivityWeight?: number }
-): EntityConnectionMatch {
-  const preparedQuery = prepareLexicalQuery(nodeText);
-  const connectivityWeight = options?.connectivityWeight ?? 0.3;
-  const textWeight = 1.0 - connectivityWeight;
-  const candidateText = `${candidate.title} ${candidate.canonicalText}`;
-  const tokenScore = scoreLexicalSignals(preparedQuery, [
-    { text: candidateText, weight: 1, strategy: "tokenOverlap" },
-  ]);
-  const textScore = scoreLexicalSignals(preparedQuery, [
-    { text: candidateText, weight: 1, strategy: "bigramJaccard" },
-  ]);
-  const wordScore = scoreLexicalSignals(preparedQuery, [
-    { text: candidateText, weight: 1, strategy: "wordOverlap" },
-  ]);
-
-  // Connectivity signal (normalized externally by caller)
-  const maxConnections = Math.max(
-    1,
-    candidate.connectedBeliefCount + candidate.connectedEvidenceCount
-  );
-  const connectivityScore = Math.min(1.0, maxConnections / 10); // soft-cap at 10
-
-  const combinedTextScore =
-    tokenScore * 0.45 + textScore * 0.35 + wordScore * 0.2;
-  const score =
-    combinedTextScore * textWeight + connectivityScore * connectivityWeight;
-
-  // Suggest edge type based on entity type
-  const suggestedEdgeType = suggestEdgeType(candidate.entityType);
-
-  const reason =
-    tokenScore > 0.3
-      ? `stem match: ${(tokenScore * 100).toFixed(0)}%`
-      : textScore > 0.2
-        ? `name similarity: ${(textScore * 100).toFixed(0)}%`
-        : wordScore > 0.2
-          ? `keyword match: ${(wordScore * 100).toFixed(0)}%`
-          : `connectivity: ${candidate.connectedBeliefCount} beliefs`;
-
-  return {
-    entityNodeId: candidate.nodeId,
-    entityType: candidate.entityType,
-    title: candidate.title,
-    score,
-    suggestedEdgeType,
-    reason,
-  };
-}
-
-/**
- * Suggest the most appropriate bridge edge type for an entity type.
- */
-function suggestEdgeType(entityType: string): string {
-  switch (entityType) {
-    case "company":
-    case "person":
-    case "investor":
-      return "contains";
-    case "function":
-    case "value_chain":
-      return "impacts";
-    default:
-      return "contains";
-  }
-}
-
-/**
- * Rank entity candidates against a node's text.
- * Returns sorted matches above the minimum score threshold.
- */
-export function rankEntityConnections(
-  nodeText: string,
-  candidates: EntityMatchCandidate[],
-  options?: { minScore?: number; limit?: number; connectivityWeight?: number }
-): EntityConnectionMatch[] {
-  const minScore = options?.minScore ?? 0.05;
-  const limit = options?.limit ?? 10;
-
-  return candidates
-    .map((c) =>
-      scoreEntityConnection(nodeText, c, {
-        connectivityWeight: options?.connectivityWeight,
-      })
-    )
-    .filter((m) => m.score >= minScore)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, limit);
-}

package/src/v1/questions/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Questions v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};

package/src/v1/worktrees/v1.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — Worktrees v1 namespace
- *
- * Placeholder. Resource contracts land in EK-16 T1 PR 2 (two-taxonomy migration).
- * Do not add symbols here — they must move from the flat contract files
- * during the PR 2 migration.
- */
-export {};