@lucern/events 0.3.0-alpha.16 → 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

@@ -921,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()
@@ -9559,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",
@@ -9573,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",
@@ -9596,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",
@@ -10424,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",
@@ -14205,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."),
@@ -14237,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."),