@trucore/openclaw-atf 0.1.0 → 0.2.0

package/src/contracts/result_builder.mjs

@@ -0,0 +1,132 @@
+/**
+ * result_builder.mjs — Universal ATF result builder
+ *
+ * Builds platform-agnostic result objects for ATF tool responses.
+ * This is the UNIVERSAL layer — adapters wrap these results in their
+ * transport-specific envelopes.
+ *
+ * Separation of concerns:
+ *   - result_builder.mjs  → universal result shape (this file)
+ *   - tool_response.mjs   → OpenClaw-specific envelope wrapping
+ *   - future CLI adapter   → stdout JSON formatting
+ *   - future API adapter   → HTTP response mapping
+ *
+ * Exports:
+ *   - buildResult(toolName, status, result, meta?)    → UniversalResult
+ *   - buildErrorResult(toolName, message, opts?)      → UniversalErrorResult
+ *   - buildMeta(toolName, opts?)                      → ResultMeta
+ *
+ * No dependencies beyond sibling status_codes. No side effects.
+ */
+
+import { RESPONSE_STATUS } from "./status_codes.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants — canonical identity
+// ---------------------------------------------------------------------------
+
+/** Canonical product identity. */
+const PRODUCT_ID = "trucore-atf";
+
+/** Product version — kept in sync by version consistency tests. */
+const PRODUCT_VERSION = "0.2.0";
+
+// ---------------------------------------------------------------------------
+// Meta builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build standard metadata for a tool result.
+ *
+ * @param {string} toolName   Name of the tool producing the result.
+ * @param {object} [opts]     Optional metadata overrides.
+ * @param {object} [opts.backend]    Backend resolution info.
+ * @param {string[]} [opts.warnings] Warnings for operator.
+ * @returns {{ product_id: string, product_version: string, tool: string, ts: string, backend?: object, warnings?: string[] }}
+ */
+export function buildMeta(toolName, opts = {}) {
+  const meta = {
+    product_id: PRODUCT_ID,
+    product_version: PRODUCT_VERSION,
+    tool: toolName,
+    ts: new Date().toISOString(),
+  };
+
+  if (opts.backend && typeof opts.backend === "object") {
+    meta.backend = {
+      preferred: opts.backend.preferred_backend ?? opts.backend.preferred ?? "unknown",
+      effective: opts.backend.effective_backend ?? opts.backend.effective ?? "unknown",
+      fallback_occurred: opts.backend.fallback_occurred ?? false,
+      fallback_reason: opts.backend.fallback_reason ?? null,
+    };
+  }
+
+  if (Array.isArray(opts.warnings) && opts.warnings.length > 0) {
+    meta.warnings = [...opts.warnings];
+  }
+
+  return meta;
+}
+
+// ---------------------------------------------------------------------------
+// Success result builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a universal ATF success result.
+ *
+ * This is the platform-agnostic result object. Adapters wrap this in
+ * their own envelope format.
+ *
+ * Universal result shape:
+ *   { status, summary, result, _meta }
+ *
+ * @param {string} toolName   Name of the tool.
+ * @param {string} summary    Human-readable summary.
+ * @param {object} result     Tool-specific result data.
+ * @param {object} [opts]     Optional overrides.
+ * @param {string} [opts.status]    RESPONSE_STATUS value (default: "ok").
+ * @param {object} [opts.backend]   Backend resolution info.
+ * @param {string[]} [opts.warnings] Warnings.
+ * @returns {{ status: string, summary: string, result: object, _meta: object }}
+ */
+export function buildResult(toolName, summary, result, opts = {}) {
+  return {
+    status: opts.status ?? RESPONSE_STATUS.OK,
+    summary,
+    result: result ?? {},
+    _meta: buildMeta(toolName, opts),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error result builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a universal ATF error result.
+ *
+ * Universal error shape:
+ *   { status: "error", error, remediation?, _meta }
+ *
+ * @param {string} toolName       Name of the tool.
+ * @param {string} message        Error message.
+ * @param {object} [opts]         Optional overrides.
+ * @param {object} [opts.backend]      Backend resolution info.
+ * @param {string[]} [opts.warnings]   Warnings.
+ * @param {string[]} [opts.remediation] Fix instructions.
+ * @returns {{ status: string, error: string, remediation?: string[], _meta: object }}
+ */
+export function buildErrorResult(toolName, message, opts = {}) {
+  const payload = {
+    status: RESPONSE_STATUS.ERROR,
+    error: message,
+    _meta: buildMeta(toolName, opts),
+  };
+
+  if (Array.isArray(opts.remediation) && opts.remediation.length > 0) {
+    payload.remediation = [...opts.remediation];
+  }
+
+  return payload;
+}

package/src/contracts/schemas.mjs

@@ -0,0 +1,402 @@
+/**
+ * schemas.mjs — Universal ATF contract family definitions
+ *
+ * Defines the canonical request/response shapes for each ATF contract
+ * family. These are platform-agnostic — any adapter (OpenClaw, CLI, API,
+ * SDK, future UI) can map to/from these shapes.
+ *
+ * This module defines STRUCTURE, not runtime logic. Think of it as
+ * the "interface declarations" for ATF contracts.
+ *
+ * Contract families:
+ *   1. READINESS   — health, doctor, preflight
+ *   2. ADVISORY    — adoption advisor, bot preflight
+ *   3. EXPLANATION — tx_explain
+ *   4. BILLING     — billing_info, billing_claim
+ *   5. DISCOVERY   — discover, bootstrap_plan
+ *   6. PROTECTION  — protect_intent, verify_receipt, report_savings
+ *
+ * Exports:
+ *   - CONTRACT_FAMILIES        — frozen family metadata
+ *   - UNIVERSAL_RESULT_FIELDS  — fields present in every universal result
+ *   - ADAPTER_ENVELOPE_FIELDS  — fields added by adapters (not universal)
+ *   - TOOL_FAMILY_MAP          — maps each tool to its contract family
+ *
+ * No dependencies. No side effects. Pure constants.
+ */
+
+// ---------------------------------------------------------------------------
+// Contract families
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical ATF contract families.
+ *
+ * Each family groups tools that share similar request/response patterns.
+ * Future adapters map their transport-specific inputs/outputs to these
+ * canonical shapes.
+ */
+export const CONTRACT_FAMILIES = Object.freeze({
+  READINESS: Object.freeze({
+    family_id: "readiness",
+    purpose:
+      "Check ATF availability, integration health, and pre-session readiness.",
+    tools: Object.freeze([
+      "atf_health",
+      "atf_integration_doctor",
+      "atf_bot_preflight",
+    ]),
+    canonical_request: Object.freeze({
+      description: "No required input. Config is read from environment.",
+      fields: Object.freeze({}),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "Structured readiness signal with backend availability, " +
+        "config validity, warnings, and remediation steps.",
+      required_fields: Object.freeze([
+        "status",
+        "warnings",
+        "remediation",
+      ]),
+      optional_fields: Object.freeze([
+        "ready",
+        "healthy",
+        "backend_ready",
+        "config_valid",
+        "cli_available",
+        "api_available",
+        "native_tools_expected",
+        "native_tools_available",
+        "native_tools_missing",
+        "config_errors",
+        "config_warnings",
+      ]),
+    }),
+  }),
+
+  ADVISORY: Object.freeze({
+    family_id: "advisory",
+    purpose:
+      "Evaluate signals and return deterministic adoption/installation recommendations.",
+    tools: Object.freeze(["atf_adoption_advisor"]),
+    canonical_request: Object.freeze({
+      description:
+        "Map of trigger_id → boolean signals indicating bot capabilities.",
+      fields: Object.freeze({
+        signals: {
+          type: "object",
+          required: false,
+          description:
+            "Map of trigger_id to boolean. Omit for no-trigger evaluation.",
+        },
+      }),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "Deterministic adoption recommendation with matched triggers, " +
+        "severity, tier, call sequence, and install guidance.",
+      required_fields: Object.freeze([
+        "install_needed",
+        "recommended_tier",
+        "highest_severity",
+        "matched_triggers",
+      ]),
+      optional_fields: Object.freeze([
+        "unmatched_triggers",
+        "call_sequence",
+        "install_guidance",
+        "next_actions",
+      ]),
+    }),
+  }),
+
+  EXPLANATION: Object.freeze({
+    family_id: "explanation",
+    purpose:
+      "Explain deny decisions and reason codes in human-readable terms.",
+    tools: Object.freeze(["atf_tx_explain"]),
+    canonical_request: Object.freeze({
+      description:
+        "Either an array of reason codes or a receipt/decision object.",
+      fields: Object.freeze({
+        reasonCodes: {
+          type: "string[]",
+          required: false,
+          description: "Array of ATF reason codes to explain.",
+        },
+        receipt: {
+          type: "object",
+          required: false,
+          description:
+            "ATF receipt or decision object with reason_codes field.",
+        },
+      }),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "Structured explanations for each reason code with category " +
+        "and remediation.",
+      required_fields: Object.freeze([
+        "reason_codes",
+        "explanations",
+      ]),
+      optional_fields: Object.freeze([
+        "decision",
+        "receipt_meta",
+      ]),
+    }),
+  }),
+
+  BILLING: Object.freeze({
+    family_id: "billing",
+    purpose:
+      "Discover pricing/package metadata and verify on-chain payment claims.",
+    tools: Object.freeze(["atf_billing_info", "atf_billing_claim"]),
+    canonical_request: Object.freeze({
+      description: "For info: optional packageId filter. " +
+        "For claim: tx_signature, wallet, package_id required.",
+      fields: Object.freeze({
+        packageId: {
+          type: "string",
+          required: false,
+          description: "Filter to a specific package (billing_info).",
+        },
+        tx_signature: {
+          type: "string",
+          required: "claim_only",
+          description: "Solana transaction signature (billing_claim).",
+        },
+        wallet: {
+          type: "string",
+          required: "claim_only",
+          description: "Claimant wallet address (billing_claim).",
+        },
+        package_id: {
+          type: "string",
+          required: "claim_only",
+          description: "Package being claimed (billing_claim).",
+        },
+        asset_symbol: {
+          type: "string",
+          required: false,
+          description: "Optional asset hint: USDC or SOL.",
+        },
+        cluster: {
+          type: "string",
+          required: false,
+          description: "Solana cluster (default: mainnet-beta).",
+        },
+      }),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "For info: package/pricing/payment metadata. " +
+        "For claim: deterministic verification result.",
+      required_fields: Object.freeze([
+        "claim_status|packages",
+      ]),
+      optional_fields: Object.freeze([
+        "deny_code",
+        "payment_rails",
+        "activation",
+        "warnings",
+        "remediation",
+        "amount_received",
+        "asset_symbol",
+        "treasury_verified",
+        "payment_verified",
+        "entitlement_status",
+        "free_vs_advanced",
+      ]),
+    }),
+  }),
+
+  DISCOVERY: Object.freeze({
+    family_id: "discovery",
+    purpose:
+      "Discover ATF capabilities, manifest, bootstrap recipes, and toolcard.",
+    tools: Object.freeze([
+      "atf_discover",
+      "atf_bootstrap_plan",
+      "atf_bootstrap_execute_safe",
+    ]),
+    canonical_request: Object.freeze({
+      description: "Optional recipe ID or manifest URL override.",
+      fields: Object.freeze({
+        recipe: {
+          type: "string",
+          required: false,
+          description: "Bootstrap recipe ID.",
+        },
+        manifestUrl: {
+          type: "string",
+          required: false,
+          description: "Override manifest fetch URL.",
+        },
+        dryRun: {
+          type: "boolean",
+          required: false,
+          description: "Preview steps without executing (execute_safe).",
+        },
+      }),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "Manifest summary, bootstrap steps, or execution results.",
+      required_fields: Object.freeze(["status"]),
+      optional_fields: Object.freeze([
+        "id",
+        "version",
+        "capabilities",
+        "recipe_ids",
+        "steps",
+        "exitCode",
+      ]),
+    }),
+  }),
+
+  PROTECTION: Object.freeze({
+    family_id: "protection",
+    purpose:
+      "Evaluate intents against policy, verify receipts, report savings.",
+    tools: Object.freeze([
+      "atf_protect_intent",
+      "atf_verify_receipt",
+      "atf_report_savings",
+    ]),
+    canonical_request: Object.freeze({
+      description:
+        "For protect: intent object. For verify: receipt. " +
+        "For savings: optional receipt count/dir.",
+      fields: Object.freeze({
+        intentJson: {
+          type: "object",
+          required: "protect_only",
+          description: "ATF ExecutionRequest or intent object.",
+        },
+        exposureHints: {
+          type: "object",
+          required: false,
+          description: "Optional exposure hints for savings estimates.",
+        },
+        receipt: {
+          type: "object|string",
+          required: "verify_only",
+          description: "Receipt JSON, string, or file path.",
+        },
+        last: {
+          type: "integer",
+          required: false,
+          description: "Number of recent receipts (report_savings).",
+        },
+        receiptsDir: {
+          type: "string",
+          required: false,
+          description: "Directory containing receipt files.",
+        },
+      }),
+    }),
+    canonical_response: Object.freeze({
+      description:
+        "Allow/deny decision with reason codes, receipt verification, " +
+        "or savings summary.",
+      required_fields: Object.freeze(["status"]),
+      optional_fields: Object.freeze([
+        "allow",
+        "reason_codes",
+        "receipt",
+        "verified",
+        "content_hash",
+        "intent_hash",
+        "total_denied",
+        "by_reason_code",
+        "evidence",
+        "savings_estimate_usd",
+      ]),
+    }),
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Universal result fields — present in every ATF tool result
+// ---------------------------------------------------------------------------
+
+/**
+ * Fields present in every universal ATF tool result.
+ * These are the CORE contract — adapters must preserve them.
+ */
+export const UNIVERSAL_RESULT_FIELDS = Object.freeze([
+  "status",       // RESPONSE_STATUS value
+  "result",       // tool-specific payload
+]);
+
+// ---------------------------------------------------------------------------
+// Adapter envelope fields — added by transport adapters
+// ---------------------------------------------------------------------------
+
+/**
+ * Fields added by transport-specific adapters (NOT part of universal contract).
+ *
+ * For example, the OpenClaw adapter wraps results in:
+ *   { content: [{type: "text", text}, {type: "json", json: universalResult}] }
+ *
+ * A CLI adapter might instead output JSON directly.
+ * An API adapter might wrap in HTTP response headers + JSON body.
+ */
+export const ADAPTER_ENVELOPE_FIELDS = Object.freeze({
+  OPENCLAW: Object.freeze({
+    description:
+      "OpenClaw wraps the universal result in a content array with " +
+      "text + json items. Error responses add isError: true.",
+    wrapper_fields: Object.freeze(["content", "isError"]),
+    content_item_types: Object.freeze(["text", "json"]),
+  }),
+  CLI: Object.freeze({
+    description:
+      "CLI adapter outputs the universal result as formatted JSON to stdout. " +
+      "Exit code 0 = success, non-zero = error.",
+    wrapper_fields: Object.freeze(["exitCode"]),
+  }),
+  API: Object.freeze({
+    description:
+      "API adapter returns the universal result as HTTP JSON response body. " +
+      "HTTP status code maps to RESPONSE_STATUS.",
+    wrapper_fields: Object.freeze(["httpStatus", "headers"]),
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Tool → family map
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps each ATF tool name to its contract family ID.
+ */
+export const TOOL_FAMILY_MAP = Object.freeze({
+  atf_health: "readiness",
+  atf_integration_doctor: "readiness",
+  atf_bot_preflight: "readiness",
+  atf_adoption_advisor: "advisory",
+  atf_tx_explain: "explanation",
+  atf_billing_info: "billing",
+  atf_billing_claim: "billing",
+  atf_discover: "discovery",
+  atf_bootstrap_plan: "discovery",
+  atf_bootstrap_execute_safe: "discovery",
+  atf_protect_intent: "protection",
+  atf_verify_receipt: "protection",
+  atf_report_savings: "protection",
+});
+
+/**
+ * All 13 canonical tool names, frozen.
+ */
+export const CANONICAL_TOOLS = Object.freeze(
+  Object.keys(TOOL_FAMILY_MAP),
+);
+
+/**
+ * Number of canonical tools. Used by tests for tool count assertions.
+ */
+export const CANONICAL_TOOL_COUNT = CANONICAL_TOOLS.length;

package/src/contracts/status_codes.mjs

@@ -0,0 +1,148 @@
+/**
+ * status_codes.mjs — Universal ATF status code vocabularies
+ *
+ * Platform-agnostic status enums used across all ATF surfaces:
+ * CLI, API, SDK, OpenClaw plugin, future human-dev UIs.
+ *
+ * These are the CANONICAL source of truth for status values.
+ * Adapters (OpenClaw, CLI, etc.) import from here — never duplicate.
+ *
+ * Exports:
+ *   - RESPONSE_STATUS    — tool response status enum
+ *   - DOCTOR_STATUS      — integration doctor status enum
+ *   - CLAIM_STATUS       — billing claim result status enum
+ *   - BACKEND_STATUS     — backend availability status enum
+ *   - PREFLIGHT_STATUS   — preflight go/no-go signal enum
+ *   - ADOPTION_TIER      — adoption recommendation tier enum
+ *   - SEVERITY           — trigger severity enum
+ *
+ * No dependencies. No side effects. Pure constants.
+ */
+
+// ---------------------------------------------------------------------------
+// Response status — used by all tool responses
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic status values for tool responses.
+ * Every ATF tool response carries one of these.
+ */
+export const RESPONSE_STATUS = Object.freeze({
+  /** Tool executed successfully, full capability. */
+  OK: "ok",
+  /** Tool executed but with reduced capability (e.g. fallback backend). */
+  DEGRADED: "degraded",
+  /** Tool execution failed — see error and remediation fields. */
+  ERROR: "error",
+  /** Backend completely unreachable — tool cannot operate. */
+  UNAVAILABLE: "unavailable",
+});
+
+// ---------------------------------------------------------------------------
+// Doctor status — integration readiness check
+// ---------------------------------------------------------------------------
+
+/**
+ * Overall integration doctor status. Stable finite set.
+ */
+export const DOCTOR_STATUS = Object.freeze({
+  /** Integration healthy. All systems operational. */
+  OK: "ok",
+  /** Integration degraded. Some capabilities limited. */
+  DEGRADED: "degraded",
+  /** Integration misconfigured. Check warnings and remediation. */
+  MISCONFIGURED: "misconfigured",
+  /** Integration unavailable. No ATF backend reachable. */
+  UNAVAILABLE: "unavailable",
+});
+
+// ---------------------------------------------------------------------------
+// Claim status — billing claim verification result
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic claim result statuses.
+ */
+export const CLAIM_STATUS = Object.freeze({
+  /** Payment verified, claim approved. */
+  VERIFIED: "verified",
+  /** Payment verification failed — see deny_code. */
+  DENIED: "denied",
+  /** Infrastructure error during verification. */
+  ERROR: "error",
+});
+
+// ---------------------------------------------------------------------------
+// Backend status — backend availability
+// ---------------------------------------------------------------------------
+
+/**
+ * Backend availability status.
+ */
+export const BACKEND_STATUS = Object.freeze({
+  /** Backend healthy and available. */
+  OK: "ok",
+  /** Backend available but degraded (fallback). */
+  DEGRADED: "degraded",
+  /** Backend misconfigured. */
+  MISCONFIGURED: "misconfigured",
+  /** Backend unavailable. */
+  UNAVAILABLE: "unavailable",
+});
+
+// ---------------------------------------------------------------------------
+// Preflight status — pre-session readiness signal
+// ---------------------------------------------------------------------------
+
+/**
+ * Preflight go/no-go signal.
+ */
+export const PREFLIGHT_STATUS = Object.freeze({
+  /** Ready to protect intents. */
+  READY: "ready",
+  /** Degraded but operational. */
+  DEGRADED: "degraded",
+  /** Not ready — see remediation. */
+  NOT_READY: "not_ready",
+});
+
+// ---------------------------------------------------------------------------
+// Adoption tier — adoption recommendation tiers
+// ---------------------------------------------------------------------------
+
+/**
+ * Adoption recommendation tiers for the adoption advisor.
+ */
+export const ADOPTION_TIER = Object.freeze({
+  /** Free core: all enforcement tools, no payment. */
+  FREE_CORE: "free_core",
+  /** Advanced bot: premium support + operator controls. */
+  ADVANCED_BOT: "advanced_bot",
+  /** No adoption needed at this time. */
+  NONE: "none",
+});
+
+// ---------------------------------------------------------------------------
+// Severity — trigger severity levels
+// ---------------------------------------------------------------------------
+
+/**
+ * Trigger severity levels (ordered: critical > high > medium > low).
+ */
+export const SEVERITY = Object.freeze({
+  CRITICAL: "critical",
+  HIGH: "high",
+  MEDIUM: "medium",
+  LOW: "low",
+});
+
+/**
+ * Severity ordering for comparison.
+ * Higher number = more severe.
+ */
+export const SEVERITY_RANK = Object.freeze({
+  [SEVERITY.CRITICAL]: 4,
+  [SEVERITY.HIGH]: 3,
+  [SEVERITY.MEDIUM]: 2,
+  [SEVERITY.LOW]: 1,
+});