@lucern/mcp 0.3.0-alpha.11 → 0.3.0-alpha.13

package/dist/index.js

@@ -1593,6 +1593,35 @@ defineTable({
     { kind: "index", name: "by_source", columns: ["source"] }
   ]
 });
+defineTable({
+  name: "domainEvents",
+  component: "kernel",
+  category: "events",
+  shape: z.object({
+    "eventId": z.string(),
+    "type": z.string(),
+    "version": z.string(),
+    "timestamp": z.number(),
+    "tenantId": z.string().optional(),
+    "workspaceId": z.string().optional(),
+    "topicId": z.string(),
+    "resourceId": z.string(),
+    "resourceType": z.string(),
+    "actorId": z.string(),
+    "actorType": z.enum(["human", "agent", "service"]),
+    "data": z.record(z.any()),
+    "correlationId": z.string().optional(),
+    "expiresAt": z.number()
+  }),
+  indices: [
+    { kind: "index", name: "by_eventId", columns: ["eventId"] },
+    { kind: "index", name: "by_topic_timestamp", columns: ["topicId", "timestamp"] },
+    { kind: "index", name: "by_tenant_workspace_timestamp", columns: ["tenantId", "workspaceId", "timestamp"] },
+    { kind: "index", name: "by_type_timestamp", columns: ["type", "timestamp"] },
+    { kind: "index", name: "by_resource", columns: ["resourceType", "resourceId", "timestamp"] },
+    { kind: "index", name: "by_expiresAt", columns: ["expiresAt"] }
+  ]
+});
 defineTable({
   name: "beliefConfidence",
   component: "kernel",
@@ -4891,7 +4920,9 @@ var permitObjectType = z.enum([
   "group",
   "resource_instance",
   "relationship_tuple",
-  "role_assignment"
+  "role_assignment",
+  "attribute_binding",
+  "policy_bundle"
 ]);
 var permitOutboxOperation = z.enum([
   "upsert",
@@ -4997,7 +5028,10 @@ defineTable({
   }),
   indices: [
     { kind: "index", name: "by_principalId", columns: ["principalId"] },
+    { kind: "index", name: "by_provider_subject", columns: ["provider", "providerSubjectId"] },
+    { kind: "index", name: "by_provider_project_subject", columns: ["provider", "providerProjectId", "providerSubjectId"] },
     { kind: "index", name: "by_tenant_provider_subject", columns: ["tenantId", "provider", "providerSubjectId"] },
+    { kind: "index", name: "by_tenant_provider_project_subject", columns: ["tenantId", "provider", "providerProjectId", "providerSubjectId"] },
     {
       kind: "index",
       name: "by_tenant_provider_alias",
@@ -8365,6 +8399,40 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
           ],
           "description": "Canonical Lucern API gateway URL. Canonical Lucern API gateway base URL. Older names remain aliases only."
         },
+        {
+          "secretId": "platform.clerk.webhook-secret",
+          "canonicalName": "LUCERN_CLERK_WEBHOOK_SECRET",
+          "envNames": [
+            "CLERK_WEBHOOK_SECRET",
+            "CLERK_WEBHOOK_SIGNING_SECRET",
+            "LUCERN_CLERK_WEBHOOK_SECRET"
+          ],
+          "aliases": [
+            "CLERK_WEBHOOK_SECRET",
+            "CLERK_WEBHOOK_SIGNING_SECRET"
+          ],
+          "writeNames": [
+            "LUCERN_CLERK_WEBHOOK_SECRET"
+          ],
+          "required": true,
+          "secret": true,
+          "public": false,
+          "sourcePath": "/platform/auth",
+          "environmentPolicy": "environment_specific",
+          "consumers": [
+            "lucern-gateway"
+          ],
+          "destinations": [
+            {
+              "kind": "vercel",
+              "target": "lucern-gateway",
+              "writeNames": [
+                "LUCERN_CLERK_WEBHOOK_SECRET"
+              ]
+            }
+          ],
+          "description": "Lucern-owned Clerk/Svix webhook signing secret used by the gateway to verify Clerk identity and organization events before projecting them into Permit."
+        },
         {
           "canonicalName": "LUCERN_CLI_SESSION_TTL_MS",
           "envNames": [
@@ -8688,6 +8756,54 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
           ],
           "description": "Optional Permit PDP URL override."
         },
+        {
+          "secretId": "platform.permit.webhook-secret",
+          "canonicalName": "LUCERN_PERMIT_WEBHOOK_SECRET",
+          "envNames": [
+            "LUCERN_PERMIT_WEBHOOK_SECRET",
+            "PERMIT_WEBHOOK_SECRET"
+          ],
+          "aliases": [
+            "PERMIT_WEBHOOK_SECRET"
+          ],
+          "writeNames": [
+            "LUCERN_PERMIT_WEBHOOK_SECRET"
+          ],
+          "required": true,
+          "secret": true,
+          "public": false,
+          "sourcePath": "/platform/permit",
+          "environmentPolicy": "environment_specific",
+          "consumers": [
+            "mc-convex",
+            "lucern-gateway",
+            "mc-operator-tooling"
+          ],
+          "destinations": [
+            {
+              "kind": "convex",
+              "target": "master-control",
+              "writeNames": [
+                "LUCERN_PERMIT_WEBHOOK_SECRET"
+              ]
+            },
+            {
+              "kind": "vercel",
+              "target": "lucern-gateway",
+              "writeNames": [
+                "LUCERN_PERMIT_WEBHOOK_SECRET"
+              ]
+            },
+            {
+              "kind": "operator_local",
+              "target": "mc-credential-maintenance",
+              "writeNames": [
+                "LUCERN_PERMIT_WEBHOOK_SECRET"
+              ]
+            }
+          ],
+          "description": "Permit.io webhook secret used by gateway and MC webhook handlers. Must fail closed if missing."
+        },
         {
           "secretId": "platform.runtime.require-deployment-host-registry",
           "canonicalName": "LUCERN_REQUIRE_DEPLOYMENT_HOST_REGISTRY",
@@ -12776,7 +12892,7 @@ var IDENTITY_WHOAMI = {
     description: "Canonical identity summary for the current session",
     fields: {
       principalId: "string \u2014 canonical federated principal identifier",
-      principalType: "string \u2014 human, service, or agent",
+      principalType: "string \u2014 human, service, agent, group, or external_viewer",
       tenantId: "string | undefined \u2014 resolved tenant scope",
       workspaceId: "string | undefined \u2014 resolved workspace scope",
       scopes: "string[] | undefined \u2014 granted scopes for this session",
@@ -12787,6 +12903,49 @@ var IDENTITY_WHOAMI = {
   ontologyPrimitive: "identity",
   tier: "workhorse"
 };
+var RESOLVE_INTERACTIVE_PRINCIPAL = {
+  name: "resolve_interactive_principal",
+  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the identity alias into the canonical authorization subject.",
+  parameters: {
+    clerkId: {
+      type: "string",
+      description: "Authenticated Clerk subject (`sub`). Clerk proves identity only; it is not the authorization record."
+    },
+    tenantId: {
+      type: "string",
+      description: "Optional tenant scope. Omit only when the Clerk alias is globally unambiguous."
+    },
+    workspaceId: {
+      type: "string",
+      description: "Optional workspace scope. Required when the principal has access to multiple workspaces and no default can be inferred."
+    },
+    providerProjectId: {
+      type: "string",
+      description: "Optional Clerk project or provider instance id for tenants with multiple identity providers."
+    }
+  },
+  required: ["clerkId"],
+  response: {
+    description: "Permit-backed Lucern principal context for tenant SDK bootstrap",
+    fields: {
+      principalId: "string \u2014 canonical Lucern principal identifier",
+      principalType: "string \u2014 human, service, agent, group, or external_viewer",
+      clerkId: "string \u2014 authenticated Clerk subject alias",
+      tenantId: "string \u2014 resolved tenant scope",
+      workspaceId: "string | null \u2014 resolved workspace scope",
+      roles: "string[] \u2014 effective Permit roles",
+      scopes: "string[] \u2014 effective scopes derived from Permit/control-plane projection",
+      groupIds: "string[] \u2014 active Permit group memberships",
+      principalStatus: "string \u2014 active, invited, suspended, disabled, revoked, or missing",
+      tenantStatus: "string \u2014 projected tenant resource status",
+      workspaceStatus: "string \u2014 projected workspace resource status",
+      permit: "object \u2014 Permit subject, tenant, and optional workspace tuple"
+    }
+  },
+  ownerModule: "control-plane",
+  ontologyPrimitive: "identity",
+  tier: "workhorse"
+};
 var COMPILE_CONTEXT = {
   name: "compile_context",
   description: "Compile a focused reasoning context. If topicId is omitted, Lucern resolves the best topic from the query. Like `git log --graph --decorate` for the reasoning substrate \u2014 returns the canonical Pillar 3 context pack through the public API shape.",
@@ -14689,6 +14848,7 @@ var MCP_TOOL_CONTRACTS = {
   update_worktree_targets: UPDATE_WORKTREE_TARGETS,
   update_worktree_metadata: UPDATE_WORKTREE_METADATA,
   identity_whoami: IDENTITY_WHOAMI,
+  resolve_interactive_principal: RESOLVE_INTERACTIVE_PRINCIPAL,
   compile_context: COMPILE_CONTEXT,
   record_scope_learning: RECORD_SCOPE_LEARNING,
   pipeline_snapshot: PIPELINE_SNAPSHOT,
@@ -14818,6 +14978,7 @@ function entries(names, surfaceClass, surfaceIntent, surfaces, rationale) {
 var MCP_CORE_OPERATION_NAMES = [
   "compile_context",
   "identity_whoami",
+  "resolve_interactive_principal",
   "check_permission",
   "filter_by_permission",
   "create_belief",
@@ -15371,7 +15532,13 @@ function surfaceContract(args) {
       scopes: args.scopes ?? [
         args.kind === "query" ? `${args.domain}.read` : `${args.domain}.write`
       ],
-      allowedPrincipalTypes: ["user", "service", "agent"]
+      allowedPrincipalTypes: [
+        "user",
+        "service",
+        "agent",
+        "group",
+        "external_viewer"
+      ]
     },
     convex: args.convex,
     gateway: args.gateway,
@@ -15513,8 +15680,6 @@ var contextContracts = [
     args: observationContextArgs
   })
 ];
-
-// ../contracts/src/function-registry/identity.ts
 var withPrincipal = (input, context) => ({
   ...input,
   tenantId: input.tenantId ?? context.tenantId,
@@ -15540,6 +15705,28 @@ var identityContracts = [
       inputProjection: withPrincipal
     }
   }),
+  surfaceContract({
+    name: "resolve_interactive_principal",
+    kind: "query",
+    domain: "controlPlane",
+    surfaceClass: "platform_public",
+    method: "POST",
+    path: "/control-plane/identity/resolve-interactive-principal",
+    sdkNamespace: "controlPlane.identity",
+    sdkMethod: "resolveInteractivePrincipal",
+    summary: "Resolve an authenticated Clerk user into a Permit-backed Lucern principal context.",
+    args: z.object({
+      clerkId: z.string().min(1),
+      tenantId: z.string().min(1).optional(),
+      workspaceId: z.string().min(1).optional(),
+      providerProjectId: z.string().min(1).optional()
+    }),
+    convex: {
+      module: "identity",
+      functionName: "resolveInteractivePrincipal",
+      kind: "query"
+    }
+  }),
   surfaceContract({
     name: "check_permission",
     kind: "query",
@@ -19344,6 +19531,13 @@ var TENANT_BOOTSTRAP_TABLE_REQUIREMENTS = [
     copyMode: "none",
     description: "Deliberation sessions are created by tenant workflows."
   },
+  {
+    component: "kernel",
+    table: "domainEvents",
+    prepopulation: "runtime_log",
+    copyMode: "none",
+    description: "Domain event rows are append-only runtime audit/exhaust data."
+  },
   {
     component: "kernel",
     table: "epistemicAudit",
@@ -20476,6 +20670,7 @@ __export(src_exports, {
   LUCERN_SDK_VERSION: () => LUCERN_SDK_VERSION,
   LucernAccessControlError: () => LucernAccessControlError,
   LucernApiError: () => LucernApiError,
+  LucernControlPlaneIdentityError: () => LucernControlPlaneIdentityError,
   LucernSdkAuthContextError: () => LucernSdkAuthContextError,
   MANAGE_WRITE_POLICY: () => MANAGE_WRITE_POLICY,
   MATCH_ENTITY_TYPE: () => MATCH_ENTITY_TYPE,
@@ -20507,6 +20702,7 @@ __export(src_exports, {
   REMOVE_EDGES_BETWEEN: () => REMOVE_EDGES_BETWEEN,
   REMOVE_LENS_FROM_TOPIC: () => REMOVE_LENS_FROM_TOPIC,
   RESOLVE_EFFECTIVE_ONTOLOGY: () => RESOLVE_EFFECTIVE_ONTOLOGY,
+  RESOLVE_INTERACTIVE_PRINCIPAL: () => RESOLVE_INTERACTIVE_PRINCIPAL,
   RUN_GRAPH_INTELLIGENCE_QUERY: () => RUN_GRAPH_INTELLIGENCE_QUERY,
   SEARCH_BELIEFS: () => SEARCH_BELIEFS,
   SEARCH_EVIDENCE: () => SEARCH_EVIDENCE,
@@ -20572,6 +20768,8 @@ __export(src_exports, {
   createCanonicalAuthHeaders: () => createCanonicalAuthHeaders,
   createContextClient: () => createContextClient,
   createContextFacade: () => createContextFacade,
+  createControlPlaneClient: () => createControlPlaneClient,
+  createControlPlaneIdentityClient: () => createControlPlaneIdentityClient,
   createDecisionsClient: () => createDecisionsClient,
   createEmbeddingsClient: () => createEmbeddingsClient,
   createEventId: () => createEventId,
@@ -20645,6 +20843,7 @@ __export(src_exports, {
   normalizeDelegationChain: () => normalizeDelegationChain,
   normalizeNodeVerificationStatus: () => normalizeNodeVerificationStatus,
   normalizeNodeWriteInput: () => normalizeNodeWriteInput,
+  normalizeResolvedInteractivePrincipal: () => normalizeResolvedInteractivePrincipal,
   normalizeRetentionDays: () => normalizeRetentionDays,
   normalizeTopicQuery: () => normalizeTopicQuery,
   normalizeWebhookPatterns: () => normalizeWebhookPatterns,
@@ -20734,14 +20933,14 @@ function requireString(value, reason, label) {
   }
   return normalized;
 }
-function requirePrincipalType(principalType) {
-  if (!principalType) {
+function requirePrincipalType(principalType2) {
+  if (!principalType2) {
     throw new LucernSdkAuthContextError(
       "principal_missing",
       "Canonical Lucern SDK auth context is missing principalType."
     );
   }
-  return principalType;
+  return principalType2;
 }
 function requireAuthMode(authMode) {
   if (!authMode) {
@@ -20787,7 +20986,7 @@ function normalizeCanonicalLucernAuthContext(input) {
   );
   const roles = cleanStringList(input.roles);
   const scopes = cleanStringList(input.scopes);
-  const principalType = requirePrincipalType(input.principalType);
+  const principalType2 = requirePrincipalType(input.principalType);
   const authMode = requireAuthMode(input.authMode);
   const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
   if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
@@ -20816,7 +21015,7 @@ function normalizeCanonicalLucernAuthContext(input) {
     principalId,
     tenantId,
     workspaceId,
-    principalType,
+    principalType: principalType2,
     authMode,
     roles,
     scopes,
@@ -21805,6 +22004,128 @@ function listResultFromEnvelope(data, legacyKey) {
   );
 }
 
+// ../sdk/src/control-plane.ts
+var LucernControlPlaneIdentityError = class extends Error {
+  reason;
+  principalStatus;
+  tenantStatus;
+  workspaceStatus;
+  details;
+  constructor(failure) {
+    super(failure.message);
+    this.name = "LucernControlPlaneIdentityError";
+    this.reason = failure.reason;
+    this.principalStatus = failure.principalStatus;
+    this.tenantStatus = failure.tenantStatus;
+    this.workspaceStatus = failure.workspaceStatus;
+    this.details = failure.details;
+  }
+};
+function cleanString3(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function stringList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [
+    ...new Set(
+      value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean)
+    )
+  ];
+}
+function principalType(value) {
+  switch (value) {
+    case "service":
+    case "service_principal":
+      return "service";
+    case "agent":
+      return "agent";
+    case "group":
+      return "group";
+    case "external_viewer":
+    case "external_stakeholder":
+      return "external_viewer";
+    default:
+      return "human";
+  }
+}
+function adminFlags(roles) {
+  const normalized = roles.map((role) => role.toLowerCase());
+  const isPlatformAdmin = normalized.includes("platform_admin");
+  const isTenantAdmin = isPlatformAdmin || normalized.includes("tenant_admin");
+  const isWorkspaceAdmin = isTenantAdmin || normalized.includes("workspace_admin") || normalized.includes("workspace_owner");
+  return { isPlatformAdmin, isTenantAdmin, isWorkspaceAdmin };
+}
+function normalizeResolvedInteractivePrincipal(payload) {
+  if ("ok" in payload && payload.ok === false) {
+    throw new LucernControlPlaneIdentityError(payload);
+  }
+  const principalId = cleanString3(payload.principalId);
+  const clerkId = cleanString3(payload.clerkId);
+  const tenantId = cleanString3(payload.tenantId);
+  if (!principalId || !clerkId || !tenantId) {
+    throw new LucernControlPlaneIdentityError({
+      ok: false,
+      reason: "resolver_unavailable",
+      message: "Control-plane principal resolver returned an incomplete principal context.",
+      principalStatus: payload.principalStatus ?? "missing",
+      tenantStatus: payload.tenantStatus,
+      workspaceStatus: payload.workspaceStatus
+    });
+  }
+  const roles = stringList(payload.roles);
+  const scopes = stringList(payload.scopes);
+  const workspaceId = cleanString3(payload.workspaceId) ?? null;
+  const flags = adminFlags(roles);
+  return {
+    principalId,
+    principalType: principalType(payload.principalType),
+    clerkId,
+    tenantId,
+    workspaceId,
+    roles,
+    scopes,
+    groupIds: stringList(payload.groupIds),
+    permittedToolNames: stringList(payload.permittedToolNames),
+    permittedPackKeys: stringList(payload.permittedPackKeys),
+    principalStatus: cleanString3(payload.principalStatus) ?? "active",
+    tenantStatus: cleanString3(payload.tenantStatus) ?? "active",
+    workspaceStatus: cleanString3(payload.workspaceStatus) ?? (workspaceId ? "active" : "none"),
+    isPlatformAdmin: typeof payload.isPlatformAdmin === "boolean" ? payload.isPlatformAdmin : flags.isPlatformAdmin,
+    isTenantAdmin: typeof payload.isTenantAdmin === "boolean" ? payload.isTenantAdmin : flags.isTenantAdmin,
+    isWorkspaceAdmin: typeof payload.isWorkspaceAdmin === "boolean" ? payload.isWorkspaceAdmin : flags.isWorkspaceAdmin,
+    permit: {
+      subject: cleanString3(payload.permit?.subject) ?? principalId,
+      tenant: cleanString3(payload.permit?.tenant) ?? tenantId,
+      ...workspaceId ? { workspace: cleanString3(payload.permit?.workspace) ?? workspaceId } : {}
+    },
+    authMode: "interactive_user",
+    sessionId: payload.sessionId,
+    delegatedBy: payload.delegatedBy,
+    expiresAt: payload.expiresAt
+  };
+}
+function createControlPlaneIdentityClient(config = {}) {
+  const gateway = createGatewayRequestClient(config);
+  return {
+    async resolveInteractivePrincipal(input) {
+      return gateway.request({
+        path: "/api/platform/v1/control-plane/identity/resolve-interactive-principal",
+        method: "POST",
+        body: input
+      }).then(
+        (response) => mapGatewayData(response, normalizeResolvedInteractivePrincipal)
+      );
+    }
+  };
+}
+function createControlPlaneClient(config = {}) {
+  return {
+    identity: createControlPlaneIdentityClient(config)
+  };
+}
+
 // ../sdk/src/identityClient.ts
 function createIdentityWhoamiClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
@@ -21872,13 +22193,25 @@ function createIdentityClient(config = {}) {
         (response) => mapGatewayData(response, (data) => ({
           principalId: data.principalId,
           principalType: data.principalType,
+          clerkId: data.clerkId,
           tenantId: data.tenantId ?? null,
           workspaceId: data.workspaceId ?? null,
           scopes: Array.isArray(data.scopes) ? data.scopes : [],
           roles: Array.isArray(data.roles) ? data.roles : [],
+          groupIds: Array.isArray(data.groupIds) ? data.groupIds : [],
+          permittedToolNames: Array.isArray(data.permittedToolNames) ? data.permittedToolNames : [],
+          permittedPackKeys: Array.isArray(data.permittedPackKeys) ? data.permittedPackKeys : [],
+          principalStatus: data.principalStatus,
+          tenantStatus: data.tenantStatus,
+          workspaceStatus: data.workspaceStatus,
           isPlatformAdmin: data.isPlatformAdmin === true,
           isTenantAdmin: data.isTenantAdmin === true,
           isWorkspaceAdmin: data.isWorkspaceAdmin === true,
+          permit: data.permit ?? (data.tenantId ? {
+            subject: data.principalId,
+            tenant: data.tenantId,
+            ...data.workspaceId ? { workspace: data.workspaceId } : {}
+          } : void 0),
           authMode: data.authMode,
           sessionId: data.sessionId,
           delegatedBy: data.delegatedBy,
@@ -21886,6 +22219,19 @@ function createIdentityClient(config = {}) {
         }))
       );
     },
+    /**
+     * Resolve a Clerk subject through the tenant control-plane Permit projection.
+     * @deprecated Prefer lucern.controlPlane.identity.resolveInteractivePrincipal().
+     */
+    async resolveInteractivePrincipal(input) {
+      return gateway.request({
+        path: "/api/platform/v1/control-plane/identity/resolve-interactive-principal",
+        method: "POST",
+        body: input
+      }).then(
+        (response) => mapGatewayData(response, normalizeResolvedInteractivePrincipal)
+      );
+    },
     /**
      * List principals in the current identity scope.
      */
@@ -22082,7 +22428,7 @@ var LucernAccessControlError = class extends LucernSdkAuthContextError {
     this.policyDecision = policyDecision;
   }
 };
-function cleanString3(value) {
+function cleanString4(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
@@ -22097,7 +22443,7 @@ function cleanStringList2(values) {
   ];
 }
 function requireString2(value, reason, label) {
-  const normalized = cleanString3(value);
+  const normalized = cleanString4(value);
   if (!normalized) {
     throw new LucernAccessControlError(
       reason,
@@ -22106,13 +22452,19 @@ function requireString2(value, reason, label) {
   }
   return normalized;
 }
-function normalizePrincipalType(principalType) {
-  if (principalType === "agent") {
+function normalizePrincipalType(principalType2) {
+  if (principalType2 === "agent") {
     return "agent";
   }
-  if (principalType === "service") {
+  if (principalType2 === "service") {
     return "service";
   }
+  if (principalType2 === "group") {
+    return "group";
+  }
+  if (principalType2 === "external_viewer") {
+    return "external_viewer";
+  }
   return "human";
 }
 function aliasKey(alias) {
@@ -22121,15 +22473,15 @@ function aliasKey(alias) {
 function normalizeAliases(input, canonicalClerkUserId) {
   const aliases = /* @__PURE__ */ new Map();
   for (const alias of input ?? []) {
-    const externalSubjectId = cleanString3(alias.externalSubjectId);
+    const externalSubjectId = cleanString4(alias.externalSubjectId);
     if (!externalSubjectId) {
       continue;
     }
     const normalized = {
-      provider: cleanString3(alias.provider) ?? "clerk",
-      providerProjectId: cleanString3(alias.providerProjectId),
+      provider: cleanString4(alias.provider) ?? "clerk",
+      providerProjectId: cleanString4(alias.providerProjectId),
       externalSubjectId,
-      status: cleanString3(alias.status)
+      status: cleanString4(alias.status)
     };
     aliases.set(aliasKey(normalized), normalized);
   }
@@ -22174,10 +22526,10 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
     "principal_missing",
     "principalId"
   );
-  const principalType = normalizePrincipalType(principalInput.principalType);
-  const observedClerkId = cleanString3(options.observedClerkId);
-  const canonicalClerkUserId = cleanString3(principalInput.canonicalClerkUserId) ?? cleanString3(principalInput.clerkId);
-  if (principalType === "human" && !canonicalClerkUserId) {
+  const principalType2 = normalizePrincipalType(principalInput.principalType);
+  const observedClerkId = cleanString4(options.observedClerkId);
+  const canonicalClerkUserId = cleanString4(principalInput.canonicalClerkUserId) ?? cleanString4(principalInput.clerkId);
+  if (principalType2 === "human" && !canonicalClerkUserId) {
     throw new LucernAccessControlError(
       "clerk_alias_missing",
       "Human principals require one canonical Clerk user id."
@@ -22199,11 +22551,11 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
   }
   return {
     principalId,
-    principalType,
+    principalType: principalType2,
     canonicalClerkUserId,
     clerkIdentityAliases: aliases,
-    tenantId: cleanString3(principalInput.tenantId),
-    workspaceId: cleanString3(principalInput.workspaceId),
+    tenantId: cleanString4(principalInput.tenantId),
+    workspaceId: cleanString4(principalInput.workspaceId),
     roles: cleanStringList2(principalInput.roles),
     scopes: cleanStringList2(principalInput.scopes)
   };
@@ -22228,7 +22580,7 @@ function buildPolicyInput(identity, input) {
     "tenant_missing",
     "tenantId"
   );
-  const workspaceId = cleanString3(input.workspaceId ?? identity.workspaceId);
+  const workspaceId = cleanString4(input.workspaceId ?? identity.workspaceId);
   if (resourceRequiresWorkspace(input.resource) && !workspaceId) {
     throw new LucernAccessControlError(
       "workspace_missing",
@@ -23628,12 +23980,12 @@ function createGraphClient(config = {}) {
 }
 
 // ../sdk/src/topicsClient.ts
-function cleanString4(value) {
+function cleanString5(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeTopicRecord(value) {
   const record = asRecord(value);
-  const topicId = cleanString4(record.topicId) ?? cleanString4(record.id) ?? cleanString4(record._id);
+  const topicId = cleanString5(record.topicId) ?? cleanString5(record.id) ?? cleanString5(record._id);
   return withTopicAlias({
     ...record,
     ...topicId ? { topicId } : {}
@@ -24846,7 +25198,7 @@ function createEmbeddingsClient(config = {}) {
 }
 
 // ../sdk/src/contextClient.ts
-function cleanString5(value) {
+function cleanString6(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function cleanNumber(value) {
@@ -24858,11 +25210,11 @@ function cleanBoolean(value) {
 function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   const effectiveInput = typeof topicIdOrInput === "string" ? input : topicIdOrInput;
   const payload = {};
-  const topicId = typeof topicIdOrInput === "string" ? cleanString5(topicIdOrInput) : cleanString5(effectiveInput.topicId);
+  const topicId = typeof topicIdOrInput === "string" ? cleanString6(topicIdOrInput) : cleanString6(effectiveInput.topicId);
   if (topicId) {
     payload.topicId = topicId;
   }
-  const query5 = cleanString5(effectiveInput.query);
+  const query5 = cleanString6(effectiveInput.query);
   if (query5) {
     payload.query = query5;
   }
@@ -24870,7 +25222,7 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (budget !== void 0) {
     payload.budget = budget;
   }
-  const ranking = cleanString5(effectiveInput.ranking) ?? cleanString5(effectiveInput.rankingProfile);
+  const ranking = cleanString6(effectiveInput.ranking) ?? cleanString6(effectiveInput.rankingProfile);
   if (ranking) {
     payload.ranking = ranking;
   }
@@ -24886,7 +25238,7 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (includeEntities !== void 0) {
     payload.includeEntities = includeEntities;
   }
-  const mode = cleanString5(effectiveInput.mode);
+  const mode = cleanString6(effectiveInput.mode);
   if (mode) {
     payload.mode = mode;
   }
@@ -24894,11 +25246,11 @@ function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
   if (includeFailures !== void 0) {
     payload.includeFailures = includeFailures;
   }
-  const worktreeId = cleanString5(effectiveInput.worktreeId);
+  const worktreeId = cleanString6(effectiveInput.worktreeId);
   if (worktreeId) {
     payload.worktreeId = worktreeId;
   }
-  const sessionId = cleanString5(effectiveInput.sessionId);
+  const sessionId = cleanString6(effectiveInput.sessionId);
   if (sessionId) {
     payload.sessionId = sessionId;
   }
@@ -25907,6 +26259,7 @@ var FUNCTION_SURFACE_METHOD_PATHS = [
   "contracts.evaluateContract",
   "contracts.getContractStatus",
   "contradictions.flagContradiction",
+  "controlPlane.identity.resolveInteractivePrincipal",
   "coordination.broadcastMessage",
   "coordination.claimFiles",
   "coordination.endSession",
@@ -26112,6 +26465,7 @@ var CONTRACTS = {
   "remove_edges_between": { method: "DELETE", path: "/edges/between", kind: "mutation", idempotent: true, surfaceIntent: "mcp_analysis" },
   "remove_lens_from_topic": { method: "DELETE", path: "/lenses/apply", kind: "mutation", idempotent: true, surfaceIntent: "mcp_workflow" },
   "resolve_effective_ontology": { method: "POST", path: "/ontologies/effective", kind: "query", idempotent: false, surfaceIntent: "mcp_workflow" },
+  "resolve_interactive_principal": { method: "POST", path: "/control-plane/identity/resolve-interactive-principal", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
   "run_graph_intelligence_query": { method: "POST", path: "/graph-intelligence/run", kind: "query", idempotent: false, surfaceIntent: "mcp_analysis" },
   "search_beliefs": { method: "POST", path: "/beliefs/search", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
   "search_evidence": { method: "POST", path: "/evidence/search", kind: "query", idempotent: false, surfaceIntent: "mcp_core" },
@@ -26494,6 +26848,9 @@ function createFunctionSurfaceClient(config = {}) {
     resolveEffectiveOntology(input = {}, idempotencyKey) {
       return execute("resolve_effective_ontology", input, idempotencyKey);
     },
+    resolveInteractivePrincipal(input = {}, idempotencyKey) {
+      return execute("resolve_interactive_principal", input, idempotencyKey);
+    },
     runGraphIntelligenceQuery(input = {}, idempotencyKey) {
       return execute("run_graph_intelligence_query", input, idempotencyKey);
     },
@@ -26754,7 +27111,7 @@ var ORG_GRAPH_SEARCH_FIELDS = [
   "cursor",
   "provenanceScope"
 ];
-function cleanString6(value, label) {
+function cleanString7(value, label) {
   const normalized = value?.trim();
   if (!normalized) {
     throw new Error(`${label} is required`);
@@ -26776,9 +27133,9 @@ function searchBody(input) {
     "orgGraphSearch.search"
   );
   return {
-    tenantId: cleanString6(input.tenantId, "tenantId"),
-    workspaceId: cleanString6(input.workspaceId, "workspaceId"),
-    query: cleanString6(input.query, "query"),
+    tenantId: cleanString7(input.tenantId, "tenantId"),
+    workspaceId: cleanString7(input.workspaceId, "workspaceId"),
+    query: cleanString7(input.query, "query"),
     nodeTypes: input.nodeTypes,
     minConfidence: input.minConfidence,
     limit: input.limit,
@@ -26788,8 +27145,8 @@ function searchBody(input) {
 }
 function listQuery2(input) {
   return {
-    tenantId: cleanString6(input.tenantId, "tenantId"),
-    workspaceId: cleanString6(input.workspaceId, "workspaceId"),
+    tenantId: cleanString7(input.tenantId, "tenantId"),
+    workspaceId: cleanString7(input.workspaceId, "workspaceId"),
     nodeTypes: input.nodeTypes?.join(","),
     minConfidence: input.minConfidence,
     limit: input.limit,
@@ -26823,8 +27180,8 @@ function createOrgGraphSearchClient(config = {}) {
       return gateway.request({
         path: `/api/platform/v1/org-graph-search/nodes/${nodePath}${toQueryString(
           {
-            tenantId: cleanString6(input.tenantId, "tenantId"),
-            workspaceId: cleanString6(input.workspaceId, "workspaceId"),
+            tenantId: cleanString7(input.tenantId, "tenantId"),
+            workspaceId: cleanString7(input.workspaceId, "workspaceId"),
             globalId: nodeId ? void 0 : globalId
           }
         )}`
@@ -27789,7 +28146,7 @@ function createToolRegistryClient(config = {}) {
 }
 
 // ../sdk/src/version.ts
-var LUCERN_SDK_VERSION = "0.3.0-alpha.11";
+var LUCERN_SDK_VERSION = "0.3.0-alpha.13";
 
 // ../sdk/src/workflowClient.ts
 function normalizeLensQuery(value) {
@@ -28266,6 +28623,7 @@ function createLucernClient(config = {}) {
   const ontologyLinksClient = createOntologyLinksClient(gatewayConfig);
   const orgGraphSearchClient = createOrgGraphSearchClient(gatewayConfig);
   const functionSurfaceClient = createFunctionSurfaceClient(gatewayConfig);
+  const controlPlaneClient = createControlPlaneClient(gatewayConfig);
   const toolRegistryClient = createToolRegistryClient(gatewayConfig);
   const modelRuntimeClient = createModelRuntimeClient(gatewayConfig);
   const packsClient = createPacksClient(gatewayConfig);
@@ -29929,9 +30287,16 @@ function createLucernClient(config = {}) {
       disable: packsClient.disable
     },
     nodes: nodesNamespace,
+    controlPlane: {
+      identity: {
+        resolveInteractivePrincipal: controlPlaneClient.identity.resolveInteractivePrincipal
+      },
+      raw: controlPlaneClient
+    },
     identity: {
       ...identityFacade,
       access: accessControlClient,
+      resolveInteractivePrincipal: identityClient.resolveInteractivePrincipal,
       evaluatePolicy: identityClient.evaluatePolicy,
       recordPolicyDecision: identityClient.recordPolicyDecision,
       putSecretReference: identityClient.putSecretReference,
@@ -29976,6 +30341,7 @@ function createLucernClient(config = {}) {
       ontologyLinks: ontologyLinksClient,
       orgGraphSearch: orgGraphSearchClient,
       functionSurface: functionSurfaceClient,
+      controlPlane: controlPlaneClient,
       toolRegistry: toolRegistryClient,
       modelRuntime: modelRuntimeClient,
       packs: packsClient,
@@ -29993,7 +30359,7 @@ function createLucernClient(config = {}) {
 }
 
 // ../sdk/src/facade/context.ts
-function cleanString7(value) {
+function cleanString8(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function cleanNumber2(value) {
@@ -30005,11 +30371,11 @@ function cleanBoolean2(value) {
 function buildCompileContextRequest2(topicIdOrInput = {}, input = {}) {
   const effectiveInput = typeof topicIdOrInput === "string" ? input : topicIdOrInput;
   const payload = {};
-  const topicId = typeof topicIdOrInput === "string" ? cleanString7(topicIdOrInput) : cleanString7(effectiveInput.topicId);
+  const topicId = typeof topicIdOrInput === "string" ? cleanString8(topicIdOrInput) : cleanString8(effectiveInput.topicId);
   if (topicId) {
     payload.topicId = topicId;
   }
-  const query5 = cleanString7(effectiveInput.query);
+  const query5 = cleanString8(effectiveInput.query);
   if (query5) {
     payload.query = query5;
   }
@@ -30017,7 +30383,7 @@ function buildCompileContextRequest2(topicIdOrInput = {}, input = {}) {
   if (budget !== void 0) {
     payload.budget = budget;
   }
-  const ranking = cleanString7(effectiveInput.ranking) ?? cleanString7(effectiveInput.rankingProfile);
+  const ranking = cleanString8(effectiveInput.ranking) ?? cleanString8(effectiveInput.rankingProfile);
   if (ranking) {
     payload.ranking = ranking;
   }
@@ -30033,7 +30399,7 @@ function buildCompileContextRequest2(topicIdOrInput = {}, input = {}) {
   if (includeEntities !== void 0) {
     payload.includeEntities = includeEntities;
   }
-  const mode = cleanString7(effectiveInput.mode);
+  const mode = cleanString8(effectiveInput.mode);
   if (mode) {
     payload.mode = mode;
   }
@@ -30041,11 +30407,11 @@ function buildCompileContextRequest2(topicIdOrInput = {}, input = {}) {
   if (includeFailures !== void 0) {
     payload.includeFailures = includeFailures;
   }
-  const worktreeId = cleanString7(effectiveInput.worktreeId);
+  const worktreeId = cleanString8(effectiveInput.worktreeId);
   if (worktreeId) {
     payload.worktreeId = worktreeId;
   }
-  const sessionId = cleanString7(effectiveInput.sessionId);
+  const sessionId = cleanString8(effectiveInput.sessionId);
   if (sessionId) {
     payload.sessionId = sessionId;
   }
@@ -31467,7 +31833,13 @@ var SESSION_AUTH_MODES = [
   "tenant_api_key",
   "session_token"
 ];
-var SESSION_PRINCIPAL_TYPES = ["human", "service", "agent"];
+var SESSION_PRINCIPAL_TYPES = [
+  "human",
+  "service",
+  "agent",
+  "group",
+  "external_viewer"
+];
 var SESSION_LIFECYCLE_STATUSES = [
   "active",
   "expired",
@@ -31480,6 +31852,12 @@ function inferSessionPrincipalType(principalId) {
   if (principalId.startsWith("agent:")) {
     return "agent";
   }
+  if (principalId.startsWith("group:")) {
+    return "group";
+  }
+  if (principalId.startsWith("external:") || principalId.startsWith("external_viewer:")) {
+    return "external_viewer";
+  }
   return "service";
 }
 function normalizeDelegationChain(args) {
@@ -34595,7 +34973,7 @@ function createLucernStandaloneMcpServer(options) {
   });
   const server = new McpServer({
     name: "lucern-mcp",
-    version: "0.3.0-alpha.11"
+    version: "0.3.0-alpha.13"
   });
   registerTools(server, runtime);
   const resources = registerResources(server, runtime, observationStore);