@punktechnologies/sdk 0.1.0 → 0.1.1

package/src/types.ts

@@ -0,0 +1,512 @@
+/**
+ * @punktechnologies/sdk — local type contracts.
+ *
+ * These mirror the canonical definitions in `@punk/trace-schema` (the
+ * dependency-free contract package every Punk service imports). They are
+ * copied here — not imported — so the published SDK has zero dependencies.
+ *
+ * If a shape changes in `@punk/trace-schema`, update the mirror here.
+ * The gateway is the source of truth at runtime; these types describe what
+ * its API returns.
+ */
+
+// ---------------------------------------------------------------------------
+// Identity & trust (mirrors @punk/trace-schema)
+// ---------------------------------------------------------------------------
+
+/** MeshGuard-compatible trust tiers. */
+export type TrustTier = "unverified" | "verified" | "trusted" | "privileged";
+
+/** Trust lane of a memory/context source (memory quarantine). */
+export type TrustLane = "untrusted" | "observed" | "verified" | "human_approved";
+
+// ---------------------------------------------------------------------------
+// Side effects (PRD §17)
+// ---------------------------------------------------------------------------
+
+/**
+ * 0 pure computation, 1 read-only external, 2 reversible/idempotent writes,
+ * 3 user-visible writes (slack/email/tickets), 4 high-impact (payments,
+ * deletion, permissions). Undeclared tools default to level 3 (conservative).
+ */
+export type SideEffectLevel = 0 | 1 | 2 | 3 | 4;
+
+export type SideEffectStatus =
+  | "planned"
+  | "executed"
+  | "suppressed"
+  | "dry_run"
+  | "blocked";
+
+export interface SideEffectRecord {
+  id: string;
+  runId: string;
+  tenantId: string;
+  toolName: string;
+  level: SideEffectLevel;
+  status: SideEffectStatus;
+  idempotencyKey?: string;
+  payload?: unknown;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Routes & explanations
+// ---------------------------------------------------------------------------
+
+export type RouteType =
+  | "live" // pass-through to live provider
+  | "exact_cache"
+  | "semantic_cache"
+  | "tool_cache"
+  | "som_cache"
+  | "plan_cache"
+  | "artifact" // promoted deterministic artifact
+  | "hybrid_artifact" // artifact with model fallback for low-confidence rows
+  | "model_substitution" // learned cheaper-model substitution
+  | "chorus" // claim-graph intelligence composition through Punk Chorus
+  | "blocked"; // policy denied
+
+export interface RouteAlternative {
+  route: RouteType;
+  rejected: string; // why this route was not taken
+}
+
+export interface PolicyVerdict {
+  decision: "allow" | "deny" | "approval_required";
+  policyName?: string;
+  ruleIndex?: number;
+  reason: string;
+  trustTier?: TrustTier;
+  sideEffectLevel?: SideEffectLevel;
+}
+
+/** Every optimized response must be explainable. */
+export interface RouteExplanation {
+  route: RouteType;
+  reason: string;
+  alternatives: RouteAlternative[];
+  policy?: PolicyVerdict;
+  cache?: {
+    type: string;
+    hit: boolean;
+    key?: string;
+    freshness?: "valid" | "stale" | "expired";
+    ageMs?: number;
+  };
+  artifact?: {
+    id: string;
+    version: number;
+    confidence: number;
+    shadowed?: boolean;
+  };
+  pattern?: { id: string; name: string; confidence: number };
+  estimatedSavedUsd?: number;
+  estimatedSavedMs?: number;
+  /**
+   * Observe-mode ghost accounting: what the optimizer WOULD have done.
+   * Present only when the API key runs in "observe" mode and a
+   * cheaper/blocked route existed.
+   */
+  ghost?: {
+    route: RouteType | "blocked";
+    estimatedSavedUsd: number;
+    estimatedSavedMs: number;
+    reason: string;
+  };
+  fallback: string;
+}
+
+// ---------------------------------------------------------------------------
+// Runs
+// ---------------------------------------------------------------------------
+
+export type RunStatus = "running" | "completed" | "failed" | "blocked";
+
+export interface Run {
+  id: string;
+  tenantId: string;
+  appId: string;
+  agentId?: string;
+  /** Pseudonymous subject (end user) identifier. */
+  subject?: string;
+  status: RunStatus;
+  route?: RouteType;
+  shadowed?: boolean; // a candidate artifact shadow-ran beside this run
+  requestHash: string;
+  /** Normalized prompt-shape fingerprint; groups runs into patterns. */
+  fingerprint?: string;
+  patternId?: string;
+  provider?: string;
+  model?: string;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+  /** Estimated USD avoided versus the live path (0 for live runs). */
+  savedUsd: number;
+  /** Observe mode: estimated USD Punk WOULD have saved (ghost accounting). */
+  ghostSavedUsd?: number;
+  latencyMs: number;
+  startedAt: number;
+  completedAt?: number;
+  routeExplanation?: RouteExplanation;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Trace events
+// ---------------------------------------------------------------------------
+
+export type TraceEventType =
+  | "request.received"
+  | "policy.checked"
+  | "route.selected"
+  | "model.requested"
+  | "model.failover"
+  | "model.completed"
+  | "chorus.contract"
+  | "chorus.claim_graph"
+  | "chorus.route_selected"
+  | "chorus.verifier"
+  | "chorus.auction"
+  | "chorus.ledger"
+  | "chorus.research_pack"
+  | "chorus.live_synthesis"
+  | "chorus.live_synthesis_empty"
+  | "chorus.live_synthesis_failed"
+  | "chorus.receipt"
+  | "tool.called"
+  | "tool.completed"
+  | "web.fetched"
+  | "som.compiled"
+  | "som.cache_hit"
+  | "som.diffed"
+  | "web.acted"
+  | "side_effect.planned"
+  | "side_effect.executed"
+  | "side_effect.suppressed"
+  | "side_effect.blocked"
+  | "cache.checked"
+  | "cache.hit"
+  | "cache.miss"
+  | "cache.stored"
+  | "artifact.selected"
+  | "artifact.executed"
+  | "artifact.failed"
+  | "artifact.shadowed"
+  | "evaluator.scored"
+  | "pattern.updated"
+  | "artifact.synthesized"
+  | "artifact.state_changed"
+  | "drift.detected"
+  | "tripwire.fired"
+  | "user.feedback"
+  | "run.completed";
+
+export interface TraceEvent {
+  id: string;
+  runId: string;
+  tenantId: string;
+  type: TraceEventType;
+  ts: number;
+  parentId?: string;
+  payload: Record<string, unknown>;
+  schemaVersion: 1;
+}
+
+// ---------------------------------------------------------------------------
+// Patterns
+// ---------------------------------------------------------------------------
+
+export type PatternState =
+  | "observed"
+  | "candidate"
+  | "watchlisted"
+  | "synthesizing"
+  | "replay_tested"
+  | "shadowing"
+  | "promoted"
+  | "negative" // negative cache: do not attempt optimization
+  | "retired";
+
+export type TaskClass =
+  | "deterministic"
+  | "schema_deterministic"
+  | "semantic"
+  | "preference"
+  | "open_ended"
+  | "high_risk";
+
+export interface Pattern {
+  id: string;
+  tenantId: string;
+  appId: string;
+  name: string;
+  state: PatternState;
+  /** Normalized prompt-shape fingerprint (primary cluster key). */
+  fingerprint: string;
+  toolSequenceFp?: string;
+  outputSchemaFp?: string;
+  taskClass: TaskClass;
+  riskLevel: SideEffectLevel;
+  runCount: number;
+  totalCostUsd: number;
+  avgCostUsd: number;
+  avgLatencyMs: number;
+  /** How stable inputs→outputs are across observed runs, [0,1]. */
+  stabilityScore: number;
+  /** expected_value-style prioritization score. */
+  optimizableScore: number;
+  exampleRunIds: string[];
+  negativeReason?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Artifacts
+// ---------------------------------------------------------------------------
+
+export type ArtifactState =
+  | "candidate"
+  | "replay_failed"
+  | "replay_passed"
+  | "shadowing"
+  | "shadow_failed"
+  | "approved"
+  | "promoted"
+  | "canary"
+  | "stable"
+  | "degraded"
+  | "quarantined"
+  | "retired";
+
+export type ArtifactType =
+  | "static_response"
+  | "template"
+  | "deterministic_transform"
+  | "ruleset_classifier"
+  | "tool_plan"
+  | "web_extraction"
+  | "hybrid";
+
+/**
+ * Loose representation slot; the gateway's artifact runtime defines and
+ * validates the concrete declarative DSL.
+ */
+export type ArtifactRepresentation = {
+  dslVersion: 1;
+  kind: ArtifactType;
+} & Record<string, unknown>;
+
+export interface ArtifactProvenance {
+  synthesizer: string; // e.g. "punk-inductive-compiler/v1"
+  sourceRunIds: string[];
+  holdoutRunIds: string[];
+  parentArtifactId?: string;
+  notes?: string;
+}
+
+export interface Artifact {
+  id: string;
+  tenantId: string;
+  patternId: string;
+  version: number;
+  type: ArtifactType;
+  state: ArtifactState;
+  representation: ArtifactRepresentation;
+  provenance: ArtifactProvenance;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  sideEffectLevel: SideEffectLevel;
+  // --- self-improving confidence state (Beta posterior over correctness) ---
+  /** Successes + prior. Updated on every replay/shadow/live evaluation. */
+  alpha: number;
+  /** Failures + prior. */
+  beta: number;
+  /** Lower-bound confidence derived from the posterior; the router gates on this. */
+  confidence: number;
+  replayPasses: number;
+  replayFails: number;
+  shadowPasses: number;
+  shadowFails: number;
+  livePasses: number;
+  liveFails: number;
+  estCostUsd: number; // cost of running this artifact (≈0 for deterministic)
+  estLatencyMs: number;
+  createdAt: number;
+  promotedAt?: number;
+  lastEvaluatedAt?: number;
+  stateReason?: string;
+}
+
+export interface PromotionGateStatus {
+  eligible: boolean;
+  autoPromotable: boolean;
+  reasons: string[];
+}
+
+export type EvaluationKind = "replay" | "shadow" | "live";
+
+export interface ArtifactEvaluation {
+  id: string;
+  artifactId: string;
+  tenantId: string;
+  kind: EvaluationKind;
+  runId?: string; // trace this evaluation compared against
+  pass: boolean;
+  structuralPass: boolean;
+  semanticScore: number; // [0,1]
+  sideEffectPass: boolean;
+  expected?: string;
+  actual?: string;
+  details?: string;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Web runtime (Plasmate SOM v0.1 contracts)
+// ---------------------------------------------------------------------------
+
+/** Mirrors Plasmate's Som struct (som_version "0.1"). */
+export interface SomSnapshot {
+  som_version: string;
+  url: string;
+  title: string;
+  lang: string;
+  regions: SomRegion[];
+  meta: {
+    html_bytes: number;
+    som_bytes: number;
+    element_count: number;
+    interactive_count: number;
+  };
+}
+
+export interface SomRegion {
+  id: string; // r_navigation, r_main_0 ...
+  role: string; // navigation | main | aside | header | footer | form | dialog | content
+  label?: string;
+  action?: string;
+  method?: string;
+  elements: SomElement[];
+}
+
+export interface SomElement {
+  id: string; // e_<12 hex> deterministic
+  role: string; // link | button | heading | paragraph | text_input | ...
+  text?: string;
+  label?: string;
+  actions?: string[];
+  attrs?: Record<string, unknown>;
+  children?: SomElement[];
+}
+
+export interface SomDiffEntry {
+  kind: "added" | "removed" | "changed";
+  regionId: string;
+  elementId?: string;
+  field?: string;
+  before?: string;
+  after?: string;
+  /** Semantic weight: pricing/CTA/form changes matter more than footer noise. */
+  significance: "high" | "medium" | "low";
+}
+
+export interface SomDiff {
+  url: string;
+  beforeFingerprint: string;
+  afterFingerprint: string;
+  entries: SomDiffEntry[];
+  /** Aggregate drift signal in [0,1]. */
+  driftScore: number;
+}
+
+// ---------------------------------------------------------------------------
+// Web actions (perception→action loop over SOM sessions)
+// ---------------------------------------------------------------------------
+
+/** Protocol-level actions an agent can take on a SOM page (no JS engine). */
+export type WebActionKind = "click" | "type" | "select" | "submit";
+
+export interface WebActionIntent {
+  action: WebActionKind;
+  /** SOM element id (e_…) — or a region id (r_form…) for submit. */
+  target: string;
+  value?: string;
+}
+
+export interface WebActionResult {
+  ok: boolean;
+  action: WebActionKind;
+  target: string;
+  /** Element/region id the engine resolved the target to. */
+  resolved?: string;
+  /** True when the action caused a page navigation (link follow / form submit). */
+  navigated?: boolean;
+  /** Page URL after the action. */
+  url: string;
+  /** URL the action attempted before redirects, when it caused navigation. */
+  requestedUrl?: string;
+  error?: string;
+  /**
+   * For successful form submissions, including submit-button clicks: the
+   * serialized field set that was posted (name -> value), so the operator can
+   * see exactly what was sent.
+   */
+  posted?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Savings rollup (dashboard)
+// ---------------------------------------------------------------------------
+
+export interface SavingsSummary {
+  tenantId: string;
+  totalRuns: number;
+  liveRuns: number;
+  optimizedRuns: number;
+  blockedRuns: number;
+  totalCostUsd: number;
+  totalSavedUsd: number;
+  /** Observe-mode ghost accounting: sum of per-run ghostSavedUsd. */
+  ghostSavedUsd: number;
+  totalSavedMs: number;
+  cacheHits: number;
+  artifactHits: number;
+  cacheHitRate: number;
+  artifactHitRate: number;
+  somTokensSaved: number;
+}
+
+// ---------------------------------------------------------------------------
+// External MCP servers (registry consumed by the gateway's tool_call nodes)
+// ---------------------------------------------------------------------------
+
+export interface McpServerRecord {
+  id: string;
+  tenantId: string;
+  name: string;
+  transport: "stdio" | "http";
+  command?: string;
+  args?: string[];
+  url?: string;
+  /** Values may be cred:<credentialId> references resolved at connect time. */
+  env?: Record<string, string>;
+  headers?: Record<string, string>;
+  enabled: boolean;
+  status: "unknown" | "ok" | "error";
+  lastTestedAt?: number;
+  lastError?: string;
+  toolCount: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface McpTestResult {
+  ok: boolean;
+  toolCount?: number;
+  tools?: Array<{ name: string; description?: string; inputSchema?: unknown }>;
+  error?: string;
+  latencyMs: number;
+}