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

package/src/api-enums.contract.ts

@@ -1,183 +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
-] as const;
-export type ForkReason = (typeof FORK_REASONS)[number];
-
-/** 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
-] as const;
-export type ConfidenceTrigger = (typeof CONFIDENCE_TRIGGERS)[number];
-
-/** 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)
-] as const;
-export type BeliefStatus = (typeof BELIEF_STATUSES)[number];
-
-// =============================================================================
-// 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
-] as const;
-export type ReasoningMethod = (typeof REASONING_METHODS)[number];
-
-/** 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
-] as const;
-export type DefeatType = (typeof DEFEAT_TYPES)[number];
-
-/** 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
-] as const;
-export type ContradictionSeverity = (typeof CONTRADICTION_SEVERITIES)[number];
-
-/** 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
-] as const;
-export type ContradictionStatus = (typeof CONTRADICTION_STATUSES)[number];
-
-// =============================================================================
-// 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)
-] as const;
-export type MergeOutcome = (typeof MERGE_OUTCOMES)[number];
-
-/** 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)
-] as const;
-export type WorktreePhase = (typeof WORKTREE_PHASES)[number];
-
-// =============================================================================
-// 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
-] as const;
-export type BranchStatus = (typeof BRANCH_STATUSES)[number];
-
-// =============================================================================
-// 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
-] as const;
-export type PullRequestStatus = (typeof PULL_REQUEST_STATUSES)[number];
-
-// =============================================================================
-// 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)
-] as const;
-export type EpistemicLayer = (typeof EPISTEMIC_LAYERS)[number];
-
-// =============================================================================
-// 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
-] as const;
-export type JudgmentType = (typeof JUDGMENT_TYPES)[number];
-
-// =============================================================================
-// 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
-] as const;
-export type IntegrationEdgeType = (typeof INTEGRATION_EDGE_TYPES)[number];

package/src/auth-context.contract.ts

@@ -1,9 +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/src/auth-session.contract.ts

@@ -1,9 +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/src/auth.contract.ts

@@ -1,162 +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",
-] 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;
-}
-
-// =============================================================================
-// AUTH CONTEXT
-// (Formerly src/auth-context.contract.ts)
-// =============================================================================
-
-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; // AGENT_IDENTITY for agents, Clerk userId for users
-  tenantId: string;
-  role: string; // "agent:internal" | "platform_admin" | "tenant_admin" | "editor" | "viewer" | ...
-  allowedTopics: string[] | null; // null = unrestricted (agents, admins). Block 11D populates this.
-  // Layer 2a: Group-pack binding — resolved at boot from MC resolveUserPackAccess
-  groupIds: string[]; // Groups this user belongs to (empty for agents)
-  permittedPackKeys: string[]; // Packs accessible via group assignments (empty = no pack filtering)
-  sessionId: string; // S2-13K: MCP process session UUID for audit attribution
-  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/src/beliefs/v1.ts

@@ -1,8 +0,0 @@
-/**
- * Beliefs API Contract v1
- *
- * Defines the public surface for belief operations:
- * create, refine, fork, score, archive, search, lineage.
- * Migrates from front-end/lucern/contracts/ during EK-16.
- */
-export {};