@lucern/sdk 0.3.0-alpha.17 → 0.3.0-alpha.3

package/CHANGELOG.md

@@ -5,18 +5,6 @@ All notable changes to `@lucern/sdk` will be documented in this file.
 ## [Unreleased]
 - No unreleased changes yet.
 
-## [0.3.0-alpha.17] - 2026-05-19
-- Release notes pending.
-
-
-## [0.3.0-alpha.16] - 2026-05-14
-- Adds the exact-row reasoning-kernel migration surface required for tenant identity/scope repairs.
-- Keeps the coherent Lucern package line aligned for StackOS and reasoning-environment adoption.
-
-
-## [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,31 +10,6 @@ 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/control-plane @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.
@@ -42,9 +17,6 @@ code should stay on `@lucern/sdk`, `@lucern/react`, `@lucern/mcp`,
 - Build applications, automations, and backend integrations against the SDK first.
 - Treat `/api/platform/v1/*` as the transport mirror of the SDK surface.
 - Treat MCP as an agent-facing client of the same surface, not as a privileged bypass around SDK or HTTP semantics.
-- Treat REST, SDK, CLI, and MCP as projections of the same manifest. New
-  control-plane operations must be added to the manifest first, then exposed
-  through the generated surfaces.
 
 IA-7 closes the remaining SDK surface gaps needed for SDK-first clients:
 
@@ -70,62 +42,6 @@ const identity = await lucern.identity.whoami();
 const principal: SdkPrincipalContext = identity.data;
 ```
 
-### Control-Plane Tenant Bootstrap
-
-Interactive tenant applications should resolve Clerk users through the Lucern
-control-plane identity surface before making workspace-scoped graph calls. Clerk
-proves the browser user's identity; Lucern authorization comes from the
-Permit-backed control-plane projection.
-
-```typescript
-import { createLucernClient } from "@lucern/sdk";
-
-async function createLucernForClerkUser(args: {
-  clerkUserId: string;
-  getClerkToken: () => Promise<string | null>;
-  tenantId: string;
-  workspaceId: string;
-  clerkProjectId?: string;
-}) {
-  const token = await args.getClerkToken();
-  if (!token) {
-    throw new Error("Clerk session token is required.");
-  }
-
-  const getAuthHeaders = () => ({ Authorization: `Bearer ${token}` });
-  const lucern = createLucernClient({
-    baseUrl: "https://api.lucern.ai",
-    getAuthHeaders,
-  });
-
-  const principal =
-    await lucern.controlPlane.identity.resolveInteractivePrincipal({
-      clerkId: args.clerkUserId,
-      tenantId: args.tenantId,
-      workspaceId: args.workspaceId,
-      providerProjectId: args.clerkProjectId,
-    });
-
-  return createLucernClient({
-    baseUrl: "https://api.lucern.ai",
-    getAuthHeaders,
-    authContext: principal.data,
-  });
-}
-```
-
-Use `authContext.principalId`, roles, scopes, groups, permitted tools, and
-Permit subject data as the runtime Lucern principal context. Tenant apps must
-not read legacy `users.mcRole` / `defaultTenantId` fields as authorization, and
-they must not call `components.controlPlane.migration` from application code.
-Provisioning and backfills can use migration APIs; runtime bootstrapping uses
-`controlPlane.identity.resolveInteractivePrincipal(...)`.
-
-StackOS, Lucern Graph, and Stack Engineering should use this bootstrap path
-before calling morning brief, graph session, MCP, or CLI-backed runtime flows.
-`/api/platform/v1/users/:clerkId` may be a profile facade, but it is not an
-authorization source.
-
 ## The Full Developer Journey
 
 This walkthrough mirrors what a developer building an AI-powered code review system would experience in a real coding session. Every API call is something you would actually use.
@@ -385,7 +301,7 @@ await lucern.graph.createEdge({
 Before your agent starts its next session, it reads the graph:
 
 ```typescript
-const context = await lucern.context.compile({
+const context = await lucern.context.compile(topicId, {
   query: "code review strategy and static analysis coverage",
   ranking: "weighted_v1",
   tokenBudget: 2000,
@@ -447,28 +363,6 @@ 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
@@ -551,7 +445,7 @@ traversal.data.nodes.forEach(node => {
 ### Inject Reasoning Context Into Any LLM Call
 
 ```typescript
-const context = await lucern.context.compile({
+const context = await lucern.context.compile(topicId, {
   query: "security review priorities",
   ranking: "weighted_v1",
   tokenBudget: 3000,
@@ -662,7 +556,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({ query: "..." })`
+- Compile context before analysis: `lucern.context.compile(topicId, { query: "..." })`
 
 After making decisions, write them back:
 - Create beliefs for architectural decisions
@@ -693,7 +587,7 @@ contradictions, or knowledge state.
 Compile the current context to understand what the graph knows:
 
 \`\`\`typescript
-const context = await lucern.context.compile({
+const context = await lucern.context.compile(topicId, {
   query: "<what you're working on>",
   tokenBudget: 2000,
 });

package/dist/adminClient.d.ts

@@ -153,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.
      */
@@ -190,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

@@ -82,15 +82,14 @@ function normalizeCanonicalLucernAuthContext(input) {
   );
   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) {
+  if (roles.length === 0 || scopes.length === 0) {
     throw new LucernSdkAuthContextError(
       "membership_missing",
       "Canonical Lucern SDK auth context requires non-empty roles and scopes."
     );
   }
+  const principalType = requirePrincipalType(input.principalType);
+  const authMode = requireAuthMode(input.authMode);
   const subject = cleanString(input.permit?.subject) ?? principalId;
   const tenant = cleanString(input.permit?.tenant) ?? tenantId;
   const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
@@ -232,7 +231,9 @@ function generatePortableRequestId() {
     8
   ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
-var randomIdempotencyKey = generatePortableRequestId;
+function randomIdempotencyKey() {
+  return generatePortableRequestId();
+}
 function isRetryableStatus(status) {
   return status >= 500 || status === 408 || status === 429;
 }
@@ -297,11 +298,8 @@ function timeoutError(timeoutMs) {
   error.name = "AbortError";
   return error;
 }
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function readPolicySummaryFromDetails(details) {
-  if (!isRecord(details)) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
     return null;
   }
   const directSummary = details.summary;
@@ -309,11 +307,11 @@ function readPolicySummaryFromDetails(details) {
     return directSummary.trim();
   }
   const policy = details.policy;
-  if (!isRecord(policy)) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
     return null;
   }
   const explanation = policy.explanation;
-  if (!isRecord(explanation)) {
+  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
     return null;
   }
   const nestedSummary = explanation.summary;
@@ -342,31 +340,13 @@ function mergeHeaderRecord(base, addition) {
   }
   return Object.fromEntries(headers.entries());
 }
-function cleanHeaderValue(value) {
-  const normalized = value?.trim();
-  return normalized ? normalized : void 0;
-}
 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() {
-    const provided = config.getAuthHeaders ? await config.getAuthHeaders() : {};
-    const headers = new Headers(provided);
-    const setIfAbsent = (name, value) => {
-      const normalized = cleanHeaderValue(value);
-      if (normalized && !headers.has(name)) {
-        headers.set(name, normalized);
-      }
-    };
-    setIfAbsent("x-lucern-key", config.apiKey);
-    setIfAbsent("x-lucern-session-token", config.userToken);
-    setIfAbsent("x-lucern-environment", config.environment);
-    setIfAbsent("x-lucern-clerk-id", config.clerkId);
-    setIfAbsent("x-lucern-user-id", config.userId ?? config.clerkId);
-    setIfAbsent("x-lucern-deployment-host", config.deploymentHost);
-    const base = Object.fromEntries(headers.entries());
+    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
     const authContextInput = await resolveConfiguredAuthContext(
       config.authContext
     );
@@ -395,11 +375,11 @@ function createGatewayRequestClient(config = {}) {
     if (!text) {
       return null;
     }
-    const parsed = tryParseGatewayEnvelopeJson(text);
-    if (!parsed.ok) {
+    try {
+      return JSON.parse(text);
+    } catch {
       return null;
     }
-    return isRecord(parsed.value) ? parsed.value : null;
   }
   function resolveTimeoutMs(method, requestTimeoutMs) {
     if (typeof requestTimeoutMs === "number") {
@@ -411,31 +391,16 @@ 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 && isRecord(failure.error) ? failure.error : failure?.legacyError;
+    const legacyError = failure && typeof failure.error === "object" && failure.error !== null ? 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 ?? failureMessage ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed."),
+      message: policySummary ?? (typeof failure?.error === "string" ? failure.error : legacyError?.message ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed.")),
       status: args.response.status,
       invariant: failure?.invariant,
       suggestion: failure?.suggestion,
@@ -567,10 +532,7 @@ function createListResult(items, legacyKey) {
     total: items.length
   };
   if (legacyKey) {
-    return {
-      ...result,
-      [legacyKey]: items
-    };
+    result[legacyKey] = items;
   }
   return result;
 }
@@ -608,17 +570,6 @@ 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.
@@ -650,11 +601,19 @@ function createAdminClient(config = {}) {
     /**
      * Get the control-object ownership contract.
      */
-    getControlObjectOwnership,
+    async getControlObjectOwnership() {
+      return gateway.request({
+        path: "/api/platform/v1/admin/control-ownership"
+      });
+    },
     /**
      * @deprecated Use getControlObjectOwnership.
      */
-    getControlObjectOwnershipContract: getControlObjectOwnership,
+    async getControlObjectOwnershipContract() {
+      return gateway.request({
+        path: "/api/platform/v1/admin/control-ownership"
+      });
+    },
     /**
      * List workspaces for the current admin scope.
      */
@@ -701,15 +660,26 @@ function createAdminClient(config = {}) {
     /**
      * Create a membership.
      */
-    createMembership,
+    async createMembership(input, idempotencyKey) {
+      return gateway.request({
+        path: "/api/platform/v1/memberships",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
     /**
      * Update a membership.
      */
-    updateMembership,
+    async updateMembership(input, idempotencyKey) {
+      return this.createMembership(input, idempotencyKey);
+    },
     /**
      * @deprecated Use createMembership or updateMembership.
      */
-    upsertMembership,
+    async upsertMembership(input, idempotencyKey) {
+      return this.createMembership(input, idempotencyKey);
+    },
     /**
      * List tenant API keys in the current admin scope.
      */