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

package/src/ontologies/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Ontology API Contract v1
- *
- * Defines the public surface for ontology operations:
- * create, version, publish, resolve, entity/edge type management.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};

package/src/ontology-matching.contract.ts

@@ -1,9 +0,0 @@
-/**
- * @lucern/contracts — ontology-matching compat shim
- *
- * This file moved to ./v1/ontologies/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/ontologies" directly.
- */
-
-export * from "./v1/ontologies/v1";

package/src/prompt.contract.ts

@@ -1,50 +0,0 @@
-/**
- * Prompt contract for portable, provider-agnostic prompt artifacts.
- */
-
-export type LucernPromptModelHint = "fast" | "balanced" | "strong";
-
-export type LucernPrompt = {
-  /** Stable prompt identifier, e.g. "lucern/classify-evidence" */
-  slug: string;
-  /** Semver-ish prompt version, e.g. "1.0.0" */
-  version: string;
-  /** Prompt template text (supports {{variable}} interpolation) */
-  template: string;
-  /** Variables expected by the template */
-  variables: string[];
-  /** Model family hint for runtime model routing */
-  modelHint: LucernPromptModelHint;
-  /** Metadata used for ownership and discovery */
-  metadata: {
-    author: string;
-    createdAt: string;
-    description: string;
-    tags: string[];
-  };
-};
-
-export function isLucernPrompt(value: unknown): value is LucernPrompt {
-  if (!value || typeof value !== "object") {
-    return false;
-  }
-  const prompt = value as Partial<LucernPrompt>;
-
-  return (
-    typeof prompt.slug === "string" &&
-    typeof prompt.version === "string" &&
-    typeof prompt.template === "string" &&
-    Array.isArray(prompt.variables) &&
-    prompt.variables.every((entry) => typeof entry === "string") &&
-    (prompt.modelHint === "fast" ||
-      prompt.modelHint === "balanced" ||
-      prompt.modelHint === "strong") &&
-    !!prompt.metadata &&
-    typeof prompt.metadata === "object" &&
-    typeof prompt.metadata.author === "string" &&
-    typeof prompt.metadata.createdAt === "string" &&
-    typeof prompt.metadata.description === "string" &&
-    Array.isArray(prompt.metadata.tags) &&
-    prompt.metadata.tags.every((entry) => typeof entry === "string")
-  );
-}

package/src/questions/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Questions API Contract v1
- *
- * Defines the public surface for question operations:
- * create, refine, answer, status transitions, priority ranking.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};

package/src/sdk-methods.contract.ts

@@ -1,522 +0,0 @@
-/**
- * SDK Method Contract Definitions
- *
- * Canonical method signatures for the Lucern TypeScript SDK.
- * DERIVED from API contracts — not independently authored.
- *
- * These types define the public API of `@lucern/sdk`, covering:
- *   - client initialization (formerly @lucern/sdk-core)
- *   - belief, evidence, edge, contradiction operations (formerly @lucern/sdk-graph)
- *   - branch, worktree, merge, push, pull request lifecycle (formerly @lucern/sdk-workflows)
- *
- * Historical note: T7.3.2 (2026-04-18) deleted the three sdk-alpha shim
- * packages; all surfaces now ship in the single `@lucern/sdk` package.
- *
- * CONTRACT SURFACE: Method signatures are semver-bound.
- * Adding optional parameters is non-breaking.
- * Changing required parameters or return types is BREAKING.
- */
-
-import type {
-  BeliefStatus,
-  BranchStatus,
-  ConfidenceTrigger,
-  ContradictionSeverity,
-  DefeatType,
-  EpistemicLayer,
-  ForkReason,
-  JudgmentType,
-  MergeOutcome,
-  PullRequestStatus,
-  ReasoningMethod,
-} from "./api-enums.contract";
-import type {
-  ContextRankingProfile,
-  PublicCompiledContext,
-} from "./context-pack.contract";
-
-// =============================================================================
-// CLIENT TYPES (@lucern/sdk (core))
-// =============================================================================
-
-export type LucernClientConfig = {
-  apiKey: string;
-  environment: "sandbox" | "production";
-  /** Optional base URL override for self-hosted deployments */
-  baseUrl?: string;
-};
-
-export type LucernClient = {
-  /** The authenticated client instance */
-  readonly config: LucernClientConfig;
-};
-
-// =============================================================================
-// GRAPH TYPES (@lucern/sdk (graph))
-// =============================================================================
-
-/** Input to createBelief() */
-export type CreateBeliefInput = {
-  canonicalText: string;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  layer?: EpistemicLayer;
-  domain?: string;
-  nodeType?: string;
-};
-
-/** Result of createBelief() */
-export type BeliefResult = {
-  nodeId: string;
-  globalId: string;
-  canonicalText: string;
-  status: BeliefStatus;
-  createdAt: number;
-};
-
-/** Input to refineBelief() */
-export type RefineBeliefInput = {
-  canonicalText: string;
-  rationale?: string;
-};
-
-/** Input to modulateConfidence() */
-export type ModulateConfidenceInput = {
-  confidence: number;
-  trigger: ConfidenceTrigger;
-  rationale: string;
-};
-
-/** Result of modulateConfidence() */
-export type ConfidenceResult = {
-  nodeId: string;
-  newConfidence: number;
-  previousConfidence: number | null;
-  trigger: ConfidenceTrigger;
-};
-
-/** Input to forkBelief() */
-export type ForkBeliefInput = {
-  newFormulation: string;
-  forkReason: ForkReason;
-};
-
-/** Result of forkBelief() */
-export type ForkResult = {
-  nodeId: string;
-  parentNodeId: string;
-  forkReason: ForkReason;
-  canonicalText: string;
-};
-
-/** Input to addEvidence() */
-export type AddEvidenceInput = {
-  canonicalText: string;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  sourceUrl?: string;
-  supports?: {
-    nodeId: string;
-    weight: number;
-    reasoning?: string;
-  };
-};
-
-/** Result of addEvidence() */
-export type EvidenceResult = {
-  nodeId: string;
-  globalId: string;
-  edgeId?: string;
-};
-
-/** Input to flagContradiction() */
-export type FlagContradictionInput = {
-  beliefA: string;
-  beliefB: string;
-  description: string;
-  severity: ContradictionSeverity;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  defeatType?: DefeatType;
-};
-
-/** Result of flagContradiction() */
-export type ContradictionResult = {
-  contradictionId: string;
-  status: "unresolved";
-  beliefA: string;
-  beliefB: string;
-  defeatType?: DefeatType;
-};
-
-/** Input to createEdge() */
-export type CreateEdgeInput = {
-  sourceId: string;
-  targetId: string;
-  edgeType: string;
-  weight?: number;
-  reasoning?: string;
-  reasoningMethod?: ReasoningMethod;
-};
-
-/** Result of createEdge() */
-export type EdgeResult = {
-  globalId: string;
-  edgeType: string;
-  fromLayer: EpistemicLayer;
-  toLayer: EpistemicLayer;
-};
-
-/** Input to queryLineage() */
-export type QueryLineageInput = {
-  depth?: number;
-};
-
-/** Result of queryLineage() */
-export type LineageResult = {
-  chain: Array<{
-    nodeId: string;
-    canonicalText: string;
-    confidence: number | null;
-    forkedFrom: string | null;
-    scoredAt: number | null;
-  }>;
-  forkTree: Record<string, string[]>;
-  depth: number;
-};
-
-/** Input to searchBeliefs() */
-export type SearchBeliefsInput = {
-  query: string;
-  status?: BeliefStatus;
-  minConfidence?: number;
-  topicId?: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  limit?: number;
-};
-
-/** Input to context.compile() */
-export type CompileContextInput = {
-  query?: string;
-  budget?: number;
-  ranking?: ContextRankingProfile;
-  limit?: number;
-  maxDepth?: number;
-  includeEntities?: boolean;
-};
-
-/** Result of context.compile() */
-export type CompiledContextResult = PublicCompiledContext;
-
-// =============================================================================
-// WORKFLOW TYPES (@lucern/sdk (workflows))
-// =============================================================================
-
-/** Input to addWorktree() — like git worktree add <branch> */
-export type AddWorktreeInput = {
-  title: string;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  branchId?: string;
-  objective?: string;
-  hypothesis?: string;
-  beliefIds?: string[];
-  autoShape?: boolean;
-  domainPackId?: string;
-  executionOrder?: number;
-  dependsOn?: string[];
-  blocks?: string[];
-  gate?: string;
-};
-
-/** Result of addWorktree() */
-export type WorktreeResult = {
-  worktreeId: string;
-  title: string;
-  status: string;
-  hypothesis?: string;
-  questionCount?: number;
-  taskCount?: number;
-  autoShapeApplied?: boolean;
-};
-
-/** Input to merge() */
-export type MergeInput = {
-  outcomes: Array<{
-    beliefId: string;
-    confidence: number;
-    rationale: string;
-  }>;
-  summary?: string;
-};
-
-/** Result of merge() */
-export type MergeResult = {
-  worktreeId: string;
-  status: "merged";
-  outcome: MergeOutcome;
-  beliefsScored: number;
-};
-
-// =============================================================================
-// JUDGMENT TYPES (Phase 1: new vocabulary)
-// =============================================================================
-
-/** Input to recordJudgment() */
-export type RecordJudgmentInput = {
-  title: string;
-  rationale: string;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  beliefIds?: string[];
-  confidence?: number;
-  judgmentType?: JudgmentType;
-};
-
-/** Result of recordJudgment() */
-export type JudgmentResult = {
-  judgmentId: string;
-  title: string;
-  status: "issued";
-};
-
-// =============================================================================
-// BRANCH TYPES (git branch)
-// =============================================================================
-
-/** Input to createBranch() */
-export type CreateBranchInput = {
-  name: string;
-  topicId: string;
-  /** @deprecated Use topicId. */
-  projectId?: string;
-  description?: string;
-};
-
-/** Result of createBranch() */
-export type BranchResult = {
-  branchId: string;
-  name: string;
-  status: BranchStatus;
-  createdAt: number;
-};
-
-// =============================================================================
-// PUSH TYPES (git push)
-// =============================================================================
-
-/** Input to push() */
-export type PushInput = {
-  targetContext: string;
-  beliefIds?: string[];
-};
-
-/** Result of push() */
-export type PushResult = {
-  pushedCount: number;
-  targetContext: string;
-  pushedAt: number;
-};
-
-// =============================================================================
-// PULL REQUEST TYPES (git pull request)
-// =============================================================================
-
-/** Input to openPullRequest() */
-export type OpenPullRequestInput = {
-  reviewers?: string[];
-  summary: string;
-};
-
-/** Result of openPullRequest() */
-export type PullRequestResult = {
-  pullRequestId: string;
-  worktreeId: string;
-  status: PullRequestStatus;
-};
-
-// =============================================================================
-// BISECT TYPES (git bisect)
-// =============================================================================
-
-/** Input to bisectConfidence() */
-export type BisectConfidenceInput = {
-  expectedDirection: "overconfident" | "underconfident";
-  timeRange?: { start: number; end: number };
-};
-
-/** Result of bisectConfidence() */
-export type BisectResult = {
-  inflectionEntry: {
-    confidence: number;
-    trigger: ConfidenceTrigger;
-    rationale: string;
-    timestamp: number;
-  };
-  triggerEvent: string;
-  confidenceBefore: number;
-  confidenceAfter: number;
-};
-
-// =============================================================================
-// SDK METHOD SIGNATURES
-// =============================================================================
-
-/**
- * @lucern/sdk (graph) method signatures.
- *
- * These define the public API. Implementation must match these signatures.
- * Parameters are the source of truth — generated from API contracts.
- */
-export type LucernGraphMethods = {
-  // Belief lifecycle
-  createBelief(
-    client: LucernClient,
-    input: CreateBeliefInput
-  ): Promise<BeliefResult>;
-  refineBelief(
-    client: LucernClient,
-    nodeId: string,
-    input: RefineBeliefInput
-  ): Promise<BeliefResult>;
-  modulateConfidence(
-    client: LucernClient,
-    nodeId: string,
-    input: ModulateConfidenceInput
-  ): Promise<ConfidenceResult>;
-  forkBelief(
-    client: LucernClient,
-    nodeId: string,
-    input: ForkBeliefInput
-  ): Promise<ForkResult>;
-  archiveBelief(
-    client: LucernClient,
-    nodeId: string,
-    rationale?: string
-  ): Promise<{ nodeId: string; status: "archived" }>;
-
-  // Evidence
-  addEvidence(
-    client: LucernClient,
-    input: AddEvidenceInput
-  ): Promise<EvidenceResult>;
-
-  // Contradictions
-  flagContradiction(
-    client: LucernClient,
-    input: FlagContradictionInput
-  ): Promise<ContradictionResult>;
-
-  // Edges
-  createEdge(client: LucernClient, input: CreateEdgeInput): Promise<EdgeResult>;
-
-  // Queries (log, blame, traverse, search)
-  queryLineage(
-    client: LucernClient,
-    nodeId: string,
-    input?: QueryLineageInput
-  ): Promise<LineageResult>;
-  getConfidenceHistory(
-    client: LucernClient,
-    nodeId: string
-  ): Promise<{
-    entries: Array<{
-      confidence: number;
-      trigger: ConfidenceTrigger;
-      rationale: string;
-      timestamp: number;
-      userId: string;
-    }>;
-  }>;
-  getAuditTrail(
-    client: LucernClient,
-    nodeId: string,
-    limit?: number
-  ): Promise<{
-    entries: Array<{
-      action: string;
-      actor: string;
-      timestamp: number;
-      rationale?: string;
-    }>;
-  }>;
-  searchBeliefs(
-    client: LucernClient,
-    input: SearchBeliefsInput
-  ): Promise<{ results: BeliefResult[] }>;
-  findContradictions(
-    client: LucernClient,
-    input: {
-      topicId?: string;
-      projectId?: string;
-      nodeId?: string;
-      status?: string;
-    }
-  ): Promise<{ contradictions: ContradictionResult[] }>;
-  traverseGraph(
-    client: LucernClient,
-    input: {
-      startNode: string;
-      direction?: "up" | "down" | "both";
-      maxDepth?: number;
-    }
-  ): Promise<{ nodes: unknown[]; edges: unknown[]; depth: number }>;
-
-  // Forensics (bisect)
-  bisectConfidence(
-    client: LucernClient,
-    nodeId: string,
-    input: BisectConfidenceInput
-  ): Promise<BisectResult>;
-
-  // Judgments (tag)
-  recordJudgment(
-    client: LucernClient,
-    input: RecordJudgmentInput
-  ): Promise<JudgmentResult>;
-};
-
-/**
- * @lucern/sdk (workflows) method signatures.
- *
- * Lifecycle: createBranch (git branch) → addWorktree (git worktree add) →
- *   openPullRequest (git pull request) → merge (git merge) → push (git push)
- */
-export type LucernWorkflowMethods = {
-  // Branch lifecycle (git branch)
-  createBranch(
-    client: LucernClient,
-    input: CreateBranchInput
-  ): Promise<BranchResult>;
-
-  // Worktree lifecycle (git worktree add → git merge)
-  addWorktree(
-    client: LucernClient,
-    input: AddWorktreeInput
-  ): Promise<WorktreeResult>;
-  merge(
-    client: LucernClient,
-    worktreeId: string,
-    input: MergeInput
-  ): Promise<MergeResult>;
-
-  // Pull request (git pull request)
-  openPullRequest(
-    client: LucernClient,
-    worktreeId: string,
-    input: OpenPullRequestInput
-  ): Promise<PullRequestResult>;
-
-  // Push (git push)
-  push(
-    client: LucernClient,
-    worktreeId: string,
-    input: PushInput
-  ): Promise<PushResult>;
-};