spine-framework 0.3.145 → 0.4.0

package/.framework/functions/_shared/notify.ts

@@ -0,0 +1,70 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/notify.ts:resolve_notification_recipients:module" type="module" identity="resolve_notification_recipients" parent="~/.framework/functions/_shared/notify.ts"]
+// CIL[DOC-MACRO purpose="Resolve notification recipient entries (person UUIDs and 'role:<slug>' handles) into concrete people.id values for notification writes."]
+// CIL[DOC-RESPONSIBILITY responsibility="Translate each recipient entry — a person UUID passthrough or a 'role:<slug>' lookup against account-scoped, active people joined to roles — into people.id strings, warning and skipping anything unresolvable."]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/pipeline-runner.ts,.framework/functions/_shared/agent-runner.ts,.framework/functions/_shared/permissions.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext (account scope); recipients: any[] of 'role:<slug>' or person UUID strings" outputs="Promise<string[]> of deduped people.id values" errors="none thrown — lookup failures and malformed entries warn and are skipped" side_effects="One people/roles join query per role: entry"]
+// CIL[DOC-MICRO logic_summary="Each entry matching /^role:(.+)$/ queries people in ctx.accountId with an inner join to roles on people.role_id filtered by roles.slug; UUID-shaped entries pass through; anything else warns and is skipped. A role that matches zero people yields zero recipients — a valid empty result, not an error." notable_decisions="person_id on notifications is a uuid column, so a literal 'role:member_admin' must never reach the insert; both notification writers (pipeline-runner send_notification, agent-runner executeSendNotification) share this resolver"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
+import { CoreContext } from './middleware'
+import { adminDb } from './db'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const ROLE_RE = /^role:(.+)$/
+
+export async function resolveNotificationRecipients(
+  ctx: CoreContext,
+  recipients: any[]
+): Promise<string[]> {
+  const personIds: string[] = []
+
+  for (const entry of recipients ?? []) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      console.warn('[notify] skipping non-string notification recipient:', entry)
+      continue
+    }
+
+    const roleMatch = entry.match(ROLE_RE)
+    if (roleMatch) {
+      const slug = roleMatch[1]
+      // people.role_id -> roles.id (same join as permissions.ts/principal.ts);
+      // !inner filters to people whose role carries this slug.
+      const { data, error } = await adminDb
+        .from('people')
+        .select('id, role:roles!role_id!inner(slug)')
+        .eq('account_id', ctx.accountId)
+        .eq('is_active', true)
+        .eq('role.slug', slug)
+
+      if (error) {
+        console.warn(`[notify] role recipient lookup failed for 'role:${slug}': ${error.message}`)
+        continue
+      }
+      if (!data || data.length === 0) {
+        console.warn(`[notify] no active people found for role recipient 'role:${slug}'`)
+        continue
+      }
+      for (const row of data) {
+        if (row?.id) personIds.push(row.id)
+      }
+      continue
+    }
+
+    if (UUID_RE.test(entry)) {
+      personIds.push(entry)
+      continue
+    }
+
+    console.warn(`[notify] skipping unresolvable notification recipient '${entry}' — expected a person UUID or 'role:<slug>'`)
+  }
+
+  return [...new Set(personIds)]
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Resolve notification recipient entries (person UUIDs and role:<slug> handles) into concrete people.id values.'; callers: pipeline-runner send_notification stage, agent-runner executeSendNotification; imports: middleware, db" status="ready"]
+// CIL[DOC-VECTOR type="blast_radius" content="Both notification writers share the resolver — behavior change is confined to recipient mapping before the notifications insert" status="ready"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
+// CIL[DOC-VECTOR type="constraint" content="notifications.person_id is uuid — only resolved people.id values may be inserted; unknown entries warn and are skipped rather than failing the stage" status="ready"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/_shared/notify.ts:resolve_notification_recipients:module"]

package/.framework/functions/_shared/outcomes.ts

@@ -1,23 +1,32 @@
-// CIL[BEGIN chunk_id="outcomes_moduleheader_1785012346" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Emit business outcome events into the runtime evidence store"]
-// CIL[DOC-RESPONSIBILITY responsibility="Record whether a user-intent-level operation succeeded, failed, or partially succeeded"]
-// CIL[DOC-CONTEXT module="_shared.outcomes" layer="infrastructure" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="ctx: CoreContext, intent: string, result: string, metadata?: object" outputs="Promise<void>" errors="none" side_effects="DB write to logs"]
-// CIL[DOC-MICRO logic_summary="Thin wrapper around emitAudit that tags rows with event_category='business_outcome' and outcome result" notable_decisions=["Outcomes share the trace/span context of the current operation"] ]
-// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="experimental"]
-// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/outcomes.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/outcomes.ts"]
+// CIL[DOC-MACRO purpose="Module-level header for shared outcome audit utilities."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declares module imports and establishes file context for outcome audit helpers."]
+// CIL[DOC-CONTEXT module="outcomes" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/middleware.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Contains import statements for CoreContext and emitAudit; no runtime logic." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="internal"]
+
 import { CoreContext } from './middleware'
 import { emitAudit } from './audit'
-// CIL[END chunk_id="outcomes_moduleheader_1785012346"]
-// CIL[BEGIN chunk_id="outcomes_emitoutcome_1785012346" type="function" identity="emitOutcome" parent="outcomes_moduleheader_1785012346"]
-// CIL[DOC-MACRO purpose="Emit a business outcome event for a completed operation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Tag a span/log row with outcome result and intent-level metadata"]
-// CIL[DOC-CONTEXT module="_shared.outcomes" layer="infrastructure" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="ctx: CoreContext, intent: string, result: string, metadata?: object" outputs="Promise<void>" errors="none" side_effects="DB write to logs"]
-// CIL[DOC-MICRO logic_summary="Calls emitAudit with outcome result and optional extra metadata" notable_decisions=["Shares trace/span context of current operation"] ]
-// CIL[DOC-CONFIDENCE pass="first" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-VECTOR type="context" content="purpose='Module-level header for shared outcome audit utilities.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/_shared/outcomes.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/outcomes.ts:emitOutcome:function" type="function" identity="emitOutcome" parent="~/.framework/functions/_shared/outcomes.ts"]
+// CIL[DOC-MACRO purpose="Emits an outcome audit record for an operation result."]
+// CIL[DOC-RESPONSIBILITY responsibility="Records the success/failure/partial result of an operation to the audit log."]
+// CIL[DOC-CONTEXT module="outcomes" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/outcomes.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: CoreContext, intent: string, result: 'success'|'failure'|'partial', metadata?: Record<string, any>" outputs="Promise<void>" errors="none" side_effects="Calls emitAudit to persist an outcome record."]
+// CIL[DOC-MICRO logic_summary="Calls emitAudit with an outcome event, including the operation result and optional metadata." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 
 export async function emitOutcome(
   ctx: CoreContext,
@@ -33,4 +42,10 @@ export async function emitOutcome(
     ...metadata
   })
 }
-// CIL[END chunk_id="outcomes_emitoutcome_1785012346"]
+// CIL[DOC-VECTOR type="context" content="purpose='Emits an outcome audit record for an operation result.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/audit.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/_shared/outcomes.ts:emitOutcome:function"]