runward 0.14.1 → 0.15.0

package/examples/request-triage/code/src/core/application/triage-request.usecase.ts

@@ -0,0 +1,195 @@
+// Orchestrator use case: the floor of the request-triage mission
+// (../../runward/floor.md). One short dependent sequence (ADR-0001):
+// validate -> model proposes -> deterministic guard verifies/recomputes ->
+// route. The orchestrator composes; the business rules live in the domain
+// (guard) and at the boundaries (routing invariants).
+//
+// Compliance is fail-closed WITHOUT freezing the process: the validated
+// record is serialized as a pending routing and the call returns
+// "suspended"; resumeTriage() rehydrates it on the human decision. Approve
+// routes with the approval recorded; reject means the routing never happens.
+
+import {
+  InboundRequestSchema,
+  QUEUE_BY_CATEGORY,
+  REVIEW_QUEUE,
+  type InboundRequest,
+  type TriageRecord,
+  type TriageResult,
+} from "../domain/triage.js";
+import {
+  guardCategory,
+  guardFields,
+  buildApprovalSummary,
+} from "../domain/guard.js";
+import type { TriageModelPort } from "../ports/model-provider.port.js";
+import type { AccountRegistryPort } from "../ports/account-registry.port.js";
+import type { RoutingPort } from "../ports/routing.port.js";
+import type { TriageLogPort } from "../ports/triage-log.port.js";
+
+export interface TriageDeps {
+  model: TriageModelPort;
+  registry: AccountRegistryPort;
+  routing: RoutingPort;
+  log: TriageLogPort;
+  clock: { nowIso(): string };
+}
+
+export class TriageRequestUseCase {
+  constructor(private readonly deps: TriageDeps) {}
+
+  async triage(rawInput: InboundRequest): Promise<TriageResult> {
+    const { model, registry, routing, log, clock } = this.deps;
+
+    // 1. Validation at the boundary: never trust the input.
+    const parsed = InboundRequestSchema.safeParse(rawInput);
+    if (!parsed.success) {
+      throw new Error(
+        `Invalid request: ${parsed.error.issues.map((i) => i.message).join("; ")}`,
+      );
+    }
+    const input = parsed.data;
+    await log.append(input.requestId, {
+      at: clock.nowIso(),
+      event: "received",
+      detail: `from=${input.senderAddress}`,
+    });
+
+    // 2. The model proposes. Everything it returns is a hypothesis.
+    const proposal = await model.propose(input.body);
+
+    // 3. Deterministic guard (ADR-0002): closed vocabulary, registry
+    //    resolution, deadline re-parsed from the source text.
+    const category = guardCategory(proposal.category);
+    const guarded = guardFields(proposal, input.body, registry);
+
+    const record: TriageRecord = {
+      requestId: input.requestId,
+      category,
+      confidence: proposal.confidence,
+      ...(guarded.accountRef ? { accountRef: guarded.accountRef } : {}),
+      ...(guarded.deadline ? { deadline: guarded.deadline } : {}),
+    };
+
+    // 4. Abstention is a first-class answer: an unknown category or a low
+    //    confidence never routes — human review, not a plausible guess.
+    if (category === "unknown" || proposal.confidence === "low") {
+      const reason = "abstention: category unknown or confidence too low";
+      await log.append(input.requestId, {
+        at: clock.nowIso(),
+        event: "escalated",
+        detail: reason,
+      });
+      return { record, status: "needs_review", targetQueue: REVIEW_QUEUE, reason };
+    }
+
+    // 5. Guard escalation: a proposed value that failed verification never
+    //    routes (fail-closed) — review is cheaper than misrouting.
+    if (guarded.escalations.length > 0) {
+      const reason = guarded.escalations.join("; ");
+      await log.append(input.requestId, {
+        at: clock.nowIso(),
+        event: "escalated",
+        detail: reason,
+      });
+      return { record, status: "needs_review", targetQueue: REVIEW_QUEUE, reason };
+    }
+
+    const targetQueue = QUEUE_BY_CATEGORY[category];
+
+    // 6. Compliance: approval required, always (the mission's attached
+    //    condition: no silent miss). Suspend, do not block: serialize the
+    //    validated record and free the process. The summary the approver
+    //    sees is deterministic, built from the validated fields.
+    if (category === "compliance") {
+      const summary = buildApprovalSummary(
+        input.requestId,
+        category,
+        targetQueue,
+        record.accountRef,
+        record.deadline,
+      );
+      await log.setPending(input.requestId, {
+        record,
+        targetQueue,
+        summary,
+        suspendedAt: clock.nowIso(),
+      });
+      await log.append(input.requestId, {
+        at: clock.nowIso(),
+        event: "suspended",
+        detail: summary,
+      });
+      return { record, status: "suspended", targetQueue, reason: summary };
+    }
+
+    // 7. Support / sales: route directly through the guarded port.
+    const confirmation = await routing.assign(record, targetQueue);
+    await log.append(input.requestId, {
+      at: clock.nowIso(),
+      event: "routed",
+      detail: `queue=${confirmation.queue} ticket=${confirmation.ticketRef}`,
+    });
+    return {
+      record,
+      status: "routed",
+      targetQueue: confirmation.queue,
+      ticketRef: confirmation.ticketRef,
+    };
+  }
+
+  // Rehydrates a suspended compliance record on the human decision.
+  // "approve" routes it with the approval recorded; "reject" ends it — the
+  // routing never happens.
+  async resumeTriage(
+    requestId: string,
+    decision: "approve" | "reject",
+    decidedBy: string,
+  ): Promise<TriageResult> {
+    const { routing, log, clock } = this.deps;
+
+    const pending = await log.getPending(requestId);
+    if (!pending) {
+      throw new Error(`Request "${requestId}" is not suspended.`);
+    }
+
+    await log.append(requestId, {
+      at: clock.nowIso(),
+      event: "approval_decision",
+      detail: `${decision} by=${decidedBy}`,
+    });
+
+    if (decision === "reject") {
+      await log.clearPending(requestId);
+      await log.append(requestId, {
+        at: clock.nowIso(),
+        event: "rejected",
+        detail: "routing never executed",
+      });
+      return {
+        record: pending.record,
+        status: "rejected",
+        targetQueue: pending.targetQueue,
+        reason: `approval rejected by ${decidedBy}`,
+      };
+    }
+
+    // Approve: route the EXACT serialized record, approval recorded.
+    const confirmation = await routing.assign(pending.record, pending.targetQueue, {
+      approvedBy: decidedBy,
+      at: clock.nowIso(),
+    });
+    await log.clearPending(requestId);
+    await log.append(requestId, {
+      at: clock.nowIso(),
+      event: "routed",
+      detail: `queue=${confirmation.queue} ticket=${confirmation.ticketRef} approved_by=${decidedBy}`,
+    });
+    return {
+      record: pending.record,
+      status: "routed",
+      targetQueue: confirmation.queue,
+      ticketRef: confirmation.ticketRef,
+    };
+  }
+}

package/examples/request-triage/code/src/core/domain/guard.ts

@@ -0,0 +1,121 @@
+// Deterministic guard on model-extracted fields (ADR-0002). Pure functions,
+// unit-testable without a model in the loop.
+//
+// The rule: THE MODEL NEVER SUPPLIES A VALUE THE SYSTEM CAN COMPUTE OR
+// VERIFY ITSELF. Concretely:
+//   - an account reference is resolved against the account registry; a
+//     reference that does not resolve is never routed on — the record
+//     escalates to human review with the reason attached;
+//   - a deadline is re-parsed from the source text by a deterministic
+//     parser; the model's proposal is DISCARDED in favor of the parsed
+//     value, whatever the model said;
+//   - the category must belong to the closed vocabulary; anything else is
+//     treated as "unknown" (abstention), never as a new category.
+
+import {
+  CategorySchema,
+  type Category,
+  type TriageField,
+} from "./triage.js";
+import type { AccountRegistryPort } from "../ports/account-registry.port.js";
+import type { TriageProposal } from "../ports/model-provider.port.js";
+
+// ----------------------------------------------------------------------------
+// Deterministic deadline parser. Reads ISO dates (YYYY-MM-DD) from the raw
+// source text and validates them as real calendar dates. Returns the first
+// valid one, normalized, or null. No model involved.
+// ----------------------------------------------------------------------------
+const ISO_DATE = /\b(\d{4})-(\d{2})-(\d{2})\b/g;
+
+export function parseDeadline(sourceText: string): string | null {
+  for (const m of sourceText.matchAll(ISO_DATE)) {
+    const [raw, y, mo, d] = m;
+    const year = Number(y);
+    const month = Number(mo);
+    const day = Number(d);
+    // Real calendar date, not just a well-shaped string.
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (
+      date.getUTCFullYear() === year &&
+      date.getUTCMonth() === month - 1 &&
+      date.getUTCDate() === day
+    ) {
+      return raw;
+    }
+  }
+  return null;
+}
+
+// ----------------------------------------------------------------------------
+// Category guard: closed vocabulary or abstention.
+// ----------------------------------------------------------------------------
+export function guardCategory(proposed: unknown): Category {
+  const parsed = CategorySchema.safeParse(proposed);
+  return parsed.success ? parsed.data : "unknown";
+}
+
+// ----------------------------------------------------------------------------
+// Field guard: promote, recompute, or escalate.
+// ----------------------------------------------------------------------------
+export interface GuardedFields {
+  accountRef?: TriageField & { accountName?: string };
+  deadline?: TriageField;
+  // Non-empty when a proposed value failed verification: the record must
+  // escalate to human review instead of routing (fail-closed).
+  escalations: string[];
+}
+
+export function guardFields(
+  proposal: TriageProposal,
+  sourceText: string,
+  registry: AccountRegistryPort,
+): GuardedFields {
+  const out: GuardedFields = { escalations: [] };
+
+  // Account reference: verified against the registry or never routed on.
+  const proposedRef = proposal.fields.find((f) => f.name === "accountRef");
+  if (proposedRef) {
+    const account = registry.resolve(proposedRef.value);
+    if (account) {
+      out.accountRef = {
+        value: account.ref,
+        provenance: "verified",
+        accountName: account.name,
+      };
+    } else {
+      out.escalations.push(
+        `unverified account reference "${proposedRef.value}" (not in registry)`,
+      );
+    }
+  }
+
+  // Deadline: recomputed from the source text; the model's value is
+  // discarded even when present, even when it looks right.
+  const parsed = parseDeadline(sourceText);
+  if (parsed) {
+    out.deadline = { value: parsed, provenance: "computed" };
+  }
+
+  return out;
+}
+
+// ----------------------------------------------------------------------------
+// Deterministic approval summary for a suspended compliance record: a pure
+// function of the validated fields, never a model reformulation.
+// ----------------------------------------------------------------------------
+export function buildApprovalSummary(
+  requestId: string,
+  category: Category,
+  targetQueue: string,
+  accountRef?: TriageField,
+  deadline?: TriageField,
+): string {
+  const parts = [
+    `Approval required: route request "${requestId}"`,
+    `category=${category}`,
+    `queue=${targetQueue}`,
+    `accountRef=${accountRef ? `${accountRef.value} (${accountRef.provenance})` : "none"}`,
+    `deadline=${deadline ? `${deadline.value} (${deadline.provenance})` : "none"}`,
+  ];
+  return parts.join(" | ");
+}

package/examples/request-triage/code/src/core/domain/triage.ts

@@ -0,0 +1,88 @@
+// Pure triage domain. Zero framework, zero I/O; zod is used as a schema
+// library only. Mirrors the TriageRecord v1.0 contract of the mission
+// documents (../../runward/architecture.md §3): closed category vocabulary,
+// provenance-marked fields, target queue, confidence level.
+
+import { z } from "zod";
+
+// ----------------------------------------------------------------------------
+// Closed category vocabulary. Anything else is a validation failure, not a
+// new category (contracts/model-port.md). "unknown" is a first-class answer:
+// abstention beats a plausible guess.
+// ----------------------------------------------------------------------------
+export const CATEGORIES = ["support", "sales", "compliance", "unknown"] as const;
+export const CategorySchema = z.enum(CATEGORIES);
+export type Category = z.infer<typeof CategorySchema>;
+
+export const ConfidenceSchema = z.enum(["high", "medium", "low"]);
+export type Confidence = z.infer<typeof ConfidenceSchema>;
+
+// ----------------------------------------------------------------------------
+// Provenance markers (ADR-0002). A model output is a hypothesis, never a
+// fact: it enters the system marked "model-proposed" and nothing acts on it
+// until the deterministic guard has promoted it to "verified" (checked
+// against a source of truth) or replaced it with a "computed" value.
+// ----------------------------------------------------------------------------
+export const ProvenanceSchema = z.enum(["computed", "verified", "model-proposed"]);
+export type Provenance = z.infer<typeof ProvenanceSchema>;
+
+export interface TriageField {
+  value: string;
+  provenance: Provenance;
+}
+
+// ----------------------------------------------------------------------------
+// Input entity: one raw inbound request (contracts/request-intake.md,
+// reduced). The body is untrusted free text by definition. strict(): no
+// smuggled keys cross the boundary.
+// ----------------------------------------------------------------------------
+export const InboundRequestSchema = z
+  .object({
+    requestId: z.string().min(1, "A request identifier cannot be empty."),
+    senderAddress: z.string().min(3),
+    body: z.string().min(1, "The body cannot be empty.").max(8000),
+  })
+  .strict();
+export type InboundRequest = z.infer<typeof InboundRequestSchema>;
+
+// ----------------------------------------------------------------------------
+// Output entity: the validated triage record. Every field that can drive an
+// action carries a provenance marker; the routing port refuses, fail-closed,
+// any action-bearing field still "model-proposed".
+// ----------------------------------------------------------------------------
+export type TriageStatus =
+  | "routed" // assigned to a team queue through the routing port
+  | "suspended" // compliance: awaiting human approval (fail-closed, not frozen)
+  | "needs_review" // abstention or guard escalation: human review queue
+  | "rejected"; // approval denied on resume: never routed
+
+export interface TriageRecord {
+  requestId: string;
+  category: Category;
+  confidence: Confidence;
+  // Resolved against the account registry, or absent. Never model-trusted.
+  accountRef?: TriageField & { accountName?: string };
+  // Re-parsed deterministically from the source text, or absent. The model's
+  // proposal for this field is always discarded (ADR-0002).
+  deadline?: TriageField;
+}
+
+export interface TriageResult {
+  record: TriageRecord;
+  status: TriageStatus;
+  targetQueue: string;
+  // Present when routed: the ticketing reference returned by the port.
+  ticketRef?: string;
+  // Present when suspended or escalated: why a human is in the loop.
+  reason?: string;
+}
+
+// Queue resolution is deterministic policy, never a model output.
+export const QUEUE_BY_CATEGORY: Record<Category, string> = {
+  support: "support-queue",
+  sales: "sales-queue",
+  compliance: "compliance-queue",
+  unknown: "review-queue",
+};
+
+export const REVIEW_QUEUE = "review-queue";

package/examples/request-triage/code/src/core/ports/account-registry.port.ts

@@ -0,0 +1,15 @@
+// Secondary port: the account registry, a deterministic source of truth.
+// The guard resolves every model-proposed account reference against it: a
+// reference that does not resolve is never routed on (ADR-0002). The model
+// cannot mint an account into existence.
+
+export interface Account {
+  ref: string;
+  name: string;
+}
+
+export interface AccountRegistryPort {
+  // Returns the account when the reference exists, null otherwise. Pure
+  // lookup: no fuzzy matching, no repair of a fabricated reference.
+  resolve(ref: string): Account | null;
+}

package/examples/request-triage/code/src/core/ports/model-provider.port.ts

@@ -0,0 +1,26 @@
+// Secondary port: the model proposes, it never decides
+// (../../runward/contracts/model-port.md). The output is a hypothesis: a
+// closed-vocabulary category, field extractions each carrying the span of
+// source text they were read from, and a confidence level. Everything is
+// provenance-marked "model-proposed" by construction; nothing downstream may
+// act on it before the deterministic guard (ADR-0002).
+
+import type { Category, Confidence } from "../domain/triage.js";
+
+export interface ProposedField {
+  name: "accountRef" | "deadline";
+  value: string;
+  // Span of source text the value was read from. A value with no span is
+  // rejected at the schema boundary.
+  sourceSpan: string;
+}
+
+export interface TriageProposal {
+  category: Category;
+  fields: ProposedField[];
+  confidence: Confidence;
+}
+
+export interface TriageModelPort {
+  propose(requestText: string): Promise<TriageProposal>;
+}

package/examples/request-triage/code/src/core/ports/routing.port.ts

@@ -0,0 +1,32 @@
+// Secondary port: the system's only action on the world
+// (../../runward/contracts/routing-port.md). Assign one validated triage
+// record to a queue. The most guarded boundary: it acts on verified facts
+// only and fails closed.
+//
+// Invariants the adapter must hold:
+//   - refuse any record whose action-bearing fields are still
+//     "model-proposed" (fail-closed on provenance, ADR-0002);
+//   - never assign a compliance-flagged record without a recorded approval;
+//   - idempotent on requestId (no duplicate tickets).
+
+import type { TriageRecord } from "../domain/triage.js";
+
+export interface RoutingApproval {
+  approvedBy: string;
+  at: string; // ISO timestamp
+}
+
+export interface RoutingConfirmation {
+  ticketRef: string;
+  routedAt: string; // ISO timestamp, UTC
+  queue: string;
+  approval?: RoutingApproval;
+}
+
+export interface RoutingPort {
+  assign(
+    record: TriageRecord,
+    targetQueue: string,
+    approval?: RoutingApproval,
+  ): Promise<RoutingConfirmation>;
+}

package/examples/request-triage/code/src/core/ports/triage-log.port.ts

@@ -0,0 +1,33 @@
+// Secondary port: persistence of triage decisions
+// (../../runward/contracts/persistence-port.md, reduced). An append-only
+// journal keyed by request id, plus the serialized suspension point of a
+// compliance record awaiting human approval (suspend-and-rehydrate: the
+// process is freed, the decision rehydrates the run).
+
+import type { TriageRecord } from "../domain/triage.js";
+
+export interface TriageLogEntry {
+  at: string; // ISO timestamp
+  event: string;
+  detail: string;
+}
+
+// Serialized suspension point: the exact validated record and target queue,
+// plus a deterministic summary built by code from the real fields — never a
+// model reformulation.
+export interface PendingRouting {
+  record: TriageRecord;
+  targetQueue: string;
+  summary: string;
+  suspendedAt: string;
+}
+
+export interface TriageLogPort {
+  append(requestId: string, entry: TriageLogEntry): Promise<void>;
+  read(requestId: string): Promise<TriageLogEntry[]>;
+  // Suspension point management. setPending throws if one already exists
+  // (a record is suspended at most once at a time).
+  setPending(requestId: string, pending: PendingRouting): Promise<void>;
+  getPending(requestId: string): Promise<PendingRouting | null>;
+  clearPending(requestId: string): Promise<void>;
+}

package/examples/request-triage/code/src/demo.ts

@@ -0,0 +1,80 @@
+// End-to-end demo of the triage floor. Four inbound requests: a support
+// issue, a sales inquiry, a compliance request (suspends, then approved),
+// and one the system abstains on. No network, no key: the model adapter is
+// the deterministic keyword classifier.
+//
+// Run: npm run demo
+
+import { TriageRequestUseCase } from "./core/application/triage-request.usecase.js";
+import { KeywordModelAdapter } from "./adapters/keyword-model.adapter.js";
+import { HardcodedAccountRegistry } from "./adapters/hardcoded-account-registry.adapter.js";
+import { InMemoryRoutingAdapter } from "./adapters/in-memory-routing.adapter.js";
+import { InMemoryTriageLog } from "./adapters/in-memory-triage-log.adapter.js";
+
+async function main(): Promise<void> {
+  const log = new InMemoryTriageLog();
+  const useCase = new TriageRequestUseCase({
+    model: new KeywordModelAdapter(),
+    registry: new HardcodedAccountRegistry(),
+    routing: new InMemoryRoutingAdapter(),
+    log,
+    clock: { nowIso: () => new Date().toISOString() },
+  });
+
+  const samples = [
+    {
+      requestId: "req-001",
+      senderAddress: "jane@acme.example",
+      body: "Our dashboard crashes with an error on login. Account ACC-1001. Please help.",
+    },
+    {
+      requestId: "req-002",
+      senderAddress: "buyer@globex.example",
+      body: "Could we get a pricing quote for the enterprise plan? Account ACC-2002.",
+    },
+    {
+      requestId: "req-003",
+      senderAddress: "dpo@initech.example",
+      body: "GDPR data deletion request for account ACC-3003, response required by 2026-08-01.",
+    },
+    {
+      requestId: "req-004",
+      senderAddress: "someone@example.org",
+      body: "Following up on the thing we discussed last month.",
+    },
+    {
+      // A plausible-looking account reference the model extracted, that the
+      // registry does not know: exactly what an LLM fabricates most fluently.
+      // The deterministic guard refuses to route on it (ADR-0002), fail-closed.
+      requestId: "req-005",
+      senderAddress: "mallory@acme.example",
+      body: "Our dashboard crashes with an error on every login. Account ACC-7777, please help urgently.",
+    },
+  ];
+
+  for (const sample of samples) {
+    const result = await useCase.triage(sample);
+    console.log(
+      `${sample.requestId}: category=${result.record.category} status=${result.status} queue=${result.targetQueue}` +
+        (result.ticketRef ? ` ticket=${result.ticketRef}` : "") +
+        (result.reason ? `\n  reason: ${result.reason}` : ""),
+    );
+  }
+
+  // The compliance request suspended: a human approves, the run rehydrates.
+  console.log("\nApproving the suspended compliance request (req-003)...");
+  const resumed = await useCase.resumeTriage("req-003", "approve", "ops-coordinator");
+  console.log(
+    `req-003: status=${resumed.status} queue=${resumed.targetQueue} ticket=${resumed.ticketRef}`,
+  );
+
+  console.log("\nJournal of req-003:");
+  for (const entry of await log.read("req-003")) {
+    console.log(`  [${entry.event}] ${entry.detail}`);
+  }
+}
+
+main().catch((err) => {
+  console.error("Demo failed:", err);
+  process.exit(1);
+});