@lucern/contracts 0.1.0-alpha.3 → 0.1.1-alpha.1

package/package.json

@@ -1,68 +1,25 @@
 {
   "name": "@lucern/contracts",
-  "version": "0.1.0-alpha.3",
-  "description": "Lucern shared boundary contracts and public types",
-  "license": "UNLICENSED",
-  "private": false,
+  "version": "0.1.1-alpha.1",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./v1/beliefs": {
-      "types": "./dist/v1/beliefs/v1.d.ts",
-      "import": "./dist/v1/beliefs/v1.js"
-    },
-    "./v1/evidence": {
-      "types": "./dist/v1/evidence/v1.d.ts",
-      "import": "./dist/v1/evidence/v1.js"
-    },
-    "./v1/questions": {
-      "types": "./dist/v1/questions/v1.d.ts",
-      "import": "./dist/v1/questions/v1.js"
-    },
-    "./v1/topics": {
-      "types": "./dist/v1/topics/v1.d.ts",
-      "import": "./dist/v1/topics/v1.js"
-    },
-    "./v1/graph": {
-      "types": "./dist/v1/graph/v1.d.ts",
-      "import": "./dist/v1/graph/v1.js"
-    },
-    "./v1/agents": {
-      "types": "./dist/v1/agents/v1.d.ts",
-      "import": "./dist/v1/agents/v1.js"
-    },
-    "./v1/worktrees": {
-      "types": "./dist/v1/worktrees/v1.d.ts",
-      "import": "./dist/v1/worktrees/v1.js"
-    },
-    "./v1/ontologies": {
-      "types": "./dist/v1/ontologies/v1.d.ts",
-      "import": "./dist/v1/ontologies/v1.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js"
-    }
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./v1/*": "./src/v1/*.ts"
   },
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run build"
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "sideEffects": false
+  }
 }

package/src/agents/v1.ts

@@ -0,0 +1,8 @@
+/**
+ * Agent API Contract v1
+ *
+ * Defines the public surface for agent operations:
+ * session management, message passing, coordination, claims.
+ * Migrates from front-end/lucern/contracts/ during EK-16.
+ */
+export {};

package/src/api-enums.contract.ts

@@ -0,0 +1,183 @@
+/**
+ * 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/{dist/auth-context.contract.js → src/auth-context.contract.ts}

@@ -5,5 +5,5 @@
  * 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";
-//# sourceMappingURL=auth-context.contract.js.map

package/{dist/auth-session.contract.js → src/auth-session.contract.ts}

@@ -5,5 +5,5 @@
  * 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";
-//# sourceMappingURL=auth-session.contract.js.map

package/src/auth.contract.ts

@@ -0,0 +1,162 @@
+/**
+ * @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

@@ -0,0 +1,8 @@
+/**
+ * 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 {};