@lucern/sdk 0.3.0-alpha.0 → 0.3.0-alpha.10

package/CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to `@lucern/sdk` will be documented in this file.
 ## [Unreleased]
 - No unreleased changes yet.
 
+## [0.3.0-alpha.7] - 2026-05-03
+- Rebuild the coherent Lucern package line after Campaign 1 SDK hardening fixes.
+
 ## [0.2.0-alpha.5] - 2026-04-18
 - Refresh publish from current stackos source under EK-16 T4.
 - Version-numbering note: 0.2.0-alpha.2 through 0.2.0-alpha.5 were published from earlier stackos source on 2026-04-12 by pete_c. This release (alpha.5) is the first to ship the current April 18 source — 56 commits of accumulated changes from the code-separation track.

package/README.md

@@ -10,6 +10,31 @@ Lucern gives your agents a reasoning graph that accumulates understanding across
 npm install @lucern/sdk
 ```
 
+## Install Model
+
+`@lucern/sdk` is the primary TypeScript app dependency. Installing it also
+installs its internal runtime dependencies, including Lucern contracts and
+reasoning-kernel helpers, but a tenant should still list any `@lucern/*`
+package that its own code or scripts import or execute.
+
+Common direct installs:
+
+| Need | Install |
+| --- | --- |
+| Programmatic Lucern API calls | `@lucern/sdk` |
+| Tool access checks | `@lucern/access-control` |
+| React hooks/components | `@lucern/react @lucern/sdk` |
+| Convex component binding | `@lucern/identity @lucern/reasoning-kernel` |
+| Bootstrap, auth, doctor, and operator commands | `@lucern/cli` |
+| Agent-facing MCP server/runtime | `@lucern/mcp` |
+| Full design-partner/package-suite pin | all packages from `TENANT_CLIENT_INSTALLABLE_PACKAGES` in `@lucern/contracts` |
+
+The difference matters: `@lucern/cli` is a direct install because it provides
+the `lucern` binary, but tenant app source should not import it. The Convex
+component packages are direct installs for `convex.config.ts`, while application
+code should stay on `@lucern/sdk`, `@lucern/react`, `@lucern/mcp`,
+`@lucern/access-control`, `@lucern/contracts`, and `@lucern/types`.
+
 ## Canonical Interface
 
 `@lucern/sdk` is the canonical public interface for Lucern.
@@ -27,6 +52,7 @@ IA-7 closes the remaining SDK surface gaps needed for SDK-first clients:
 ```typescript
 import {
   createLucernClient,
+  opinionFromDogmatic,
   type PlatformBeliefRecord,
   type SdkPrincipalContext,
   type WorkflowWorktreeRecord,
@@ -87,45 +113,54 @@ const topicId = securityTopic.data.topicId;
 // A fact — verified and anchored
 const sqlFact = await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "Parameterized queries prevent SQL injection in all major database drivers",
   beliefType: "fact",
 });
+const sqlFactEvidence = await lucern.evidence.create({
+  topicId,
+  text: "OWASP SQL Injection Prevention guidance identifies parameterized queries as the primary defense.",
+  sourceUrl: "https://owasp.org/www-community/attacks/SQL_Injection",
+  targetId: sqlFact.data.nodeId,
+  weight: 1,
+});
 await lucern.beliefs.modulateConfidence(sqlFact.data.nodeId, {
-  confidence: 0.95,
+  opinion: opinionFromDogmatic(0.95, 0.5),
   trigger: "evidence_added",
+  triggeringEvidenceId: sqlFactEvidence.data.nodeId,
   rationale: "OWASP verified, industry standard for 20+ years",
 });
 
 // A belief — confident from observation
 const patternBelief = await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "Most security vulnerabilities in our codebase come from unvalidated user input at API boundaries, not from cryptographic weaknesses",
 });
+const patternEvidence = await lucern.evidence.create({
+  topicId,
+  text: "Last 6 months of security audits found 14 input validation issues and 1 cryptographic issue.",
+  sourceUrl: "audit://security/findings-last-6-months",
+  targetId: patternBelief.data.nodeId,
+  weight: 0.82,
+});
 await lucern.beliefs.modulateConfidence(patternBelief.data.nodeId, {
-  confidence: 0.82,
+  opinion: opinionFromDogmatic(0.82, 0.5),
   trigger: "evidence_added",
+  triggeringEvidenceId: patternEvidence.data.nodeId,
   rationale: "Last 6 months of security audits: 14 input validation issues, 1 crypto issue",
 });
 
 // A hypothesis — under active testing
 const hypothesis = await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "Automated static analysis catches fewer than 30% of the input validation vulnerabilities that human reviewers find",
   beliefType: "hypothesis",
 });
-await lucern.beliefs.modulateConfidence(hypothesis.data.nodeId, {
-  confidence: 0.6,
-  trigger: "manual",
-  rationale: "Anecdotal — need to run a proper comparison study",
-});
+// This remains at the default vacuous prior until evidence or an answered
+// question records what the comparison study found.
 
 // An assumption — untested but used as a basis for decisions
 const assumption = await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "Our CI pipeline runs all static analysis rules on every PR",
   beliefType: "assumption",
 });
@@ -202,7 +237,7 @@ Your agent processes the results and commits evidence to the graph.
 
 ```typescript
 // Static analysis results
-await lucern.evidence.create({
+const staticEvidence = await lucern.evidence.create({
   topicId,
   text: "Semgrep + CodeQL found 23 issues across 50 PRs. 18 were true positives. Categories: 12 input validation, 4 auth bypass patterns, 2 information disclosure.",
   sourceUrl: "ci://semgrep-run/batch-50pr-comparison",
@@ -211,7 +246,7 @@ await lucern.evidence.create({
 });
 
 // Human review results
-await lucern.evidence.create({
+const humanEvidence = await lucern.evidence.create({
   topicId,
   text: "Two senior engineers found 41 issues across the same 50 PRs (34 unique after dedup). Categories: 22 input validation, 7 business logic flaws, 3 auth, 2 race conditions.",
   sourceUrl: "review://manual-audit/batch-50pr",
@@ -227,7 +262,7 @@ const comparisonQuestion = await lucern.questions.create({
   linkedBeliefId: hypothesis.data.nodeId,
 });
 
-await lucern.questions.answer(comparisonQuestion.data.questionId, {
+const comparisonAnswer = await lucern.questions.answer(comparisonQuestion.data.questionId, {
   text: "Static analysis caught 18 of 34 unique issues (53%). However, it missed all 7 business logic flaws and both race conditions — categories where it found 0%.",
   confidence: "strong",
   evidenceIds: [staticEvidence.data.nodeId, humanEvidence.data.nodeId],
@@ -241,8 +276,9 @@ The original hypothesis said "less than 30%." The data shows 53% — but the sto
 ```typescript
 // Drop confidence on the original (it was too pessimistic about overall catch rate)
 await lucern.beliefs.modulateConfidence(hypothesis.data.nodeId, {
-  confidence: 0.2,
+  opinion: opinionFromDogmatic(0.2, 0.5),
   trigger: "evidence_added",
+  triggeringEvidenceId: humanEvidence.data.nodeId,
   rationale: "Static analysis catches 53% overall, not <30%. But the category breakdown reveals something more important.",
 });
 
@@ -253,22 +289,24 @@ const evolved = await lucern.beliefs.fork(hypothesis.data.nodeId, {
 });
 
 await lucern.beliefs.modulateConfidence(evolved.data.nodeId, {
-  confidence: 0.88,
+  opinion: opinionFromDogmatic(0.88, 0.5),
   trigger: "evidence_added",
+  triggeringEvidenceId: humanEvidence.data.nodeId,
+  triggeringAnswerId: comparisonAnswer.data.answerId,
   rationale: "Direct comparison data: 0/7 business logic flaws caught, 0/2 race conditions caught, while input validation catch rate was 12/22 (55%)",
 });
 
 // This creates a new actionable belief
 const actionable = await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "Human code review should focus on business logic and concurrency — the categories where static analysis provides zero coverage",
   beliefType: "belief",
 });
 
 await lucern.beliefs.modulateConfidence(actionable.data.nodeId, {
-  confidence: 0.85,
+  opinion: opinionFromDogmatic(0.85, 0.5),
   trigger: "worktree_outcome",
+  triggeringWorktreeId: investigation.data.worktreeId,
   rationale: "Direct implication of the comparison study findings",
 });
 
@@ -288,7 +326,7 @@ await lucern.graph.createEdge({
 Before your agent starts its next session, it reads the graph:
 
 ```typescript
-const context = await lucern.context.compile(topicId, {
+const context = await lucern.context.compile({
   query: "code review strategy and static analysis coverage",
   ranking: "weighted_v1",
   tokenBudget: 2000,
@@ -350,6 +388,28 @@ lucern.identity       // API keys and sessions
 
 The graph doesn't just store knowledge — it analyzes itself.
 
+### Query Suite
+
+```typescript
+// Discover the prompt-backed Graph Intelligence recipes tenants can expose in
+// their own UI or model workflows.
+const catalog = await lucern.graphAnalysis.listGraphIntelligenceQueries();
+
+// Run a named recipe. Lucern returns the resolved prompt, deterministic graph
+// analysis bundle, sampled graph context, and public tool plan for LLM synthesis.
+const preMortem = await lucern.graphAnalysis.runGraphIntelligenceQuery({
+  topicId,
+  queryId: "pre-mortem",
+  limit: 25,
+});
+
+await modelMachine.run({
+  prompt: preMortem.data.prompt,
+  context: preMortem.data.analysis,
+  tools: preMortem.data.toolPlan,
+});
+```
+
 ### Structural Analysis
 
 ```typescript
@@ -432,7 +492,7 @@ traversal.data.nodes.forEach(node => {
 ### Inject Reasoning Context Into Any LLM Call
 
 ```typescript
-const context = await lucern.context.compile(topicId, {
+const context = await lucern.context.compile({
   query: "security review priorities",
   ranking: "weighted_v1",
   tokenBudget: 3000,
@@ -543,7 +603,7 @@ architectural decisions, check the reasoning graph:
 
 - Read current beliefs: `lucern.beliefs.list({ topicId: "..." })`
 - Check for contradictions: `lucern.contradictions.list({ topicId: "..." })`
-- Compile context before analysis: `lucern.context.compile(topicId, { query: "..." })`
+- Compile context before analysis: `lucern.context.compile({ query: "..." })`
 
 After making decisions, write them back:
 - Create beliefs for architectural decisions
@@ -574,7 +634,7 @@ contradictions, or knowledge state.
 Compile the current context to understand what the graph knows:
 
 \`\`\`typescript
-const context = await lucern.context.compile(topicId, {
+const context = await lucern.context.compile({
   query: "<what you're working on>",
   tokenBudget: 2000,
 });
@@ -591,7 +651,6 @@ Record what you learned:
 // Create a belief for decisions made
 await lucern.beliefs.create({
   topicId,
-  baseRate: 0.5,
   canonicalText: "<what you now believe to be true>",
 });
 
@@ -706,8 +765,8 @@ history.data.forEach(entry => {
 });
 
 // Example output:
-// 2026-04-10T14:00:00Z null -> 0.60 [manual] Anecdotal observation
-// 2026-04-11T09:30:00Z 0.60 -> 0.75 [evidence_added] Semgrep data supports
+// 2026-04-10T14:00:00Z null -> 0.50 [initial] Vacuous neutral prior
+// 2026-04-11T09:30:00Z 0.50 -> 0.75 [evidence_added] Semgrep data supports
 // 2026-04-11T16:00:00Z 0.75 -> 0.20 [evidence_added] Comparison study contradicted
 ```
 

package/dist/adminClient.d.ts

@@ -2,6 +2,8 @@ import { GatewayClientConfig, PlatformGatewaySuccess, GatewayScope } from './cor
 export { LucernApiError } from './coreClient.js';
 import { ListResult, JsonObject } from './types.js';
 import { ControlObjectOwnershipContract } from './controlObjectOwnership.js';
+import './authContext.js';
+import './contracts/auth-session.contract.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
 import './contracts/lens-filter.contract.js';
@@ -151,11 +153,11 @@ declare function createAdminClient(config?: AdminClientConfig): {
     /**
      * Get the control-object ownership contract.
      */
-    getControlObjectOwnership(): Promise<PlatformGatewaySuccess<ControlObjectOwnershipContract>>;
+    getControlObjectOwnership: () => Promise<PlatformGatewaySuccess<ControlObjectOwnershipContract>>;
     /**
      * @deprecated Use getControlObjectOwnership.
      */
-    getControlObjectOwnershipContract(): Promise<PlatformGatewaySuccess<ControlObjectOwnershipContract>>;
+    getControlObjectOwnershipContract: () => Promise<PlatformGatewaySuccess<ControlObjectOwnershipContract>>;
     /**
      * List workspaces for the current admin scope.
      */
@@ -188,33 +190,33 @@ declare function createAdminClient(config?: AdminClientConfig): {
     /**
      * Create a membership.
      */
-    createMembership(input: GatewayScope & {
+    createMembership: (input: GatewayScope & {
         membershipId?: string;
         principalId: string;
         role: "platform_admin" | "tenant_admin" | "workspace_admin" | "editor" | "viewer" | "auditor" | "service_agent";
         status?: "active" | "invited" | "revoked" | "expired";
         source?: "bootstrap" | "manual" | "sync" | "sso" | "api" | "scim" | "invitation";
-    }, idempotencyKey?: string): Promise<PlatformGatewaySuccess<unknown>>;
+    }, idempotencyKey?: string) => Promise<PlatformGatewaySuccess<unknown>>;
     /**
      * Update a membership.
      */
-    updateMembership(input: GatewayScope & {
+    updateMembership: (input: GatewayScope & {
         membershipId?: string;
         principalId: string;
         role: "platform_admin" | "tenant_admin" | "workspace_admin" | "editor" | "viewer" | "auditor" | "service_agent";
         status?: "active" | "invited" | "revoked" | "expired";
         source?: "bootstrap" | "manual" | "sync" | "sso" | "api" | "scim" | "invitation";
-    }, idempotencyKey?: string): Promise<PlatformGatewaySuccess<unknown>>;
+    }, idempotencyKey?: string) => Promise<PlatformGatewaySuccess<unknown>>;
     /**
      * @deprecated Use createMembership or updateMembership.
      */
-    upsertMembership(input: GatewayScope & {
+    upsertMembership: (input: GatewayScope & {
         membershipId?: string;
         principalId: string;
         role: "platform_admin" | "tenant_admin" | "workspace_admin" | "editor" | "viewer" | "auditor" | "service_agent";
         status?: "active" | "invited" | "revoked" | "expired";
         source?: "bootstrap" | "manual" | "sync" | "sso" | "api" | "scim" | "invitation";
-    }, idempotencyKey?: string): Promise<PlatformGatewaySuccess<unknown>>;
+    }, idempotencyKey?: string) => Promise<PlatformGatewaySuccess<unknown>>;
     /**
      * List tenant API keys in the current admin scope.
      */