@lucern/sdk 0.3.0-alpha.1 → 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.
@@ -301,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,
@@ -363,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
@@ -445,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,
@@ -556,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
@@ -587,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,
 });

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.
      */

package/dist/adminClient.js

@@ -1,3 +1,170 @@
+// src/authContext.ts
+var LucernSdkAuthContextError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "LucernSdkAuthContextError";
+    this.reason = reason;
+  }
+};
+function cleanString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function cleanStringList(values) {
+  if (!values) {
+    return [];
+  }
+  return values.map((value) => value.trim()).filter(
+    (value, index, list) => value.length > 0 && list.indexOf(value) === index
+  );
+}
+function requireString(value, reason, label) {
+  const normalized = cleanString(value);
+  if (!normalized) {
+    throw new LucernSdkAuthContextError(
+      reason,
+      `Canonical Lucern SDK auth context is missing ${label}.`
+    );
+  }
+  return normalized;
+}
+function requirePrincipalType(principalType) {
+  if (!principalType) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing principalType."
+    );
+  }
+  return principalType;
+}
+function requireAuthMode(authMode) {
+  if (!authMode) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing authMode."
+    );
+  }
+  return authMode;
+}
+function ensurePermitMatch(args) {
+  const actual = cleanString(args.actual);
+  if (actual && actual !== args.expected) {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      `Canonical Lucern SDK auth context has conflicting Permit ${args.field}.`
+    );
+  }
+}
+function normalizeCanonicalLucernAuthContext(input) {
+  if (!input) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is required."
+    );
+  }
+  if (input.policyDecision === "deny") {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      "Canonical Lucern SDK auth context carries a denied policy decision."
+    );
+  }
+  const principalId = requireString(
+    input.principalId,
+    "principal_missing",
+    "principalId"
+  );
+  const tenantId = requireString(input.tenantId, "tenant_missing", "tenantId");
+  const workspaceId = requireString(
+    input.workspaceId,
+    "workspace_missing",
+    "workspaceId"
+  );
+  const roles = cleanStringList(input.roles);
+  const scopes = cleanStringList(input.scopes);
+  const principalType = requirePrincipalType(input.principalType);
+  const authMode = requireAuthMode(input.authMode);
+  const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
+  if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
+    throw new LucernSdkAuthContextError(
+      "membership_missing",
+      "Canonical Lucern SDK auth context requires non-empty roles and scopes."
+    );
+  }
+  const subject = cleanString(input.permit?.subject) ?? principalId;
+  const tenant = cleanString(input.permit?.tenant) ?? tenantId;
+  const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
+  ensurePermitMatch({
+    field: "subject",
+    expected: principalId,
+    actual: subject
+  });
+  ensurePermitMatch({ field: "tenant", expected: tenantId, actual: tenant });
+  ensurePermitMatch({
+    field: "workspace",
+    expected: workspaceId,
+    actual: workspace
+  });
+  const context = input.permit?.context ? { ...input.permit.context } : void 0;
+  return {
+    clerkId: cleanString(input.clerkId),
+    principalId,
+    tenantId,
+    workspaceId,
+    principalType,
+    authMode,
+    roles,
+    scopes,
+    delegationChain: input.delegationChain ? [...input.delegationChain] : [],
+    policyTraceId: cleanString(input.policyTraceId),
+    correlationId: cleanString(input.correlationId),
+    membershipId: cleanString(input.membershipId),
+    permit: {
+      subject,
+      tenant,
+      workspace,
+      resource: cleanString(input.permit?.resource),
+      action: cleanString(input.permit?.action),
+      relation: cleanString(input.permit?.relation),
+      context
+    }
+  };
+}
+function createCanonicalAuthHeaders(authContext) {
+  const headers = {
+    "x-lucern-principal-id": authContext.principalId,
+    "x-lucern-principal-type": authContext.principalType,
+    "x-lucern-tenant": authContext.tenantId,
+    "x-lucern-tenant-id": authContext.tenantId,
+    "x-lucern-workspace": authContext.workspaceId,
+    "x-lucern-workspace-id": authContext.workspaceId,
+    "x-lucern-auth-mode": authContext.authMode,
+    "x-lucern-roles": authContext.roles.join(","),
+    "x-lucern-scopes": authContext.scopes.join(","),
+    "x-lucern-permit-context": JSON.stringify(authContext.permit)
+  };
+  if (authContext.clerkId) {
+    headers["x-lucern-clerk-id"] = authContext.clerkId;
+    headers["x-lucern-user-id"] = authContext.clerkId;
+  }
+  if (authContext.delegationChain.length > 0) {
+    headers["x-lucern-delegation-chain"] = JSON.stringify(
+      authContext.delegationChain
+    );
+  }
+  if (authContext.policyTraceId) {
+    headers["x-lucern-policy-trace-id"] = authContext.policyTraceId;
+  }
+  if (authContext.correlationId) {
+    headers["x-correlation-id"] = authContext.correlationId;
+    headers["x-lucern-correlation-id"] = authContext.correlationId;
+  }
+  if (authContext.membershipId) {
+    headers["x-lucern-membership-id"] = authContext.membershipId;
+  }
+  return headers;
+}
+
 // src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -65,9 +232,7 @@ function generatePortableRequestId() {
     8
   ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
-function randomIdempotencyKey() {
-  return generatePortableRequestId();
-}
+var randomIdempotencyKey = generatePortableRequestId;
 function isRetryableStatus(status) {
   return status >= 500 || status === 408 || status === 429;
 }
@@ -132,8 +297,11 @@ function timeoutError(timeoutMs) {
   error.name = "AbortError";
   return error;
 }
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function readPolicySummaryFromDetails(details) {
-  if (!details || typeof details !== "object" || Array.isArray(details)) {
+  if (!isRecord(details)) {
     return null;
   }
   const directSummary = details.summary;
@@ -141,11 +309,11 @@ function readPolicySummaryFromDetails(details) {
     return directSummary.trim();
   }
   const policy = details.policy;
-  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+  if (!isRecord(policy)) {
     return null;
   }
   const explanation = policy.explanation;
-  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
+  if (!isRecord(explanation)) {
     return null;
   }
   const nestedSummary = explanation.summary;
@@ -154,16 +322,41 @@ function readPolicySummaryFromDetails(details) {
   }
   return null;
 }
+async function resolveConfiguredAuthContext(authContext) {
+  if (typeof authContext === "function") {
+    return await authContext();
+  }
+  return authContext;
+}
+function mergeHeaderRecord(base, addition) {
+  const headers = new Headers(base);
+  for (const [key, value] of Object.entries(addition)) {
+    const existing = headers.get(key);
+    if (existing !== null && existing !== value) {
+      throw new LucernSdkAuthContextError(
+        "policy_denied",
+        `Canonical Lucern SDK auth context conflicts with existing ${key} header.`
+      );
+    }
+    headers.set(key, value);
+  }
+  return Object.fromEntries(headers.entries());
+}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    if (!config.getAuthHeaders) {
-      return {};
+    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const authContextInput = await resolveConfiguredAuthContext(
+      config.authContext
+    );
+    if (!authContextInput && !config.requireCanonicalAuthContext) {
+      return base;
     }
-    return await config.getAuthHeaders();
+    const authContext = normalizeCanonicalLucernAuthContext(authContextInput);
+    return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -184,11 +377,11 @@ function createGatewayRequestClient(config = {}) {
     if (!text) {
       return null;
     }
-    try {
-      return JSON.parse(text);
-    } catch {
+    const parsed = tryParseGatewayEnvelopeJson(text);
+    if (!parsed.ok) {
       return null;
     }
+    return isRecord(parsed.value) ? parsed.value : null;
   }
   function resolveTimeoutMs(method, requestTimeoutMs) {
     if (typeof requestTimeoutMs === "number") {
@@ -200,16 +393,31 @@ function createGatewayRequestClient(config = {}) {
     }
     return config.timeoutMs ?? 15e3;
   }
+  function tryParseGatewayEnvelopeJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+      return { ok: false, reason: "non-json" };
+    }
+    try {
+      return { ok: true, value: JSON.parse(trimmed) };
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return { ok: false, reason: "invalid-json", error };
+      }
+      throw error;
+    }
+  }
   function buildApiError(args) {
     const failure = args.failure;
-    const legacyError = failure && typeof failure.error === "object" && failure.error !== null ? failure.error : failure?.legacyError;
+    const legacyError = failure && isRecord(failure.error) ? failure.error : failure?.legacyError;
     const correlationId = failure?.correlationId ?? args.response.headers.get("x-lucern-correlation-id")?.trim() ?? args.requestId;
     const policyTraceId = failure?.policyTraceId ?? args.response.headers.get("x-lucern-policy-trace-id")?.trim() ?? null;
     const details = failure?.details ?? legacyError?.details;
     const policySummary = readPolicySummaryFromDetails(details);
+    const failureMessage = typeof failure?.error === "string" ? failure.error : legacyError?.message;
     return new LucernApiError({
       code: failure?.code ?? legacyError?.code ?? fallbackErrorCode(args.response.status),
-      message: policySummary ?? (typeof failure?.error === "string" ? failure.error : legacyError?.message ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed.")),
+      message: policySummary ?? failureMessage ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed."),
       status: args.response.status,
       invariant: failure?.invariant,
       suggestion: failure?.suggestion,
@@ -341,7 +549,10 @@ function createListResult(items, legacyKey) {
     total: items.length
   };
   if (legacyKey) {
-    result[legacyKey] = items;
+    return {
+      ...result,
+      [legacyKey]: items
+    };
   }
   return result;
 }
@@ -379,6 +590,17 @@ function asTenantVaultSecretArray(data) {
 }
 function createAdminClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
+  const getControlObjectOwnership = async () => gateway.request({
+    path: "/api/platform/v1/admin/control-ownership"
+  });
+  const createMembership = async (input, idempotencyKey) => gateway.request({
+    path: "/api/platform/v1/memberships",
+    method: "POST",
+    body: input,
+    idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+  });
+  const updateMembership = createMembership;
+  const upsertMembership = createMembership;
   return {
     /**
      * List tenants visible to the current principal.
@@ -410,19 +632,11 @@ function createAdminClient(config = {}) {
     /**
      * Get the control-object ownership contract.
      */
-    async getControlObjectOwnership() {
-      return gateway.request({
-        path: "/api/platform/v1/admin/control-ownership"
-      });
-    },
+    getControlObjectOwnership,
     /**
      * @deprecated Use getControlObjectOwnership.
      */
-    async getControlObjectOwnershipContract() {
-      return gateway.request({
-        path: "/api/platform/v1/admin/control-ownership"
-      });
-    },
+    getControlObjectOwnershipContract: getControlObjectOwnership,
     /**
      * List workspaces for the current admin scope.
      */
@@ -469,26 +683,15 @@ function createAdminClient(config = {}) {
     /**
      * Create a membership.
      */
-    async createMembership(input, idempotencyKey) {
-      return gateway.request({
-        path: "/api/platform/v1/memberships",
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
-      });
-    },
+    createMembership,
     /**
      * Update a membership.
      */
-    async updateMembership(input, idempotencyKey) {
-      return this.createMembership(input, idempotencyKey);
-    },
+    updateMembership,
     /**
      * @deprecated Use createMembership or updateMembership.
      */
-    async upsertMembership(input, idempotencyKey) {
-      return this.createMembership(input, idempotencyKey);
-    },
+    upsertMembership,
     /**
      * List tenant API keys in the current admin scope.
      */