@lucern/sdk 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/lucern/contracts/src/api-enums.contract.js

@@ -1,147 +0,0 @@
-/**
- * API Enum Contract Definitions
- *
- * Canonical enum values for all API-facing enumerations.
- * These are co-equal with MCP contracts as external contracts.
- * SDK types are DERIVED from these — not independently authored.
- *
- * CONTRACT SURFACE: Adding a new enum value is additive (non-breaking).
- * Removing or renaming an existing value is a BREAKING CHANGE.
- */
-// =============================================================================
-// BELIEF ENUMS
-// =============================================================================
-/** Fork reasons — why a scored belief was branched */
-export const FORK_REASONS = [
-    "refinement", // Belief text evolved based on new understanding
-    "contradiction_response", // Created in response to a detected contradiction
-    "scope_change", // Belief scope narrowed or broadened
-    "confidence_collapse", // Confidence dropped below viability threshold
-    "manual", // User-initiated fork without specific trigger
-];
-/** Confidence modulation triggers — what caused a confidence change */
-export const CONFIDENCE_TRIGGERS = [
-    "evidence_added", // New evidence bore on the belief
-    "contradiction_detected", // A contradiction was flagged involving this belief
-    "merge_outcome", // Merge scoring determined this confidence
-    "manual", // User manually adjusted confidence
-    "decay", // Time-based confidence erosion
-];
-/** Belief status — lifecycle state */
-export const BELIEF_STATUSES = [
-    "unscored", // Draft — editable in worktree (on feature branch, pre-merge)
-    "scored", // Merged — formulation frozen (merged to main)
-    "archived", // Soft-deleted — preserved in history (git rm)
-];
-// =============================================================================
-// EDGE ENUMS
-// =============================================================================
-/** Reasoning methods — how an edge relationship was determined */
-export const REASONING_METHODS = [
-    "deductive", // Logically entailed
-    "inductive", // Generalized from instances
-    "abductive", // Best explanation inference
-    "analogical", // Reasoning by analogy
-    "empirical", // Direct observation/measurement
-];
-/** Defeat types (Pollock taxonomy) — how a contradiction operates */
-export const DEFEAT_TYPES = [
-    "rebuts", // Direct contradiction — reasons for the negation
-    "undercuts", // Breaks the inference link between evidence and belief
-    "undermines", // Attacks a premise the belief depends on
-];
-/** Contradiction severity levels */
-export const CONTRADICTION_SEVERITIES = [
-    "low", // Minor tension, may not require action
-    "medium", // Moderate conflict, should be investigated
-    "high", // Significant contradiction, likely needs resolution
-    "critical", // Blocks progress — must be addressed before judgment
-];
-/** Contradiction resolution status */
-export const CONTRADICTION_STATUSES = [
-    "unresolved", // Open conflict — may persist indefinitely
-    "resolved", // Conflict addressed (one belief forked, archived, or confidence adjusted)
-    "accepted", // Explicitly accepted as irreconcilable — both beliefs maintained
-];
-// =============================================================================
-// WORKTREE ENUMS (git worktree lifecycle)
-// =============================================================================
-/** Merge outcome types — how a worktree merge resolved */
-export const MERGE_OUTCOMES = [
-    "validated", // Beliefs confirmed — clean merge to main
-    "invalidated", // Defeat recorded — confidence collapsed (merge with revert)
-    "forked", // Beliefs split into competing versions (fork from merge point)
-    "inconclusive", // Insufficient evidence — stashed (git stash)
-];
-/** Worktree phases — investigation lifecycle within a checked-out worktree */
-export const WORKTREE_PHASES = [
-    "hypothesis", // Form testable claims (write the code — commits)
-    "investigation", // Collect evidence (run the tests — more commits)
-    "evaluation", // Update credences (review the results — amend as needed)
-    "resolution", // Determine outcome (merge to main, fork, or stash)
-];
-// =============================================================================
-// BRANCH ENUMS (git branch lifecycle)
-// =============================================================================
-/** Branch status — thematic branch lifecycle */
-export const BRANCH_STATUSES = [
-    "dormant", // Branch exists but no active worktree (no one investigating)
-    "active", // At least one worktree is investigating this branch
-    "archived", // Branch retired — no longer a relevant thematic container
-];
-// =============================================================================
-// PULL REQUEST ENUMS (git pull request lifecycle)
-// =============================================================================
-/** Pull request status — review lifecycle before merge */
-export const PULL_REQUEST_STATUSES = [
-    "pending_review", // PR opened — awaiting reviewer feedback
-    "changes_requested", // Reviewer requests changes before merge
-    "approved", // Approved — ready to merge
-    "blocked", // Blocked — cannot merge until contradiction is resolved
-];
-// =============================================================================
-// LAYER ENUMS
-// =============================================================================
-/** Epistemic layers — the hierarchy of knowledge */
-export const EPISTEMIC_LAYERS = [
-    "L1", // Source — the given (vendored deps)
-    "L2", // Evidence — the interpreted (test suite)
-    "L3", // Belief — the structural (source files)
-    "L4", // Judgment — the committed (release tags)
-];
-// =============================================================================
-// JUDGMENT ENUMS (Phase 1: new vocabulary)
-// =============================================================================
-/**
- * Judgment type — classification of the determination.
- *
- * Phase 1: These are new enum values for the Judgment (L4) vocabulary.
- * The existing code uses "Decision" — these are the forward-looking terms
- * that will eventually replace the Decision vocabulary (Phase 2-3).
- */
-export const JUDGMENT_TYPES = [
-    "investment_thesis", // Judgment on an investment opportunity
-    "thesis_maturity", // Judgment that a thesis is ready for IC presentation
-    "contradiction_ruling", // Judgment on how to handle an irreconcilable contradiction
-    "scope_determination", // Judgment that defines or redefines investigation scope
-    "confidence_ruling", // Judgment that overrides automated confidence for policy reasons
-];
-// =============================================================================
-// SUPPORT RELATION ENUMS
-// =============================================================================
-/** Core edge types used in the Integration Surfaces */
-export const INTEGRATION_EDGE_TYPES = [
-    // Support relations
-    "informs", // Evidence bears on a belief (weight = direction/strength)
-    "grounds", // Source provides raw basis for evidence
-    "answers", // Evidence or belief resolves a question
-    // Defeat relations (Pollock) — weight carries direction
-    "contradicts", // Rebuts — direct contradiction
-    "supports", // Weight carries valence (negative = weakens/undercuts)
-    // Structural relations
-    "depends_on", // Belief B requires Belief A
-    "derived_from", // Provenance lineage
-    "contains", // Hierarchical containment
-    "supersedes", // New version replaces old (lineage)
-    "tests", // Question tests a belief
-];

package/dist/lucern/contracts/src/auth-context.contract.d.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — auth-context compat shim
- *
- * This file consolidated into ./auth.contract.ts during EK-16 T1 PR 3a.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./auth.contract".
- */
-export * from "./auth.contract";

package/dist/lucern/contracts/src/auth-context.contract.js

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — auth-context compat shim
- *
- * This file consolidated into ./auth.contract.ts during EK-16 T1 PR 3a.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./auth.contract".
- */
-export * from "./auth.contract.js";

package/dist/lucern/contracts/src/auth-session.contract.d.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — auth-session compat shim
- *
- * This file consolidated into ./auth.contract.ts during EK-16 T1 PR 3a.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./auth.contract".
- */
-export * from "./auth.contract";

package/dist/lucern/contracts/src/auth-session.contract.js

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — auth-session compat shim
- *
- * This file consolidated into ./auth.contract.ts during EK-16 T1 PR 3a.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./auth.contract".
- */
-export * from "./auth.contract.js";

package/dist/lucern/contracts/src/auth.contract.d.ts

@@ -1,88 +0,0 @@
-/**
- * @lucern/contracts — auth (canonical support contract)
- *
- * Consolidated flat support surface for Lucern authentication:
- *   - Session primitives (auth modes, principal types, lifecycle)
- *   - AuthContext shape + McpTransportKind + LucernSdkClient alias
- *
- * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts
- * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).
- */
-export declare const SESSION_AUTH_MODES: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
-export type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
-export declare const SESSION_PRINCIPAL_TYPES: readonly ["human", "service", "agent"];
-export type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];
-export declare const SESSION_LIFECYCLE_STATUSES: readonly ["active", "expired", "revoked"];
-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 declare function inferSessionPrincipalType(principalId: string): SessionPrincipalType;
-export declare function normalizeDelegationChain(args: {
-    delegationChain?: readonly SessionDelegationHop[];
-    delegatedBy?: string;
-    delegatedByType?: SessionPrincipalType;
-    delegatedAt?: number;
-    reason?: string;
-}): SessionDelegationHop[] | undefined;
-export declare function lastDelegator(delegationChain?: readonly SessionDelegationHop[]): string | undefined;
-import type { ConvexAdminClient } from "./convex-admin.contract";
-export type McpTransportKind = "stdio" | "hosted";
-export type LucernSdkClient = unknown;
-/**
- * Session authentication context — injected by withAuth() middleware.
- *
- * Built from TenantConfig at dispatch time. Agent sessions get
- * AGENT_IDENTITY + "agent:internal" role + unrestricted access.
- * User sessions get Clerk userId + resolved role + tool ACLs.
- */
-export type AuthContext = {
-    sessionType: "agent" | "user";
-    userId: string;
-    tenantId: string;
-    role: string;
-    allowedTopics: string[] | null;
-    groupIds: string[];
-    permittedPackKeys: string[];
-    sessionId: string;
-    principalId?: string;
-    principalType?: SessionPrincipalType;
-    workspaceId?: string;
-    scopes?: string[];
-    authMode?: SessionAuthMode;
-    roles?: string[];
-    transportKind?: McpTransportKind;
-    lucernClient?: LucernSdkClient;
-    convex?: ConvexAdminClient;
-    setDefaultScopeContext?: (scopeId: string) => Promise<unknown>;
-    matchesWorkspaceReasoningScope?: (node: unknown, scope: unknown) => boolean;
-};

package/dist/lucern/contracts/src/auth.contract.js

@@ -1,57 +0,0 @@
-/**
- * @lucern/contracts — auth (canonical support contract)
- *
- * Consolidated flat support surface for Lucern authentication:
- *   - Session primitives (auth modes, principal types, lifecycle)
- *   - AuthContext shape + McpTransportKind + LucernSdkClient alias
- *
- * Consolidated from src/auth-session.contract.ts and src/auth-context.contract.ts
- * in EK-16 T1 PR 3a. Compat shims remain at both old paths until Lucern 1.0.0 (D12).
- */
-// =============================================================================
-// SESSION PRIMITIVES
-// (Formerly src/auth-session.contract.ts)
-// =============================================================================
-export const SESSION_AUTH_MODES = [
-    "interactive_user",
-    "service_principal",
-    "tenant_api_key",
-    "session_token",
-];
-export const SESSION_PRINCIPAL_TYPES = ["human", "service", "agent"];
-export const SESSION_LIFECYCLE_STATUSES = [
-    "active",
-    "expired",
-    "revoked",
-];
-export function inferSessionPrincipalType(principalId) {
-    if (principalId.startsWith("user:")) {
-        return "human";
-    }
-    if (principalId.startsWith("agent:")) {
-        return "agent";
-    }
-    return "service";
-}
-export function normalizeDelegationChain(args) {
-    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) {
-    if (!delegationChain || delegationChain.length === 0) {
-        return;
-    }
-    return delegationChain[delegationChain.length - 1]?.principalId;
-}

package/dist/lucern/contracts/src/context-pack.contract.js

@@ -1,169 +0,0 @@
-/**
- * Context-Pack Contract v1
- *
- * Canonical TypeScript types and constants for the context-pack output schema.
- * This is the external contract consumed by:
- *   - MCP tool `compile_context` (canonical compiler read)
- *   - SDK/HTTP consumers that read compiled context packs programmatically
- *   - Benchmark harnesses (context-pack-ab)
- *
- * BREAKING CHANGE RULES:
- *   - Adding optional fields to ContextPackV1 is NON-breaking
- *   - Removing fields or changing types is BREAKING (bump CONTEXT_PACK_SCHEMA_VERSION)
- *   - Changing section budget ratios or ranking weights is NON-breaking (tuning)
- *   - Changing the version string is BREAKING (consumers check it)
- */
-// =============================================================================
-// SCHEMA VERSION
-// =============================================================================
-/** Canonical version string. Consumers MUST check this field for compatibility. */
-export const CONTEXT_PACK_SCHEMA_VERSION = "1.0.0";
-export const CONTEXT_RANKING_PROFILES = [
-    "baseline_v1",
-    "weighted_v1",
-];
-export const DEFAULT_RANKING_PROFILE = "weighted_v1";
-export const DEFAULT_COMPILATION_MODE = "standard";
-export const CONTEXT_PACK_SECTION_KEYS = [
-    "invariants",
-    "activeBeliefs",
-    "openQuestions",
-    "recentEvidence",
-    "contradictions",
-];
-// =============================================================================
-// SECTION BUDGET RATIOS
-// =============================================================================
-/**
- * Token budget allocation ratios per section.
- * These sum to 1.0 and determine how the total tokenBudget is divided.
- *
- * Rationale:
- * - invariants (0.28): Highest-priority constraints, injected first
- * - activeBeliefs (0.30): Largest section, carries domain knowledge
- * - openQuestions (0.17): Unresolved work items guide agent behavior
- * - recentEvidence (0.17): Implementation context for grounding
- * - contradictions (0.08): Tension signals, smallest section
- */
-export const SECTION_BUDGET_RATIOS = {
-    invariants: 0.28,
-    activeBeliefs: 0.3,
-    openQuestions: 0.17,
-    recentEvidence: 0.17,
-    contradictions: 0.08,
-};
-// =============================================================================
-// TOKEN BUDGET CONSTRAINTS
-// =============================================================================
-/** Minimum allowed token budget. Below this, context packs lose utility. */
-export const MIN_TOKEN_BUDGET = 400;
-/** Maximum allowed token budget. Above this, context packs bloat prompts. */
-export const MAX_TOKEN_BUDGET = 8000;
-/** Default token budget when caller does not specify. */
-export const DEFAULT_TOKEN_BUDGET = 1800;
-/** Default max items per section. */
-export const DEFAULT_SECTION_LIMIT = 8;
-/** Hard ceiling on items per section. */
-export const MAX_SECTION_LIMIT = 25;
-/** Minimum contradiction section budget floor (tokens). */
-export const MIN_CONTRADICTION_BUDGET = 40;
-export const RANKING_WEIGHTS = {
-    invariants: {
-        query: 0.35,
-        recency: 0.1,
-        confidence: 0.4,
-        beliefType: 0.15,
-    },
-    activeBeliefs: {
-        query: 0.5,
-        recency: 0.2,
-        confidence: 0.2,
-        beliefType: 0.1,
-    },
-    openQuestions: {
-        query: 0.55,
-        recency: 0.2,
-        priority: 0.25,
-    },
-    recentEvidence: {
-        query: 0.6,
-        recency: 0.4,
-    },
-    contradictions: {
-        query: 0.4,
-        recency: 0.2,
-        severity: 0.4,
-    },
-};
-/** Recency decay half-life in days. After 30 days, recency score = 0.5. */
-export const RECENCY_HALF_LIFE_DAYS = 30;
-/**
- * Ranking weight vector for the relatedEntities section.
- * Entities are ranked by query relevance and connectivity (bridge edge count).
- * Separate from RANKING_WEIGHTS because entities are not part of the
- * token-budgeted injection plan.
- */
-export const ENTITY_RANKING_WEIGHTS = {
-    query: 0.4,
-    connectivity: 0.6,
-};
-/** Default max entities to include in the context pack. */
-export const DEFAULT_ENTITY_LIMIT = 10;
-/** Hard ceiling on entities per context pack. */
-export const MAX_ENTITY_LIMIT = 50;
-// =============================================================================
-// BELIEF TYPE BONUS MAP
-// =============================================================================
-/**
- * Bonus multiplier for belief types in ranking.
- * Invariants get 1.0, unknown types get 0.4.
- */
-export const BELIEF_TYPE_BONUS = {
-    invariant: 1.0,
-    tenet: 0.8,
-    principle: 0.6,
-};
-export const DEFAULT_BELIEF_TYPE_BONUS = 0.4;
-// =============================================================================
-// PRIORITY / SEVERITY SCORE MAPS
-// =============================================================================
-export const PRIORITY_SCORES = {
-    critical: 1.0,
-    high: 0.85,
-    medium: 0.55,
-    low: 0.35,
-};
-export const DEFAULT_PRIORITY_SCORE = 0.5;
-export const SEVERITY_SCORES = {
-    critical: 1.0,
-    high: 0.85,
-    medium: 0.6,
-    low: 0.35,
-};
-export const DEFAULT_SEVERITY_SCORE = 0.5;
-// =============================================================================
-// RESOLVED QUESTION STATUSES
-// =============================================================================
-/**
- * Question statuses that are considered "resolved" (not open).
- * Used to filter which questions appear in the openQuestions section.
- */
-export const RESOLVED_QUESTION_STATUSES = [
-    "answered",
-    "archived",
-    "closed",
-    "resolved",
-    "resolved_support",
-    "resolved_contra",
-    "belief_forked",
-];
-// =============================================================================
-// TOKEN ESTIMATION
-// =============================================================================
-/**
- * Tokens-per-word multiplier for rough token estimation.
- * Conservative estimate: ~1.35 tokens per whitespace-delimited word.
- */
-export const TOKENS_PER_WORD = 1.35;
-/** Minimum token estimate for any non-empty string. */
-export const MIN_TOKEN_ESTIMATE = 8;

package/dist/lucern/contracts/src/convex-admin.contract.d.ts

@@ -1,5 +0,0 @@
-export interface ConvexAdminClient {
-    query<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
-    mutation<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
-    action<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
-}

package/dist/lucern/contracts/src/convex-admin.contract.js

@@ -1 +0,0 @@
-export {};

package/dist/lucern/contracts/src/events-types.contract.d.ts

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — events-types compat shim
- *
- * This file consolidated into ./events.contract.ts during EK-16 T1 PR 3b.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./events.contract".
- */
-export * from "./events.contract";

package/dist/lucern/contracts/src/events-types.contract.js

@@ -1,8 +0,0 @@
-/**
- * @lucern/contracts — events-types compat shim
- *
- * This file consolidated into ./events.contract.ts during EK-16 T1 PR 3b.
- * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
- * New code should import from "@lucern/contracts" (barrel) or "./events.contract".
- */
-export * from "./events.contract.js";