FretGuard OpenAPI pilot

This pilot proves one shared partner API can serve isolated users, a query, and a partner-computed simulation. It requires a Dataira-supplied prerelease of @dataira/node, an environment where OpenAPI execution is enabled, a key with minimal pack read/write/publish rights, and a FretGuard origin exposing /openapi.json. It does not require database access.

Register the reviewed contract

Run this only in the partner backend. Replace placeholders with secrets and IDs from Dataira; derive customer_id from trusted policy state, never user input.

import { Dataira } from "@dataira/node";
const dataira = new Dataira({ apiKey: process.env.DATAIRA_API_KEY!, baseUrl: process.env.DATAIRA_URL! });
const caps = await dataira.sourceConnectors.capabilities();
if (!caps.openapi.configuration || !caps.openapi.execution ||
    !caps.openapi.canonicalSpec || caps.openapi.egress !== "private_pinned_ip") throw new Error("OpenAPI unavailable");
const origin = process.env.FRETGUARD_ORIGIN!;
await dataira.sourceConnectors.preflightOpenApi({ origin, specUrl: `${origin}/openapi.json` });
const policy = { name: "customer_id", location: "query" as const,
  source: "policy" as const, key: "costs.customer_id", required: true, valueType: "string" as const };
const arg = (name: string) => ({ name, location: "body" as const,
  source: "argument" as const, key: name, required: true, valueType: "number" as const });
const source = await dataira.sourceConnectors.createOpenApi({ name: "FretGuard", origin,
  specUrl: `${origin}/openapi.json`, headers: { Authorization: `Bearer ${process.env.FRETGUARD_TOKEN!}` },
  timeoutMs: 3000, maxRows: 100, maxBytes: 250000, selectedOperations: [
    { operationId: "listCostVariance", policyTables: ["costs"], parameters: [policy], kind: "query",
      sideEffect: "none", mode: "sync", responseShape: "rows", idempotency: "not_applicable",
      responseItemsPath: ["items"], evidenceFields: ["evidenceId"],
      responseFields: ["month", "carrier", "baselineCost", "actualCost", "variance", "currency", "evidenceId"] },
    { operationId: "simulateCostScenario", policyTables: ["costs"],
      parameters: [{ ...policy, location: "body" }, ...["shipment_count", "average_weight_kg",
        "fuel_index", "discount_percent"].map(arg)], kind: "computation", sideEffect: "none",
      mode: "sync", responseShape: "object", idempotency: "required", responseResultPath: ["result"],
      evidenceFields: ["evidenceId"], responseFields: ["calculationVersion", "currency",
        "baselineCost", "simulatedCost", "savings", "evidenceId"] }
  ] }, { idempotencyKey: crypto.randomUUID() });
const specRevision = source.spec?.revision;
if (!specRevision) throw new Error("Immutable spec revision unavailable");
const sourceAuthorizationVersion = source.datasourceAuthorizationVersion;

Continue with pack imports, publication, export, and rollback.

Dataira's dev canary binds two users to different costs.customer_id values, proves cross-scope overrides fail, runs both operations with sourceAuthorizationVersion, inspects versioned receipts, revokes one user, and proves the other remains available. Reproduce it with pnpm --filter @bda/gateway-api smoke:fretguard:runtime:dev after building @dataira/node. Change the contract to prove incompatible drift blocks execution, then roll back to the prior published revision. Publication performs structural evaluation only; live post-publish conformance awaits an approved server-owned principal. Async execution, public packages, and production deployment remain unavailable.