@lucern/sdk 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/contextPackSchema.ts

@@ -0,0 +1,251 @@
+const CONTEXT_PACK_SCHEMA_VERSION = "1.0.0" as const;
+
+type ValidationResult = {
+  valid: boolean;
+  errors: string[];
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isNullableNumber(value: unknown): boolean {
+  return value === null || isNumber(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => isString(entry));
+}
+
+function requireObject(
+  parent: Record<string, unknown>,
+  key: string,
+  errors: string[]
+): Record<string, unknown> | null {
+  const value = parent[key];
+  if (!isObject(value)) {
+    errors.push(`Expected '${key}' to be an object`);
+    return null;
+  }
+  return value;
+}
+
+function validateBeliefArray(
+  key: string,
+  value: unknown,
+  errors: string[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`Expected '${key}' to be an array`);
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const row = value[index];
+    if (!isObject(row)) {
+      errors.push(`Expected '${key}[${index}]' to be an object`);
+      continue;
+    }
+    if (!isString(row.nodeId)) {
+      errors.push(`Expected '${key}[${index}].nodeId' to be a string`);
+    }
+    if (!isString(row.canonicalText)) {
+      errors.push(`Expected '${key}[${index}].canonicalText' to be a string`);
+    }
+    if (!isNullableNumber(row.confidence)) {
+      errors.push(`Expected '${key}[${index}].confidence' to be number|null`);
+    }
+  }
+}
+
+function validateQuestionArray(
+  key: string,
+  value: unknown,
+  errors: string[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`Expected '${key}' to be an array`);
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const row = value[index];
+    if (!isObject(row)) {
+      errors.push(`Expected '${key}[${index}]' to be an object`);
+      continue;
+    }
+    if (!isString(row.questionId)) {
+      errors.push(`Expected '${key}[${index}].questionId' to be a string`);
+    }
+    if (!isString(row.text)) {
+      errors.push(`Expected '${key}[${index}].text' to be a string`);
+    }
+    if (!isString(row.status)) {
+      errors.push(`Expected '${key}[${index}].status' to be a string`);
+    }
+  }
+}
+
+function validateEvidenceArray(
+  key: string,
+  value: unknown,
+  errors: string[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`Expected '${key}' to be an array`);
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const row = value[index];
+    if (!isObject(row)) {
+      errors.push(`Expected '${key}[${index}]' to be an object`);
+      continue;
+    }
+    if (!isString(row.nodeId)) {
+      errors.push(`Expected '${key}[${index}].nodeId' to be a string`);
+    }
+    if (!isString(row.canonicalText)) {
+      errors.push(`Expected '${key}[${index}].canonicalText' to be a string`);
+    }
+  }
+}
+
+function validateEntityArray(
+  key: string,
+  value: unknown,
+  errors: string[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`Expected '${key}' to be an array`);
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const row = value[index];
+    if (!isObject(row)) {
+      errors.push(`Expected '${key}[${index}]' to be an object`);
+      continue;
+    }
+    if (!isString(row.nodeId)) {
+      errors.push(`Expected '${key}[${index}].nodeId' to be a string`);
+    }
+    if (!isString(row.entityType)) {
+      errors.push(`Expected '${key}[${index}].entityType' to be a string`);
+    }
+    if (!isString(row.title)) {
+      errors.push(`Expected '${key}[${index}].title' to be a string`);
+    }
+    if (!isNumber(row.connectedBeliefCount)) {
+      errors.push(`Expected '${key}[${index}].connectedBeliefCount' to be a number`);
+    }
+    if (!isNumber(row.connectedEvidenceCount)) {
+      errors.push(`Expected '${key}[${index}].connectedEvidenceCount' to be a number`);
+    }
+    if (!isNumber(row.score)) {
+      errors.push(`Expected '${key}[${index}].score' to be a number`);
+    }
+  }
+}
+
+function validateContradictionArray(
+  key: string,
+  value: unknown,
+  errors: string[]
+): void {
+  if (!Array.isArray(value)) {
+    errors.push(`Expected '${key}' to be an array`);
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const row = value[index];
+    if (!isObject(row)) {
+      errors.push(`Expected '${key}[${index}]' to be an object`);
+      continue;
+    }
+    if (!isString(row.contradictionId)) {
+      errors.push(`Expected '${key}[${index}].contradictionId' to be a string`);
+    }
+    if (!isString(row.status)) {
+      errors.push(`Expected '${key}[${index}].status' to be a string`);
+    }
+  }
+}
+
+export function validateContextPackSchema(payload: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (!isObject(payload)) {
+    return {
+      valid: false,
+      errors: ["Expected context pack payload to be an object"],
+    };
+  }
+
+  if (payload.schemaVersion !== CONTEXT_PACK_SCHEMA_VERSION) {
+    errors.push(
+      `Expected schemaVersion='${CONTEXT_PACK_SCHEMA_VERSION}', received '${String(
+        payload.schemaVersion
+      )}'`
+    );
+  }
+
+  if (!isString(payload.topicId)) {
+    errors.push("Expected 'topicId' to be a string");
+  }
+  if (!isString(payload.topicName)) {
+    errors.push("Expected 'topicName' to be a string");
+  }
+  if (!isStringArray(payload.scopedTopicIds)) {
+    errors.push("Expected 'scopedTopicIds' to be string[]");
+  }
+  if (!isNumber(payload.generatedAt)) {
+    errors.push("Expected 'generatedAt' to be a number");
+  }
+  if (!isString(payload.ranking)) {
+    errors.push("Expected 'ranking' to be a string");
+  }
+
+  validateBeliefArray("invariants", payload.invariants, errors);
+  validateBeliefArray("activeBeliefs", payload.activeBeliefs, errors);
+  validateQuestionArray("openQuestions", payload.openQuestions, errors);
+  validateEvidenceArray("recentEvidence", payload.recentEvidence, errors);
+  validateContradictionArray("contradictions", payload.contradictions, errors);
+
+  if (
+    payload.relatedEntities !== undefined &&
+    payload.relatedEntities !== null
+  ) {
+    validateEntityArray("relatedEntities", payload.relatedEntities, errors);
+  }
+
+  if (!Array.isArray(payload.contextNarrative)) {
+    errors.push("Expected 'contextNarrative' to be an array");
+  }
+
+  const injectionPolicy = requireObject(payload, "injectionPolicy", errors);
+  if (injectionPolicy) {
+    if (!isNumber(injectionPolicy.tokenBudget)) {
+      errors.push("Expected 'injectionPolicy.tokenBudget' to be a number");
+    }
+    if (!isNumber(injectionPolicy.estimatedTokens)) {
+      errors.push("Expected 'injectionPolicy.estimatedTokens' to be a number");
+    }
+  }
+
+  if (!isObject(payload.summary)) {
+    errors.push("Expected 'summary' to be an object");
+  }
+  if (!isObject(payload.diagnostics)) {
+    errors.push("Expected 'diagnostics' to be an object");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/contextTypes.ts

@@ -0,0 +1,153 @@
+export type ContextRankingProfile =
+  | "baseline_v1"
+  | "hybrid_v1"
+  | "weighted_v1";
+
+export type ContextCompilationMode = "standard" | "delta";
+
+export type ContextPackSectionKey =
+  | "invariants"
+  | "activeBeliefs"
+  | "openQuestions"
+  | "recentEvidence"
+  | "contradictions";
+
+export type RankingWeightVector = {
+  query: number;
+  recency: number;
+  confidence?: number;
+  beliefType?: number;
+  priority?: number;
+  severity?: number;
+};
+
+export type PackWeightOverride = {
+  section: ContextPackSectionKey;
+  weights: Partial<RankingWeightVector>;
+};
+
+export type CompileContextInput = {
+  query?: string;
+  budget?: number;
+  ranking?: ContextRankingProfile;
+  limit?: number;
+  maxDepth?: number;
+  includeEntities?: boolean;
+  mode?: ContextCompilationMode;
+  includeFailures?: boolean;
+  worktreeId?: string;
+  sessionId?: string;
+  packWeightOverrides?: PackWeightOverride[];
+  tokenBudget?: number;
+  rankingProfile?: ContextRankingProfile;
+};
+
+export type PublicContextBelief = {
+  beliefId: string;
+  text: string;
+  confidence: number | null;
+  beliefType?: string | null;
+  status?: string;
+  updatedAt?: number | null;
+  score: number;
+  justification?: string;
+};
+
+export type PublicContextQuestion = {
+  questionId: string;
+  text: string;
+  status: string;
+  priority: string;
+  updatedAt?: number | null;
+  score: number;
+  justification?: string;
+};
+
+export type PublicContextEvidence = {
+  evidenceId: string;
+  text: string;
+  sourceUrl?: string | null;
+  kind: string;
+  createdAt?: number | null;
+  score: number;
+  justification?: string;
+};
+
+export type PublicContextContradiction = {
+  contradictionId: string;
+  severity: string;
+  status: string;
+  description: string;
+  score: number;
+  justification?: string;
+};
+
+export type PublicContextEntity = {
+  entityId: string;
+  entityType: string;
+  title: string;
+  text?: string;
+  connectedBeliefCount: number;
+  connectedEvidenceCount: number;
+  score: number;
+  metadata?: Record<string, unknown>;
+};
+
+export type PublicContextInjectionPolicy = {
+  tokenBudget: number;
+  estimatedTokens: number;
+  sectionBudgets: Record<string, number>;
+  sectionUsage: Record<string, number>;
+  selected: Record<string, string[]>;
+  excludedItems?: Array<{
+    id: string;
+    section: string;
+    reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
+    score: number;
+  }>;
+};
+
+export type PublicCompiledContext = {
+  schemaVersion: string;
+  topicId: string;
+  topicName: string;
+  scopedTopicIds: string[];
+  generatedAt: number;
+  ranking: ContextRankingProfile;
+  summary: Record<string, unknown>;
+  invariants: PublicContextBelief[];
+  activeBeliefs: PublicContextBelief[];
+  openQuestions: PublicContextQuestion[];
+  recentEvidence: PublicContextEvidence[];
+  contradictions: PublicContextContradiction[];
+  relatedEntities?: PublicContextEntity[];
+  contextNarrative: string[];
+  injectionPolicy: PublicContextInjectionPolicy;
+  diagnostics: Record<string, unknown>;
+  compilationMode?: string;
+  failureContext?: {
+    failures: Array<{
+      attemptId: string;
+      approach: string;
+      outcome: string;
+      recordedAt: number;
+      score: number;
+    }>;
+    suppressedIds: string[];
+  };
+  deltaReport?: {
+    changedItems: Array<{
+      id: string;
+      section: string;
+      changeType: string;
+      summary: string;
+    }>;
+    verificationObligations: Array<{
+      description: string;
+      source: string;
+      severity: "critical" | "high" | "medium" | "low";
+    }>;
+    referencePoint: string;
+  };
+  appliedWeightOverrides?: unknown[];
+};

package/src/contracts/api-enums.contract.ts

@@ -0,0 +1,202 @@
+/**
+ * API Enum Contract Definitions
+ *
+ * Canonical enum values for all API-facing enumerations.
+ * These MUST match the kernel schema validators exactly.
+ *
+ * Source of truth: lucern/packages/reasoning-kernel/src/adapters/schema/spine/
+ */
+
+// =============================================================================
+// BELIEF STATUS
+// =============================================================================
+
+/**
+ * Belief epistemic lifecycle — tracks maturity from raw claim to verified fact.
+ *
+ * - assumption: Untested raw claim, lowest epistemic standing
+ * - hypothesis: Under active investigation, being tested against evidence
+ * - belief: Validated through investigation, carries confidence score
+ * - fact: Resolved outcome anchored by strong evidence
+ */
+export const BELIEF_STATUSES = [
+  "assumption",
+  "hypothesis",
+  "belief",
+  "fact",
+] as const;
+export type BeliefStatus = (typeof BELIEF_STATUSES)[number];
+
+// =============================================================================
+// FORK REASONS
+// =============================================================================
+
+/** Why a scored belief was branched into a new version */
+export const FORK_REASONS = [
+  "refinement",
+  "contradiction_response",
+  "scope_change",
+  "confidence_collapse",
+  "manual",
+] as const;
+export type ForkReason = (typeof FORK_REASONS)[number];
+
+// =============================================================================
+// CONFIDENCE TRIGGERS
+// =============================================================================
+
+/** What caused a confidence change — every modulation must declare its trigger */
+export const CONFIDENCE_TRIGGERS = [
+  "evidence_added",
+  "contradiction_detected",
+  "merge_outcome",
+  "worktree_outcome",
+  "manual",
+  "decay",
+] as const;
+export type ConfidenceTrigger = (typeof CONFIDENCE_TRIGGERS)[number];
+
+// =============================================================================
+// EDGE TYPES — The 6 canonical epistemic edge types
+// =============================================================================
+
+/**
+ * Core epistemic edge types — the grammar of reasoning relationships.
+ *
+ * - supports: Evidence or belief reinforces another belief (weight = strength)
+ * - informs: Evidence bears on a belief (directional, weighted)
+ * - depends_on: Belief B requires belief A to hold
+ * - derived_from: Belief was derived from another (lineage)
+ * - contains: Structural containment (topic contains beliefs)
+ * - tests: Question tests a belief (falsification link)
+ */
+export const EPISTEMIC_EDGE_TYPES = [
+  "supports",
+  "informs",
+  "depends_on",
+  "derived_from",
+  "contains",
+  "tests",
+] as const;
+export type EpistemicEdgeType = (typeof EPISTEMIC_EDGE_TYPES)[number];
+
+/** Structural and lifecycle edges — required for graph integrity */
+export const STRUCTURAL_EDGE_TYPES = [
+  "supersedes",
+  "responds_to",
+  "belongs_to",
+  "relates_to_thesis",
+] as const;
+export type StructuralEdgeType = (typeof STRUCTURAL_EDGE_TYPES)[number];
+
+/** All valid edge types (epistemic + structural) */
+export const EDGE_TYPES = [
+  ...EPISTEMIC_EDGE_TYPES,
+  ...STRUCTURAL_EDGE_TYPES,
+] as const;
+export type EdgeType = EpistemicEdgeType | StructuralEdgeType;
+
+// =============================================================================
+// REASONING METHODS
+// =============================================================================
+
+/** How an edge relationship was determined */
+export const REASONING_METHODS = [
+  "deductive",
+  "inductive",
+  "abductive",
+  "analogical",
+  "empirical",
+] as const;
+export type ReasoningMethod = (typeof REASONING_METHODS)[number];
+
+// =============================================================================
+// CONTRADICTION ENUMS
+// =============================================================================
+
+/** Defeat types (Pollock taxonomy) — how a contradiction operates */
+export const DEFEAT_TYPES = [
+  "rebuts",
+  "undercuts",
+  "undermines",
+] as const;
+export type DefeatType = (typeof DEFEAT_TYPES)[number];
+
+/** Contradiction severity */
+export const CONTRADICTION_SEVERITIES = [
+  "low",
+  "medium",
+  "high",
+  "critical",
+] as const;
+export type ContradictionSeverity = (typeof CONTRADICTION_SEVERITIES)[number];
+
+/** Contradiction resolution status */
+export const CONTRADICTION_STATUSES = [
+  "unresolved",
+  "resolved",
+  "accepted",
+] as const;
+export type ContradictionStatus = (typeof CONTRADICTION_STATUSES)[number];
+
+// =============================================================================
+// WORKTREE ENUMS
+// =============================================================================
+
+/** How a worktree investigation concluded */
+export const MERGE_OUTCOMES = [
+  "validated",
+  "invalidated",
+  "forked",
+  "inconclusive",
+] as const;
+export type MergeOutcome = (typeof MERGE_OUTCOMES)[number];
+
+/** Investigation phases within a worktree */
+export const WORKTREE_PHASES = [
+  "hypothesis",
+  "investigation",
+  "evaluation",
+  "resolution",
+] as const;
+export type WorktreePhase = (typeof WORKTREE_PHASES)[number];
+
+// =============================================================================
+// EPISTEMIC LAYERS
+// =============================================================================
+
+/**
+ * The knowledge hierarchy — each layer builds on the one below it.
+ *
+ * - L1: Sources — raw inputs (documents, APIs, observations)
+ * - L2: Evidence — interpreted facts with context and weight
+ * - L3: Beliefs — structural claims that carry confidence
+ * - L4: Judgments — irreversible commitments based on the epistemic state
+ */
+export const EPISTEMIC_LAYERS = [
+  "L1",
+  "L2",
+  "L3",
+  "L4",
+] as const;
+export type EpistemicLayer = (typeof EPISTEMIC_LAYERS)[number];
+
+// =============================================================================
+// JUDGMENT TYPES
+// =============================================================================
+
+/**
+ * Classification of L4 judgments — irreversible determinations.
+ *
+ * Judgments are evaluated against the knowledge horizon that existed
+ * when they were made. They cannot be retroactively invalidated —
+ * only new judgments can supersede old ones.
+ */
+export const JUDGMENT_TYPES = [
+  "thesis",
+  "thesis_maturity",
+  "contradiction_ruling",
+  "scope_determination",
+  "confidence_ruling",
+] as const;
+export type JudgmentType = (typeof JUDGMENT_TYPES)[number];

package/src/contracts/auth-session.contract.ts

@@ -0,0 +1,109 @@
+/**
+ * Session + Delegation Contract
+ *
+ * Canonical session lifecycle vocabulary shared by platform gateway auth,
+ * hosted MCP auth, Master Control persistence, and SDK session tokens.
+ */
+
+export const SESSION_AUTH_MODES = [
+  "interactive_user",
+  "service_principal",
+  "tenant_api_key",
+  "session_token",
+] as const;
+export type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
+
+export const SESSION_PRINCIPAL_TYPES = ["human", "service", "agent"] as const;
+export type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];
+
+export const SESSION_LIFECYCLE_STATUSES = [
+  "active",
+  "expired",
+  "revoked",
+] as const;
+export type SessionLifecycleStatus =
+  (typeof SESSION_LIFECYCLE_STATUSES)[number];
+
+export type SessionDelegationHop = {
+  principalId: string;
+  principalType: SessionPrincipalType;
+  authMode?: SessionAuthMode;
+  sessionId?: string;
+  delegatedAt?: number;
+  reason?: string;
+};
+
+export type SessionAuditOutcome =
+  | "accepted"
+  | "rejected"
+  | "revoked"
+  | "expired";
+
+export type SessionAuditEnvelope = {
+  sessionId: string;
+  authMode: SessionAuthMode;
+  principalId: string;
+  principalType: SessionPrincipalType;
+  tenantId: string;
+  workspaceId?: string;
+  apiKeyId?: string;
+  scopes: readonly string[];
+  roles?: readonly string[];
+  delegationChain?: readonly SessionDelegationHop[];
+  sourceSessionId?: string;
+  expiresAt?: number;
+  request?: {
+    endpoint?: string;
+    method?: string;
+    correlationId?: string;
+  };
+  result?: {
+    outcome: SessionAuditOutcome;
+    reason?: string;
+  };
+};
+
+export function inferSessionPrincipalType(
+  principalId: string
+): SessionPrincipalType {
+  if (principalId.startsWith("user:")) {
+    return "human";
+  }
+  if (principalId.startsWith("agent:")) {
+    return "agent";
+  }
+  return "service";
+}
+
+export function normalizeDelegationChain(args: {
+  delegationChain?: readonly SessionDelegationHop[];
+  delegatedBy?: string;
+  delegatedByType?: SessionPrincipalType;
+  delegatedAt?: number;
+  reason?: string;
+}): SessionDelegationHop[] | undefined {
+  if (args.delegationChain && args.delegationChain.length > 0) {
+    return [...args.delegationChain];
+  }
+  if (!args.delegatedBy) {
+    return;
+  }
+  return [
+    {
+      principalId: args.delegatedBy,
+      principalType:
+        args.delegatedByType ?? inferSessionPrincipalType(args.delegatedBy),
+      delegatedAt: args.delegatedAt,
+      reason: args.reason,
+    },
+  ];
+}
+
+export function lastDelegator(
+  delegationChain?: readonly SessionDelegationHop[]
+): string | undefined {
+  if (!delegationChain || delegationChain.length === 0) {
+    return;
+  }
+  return delegationChain[delegationChain.length - 1]?.principalId;
+}