refactor(provenance): make reason the only locator, not one of two

Two fields had grown into competing answers to the same question. `origin` is a
free-form label for which importer accepted an already-incomplete bundle; four
latches had started passing `markIncomplete('unspecified', { origin })`, using it
to stand in for a reason that did not exist yet. That splits one fact across a
closed enum and an open string, leaving neither worth alerting on.

Give those four the literal they were reaching for — none needed a new one — and
split the five reasons that covered genuinely different guards, so the reason
alone locates the site rather than needing an origin beside it. `origin` keeps its
narrow job, now documented: it disambiguates importers that share one guard, and a
latch that wants an origin because no reason fits should add a reason instead.

No production call site passes 'unspecified' any more.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

apps/sim/executor/handlers/generic/generic-handler.ts

@@ -234,7 +234,7 @@ export class GenericBlockHandler implements BlockHandler {
               continue
             }
             if (boundary.requiredProjectionRoots.has(projection.path[0])) {
-              registry.markIncomplete('structural-input-projection-incomplete')
+              registry.markIncomplete('structural-input-root-unprojected')
             }
             continue
           }

apps/sim/executor/handlers/mothership/mothership-handler.ts

@@ -464,7 +464,7 @@ async function readMothershipExecuteResponse(
       result = (await response.json()) as MothershipExecuteResult
     } catch (error) {
       if (expectsProvenance) {
-        registry?.markIncomplete('mothership-provenance-invalid')
+        registry?.markIncomplete('mothership-response-unreadable')
         throw new Error('Mothership response provenance metadata is invalid')
       }
       throw error
@@ -948,7 +948,7 @@ export class MothershipBlockHandler implements BlockHandler {
           try {
             payload = (await response.clone().json()) as MothershipExecuteResult
           } catch {
-            resultRegistry?.markIncomplete('mothership-provenance-invalid')
+            resultRegistry?.markIncomplete('mothership-response-unreadable')
             throw new Error('Mothership response provenance metadata is invalid')
           }
           await consumeMothershipProvenance(payload, response, resultRegistry)

apps/sim/executor/utils/resolved-secret-trace-registry.test.ts

@@ -1449,7 +1449,10 @@ describe('incompleteness diagnostics', () => {
     'structural-input-projection-incomplete',
     'mothership-provenance-invalid',
     'client-tool-seal-failed',
+    'knowledge-row-missing',
     'knowledge-row-content-mismatch',
+    'mothership-response-unreadable',
+    'structural-input-root-unprojected',
     'backfill-scope-mismatch',
   ] as const)('reports %s at error, since it cannot trip on a healthy run', (reason) => {
     new ResolvedSecretTraceRegistry([], scope).markIncomplete(reason)
@@ -1463,8 +1466,11 @@ describe('incompleteness diagnostics', () => {
 
   it.each([
     'mothership-provenance-missing',
-    'client-tool-completion-unavailable',
+    'client-tool-completion-missing',
+    'client-tool-completion-deferred',
+    'client-tool-completion-unidentified',
     'client-tool-execution-untrusted',
+    'client-tool-content-unavailable',
     'knowledge-result-provenance-unavailable',
     'knowledge-response-capacity-exceeded',
     'memory-crossing-capacity-exceeded',

apps/sim/executor/utils/resolved-secret-trace-registry.ts

@@ -44,13 +44,19 @@ export type ResolvedSecretIncompletenessReason =
   | 'tool-input-not-enumerable'
   | 'tool-params-transform-failed'
   | 'structural-input-projection-incomplete'
+  | 'structural-input-root-unprojected'
   | 'mothership-provenance-invalid'
+  | 'mothership-response-unreadable'
   | 'mothership-provenance-missing'
   | 'client-tool-seal-failed'
-  | 'client-tool-completion-unavailable'
+  | 'client-tool-completion-missing'
+  | 'client-tool-completion-deferred'
+  | 'client-tool-completion-unidentified'
   | 'client-tool-execution-untrusted'
+  | 'client-tool-content-unavailable'
   | 'knowledge-result-provenance-unavailable'
   | 'knowledge-response-capacity-exceeded'
+  | 'knowledge-row-missing'
   | 'knowledge-row-content-mismatch'
   | 'memory-crossing-capacity-exceeded'
   | 'workspace-scope-missing'
@@ -95,7 +101,10 @@ const ORIGINATING_FAULT_REASONS = new Set<ResolvedSecretIncompletenessReason>([
   'structural-input-projection-incomplete',
   'mothership-provenance-invalid',
   'client-tool-seal-failed',
+  'knowledge-row-missing',
   'knowledge-row-content-mismatch',
+  'mothership-response-unreadable',
+  'structural-input-root-unprojected',
   'backfill-scope-mismatch',
 ])
 
@@ -219,6 +228,16 @@ type PreparedProvenanceFilterResult =
 /** Extra attribution for a latch: which registry it propagated from, and which importer caused it. */
 interface MarkIncompleteContext {
   source?: ResolvedSecretTraceRegistry
+  /**
+   * Which importer accepted an already-incomplete bundle — only meaningful where several callers
+   * share one guard, as {@link ImportResolvedSecretTraceProvenanceOptions.origin} describes.
+   *
+   * It is not a second way to say what `reason` says. A latch that reaches for an origin because no
+   * reason fits is the signal to add a reason literal instead: `reason` is a closed set that can be
+   * alerted on and aggregated, and splitting the same fact across two fields leaves neither
+   * trustworthy. Passing `'unspecified'` alongside an origin is the shape that produced a
+   * production latch naming no guard at all.
+   */
   origin?: string
 }
 

apps/sim/lib/copilot/request/tools/client.ts

@@ -116,7 +116,9 @@ export async function waitForClientToolCompletion({
       }
     }
   } catch {
-    toolRegistry?.markIncomplete('unspecified', { origin: 'copilotToolClient.sealedContext' })
+    toolRegistry?.markIncomplete('client-tool-seal-failed', {
+      origin: 'copilotToolClient.sealedContext',
+    })
   } finally {
     finishPendingActivation?.()
   }
@@ -243,18 +245,18 @@ export async function waitForWorkflowToolCompletion({
   try {
     completion = await waitForToolCompletion(toolCallId, timeoutMs, abortSignal)
     if (!completion) {
-      toolRegistry?.markIncomplete('client-tool-completion-unavailable')
+      toolRegistry?.markIncomplete('client-tool-completion-missing')
       return null
     }
 
     const executionId = getWorkflowToolCompletionExecutionId(completion.data)
     const deploymentError = getAsyncWorkflowDeploymentError(completion.data)
     if (completion.status === ASYNC_TOOL_CONFIRMATION_STATUS.background) {
-      toolRegistry?.markIncomplete('client-tool-completion-unavailable')
+      toolRegistry?.markIncomplete('client-tool-completion-deferred')
       return structuralWorkflowCompletion(completion.status, workflowId, executionId)
     }
     if (!workflowId || !executionId) {
-      toolRegistry?.markIncomplete('client-tool-completion-unavailable')
+      toolRegistry?.markIncomplete('client-tool-completion-unidentified')
       const structuralStatus =
         completion.status === MothershipStreamV1ToolOutcome.success
           ? MothershipStreamV1ToolOutcome.error
@@ -284,7 +286,7 @@ export async function waitForWorkflowToolCompletion({
     }
 
     if (!trustedExecution.contentAvailable) {
-      toolRegistry?.markIncomplete('client-tool-execution-untrusted')
+      toolRegistry?.markIncomplete('client-tool-content-unavailable')
       return structuralWorkflowCompletion(
         getWorkflowToolConfirmationStatus(trustedExecution.status),
         workflowId,

apps/sim/lib/copilot/tools/handlers/function-execute.ts

@@ -539,7 +539,7 @@ export async function resolveInputFiles(
           })
         }
       } catch {
-        resolvedSecretTraceRegistry.markIncomplete('unspecified', {
+        resolvedSecretTraceRegistry.markIncomplete('source-provenance-incomplete', {
           origin: 'copilotFunctionExecute.result',
         })
       }
@@ -573,9 +573,13 @@ async function importMountedProvenance(
       trusted: true,
     })
     if (!imported)
-      target.markIncomplete('unspecified', { origin: 'copilotFunctionExecute.crossing' })
+      target.markIncomplete('value-provenance-import-failed', {
+        origin: 'copilotFunctionExecute.crossing',
+      })
   } catch {
-    target.markIncomplete('unspecified', { origin: 'copilotFunctionExecute.crossing' })
+    target.markIncomplete('value-provenance-import-failed', {
+      origin: 'copilotFunctionExecute.crossing',
+    })
   }
 }
 

apps/sim/lib/knowledge/secret-provenance.ts

@@ -480,14 +480,14 @@ export async function importKnowledgePersistedResponseSecretProvenance(options:
   const documentById = new Map(documentRows.map((row) => [row.id, row]))
   const chunkById = new Map(chunkRows.map((row) => [row.id, row]))
   if (documentById.size !== documentIds.length || chunkById.size !== chunkIds.length) {
-    options.registry.markIncomplete('knowledge-row-content-mismatch')
+    options.registry.markIncomplete('knowledge-row-missing')
     return false
   }
 
   for (const item of documents) {
     const row = documentById.get(item.id)
     if (!row) {
-      options.registry.markIncomplete('knowledge-row-content-mismatch')
+      options.registry.markIncomplete('knowledge-row-missing')
       return false
     }
     const source = createKnowledgeDocumentSourceValue(row)