@lucern/sdk 0.3.0-alpha.1 → 0.3.0-alpha.11

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/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.
@@ -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/accessControl.d.ts

@@ -0,0 +1,78 @@
+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 './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 };