@deployfoundation/foundation-deploy 0.2.50 → 0.2.52

package/dist/chunk-jf5rw6h4.js

@@ -0,0 +1,1117 @@
+import {
+  CRM_HTTP_CONTRACT,
+  CRM_HTTP_HEADERS,
+  CRM_HTTP_ROUTES,
+  CrmHttpError,
+  createCrmHttpClient,
+  encodeCrmActor,
+  readCrmHttpBody
+} from "./chunk-m76jt5rc.js";
+import {
+  outreachWeekStart,
+  personOwnedStatuses
+} from "./chunk-p7zkm4pp.js";
+import {
+  CRM_NOTE_ACTIVITY,
+  CRM_OUTREACH_DRAFTED_ACTIVITY,
+  CRM_REQUIRED_PROVIDER_OPERATIONS
+} from "./chunk-3614v9rr.js";
+import"./chunk-96fjaysn.js";
+import"./chunk-5wgwscd0.js";
+
+// ../capability-crm/src/contract/conformance.ts
+import { randomUUID } from "node:crypto";
+class Skip extends Error {
+  reason;
+  needs;
+  constructor(reason, needs = "other") {
+    super(reason);
+    this.reason = reason;
+    this.needs = needs;
+    this.name = "Skip";
+  }
+}
+
+class Failure extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "Failure";
+  }
+}
+var USER_AGENT = "foundation-crm-conformance/1";
+var RAW_TIMEOUT_MS = 1e4;
+var MAX_RAW_BODY_BYTES = 64 * 1024;
+var CANDIDATE_PAGES = 20;
+async function runCrmConformance(target) {
+  const suite = new Suite(target);
+  return suite.run();
+}
+
+class Suite {
+  target;
+  cases = [];
+  client;
+  runId;
+  fetchImpl;
+  meta;
+  sequence = 0;
+  firstTouches = 0;
+  followUps = 0;
+  constructor(target) {
+    this.target = target;
+    this.fetchImpl = target.fetchImpl ?? fetch;
+    this.runId = target.runId ?? `fcrm-${randomUUID().slice(0, 8)}`;
+    this.client = this.clientFor(target.apiKey);
+  }
+  async run() {
+    await this.check("meta", "GET /meta is valid and names the expected tenant", () => this.metaCase());
+    await this.check("auth_401", "an unknown key is 401", () => this.authCase());
+    await this.check("origin_403", "a request with an Origin header is 403 forbidden", () => this.originCase());
+    await this.check("contract_header", "a missing or other contract header is 400", () => this.contractHeaderCase());
+    await this.check("unknown_field", "an unknown request field is invalid_input", () => this.unknownFieldCase());
+    await this.check("search_bounds", "search enforces and honours its limit", () => this.searchBoundsCase());
+    await this.check("get_not_found", "an unknown record is 404 with contract and tenant headers", () => this.notFoundCase());
+    await this.check("delete_unsupported", "a server without deletes answers 501", () => this.deleteUnsupportedCase());
+    await this.writeCheck("upsert_and_read", "upserts create records; reads carry provenance", () => this.upsertCase());
+    await this.writeCheck("idempotent_replay", "a repeated write replays; a changed one is 409", () => this.replayCase());
+    await this.writeCheck("idempotency_header_mismatch", "Idempotency-Key must equal the body's key", () => this.headerMismatchCase());
+    await this.writeCheck("company_unknown", "a contact's unknown company is refused", () => this.companyUnknownCase());
+    await this.writeCheck("batch_bound", "an upsert over maxBatchSize is invalid_input", () => this.batchBoundCase());
+    await this.writeCheck("status_cas", "a status change compares and sets; a stale one is 412", () => this.statusCasCase());
+    await this.writeCheck("status_cas_version", "statusVersion is compared, not only the status", () => this.statusCasVersionCase());
+    await this.writeCheck("status_replay", "a status retry with a fresh expect replays", () => this.statusReplayCase());
+    await this.writeCheck("transition_not_allowed", "a disallowed status change is refused", () => this.transitionCase());
+    await this.writeCheck("status_locked", "a status a person set is not re-set by the agent", () => this.statusLockedCase());
+    await this.writeCheck("person_stage_rules", "a person's status moves only as the deployment's policy allows", () => this.personStageCase());
+    await this.writeCheck("attributes_by_reserved", "attributes.by is the server's to set", () => this.attributesByCase());
+    await this.writeCheck("note_log_and_edit", "the agent's note is versioned and editable", () => this.noteEditCase());
+    await this.writeCheck("note_not_editable", "other activities and a person's note are not", () => this.noteNotEditableCase());
+    await this.writeCheck("outreach_first_touch", "a first touch counts once per contact", () => this.firstTouchCase());
+    await this.writeCheck("outreach_not_contacted", "a follow-up needs a first touch", () => this.notContactedCase());
+    await this.writeCheck("outreach_per_email", "one first touch per email address", () => this.perEmailCase());
+    await this.writeCheck("outreach_company_draft", "a draft on a company is invalid_input", () => this.companyDraftCase());
+    await this.writeCheck("outreach_candidates", "candidates carry touch and rank, and page", () => this.candidatesCase());
+    await this.writeCheck("outreach_suppressed", "do-not-contact and suppressed addresses refuse drafts", () => this.suppressedCase());
+    await this.writeCheck("max_follow_ups", "follow-ups stop at maxFollowUps", () => this.maxFollowUpsCase());
+    await this.writeCheck("follow_up_limit", "follow-ups stop at the weekly follow-up limit", () => this.followUpLimitCase());
+    await this.writeCheck("read_only_scope", "a read-only key cannot write", () => this.readOnlyScopeCase());
+    await this.writeCheck("weekly_limit", "first touches stop at the weekly limit", () => this.weeklyLimitCase());
+    const count = (outcome) => this.cases.filter((entry) => entry.outcome === outcome).length;
+    return {
+      contract: CRM_HTTP_CONTRACT,
+      passed: count("pass"),
+      failed: count("fail"),
+      skipped: count("skip"),
+      cases: this.cases
+    };
+  }
+  async check(id, title, body) {
+    try {
+      const note = await body();
+      this.cases.push({
+        id,
+        title,
+        outcome: "pass",
+        ...note === undefined ? {} : { detail: note }
+      });
+    } catch (error) {
+      if (error instanceof Skip && error.needs === "harness" && this.target.strict === true) {
+        this.cases.push({
+          id,
+          title,
+          outcome: "fail",
+          detail: `not run: ${error.reason} (strict: person-only cases need a harness)`
+        });
+      } else if (error instanceof Skip) {
+        this.cases.push({ id, title, outcome: "skip", detail: error.reason });
+      } else {
+        this.cases.push({ id, title, outcome: "fail", detail: describe(error) });
+      }
+    }
+  }
+  async writeCheck(id, title, body) {
+    await this.check(id, title, async () => {
+      if (this.target.write !== true)
+        throw new Skip("write cases are off (write: false)");
+      return body();
+    });
+  }
+  async metaCase() {
+    const meta = await this.client.meta();
+    if (meta.contract !== CRM_HTTP_CONTRACT)
+      throw new Failure("contract is not crm/1");
+    if (meta.tenant.id !== this.target.tenantId) {
+      throw new Failure("tenant.id is not the expected tenant");
+    }
+    const missing = CRM_REQUIRED_PROVIDER_OPERATIONS.filter((name) => !meta.operations.includes(name));
+    if (missing.length > 0) {
+      throw new Failure(`required operations missing: ${missing.join(", ")}`);
+    }
+    if (meta.statuses.company.length === 0 || meta.statuses.contact.length === 0) {
+      throw new Failure("each record type needs at least one status");
+    }
+    if (meta.operations.includes("outreach_state")) {
+      const policy = meta.policy;
+      const missing2 = ["firstTouchWeeklyLimit", "followUpWeeklyLimit", "maxFollowUps"].filter((field) => policy?.[field] === undefined).join(", ");
+      if (missing2 !== "")
+        throw new Failure(`/meta policy is missing ${missing2}`);
+    }
+    this.meta = meta;
+    return;
+  }
+  async authCase() {
+    const reply = await this.raw("meta", undefined, {
+      headers: { authorization: "Bearer conformance-invalid-key-000000" }
+    });
+    expectStatus(reply, [401]);
+    return;
+  }
+  async originCase() {
+    const reply = await this.raw("search", { limit: 1 }, {
+      headers: { origin: "https://conformance.example" }
+    });
+    expectStatus(reply, [403]);
+    expectErrorBody(reply, "forbidden");
+    return;
+  }
+  async contractHeaderCase() {
+    const missing = await this.raw("meta", undefined, { omit: [CRM_HTTP_HEADERS.contract] });
+    expectStatus(missing, [400]);
+    expectErrorBody(missing, "invalid_input");
+    const other = await this.raw("meta", undefined, {
+      headers: { [CRM_HTTP_HEADERS.contract]: "crm/2" }
+    });
+    expectStatus(other, [400]);
+    expectErrorBody(other, "invalid_input");
+    return;
+  }
+  async unknownFieldCase() {
+    const reply = await this.raw("search", { limit: 1, customerId: "conformance" });
+    expectStatus(reply, [400, 422]);
+    expectErrorBody(reply, "invalid_input");
+    return;
+  }
+  async searchBoundsCase() {
+    await expectError(this.client.search({ limit: 101 }), "invalid_input");
+    const page = await this.client.search({ limit: 1 });
+    if (page.records.length > 1)
+      throw new Failure("search returned more records than its limit");
+    return;
+  }
+  async notFoundCase() {
+    const body = { recordType: "contact", recordId: `${this.runId}-missing` };
+    const reply = await this.raw("get_record", body);
+    expectStatus(reply, [404]);
+    expectErrorBody(reply, "not_found");
+    if (reply.headers.get(CRM_HTTP_HEADERS.contract) === null) {
+      throw new Failure("the 404 has no Foundation-Contract header");
+    }
+    if (reply.headers.get(CRM_HTTP_HEADERS.tenant) !== this.target.tenantId) {
+      throw new Failure("the 404 does not name the expected tenant");
+    }
+    await expectError(this.client.getRecord({ recordType: "contact", recordId: `${this.runId}-missing` }), "not_found");
+    return;
+  }
+  async deleteUnsupportedCase() {
+    const meta = this.requireMeta();
+    if (meta.operations.includes("delete_record")) {
+      throw new Skip("the server offers delete_record");
+    }
+    const key = this.key();
+    const reply = await this.raw("delete_record", { recordType: "contact", recordId: `${this.runId}-missing`, idempotencyKey: key }, { headers: { [CRM_HTTP_HEADERS.idempotencyKey]: key } });
+    expectStatus(reply, [501]);
+    expectErrorBody(reply, "unsupported");
+    return;
+  }
+  async upsertCase() {
+    const meta = this.requireMeta();
+    const fixture = await this.fixture("upsert", { title: "Head of Growth" });
+    const contact = await this.profile("contact", fixture.contactId);
+    const company = await this.profile("company", fixture.companyId);
+    if (contact.statusSetBy === undefined)
+      throw new Failure("contact profile has no statusSetBy");
+    if (contact.statusVersion === undefined) {
+      throw new Failure("contact profile has no statusVersion");
+    }
+    if (contact.doNotContact === undefined) {
+      throw new Failure("contact profile has no doNotContact");
+    }
+    if (contact.status !== meta.statuses.contact[0]) {
+      throw new Failure("a new contact is not in the first contact status");
+    }
+    if (company.status !== meta.statuses.company[0]) {
+      throw new Failure("a new company is not in the first company status");
+    }
+    await this.client.upsertRecords({
+      idempotencyKey: this.key(),
+      contacts: [
+        {
+          externalId: fixture.contactExternalId,
+          email: fixture.email,
+          title: "Director of Growth",
+          companyExternalId: fixture.companyExternalId
+        }
+      ]
+    });
+    const again = await this.profile("contact", fixture.contactId);
+    if (again.title !== "Director of Growth")
+      throw new Failure("a second upsert did not update");
+    if (again.status !== contact.status || again.statusVersion !== contact.statusVersion) {
+      throw new Failure("a second upsert changed the status");
+    }
+    return;
+  }
+  async replayCase() {
+    const key = this.key();
+    const body = {
+      idempotencyKey: key,
+      companies: [{ externalId: this.externalId("replay"), name: this.name("replay") }]
+    };
+    const first = await this.raw("upsert_records", body, {
+      headers: { [CRM_HTTP_HEADERS.idempotencyKey]: key }
+    });
+    expectStatus(first, [200, 201]);
+    const second = await this.raw("upsert_records", body, {
+      headers: { [CRM_HTTP_HEADERS.idempotencyKey]: key }
+    });
+    expectStatus(second, [200, 201]);
+    if (second.headers.get(CRM_HTTP_HEADERS.replayed) !== "true") {
+      throw new Failure("the replay has no Idempotent-Replayed: true header");
+    }
+    if (JSON.stringify(first.json) !== JSON.stringify(second.json)) {
+      throw new Failure("the replay's acknowledgement differs from the original");
+    }
+    await expectError(this.client.upsertRecords({
+      idempotencyKey: key,
+      companies: [{ externalId: this.externalId("replay"), name: `${this.name("replay")} 2` }]
+    }), "conflict");
+    return;
+  }
+  async headerMismatchCase() {
+    const reply = await this.raw("upsert_records", {
+      idempotencyKey: this.key(),
+      companies: [{ externalId: this.externalId("mismatch"), name: this.name("mismatch") }]
+    }, { headers: { [CRM_HTTP_HEADERS.idempotencyKey]: this.key() } });
+    expectStatus(reply, [400]);
+    expectErrorBody(reply, "invalid_input");
+    return;
+  }
+  async companyUnknownCase() {
+    try {
+      await this.client.upsertRecords({
+        idempotencyKey: this.key(),
+        contacts: [
+          {
+            externalId: this.externalId("orphan"),
+            email: this.email("orphan"),
+            companyExternalId: this.externalId("no-such-company")
+          }
+        ]
+      });
+    } catch (error) {
+      if (error instanceof CrmHttpError && error.code === "invalid_input" && error.detailCode === "contact_company_unknown") {
+        return;
+      }
+      throw error;
+    }
+    throw new Skip("the server accepts a contact whose company is unknown");
+  }
+  async batchBoundCase() {
+    const meta = this.requireMeta();
+    if (meta.maxBatchSize >= 1000)
+      throw new Skip("maxBatchSize is too large to exceed here");
+    const companies = Array.from({ length: meta.maxBatchSize + 1 }, (_, index) => ({
+      externalId: this.externalId(`batch-${index}`),
+      name: this.name(`batch-${index}`)
+    }));
+    await expectError(this.client.upsertRecords({ idempotencyKey: this.key(), companies }), "invalid_input");
+    return;
+  }
+  async statusCasCase() {
+    const fixture = await this.fixture("cas");
+    const before = await this.profile("company", fixture.companyId);
+    const move = await this.legalMove("company", fixture.companyId, before);
+    const after = await this.profile("company", fixture.companyId);
+    if (after.status !== move.status)
+      throw new Failure("the status was not applied");
+    if ((after.statusVersion ?? -1) <= (before.statusVersion ?? -1)) {
+      throw new Failure("statusVersion did not increase");
+    }
+    if (after.statusSetBy !== "agent")
+      throw new Failure("the agent's change is not stamped agent");
+    await expectError(this.client.updateStatus({
+      recordType: "company",
+      recordId: fixture.companyId,
+      status: before.status,
+      idempotencyKey: this.key()
+    }, { status: before.status, statusVersion: before.statusVersion ?? 0 }), "stale_status");
+    return;
+  }
+  async statusCasVersionCase() {
+    const harness = this.requireHarness();
+    const second = await this.fixture("cas-version");
+    const read = await this.profile("company", second.companyId);
+    await harness.setStatusAsPerson("company", second.companyId, read.status);
+    const target = this.requireMeta().statuses.company.find((status) => status !== read.status);
+    if (target === undefined)
+      return;
+    await expectError(this.client.updateStatus({
+      recordType: "company",
+      recordId: second.companyId,
+      status: target,
+      idempotencyKey: this.key()
+    }, { status: read.status, statusVersion: read.statusVersion ?? 0 }), "stale_status");
+    return;
+  }
+  async statusReplayCase() {
+    const fixture = await this.fixture("status-replay");
+    const before = await this.profile("company", fixture.companyId);
+    const move = await this.legalMove("company", fixture.companyId, before);
+    const after = await this.profile("company", fixture.companyId);
+    const reply = await this.raw("update_status", {
+      recordType: "company",
+      recordId: fixture.companyId,
+      status: move.status,
+      idempotencyKey: move.key,
+      expect: { status: after.status, statusVersion: after.statusVersion ?? 0 }
+    }, { headers: { [CRM_HTTP_HEADERS.idempotencyKey]: move.key } });
+    expectStatus(reply, [200, 201]);
+    if (reply.headers.get(CRM_HTTP_HEADERS.replayed) !== "true") {
+      throw new Failure("the retry was not replayed (no Idempotent-Replayed: true)");
+    }
+    const latest = await this.profile("company", fixture.companyId);
+    if (latest.statusVersion !== after.statusVersion) {
+      throw new Failure("the replay changed the status again");
+    }
+    return;
+  }
+  async transitionCase() {
+    const transition = this.target.disallowedTransition;
+    if (transition === undefined)
+      throw new Skip("no disallowedTransition given");
+    const fixture = await this.fixture("transition");
+    const recordId = transition.recordType === "company" ? fixture.companyId : fixture.contactId;
+    const current = await this.profile(transition.recordType, recordId);
+    await expectError(this.client.updateStatus({
+      recordType: transition.recordType,
+      recordId,
+      status: transition.to,
+      idempotencyKey: this.key()
+    }, { status: current.status, statusVersion: current.statusVersion ?? 0 }), "refused", "transition_not_allowed");
+    return;
+  }
+  async statusLockedCase() {
+    const harness = this.requireHarness();
+    const fixture = await this.fixture("locked");
+    const initial = await this.profile("company", fixture.companyId);
+    await harness.setStatusAsPerson("company", fixture.companyId, initial.status);
+    const current = await this.profile("company", fixture.companyId);
+    if (current.statusSetBy !== "person")
+      throw new Failure("a person's change is not stamped person");
+    if ((current.statusVersion ?? -1) <= (initial.statusVersion ?? -1)) {
+      throw new Failure("a person's change did not bump statusVersion");
+    }
+    await expectError(this.client.updateStatus({
+      recordType: "company",
+      recordId: fixture.companyId,
+      status: current.status,
+      idempotencyKey: this.key()
+    }, { status: current.status, statusVersion: current.statusVersion ?? 0 }), "refused", "status_locked");
+    return;
+  }
+  async personStageCase() {
+    const harness = this.requireHarness();
+    const policy = this.target.statusPolicy;
+    if (policy === undefined)
+      throw new Skip("no statusPolicy given");
+    const meta = this.requireMeta();
+    const checked = [];
+    for (const recordType of ["company", "contact"]) {
+      const rule = policy[recordType];
+      if (rule === undefined)
+        continue;
+      const exits = (from) => Object.hasOwn(rule.agentTransitions, from) ? rule.agentTransitions[from] ?? [] : [];
+      const fresh = async (label) => {
+        const fixture = await this.fixture(`${recordType}-${label}`);
+        return recordType === "company" ? fixture.companyId : fixture.contactId;
+      };
+      const personOnly = personOwnedStatuses(rule, meta.statuses[recordType]);
+      if (personOnly.length > 0) {
+        const recordId = await fresh("into-person-only");
+        for (const status of personOnly) {
+          await this.expectMoveRefused(recordType, recordId, status, "transition_not_allowed");
+        }
+        const owned = personOnly[0];
+        const outId = await fresh("out-of-person-only");
+        await harness.setStatusAsPerson(recordType, outId, owned);
+        const away = meta.statuses[recordType].find((status) => status !== owned);
+        if (away !== undefined)
+          await this.expectMoveRefused(recordType, outId, away);
+        checked.push(`${recordType}: person-only`);
+      }
+      if (!rule.respectHumanChanges)
+        continue;
+      if (rule.personSet === "advance") {
+        const step = rule.ladder.findIndex((status, index) => index + 1 < rule.ladder.length && exits(status).includes(rule.ladder[index + 1]));
+        if (step < 0)
+          continue;
+        const from = rule.ladder[step];
+        const forward = rule.ladder[step + 1];
+        const forwardId = await fresh("advance");
+        await harness.setStatusAsPerson(recordType, forwardId, from);
+        await this.move(recordType, forwardId, forward);
+        const offLadder = exits(from).filter((status) => !rule.ladder.includes(status));
+        const offId = await fresh("off-ladder");
+        await harness.setStatusAsPerson(recordType, offId, from);
+        for (const status of offLadder) {
+          await this.expectMoveRefused(recordType, offId, status, "status_locked");
+        }
+        checked.push(`${recordType}: advance`);
+      } else {
+        const from = meta.statuses[recordType].find((status) => exits(status).length > 0);
+        if (from === undefined)
+          continue;
+        const lockedId = await fresh("lock");
+        await harness.setStatusAsPerson(recordType, lockedId, from);
+        await this.expectMoveRefused(recordType, lockedId, exits(from)[0], "status_locked");
+        checked.push(`${recordType}: lock`);
+      }
+    }
+    if (checked.length === 0)
+      throw new Skip("the statusPolicy has no rule a person's change affects");
+    return checked.join("; ");
+  }
+  async move(recordType, recordId, status) {
+    const current = await this.profile(recordType, recordId);
+    try {
+      await this.client.updateStatus({ recordType, recordId, status, idempotencyKey: this.key() }, { status: current.status, statusVersion: current.statusVersion ?? 0 });
+    } catch (error) {
+      throw new Failure(`${current.status} → ${status} was refused (${describe(error)})`);
+    }
+  }
+  async expectMoveRefused(recordType, recordId, status, reason) {
+    const current = await this.profile(recordType, recordId);
+    try {
+      await this.client.updateStatus({ recordType, recordId, status, idempotencyKey: this.key() }, { status: current.status, statusVersion: current.statusVersion ?? 0 });
+    } catch (error) {
+      if (error instanceof CrmHttpError && error.code === "refused" && (reason === undefined ? error.reason === "status_locked" || error.reason === "transition_not_allowed" : error.reason === reason)) {
+        return;
+      }
+      throw new Failure(`${current.status} → ${status} should be refused${reason === undefined ? "" : ` (${reason})`}, got ${describe(error)}`);
+    }
+    throw new Failure(`${current.status} → ${status} was accepted`);
+  }
+  async attributesByCase() {
+    const meta = this.requireMeta();
+    const activityType = meta.activityTypes.includes(CRM_NOTE_ACTIVITY) ? CRM_NOTE_ACTIVITY : meta.activityTypes[0];
+    const fixture = await this.fixture("by");
+    const key = this.key();
+    const reply = await this.raw("log_activity", {
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityType,
+      summary: "Conformance: a caller may not claim authorship.",
+      attributes: { by: "agent" },
+      idempotencyKey: key
+    }, { headers: { [CRM_HTTP_HEADERS.idempotencyKey]: key } });
+    expectStatus(reply, [400, 422]);
+    expectErrorBody(reply, "invalid_input");
+    return;
+  }
+  async noteEditCase() {
+    this.requireNotes();
+    const fixture = await this.fixture("note");
+    await this.client.logActivity({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityType: CRM_NOTE_ACTIVITY,
+      summary: "Conformance note, first text.",
+      idempotencyKey: this.key()
+    });
+    const note = await this.findActivity("company", fixture.companyId, (activity) => activity.summary === "Conformance note, first text.");
+    if (note.attributes?.by !== "agent")
+      throw new Failure("the agent's note is not by: agent");
+    if (note.version !== 1)
+      throw new Failure("a new note is not version 1");
+    const edit = {
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityId: note.id,
+      summary: "Conformance note, edited.",
+      version: 1,
+      idempotencyKey: this.key()
+    };
+    const ack = await this.client.updateNote(edit);
+    if (ack.operation !== "update_note" || ack.version !== 2) {
+      throw new Failure("the edit did not answer version 2");
+    }
+    const read = await this.client.getActivity({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityId: note.id
+    });
+    if (read.summary !== edit.summary || read.version !== 2) {
+      throw new Failure("get_activity does not show the edit");
+    }
+    await expectError(this.client.updateNote({
+      ...edit,
+      summary: "Conformance note, stale.",
+      idempotencyKey: this.key()
+    }), "stale_version");
+    const replay = await this.client.updateNote(edit);
+    if (replay.operation !== "update_note" || replay.version !== 2) {
+      throw new Failure("the replayed edit did not answer the original acknowledgement");
+    }
+    return;
+  }
+  async noteNotEditableCase() {
+    const meta = this.requireNotes();
+    const other = meta.activityTypes.find((type) => type !== CRM_NOTE_ACTIVITY && type !== CRM_OUTREACH_DRAFTED_ACTIVITY);
+    if (other === undefined)
+      throw new Skip("no activity type besides note and email_drafted");
+    const fixture = await this.fixture("not-editable");
+    await this.client.logActivity({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityType: other,
+      summary: "Conformance: not a note.",
+      idempotencyKey: this.key()
+    });
+    const activity = await this.findActivity("company", fixture.companyId, (entry) => entry.activityType === other);
+    await expectError(this.client.updateNote({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityId: activity.id,
+      summary: "Conformance: an edit that must be refused.",
+      version: activity.version ?? 1,
+      idempotencyKey: this.key()
+    }), "not_editable");
+    const harness = this.target.harness;
+    if (harness === undefined) {
+      throw new Skip("a non-note was refused, but a person's note needs a harness", "harness");
+    }
+    const personNoteId = await harness.addPersonNote("company", fixture.companyId, `Conformance: a person's long note. ${"x".repeat(4500)}`);
+    const personNote = await this.findActivity("company", fixture.companyId, (entry) => entry.id === personNoteId);
+    if (personNote.attributes?.by !== "person")
+      throw new Failure("a person's note is not by: person");
+    await expectError(this.client.updateNote({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityId: personNoteId,
+      summary: "Conformance: an edit of a person's note.",
+      version: personNote.version ?? 1,
+      idempotencyKey: this.key()
+    }), "not_editable");
+    return;
+  }
+  async firstTouchCase() {
+    this.requireOutreach();
+    const fixture = await this.fixture("first-touch");
+    await this.draft(fixture.contactId, "first_touch", { threadId: `${this.runId}-thread` });
+    const state = await this.client.outreachState({ contactId: fixture.contactId });
+    if (state.touch.firstTouchAt === undefined)
+      throw new Failure("no firstTouchAt after a first touch");
+    if (state.touch.followUps !== 0)
+      throw new Failure("followUps is not 0 after a first touch");
+    if (state.touch.lastThreadId !== `${this.runId}-thread`) {
+      throw new Failure("the draft's thread was not kept");
+    }
+    if (state.companyId !== fixture.companyId)
+      throw new Failure("outreach state names another company");
+    await expectError(this.draft(fixture.contactId, "first_touch"), "refused", "already_contacted");
+    return;
+  }
+  async notContactedCase() {
+    this.requireOutreach();
+    const fixture = await this.fixture("not-contacted");
+    await expectError(this.draft(fixture.contactId, "follow_up"), "refused", "not_contacted");
+    return;
+  }
+  async perEmailCase() {
+    this.requireOutreach();
+    const email = this.email("shared");
+    const first = await this.fixture("shared-a", { email });
+    const second = await this.fixture("shared-b", { email });
+    await this.draft(first.contactId, "first_touch");
+    await expectError(this.draft(second.contactId, "first_touch"), "refused", "already_contacted");
+    return;
+  }
+  async companyDraftCase() {
+    this.requireOutreach();
+    const fixture = await this.fixture("company-draft");
+    await expectError(this.client.logActivity({
+      recordType: "company",
+      recordId: fixture.companyId,
+      activityType: CRM_OUTREACH_DRAFTED_ACTIVITY,
+      summary: "Conformance: a draft logged on a company.",
+      attributes: { kind: "first_touch" },
+      idempotencyKey: this.key()
+    }, this.outreach("drafted", "first_touch")), "invalid_input");
+    return;
+  }
+  async candidatesCase() {
+    const meta = this.requireOutreach();
+    const status = meta.statuses.contact[0];
+    const fixture = await this.fixture("candidate", { attributes: { conformanceRank: 42 } });
+    let cursor;
+    let found = false;
+    for (let page = 0;page < CANDIDATE_PAGES && !found; page += 1) {
+      const reply = await this.client.outreachCandidates({
+        rankAttribute: "conformanceRank",
+        statuses: { contact: [status] },
+        limit: 200,
+        ...cursor === undefined ? {} : { cursor }
+      });
+      const candidate = reply.candidates.find((entry) => entry.contactId === fixture.contactId);
+      if (candidate !== undefined) {
+        found = true;
+        if (candidate.email.toLowerCase() !== fixture.email.toLowerCase()) {
+          throw new Failure("the candidate's email is not the contact's");
+        }
+        if (candidate.rank !== 42)
+          throw new Failure("the candidate's rank is not its rank attribute");
+        if (candidate.touch.followUps !== 0 || candidate.touch.firstTouchAt !== undefined) {
+          throw new Failure("a never-drafted candidate carries a touch");
+        }
+        if (candidate.companyId !== undefined && !reply.companies.some((company) => company.companyId === candidate.companyId)) {
+          throw new Failure("the page's companies leave out the candidate's company");
+        }
+      }
+      cursor = reply.cursor;
+      if (cursor === undefined)
+        break;
+    }
+    if (!found)
+      throw new Failure("a fresh contact with an email is not a candidate");
+    const first = await this.client.outreachCandidates({
+      rankAttribute: "conformanceRank",
+      statuses: { contact: [status] },
+      limit: 1
+    });
+    if (first.candidates.length > 1)
+      throw new Failure("candidates exceeded the page limit");
+    if (first.cursor !== undefined) {
+      const next = await this.client.outreachCandidates({
+        rankAttribute: "conformanceRank",
+        statuses: { contact: [status] },
+        limit: 1,
+        cursor: first.cursor
+      });
+      if (next.candidates.length === 1 && next.candidates[0]?.contactId === first.candidates[0]?.contactId) {
+        throw new Failure("the next page repeats the first");
+      }
+    }
+    return;
+  }
+  async suppressedCase() {
+    this.requireOutreach();
+    const harness = this.requireHarness();
+    const flagged = await this.fixture("dnc-contact");
+    await harness.setDoNotContact("contact", flagged.contactId);
+    await this.expectSuppressed(flagged.contactId, "the contact's own flag");
+    const company = await this.fixture("dnc-company");
+    await harness.setDoNotContact("company", company.companyId);
+    await this.expectSuppressed(company.contactId, "the company's flag");
+    const address = await this.fixture("dnc-email");
+    await harness.suppressEmail(address.email);
+    await this.expectSuppressed(address.contactId, "a suppressed address");
+    const suppressed = this.target.suppressedStatuses;
+    if (suppressed === undefined) {
+      return "suppressed statuses were not checked (no suppressedStatuses given)";
+    }
+    const contactStatus = suppressed.contact[0];
+    if (contactStatus !== undefined) {
+      const ruledOut = await this.fixture("suppressed-status");
+      await harness.setStatusAsPerson("contact", ruledOut.contactId, contactStatus);
+      await this.expectSuppressed(ruledOut.contactId, `contact status ${contactStatus}`, {
+        status: contactStatus
+      });
+    }
+    const companyStatus = suppressed.company[0];
+    if (companyStatus !== undefined) {
+      const closed = await this.fixture("suppressed-company-status");
+      await harness.setStatusAsPerson("company", closed.companyId, companyStatus);
+      await this.expectSuppressed(closed.contactId, `company status ${companyStatus}`, {
+        companyStatus
+      });
+    }
+    return;
+  }
+  async maxFollowUpsCase() {
+    const meta = this.requireOutreach();
+    const max = meta.policy?.maxFollowUps;
+    const weekly = meta.policy?.followUpWeeklyLimit;
+    if (max === undefined || weekly === undefined) {
+      throw new Skip("/meta policy has no maxFollowUps or followUpWeeklyLimit");
+    }
+    if (weekly < max + 1)
+      throw new Skip("followUpWeeklyLimit is below maxFollowUps + 1");
+    const fixture = await this.fixture("follow-ups");
+    await this.draft(fixture.contactId, "first_touch");
+    for (let index = 0;index < max; index += 1) {
+      await this.draft(fixture.contactId, "follow_up");
+    }
+    const state = await this.client.outreachState({ contactId: fixture.contactId });
+    if (state.touch.followUps !== max)
+      throw new Failure("followUps does not count the follow-ups");
+    await expectError(this.draft(fixture.contactId, "follow_up"), "refused", "max_follow_ups_reached");
+    return;
+  }
+  async followUpLimitCase() {
+    if (this.target.spendWeeklyAllowance !== true) {
+      throw new Skip("spendWeeklyAllowance is off");
+    }
+    const meta = this.requireOutreach();
+    const limit = meta.policy?.followUpWeeklyLimit;
+    const max = meta.policy?.maxFollowUps;
+    const firstTouchLimit = meta.policy?.firstTouchWeeklyLimit;
+    if (limit === undefined || max === undefined || firstTouchLimit === undefined) {
+      throw new Skip("/meta policy has no follow-up limits");
+    }
+    if (max < 1 || firstTouchLimit < 1)
+      throw new Skip("the server allows no follow-ups");
+    if (limit > 100)
+      throw new Skip("followUpWeeklyLimit is too large to spend here");
+    let contacts = 0;
+    const touched = async () => {
+      const fixture = await this.fixture(`follow-up-limit-${contacts}`);
+      await this.draft(fixture.contactId, "first_touch", {
+        weekStart: this.pastWeek(Math.floor(contacts / firstTouchLimit))
+      });
+      contacts += 1;
+      return fixture.contactId;
+    };
+    while (this.followUps < limit) {
+      const contactId = await touched();
+      for (let index = 0;index < max && this.followUps < limit; index += 1) {
+        await this.draft(contactId, "follow_up");
+      }
+    }
+    await expectError(this.draft(await touched(), "follow_up"), "refused", "follow_up_limit_reached");
+    return;
+  }
+  async readOnlyScopeCase() {
+    const key = this.target.readOnlyApiKey;
+    if (key === undefined)
+      throw new Skip("no readOnlyApiKey given");
+    const readOnly = this.clientFor(key);
+    await readOnly.search({ limit: 1 });
+    await expectError(readOnly.upsertRecords({
+      idempotencyKey: this.key(),
+      companies: [{ externalId: this.externalId("read-only"), name: this.name("read-only") }]
+    }), "forbidden");
+    return;
+  }
+  async weeklyLimitCase() {
+    if (this.target.spendWeeklyAllowance !== true) {
+      throw new Skip("spendWeeklyAllowance is off");
+    }
+    const meta = this.requireOutreach();
+    const limit = meta.policy?.firstTouchWeeklyLimit;
+    if (limit === undefined)
+      throw new Skip("/meta policy has no firstTouchWeeklyLimit");
+    for (let attempt = 0;attempt <= limit; attempt += 1) {
+      const fixture = await this.fixture(`weekly-${attempt}`);
+      try {
+        await this.draft(fixture.contactId, "first_touch");
+      } catch (error) {
+        if (error instanceof CrmHttpError && error.code === "refused" && error.reason === "weekly_limit_reached") {
+          if (this.firstTouches !== limit) {
+            throw new Failure(`refused after ${this.firstTouches} first touches this run; the limit is ${limit} (a fresh week and database are assumed)`);
+          }
+          return;
+        }
+        throw error;
+      }
+    }
+    throw new Failure(`more than ${limit} first touches were accepted this week`);
+  }
+  clientFor(apiKey) {
+    return createCrmHttpClient({
+      baseUrl: this.target.baseUrl,
+      credentials: { get: async () => apiKey, refresh: async () => apiKey },
+      expectedTenant: this.target.tenantId,
+      userAgent: USER_AGENT,
+      actor: encodeCrmActor({
+        agent: "conformance",
+        slackTeamId: "T0CONFORMANCE",
+        slackUserId: "config",
+        channelId: "C0CONFORMANCE",
+        sessionHash: "conformance"
+      }),
+      fetchImpl: this.fetchImpl
+    });
+  }
+  requireMeta() {
+    if (this.meta === undefined)
+      throw new Skip("/meta did not pass");
+    return this.meta;
+  }
+  requireHarness() {
+    if (this.target.harness === undefined)
+      throw new Skip("no harness given", "harness");
+    return this.target.harness;
+  }
+  requireOperations(...names) {
+    const meta = this.requireMeta();
+    const missing = names.filter((name) => !meta.operations.includes(name));
+    if (missing.length > 0)
+      throw new Skip(`the server does not offer ${missing.join(", ")}`);
+    return meta;
+  }
+  requireNotes() {
+    const meta = this.requireOperations("get_activity", "update_note");
+    if (!meta.activityTypes.includes(CRM_NOTE_ACTIVITY))
+      throw new Skip("note is not an activity type");
+    return meta;
+  }
+  requireOutreach() {
+    const meta = this.requireOperations("outreach_state", "outreach_candidates");
+    if (!meta.activityTypes.includes(CRM_OUTREACH_DRAFTED_ACTIVITY)) {
+      throw new Skip("email_drafted is not an activity type");
+    }
+    return meta;
+  }
+  key() {
+    this.sequence += 1;
+    return `${this.runId}-k${this.sequence}`;
+  }
+  externalId(label) {
+    return `${this.runId}-${label}`;
+  }
+  name(label) {
+    return `Conformance ${this.runId} ${label}`;
+  }
+  email(label) {
+    return `${this.runId}-${label}@conformance.example.com`;
+  }
+  async fixture(label, options = {}) {
+    const companyExternalId = this.externalId(`${label}-co`);
+    const contactExternalId = this.externalId(`${label}-ct`);
+    const email = options.email ?? this.email(label);
+    const companyName = this.name(`${label} company`);
+    await this.client.upsertRecords({
+      idempotencyKey: this.key(),
+      companies: [{ externalId: companyExternalId, name: companyName }],
+      contacts: [
+        {
+          externalId: contactExternalId,
+          email,
+          firstName: "Conformance",
+          lastName: label,
+          companyExternalId,
+          ...options.title === undefined ? {} : { title: options.title },
+          ...options.attributes === undefined ? {} : { attributes: options.attributes }
+        }
+      ]
+    });
+    return {
+      companyId: await this.findId("company", companyName, companyExternalId),
+      companyExternalId,
+      contactId: await this.findId("contact", email, contactExternalId),
+      contactExternalId,
+      email
+    };
+  }
+  async findId(recordType, query, externalId) {
+    let cursor;
+    for (let page = 0;page < 10; page += 1) {
+      const reply = await this.client.search({
+        query,
+        limit: 100,
+        ...cursor === undefined ? {} : { cursor }
+      });
+      const match = reply.records.find((record) => record.recordType === recordType && record.externalId === externalId);
+      if (match !== undefined)
+        return match.id;
+      cursor = reply.cursor;
+      if (cursor === undefined)
+        break;
+    }
+    throw new Failure(`a ${recordType} just upserted is not found by search`);
+  }
+  async profile(recordType, recordId) {
+    const reply = await this.client.getRecord({ recordType, recordId, activityLimit: 1 });
+    if (reply.profile.id !== recordId || reply.profile.recordType !== recordType) {
+      throw new Failure("get_record answered a different record");
+    }
+    return reply.profile;
+  }
+  async findActivity(recordType, recordId, matches) {
+    const reply = await this.client.getRecord({ recordType, recordId, activityLimit: 100 });
+    const activity = reply.activities.find(matches);
+    if (activity === undefined)
+      throw new Failure("a logged activity is not on its record");
+    return activity;
+  }
+  async legalMove(recordType, recordId, current) {
+    const meta = this.requireMeta();
+    for (const status of meta.statuses[recordType]) {
+      if (status === current.status)
+        continue;
+      const key = this.key();
+      try {
+        await this.client.updateStatus({ recordType, recordId, status, idempotencyKey: key }, { status: current.status, statusVersion: current.statusVersion ?? 0 });
+        return { status, key };
+      } catch (error) {
+        if (error instanceof CrmHttpError && error.code === "refused")
+          continue;
+        throw error;
+      }
+    }
+    throw new Skip(`the agent may not move a fresh ${recordType} to any status`);
+  }
+  outreach(event, kind, weekStart = this.currentWeek()) {
+    const timezone = this.meta?.policy?.timezone ?? "UTC";
+    return { event, ...kind === undefined ? {} : { kind }, weekStart, timezone };
+  }
+  currentWeek() {
+    try {
+      return outreachWeekStart(new Date, this.meta?.policy?.timezone ?? "UTC");
+    } catch {
+      return outreachWeekStart(new Date, "UTC");
+    }
+  }
+  async draft(contactId, kind, extra = {}) {
+    const weekStart = extra.weekStart ?? this.currentWeek();
+    await this.client.logActivity({
+      recordType: "contact",
+      recordId: contactId,
+      activityType: CRM_OUTREACH_DRAFTED_ACTIVITY,
+      summary: `Conformance ${kind} draft.`,
+      attributes: { kind, ...extra.threadId === undefined ? {} : { threadId: extra.threadId } },
+      idempotencyKey: this.key()
+    }, this.outreach("drafted", kind, weekStart));
+    if (weekStart !== this.currentWeek())
+      return;
+    if (kind === "first_touch")
+      this.firstTouches += 1;
+    else
+      this.followUps += 1;
+  }
+  pastWeek(index) {
+    return new Date(Date.UTC(2001, 0, 1 + 7 * index)).toISOString().slice(0, 10);
+  }
+  async expectSuppressed(contactId, cause, expected = {}) {
+    const byFlag = expected.status === undefined && expected.companyStatus === undefined;
+    const state = await this.client.outreachState({ contactId });
+    if (byFlag && !state.doNotContact)
+      throw new Failure(`doNotContact is false after ${cause}`);
+    if (expected.status !== undefined && state.status !== expected.status) {
+      throw new Failure(`outreach state does not show ${cause}`);
+    }
+    if (expected.companyStatus !== undefined && state.companyStatus !== expected.companyStatus) {
+      throw new Failure(`outreach state does not show ${cause}`);
+    }
+    const candidate = await this.findCandidate(contactId, state.status);
+    if (candidate !== undefined && (byFlag && !candidate.doNotContact || expected.status !== undefined && candidate.status !== expected.status || expected.companyStatus !== undefined && candidate.companyStatus !== expected.companyStatus)) {
+      throw new Failure(`outreach candidates list the contact without ${cause}`);
+    }
+    try {
+      await this.draft(contactId, "first_touch");
+    } catch (error) {
+      if (error instanceof CrmHttpError && error.code === "refused" && error.reason === "suppressed") {
+        return;
+      }
+      throw new Failure(`a draft after ${cause} was not refused as suppressed (${describe(error)})`);
+    }
+    throw new Failure(`a draft after ${cause} was accepted`);
+  }
+  async findCandidate(contactId, status) {
+    let cursor;
+    for (let page = 0;page < CANDIDATE_PAGES; page += 1) {
+      const reply = await this.client.outreachCandidates({
+        rankAttribute: "conformanceRank",
+        statuses: { contact: [status] },
+        limit: 200,
+        ...cursor === undefined ? {} : { cursor }
+      });
+      const found = reply.candidates.find((entry) => entry.contactId === contactId);
+      if (found !== undefined)
+        return found;
+      cursor = reply.cursor;
+      if (cursor === undefined)
+        return;
+    }
+    return;
+  }
+  async raw(route, body, options = {}) {
+    const { method, path } = CRM_HTTP_ROUTES[route];
+    const headers = {
+      authorization: `Bearer ${this.target.apiKey}`,
+      accept: "application/json",
+      "user-agent": USER_AGENT,
+      [CRM_HTTP_HEADERS.contract]: CRM_HTTP_CONTRACT,
+      [CRM_HTTP_HEADERS.requestId]: randomUUID(),
+      ...body === undefined ? {} : { "content-type": "application/json" },
+      ...options.headers
+    };
+    for (const name of options.omit ?? [])
+      delete headers[name];
+    const signal = AbortSignal.timeout(RAW_TIMEOUT_MS);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.target.baseUrl.replace(/\/+$/, "")}${path}`, {
+        method,
+        redirect: "error",
+        headers,
+        ...body === undefined ? {} : { body: JSON.stringify(body) },
+        signal
+      });
+    } catch {
+      throw new Failure(signal.aborted ? "the server did not answer in time" : "the server is unreachable");
+    }
+    let text;
+    try {
+      text = await readCrmHttpBody(response, MAX_RAW_BODY_BYTES, signal);
+    } catch {
+      throw new Failure("the reply body is too large or could not be read");
+    }
+    let json;
+    try {
+      json = text === "" ? undefined : JSON.parse(text);
+    } catch {
+      json = undefined;
+    }
+    return { status: response.status, headers: response.headers, json };
+  }
+}
+function expectStatus(reply, allowed) {
+  if (!allowed.includes(reply.status)) {
+    throw new Failure(`expected HTTP ${allowed.join(" or ")}, got ${reply.status}`);
+  }
+}
+function expectErrorBody(reply, error) {
+  const body = reply.json;
+  const actual = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string" ? body.error : undefined;
+  if (actual !== error) {
+    throw new Failure(actual !== undefined && /^[a-z_]{1,64}$/.test(actual) ? `expected error ${error}, got ${actual}` : `expected error ${error}, got no contract error body`);
+  }
+}
+async function expectError(call, code, reason) {
+  try {
+    await call;
+  } catch (error) {
+    if (error instanceof CrmHttpError && error.code === code && (reason === undefined || error.reason === reason)) {
+      return;
+    }
+    throw new Failure(`expected ${code}${reason === undefined ? "" : ` (${reason})`}, got ${describe(error)}`);
+  }
+  throw new Failure(`expected ${code}${reason === undefined ? "" : ` (${reason})`}, the call succeeded`);
+}
+function describe(error) {
+  if (error instanceof Failure)
+    return error.message;
+  if (error instanceof CrmHttpError) {
+    return [
+      error.code,
+      error.reason === undefined ? undefined : `(${error.reason})`,
+      error.detailCode === undefined ? undefined : `[${error.detailCode}]`,
+      error.status === undefined ? undefined : `HTTP ${error.status}`
+    ].filter((part) => part !== undefined).join(" ");
+  }
+  return `unexpected ${error instanceof Error ? error.name : typeof error}`;
+}
+export {
+  runCrmConformance
+};