@lucern/contracts 0.3.0-alpha.3 → 0.3.0-alpha.4

package/dist/function-registry-input-audit.d.ts

@@ -0,0 +1,13 @@
+import { FunctionContract } from './function-registry/types.js';
+
+type FunctionRegistryInputAuditFinding = {
+    contractName: string;
+    projectionKeys: string[];
+    acceptedKeys: string[];
+    missingKeys: string[];
+};
+type InputProjection = NonNullable<FunctionContract["convex"]>["inputProjection"];
+declare function projectionReadKeys(projection: InputProjection): string[];
+declare function auditFunctionRegistryInputs(contracts?: readonly FunctionContract[]): FunctionRegistryInputAuditFinding[];
+
+export { type FunctionRegistryInputAuditFinding, auditFunctionRegistryInputs, projectionReadKeys };

package/dist/function-registry-input-audit.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { ALL_FUNCTION_CONTRACTS } from './function-registry/index.js';
+
+// src/function-registry-input-audit.ts
+var INTERNAL_OR_ALIAS_KEYS = /* @__PURE__ */ new Set([
+  "__sdkSessionId",
+  "actorId",
+  "beliefId",
+  "createdBy",
+  "evidenceId",
+  "id",
+  "insightId",
+  "nodeId",
+  "ontologyId",
+  "parentNodeId",
+  "principalId",
+  "projectId",
+  "questionId",
+  "tenantId",
+  "trustedBypassAccessCheck",
+  "userId",
+  "versionId",
+  "workspaceId"
+]);
+var INTENTIONAL_PROJECTION_READS = {
+  add_evidence: ["linkedBeliefNodeId", "targetId"],
+  apply_lens_to_topic: ["metadata"],
+  archive_belief: ["reason"],
+  check_permission: ["principalId", "tenantId", "userId", "workspaceId"],
+  claim_files: ["paths", "touchedFiles"],
+  complete_task: ["summary"],
+  create_belief: ["formulation"],
+  discover: ["prompt", "topicHint"],
+  filter_by_permission: ["principalId", "tenantId", "userId", "workspaceId"],
+  get_change_history: ["status"],
+  get_failure_log: ["status"],
+  identity_whoami: ["principalId", "tenantId", "userId", "workspaceId"],
+  ingest_observation: ["reasoning", "trustedBypassAccessCheck"],
+  link_evidence: [
+    "beliefId",
+    "beliefNodeId",
+    "context",
+    "evidenceNodeId",
+    "globalId",
+    "insightId",
+    "topicId",
+    "trustedBypassAccessCheck",
+    "type"
+  ],
+  link_evidence_to_belief: [
+    "beliefNodeId",
+    "context",
+    "evidenceNodeId",
+    "globalId",
+    "insightId",
+    "targetId",
+    "topicId",
+    "trustedBypassAccessCheck",
+    "type"
+  ],
+  link_evidence_to_question: [
+    "context",
+    "evidenceNodeId",
+    "globalId",
+    "impactScore",
+    "insightId",
+    "questionNodeId",
+    "targetId",
+    "topicId",
+    "trustedBypassAccessCheck",
+    "weight"
+  ],
+  list_evidence: ["status"],
+  manage_write_policy: ["summary"],
+  merge: ["decisionsReached", "keyFindings", "nextSteps"],
+  record_attempt: ["reasoning", "trustedBypassAccessCheck"],
+  record_judgment: ["reasoning", "trustedBypassAccessCheck"],
+  record_scope_learning: ["reasoning", "trustedBypassAccessCheck"],
+  search_beliefs: ["searchQuery"],
+  search_evidence: ["query", "searchQuery"],
+  update_question_status: ["answer", "answerStatus", "nodeId", "questionId"],
+  update_topic: ["graphScopeProjectId"]
+};
+function unwrapObjectSchema(schema) {
+  let current = schema;
+  while (true) {
+    switch (current._def.typeName) {
+      case z.ZodFirstPartyTypeKind.ZodEffects:
+        current = current._def.schema;
+        continue;
+      case z.ZodFirstPartyTypeKind.ZodBranded:
+        current = current._def.type;
+        continue;
+      default:
+        return current instanceof z.ZodObject ? current : void 0;
+    }
+  }
+}
+function objectSchemaKeys(schema) {
+  const objectSchema = unwrapObjectSchema(schema);
+  if (!objectSchema) {
+    return /* @__PURE__ */ new Set();
+  }
+  const shape = typeof objectSchema._def.shape === "function" ? objectSchema._def.shape() : objectSchema._def.shape;
+  return new Set(Object.keys(shape));
+}
+function projectionReadKeys(projection) {
+  if (!projection) {
+    return [];
+  }
+  const source = String(projection);
+  const keys = /* @__PURE__ */ new Set();
+  for (const match of source.matchAll(/\binput\s*\.\s*([A-Za-z_$][\w$]*)/gu)) {
+    keys.add(match[1]);
+  }
+  for (const match of source.matchAll(/\binput\s*\[\s*["']([^"']+)["']\s*\]/gu)) {
+    keys.add(match[1]);
+  }
+  return [...keys].sort();
+}
+function acceptedInputKeys(contract) {
+  return [
+    .../* @__PURE__ */ new Set([
+      ...objectSchemaKeys(contract.args),
+      ...objectSchemaKeys(contract.input),
+      ...Object.keys(contract.mcp.parameters),
+      "__sdkSessionId"
+    ])
+  ].sort();
+}
+function allowedProjectionKeys(contractName) {
+  return /* @__PURE__ */ new Set([
+    ...INTERNAL_OR_ALIAS_KEYS,
+    ...INTENTIONAL_PROJECTION_READS[contractName] ?? []
+  ]);
+}
+function auditFunctionRegistryInputs(contracts = ALL_FUNCTION_CONTRACTS) {
+  return contracts.flatMap((contract) => {
+    const projectionKeys = projectionReadKeys(contract.convex?.inputProjection);
+    if (projectionKeys.length === 0) {
+      return [];
+    }
+    const accepted = new Set(acceptedInputKeys(contract));
+    const allowed = allowedProjectionKeys(contract.name);
+    const missingKeys = projectionKeys.filter(
+      (key) => !accepted.has(key) && !allowed.has(key)
+    );
+    if (missingKeys.length === 0) {
+      return [];
+    }
+    return [
+      {
+        contractName: contract.name,
+        projectionKeys,
+        acceptedKeys: [...accepted].sort(),
+        missingKeys
+      }
+    ];
+  });
+}
+
+export { auditFunctionRegistryInputs, projectionReadKeys };
+//# sourceMappingURL=function-registry-input-audit.js.map
+//# sourceMappingURL=function-registry-input-audit.js.map

package/dist/function-registry-input-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/function-registry-input-audit.ts"],"names":[],"mappings":"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","file":"function-registry-input-audit.js","sourcesContent":["import { z } from \"zod\";\nimport { ALL_FUNCTION_CONTRACTS } from \"./function-registry/index.js\";\nimport type { FunctionContract } from \"./function-registry/types.js\";\n\nexport type FunctionRegistryInputAuditFinding = {\n  contractName: string;\n  projectionKeys: string[];\n  acceptedKeys: string[];\n  missingKeys: string[];\n};\n\ntype InputProjection = NonNullable<\n  FunctionContract[\"convex\"]\n>[\"inputProjection\"];\n\nconst INTERNAL_OR_ALIAS_KEYS = new Set([\n  \"__sdkSessionId\",\n  \"actorId\",\n  \"beliefId\",\n  \"createdBy\",\n  \"evidenceId\",\n  \"id\",\n  \"insightId\",\n  \"nodeId\",\n  \"ontologyId\",\n  \"parentNodeId\",\n  \"principalId\",\n  \"projectId\",\n  \"questionId\",\n  \"tenantId\",\n  \"trustedBypassAccessCheck\",\n  \"userId\",\n  \"versionId\",\n  \"workspaceId\",\n]);\n\nconst INTENTIONAL_PROJECTION_READS: Record<string, readonly string[]> = {\n  add_evidence: [\"linkedBeliefNodeId\", \"targetId\"],\n  apply_lens_to_topic: [\"metadata\"],\n  archive_belief: [\"reason\"],\n  check_permission: [\"principalId\", \"tenantId\", \"userId\", \"workspaceId\"],\n  claim_files: [\"paths\", \"touchedFiles\"],\n  complete_task: [\"summary\"],\n  create_belief: [\"formulation\"],\n  discover: [\"prompt\", \"topicHint\"],\n  filter_by_permission: [\"principalId\", \"tenantId\", \"userId\", \"workspaceId\"],\n  get_change_history: [\"status\"],\n  get_failure_log: [\"status\"],\n  identity_whoami: [\"principalId\", \"tenantId\", \"userId\", \"workspaceId\"],\n  ingest_observation: [\"reasoning\", \"trustedBypassAccessCheck\"],\n  link_evidence: [\n    \"beliefId\",\n    \"beliefNodeId\",\n    \"context\",\n    \"evidenceNodeId\",\n    \"globalId\",\n    \"insightId\",\n    \"topicId\",\n    \"trustedBypassAccessCheck\",\n    \"type\",\n  ],\n  link_evidence_to_belief: [\n    \"beliefNodeId\",\n    \"context\",\n    \"evidenceNodeId\",\n    \"globalId\",\n    \"insightId\",\n    \"targetId\",\n    \"topicId\",\n    \"trustedBypassAccessCheck\",\n    \"type\",\n  ],\n  link_evidence_to_question: [\n    \"context\",\n    \"evidenceNodeId\",\n    \"globalId\",\n    \"impactScore\",\n    \"insightId\",\n    \"questionNodeId\",\n    \"targetId\",\n    \"topicId\",\n    \"trustedBypassAccessCheck\",\n    \"weight\",\n  ],\n  list_evidence: [\"status\"],\n  manage_write_policy: [\"summary\"],\n  merge: [\"decisionsReached\", \"keyFindings\", \"nextSteps\"],\n  record_attempt: [\"reasoning\", \"trustedBypassAccessCheck\"],\n  record_judgment: [\"reasoning\", \"trustedBypassAccessCheck\"],\n  record_scope_learning: [\"reasoning\", \"trustedBypassAccessCheck\"],\n  search_beliefs: [\"searchQuery\"],\n  search_evidence: [\"query\", \"searchQuery\"],\n  update_question_status: [\"answer\", \"answerStatus\", \"nodeId\", \"questionId\"],\n  update_topic: [\"graphScopeProjectId\"],\n};\n\nfunction unwrapObjectSchema(\n  schema: z.ZodTypeAny,\n): z.ZodObject<z.ZodRawShape> | undefined {\n  let current = schema;\n  while (true) {\n    switch (current._def.typeName) {\n      case z.ZodFirstPartyTypeKind.ZodEffects:\n        current = current._def.schema;\n        continue;\n      case z.ZodFirstPartyTypeKind.ZodBranded:\n        current = current._def.type;\n        continue;\n      default:\n        return current instanceof z.ZodObject ? current : undefined;\n    }\n  }\n}\n\nfunction objectSchemaKeys(schema: z.ZodTypeAny): Set<string> {\n  const objectSchema = unwrapObjectSchema(schema);\n  if (!objectSchema) {\n    return new Set();\n  }\n  const shape =\n    typeof objectSchema._def.shape === \"function\"\n      ? objectSchema._def.shape()\n      : objectSchema._def.shape;\n  return new Set(Object.keys(shape));\n}\n\nexport function projectionReadKeys(\n  projection: InputProjection,\n): string[] {\n  if (!projection) {\n    return [];\n  }\n  const source = String(projection);\n  const keys = new Set<string>();\n\n  for (const match of source.matchAll(/\\binput\\s*\\.\\s*([A-Za-z_$][\\w$]*)/gu)) {\n    keys.add(match[1]);\n  }\n  for (const match of source.matchAll(/\\binput\\s*\\[\\s*[\"']([^\"']+)[\"']\\s*\\]/gu)) {\n    keys.add(match[1]);\n  }\n\n  return [...keys].sort();\n}\n\nfunction acceptedInputKeys(contract: FunctionContract): string[] {\n  return [\n    ...new Set([\n      ...objectSchemaKeys(contract.args),\n      ...objectSchemaKeys(contract.input),\n      ...Object.keys(contract.mcp.parameters),\n      \"__sdkSessionId\",\n    ]),\n  ].sort();\n}\n\nfunction allowedProjectionKeys(contractName: string): Set<string> {\n  return new Set([\n    ...INTERNAL_OR_ALIAS_KEYS,\n    ...(INTENTIONAL_PROJECTION_READS[contractName] ?? []),\n  ]);\n}\n\nexport function auditFunctionRegistryInputs(\n  contracts: readonly FunctionContract[] = ALL_FUNCTION_CONTRACTS,\n): FunctionRegistryInputAuditFinding[] {\n  return contracts.flatMap((contract) => {\n    const projectionKeys = projectionReadKeys(contract.convex?.inputProjection);\n    if (projectionKeys.length === 0) {\n      return [];\n    }\n\n    const accepted = new Set(acceptedInputKeys(contract));\n    const allowed = allowedProjectionKeys(contract.name);\n    const missingKeys = projectionKeys.filter(\n      (key) => !accepted.has(key) && !allowed.has(key),\n    );\n\n    if (missingKeys.length === 0) {\n      return [];\n    }\n\n    return [\n      {\n        contractName: contract.name,\n        projectionKeys,\n        acceptedKeys: [...accepted].sort(),\n        missingKeys,\n      },\n    ];\n  });\n}\n"]}

package/dist/gateway.contract.d.ts

@@ -43,6 +43,7 @@ type GatewayAuthContext = {
     tenantId?: string;
     workspaceId?: string;
     roles?: string[];
+    membershipId?: string;
     sessionId?: string;
     sessionAuthMode?: SessionAuthMode;
     sessionExpiresAt?: number;

package/dist/gateway.contract.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/gateway.contract.ts"],"names":[],"mappings":";AA4IO,SAAS,wBACd,WAAA,EACQ;AACR,EAAA,MAAM,WAAA,GACJ,OAAO,WAAA,CAAY,WAAA,KAAgB,WAC/B,WAAA,CAAY,WAAA,CAAY,MAAK,GAC7B,EAAA;AACN,EAAA,IAAI,WAAA,CAAY,SAAS,CAAA,EAAG;AAC1B,IAAA,OAAO,WAAA;AAAA,EACT;AACA,EAAA,MAAM,IAAI,MAAM,sDAAsD,CAAA;AACxE","file":"gateway.contract.js","sourcesContent":["/**\n * Gateway contract types — shared between Stack's gateway middleware and\n * Lucern's server-core / gateway route handlers.\n *\n * These types describe the authenticated request context that flows from\n * the gateway into Lucern route handlers. The gateway (Stack-side) creates\n * the context; Lucern consumes it read-only.\n *\n * @module @lucern/contracts/src/gateway\n */\n\nimport type {\n  SessionAuthMode,\n  SessionDelegationHop,\n  SessionPrincipalType,\n} from \"./auth-session.contract\";\n\n// ---------------------------------------------------------------------------\n// Error codes\n// ---------------------------------------------------------------------------\n\nexport type PlatformApiErrorCode =\n  | \"AUTH_REQUIRED\"\n  | \"AUTHENTICATION_REQUIRED\"\n  | \"AUTH_TOKEN_MISSING\"\n  | \"INVALID_REQUEST\"\n  | \"IDEMPOTENCY_KEY_REQUIRED\"\n  | \"FORBIDDEN\"\n  | \"SCOPE_INSUFFICIENT\"\n  | \"ENVIRONMENT_MISMATCH\"\n  | \"KEY_EXPIRED\"\n  | \"KEY_REVOKED\"\n  | \"RATE_LIMIT_EXCEEDED\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"UPSTREAM_ERROR\"\n  | \"INTERNAL_ERROR\";\n\n// ---------------------------------------------------------------------------\n// Gateway scope and environment\n// ---------------------------------------------------------------------------\n\nexport type GatewayScope = {\n  tenantId?: string;\n  workspaceId?: string;\n};\n\nexport type GatewayEnvironment = \"sandbox\" | \"production\";\n\nexport type GatewayAuthMode =\n  | \"interactive_user\"\n  | \"service_principal\"\n  | \"tenant_api_key\"\n  | \"session_token\";\n\nexport type KeyLifecycleStatus =\n  | \"active\"\n  | \"rotating\"\n  | \"rotated\"\n  | \"expired\"\n  | \"revoked\";\n\nexport type CutoverDomain =\n  | \"graph\"\n  | \"schema\"\n  | \"identity\"\n  | \"policy\"\n  | \"audit\"\n  | \"admin\"\n  | \"agent\"\n  | \"tool\"\n  | \"prompt\"\n  | \"intelligence\";\n\nexport type CutoverFlagState = \"legacy\" | \"cutover\" | \"disabled\";\n\n// ---------------------------------------------------------------------------\n// Gateway auth context — the canonical authenticated request shape\n// ---------------------------------------------------------------------------\n\n/**\n * Authenticated request context created by the gateway middleware.\n * Lucern route handlers receive this as a read-only parameter.\n *\n * The `convex` field is typed as `unknown` in the contract because Lucern\n * consumers should not use the gateway's Convex client directly — they\n * have their own kernel client. The gateway (Stack-side) narrows this to\n * `ConvexHttpClient` at the construction site.\n */\nexport type GatewayAuthContext = {\n  userId: string;\n  clerkId?: string;\n  convexToken?: string;\n  /** Opaque in contract — narrowed to ConvexHttpClient at the gateway. */\n  convex: any; // eslint-disable-line @typescript-eslint/no-explicit-any\n  authMode: GatewayAuthMode;\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  tenantId?: string;\n  workspaceId?: string;\n  roles?: string[];\n  sessionId?: string;\n  sessionAuthMode?: SessionAuthMode;\n  sessionExpiresAt?: number;\n  delegationChain?: SessionDelegationHop[];\n  servicePrincipalId?: string;\n  servicePrincipalKeyId?: string;\n  servicePrincipalTenantId?: string;\n  servicePrincipalWorkspaceId?: string;\n  requestEnvironment: GatewayEnvironment;\n  keyEnvironment?: GatewayEnvironment;\n  keyStatus: KeyLifecycleStatus | \"unknown\";\n  grantedScopes: Set<string>;\n  cutoverDomain: CutoverDomain;\n  cutoverState: CutoverFlagState;\n};\n\n// ---------------------------------------------------------------------------\n// Gateway response helpers — portable (no Next.js dependency)\n// ---------------------------------------------------------------------------\n\nexport type GatewayErrorArgs = {\n  code: PlatformApiErrorCode;\n  message: string;\n  status: number;\n  correlationId: string;\n  policyTraceId?: string;\n  invariant?: string;\n  suggestion?: string;\n  details?: unknown;\n  headers?: HeadersInit;\n};\n\nexport type GatewaySuccessArgs = {\n  status?: number;\n  correlationId: string;\n  policyTraceId?: string;\n  idempotentReplay?: boolean;\n};\n\nexport function requireActorPrincipalId(\n  authContext: GatewayAuthContext\n): string {\n  const principalId =\n    typeof authContext.principalId === \"string\"\n      ? authContext.principalId.trim()\n      : \"\";\n  if (principalId.length > 0) {\n    return principalId;\n  }\n  throw new Error(\"Access denied: federated principal context required.\");\n}\n"]}
+{"version":3,"sources":["../src/gateway.contract.ts"],"names":[],"mappings":";AA6IO,SAAS,wBACd,WAAA,EACQ;AACR,EAAA,MAAM,WAAA,GACJ,OAAO,WAAA,CAAY,WAAA,KAAgB,WAC/B,WAAA,CAAY,WAAA,CAAY,MAAK,GAC7B,EAAA;AACN,EAAA,IAAI,WAAA,CAAY,SAAS,CAAA,EAAG;AAC1B,IAAA,OAAO,WAAA;AAAA,EACT;AACA,EAAA,MAAM,IAAI,MAAM,sDAAsD,CAAA;AACxE","file":"gateway.contract.js","sourcesContent":["/**\n * Gateway contract types — shared between Stack's gateway middleware and\n * Lucern's server-core / gateway route handlers.\n *\n * These types describe the authenticated request context that flows from\n * the gateway into Lucern route handlers. The gateway (Stack-side) creates\n * the context; Lucern consumes it read-only.\n *\n * @module @lucern/contracts/src/gateway\n */\n\nimport type {\n  SessionAuthMode,\n  SessionDelegationHop,\n  SessionPrincipalType,\n} from \"./auth-session.contract\";\n\n// ---------------------------------------------------------------------------\n// Error codes\n// ---------------------------------------------------------------------------\n\nexport type PlatformApiErrorCode =\n  | \"AUTH_REQUIRED\"\n  | \"AUTHENTICATION_REQUIRED\"\n  | \"AUTH_TOKEN_MISSING\"\n  | \"INVALID_REQUEST\"\n  | \"IDEMPOTENCY_KEY_REQUIRED\"\n  | \"FORBIDDEN\"\n  | \"SCOPE_INSUFFICIENT\"\n  | \"ENVIRONMENT_MISMATCH\"\n  | \"KEY_EXPIRED\"\n  | \"KEY_REVOKED\"\n  | \"RATE_LIMIT_EXCEEDED\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"UPSTREAM_ERROR\"\n  | \"INTERNAL_ERROR\";\n\n// ---------------------------------------------------------------------------\n// Gateway scope and environment\n// ---------------------------------------------------------------------------\n\nexport type GatewayScope = {\n  tenantId?: string;\n  workspaceId?: string;\n};\n\nexport type GatewayEnvironment = \"sandbox\" | \"production\";\n\nexport type GatewayAuthMode =\n  | \"interactive_user\"\n  | \"service_principal\"\n  | \"tenant_api_key\"\n  | \"session_token\";\n\nexport type KeyLifecycleStatus =\n  | \"active\"\n  | \"rotating\"\n  | \"rotated\"\n  | \"expired\"\n  | \"revoked\";\n\nexport type CutoverDomain =\n  | \"graph\"\n  | \"schema\"\n  | \"identity\"\n  | \"policy\"\n  | \"audit\"\n  | \"admin\"\n  | \"agent\"\n  | \"tool\"\n  | \"prompt\"\n  | \"intelligence\";\n\nexport type CutoverFlagState = \"legacy\" | \"cutover\" | \"disabled\";\n\n// ---------------------------------------------------------------------------\n// Gateway auth context — the canonical authenticated request shape\n// ---------------------------------------------------------------------------\n\n/**\n * Authenticated request context created by the gateway middleware.\n * Lucern route handlers receive this as a read-only parameter.\n *\n * The `convex` field is typed as `unknown` in the contract because Lucern\n * consumers should not use the gateway's Convex client directly — they\n * have their own kernel client. The gateway (Stack-side) narrows this to\n * `ConvexHttpClient` at the construction site.\n */\nexport type GatewayAuthContext = {\n  userId: string;\n  clerkId?: string;\n  convexToken?: string;\n  /** Opaque in contract — narrowed to ConvexHttpClient at the gateway. */\n  convex: any; // eslint-disable-line @typescript-eslint/no-explicit-any\n  authMode: GatewayAuthMode;\n  principalId?: string;\n  principalType?: SessionPrincipalType;\n  tenantId?: string;\n  workspaceId?: string;\n  roles?: string[];\n  membershipId?: string;\n  sessionId?: string;\n  sessionAuthMode?: SessionAuthMode;\n  sessionExpiresAt?: number;\n  delegationChain?: SessionDelegationHop[];\n  servicePrincipalId?: string;\n  servicePrincipalKeyId?: string;\n  servicePrincipalTenantId?: string;\n  servicePrincipalWorkspaceId?: string;\n  requestEnvironment: GatewayEnvironment;\n  keyEnvironment?: GatewayEnvironment;\n  keyStatus: KeyLifecycleStatus | \"unknown\";\n  grantedScopes: Set<string>;\n  cutoverDomain: CutoverDomain;\n  cutoverState: CutoverFlagState;\n};\n\n// ---------------------------------------------------------------------------\n// Gateway response helpers — portable (no Next.js dependency)\n// ---------------------------------------------------------------------------\n\nexport type GatewayErrorArgs = {\n  code: PlatformApiErrorCode;\n  message: string;\n  status: number;\n  correlationId: string;\n  policyTraceId?: string;\n  invariant?: string;\n  suggestion?: string;\n  details?: unknown;\n  headers?: HeadersInit;\n};\n\nexport type GatewaySuccessArgs = {\n  status?: number;\n  correlationId: string;\n  policyTraceId?: string;\n  idempotentReplay?: boolean;\n};\n\nexport function requireActorPrincipalId(\n  authContext: GatewayAuthContext\n): string {\n  const principalId =\n    typeof authContext.principalId === \"string\"\n      ? authContext.principalId.trim()\n      : \"\";\n  if (principalId.length > 0) {\n    return principalId;\n  }\n  throw new Error(\"Access denied: federated principal context required.\");\n}\n"]}

package/dist/generated/convexSchemas.js

@@ -118,7 +118,7 @@ var MC_SCHEMA_TABLES = {
   "toolCatalog": defineTable(v.object({ "category": v.union(v.literal("read"), v.literal("write"), v.literal("admin"), v.literal("system")), "createdAt": v.number(), "description": v.string(), "distribution": v.union(v.literal("base"), v.literal("pack_only")), "executionAdapter": v.optional(v.union(v.literal("convex_mutation"), v.literal("convex_action"), v.literal("http_callback"), v.literal("mcp_tool"), v.literal("sdk_invocation"), v.literal("external_observed"))), "handlerRef": v.optional(v.string()), "metadata": v.optional(v.record(v.string(), v.any())), "parameterSchema": v.optional(v.record(v.string(), v.any())), "requiredAction": v.union(v.literal("read"), v.literal("mutate"), v.literal("admin"), v.literal("summarize"), v.literal("export"), v.literal("create"), v.literal("delete"), v.literal("grant"), v.literal("revoke")), "requiredRole": v.union(v.literal("platform_admin"), v.literal("tenant_admin"), v.literal("workspace_admin"), v.literal("editor"), v.literal("viewer"), v.literal("auditor"), v.literal("service_agent")), "returnSchema": v.optional(v.record(v.string(), v.any())), "safetyMetadata": v.optional(v.object({ "idempotent": v.boolean(), "readOnly": v.boolean(), "sideEffectLevel": v.union(v.literal("none"), v.literal("low"), v.literal("high")) })), "status": v.union(v.literal("active"), v.literal("deprecated"), v.literal("draft")), "surfaces": v.array(v.union(v.literal("mcp"), v.literal("chat"), v.literal("voice"), v.literal("sprint"), v.literal("api"), v.literal("sdk"), v.literal("cli"))), "toolName": v.string(), "updatedAt": v.number(), "version": v.string() })).index("by_toolName", ["toolName"]).index("by_status", ["status"]).index("by_distribution", ["distribution"]).index("by_distribution_status", ["distribution", "status"]).index("by_category", ["category"]).index("by_requiredRole", ["requiredRole"]),
   "toolRegistryEntries": defineTable(v.object({ "approvalGateId": v.optional(v.string()), "category": v.optional(v.union(v.literal("read"), v.literal("write"), v.literal("admin"), v.literal("system"))), "createdAt": v.number(), "createdBy": v.string(), "description": v.string(), "exampleInvocations": v.array(v.object({ "expectedOutput": v.optional(v.record(v.string(), v.any())), "input": v.record(v.string(), v.any()) })), "executionAdapter": v.union(v.literal("convex_mutation"), v.literal("convex_action"), v.literal("http_callback"), v.literal("mcp_tool"), v.literal("sdk_invocation"), v.literal("external_observed")), "gateClassification": v.union(v.literal("core"), v.literal("shimmed")), "isCore": v.optional(v.boolean()), "metadata": v.optional(v.record(v.string(), v.any())), "parameterSchema": v.record(v.string(), v.any()), "requiredAction": v.optional(v.union(v.literal("read"), v.literal("mutate"), v.literal("admin"), v.literal("summarize"), v.literal("export"), v.literal("create"), v.literal("delete"), v.literal("grant"), v.literal("revoke"))), "requiredRole": v.optional(v.union(v.literal("platform_admin"), v.literal("tenant_admin"), v.literal("workspace_admin"), v.literal("editor"), v.literal("viewer"), v.literal("auditor"), v.literal("service_agent"))), "safetyMetadata": v.object({ "idempotent": v.boolean(), "readOnly": v.boolean(), "sideEffectLevel": v.union(v.literal("none"), v.literal("low"), v.literal("high")) }), "scopeRequirements": v.array(v.string()), "status": v.union(v.literal("active"), v.literal("deprecated"), v.literal("disabled")), "surfaces": v.optional(v.array(v.union(v.literal("mcp"), v.literal("chat"), v.literal("voice"), v.literal("sprint"), v.literal("api"), v.literal("sdk"), v.literal("cli")))), "tenantId": v.id("tenants"), "toolId": v.string(), "toolName": v.string(), "updatedAt": v.number(), "version": v.string(), "workspaceId": v.optional(v.id("workspaces")) })).index("by_toolId", ["toolId"]).index("by_tenant_toolId", ["tenantId", "toolId"]).index("by_tenant_toolId_version", ["tenantId", "toolId", "version"]).index("by_tenant_toolName", ["tenantId", "toolName"]).index("by_tenant_toolName_version", ["tenantId", "toolName", "version"]).index("by_workspace_toolName_version", ["workspaceId", "toolName", "version"]).index("by_tenant_gateClassification", ["tenantId", "gateClassification"]).index("by_tenant_status", ["tenantId", "status"]),
   "userSessions": defineTable(v.object({ "apiKeyId": v.id("apiKeys"), "authMode": v.optional(v.union(v.literal("interactive_user"), v.literal("service_principal"), v.literal("tenant_api_key"), v.literal("session_token"))), "clerkUserId": v.string(), "createdAt": v.number(), "delegationChain": v.optional(v.array(v.object({ "authMode": v.optional(v.union(v.literal("interactive_user"), v.literal("service_principal"), v.literal("tenant_api_key"), v.literal("session_token"))), "delegatedAt": v.optional(v.number()), "principalId": v.string(), "principalType": v.union(v.literal("human"), v.literal("service"), v.literal("agent")), "reason": v.optional(v.string()), "sessionId": v.optional(v.string()) }))), "jwtExpiresAt": v.optional(v.number()), "jwtIssuedAt": v.optional(v.number()), "lastActivityAt": v.number(), "lastValidatedAt": v.optional(v.number()), "principalId": v.optional(v.string()), "principalType": v.optional(v.union(v.literal("human"), v.literal("service"), v.literal("agent"))), "revokedAt": v.optional(v.number()), "revokedBy": v.optional(v.string()), "revokeReason": v.optional(v.string()), "role": v.optional(v.string()), "scopes": v.optional(v.array(v.string())), "sessionExpiresAt": v.optional(v.number()), "sessionId": v.string(), "sessionType": v.union(v.literal("user"), v.literal("agent")), "sourceSessionId": v.optional(v.string()), "status": v.union(v.literal("active"), v.literal("expired"), v.literal("revoked")), "tenantId": v.id("tenants"), "updatedAt": v.number(), "workspaceId": v.optional(v.string()) })).index("by_sessionId", ["sessionId"]).index("by_sourceSessionId", ["sourceSessionId"]).index("by_tenantId", ["tenantId"]).index("by_clerkUserId", ["clerkUserId"]).index("by_status", ["status"]),
-  "workspaces": defineTable(v.object({ "createdAt": v.number(), "createdBy": v.optional(v.string()), "defaultProjectVisibility": v.optional(v.union(v.literal("private"), v.literal("team"), v.literal("firm"), v.literal("external"), v.literal("public"))), "deployments": v.optional(v.record(v.string(), v.object({ "encryptedDeployKey": v.string(), "url": v.string() }))), "key": v.string(), "metadata": v.optional(v.record(v.string(), v.any())), "name": v.string(), "slug": v.string(), "status": v.union(v.literal("active"), v.literal("archived")), "tenantId": v.id("tenants"), "updatedAt": v.number() })).index("by_tenantId", ["tenantId"]).index("by_tenantId_key", ["tenantId", "key"]).index("by_tenantId_slug", ["tenantId", "slug"]).index("by_status", ["status"])
+  "workspaces": defineTable(v.object({ "createdAt": v.number(), "createdBy": v.optional(v.string()), "defaultProjectVisibility": v.optional(v.union(v.literal("private"), v.literal("team"), v.literal("firm"), v.literal("external"), v.literal("public"))), "deployments": v.optional(v.record(v.string(), v.object({ "credentialRef": v.optional(v.string()), "encryptedDeployKey": v.optional(v.string()), "target": v.optional(v.union(v.literal("kernelDeployment"), v.literal("appDeployment"))), "url": v.string() }))), "key": v.string(), "metadata": v.optional(v.record(v.string(), v.any())), "name": v.string(), "slug": v.string(), "status": v.union(v.literal("active"), v.literal("archived")), "tenantId": v.id("tenants"), "updatedAt": v.number() })).index("by_tenantId", ["tenantId"]).index("by_tenantId_key", ["tenantId", "key"]).index("by_tenantId_slug", ["tenantId", "slug"]).index("by_status", ["status"])
 };
 var DEVELOPER_PACK_SCHEMA_TABLES = {};
 var EMPTY_SCHEMA_TABLES = {};