{
  "title": "Original AccountBook-to-HelpBench API integration contract",
  "synthetic": true,
  "version": 1,
  "scope": "Invented interface for planning. It is not a real provider API or a runnable integration.",
  "sourceOfTruth": {
    "AccountBook": [
      "company_name",
      "subscription_tier",
      "record_version"
    ],
    "HelpBench": [
      "ticket_status",
      "agent_notes"
    ]
  },
  "authorization": "Server-side credentials limited to authorized tenant and company upserts. A stable external ID never replaces tenant authorization.",
  "endpoint": {
    "method": "PUT",
    "path": "/v1/companies/{destinationKey}",
    "successMeaning": "Stored and applied after validating tenant authorization and source_version.",
    "externalKey": "crm:{immutable account_id}",
    "ordering": "Lower source_version never overwrites a higher stored version.",
    "repetition": "A repeated identical version has no additional side effect. A same-version conflicting body requires investigation."
  },
  "mapping": [
    {
      "source": "account_id",
      "target": "external_id",
      "rule": "prefix stable ID with crm:"
    },
    {
      "source": "company_name",
      "target": "name",
      "rule": "trim; require nonempty string"
    },
    {
      "source": "subscription_tier",
      "target": "plan",
      "rule": "starter, team, or enterprise only"
    },
    {
      "source": "record_version",
      "target": "source_version",
      "rule": "positive integer"
    }
  ],
  "cases": [
    {
      "id": "create",
      "stored": null,
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "team",
        "source_version": 7
      },
      "expected": {
        "action": "create",
        "storedVersion": 7
      }
    },
    {
      "id": "repeat",
      "stored": {
        "source_version": 7,
        "name": "North Studio",
        "plan": "team"
      },
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "team",
        "source_version": 7
      },
      "expected": {
        "action": "no_additional_side_effect",
        "storedVersion": 7
      }
    },
    {
      "id": "newer",
      "stored": {
        "source_version": 7,
        "name": "North Studio",
        "plan": "team"
      },
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "enterprise",
        "source_version": 8
      },
      "expected": {
        "action": "update",
        "storedVersion": 8
      }
    },
    {
      "id": "older",
      "stored": {
        "source_version": 8,
        "name": "North Studio",
        "plan": "enterprise"
      },
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "team",
        "source_version": 6
      },
      "expected": {
        "action": "ignore_stale",
        "storedVersion": 8
      }
    },
    {
      "id": "empty_name",
      "stored": null,
      "input": {
        "external_id": "crm:acct_041",
        "name": "   ",
        "plan": "team",
        "source_version": 7
      },
      "expected": {
        "action": "reject",
        "reason": "name_required"
      }
    },
    {
      "id": "unknown_plan",
      "stored": null,
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "unmapped",
        "source_version": 7
      },
      "expected": {
        "action": "reject",
        "reason": "unsupported_plan"
      }
    },
    {
      "id": "temporary_failure",
      "stored": null,
      "input": {
        "external_id": "crm:acct_041",
        "name": "North Studio",
        "plan": "team",
        "source_version": 7
      },
      "transport": "temporary_unavailability",
      "expected": {
        "action": "retry_with_bounded_policy",
        "markSourceCursorComplete": false,
        "sideEffectKnown": false
      }
    }
  ],
  "unresolvedForRealProvider": [
    "authentication and authorization scopes",
    "documented idempotency and expiry rules",
    "pagination and resumable cursors",
    "throttling and retry timing",
    "deletions and retention",
    "observability, reconciliation, and operator ownership"
  ]
}