spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/functions/_shared/cil.ts

@@ -192,7 +192,8 @@ export function computeContentHash(raw: string): string {
            !trimmed.match(/^\/\*\*?\s*CIL\[DOC-/) &&
            !trimmed.match(/^<!--\s*CIL\[(BEGIN|END)/) &&
            !trimmed.match(/^<!--\s*CIL\[DOC-/) &&
-           !trimmed.match(/^#\s*CIL\[(BEGIN|END|DOC-)/)
+           !trimmed.match(/^#\s*CIL\[(BEGIN|END|DOC-)/) &&
+           !trimmed.match(/^--\s*CIL\[(BEGIN|END|DOC-)/)
   })
   const collapsed: string[] = []
   let lastBlank = false

package/.framework/functions/_shared/db.ts

@@ -3,7 +3,7 @@
 // CIL[DOC-RESPONSIBILITY responsibility="Owns the shared Supabase client exports and common query joins."]
 // CIL[DOC-CONTEXT module="functions/_shared/db" layer="data-access" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-CONTRACT inputs="[]" outputs="adminDb, getUserDb, DbResult, joins, constants" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Imports the Supabase client and WebSocket transport, then exports configured admin/user clients, a result type, and join mappings." notable_decisions="Falls back to placeholder credentials when environment values are absent."]
+// CIL[DOC-MICRO logic_summary="Imports the Supabase client and exports configured admin/user clients, a result type, and join mappings. WebSocket/ws realtime transport removed — server-side functions never subscribe to Supabase channels." notable_decisions="Falls back to placeholder credentials when environment values are absent. Realtime transport removed to reduce bundle size and eliminate unnecessary module-level initialization."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="human"]
@@ -14,7 +14,6 @@
 
 
 import { createClient } from '@supabase/supabase-js'
-import WebSocket from 'ws'
 // CIL[DOC-VECTOR type="context" content="purpose='Supabase client and database relation join module'; No verified external callers; imports: none"]
 // 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"]
@@ -241,12 +240,11 @@ const dbSchema: string = _env.DB_SCHEMA || 'public'
 // CIL[DOC-RESPONSIBILITY responsibility="Exports the admin-authorized Supabase client for backend use."]
 // CIL[DOC-CONTEXT module="functions/_shared/db" layer="data-access" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-CONTRACT inputs="[]" outputs="SupabaseClient adminDb" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Creates a createClient instance using supabaseUrl and supabaseServiceKey, sets the schema and WebSocket transport." notable_decisions="Uses service role key for elevated privileges and WebSocket for realtime."]
+// CIL[DOC-MICRO logic_summary="Creates a createClient instance using supabaseUrl and supabaseServiceKey and sets the schema. No realtime transport: server-side functions never subscribe to Supabase channels — omitting the ws transport shrinks every function bundle and eliminates an unnecessary module-level init." notable_decisions="Realtime transport removed: ws import added ~10KB to every bundle and could attempt a WebSocket handshake on module load. REST/PostgREST queries are unaffected."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
   db: { schema: dbSchema },
-  realtime: { transport: WebSocket as any }
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Admin Supabase client'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -262,14 +260,13 @@ export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
 // CIL[DOC-CONTEXT module="db" layer="functions" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-RESPONSIBILITY responsibility="Creates a Supabase client scoped to an end-user JWT."]
 // CIL[DOC-CONTRACT inputs="jwt: string" outputs="SupabaseClient" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Returns a createClient instance using supabaseUrl and supabaseAnonKey, schema, WebSocket transport, and an Authorization header." notable_decisions="Uses the anon key plus Bearer token for row-level security."]
+// CIL[DOC-MICRO logic_summary="Returns a createClient instance using supabaseUrl and supabaseAnonKey, schema, and an Authorization header." notable_decisions="Uses the anon key plus Bearer token for row-level security. Realtime transport omitted for same reasons as adminDb."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export function getUserDb(jwt: string) {
   return createClient(supabaseUrl, supabaseAnonKey, {
     db: { schema: dbSchema },
     global: { headers: { Authorization: `Bearer ${jwt}` } },
-    realtime: { transport: WebSocket as any }
   })
 }
 // CIL[END stable_id="~/.framework/functions/_shared/db.ts:getUserDb:function"]

package/.framework/functions/_shared/hash-api-key.ts

@@ -1,81 +1,135 @@
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Provides PBKDF2-based API key hashing and verification utilities"]
-// CIL[DOC-RESPONSIBILITY responsibility="Imports crypto primitives and exports hashApiKey and verifyApiKey"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports crypto functions used by hashing and verification" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developers"]
+/**
+ * @module   hash-api-key
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides utilities for securely hashing API keys using cryptographic functions. It plays a crucial role in ensuring the integrity and confidentiality of sensitive data within the application. INVARIANT: The API keys must always be hashed before storage to prevent unauthorized access.
+ *
+ * @seeAlso crypto (provides cryptographic functions for hashing).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 import { randomBytes, pbkdf2Sync, timingSafeEqual } from 'crypto'
-// CIL[DOC-VECTOR type="context" content="purpose='Provides PBKDF2-based API key hashing and verification utilities'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:module_header:module_header"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:ITERATIONS:constant" type="constant" identity="ITERATIONS" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the default PBKDF2 iteration count"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the default number of PBKDF2 iterations for hashing"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="number" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant default iteration count used by hashApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * ITERATIONS defines the number of iterations used for hashing an API key, ensuring a high level of security. This constant is crucial for maintaining the strength of the hashing process.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const ITERATIONS = 100000
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the default PBKDF2 iteration count'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:ITERATIONS:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:KEY_LENGTH:constant" type="constant" identity="KEY_LENGTH" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the derived key length in bytes for PBKDF2"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the PBKDF2 derived key length"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="number" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant derived key length used by hashApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * KEY_LENGTH defines the length of the API key used for hashing to ensure a consistent key size for security purposes.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const KEY_LENGTH = 32
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the derived key length in bytes for PBKDF2'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:KEY_LENGTH:constant"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:DIGEST:constant" type="constant" identity="DIGEST" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Defines the digest algorithm for PBKDF2"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stores the PBKDF2 digest algorithm"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Constant digest algorithm used by hashApiKey and verifyApiKey" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * DIGEST defines the hashing algorithm used for API key generation, specifically SHA-256. It provides a consistent and secure method for hashing within the module.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 const DIGEST = 'sha256'
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the digest algorithm for PBKDF2'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:DIGEST:constant"]
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:hashApiKey:function" type="function" identity="hashApiKey" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Hash a raw API key using PBKDF2 and return a storable key record"]
-// CIL[DOC-RESPONSIBILITY responsibility="Derive a salted PBKDF2 hash, prefix the raw key, and return a hash string"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="rawKey: string, iterations = ITERATIONS" outputs="{ key_prefix: string, key_hash: string, rawKey: string }" errors="none" side_effects="Uses crypto.randomBytes and pbkdf2Sync to generate salt and hash"]
-// CIL[DOC-MICRO logic_summary="Extracts an 8-character prefix, generates a random salt, derives a 32-byte PBKDF2 hash, and encodes the result as pbkdf2$iterations$salt$hash" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Hashes a raw API key using PBKDF2 to enhance security and returns the key prefix along with the hashed key. This function is essential for securely storing API keys.
+ *
+ * @inputSpec
+ *   - rawKey: string (required) — the raw API key to be hashed.
+ *   - iterations: number (optional) — the number of iterations for the PBKDF2 algorithm, defaults to ITERATIONS.
+ * @outputSpec  { key_prefix: string; key_hash: string; rawKey: string }
+ * @sideEffects none
+ * @stability   internal
+ * @calls       randomBytes, pbkdf2Sync
+ * @cil-generated
+ */
 export function hashApiKey(rawKey: string, iterations = ITERATIONS): { key_prefix: string; key_hash: string; rawKey: string } {
   const key_prefix = rawKey.slice(0, 8)
   const salt = randomBytes(16)
@@ -84,23 +138,37 @@ export function hashApiKey(rawKey: string, iterations = ITERATIONS): { key_prefi
 
   return { key_prefix, key_hash, rawKey }
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Hash a raw API key using PBKDF2 and return a storable key record'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:hashApiKey:function"]
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:verifyApiKey:function" type="function" identity="verifyApiKey" parent="~/.framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-MACRO purpose="Verify a raw API key against a stored PBKDF2 hash"]
-// CIL[DOC-RESPONSIBILITY responsibility="Parse the stored hash, re-derive the key, and compare hashes timing-safely"]
-// CIL[DOC-CONTEXT module="functions/_shared" layer="shared" related_files=".framework/functions/_shared/hash-api-key.ts"]
-// CIL[DOC-CONTRACT inputs="rawKey: string, keyHash: string" outputs="boolean" errors="Returns false for invalid format, missing parts, non-positive iterations, base64 decode errors, or mismatched lengths" side_effects="Uses crypto.pbkdf2Sync and timingSafeEqual"]
-// CIL[DOC-MICRO logic_summary="Validates the keyHash format, extracts iterations and salt, derives the hash with the stored length, and compares with timingSafeEqual" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Verifies an API key against a stored hash to ensure its validity. This function is essential for securing access to resources by validating the provided key.
+ *
+ * @inputSpec
+ *   - rawKey: string (required) — the API key to verify.
+ *   - keyHash: string (required) — the hashed representation of the API key.
+ * @outputSpec  boolean — returns true if the API key is valid, otherwise false.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       pbkdf2Sync, timingSafeEqual
+ * @cil-generated
+ */
 export function verifyApiKey(rawKey: string, keyHash: string): boolean {
   if (!keyHash || !keyHash.startsWith('pbkdf2$')) {
     return false
@@ -131,10 +199,46 @@ export function verifyApiKey(rawKey: string, keyHash: string): boolean {
     return false
   }
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Verify a raw API key against a stored PBKDF2 hash'; No verified external callers; imports: none"]
-// 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/hash-api-key.ts:verifyApiKey:function"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/hash-api-key.ts:omitSecretFields:function" type="function" identity="omitSecretFields" parent="~/.framework/functions/_shared/hash-api-key.ts"]
+/**
+ * The omitSecretFields function removes sensitive fields from an object to prevent exposure of secret information. It is designed to sanitize data before further processing or transmission.
+ *
+ * @inputSpec
+ *   row: Record<string, any> | null | undefined — the object from which secret fields will be omitted.
+ * @outputSpec  Record<string, any> | null | undefined — a new object without the omitted fields, or the original input if it was not an object.
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
+export function omitSecretFields(row: Record<string, any> | null | undefined) {
+  if (!row || typeof row !== 'object') return row
+  const copy = { ...row }
+  delete copy.key_value
+  delete copy.key_hash
+  return copy
+}
+// CIL[END stable_id="~/.framework/functions/_shared/hash-api-key.ts:omitSecretFields:function"]
+
+
+
+
+
+
+

package/.framework/functions/_shared/kb.ts

@@ -218,6 +218,43 @@ function getFieldValue(record: any, field: string): string {
   }
   return ''
 }
+
+const UUID_TOKEN_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi
+const HTML_TAG_RE = /<[^>]*>/g
+const HTML_LOOKS_LIKE_RE = /<\/?[a-z][^>]*>/i
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/kb.ts:getembeddablefieldvalue:function" type="function" identity="getEmbeddableFieldValue" parent="~/.framework/functions/_shared/kb.ts"]
+// CIL[DOC-MACRO purpose="Normalize a record field into embeddable plain text — strips rich-text HTML and bare UUID tokens"]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce the exact text that feeds both the content-hash lease and the embedder so neither markup nor identifier-only chunks enter the corpus"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="kb" related_files=".framework/functions/_shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="record: any, field: string, designSchema: any" outputs="string — normalized text, '' when nothing embeddable remains" errors="[]" side_effects="[]"]
+// CIL[DOC-MICRO logic_summary="rich_text fields (or any value containing tags) run through an HTML-to-text pass; every field then drops bare UUID tokens — reference-id arrays like tag item ids collapse to empty and are skipped" notable_decisions="applied uniformly to all vector fields so the content hash dedupes on the same text the embedder sees"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+function getEmbeddableFieldValue(record: any, field: string, designSchema: any): string {
+  let text = getFieldValue(record, field)
+  if (!text) return ''
+  const dataType = designSchema?.fields?.[field]?.data_type
+  if (dataType === 'rich_text' || HTML_LOOKS_LIKE_RE.test(text)) {
+    text = text
+      .replace(/<\/(p|div|h[1-6]|li|ul|ol|section|article|header|footer|blockquote|tr|table)>/gi, '\n')
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/<li[^>]*>/gi, '\n- ')
+      .replace(HTML_TAG_RE, ' ')
+      .replace(/&nbsp;/gi, ' ')
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#0?39;|&apos;/g, "'")
+  }
+  return text
+    .replace(UUID_TOKEN_RE, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+// CIL[END stable_id="~/.framework/functions/_shared/kb.ts:getembeddablefieldvalue:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Retrieves a flattened string value from a record or its data object.'; No verified external callers; imports: .framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.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"]
@@ -596,7 +633,7 @@ async function clearEmbeddingsForItem(documentId: string): Promise<number> {
 // CIL[DOC-RESPONSIBILITY responsibility="Processes a published KB item, chunks vector fields, and persists embeddings under a content-hash document lease."]
 // CIL[DOC-CONTEXT module="functions/_shared" layer="kb" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/kb.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/migrations/054_kb_ingest_lease.sql"]
 // CIL[DOC-CONTRACT inputs="ctx: CoreContext, body with id: string and optional account_id" outputs="ok: boolean; message: string; count?: number; in_progress?: boolean" errors="id is required; record not found; database errors" side_effects="revokes previous embeddings; inserts rows into embeddings table; acquires/releases a document_leases row; archives+revokes superseded documents"]
-// CIL[DOC-MICRO logic_summary="Fetches the item, validates status, hashes the declared vector-field values, acquires a document lease ('reused' skips unchanged work, 'processing' reports another worker owns it), then inside try/finally clears stale embeddings, batches chunks into one embeddings call, inserts, and runs supersede_keys-driven supersession before releasing the lease token." notable_decisions="Revokes existing embeddings via clearEmbeddingsForItem (not kbRevoke — that would delete the caller's own lease); supersession is driven by functionality.kb.supersede_keys declared data fields instead of a hardcoded type-slug gate; a fenced release (token mismatch) warns without throwing — the work was written but ownership was lost to a superseding acquire."]
+// CIL[DOC-MICRO logic_summary="Fetches the item, validates status, hashes the normalized vector-field values (rich_text HTML stripped, bare UUID tokens dropped), acquires a document lease ('reused' skips unchanged work, 'processing' reports another worker owns it), then inside try/finally clears stale embeddings, batches chunks into one embeddings call, inserts, and runs supersede_keys-driven supersession before releasing the lease token." notable_decisions="Revokes existing embeddings via clearEmbeddingsForItem (not kbRevoke — that would delete the caller's own lease); supersession is driven by functionality.kb.supersede_keys declared data fields instead of a hardcoded type-slug gate; a fenced release (token mismatch) warns without throwing — the work was written but ownership was lost to a superseding acquire."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="internal"]
 // CIL[DOC-NOTE type="contract" content="Lease outcomes: 'reused' returns a live-embeddings count so callers may stamp freshness; 'processing' returns in_progress:true with NO success marker — callers that stamp embedding state must not stamp success or failure for it, the owning worker's completion reconciles the corpus."]
@@ -660,11 +697,12 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
   const securityLevel = resolveSecurityLevel(designSchema)
 
   // Content-hash lease (document_leases, migration 054): sha256 over the
-  // declared vector-field values in order — the same text that feeds the
-  // embedder. The lease dedupes unchanged re-embeds and fences concurrent
-  // workers (publish trigger + detached ingest both arrive here).
+  // declared vector-field values in order — the same NORMALIZED text that
+  // feeds the embedder (HTML stripped, bare UUIDs dropped). The lease
+  // dedupes unchanged re-embeds and fences concurrent workers (publish
+  // trigger + detached ingest both arrive here).
   const contentHash = createHash('sha256')
-    .update(vectorFields.map((field: string) => getFieldValue(record, field)).join('\n'))
+    .update(vectorFields.map((field: string) => getEmbeddableFieldValue(record, field, designSchema)).join('\n'))
     .digest('hex')
 
   const { data: lease, error: leaseError } = await adminDb.rpc('acquire_document_lease', {
@@ -703,7 +741,7 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
 
     const toEmbed: Array<{ field: string; chunk: string }> = []
     for (const field of vectorFields) {
-      const raw = getFieldValue(record, field)
+      const raw = getEmbeddableFieldValue(record, field, designSchema)
       if (!raw.trim()) continue
 
       const isChunked = field === chunkField && raw.length > chunkSize
@@ -837,10 +875,26 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
  * @calls       clearEmbeddingsForItem, adminDb.from('document_leases').delete()
  * @cil-generated
  */
-export async function kbRevoke(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number }> {
+export async function kbRevoke(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number; skipped?: boolean }> {
   const { id } = body
   if (!id) throw new Error('id is required')
 
+  // Execution-time fence: a revoke queued by an intermediate
+  // item_updated event (e.g. auto_revoke_on_unpublish fired while a
+  // publish pipeline was mid-flight) executes long after the trigger
+  // condition was true. Re-check the document's CURRENT status — if it
+  // is published now, its embeddings are fresh and must be kept.
+  // Trigger-time evaluation is always stale by the time work runs.
+  const { data: doc } = await adminDb
+    .from('items')
+    .select('status, data')
+    .eq('id', id)
+    .maybeSingle()
+  const docStatus = doc?.status ?? doc?.data?.status
+  if (doc && docStatus === 'published') {
+    return { ok: true, skipped: true, message: 'document is published — embeddings retained', count: 0 }
+  }
+
   const count = await clearEmbeddingsForItem(id)
 
   // Clear any stored lease — a 'completed' lease would otherwise force