improvement(provenance): name every guard that can latch a registry (#6513)

* fix(provenance): name every guard that can latch a registry

A production latch reported `reason: "unspecified"` because 44 call sites took
the default. The reason is the only thing that names which guard tripped, and a
refusal surfaces many frames later as one fixed sentence, so an unnamed latch is
undiagnosable — that is what left an incident's origin unidentified for a day.

Give each call site a literal that names its guard, add the 20 new literals to
the reason union, and sort them into the existing error/warn split: a guard that
should not trip on a healthy run reports at error, everything else stays at warn.
`log-creation-skipped` joins the by-design set since it fires on every run that
does not persist a log.

Make `reason` required on both `markIncomplete` and `markInputPathIncomplete`, so
omission is a compile error rather than a silent `unspecified`. A caller with
genuinely nothing to say now passes `'unspecified'` where a reviewer can see it.

The three remaining bare calls are on ResolvedSecretTraceProvenanceAccumulator,
a different class with no reason concept.

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

* test(provenance): pin the new reasons and the guard that latched in production

Cover what the reason set is for rather than only that it compiles: the
non-enumerable tool-params branch now asserts it names `tool-input-not-enumerable`,
which is the guard the production logs showed reporting `unspecified`, and every
new literal asserts which stream it reports on — error for a guard that cannot
trip on a healthy run, warn for one reachable without a fault, silent for the
by-design log-less session.

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

* 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>

* fix(provenance): stop two expected states from reporting as faults

Cursor Bugbot caught `backfill-checkpoint-*`: the guard covered four conditions
under one reason classified as an originating fault, and one of them — a state
persisted before the checkpoint contract existed — is what essentially every
legacy row looks like. A backfill over historical rows would have put one error
line per row into the stream the error/warn split exists to protect.

Auditing the rest of the error-level reasons for the same shape found a second:
a client tool invoked without a run id has no binding to unseal against, so it
took the `[null, null]` path and reported `client-tool-seal-failed` at error on an
ordinary configuration.

Split both along the line that matters — absent versus unusable, not attempted
versus failed — and classify each half: expected states warn, genuine faults keep
error. `backfill-scope-mismatch` is retired; it named one of its four conditions.

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

---------

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

Author: icecrasher321

apps/sim/app/api/knowledge/search/route.ts

@@ -381,7 +381,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       results,
     })
     if (!resultProvenanceSnapshot.imported) {
-      resultSecretRegistry.markIncomplete()
+      resultSecretRegistry.markIncomplete('knowledge-result-provenance-unavailable')
       if (useReranker) {
         return NextResponse.json(
           { error: 'Knowledge result secret provenance is unavailable' },
@@ -608,7 +608,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           'knowledge'
         ))
       ) {
-        resultSecretRegistry.markIncomplete()
+        resultSecretRegistry.markIncomplete('knowledge-result-provenance-unavailable')
       }
     }
 

apps/sim/app/api/knowledge/secret-provenance.ts

@@ -154,7 +154,7 @@ export async function createKnowledgeProvenanceResponse(options: {
   })
   for (const provenance of options.provenances) {
     if (provenance.status === 'unknown') {
-      registry.markIncomplete()
+      registry.markIncomplete('durable-provenance-unknown')
       break
     }
     const sourceRegistry = await createDurableSecretProvenanceRegistry(provenance, {

apps/sim/app/api/memory/secret-provenance.ts

@@ -98,7 +98,7 @@ export async function createMemoryResponse(options: {
     workspaceId: options.workspaceId,
   })
   if (options.memories.length > MAX_PRIVATE_MEMORY_CROSSINGS) {
-    registry.markIncomplete()
+    registry.markIncomplete('memory-crossing-capacity-exceeded')
   } else {
     const ids = [...new Set(options.memories.map((record) => record.id))]
     const memoriesById = new Map<string, MemoryCrossing[]>()
@@ -123,7 +123,7 @@ export async function createMemoryResponse(options: {
         provenanceEntryCount > MAX_PRIVATE_MEMORY_PROVENANCE_ENTRIES ||
         provenanceBytes > MAX_PRIVATE_MEMORY_PROVENANCE_BYTES
       ) {
-        registry.markIncomplete()
+        registry.markIncomplete('memory-crossing-capacity-exceeded')
         break
       }
       const sidecarById = new Map(sidecars.map((sidecar) => [sidecar.memoryId, sidecar]))

apps/sim/app/api/workflows/[id]/log/route.ts

@@ -142,7 +142,7 @@ export const POST = withRouteHandler(
             : undefined
         const trustedProvenance = trustedExecutionState?.resolvedSecretTraceProvenance
         if (trustedProvenance === undefined) {
-          resolvedSecretTraceRegistry.markIncomplete()
+          resolvedSecretTraceRegistry.markIncomplete('restored-provenance-untrusted')
         } else {
           await resolvedSecretTraceRegistry.importProvenance(trustedProvenance, {
             trusted: true,

apps/sim/executor/handlers/agent/memory.test.ts

@@ -278,7 +278,7 @@ describe('Memory', () => {
 
     it('persists raw memory with unknown lineage when provenance is unavailable', async () => {
       const registry = new ResolvedSecretTraceRegistry()
-      registry.markIncomplete()
+      registry.markIncomplete('unspecified')
       const appendMessage = vi
         .spyOn(memoryService as any, 'appendMessage')
         .mockResolvedValue(undefined)
@@ -293,7 +293,7 @@ describe('Memory', () => {
 
     it('seeds raw memory with unknown lineage when provenance is unavailable', async () => {
       const registry = new ResolvedSecretTraceRegistry()
-      registry.markIncomplete()
+      registry.markIncomplete('unspecified')
       const seedMemoryRecord = vi
         .spyOn(memoryService as any, 'seedMemoryRecord')
         .mockResolvedValue(undefined)

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

@@ -199,7 +199,8 @@ export class GenericBlockHandler implements BlockHandler {
         boundary && boundary.paths.length > 0 && registry?.hasResolvedInputProjections()
           ? registry.projectResolvedInputSelections(inputs)
           : undefined
-      if (projectedInputs?.complete === false) registry?.markIncomplete()
+      if (projectedInputs?.complete === false)
+        registry?.markIncomplete('structural-input-projection-incomplete')
 
       if (projectedInputs?.complete && boundary && tool && registry) {
         for (const projection of projectedInputs.values) {
@@ -233,7 +234,7 @@ export class GenericBlockHandler implements BlockHandler {
               continue
             }
             if (boundary.requiredProjectionRoots.has(projection.path[0])) {
-              registry.markIncomplete()
+              registry.markIncomplete('structural-input-root-unprojected')
             }
             continue
           }

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

@@ -372,7 +372,7 @@ async function consumeMothershipProvenance(
     return false
   }
   if (inspection.status === 'invalid') {
-    registry?.markIncomplete()
+    registry?.markIncomplete('mothership-provenance-invalid')
     throw new Error('Mothership response provenance metadata is invalid')
   }
 
@@ -399,7 +399,7 @@ function inspectMothershipResponseCapability(
     return false
   }
 
-  registry?.markIncomplete()
+  registry?.markIncomplete('mothership-provenance-invalid')
   throw new Error('Mothership response provenance metadata is invalid')
 }
 
@@ -464,7 +464,7 @@ async function readMothershipExecuteResponse(
       result = (await response.json()) as MothershipExecuteResult
     } catch (error) {
       if (expectsProvenance) {
-        registry?.markIncomplete()
+        registry?.markIncomplete('mothership-response-unreadable')
         throw new Error('Mothership response provenance metadata is invalid')
       }
       throw error
@@ -528,7 +528,7 @@ async function readMothershipExecuteResponse(
     return finalResult
   } finally {
     if (expectsProvenance && !finalResult && !receivedTerminalProvenance) {
-      registry?.markIncomplete()
+      registry?.markIncomplete('mothership-provenance-missing')
     }
     reader.releaseLock()
   }
@@ -630,7 +630,7 @@ function createMothershipStreamingExecution(
         }
       } finally {
         if (expectsProvenance && !sawFinal && !receivedTerminalProvenance) {
-          options.registry?.markIncomplete()
+          options.registry?.markIncomplete('mothership-provenance-missing')
         }
         cleanup()
         reader?.releaseLock()
@@ -948,7 +948,7 @@ export class MothershipBlockHandler implements BlockHandler {
           try {
             payload = (await response.clone().json()) as MothershipExecuteResult
           } catch {
-            resultRegistry?.markIncomplete()
+            resultRegistry?.markIncomplete('mothership-response-unreadable')
             throw new Error('Mothership response provenance metadata is invalid')
           }
           await consumeMothershipProvenance(payload, response, resultRegistry)

apps/sim/executor/handlers/pi/local/sim-tools.test.ts

@@ -320,7 +320,7 @@ describe('buildSimToolSpecs', () => {
       output: { result: 'untrusted output' },
     })
     const registry = new ResolvedSecretTraceRegistry()
-    registry.markIncomplete()
+    registry.markIncomplete('unspecified')
     const [spec] = await buildSimToolSpecs(executionContext(registry), toolInput)
 
     const result = await spec.execute({})

apps/sim/executor/handlers/pi/pi-handler.test.ts

@@ -227,7 +227,7 @@ describe('PiBlockHandler', () => {
 
   it('fails closed when task provenance is incomplete', async () => {
     const registry = new ResolvedSecretTraceRegistry()
-    registry.markIncomplete()
+    registry.markIncomplete('unspecified')
 
     await expect(
       handler.execute(

apps/sim/executor/handlers/pi/search/tool.test.ts

@@ -288,7 +288,7 @@ describe('buildPiSearchToolSpec', () => {
 
   it('fails closed before search when provenance is incomplete', async () => {
     const registry = new ResolvedSecretTraceRegistry()
-    registry.markIncomplete()
+    registry.markIncomplete('unspecified')
 
     const result = await buildTool('exa', executionContext(registry)).execute({ query: 'pi' })
 
@@ -303,7 +303,7 @@ describe('buildPiSearchToolSpec', () => {
     const registry = new ResolvedSecretTraceRegistry()
     const mergeSpy = vi.spyOn(registry, 'mergeToolCallRegistry')
     mockExecuteTool.mockImplementation(async (_toolId, _params, options) => {
-      options.resolvedSecretTraceRegistry.markIncomplete()
+      options.resolvedSecretTraceRegistry.markIncomplete('unspecified')
       return {
         success: true,
         output: {