@lucern/contracts 0.3.0-alpha.12 → 0.3.0-alpha.13

package/dist/function-registry/identity.d.ts

@@ -1,4 +1,4 @@
-import * as zod from 'zod';
+import { z } from 'zod';
 
 /**
  * MCP Tool Contract Definitions
@@ -115,14 +115,14 @@ declare const identityContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -155,14 +155,14 @@ declare const identityContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -195,14 +195,54 @@ declare const identityContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent")[];
+        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    gateway: FunctionGatewayTarget | undefined;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];

package/dist/function-registry/identity.js

@@ -2328,7 +2328,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",
@@ -2339,6 +2339,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.",
@@ -4241,6 +4284,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,
@@ -4358,6 +4402,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",
@@ -4895,7 +4940,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,
@@ -4909,8 +4960,6 @@ function surfaceContract(args) {
     }
   });
 }
-
-// src/function-registry/identity.ts
 var withPrincipal = (input, context) => ({
   ...input,
   tenantId: input.tenantId ?? context.tenantId,
@@ -4936,6 +4985,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",