《互联网产品的 AI 架构·多能力编排与任务闭环》2.1 能力之间的数据契约

// file: src/orch/handoff.ts
// tier: L1
// verify: node --test test/orch/handoff.test.ts

import { AiError } from "../core/errors.ts";

/** 四类载体：payload 必传，reference 传指针，summary 传压缩语义，cursor 传续跑位置。 */
export type ContextCarrier = "payload" | "reference" | "summary" | "cursor";

export interface ContractField {
  name: string;
  carrier: ContextCarrier;
  required: boolean;
  source: string;
  since: string;
  changedIn: string;
  onViolation: "reject" | "degrade" | "repair";
}

export interface NodeContract {
  nodeId: string;
  capability: string;
  version: string;
  fields: readonly ContractField[];
  /** 必须能在外存中解析到同一 revision 的引用 id。 */
  references: readonly string[];
  /** 不在节点间复制、只按前缀复用的稳定上下文块。 */
  sharedBlocks: readonly string[];
  maxSummaryTokens: number;
  maxCursorBytes: number;
}

export interface PayloadReference {
  id: string;
  revision: string;
  checksum: string;
}

export interface NodeEnvelope {
  contractVersion: string;
  runId: string;
  from: string;
  to: string;
  payload: Record<string, unknown>;
  references: readonly PayloadReference[];
  summary?: { text: string; tokens: number };
  cursor?: { step: string; offset: number };
  budgetMicros: number;
  deadlineMs: number;
}

export type ContractIssueCode =
  | "missing-field"
  | "unknown-field"
  | "reference-missing"
  | "reference-unknown"
  | "reference-invalid"
  | "reference-duplicate"
  | "summary-too-long"
  | "cursor-too-large"
  | "budget-negative"
  | "deadline-invalid"
  | "version-mismatch";

export interface ContractIssue {
  path: string;
  code: ContractIssueCode;
  expected: string;
  actual: string;
}

export type VersionDecision =
  | { ok: true; mode: "exact" | "backward-compatible" }
  | { ok: false; reason: "major-mismatch" | "sender-newer-minor" | "invalid-version"; detail: string };

const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;

export function parseVersion(
  version: string,
): { major: number; minor: number; patch: number } | null {
  const match = VERSION.exec(version);
  return match === null ? null : { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
}

/** 大版本必须相同；发送方次版本更高时接收方可能不认识新字段，直接拒绝。 */
export function checkVersionCompatibility(producer: string, consumer: string): VersionDecision {
  const left = parseVersion(producer);
  const right = parseVersion(consumer);
  if (left === null || right === null) {
    return { ok: false, reason: "invalid-version", detail: `producer=${producer} consumer=${consumer}` };
  }
  if (left.major !== right.major) {
    return { ok: false, reason: "major-mismatch", detail: `producer=${producer} consumer=${consumer}` };
  }
  if (left.minor > right.minor) {
    return { ok: false, reason: "sender-newer-minor", detail: `producer=${producer} consumer=${consumer}` };
  }
  return { ok: true, mode: left.minor < right.minor ? "backward-compatible" : "exact" };
}

function push(issues: ContractIssue[], path: string, code: ContractIssueCode, expected: string, actual: unknown): void {
  issues.push({ path, code, expected, actual: String(actual) });
}

function compareText(a: string, b: string): number {
  return a < b ? -1 : a > b ? 1 : 0;
}

/** 校验只收集问题、不抛异常：节点输出不合契约是预期事件。 */
export function validateEnvelope(contract: NodeContract, envelope: NodeEnvelope): ContractIssue[] {
  const issues: ContractIssue[] = [];
  const declared = new Map(contract.fields.map((field) => [field.name, field]));

  if (envelope.runId.trim() === "") push(issues, "$.runId", "missing-field", "non-empty", envelope.runId);
  if (envelope.from.trim() === "") push(issues, "$.from", "missing-field", "non-empty", envelope.from);
  if (envelope.to.trim() === "") push(issues, "$.to", "missing-field", "non-empty", envelope.to);
  if (!checkVersionCompatibility(envelope.contractVersion, contract.version).ok) {
    push(issues, "$.contractVersion", "version-mismatch", contract.version, envelope.contractVersion);
  }
  if (!Number.isInteger(envelope.budgetMicros) || envelope.budgetMicros < 0) {
    push(issues, "$.budgetMicros", "budget-negative", "integer >= 0", envelope.budgetMicros);
  }
  if (!Number.isFinite(envelope.deadlineMs) || envelope.deadlineMs <= 0) {
    push(issues, "$.deadlineMs", "deadline-invalid", "finite > 0", envelope.deadlineMs);
  }

  for (const field of contract.fields) {
    if (!field.required) continue;
    if (field.carrier === "payload") {
      const value = envelope.payload[field.name];
      if (value === undefined || value === null || value === "") {
        push(issues, `$.payload.${field.name}`, "missing-field", "present", "missing");
      }
    } else if (field.carrier === "reference") {
      if (!envelope.references.some((reference) => reference.id === field.name)) {
        push(issues, `$.references.${field.name}`, "reference-missing", "present", "missing");
      }
    } else if (field.carrier === "summary") {
      if (envelope.summary === undefined || envelope.summary.text.trim() === "") {
        push(issues, "$.summary", "missing-field", "present", "missing");
      }
    } else if (envelope.cursor === undefined) {
      push(issues, "$.cursor", "missing-field", "present", "missing");
    }
  }

  for (const key of Object.keys(envelope.payload)) {
    if (!declared.has(key)) push(issues, `$.payload.${key}`, "unknown-field", "declared field", key);
  }

  if (envelope.summary !== undefined) {
    const { text, tokens } = envelope.summary;
    if (text.trim() === "") push(issues, "$.summary.text", "missing-field", "non-empty", text);
    if (!Number.isInteger(tokens) || tokens < 0) {
      push(issues, "$.summary.tokens", "summary-too-long", "integer >= 0", tokens);
    } else if (tokens > contract.maxSummaryTokens) {
      push(issues, "$.summary.tokens", "summary-too-long", `<= ${contract.maxSummaryTokens}`, tokens);
    }
  }

  if (envelope.cursor !== undefined) {
    const bytes = new TextEncoder().encode(JSON.stringify(envelope.cursor)).length;
    if (bytes > contract.maxCursorBytes) {
      push(issues, "$.cursor", "cursor-too-large", `<= ${contract.maxCursorBytes} bytes`, bytes);
    }
  }

  const allowed = new Set(contract.references);
  const seen = new Set<string>();
  envelope.references.forEach((reference, index) => {
    const path = `$.references[${index}]`;
    if (reference.id.trim() === "" || reference.revision.trim() === "") {
      push(issues, path, "reference-invalid", "id and revision", reference.id);
      return;
    }
    if (!allowed.has(reference.id)) push(issues, path, "reference-unknown", "declared reference", reference.id);
    if (seen.has(reference.id)) push(issues, path, "reference-duplicate", "unique id", reference.id);
    seen.add(reference.id);
    if (reference.checksum.trim() === "") {
      push(issues, `${path}.checksum`, "reference-invalid", "non-empty", "missing");
    }
  });
  for (const id of contract.references) {
    if (!seen.has(id)) push(issues, `$.references.${id}`, "reference-missing", "present", "missing");
  }

  issues.sort((a, b) => compareText(a.path, b.path) || compareText(a.code, b.code));
  return issues;
}

export function describeIssues(issues: readonly ContractIssue[]): string {
  return issues.map((issue) => `${issue.path} ${issue.code} expected=${issue.expected} actual=${issue.actual}`).join("; ");
}

export function assertEnvelope(contract: NodeContract, envelope: NodeEnvelope): void {
  const issues = validateEnvelope(contract, envelope);
  if (issues.length > 0) throw new AiError("invalid-request", `handoff: ${describeIssues(issues)}`);
}

export interface TransportPlan {
  inline: string[];
  referenced: string[];
  summarized: string[];
  cursored: string[];
  /** 共享块为空时，只传交接包也能保证下游看到全部必需上下文。 */
  passSafe: boolean;
}

export function planTransport(contract: NodeContract): TransportPlan {
  const plan: TransportPlan = {
    inline: [],
    referenced: [],
    summarized: [],
    cursored: [],
    passSafe: contract.sharedBlocks.length === 0,
  };
  for (const field of contract.fields) {
    if (!field.required) continue;
    if (field.carrier === "payload") plan.inline.push(field.name);
    else if (field.carrier === "reference") plan.referenced.push(field.name);
    else if (field.carrier === "summary") plan.summarized.push(field.name);
    else plan.cursored.push(field.name);
  }
  return plan;
}

export function passModeAllowed(contract: NodeContract): boolean {
  return contract.sharedBlocks.length === 0;
}

export function summarizeContract(contract: NodeContract): {
  required: number;
  optional: number;
  references: number;
  sharedBlocks: number;
} {
  return {
    required: contract.fields.filter((field) => field.required).length,
    optional: contract.fields.filter((field) => !field.required).length,
    references: contract.references.length,
    sharedBlocks: contract.sharedBlocks.length,
  };
}