@lucern/sdk 0.3.0-alpha.8 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to `@lucern/sdk` will be documented in this file.
 ## [Unreleased]
 - No unreleased changes yet.
 
+## [1.0.0] - 2026-05-23
+- Promote the Campaign 1 package line to the stable 1.0.0 release.
+
+## [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.
 

package/README.md

@@ -24,7 +24,7 @@ Common direct installs:
 | 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` |
+| 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` |
@@ -42,6 +42,9 @@ 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:
 
@@ -67,6 +70,62 @@ 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.

package/dist/accessControl.d.ts

@@ -0,0 +1,79 @@
+import { LucernSdkAuthContextError, LucernSdkAuthFailureReason, LucernSdkAuthContextInput } from './authContext.js';
+import { GatewayClientConfig } from './coreClient.js';
+import { PolicyEvaluationInput, PolicyDecisionRecord } from './identityClient.js';
+import { SessionPrincipalType } from './contracts/auth-session.contract.js';
+import { JsonObject } from './types.js';
+import './control-plane.js';
+import './contracts/workflow-runtime.contract.js';
+import './contracts/lens-workflow.contract.js';
+import './contracts/lens-filter.contract.js';
+
+type ClerkIdentityAliasInput = {
+    provider?: "clerk" | string;
+    providerProjectId?: string | null;
+    externalSubjectId: string;
+    status?: "active" | "pending" | "revoked" | string;
+};
+type CanonicalPrincipalIdentityInput = {
+    principalId?: string | null;
+    principalType?: SessionPrincipalType | "user" | "external_viewer" | null;
+    canonicalClerkUserId?: string | null;
+    clerkId?: string | null;
+    clerkIdentityAliases?: readonly ClerkIdentityAliasInput[];
+    tenantId?: string | null;
+    workspaceId?: string | null;
+    roles?: readonly string[];
+    scopes?: readonly string[];
+};
+type CanonicalPrincipalIdentityAlias = {
+    provider: string;
+    providerProjectId?: string;
+    externalSubjectId: string;
+    status?: string;
+};
+type CanonicalPrincipalIdentity = {
+    principalId: string;
+    principalType: SessionPrincipalType;
+    canonicalClerkUserId?: string;
+    clerkIdentityAliases: CanonicalPrincipalIdentityAlias[];
+    tenantId?: string;
+    workspaceId?: string;
+    roles: string[];
+    scopes: string[];
+};
+type AccessResourceType = "tenant" | "workspace" | "deployment" | "convex_table" | "secret_scope" | "agent_session" | (string & {});
+type AccessResourceDescriptor = {
+    type: AccessResourceType;
+    key: string;
+};
+type RequireAccessInput = {
+    identity?: CanonicalPrincipalIdentityInput | LucernSdkAuthContextInput;
+    observedClerkId?: string;
+    tenantId?: string;
+    workspaceId?: string;
+    action: string;
+    resource: AccessResourceDescriptor | string;
+    context?: JsonObject;
+};
+type AccessCheckResult = {
+    identity: CanonicalPrincipalIdentity;
+    policyInput: PolicyEvaluationInput;
+    decision: PolicyDecisionRecord;
+};
+declare class LucernAccessControlError extends LucernSdkAuthContextError {
+    readonly policyDecision?: PolicyDecisionRecord;
+    constructor(reason: LucernSdkAuthFailureReason, message: string, policyDecision?: PolicyDecisionRecord);
+}
+declare function normalizeCanonicalPrincipalIdentity(input: CanonicalPrincipalIdentityInput | LucernSdkAuthContextInput, options?: {
+    observedClerkId?: string;
+}): CanonicalPrincipalIdentity;
+declare function formatPermitResource(resource: AccessResourceDescriptor | string): string;
+declare function assertPermitAllowed(decision: PolicyDecisionRecord): void;
+declare function createAccessControlClient(config?: GatewayClientConfig): {
+    normalizePrincipal: typeof normalizeCanonicalPrincipalIdentity;
+    checkAccess: (input: RequireAccessInput, idempotencyKey?: string) => Promise<AccessCheckResult>;
+    requireAccess: (input: RequireAccessInput, idempotencyKey?: string) => Promise<AccessCheckResult>;
+    canAccess: (input: RequireAccessInput, idempotencyKey?: string) => Promise<boolean>;
+};
+
+export { type AccessCheckResult, type AccessResourceDescriptor, type AccessResourceType, type CanonicalPrincipalIdentity, type CanonicalPrincipalIdentityAlias, type CanonicalPrincipalIdentityInput, type ClerkIdentityAliasInput, LucernAccessControlError, type RequireAccessInput, assertPermitAllowed, createAccessControlClient, formatPermitResource, normalizeCanonicalPrincipalIdentity };