supipowers 1.5.2 → 2.0.0

package/src/ultraplan/runtime/normalize.ts

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import type {
+  UltraPlanActorKind,
+  UltraPlanAttemptRecord,
+  UltraPlanCursorTargetType,
+  UltraPlanExecutionPhase,
+  UltraPlanHookEventName,
+  UltraPlanHookObservation,
+  UltraPlanObservationTarget,
+  UltraPlanScenarioLevel,
+  UltraPlanSourceAgent,
+  UltraPlanStackId,
+} from "../../types.js";
+import { recoverLaunchContextFromEvent, recoverTargetHintFromPrompt } from "./launch-context.js";
+
+/**
+ * Slice-2 normalization seam.
+ *
+ * Converts raw platform hook events into typed `UltraPlanHookObservation` values. This module is
+ * the gate between raw platform behavior and UltraPlan runtime truth — by the time an observation
+ * reaches the reducer, its attempt identity, target, replay fingerprint, and correlation status
+ * are all fully resolved. Pure.
+ */
+
+export interface UltraPlanTargetHint {
+  targetType?: UltraPlanCursorTargetType;
+  stack?: UltraPlanStackId | null;
+  domainId?: string | null;
+  level?: UltraPlanScenarioLevel | null;
+  scenarioId?: string | null;
+  phase?: UltraPlanExecutionPhase;
+  resolvedSlot?: string | null;
+  actorKind?: UltraPlanActorKind;
+  sourceAgent?: UltraPlanSourceAgent;
+}
+
+export interface NormalizeHookEventInput {
+  hookEvent: UltraPlanHookEventName;
+  sessionId: string;
+  nowIso: string;
+
+  /** Structured platform metadata (may carry `ultraplanLaunchContext`). */
+  metadata?: Record<string, unknown> | null;
+  /** Prompt/assignment/system-prompt text (may carry `ULTRAPLAN_LAUNCH_CONTEXT=<json>`). */
+  prompt?: string | null;
+  /** The currently-persisted active attempt from the tracker (last-resort carrier). */
+  persistedActiveAttempt?: UltraPlanAttemptRecord | null;
+
+  /** Raw platform payload (tool args, results, exit reasons, etc.) — used for audit + fingerprint. */
+  payload?: Record<string, unknown>;
+
+  /**
+   * Hints about the slot-backed target derived from the platform event (e.g. before_agent_start
+   * args). When absent or the hook is a pure session event, the observation is classified as
+   * session-scope.
+   */
+  targetHint?: UltraPlanTargetHint;
+  /** Fallback hint from active-execution state when prompt text did not carry one. */
+  fallbackTargetHint?: UltraPlanTargetHint;
+
+  /** Optional platform-native event id (tool call id, turn id, agent run id). */
+  nativeEventId?: string | null;
+  /** Optional causation id grouping related hook activity. */
+  causationId?: string | null;
+  /** Optional override for when the event actually occurred; defaults to `nowIso`. */
+  occurredAt?: string;
+}
+
+/**
+ * Hook events that are session-scope regardless of target hint. Main-orchestrator-only
+ * before_agent_start / tool_call / tool_result / agent_end events that arrive with no slot-backed
+ * target hint are also treated as session-scope via the classification logic below.
+ */
+const SESSION_SCOPE_HOOKS: readonly UltraPlanHookEventName[] = [
+  "session_start",
+  "session_shutdown",
+];
+
+export function normalizeHookEvent(input: NormalizeHookEventInput): UltraPlanHookObservation {
+  const occurredAt = input.occurredAt ?? input.nowIso;
+  const targetHint = resolveTargetHint(input);
+  const launchContext = SESSION_SCOPE_HOOKS.includes(input.hookEvent)
+    ? null
+    : recoverLaunchContextFromEvent({
+        metadata: input.metadata ?? null,
+        prompt: input.prompt ?? null,
+        persistedActiveAttempt: input.persistedActiveAttempt ?? null,
+      });
+  const { actorKind, isSessionScope } = classifyActor(input, targetHint, launchContext);
+  const sourceAgent = targetHint?.sourceAgent
+    ?? launchContext?.sourceAgent
+    ?? (isSessionScope ? "main" : "sub-agent");
+
+  if (isSessionScope) {
+    return {
+      sessionId: input.sessionId,
+      hookEvent: input.hookEvent,
+      actorKind: "main-orchestrator",
+      attemptId: null,
+      attemptKey: null,
+      sourceAgent,
+      occurredAt,
+      causationId: input.causationId ?? null,
+      fingerprint: computeFingerprint({
+        attemptId: null,
+        hookEvent: input.hookEvent,
+        nativeEventId: input.nativeEventId ?? null,
+        payload: input.payload ?? {},
+      }),
+      target: null,
+      correlationFailure: null,
+      payloadSummary: summarizePayload(input.hookEvent, input.payload),
+    };
+  }
+
+  if (!launchContext) {
+    return {
+      sessionId: input.sessionId,
+      hookEvent: input.hookEvent,
+      actorKind,
+      attemptId: null,
+      attemptKey: null,
+      sourceAgent,
+      occurredAt,
+      causationId: input.causationId ?? null,
+      fingerprint: computeFingerprint({
+        attemptId: null,
+        hookEvent: input.hookEvent,
+        nativeEventId: input.nativeEventId ?? null,
+        payload: input.payload ?? {},
+      }),
+      target: buildTargetFromHint(targetHint),
+      correlationFailure: {
+        reason: "slot-backed hook event without a resolvable UltraPlan launch context",
+      },
+      payloadSummary: summarizePayload(input.hookEvent, input.payload),
+    };
+  }
+
+  if (!targetHint) {
+    return {
+      sessionId: input.sessionId,
+      hookEvent: input.hookEvent,
+      actorKind,
+      attemptId: launchContext.attemptId,
+      attemptKey: launchContext.attemptKey,
+      sourceAgent,
+      occurredAt,
+      causationId: input.causationId ?? null,
+      fingerprint: computeFingerprint({
+        attemptId: launchContext.attemptId,
+        hookEvent: input.hookEvent,
+        nativeEventId: input.nativeEventId ?? null,
+        payload: input.payload ?? {},
+      }),
+      target: null,
+      correlationFailure: {
+        reason: "slot-backed hook event without a resolvable UltraPlan target hint",
+      },
+      payloadSummary: summarizePayload(input.hookEvent, input.payload),
+    };
+  }
+
+  return {
+    sessionId: input.sessionId,
+    hookEvent: input.hookEvent,
+    actorKind,
+    attemptId: launchContext.attemptId,
+    attemptKey: launchContext.attemptKey,
+    sourceAgent,
+    occurredAt,
+    causationId: input.causationId ?? null,
+    fingerprint: computeFingerprint({
+      attemptId: launchContext.attemptId,
+      hookEvent: input.hookEvent,
+      nativeEventId: input.nativeEventId ?? null,
+      payload: input.payload ?? {},
+    }),
+    target: buildTargetFromHint(targetHint),
+    correlationFailure: null,
+    payloadSummary: summarizePayload(input.hookEvent, input.payload),
+  };
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function classifyActor(
+  input: NormalizeHookEventInput,
+  targetHint: UltraPlanTargetHint | undefined,
+  launchContext: UltraPlanAttemptRecord["launchContext"] | null,
+ ): { actorKind: UltraPlanActorKind; isSessionScope: boolean } {
+  if (SESSION_SCOPE_HOOKS.includes(input.hookEvent)) {
+    return { actorKind: "main-orchestrator", isSessionScope: true };
+  }
+  if (targetHint?.actorKind === "main-orchestrator") {
+    return { actorKind: "main-orchestrator", isSessionScope: true };
+  }
+  if (targetHint || launchContext) {
+    return { actorKind: targetHint?.actorKind ?? "slot", isSessionScope: false };
+  }
+  return { actorKind: "main-orchestrator", isSessionScope: true };
+}
+
+function buildTargetFromHint(hint: UltraPlanTargetHint | undefined): UltraPlanObservationTarget | null {
+  if (!hint) return null;
+  const hasAnyField = hint.targetType !== undefined
+    || hint.stack !== undefined
+    || hint.domainId !== undefined
+    || hint.level !== undefined
+    || hint.scenarioId !== undefined
+    || hint.phase !== undefined
+    || hint.resolvedSlot !== undefined;
+  if (!hasAnyField) return null;
+  return {
+    targetType: hint.targetType ?? "scenario",
+    stack: hint.stack ?? null,
+    domainId: hint.domainId ?? null,
+    level: hint.level ?? null,
+    scenarioId: hint.scenarioId ?? null,
+    phase: hint.phase ?? "red",
+    resolvedSlot: hint.resolvedSlot ?? null,
+  };
+}
+
+function resolveTargetHint(input: NormalizeHookEventInput): UltraPlanTargetHint | undefined {
+  return input.targetHint
+    ?? recoverTargetHintFromPrompt(input.prompt ?? null)
+    ?? input.fallbackTargetHint;
+}
+
+interface FingerprintComponents {
+  attemptId: string | null;
+  hookEvent: UltraPlanHookEventName;
+  nativeEventId: string | null;
+  payload: unknown;
+}
+
+/**
+ * Replay fingerprint per spec §cross-hook carrier line 459:
+ *   `attemptId + hook name + native event id + normalized payload`
+ *
+ * The payload is canonicalized (sorted keys) so equivalent payloads with different key ordering
+ * produce the same fingerprint. This is what makes replay dedupe durable across reloads.
+ */
+function computeFingerprint(parts: FingerprintComponents): string {
+  const canonical = JSON.stringify({
+    attemptId: parts.attemptId,
+    hookEvent: parts.hookEvent,
+    nativeEventId: parts.nativeEventId,
+    payload: canonicalize(parts.payload),
+  });
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => [k, canonicalize(v)] as const);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}
+
+function summarizePayload(hookEvent: UltraPlanHookEventName, payload: Record<string, unknown> | undefined): string {
+  if (!payload) return hookEvent;
+  const tool = typeof payload.toolName === "string" ? payload.toolName : undefined;
+  const exit = typeof payload.exitCode === "number" ? payload.exitCode : undefined;
+  const reason = typeof payload.exitReason === "string" ? payload.exitReason : undefined;
+  const summary = typeof payload.summary === "string" ? payload.summary : undefined;
+  const bits: string[] = [hookEvent];
+  if (tool) bits.push(`tool=${tool}`);
+  if (exit !== undefined) bits.push(`exit=${exit}`);
+  if (reason) bits.push(`reason=${reason}`);
+  if (summary) bits.push(summary);
+  return bits.join(" ");
+}

package/src/ultraplan/runtime/proof.ts

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import type {
+  UltraPlanBlockerCandidate,
+  UltraPlanExecutionPhase,
+  UltraPlanHookObservation,
+  UltraPlanProofCandidate,
+  UltraPlanProofCandidateTarget,
+  UltraPlanStackId,
+} from "../../types.js";
+import {
+  isUltraPlanDomainReview,
+  isUltraPlanStackReview,
+} from "../contracts.js";
+import {
+  buildProofInvalidBlocker,
+} from "./blockers.js";
+
+/**
+ * Slice-2 proof extraction.
+ *
+ * Converts `tool_result` / `agent_end` observations into typed proof candidates. Fail-closed:
+ * phase or target mismatches become `proof-invalid` blocker candidates, never silent advancement.
+ * Pure — no I/O.
+ */
+
+export interface ExtractProofInput {
+  observation: UltraPlanHookObservation;
+  /**
+   * Raw platform payload. When the payload has a structured `proof` object of shape
+   * `{ type, phase, evidence, artifactRef? }`, that value is treated as a proof candidate.
+   */
+  payload: Record<string, unknown>;
+  expectedTarget: UltraPlanProofCandidateTarget;
+  expectedPhase: UltraPlanExecutionPhase;
+}
+
+export type ExtractProofResult =
+  | { kind: "proof"; proof: UltraPlanProofCandidate }
+  | { kind: "blocker-candidate"; blocker: UltraPlanBlockerCandidate }
+  | { kind: "none" };
+
+export function extractProofCandidate(input: ExtractProofInput): ExtractProofResult {
+  const raw = input.payload?.proof;
+  if (raw === undefined || raw === null) {
+    return { kind: "none" };
+  }
+
+  const parsed = parseProofShape(raw);
+  if (!parsed) {
+    return {
+      kind: "blocker-candidate",
+      blocker: {
+        blocker: buildProofInvalidBlocker({
+          detectedAt: input.observation.occurredAt,
+          scope: "scenario",
+          affected: toAffected(input.expectedTarget),
+          reason: "payload.proof is not a well-formed proof object",
+        }),
+        observationFingerprint: input.observation.fingerprint,
+      },
+    };
+  }
+
+  // Phase mismatch: reducer spec §proof obligations requires exact phase alignment.
+  if (parsed.phase !== input.expectedPhase) {
+    return {
+      kind: "blocker-candidate",
+      blocker: {
+        blocker: buildProofInvalidBlocker({
+          detectedAt: input.observation.occurredAt,
+          scope: "scenario",
+          affected: toAffected(input.expectedTarget),
+          reason: `expected ${input.expectedPhase}-phase proof, received ${parsed.phase}-phase proof`,
+        }),
+        observationFingerprint: input.observation.fingerprint,
+      },
+    };
+  }
+
+  // Target mismatch: observation.target must align with the expected target.
+  if (!observationTargetMatchesExpected(input.observation, input.expectedTarget)) {
+    return {
+      kind: "blocker-candidate",
+      blocker: {
+        blocker: buildProofInvalidBlocker({
+          detectedAt: input.observation.occurredAt,
+          scope: "scenario",
+          affected: toAffected(input.expectedTarget),
+          reason: "proof target does not match the expected attempt target",
+        }),
+        observationFingerprint: input.observation.fingerprint,
+      },
+    };
+  }
+
+  const candidate: UltraPlanProofCandidate = {
+    phase: parsed.phase,
+    type: parsed.type,
+    target: input.expectedTarget,
+    evidence: parsed.evidence,
+    artifactRef: parsed.artifactRef ?? null,
+    observationFingerprint: input.observation.fingerprint,
+    fingerprint: computeProofFingerprint({
+      observationFingerprint: input.observation.fingerprint,
+      phase: parsed.phase,
+      type: parsed.type,
+      target: input.expectedTarget,
+      evidence: parsed.evidence,
+      artifactRef: parsed.artifactRef ?? null,
+    }),
+  };
+  return { kind: "proof", proof: candidate };
+}
+
+// ---------------------------------------------------------------------------
+// Review artifact validation (spec §proof obligations line 602)
+// ---------------------------------------------------------------------------
+
+export interface ValidateReviewArtifactInput {
+  reviewType: "domain" | "stack";
+  stack: UltraPlanStackId;
+  domainId: string | null;
+  expectedCanonicalPath: string;
+  observedArtifactRef: string;
+  artifact: unknown;
+}
+
+export type ValidateReviewArtifactResult =
+  | { ok: true }
+  | { ok: false; reason: string };
+
+export function validateReviewArtifactProof(input: ValidateReviewArtifactInput): ValidateReviewArtifactResult {
+  if (input.observedArtifactRef !== input.expectedCanonicalPath) {
+    return {
+      ok: false,
+      reason: `review artifact must live at canonical path ${input.expectedCanonicalPath}, observed ${input.observedArtifactRef}`,
+    };
+  }
+
+  if (input.reviewType === "domain") {
+    if (!isUltraPlanDomainReview(input.artifact)) {
+      return { ok: false, reason: "domain review artifact failed schema validation" };
+    }
+    const artifact = input.artifact;
+    if (artifact.status !== "passed") {
+      return { ok: false, reason: `domain review artifact status is ${artifact.status}, expected passed` };
+    }
+    if (artifact.stack !== input.stack || artifact.domainId !== input.domainId) {
+      return { ok: false, reason: "domain review artifact stack/domainId does not match review target" };
+    }
+    return { ok: true };
+  }
+
+  // stack review
+  if (!isUltraPlanStackReview(input.artifact)) {
+    return { ok: false, reason: "stack review artifact failed schema validation" };
+  }
+  const artifact = input.artifact;
+  if (artifact.status !== "passed") {
+    return { ok: false, reason: `stack review artifact status is ${artifact.status}, expected passed` };
+  }
+  if (artifact.stack !== input.stack) {
+    return { ok: false, reason: "stack review artifact stack does not match review target" };
+  }
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+interface ParsedProofShape {
+  type: UltraPlanProofCandidate["type"];
+  phase: UltraPlanExecutionPhase;
+  evidence: { summary: string; command?: string; outputRef?: string; metadata?: Record<string, unknown> };
+  artifactRef?: string;
+}
+
+const VALID_PROOF_TYPES: readonly string[] = ["test", "command", "review", "artifact"];
+const VALID_PHASES: readonly string[] = ["red", "green", "review", "waiting", "complete"];
+
+function parseProofShape(raw: unknown): ParsedProofShape | null {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.type !== "string" || !VALID_PROOF_TYPES.includes(obj.type)) return null;
+  if (typeof obj.phase !== "string" || !VALID_PHASES.includes(obj.phase)) return null;
+  if (!obj.evidence || typeof obj.evidence !== "object") return null;
+  const ev = obj.evidence as Record<string, unknown>;
+  if (typeof ev.summary !== "string" || ev.summary.length === 0) return null;
+
+  const parsed: ParsedProofShape = {
+    type: obj.type as UltraPlanProofCandidate["type"],
+    phase: obj.phase as UltraPlanExecutionPhase,
+    evidence: {
+      summary: ev.summary,
+      ...(typeof ev.command === "string" ? { command: ev.command } : {}),
+      ...(typeof ev.outputRef === "string" ? { outputRef: ev.outputRef } : {}),
+      ...(ev.metadata && typeof ev.metadata === "object" && !Array.isArray(ev.metadata)
+        ? { metadata: ev.metadata as Record<string, unknown> }
+        : {}),
+    },
+  };
+  if (typeof obj.artifactRef === "string" && obj.artifactRef.length > 0) {
+    parsed.artifactRef = obj.artifactRef;
+  }
+  return parsed;
+}
+
+function toAffected(target: UltraPlanProofCandidateTarget) {
+  return {
+    stack: target.stack,
+    domainId: target.domainId,
+    level: target.level,
+    scenarioId: target.scenarioId,
+  };
+}
+
+function observationTargetMatchesExpected(
+  observation: UltraPlanHookObservation,
+  expected: UltraPlanProofCandidateTarget,
+): boolean {
+  const obsTarget = observation.target;
+  if (!obsTarget) return false;
+  return obsTarget.targetType === expected.targetType
+    && obsTarget.stack === expected.stack
+    && obsTarget.domainId === expected.domainId
+    && obsTarget.level === expected.level
+    && obsTarget.scenarioId === expected.scenarioId;
+}
+
+function computeProofFingerprint(parts: {
+  observationFingerprint: string;
+  phase: UltraPlanExecutionPhase;
+  type: UltraPlanProofCandidate["type"];
+  target: UltraPlanProofCandidateTarget;
+  evidence: ParsedProofShape["evidence"];
+  artifactRef: string | null;
+}): string {
+  const canonical = JSON.stringify({
+    observationFingerprint: parts.observationFingerprint,
+    phase: parts.phase,
+    type: parts.type,
+    target: canonicalize(parts.target),
+    evidence: canonicalize(parts.evidence),
+    artifactRef: parts.artifactRef,
+  });
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => [k, canonicalize(v)] as const);
+    return Object.fromEntries(entries);
+  }
+  return value;
+}