@lucern/events 0.3.0-alpha.15 → 0.3.0-alpha.17

package/README.md

@@ -1,5 +1,17 @@
-# packages/events
+# @lucern/events
 
-Event infrastructure: outbox pattern, webhook delivery, replay, projection reconciliation.
+Operational eventing helpers for Lucern: domain event contracts, event matching,
+outbox helper re-exports, webhook validation, webhook signing, retry scheduling,
+and delivery record sanitization.
 
 ## Built by: EK-13.8 (Eventing + Async Integrations)
+
+## Replay boundary
+
+This package is operational eventing substrate. It is not the final Campaign #4
+bitemporal replay architecture. Source Horizons, Output Objects, Computation
+Runs, Bitemporal Events, Replay Records, and source-horizon-bound artifact
+replay remain roadmap contracts.
+
+See `docs/reference/mcp-event-packages.md` for package-boundary truth and
+`docs/development/mcp-eventing-workflows.md` for development workflow examples.

package/dist/index.js

@@ -893,6 +893,7 @@ defineTable({
   shape: z.object({
     "tenantId": idOf("tenants"),
     "workspaceId": idOf("workspaces").optional(),
+    "environment": z.enum(["dev", "staging", "prod"]).optional(),
     "keyPrefix": z.enum(["luc", "stk"]),
     "keyHash": z.string(),
     "keyHint": z.string(),
@@ -920,7 +921,7 @@ defineTable({
   shape: z.object({
     "tenantId": idOf("tenants").optional(),
     "apiKeyId": idOf("apiKeys").optional(),
-    "action": z.enum(["key_created", "key_revoked", "key_expired", "key_used", "tenant_secret_created", "tenant_secret_rotated", "tenant_secret_revoked", "tenant_slot_binding_upserted", "tenant_slot_binding_revoked", "proxy_token_minted", "proxy_token_lease_issued", "proxy_token_lease_renewed", "proxy_token_lease_revoked", "proxy_request_recorded", "tenant_created", "tenant_updated", "tenant_suspended", "tenant_archived", "tenant_reactivated", "principal_created", "principal_updated", "principal_suspended", "principal_identity_alias_upserted", "principal_identity_alias_revoked", "membership_created", "membership_updated", "membership_revoked", "group_created", "group_updated", "group_deleted", "group_member_added", "group_member_removed", "workspace_created", "workspace_updated", "workspace_archived", "workspace_deployment_set", "workspace_deployment_removed", "deployment_host_registered", "deployment_host_revoked", "service_key_created", "service_key_rotated", "service_key_revoked", "service_key_used", "service_key_auth_failed", "session_created", "session_validated", "session_revoked", "session_cascade_revoked", "session_expired", "sandbox_created", "sandbox_secret_injected", "sandbox_execution_started", "sandbox_execution_completed", "sandbox_limit_violated", "policy_created", "policy_updated", "policy_enforced", "policy_archived", "permit_sync_enqueued", "permit_sync_succeeded", "permit_sync_failed", "permit_sync_skipped", "agent_registered", "agent_updated", "tool_registered", "tool_updated", "pack_entitled", "pack_installed", "pack_enabled", "pack_disabled", "pack_entitlement_revoked", "pack_upgraded", "pack_upgrade_committed", "pack_upgrade_rolled_back", "pack_group_assigned", "pack_group_unassigned", "methodology_pack_created", "methodology_pack_updated", "methodology_pack_assigned", "methodology_pack_removed", "pack_assigned_to_group", "pack_revoked_from_group", "pack_ontology_materialized", "pack_ontology_topic_bound", "cutover_flag_set", "cutover_flag_cleared"]),
+    "action": z.enum(["key_created", "key_revoked", "key_expired", "key_used", "tenant_secret_created", "tenant_secret_rotated", "tenant_secret_revoked", "tenant_slot_binding_upserted", "tenant_slot_binding_revoked", "proxy_token_minted", "proxy_token_lease_issued", "proxy_token_lease_renewed", "proxy_token_lease_revoked", "proxy_request_recorded", "tenant_created", "tenant_updated", "tenant_suspended", "tenant_archived", "tenant_reactivated", "tenant_clerk_organization_linked", "principal_created", "principal_updated", "principal_suspended", "principal_identity_alias_upserted", "principal_identity_alias_revoked", "membership_created", "membership_updated", "membership_revoked", "group_created", "group_updated", "group_deleted", "group_member_added", "group_member_removed", "workspace_created", "workspace_updated", "workspace_archived", "workspace_deployment_set", "workspace_deployment_removed", "deployment_host_registered", "deployment_host_revoked", "service_key_created", "service_key_rotated", "service_key_revoked", "service_key_used", "service_key_auth_failed", "session_created", "session_validated", "session_revoked", "session_cascade_revoked", "session_expired", "sandbox_created", "sandbox_secret_injected", "sandbox_execution_started", "sandbox_execution_completed", "sandbox_limit_violated", "policy_created", "policy_updated", "policy_enforced", "policy_archived", "permit_sync_enqueued", "permit_sync_succeeded", "permit_sync_failed", "permit_sync_skipped", "agent_registered", "agent_updated", "tool_registered", "tool_updated", "pack_entitled", "pack_installed", "pack_enabled", "pack_disabled", "pack_entitlement_revoked", "pack_upgraded", "pack_upgrade_committed", "pack_upgrade_rolled_back", "pack_group_assigned", "pack_group_unassigned", "methodology_pack_created", "methodology_pack_updated", "methodology_pack_assigned", "methodology_pack_removed", "pack_assigned_to_group", "pack_revoked_from_group", "pack_ontology_materialized", "pack_ontology_topic_bound", "cutover_flag_set", "cutover_flag_cleared"]),
     "actorClerkId": z.string(),
     "details": z.any().optional(),
     "createdAt": z.number()
@@ -7049,7 +7050,7 @@ function compactRecord2(input) {
     Object.entries(input).filter(([, value]) => value !== void 0)
   );
 }
-var listBeliefsProjection = defineProjection({
+defineProjection({
   contractName: "list_beliefs",
   inputSchema: listBeliefsInputSchema,
   project: (input) => compactRecord2({
@@ -9558,7 +9559,7 @@ var IDENTITY_WHOAMI = {
   response: {
     description: "Canonical identity summary for the current session",
     fields: {
-      principalId: "string \u2014 canonical federated principal identifier",
+      principalId: "string \u2014 canonical principal identifier; for humans this is the Clerk user_... ID",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       tenantId: "string | undefined \u2014 resolved tenant scope",
       workspaceId: "string | undefined \u2014 resolved workspace scope",
@@ -9572,7 +9573,7 @@ var IDENTITY_WHOAMI = {
 };
 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.",
+  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 Clerk subject into tenant/workspace authorization context.",
   parameters: {
     clerkId: {
       type: "string",
@@ -9595,7 +9596,7 @@ var RESOLVE_INTERACTIVE_PRINCIPAL = {
   response: {
     description: "Permit-backed Lucern principal context for tenant SDK bootstrap",
     fields: {
-      principalId: "string \u2014 canonical Lucern principal identifier",
+      principalId: "string \u2014 canonical Clerk user_... ID for human sessions",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       clerkId: "string \u2014 authenticated Clerk subject alias",
       tenantId: "string \u2014 resolved tenant scope",
@@ -10423,7 +10424,7 @@ var MANAGE_WRITE_POLICY = {
     },
     role: {
       type: "string",
-      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal', 'user:analyst'."
+      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal' or a Permit role key such as 'workspace_admin'."
     },
     permission: {
       type: "string",
@@ -12353,11 +12354,8 @@ var identityContracts = [
     sdkNamespace: "identity",
     sdkMethod: "whoami",
     summary: "Describe the current gateway principal.",
-    convex: {
-      module: "identity",
-      functionName: "whoami",
-      kind: "query",
-      inputProjection: withPrincipal
+    gateway: {
+      handler: "identity.whoami"
     }
   }),
   surfaceContract({
@@ -12377,7 +12375,7 @@ var identityContracts = [
       providerProjectId: z.string().min(1).optional()
     }),
     convex: {
-      module: "identity",
+      module: "platform",
       functionName: "resolveInteractivePrincipal",
       kind: "query"
     }
@@ -12461,15 +12459,6 @@ var beliefLookupInput = (input) => compactRecord4({
 var beliefNodeInput = (input) => compactRecord4({
   nodeId: input.nodeId ?? input.id ?? input.beliefId
 });
-var beliefTopicInput = (input) => {
-  const parsed = listBeliefsProjection.inputSchema.safeParse(input);
-  if (!parsed.success) {
-    throw new Error(
-      `list_beliefs projection input rejected: ${parsed.error.message}`
-    );
-  }
-  return compactRecord4(listBeliefsProjection.project(parsed.data));
-};
 var createBeliefInput = (input, context) => {
   return withUserId(
     compactRecord4({
@@ -12558,11 +12547,8 @@ var beliefsContracts = [
     sdkNamespace: "beliefs",
     sdkMethod: "listBeliefs",
     summary: "List beliefs for a topic.",
-    convex: {
-      module: "beliefs",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: beliefTopicInput
+    gateway: {
+      handler: "beliefs.list"
     },
     args: listBeliefsInputSchema
   }),
@@ -12747,12 +12733,6 @@ var evidenceIdInput = (input) => compactRecord4({
   insightId: input.insightId,
   nodeId: input.nodeId ?? input.id ?? input.evidenceId
 });
-var evidenceTopicInput = (input) => compactRecord4({
-  topicId: input.topicId,
-  status: input.status,
-  userId: input.userId,
-  limit: input.limit
-});
 var createEvidenceInput = (input, context) => {
   const parsed = createEvidenceProjection.inputSchema.safeParse(input);
   if (!parsed.success) {
@@ -12883,11 +12863,8 @@ var evidenceContracts = [
     sdkNamespace: "evidence",
     sdkMethod: "listEvidence",
     summary: "List evidence for a topic.",
-    convex: {
-      module: "evidence",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: evidenceTopicInput
+    gateway: {
+      handler: "evidence.list"
     }
   }),
   surfaceContract({
@@ -13122,11 +13099,8 @@ var questionsContracts = [
     sdkNamespace: "questions",
     sdkMethod: "listQuestions",
     summary: "List questions for a topic.",
-    convex: {
-      module: "questions",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: questionTopicInput
+    gateway: {
+      handler: "questions.list"
     }
   }),
   surfaceContract({
@@ -14231,6 +14205,19 @@ var worktreeEvidenceSignalInputSchema = z.object({
   progress: z.string().optional().describe("Collection progress note for the signal."),
   notes: z.string().optional().describe("Additional evidence collection notes.")
 }).passthrough().describe("Evidence signal embedded in the worktree plan.");
+var worktreeDocCompanionTargetSchema = z.object({
+  docPath: z.string().describe(
+    "Repo-relative path to a documentation file the worktree promises to update."
+  ),
+  sectionAnchor: z.string().optional().describe(
+    "Markdown heading anchor (e.g. '## Function-surface manifest') that scopes the promised update."
+  ),
+  reason: z.string().describe(
+    "Why this doc section must be updated for the worktree to be complete."
+  )
+}).passthrough().describe(
+  "Intent-driven docs companion target. pr-gate-reviewer verifies that the PR actually touches each declared (docPath, sectionAnchor). Distinct from the touch-driven docs-loop. See docs/development/docs-sync-discipline.md Lock 3."
+);
 var worktreeDecisionGateInputSchema = z.object({
   goCriteria: z.array(z.string()).describe("Criteria that must hold for the worktree to proceed."),
   noGoSignals: z.array(z.string()).describe("Signals that stop or redirect the worktree."),
@@ -14263,6 +14250,9 @@ var addWorktreeArgs = z.object({
   keyQuestions: z.array(worktreeKeyQuestionInputSchema).optional().describe("Inline key questions captured as part of the worktree plan."),
   evidenceSignals: z.array(worktreeEvidenceSignalInputSchema).optional().describe("Evidence signals the worktree needs to collect or validate."),
   decisionGate: worktreeDecisionGateInputSchema.optional(),
+  docCompanionTargets: z.array(worktreeDocCompanionTargetSchema).optional().describe(
+    "Doc sections the worktree promises to update at PR time. Enforced by pr-gate-reviewer (Lock 3)."
+  ),
   goCriteria: z.array(z.string()).optional().describe("Shorthand go criteria used to build decisionGate."),
   noGoSignals: z.array(z.string()).optional().describe("Shorthand no-go signals used to build decisionGate."),
   proofArtifacts: z.array(z.unknown()).optional().describe("Expected proof artifacts required to close the worktree."),