@gakim-digital/dexter-bridge 0.11.4 → 0.11.6

package/src/framerBehaviorContract.js

@@ -24,6 +24,7 @@ export const BEHAVIOR_LAYOUT_EFFECTS = [
 ];
 
 export const BEHAVIOR_MECHANISMS = [
+  'native_link',
   'native_event',
   'native_effect',
   'native_overlay',
@@ -33,6 +34,14 @@ export const BEHAVIOR_MECHANISMS = [
 ];
 
 const MECHANISM_CAPABILITIES = {
+  native_link: {
+    activations: new Set(['tap', 'key']),
+    presentations: new Set(['navigation']),
+    layoutEffects: new Set(['navigation']),
+    stateChange: false,
+    reversible: false,
+    repeatable: true,
+  },
   native_event: {
     activations: new Set(['tap', 'hover', 'appear', 'key']),
     presentations: new Set(['none', 'navigation']),
@@ -147,6 +156,7 @@ export function behaviorSignature(behavior) {
       expectedTargets: behavior.expectedTargets,
       initialState: behavior.initialState,
       activatedState: behavior.activatedState,
+      expectedDestinations: behavior.expectedDestinations,
     }))
     .digest('hex');
 }
@@ -193,9 +203,20 @@ function normalizeBehavior(rawBehavior, index) {
     repeatable: rawBehavior.repeatable === true,
     expectedTargets: integer(rawBehavior.expectedTargets),
     expectedContent: uniqueStrings(rawBehavior.expectedContent, 20),
+    expectedDestinations: uniqueStrings(rawBehavior.expectedDestinations, 20),
     initialState,
     activatedState,
   };
+  if (
+    (behavior.presentation === 'navigation'
+      || behavior.layoutEffect === 'navigation')
+    && behavior.expectedDestinations.length === 0
+  ) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_CONTRACT_INVALID',
+      `Behavior ${index + 1} must declare expectedDestinations for navigation.`,
+    );
+  }
   return {
     ...behavior,
     signature: behaviorSignature(behavior),
@@ -227,6 +248,11 @@ function normalizeMechanism(rawMechanism, index) {
     mechanism,
     rationale,
     representativeFirst: rawMechanism.representativeFirst !== false,
+    targetNodeIds: uniqueStrings(rawMechanism.targetNodeIds, 50),
+    representativeTargetNodeId: text(
+      rawMechanism.representativeTargetNodeId,
+      200,
+    ),
   };
 }
 
@@ -333,6 +359,21 @@ export function normalizeBehaviorPlan(rawArguments, inheritedRejected = []) {
         `Behavior "${decision.behaviorId}" has more than one selected mechanism.`,
       );
     }
+    const behavior = behaviors.find((item) => item.id === decision.behaviorId);
+    if (
+      behavior?.expectedTargets > 1
+      && decision.representativeFirst
+      && (
+        decision.targetNodeIds.length !== behavior.expectedTargets
+        || !decision.representativeTargetNodeId
+        || !decision.targetNodeIds.includes(decision.representativeTargetNodeId)
+      )
+    ) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_REPRESENTATIVE_TARGETS_REQUIRED',
+        `Repeated behavior "${decision.behaviorId}" must declare all targetNodeIds and one representativeTargetNodeId before mutation.`,
+      );
+    }
     mechanismByBehavior.set(decision.behaviorId, decision);
   }
   const compatibility = behaviors.map((behavior) => {
@@ -520,9 +561,19 @@ function referencesComponent(snapshot, componentNodeId) {
 function nodeVisible(snapshot) {
   const node = nodeFromSnapshot(snapshot);
   if (!node) return null;
-  if (node.visible === false || node.hidden === true) return false;
-  if (node.visible === true || node.hidden === false) return true;
-  return true;
+  const visible = Object.prototype.hasOwnProperty.call(node, 'visible')
+    ? node.visible
+    : isRecord(node.attributes)
+      ? node.attributes.visible
+      : undefined;
+  const hidden = Object.prototype.hasOwnProperty.call(node, 'hidden')
+    ? node.hidden
+    : isRecord(node.attributes)
+      ? node.attributes.hidden
+      : undefined;
+  if (visible === false || hidden === true) return false;
+  if (visible === true || hidden === false) return true;
+  return null;
 }
 
 function eventText(snapshot, event) {
@@ -570,11 +621,24 @@ function normalizeEvidence(raw, behaviorById) {
       `Interaction evidence references unknown behavior "${behaviorId}".`,
     );
   }
+  const expectedDestination = text(raw.expectedDestination, 500);
+  if (
+    expectedDestination
+    && !behavior.expectedDestinations.some((planned) =>
+      destinationCandidates(planned).some((candidate) =>
+        destinationCandidates(expectedDestination).includes(candidate)))
+  ) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_EVIDENCE_INVALID',
+      `Interaction evidence for "${behaviorId}" must use a destination declared in the behavior plan.`,
+    );
+  }
   return {
     behaviorId,
     description: text(raw.description, 300),
     triggerNodeId: text(raw.triggerNodeId, 200),
     event: text(raw.event, 80),
+    expectedDestination,
     targetNodeId: text(raw.targetNodeId, 200),
     componentNodeId: text(raw.componentNodeId, 200),
     instanceNodeIds: uniqueStrings(raw.instanceNodeIds, 50),
@@ -582,6 +646,19 @@ function normalizeEvidence(raw, behaviorById) {
     closedVariantNodeId: text(raw.closedVariantNodeId, 200),
     openAnswerNodeId: text(raw.openAnswerNodeId, 200),
     closedAnswerNodeId: text(raw.closedAnswerNodeId, 200),
+    semanticAssessment: isRecord(raw.semanticAssessment)
+      && ['verified', 'contradicted', 'unknown']
+        .includes(raw.semanticAssessment.verdict)
+      && text(raw.semanticAssessment.rationale, 1200).length >= 10
+      ? {
+          verdict: raw.semanticAssessment.verdict,
+          rationale: text(raw.semanticAssessment.rationale, 1200),
+          evidenceNodeIds: uniqueStrings(
+            raw.semanticAssessment.evidenceNodeIds,
+            50,
+          ),
+        }
+      : null,
   };
 }
 
@@ -612,94 +689,154 @@ export function evidenceNodeIds(checks) {
   ]), 200);
 }
 
-function verifyTrigger(check, behavior, trigger, failures) {
+function evidenceState() {
+  return {
+    contradictions: [],
+    unknowns: [],
+    observations: [],
+  };
+}
+
+function contradict(state, message) {
+  state.contradictions.push(message);
+}
+
+function unknown(state, message) {
+  state.unknowns.push(message);
+}
+
+function observe(state, kind, detail = {}) {
+  state.observations.push({ kind, ...detail });
+}
+
+function verifyTrigger(check, behavior, trigger, state) {
   if (!check.triggerNodeId || !trigger) {
-    failures.push('trigger node was not found');
+    unknown(state, 'trigger node was not found');
     return '';
   }
+  observe(state, 'node_found', {
+    nodeId: check.triggerNodeId,
+    nodeType: nodeType(trigger),
+  });
   const allowedEvents = expectedEvents(behavior.activation);
   if (
     allowedEvents.length > 0
     && !allowedEvents.includes(check.event)
   ) {
-    failures.push(
+    contradict(
+      state,
       `${check.event || 'the supplied event'} does not match ${behavior.activation} activation`,
     );
   }
   if (!check.event) {
-    failures.push('the trigger event was not supplied');
+    unknown(state, 'the trigger event was not supplied');
     return '';
   }
   if (!FRAME_EVENT_NODE_TYPES.has(nodeType(trigger))) {
-    failures.push(`${nodeType(trigger) || 'the trigger node'} does not support verified frame events`);
+    contradict(
+      state,
+      `${nodeType(trigger) || 'the trigger node'} does not support verified frame events`,
+    );
   }
   const evidence = eventText(trigger, check.event);
-  if (!evidence) failures.push(`${check.event} is not configured on the trigger`);
+  if (!evidence) {
+    unknown(state, `${check.event} was not visible in the serialized trigger`);
+  } else {
+    observe(state, 'event_binding', {
+      nodeId: check.triggerNodeId,
+      event: check.event,
+      value: evidence.slice(0, 1000),
+    });
+  }
   return evidence;
 }
 
-function verifyExpectedContent(behavior, snapshots, nodeIds, failures) {
+function verifyExpectedContent(behavior, snapshots, nodeIds, state) {
   const combined = normalizedEvidenceText(
     nodeIds.map((id) => nodeFromSnapshot(snapshotFor(snapshots, id))),
   );
   for (const expected of behavior.expectedContent) {
     if (!combined.includes(expected.toLowerCase())) {
-      failures.push(`expected content was not found: ${expected}`);
+      unknown(state, `expected content was not visible in the evidence: ${expected}`);
+    } else {
+      observe(state, 'expected_content', { value: expected });
     }
   }
 }
 
-function verifyOverlay(check, behavior, snapshots, failures) {
+function verifyOverlay(check, behavior, snapshots, state) {
   const trigger = snapshotFor(snapshots, check.triggerNodeId);
   const target = snapshotFor(snapshots, check.targetNodeId);
-  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
+  const triggerEvent = verifyTrigger(check, behavior, trigger, state);
   if (!check.targetNodeId || !target) {
-    failures.push('overlay target node was not found');
+    unknown(state, 'overlay target node was not found');
     return;
   }
-  if (!triggerEvent.includes('show_overlay')) {
-    failures.push(`${check.event} does not contain SHOW_OVERLAY`);
+  observe(state, 'node_found', {
+    nodeId: check.targetNodeId,
+    nodeType: nodeType(target),
+  });
+  if (triggerEvent && !triggerEvent.includes('show_overlay')) {
+    contradict(state, `${check.event} does not contain SHOW_OVERLAY`);
   }
-  if (!triggerEvent.includes(check.targetNodeId.toLowerCase())) {
-    failures.push(`${check.event} does not reference target ${check.targetNodeId}`);
+  if (
+    triggerEvent
+    && !triggerEvent.includes(check.targetNodeId.toLowerCase())
+  ) {
+    contradict(state, `${check.event} does not reference target ${check.targetNodeId}`);
   }
   const expectedType =
     behavior.presentation === 'modal'
       ? 'FixedOverlayNode'
       : 'RelativeOverlayNode';
   if (nodeType(target) !== expectedType) {
-    failures.push(`the behavior requires a ${expectedType}`);
+    contradict(state, `the behavior requires a ${expectedType}`);
   }
-  if (parentId(target) !== check.triggerNodeId) {
-    failures.push('the overlay is not parented to its actual trigger');
+  const actualParentId = parentId(target);
+  if (!actualParentId) {
+    unknown(state, 'the overlay parent was not visible in the evidence');
+  } else if (actualParentId !== check.triggerNodeId) {
+    contradict(state, 'the overlay is not parented to its actual trigger');
   }
-  verifyExpectedContent(behavior, snapshots, [check.targetNodeId], failures);
+  verifyExpectedContent(behavior, snapshots, [check.targetNodeId], state);
 }
 
 function verifyComponentInstances(
   check,
   behavior,
   snapshots,
-  failures,
+  state,
   context,
   { requireDefinition = true } = {},
 ) {
   const component = snapshotFor(snapshots, check.componentNodeId);
-  if (
+  if (requireDefinition && !component) {
+    unknown(state, 'component definition was not found');
+  } else if (
     requireDefinition
-    && (!component || nodeType(component) !== 'ComponentNode')
+    && nodeType(component) !== 'ComponentNode'
   ) {
-    failures.push('component definition was not found');
+    contradict(state, 'the declared component definition is not a ComponentNode');
   }
   const instances = check.instanceNodeIds.map((id) => ({
     id,
     snapshot: snapshotFor(snapshots, id),
   }));
   for (const instance of instances) {
-    if (!instance.snapshot || nodeType(instance.snapshot) !== 'ComponentInstanceNode') {
-      failures.push(`component instance ${instance.id} was not found`);
+    if (!instance.snapshot) {
+      unknown(state, `component instance ${instance.id} was not found`);
+    } else if (nodeType(instance.snapshot) !== 'ComponentInstanceNode') {
+      contradict(state, `${instance.id} is not a ComponentInstanceNode`);
     } else if (!referencesComponent(instance.snapshot, check.componentNodeId)) {
-      failures.push(`component instance ${instance.id} does not reference ${check.componentNodeId}`);
+      contradict(
+        state,
+        `component instance ${instance.id} does not reference ${check.componentNodeId}`,
+      );
+    } else {
+      observe(state, 'component_instance', {
+        nodeId: instance.id,
+        componentNodeId: check.componentNodeId,
+      });
     }
     const authorizedContainerIds = uniqueStrings(
       context?.authorizedInstanceContainerIds,
@@ -714,7 +851,8 @@ function verifyComponentInstances(
           : []),
       ].filter(Boolean));
       if (!authorizedContainerIds.some((id) => ancestry.has(id))) {
-        failures.push(
+        contradict(
+          state,
           `component instance ${instance.id} is outside the authorized write scope`,
         );
       }
@@ -726,7 +864,7 @@ function verifyComponentVariants(
   check,
   behavior,
   snapshots,
-  failures,
+  state,
   context,
 ) {
   const trigger = snapshotFor(snapshots, check.triggerNodeId);
@@ -735,27 +873,28 @@ function verifyComponentVariants(
   const closedVariant = snapshotFor(snapshots, check.closedVariantNodeId);
   const openAnswer = snapshotFor(snapshots, check.openAnswerNodeId);
   const closedAnswer = snapshotFor(snapshots, check.closedAnswerNodeId);
-  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
-  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  const triggerEvent = verifyTrigger(check, behavior, trigger, state);
+  verifyComponentInstances(check, behavior, snapshots, state, context);
   if (component && trigger && !belongsTo(trigger, check.componentNodeId)) {
-    failures.push('the trigger is not inside the component definition');
+    contradict(state, 'the trigger is not inside the component definition');
   }
   if (
     !openVariant
     || !closedVariant
-    || check.openVariantNodeId === check.closedVariantNodeId
   ) {
-    failures.push('distinct open and closed variants were not found');
+    unknown(state, 'open and closed variants were not both found');
+  } else if (check.openVariantNodeId === check.closedVariantNodeId) {
+    contradict(state, 'open and closed variants must be distinct');
   } else {
     if (!belongsTo(openVariant, check.componentNodeId)) {
-      failures.push('the open variant does not belong to the component');
+      contradict(state, 'the open variant does not belong to the component');
     }
     if (!belongsTo(closedVariant, check.componentNodeId)) {
-      failures.push('the closed variant does not belong to the component');
+      contradict(state, 'the closed variant does not belong to the component');
     }
   }
-  if (!triggerEvent.includes('set_variant')) {
-    failures.push(`${check.event} does not contain SET_VARIANT`);
+  if (triggerEvent && !triggerEvent.includes('set_variant')) {
+    contradict(state, `${check.event} does not contain SET_VARIANT`);
   }
   if (
     triggerEvent
@@ -763,44 +902,167 @@ function verifyComponentVariants(
     && !triggerEvent.includes(check.openVariantNodeId.toLowerCase())
     && !triggerEvent.includes(check.closedVariantNodeId.toLowerCase())
   ) {
-    failures.push('SET_VARIANT does not reference cycle or a declared variant');
+    contradict(state, 'SET_VARIANT does not reference cycle or a declared variant');
   }
   if (!openAnswer || !closedAnswer) {
-    failures.push('open and closed answer-state nodes were not found');
+    unknown(state, 'open and closed answer-state nodes were not found');
   } else {
     if (!belongsTo(openAnswer, check.openVariantNodeId)) {
-      failures.push('the visible answer does not belong to the open variant');
+      contradict(state, 'the visible answer does not belong to the open variant');
     }
     if (!belongsTo(closedAnswer, check.closedVariantNodeId)) {
-      failures.push('the hidden answer does not belong to the closed variant');
+      contradict(state, 'the hidden answer does not belong to the closed variant');
     }
-    if (nodeVisible(openAnswer) === false) {
-      failures.push('the answer is hidden in the open variant');
+    const openVisibility = nodeVisible(openAnswer);
+    const closedVisibility = nodeVisible(closedAnswer);
+    observe(state, 'visibility', {
+      nodeId: check.openAnswerNodeId,
+      value:
+        openVisibility === null
+          ? 'unknown'
+          : openVisibility
+            ? 'visible'
+            : 'hidden',
+    });
+    observe(state, 'visibility', {
+      nodeId: check.closedAnswerNodeId,
+      value:
+        closedVisibility === null
+          ? 'unknown'
+          : closedVisibility
+            ? 'visible'
+            : 'hidden',
+    });
+    if (openVisibility === false) {
+      contradict(state, 'the answer is hidden in the open variant');
+    } else if (openVisibility === null) {
+      unknown(state, 'the open answer visibility was not exposed');
     }
-    if (nodeVisible(closedAnswer) !== false) {
-      failures.push('the answer is not hidden in the closed variant');
+    if (closedVisibility === true) {
+      contradict(state, 'the answer is not hidden in the closed variant');
+    } else if (closedVisibility === null) {
+      unknown(state, 'the closed answer visibility was not exposed');
     }
   }
-  verifyExpectedContent(
-    behavior,
-    snapshots,
-    [check.openAnswerNodeId, check.closedAnswerNodeId],
-    failures,
-  );
+}
+
+function destinationCandidates(value) {
+  const candidate = text(value, 2000);
+  if (!candidate) return [];
+  const normalized = candidate.toLowerCase().replace(/\/+$/, '') || '/';
+  const candidates = new Set([normalized]);
+  try {
+    const parsed = new URL(candidate, 'https://dexter.local');
+    candidates.add(
+      `${parsed.pathname}${parsed.search}${parsed.hash}`
+        .toLowerCase()
+        .replace(/\/+$/, '') || '/',
+    );
+  } catch {
+    // Non-URL control values are ignored unless the raw value matches.
+  }
+  return [...candidates];
+}
+
+function linkFacts(value) {
+  const facts = [];
+  const visit = (current, path = []) => {
+    if (Array.isArray(current)) {
+      current.forEach((nested, index) => visit(nested, [...path, String(index)]));
+      return;
+    }
+    if (!isRecord(current)) return;
+    for (const [key, nested] of Object.entries(current)) {
+      const nextPath = [...path, key];
+      if (
+        typeof nested === 'string'
+        && /(?:href|url|link|destination|route|path)$/i.test(key)
+      ) {
+        facts.push({
+          path: nextPath.join('.'),
+          value: nested,
+          candidates: destinationCandidates(nested),
+        });
+      }
+      visit(nested, nextPath);
+    }
+  };
+  visit(value);
+  return facts.filter((fact) => fact.candidates.length > 0);
+}
+
+function verifyNativeLink(check, behavior, snapshots, state, context) {
+  const targetIds = check.instanceNodeIds.length > 0
+    ? check.instanceNodeIds
+    : [check.triggerNodeId].filter(Boolean);
+  const expectedValues = check.expectedDestination
+    ? [check.expectedDestination]
+    : behavior.expectedDestinations;
+  const expected = new Set(expectedValues.flatMap(destinationCandidates));
+  if (targetIds.length === 0) {
+    unknown(state, 'no navigation target node was supplied');
+    return;
+  }
+  for (const nodeId of targetIds) {
+    const snapshot = snapshotFor(snapshots, nodeId);
+    if (!snapshot) {
+      unknown(state, `navigation node ${nodeId} was not found`);
+      continue;
+    }
+    const facts = linkFacts([
+      nodeFromSnapshot(snapshot),
+      snapshot?.controls,
+    ]);
+    if (facts.length === 0) {
+      const controlFacts = linkFacts(context?.componentControls);
+      if (controlFacts.length > 0) {
+        observe(state, 'component_link_control_available', {
+          nodeId,
+          sources: controlFacts.map((fact) => fact.path).slice(0, 20),
+        });
+      }
+      unknown(
+        state,
+        `no native link or component-control destination was visible for ${nodeId}`,
+      );
+      continue;
+    }
+    const matchingFact = facts.find((fact) =>
+      fact.candidates.some((candidate) => expected.has(candidate)));
+    if (matchingFact) {
+      observe(state, 'navigation_destination', {
+        nodeId,
+        source: matchingFact.path,
+        value: matchingFact.value,
+      });
+      continue;
+    }
+    contradict(
+      state,
+      `${nodeId} points to ${facts.map((fact) => fact.value).join(', ')} instead of ${expectedValues.join(' or ')}`,
+    );
+  }
 }
 
 function verifyExistingComponent(
   check,
   behavior,
   snapshots,
-  failures,
+  state,
   context,
 ) {
   const trigger = snapshotFor(snapshots, check.triggerNodeId);
-  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
-  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  verifyComponentInstances(check, behavior, snapshots, state, context);
+  if (
+    behavior.presentation === 'navigation'
+    || behavior.layoutEffect === 'navigation'
+  ) {
+    verifyNativeLink(check, behavior, snapshots, state, context);
+    return;
+  }
+  const triggerEvent = verifyTrigger(check, behavior, trigger, state);
   if (trigger && !belongsTo(trigger, check.componentNodeId)) {
-    failures.push('the trigger is not inside the existing component definition');
+    contradict(state, 'the trigger is not inside the existing component definition');
   }
   const permittedActions =
     behavior.presentation === 'floating' || behavior.presentation === 'modal'
@@ -810,15 +1072,19 @@ function verifyExistingComponent(
         : [];
   if (
     permittedActions.length > 0
+    && triggerEvent
     && !permittedActions.some((action) => triggerEvent.includes(action))
   ) {
-    failures.push('the component trigger does not expose an action capable of the declared behavior');
+    contradict(
+      state,
+      'the component trigger does not expose an action capable of the declared behavior',
+    );
   }
   verifyExpectedContent(
     behavior,
     snapshots,
     [check.componentNodeId, ...check.instanceNodeIds],
-    failures,
+    state,
   );
 }
 
@@ -834,7 +1100,7 @@ function hasCodeComponentEvidence(snapshot) {
   );
 }
 
-function verifyCodeComponent(check, behavior, snapshots, failures, context) {
+function verifyCodeComponent(check, behavior, snapshots, state, context) {
   // Code files are not native canvas ComponentNodes. Their durable structural
   // proof is an installed ComponentInstanceNode whose component reference
   // resolves to the authored code-file ID.
@@ -842,7 +1108,7 @@ function verifyCodeComponent(check, behavior, snapshots, failures, context) {
     check,
     behavior,
     snapshots,
-    failures,
+    state,
     context,
     { requireDefinition: false },
   );
@@ -851,7 +1117,10 @@ function verifyCodeComponent(check, behavior, snapshots, failures, context) {
     !nodes.some(hasCodeComponentEvidence)
     && Number(context?.lowLevelWriteCalls || 0) < 1
   ) {
-    failures.push('no code-component source or installed code-component evidence was found');
+    unknown(
+      state,
+      'no code-component source or installed code-component evidence was found',
+    );
   }
   // Content is covered by the mandatory structural and visual checks. Behavior
   // plans may describe content semantically rather than quote literal canvas
@@ -859,49 +1128,61 @@ function verifyCodeComponent(check, behavior, snapshots, failures, context) {
   // false failures for otherwise valid code components.
 }
 
-function verifyNativeEvent(check, behavior, snapshots, failures) {
+function verifyNativeEvent(check, behavior, snapshots, state) {
   verifyTrigger(
     check,
     behavior,
     snapshotFor(snapshots, check.triggerNodeId),
-    failures,
+    state,
   );
 }
 
-function verifyNativeEffect(check, behavior, snapshots, failures) {
+function verifyNativeEffect(check, behavior, snapshots, state) {
   const trigger = snapshotFor(snapshots, check.triggerNodeId);
   if (!check.triggerNodeId || !trigger) {
-    failures.push('effect target node was not found');
+    unknown(state, 'effect target node was not found');
     return null;
   }
+  observe(state, 'node_found', {
+    nodeId: check.triggerNodeId,
+    nodeType: nodeType(trigger),
+  });
   if (!FRAME_EFFECT_NODE_TYPES.has(nodeType(trigger))) {
-    failures.push(
+    contradict(
+      state,
       `${nodeType(trigger) || 'the target node'} does not support verified Framer effects`,
     );
   }
   const effectName = NATIVE_EFFECT_BY_ACTIVATION[behavior.activation];
   if (!effectName) {
-    failures.push(
+    contradict(
+      state,
       `native_effect does not support ${behavior.activation} activation`,
     );
     return null;
   }
   if (check.event !== effectName) {
-    failures.push(
+    contradict(
+      state,
       `${check.event || 'the supplied effect'} does not match ${effectName}`,
     );
   }
   const effect = directNodeProperty(trigger, effectName);
   if (!isRecord(effect) || Object.keys(effect).length === 0) {
-    failures.push(`${effectName} is not configured on the target`);
+    unknown(state, `${effectName} is not visible on the serialized target`);
     return null;
   }
+  observe(state, 'native_effect', {
+    nodeId: check.triggerNodeId,
+    effectName,
+    value: effect,
+  });
   if (
     effectName === 'appearEffect'
     && !['onInView', 'onMount', 'onScrollTarget', 'onScrollDirection']
       .includes(effect.trigger)
   ) {
-    failures.push('appearEffect does not declare a supported trigger');
+    contradict(state, 'appearEffect does not declare a supported trigger');
   }
   return {
     effectName,
@@ -909,6 +1190,66 @@ function verifyNativeEffect(check, behavior, snapshots, failures) {
   };
 }
 
+function verdictFor(state) {
+  if (state.contradictions.length > 0) return 'contradicted';
+  if (state.unknowns.length > 0) return 'unknown';
+  return 'verified';
+}
+
+function applySemanticAssessment(
+  check,
+  result,
+  mode,
+  liveEvidenceNodeIds = new Set(),
+) {
+  const assessment = check.semanticAssessment;
+  const base = {
+    ...result,
+    deterministicVerdict: result.verdict,
+    semanticAssessment: assessment
+      ? {
+          ...assessment,
+          mode,
+          accepted: false,
+        }
+      : null,
+  };
+  if (
+    mode !== 'enforce'
+    || result.verdict !== 'unknown'
+    || !assessment
+    || assessment.verdict === 'unknown'
+  ) return base;
+  if (
+    assessment.evidenceNodeIds.length === 0
+    || !assessment.evidenceNodeIds.every((nodeId) =>
+      liveEvidenceNodeIds.has(nodeId))
+  ) {
+    return {
+      ...base,
+      unknowns: uniqueStrings([
+        ...base.unknowns,
+        'semantic verification was not accepted because its evidence IDs were not backed by live observations',
+      ]),
+    };
+  }
+  return {
+    ...base,
+    verdict: assessment.verdict,
+    contradictions:
+      assessment.verdict === 'contradicted'
+        ? uniqueStrings([
+            ...base.contradictions,
+            `Semantic assessment contradicted the behavior: ${assessment.rationale}`,
+          ], 30)
+        : base.contradictions,
+    semanticAssessment: {
+      ...base.semanticAssessment,
+      accepted: true,
+    },
+  };
+}
+
 export function verifyBehaviorEvidence({
   plan,
   checks,
@@ -924,82 +1265,154 @@ export function verifyBehaviorEvidence({
       decision,
     ]),
   );
+  const liveEvidenceNodeIds = new Set(
+    snapshots instanceof Map
+      ? [...snapshots.entries()]
+          .filter(([, snapshot]) => Boolean(snapshot))
+          .map(([nodeId]) => nodeId)
+      : Object.entries(snapshots || {})
+          .filter(([, snapshot]) => Boolean(snapshot))
+          .map(([nodeId]) => nodeId),
+  );
   const verifiedChecks = checks.map((check) => {
     const behavior = behaviorById.get(check.behaviorId);
     const decision = mechanismByBehavior.get(check.behaviorId);
-    const failures = [];
+    const state = evidenceState();
     let nativeEffectEvidence = null;
     if (!behavior || !decision) {
-      failures.push('the planned behavior or mechanism was not found');
+      contradict(state, 'the planned behavior or mechanism was not found');
+    } else if (decision.mechanism === 'native_link') {
+      verifyNativeLink(check, behavior, snapshots, state, context);
     } else if (decision.mechanism === 'native_overlay') {
-      verifyOverlay(check, behavior, snapshots, failures);
+      verifyOverlay(check, behavior, snapshots, state);
     } else if (decision.mechanism === 'native_component_variants') {
-      verifyComponentVariants(check, behavior, snapshots, failures, context);
+      verifyComponentVariants(check, behavior, snapshots, state, context);
     } else if (decision.mechanism === 'existing_component_control') {
-      verifyExistingComponent(check, behavior, snapshots, failures, context);
+      verifyExistingComponent(check, behavior, snapshots, state, context);
     } else if (decision.mechanism === 'code_component') {
-      verifyCodeComponent(check, behavior, snapshots, failures, context);
+      verifyCodeComponent(check, behavior, snapshots, state, context);
     } else if (decision.mechanism === 'native_effect') {
       nativeEffectEvidence = verifyNativeEffect(
         check,
         behavior,
         snapshots,
-        failures,
+        state,
       );
     } else {
-      verifyNativeEvent(check, behavior, snapshots, failures);
+      verifyNativeEvent(check, behavior, snapshots, state);
     }
-    return {
+    const result = {
       ...check,
       mechanism: decision?.mechanism,
       ...(nativeEffectEvidence || {}),
-      passed: failures.length === 0,
-      failures,
+      verdict: verdictFor(state),
+      contradictions: uniqueStrings(state.contradictions, 30),
+      unknowns: uniqueStrings(state.unknowns, 30),
+      observations: state.observations.slice(0, 50),
+      repairAllowed: state.contradictions.length > 0,
+      nextSafeActions:
+        state.contradictions.length > 0
+          ? ['Repair only the observed contradictory properties, then verify once.']
+          : state.unknowns.length > 0
+            ? ['Collect a different live evidence source or provide a grounded semantic assessment; do not mutate based only on unknown evidence.']
+            : [],
     };
+    return applySemanticAssessment(
+      check,
+      result,
+      ['off', 'shadow', 'enforce'].includes(context?.semanticVerifierMode)
+        ? context.semanticVerifierMode
+        : 'shadow',
+      liveEvidenceNodeIds,
+    );
   });
 
   const behaviorResults = (plan?.behaviors || []).map((behavior) => {
     const decision = mechanismByBehavior.get(behavior.id);
     const matching = verifiedChecks.filter((check) =>
       check.behaviorId === behavior.id);
-    const suppliedTargets = new Set(
-      matching.flatMap((check) =>
-        decision?.mechanism === 'native_component_variants'
-        || decision?.mechanism === 'existing_component_control'
-        || decision?.mechanism === 'code_component'
-          ? check.instanceNodeIds
-          : [check.triggerNodeId]),
+    const targetIdsFor = (check) =>
+      decision?.mechanism === 'native_component_variants'
+      || decision?.mechanism === 'existing_component_control'
+      || decision?.mechanism === 'code_component'
+      || (
+        decision?.mechanism === 'native_link'
+        && check.instanceNodeIds.length > 0
+      )
+        ? check.instanceNodeIds
+        : [check.triggerNodeId].filter(Boolean);
+    const observedTargets = new Set(matching.flatMap(targetIdsFor));
+    const verifiedTargets = new Set(
+      matching
+        .filter((check) => check.verdict === 'verified')
+        .flatMap(targetIdsFor),
+    );
+    const contradictedTargets = new Set(
+      matching
+        .filter((check) => check.verdict === 'contradicted')
+        .flatMap(targetIdsFor),
     );
-    const failures = matching.flatMap((check) => check.failures);
-    if (matching.length === 0) failures.push('no evidence was supplied');
-    if (suppliedTargets.size < behavior.expectedTargets) {
-      failures.push(
-        `verified ${suppliedTargets.size} of ${behavior.expectedTargets} expected targets`,
+    const contradictions = matching
+      .filter((check) => check.verdict === 'contradicted')
+      .flatMap((check) => check.contradictions);
+    const unknowns = matching
+      .filter((check) => check.verdict === 'unknown')
+      .flatMap((check) => check.unknowns);
+    if (matching.length === 0) unknowns.push('no evidence was supplied');
+    if (verifiedTargets.size < behavior.expectedTargets) {
+      unknowns.push(
+        `verified ${verifiedTargets.size} of ${behavior.expectedTargets} expected targets`,
       );
     }
+    const verdict =
+      matching.some((check) => check.verdict === 'contradicted')
+        ? 'contradicted'
+        : matching.some((check) => check.verdict === 'unknown')
+          || unknowns.length > 0
+          ? 'unknown'
+          : 'verified';
     return {
       behaviorId: behavior.id,
       behaviorSignature: behavior.signature,
       mechanism: decision?.mechanism,
       expectedTargets: behavior.expectedTargets,
-      verifiedTargets: suppliedTargets.size,
-      passed: failures.length === 0,
-      failures: uniqueStrings(failures, 50),
+      observedTargets: observedTargets.size,
+      verifiedTargets: verifiedTargets.size,
+      contradictedTargets: contradictedTargets.size,
+      unknownTargets: Math.max(
+        0,
+        behavior.expectedTargets
+          - verifiedTargets.size
+          - contradictedTargets.size,
+      ),
+      verdict,
+      contradictions: uniqueStrings(contradictions, 50),
+      unknowns: uniqueStrings(unknowns, 50),
     };
   });
   const representativeBehaviorIds = behaviorResults
     .filter((result) =>
       verifiedChecks.some((check) =>
-        check.behaviorId === result.behaviorId && check.passed))
+        check.behaviorId === result.behaviorId
+        && check.verdict === 'verified'))
     .map((result) => result.behaviorId);
   const completed =
     behaviorResults.length > 0
-    && behaviorResults.every((result) => result.passed);
+    && behaviorResults.every((result) => result.verdict === 'verified');
+  const hasContradictions = behaviorResults.some((result) =>
+    result.verdict === 'contradicted');
+  const usedSemanticAssessment = verifiedChecks.some((check) =>
+    check.semanticAssessment?.accepted === true);
   return {
     completed,
-    verificationLevel: completed
-      ? 'structurally_verified'
-      : 'unverified',
+    verificationLevel:
+      completed && usedSemanticAssessment
+        ? 'semantically_verified'
+        : completed
+          ? 'structurally_verified'
+          : hasContradictions
+            ? 'contradicted'
+            : 'unknown',
     checks: verifiedChecks,
     behaviors: behaviorResults,
     representativeBehaviorIds,