@deployfoundation/foundation-deploy 0.2.54 → 0.2.55

package/README.md

@@ -55,7 +55,7 @@ bun run packages/infra/bin/foundation-deploy.ts <command> --instance <path>
 | `slack-manifest` | Print the instance's Slack app manifest as JSON (the Slack CLI's `get-manifest` hook contract). |
 | `stage-customization` | Validate and stage a tenant-owned runtime config. |
 | `crm-key` | Write the company CRM's `crm/1` key, piped in with `--stdin`, into `<secretPrefix>/crm/http` (`crm.provider` kind `http`). |
-| `crm-check` | Run the `crm/1` conformance suite: the read cases against the instance's CRM with its stored key, or, with `--base-url --tenant --key-stdin` and no instance, any server, write cases included. |
+| `crm-check` | Run the `crm/1` conformance suite: the read cases against the instance's CRM with its stored key, or, with `--base-url --tenant --key-stdin` and no instance, any server, write cases included, every case strict given the server's harness endpoint (`--harness-url`) and the deployment's inputs (docs/crm-provider-contract.md#crm-check). A CRM can also import the suite: `@deployfoundation/foundation-deploy/crm-conformance`. |
 | `crm-replay` | Replay the agent's CRM writes (JSONL) into the instance's own table after a rollback to the DynamoDB provider. |
 
 `--instance <path>` is required for every command (or `FOUNDATION_INSTANCE_FILE`

package/dist/bin/app.js

@@ -8,16 +8,16 @@ import {
   FoundationPages,
   FoundationPipeline,
   NewsletterStack
-} from "../chunk-tfn9tvaa.js";
+} from "../chunk-68jxyg2n.js";
 import"../chunk-pxhftba1.js";
-import"../chunk-dz91avrb.js";
 import {
   adminsFor,
   instanceNames,
   loadInstanceFile,
   provisionsIntegration
-} from "../chunk-fjdgxw8h.js";
-import"../chunk-96fjaysn.js";
+} from "../chunk-pmjbzsq3.js";
+import"../chunk-dz91avrb.js";
+import"../chunk-rvx0cncy.js";
 import"../chunk-5wgwscd0.js";
 
 // bin/app.ts

package/dist/bin/foundation-deploy.js

@@ -1,17 +1,5 @@
 #!/usr/bin/env node
 // @bun
-import {
-  RELEASE_BUCKET_ENV,
-  RELEASE_VERSION_RE,
-  manifestKey,
-  releaseCacheDir,
-  skillsKey,
-  verifyManifest
-} from "../chunk-pxhftba1.js";
-import {
-  DEFAULT_RELEASE_BUCKET,
-  expectedKeyArn
-} from "../chunk-dz91avrb.js";
 import {
   argv,
   aws,
@@ -32,16 +20,28 @@ import {
   secretExists,
   stackExists,
   stackOutput
-} from "../chunk-nvsj7bbw.js";
+} from "../chunk-345e0grd.js";
+import {
+  RELEASE_BUCKET_ENV,
+  RELEASE_VERSION_RE,
+  manifestKey,
+  releaseCacheDir,
+  skillsKey,
+  verifyManifest
+} from "../chunk-pxhftba1.js";
 import {
   CUSTOMIZATION_ARTIFACT_NAME,
   instanceNames,
   mongoCollectionPolicyEnv,
   slackCommandPrefix,
   versionedConfigKey
-} from "../chunk-fjdgxw8h.js";
-import"../chunk-m76jt5rc.js";
-import"../chunk-3614v9rr.js";
+} from "../chunk-pmjbzsq3.js";
+import {
+  DEFAULT_RELEASE_BUCKET,
+  expectedKeyArn
+} from "../chunk-dz91avrb.js";
+import"../chunk-hvntk8p5.js";
+import"../chunk-xt9gdsa0.js";
 import {
   BASE_SLACK_EVENTS,
   CAPABILITY_IDS,
@@ -53,7 +53,7 @@ import {
   requiredGithubPermissions,
   requiredSlackCommands,
   requiredSlackScopes
-} from "../chunk-96fjaysn.js";
+} from "../chunk-rvx0cncy.js";
 import {
   __require
 } from "../chunk-5wgwscd0.js";
@@ -2449,6 +2449,20 @@ crm-check options
   --write              with --base-url only: also run the write cases, which
                        create records and spend the week's outreach allowance;
                        point it at a sandbox tenant
+  with --base-url --write, what the remaining write cases need:
+  --harness-url <url>  the CRM's harness endpoint (crm-harness/1), which does
+  --harness-key-stdin  what only a person can; its key comes on stdin
+  --readonly-key-stdin a key for the same tenant without write scopes, on stdin
+  --status-policy <file>
+                       the deployment's capabilities.crm.statusPolicy (JSON
+                       or YAML)
+  --suppressed-statuses <file>
+                       its capabilities.crm.outreach.suppressedStatuses
+  --spend-weekly-allowance
+                       drive this week's outreach caps to their limits
+                       (a throwaway database only)
+  Keys on stdin go one per line, in this order: the crm/1 key, the read-only
+  key, the harness key (each only when its flag is given).
 
 crm-replay options
   --from <file>        REQUIRED: the writes to replay, one JSON object per line
@@ -2462,6 +2476,22 @@ function flag2(args, name) {
   const index = args.indexOf(name);
   return index === -1 ? undefined : args[index + 1];
 }
+function valueFlag(args, name, what) {
+  if (!args.includes(name))
+    return;
+  const value = flag2(args, name);
+  if (value === undefined || value.startsWith("-"))
+    throw new Error(`${name} needs ${what}`);
+  return value;
+}
+var CRM_CHECK_TARGET_FLAGS = [
+  "--harness-url",
+  "--harness-key-stdin",
+  "--readonly-key-stdin",
+  "--status-policy",
+  "--suppressed-statuses",
+  "--spend-weekly-allowance"
+];
 function contextFor(args) {
   const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
   return awsContext({
@@ -2540,12 +2570,22 @@ ${USAGE}`);
     const tenantId = flag2(args, "--tenant");
     if (baseUrl === undefined || tenantId === undefined || !args.includes("--key-stdin"))
       throw new Error("crm-check --base-url needs --tenant <id> and --key-stdin");
-    const { crmCheckTarget, defaultCrmCommandDeps } = await import("../chunk-1pww63wd.js");
+    const harnessUrl = valueFlag(args, "--harness-url", "the CRM's harness endpoint URL");
+    if (harnessUrl !== undefined !== args.includes("--harness-key-stdin"))
+      throw new Error("crm-check --harness-url <url> and --harness-key-stdin go together: the harness key comes on stdin");
+    const statusPolicyFile = valueFlag(args, "--status-policy", "a file");
+    const suppressedStatusesFile = valueFlag(args, "--suppressed-statuses", "a file");
+    const { crmCheckTarget, defaultCrmCommandDeps } = await import("../chunk-ztrhakgc.js");
     return crmCheckTarget({
       baseUrl,
       tenantId,
       write: args.includes("--write"),
-      allowSkips: args.includes("--allow-skips")
+      allowSkips: args.includes("--allow-skips"),
+      readOnlyKeyStdin: args.includes("--readonly-key-stdin"),
+      spendWeeklyAllowance: args.includes("--spend-weekly-allowance"),
+      ...harnessUrl === undefined ? {} : { harnessUrl },
+      ...statusPolicyFile === undefined ? {} : { statusPolicyFile },
+      ...suppressedStatusesFile === undefined ? {} : { suppressedStatusesFile }
     }, defaultCrmCommandDeps());
   }
   if (command === "github-app-create") {
@@ -2613,21 +2653,24 @@ ${USAGE}`);
       return 0;
     }
     case "crm-key": {
-      const { crmKey, defaultCrmCommandDeps } = await import("../chunk-1pww63wd.js");
+      const { crmKey, defaultCrmCommandDeps } = await import("../chunk-ztrhakgc.js");
       await crmKey(ctx, { stdin: args.includes("--stdin") }, defaultCrmCommandDeps());
       return 0;
     }
     case "crm-check": {
       if (args.includes("--write"))
         throw new Error("crm-check --write creates records and spends the week's outreach allowance, so it never runs against the instance's own tenant: use --base-url with a sandbox tenant");
-      const { crmCheck, defaultCrmCommandDeps } = await import("../chunk-1pww63wd.js");
+      const targetOnly = CRM_CHECK_TARGET_FLAGS.filter((name) => args.includes(name));
+      if (targetOnly.length > 0)
+        throw new Error(`crm-check --instance runs the read cases with the deployment's own key and policy; ${targetOnly.join(", ")} feed the write cases: use --base-url --write with a sandbox tenant`);
+      const { crmCheck, defaultCrmCommandDeps } = await import("../chunk-ztrhakgc.js");
       return crmCheck(ctx, { allowSkips: args.includes("--allow-skips") }, defaultCrmCommandDeps());
     }
     case "crm-replay": {
       const from = flag2(args, "--from");
       if (from === undefined || from.startsWith("-"))
         throw new Error("crm-replay needs --from <file>: the writes to replay, as JSONL");
-      const { crmReplay, defaultCrmCommandDeps } = await import("../chunk-1pww63wd.js");
+      const { crmReplay, defaultCrmCommandDeps } = await import("../chunk-ztrhakgc.js");
       const result = await crmReplay(ctx, { from }, defaultCrmCommandDeps());
       return result.refused.length > 0 ? 1 : 0;
     }

package/dist/{chunk-nvsj7bbw.js → chunk-345e0grd.js}

@@ -1,7 +1,7 @@
 import {
   instanceNames,
   loadInstanceFile
-} from "./chunk-fjdgxw8h.js";
+} from "./chunk-pmjbzsq3.js";
 
 // src/deploy/aws.ts
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";

package/dist/{chunk-tfn9tvaa.js → chunk-68jxyg2n.js}

@@ -17,7 +17,7 @@ import {
   provisionsIntegration,
   requiresAuthenticatedQueue,
   slackCommandPrefixes
-} from "./chunk-fjdgxw8h.js";
+} from "./chunk-pmjbzsq3.js";
 import {
   capabilityScheduledJobs,
   crmOutreachConfigured,
@@ -28,7 +28,7 @@ import {
   parseSchedule,
   scheduledJobBindings,
   webhookJobBindings
-} from "./chunk-96fjaysn.js";
+} from "./chunk-rvx0cncy.js";
 
 // src/stacks/agent-stack.ts
 import * as cdk from "aws-cdk-lib";
@@ -1942,8 +1942,10 @@ function addConfigLoadAlarm(stack, args) {
       `${args.instance.displayName}'s runtime is not serving the config deployed for it: the`,
       "config failed to load, so it runs on its last good config with company-data",
       "capabilities off, or on the built-in fallback. The config_fallback_active or",
-      "config_reload_failed line in the runtime's live log group names the refused field.",
-      "Fix config.yaml, run foundation-deploy check, then deploy or config:sync."
+      "config_reload_failed line in the runtime's live log group says why: its error_message",
+      "names the refused field (record keys shown as *), the YAML error and line, or the",
+      "S3/KMS error and the IAM action it cites (error_type s3_read_failed).",
+      "Fix config.yaml or the grant, run foundation-deploy check, then deploy or config:sync."
     ].join(" "),
     metric: filter.metric({ statistic: "Sum", period: cdk2.Duration.hours(1) }),
     threshold: 1,

package/dist/{chunk-mh1206ne.js → chunk-7k4e3d7n.js}

@@ -15,7 +15,7 @@ import {
   classifyOutreach,
   movesToDraftedStatus,
   outreachWeekStart
-} from "./chunk-p7zkm4pp.js";
+} from "./chunk-caqstrxb.js";
 import {
   CRM_MAX_ACTIVITY_PAGE_SIZE,
   CRM_MAX_CURSOR_CHARS,
@@ -29,8 +29,8 @@ import {
   parseCrmOutreachQueueResponse,
   parseCrmSearchResponse,
   parseCrmTimestamp
-} from "./chunk-3614v9rr.js";
-import"./chunk-96fjaysn.js";
+} from "./chunk-xt9gdsa0.js";
+import"./chunk-rvx0cncy.js";
 import"./chunk-5wgwscd0.js";
 
 // ../capability-crm/src/proxy/repository.ts

package/dist/{chunk-p7zkm4pp.js → chunk-caqstrxb.js}

@@ -5,7 +5,7 @@ import {
   CRM_OUTREACH_REPLY_ACTIVITY,
   CRM_OUTREACH_SENT_ACTIVITY,
   CrmInputError
-} from "./chunk-3614v9rr.js";
+} from "./chunk-xt9gdsa0.js";
 
 // ../capability-crm/src/proxy/policy.ts
 class CrmPolicyRefusedError extends Error {

package/dist/chunk-gpq7e1kq.js

@@ -0,0 +1,101 @@
+import {
+  CrmConformanceHarnessError
+} from "./chunk-vcz9zbb3.js";
+import {
+  CRM_HTTP_HEADERS,
+  crmHttpBaseUrl,
+  isCrmHttpKey,
+  readCrmHttpBody
+} from "./chunk-hvntk8p5.js";
+import"./chunk-caqstrxb.js";
+import"./chunk-xt9gdsa0.js";
+import"./chunk-rvx0cncy.js";
+import"./chunk-5wgwscd0.js";
+
+// ../capability-crm/src/contract/http-harness.ts
+var CRM_HARNESS_CONTRACT = "crm-harness/1";
+var USER_AGENT = "foundation-crm-conformance/1";
+var TIMEOUT_MS = 1e4;
+var MAX_REPLY_BYTES = 64 * 1024;
+function crmHarnessUrl(value) {
+  try {
+    return crmHttpBaseUrl(value);
+  } catch {
+    throw new Error("the harness URL must be an HTTPS URL with no userinfo, query or fragment");
+  }
+}
+function createCrmHttpHarness(options) {
+  const url = crmHarnessUrl(options.url);
+  if (!isCrmHttpKey(options.apiKey)) {
+    throw new Error("the harness key must be 16 to 1024 visible ASCII characters");
+  }
+  const { apiKey, tenantId } = options;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  async function call(request) {
+    const signal = AbortSignal.timeout(TIMEOUT_MS);
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          accept: "application/json",
+          "content-type": "application/json",
+          "user-agent": USER_AGENT,
+          [CRM_HTTP_HEADERS.contract]: CRM_HARNESS_CONTRACT
+        },
+        body: JSON.stringify(request),
+        signal
+      });
+    } catch {
+      throw new CrmConformanceHarnessError(`${request.action} ${signal.aborted ? "did not answer in time" : "could not reach the harness"}`);
+    }
+    let text;
+    try {
+      text = await readCrmHttpBody(response, MAX_REPLY_BYTES, signal);
+    } catch {
+      throw new CrmConformanceHarnessError(`${request.action} reply is too large or unreadable`);
+    }
+    if (response.status < 200 || response.status > 299) {
+      throw new CrmConformanceHarnessError(`${request.action} answered HTTP ${response.status}`);
+    }
+    return text;
+  }
+  return {
+    async setStatusAsPerson(recordType, recordId, status) {
+      await call({ action: "set_status_as_person", tenantId, recordType, recordId, status });
+    },
+    async setDoNotContact(recordType, recordId) {
+      await call({ action: "set_do_not_contact", tenantId, recordType, recordId });
+    },
+    async suppressEmail(email) {
+      await call({ action: "suppress_email", tenantId, email });
+    },
+    async addPersonNote(recordType, recordId, summary) {
+      const text = await call({
+        action: "add_person_note",
+        tenantId,
+        recordType,
+        recordId,
+        summary
+      });
+      let activityId;
+      try {
+        const reply = JSON.parse(text);
+        if (typeof reply === "object" && reply !== null && "activityId" in reply) {
+          activityId = reply.activityId;
+        }
+      } catch {}
+      if (typeof activityId !== "string" || !/^[\x21-\x7e]{1,256}$/.test(activityId)) {
+        throw new CrmConformanceHarnessError("add_person_note answered no activityId");
+      }
+      return activityId;
+    }
+  };
+}
+export {
+  CRM_HARNESS_CONTRACT,
+  createCrmHttpHarness,
+  crmHarnessUrl
+};

package/dist/{chunk-m76jt5rc.js → chunk-hvntk8p5.js}

@@ -12,7 +12,7 @@ import {
   parseCrmOutreachState,
   parseCrmProviderMeta,
   parseCrmSearchResponse
-} from "./chunk-3614v9rr.js";
+} from "./chunk-xt9gdsa0.js";
 
 // ../connectors/src/crm-http.ts
 import { randomUUID } from "node:crypto";

package/dist/chunk-p6yjbtqz.js

@@ -0,0 +1,13 @@
+import {
+  CrmConformanceHarnessError,
+  runCrmConformance
+} from "./chunk-vcz9zbb3.js";
+import"./chunk-hvntk8p5.js";
+import"./chunk-caqstrxb.js";
+import"./chunk-xt9gdsa0.js";
+import"./chunk-rvx0cncy.js";
+import"./chunk-5wgwscd0.js";
+export {
+  CrmConformanceHarnessError,
+  runCrmConformance
+};

package/dist/{chunk-fjdgxw8h.js → chunk-pmjbzsq3.js}

@@ -2,7 +2,7 @@ import {
   INTEGRATION_CAPABILITY_IDS,
   PROACTIVE_CHANNEL_MODES,
   SLACK_COMMAND_PREFIX_RE
-} from "./chunk-96fjaysn.js";
+} from "./chunk-rvx0cncy.js";
 
 // ../core/src/instance.ts
 import { parse as parseYaml } from "yaml";

package/dist/{chunk-96fjaysn.js → chunk-rvx0cncy.js}

@@ -1,8 +1,3 @@
-// ../core/src/config.ts
-import { createHash as createHash2 } from "node:crypto";
-import { parse as parseYaml } from "yaml";
-import { z as z4 } from "zod";
-
 // ../core/src/capabilities.ts
 import { z } from "zod";
 
@@ -936,6 +931,11 @@ function requiredSlackCommandSuffixes(enabled) {
   return [...suffixes].sort();
 }
 
+// ../core/src/config.ts
+import { createHash as createHash2 } from "node:crypto";
+import { parse as parseYaml } from "yaml";
+import { z as z4 } from "zod";
+
 // ../core/src/jobs.ts
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { z as z3 } from "zod";
@@ -1234,6 +1234,33 @@ function parseInstanceConfig(yamlText) {
       throw new Error(`job ${job.id} owner ${job.owner} must be an instance admin`);
   return cfg;
 }
+var ZOD_ISSUE_CODES = new Set(Object.values(z4.ZodIssueCode));
+var ZOD_PARSED_TYPES = new Set(Object.values(z4.ZodParsedType));
+var YAML_ERROR_CODES = new Set([
+  "ALIAS_PROPS",
+  "BAD_ALIAS",
+  "BAD_COLLECTION_TYPE",
+  "BAD_DIRECTIVE",
+  "BAD_DQ_ESCAPE",
+  "BAD_INDENT",
+  "BAD_PROP_ORDER",
+  "BAD_SCALAR_START",
+  "BLOCK_AS_IMPLICIT_KEY",
+  "BLOCK_IN_FLOW",
+  "DUPLICATE_KEY",
+  "IMPOSSIBLE",
+  "KEY_OVER_1024_CHARS",
+  "MISSING_CHAR",
+  "MULTILINE_IMPLICIT_KEY",
+  "MULTIPLE_ANCHORS",
+  "MULTIPLE_DOCS",
+  "MULTIPLE_TAGS",
+  "NON_STRING_KEY",
+  "RESOURCE_EXHAUSTION",
+  "TAB_AS_INDENT",
+  "TAG_RESOLVE_FAILED",
+  "UNEXPECTED_TOKEN"
+]);
 
 // ../core/src/logger.ts
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -1295,4 +1322,4 @@ function wrapUntrusted(source, content) {
 ${safe}
 </${UNTRUSTED_TAG}>`;
 }
-export { parseSchedule, BASE_SLACK_EVENTS, SLACK_COMMAND_PREFIX_RE, CAPABILITY_IDS, INTEGRATION_CAPABILITY_IDS, requiredGithubPermissions, requiredSlackScopes, requiredSlackCommands, isScheduledJob, isWebhookJob, webhookJobBindings, scheduledJobBindings, jobWebhookKey, capabilityScheduledJobs, crmOutreachConfigured, crmPolicyFingerprint, parseInstanceConfig, PROACTIVE_CHANNEL_MODES, encodeProactiveChannels, wrapUntrusted };
+export { parseSchedule, RawCrmStatusPolicy, RawCrmStatusesByType, BASE_SLACK_EVENTS, SLACK_COMMAND_PREFIX_RE, CAPABILITY_IDS, INTEGRATION_CAPABILITY_IDS, requiredGithubPermissions, requiredSlackScopes, requiredSlackCommands, isScheduledJob, isWebhookJob, webhookJobBindings, scheduledJobBindings, jobWebhookKey, capabilityScheduledJobs, crmOutreachConfigured, crmPolicyFingerprint, parseInstanceConfig, PROACTIVE_CHANNEL_MODES, encodeProactiveChannels, wrapUntrusted };

package/dist/{chunk-jf5rw6h4.js → chunk-vcz9zbb3.js}

@@ -6,21 +6,26 @@ import {
   createCrmHttpClient,
   encodeCrmActor,
   readCrmHttpBody
-} from "./chunk-m76jt5rc.js";
+} from "./chunk-hvntk8p5.js";
 import {
   outreachWeekStart,
   personOwnedStatuses
-} from "./chunk-p7zkm4pp.js";
+} from "./chunk-caqstrxb.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";
+} from "./chunk-xt9gdsa0.js";
 
 // ../capability-crm/src/contract/conformance.ts
 import { randomUUID } from "node:crypto";
+class CrmConformanceHarnessError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CrmConformanceHarnessError";
+  }
+}
+
 class Skip extends Error {
   reason;
   needs;
@@ -386,9 +391,11 @@ class Suite {
     return;
   }
   async transitionCase() {
-    const transition = this.target.disallowedTransition;
-    if (transition === undefined)
-      throw new Skip("no disallowedTransition given");
+    const given = this.target.disallowedTransition;
+    const transition = given ?? this.policyDisallowedTransition();
+    if (transition === undefined) {
+      throw new Skip(this.target.statusPolicy === undefined ? "no disallowedTransition or statusPolicy given" : "the statusPolicy allows every move from a new record's status");
+    }
     const fixture = await this.fixture("transition");
     const recordId = transition.recordType === "company" ? fixture.companyId : fixture.contactId;
     const current = await this.profile(transition.recordType, recordId);
@@ -398,6 +405,23 @@ class Suite {
       status: transition.to,
       idempotencyKey: this.key()
     }, { status: current.status, statusVersion: current.statusVersion ?? 0 }), "refused", "transition_not_allowed");
+    return given === undefined ? `${transition.recordType} → ${transition.to}, from the statusPolicy` : undefined;
+  }
+  policyDisallowedTransition() {
+    const policy = this.target.statusPolicy;
+    if (policy === undefined)
+      return;
+    const meta = this.requireMeta();
+    for (const recordType of ["company", "contact"]) {
+      const rule = policy[recordType];
+      const [first, ...others] = meta.statuses[recordType];
+      if (rule === undefined || first === undefined)
+        continue;
+      const exits = Object.hasOwn(rule.agentTransitions, first) ? rule.agentTransitions[first] ?? [] : [];
+      const to = others.find((status) => !exits.includes(status));
+      if (to !== undefined)
+        return { recordType, to };
+    }
     return;
   }
   async statusLockedCase() {
@@ -1102,6 +1126,8 @@ async function expectError(call, code, reason) {
 function describe(error) {
   if (error instanceof Failure)
     return error.message;
+  if (error instanceof CrmConformanceHarnessError)
+    return `harness: ${error.message}`;
   if (error instanceof CrmHttpError) {
     return [
       error.code,
@@ -1112,6 +1138,5 @@ function describe(error) {
   }
   return `unexpected ${error instanceof Error ? error.name : typeof error}`;
 }
-export {
-  runCrmConformance
-};
+
+export { CrmConformanceHarnessError, runCrmConformance };

package/dist/{chunk-3614v9rr.js → chunk-xt9gdsa0.js}

@@ -1,6 +1,6 @@
 import {
   wrapUntrusted
-} from "./chunk-96fjaysn.js";
+} from "./chunk-rvx0cncy.js";
 
 // ../connectors/src/crm.ts
 var CRM_MAX_BATCH_SIZE = 100;

package/dist/{chunk-1pww63wd.js → chunk-ztrhakgc.js}

@@ -3,8 +3,8 @@ import {
   putSecretString,
   readSecretString,
   secretExists
-} from "./chunk-nvsj7bbw.js";
-import"./chunk-fjdgxw8h.js";
+} from "./chunk-345e0grd.js";
+import"./chunk-pmjbzsq3.js";
 import {
   CrmIdempotencyConflictError,
   CrmRecordNotFoundError
@@ -12,27 +12,30 @@ import {
 import {
   crmHttpBaseUrl,
   isCrmHttpKey
-} from "./chunk-m76jt5rc.js";
+} from "./chunk-hvntk8p5.js";
 import {
   CrmPolicyRefusedError
-} from "./chunk-p7zkm4pp.js";
+} from "./chunk-caqstrxb.js";
 import {
   CRM_MAX_ID_CHARS,
   CrmInputError,
   parseCrmLogActivityArgs,
   parseCrmUpdateStatusArgs,
   parseCrmUpsertRecordsArgs
-} from "./chunk-3614v9rr.js";
+} from "./chunk-xt9gdsa0.js";
 import {
+  RawCrmStatusPolicy,
+  RawCrmStatusesByType,
   crmOutreachConfigured,
   parseInstanceConfig
-} from "./chunk-96fjaysn.js";
+} from "./chunk-rvx0cncy.js";
 import {
   __require
 } from "./chunk-5wgwscd0.js";
 
 // src/deploy/crm.ts
 import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
 function httpProvider(ctx, command) {
   const { instance } = ctx;
   const provider = instance.crm.provider;
@@ -78,6 +81,11 @@ async function crmCheck(ctx, options, deps) {
   });
   return reportConformance(report, provider.baseUrl, deps.log);
 }
+var STDIN_KEYS = [
+  { flag: "--key-stdin", name: "the crm/1 key" },
+  { flag: "--readonly-key-stdin", name: "the read-only key" },
+  { flag: "--harness-key-stdin", name: "the harness key" }
+];
 async function crmCheckTarget(options, deps) {
   let baseUrl;
   try {
@@ -87,20 +95,86 @@ async function crmCheckTarget(options, deps) {
   }
   if (!/^[\x21-\x7e]{1,256}$/.test(options.tenantId))
     throw new Error("--tenant must be the tenant id the server's /meta names");
-  const apiKey = (await deps.readStdin()).trim();
-  if (!isCrmHttpKey(apiKey))
-    throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+  const writeInputs = [
+    ["--harness-url", options.harnessUrl !== undefined],
+    ["--readonly-key-stdin", options.readOnlyKeyStdin === true],
+    ["--status-policy", options.statusPolicyFile !== undefined],
+    ["--suppressed-statuses", options.suppressedStatusesFile !== undefined],
+    ["--spend-weekly-allowance", options.spendWeeklyAllowance === true]
+  ].filter(([, given]) => given).map(([flag]) => flag);
+  if (!options.write && writeInputs.length > 0)
+    throw new Error(`${writeInputs.join(", ")} only feed the write cases: add --write, against a sandbox tenant`);
+  const { createCrmHttpHarness, crmHarnessUrl } = await import("./chunk-gpq7e1kq.js");
+  let harnessUrl;
+  try {
+    harnessUrl = options.harnessUrl === undefined ? undefined : crmHarnessUrl(options.harnessUrl);
+  } catch {
+    throw new Error("--harness-url must be an HTTPS URL with no userinfo, query or fragment");
+  }
+  const statusPolicy = options.statusPolicyFile === undefined ? undefined : deploymentInput(deps, "--status-policy", options.statusPolicyFile, RawCrmStatusPolicy);
+  const suppressedStatuses = options.suppressedStatusesFile === undefined ? undefined : deploymentInput(deps, "--suppressed-statuses", options.suppressedStatusesFile, RawCrmStatusesByType);
+  const wanted = STDIN_KEYS.filter(({ flag }) => flag === "--key-stdin" || flag === "--readonly-key-stdin" && options.readOnlyKeyStdin === true || flag === "--harness-key-stdin" && harnessUrl !== undefined);
+  const keys = stdinKeys(await deps.readStdin(), wanted);
+  const key = (flag) => keys[wanted.findIndex((entry) => entry.flag === flag)];
+  const apiKey = key("--key-stdin");
+  const readOnlyApiKey = key("--readonly-key-stdin");
+  const harnessKey = key("--harness-key-stdin");
+  const harness = harnessUrl === undefined || harnessKey === undefined ? undefined : createCrmHttpHarness({
+    url: harnessUrl,
+    apiKey: harnessKey,
+    tenantId: options.tenantId,
+    fetchImpl: deps.fetch
+  });
   const report = await deps.runConformance({
     baseUrl,
     apiKey,
     tenantId: options.tenantId,
     write: options.write,
-    strict: !options.allowSkips
+    strict: !options.allowSkips,
+    ...readOnlyApiKey === undefined ? {} : { readOnlyApiKey },
+    ...statusPolicy === undefined ? {} : { statusPolicy },
+    ...suppressedStatuses === undefined ? {} : { suppressedStatuses },
+    ...options.spendWeeklyAllowance === true ? { spendWeeklyAllowance: true } : {},
+    ...harness === undefined ? {} : { harness }
   });
-  return reportConformance(report, baseUrl, deps.log);
+  return reportConformance(report, baseUrl, deps.log, harnessUrl);
+}
+function stdinKeys(text, wanted) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== "");
+  if (wanted.length === 1) {
+    if (lines.length !== 1 || !isCrmHttpKey(lines[0]))
+      throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+    return lines;
+  }
+  if (lines.length !== wanted.length)
+    throw new Error(`stdin must hold ${wanted.length} keys, one per line: ${wanted.map(({ name, flag }) => `${name} (${flag})`).join(", then ")}; it held ${lines.length}`);
+  lines.forEach((line, index) => {
+    const entry = wanted[index];
+    if (!isCrmHttpKey(line))
+      throw new Error(`stdin line ${index + 1}, ${entry.name} (${entry.flag}), is not a usable key: 16 to 1024 visible ASCII characters, no spaces`);
+  });
+  return lines;
+}
+function deploymentInput(deps, flag, path, schema) {
+  let text;
+  try {
+    text = deps.readFile(path);
+  } catch {
+    throw new Error(`${flag} ${path} could not be read`);
+  }
+  let value;
+  try {
+    value = parseYaml(text);
+  } catch {
+    throw new Error(`${flag} ${path} is not JSON or YAML`);
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success)
+    throw new Error(`${flag} ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "(top level)"}: ${issue.message}`).join("; ")}`);
+  return parsed.data;
 }
-function reportConformance(report, baseUrl, log) {
-  log(`crm/1 conformance against ${baseUrl}`);
+function reportConformance(report, baseUrl, log, harnessUrl) {
+  log(`crm/1 conformance against ${baseUrl}${harnessUrl === undefined ? "" : `, harness ${harnessUrl}`}`);
   for (const entry of report.cases) {
     const mark = entry.outcome === "fail" ? "FAIL" : entry.outcome;
     log(`  ${mark.padEnd(4)}  ${entry.id}: ${entry.title}${entry.detail === undefined ? "" : ` (${entry.detail})`}`);
@@ -181,7 +255,7 @@ async function crmReplay(ctx, options, deps) {
   const crm = crmCapability(config);
   if (crm === undefined || crm.statuses.company.length === 0 || crm.statuses.contact.length === 0)
     throw new Error(`${ctx.paths.configPath}: crm-replay needs capabilities.crm with its statuses`);
-  const { createDynamoCrmClient, deterministicRecordId } = await import("./chunk-mh1206ne.js");
+  const { createDynamoCrmClient, deterministicRecordId } = await import("./chunk-7k4e3d7n.js");
   const writes = parseCrmReplay(deps.readFile(options.from), crm, deterministicRecordId);
   const counts = REPLAY_OPS.map((op) => `${writes.filter((write) => write.op === op).length} ${op}`).join(", ");
   if (ctx.dryRun === true) {
@@ -282,12 +356,13 @@ function defaultCrmCommandDeps() {
     putSecretString,
     readSecretString,
     runConformance: async (target) => {
-      const { runCrmConformance } = await import("./chunk-jf5rw6h4.js");
+      const { runCrmConformance } = await import("./chunk-p6yjbtqz.js");
       return runCrmConformance(target);
     },
     crmTableName: crmTableNameFromStack,
     documentClient: operatorDocumentClient,
     readFile: (path) => readFileSync(path, "utf8"),
+    fetch: (input, init) => fetch(input, init),
     log: (line) => console.log(line)
   };
 }

package/dist/src/crm-conformance.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Declarations for `@deployfoundation/foundation-deploy/crm-conformance`
+ * (src/crm-conformance.ts): the `crm/1` conformance suite. Self-contained on
+ * purpose: the source behind them is bundled from workspace packages that are
+ * never published. test/crm-conformance-export.test.ts fails the typecheck
+ * when these and the source drift apart.
+ *
+ * docs/crm-provider-contract.md#conformance describes each option.
+ */
+
+/** A fetch the suite sends every request through; default the global `fetch`. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type CrmRecordType = "company" | "contact";
+
+/** The agent's allowed status changes on one record type. */
+export interface CrmStatusRule {
+  /** From each status, the statuses the agent may move a record to. No entry, no exit. */
+  agentTransitions: Readonly<Record<string, readonly string[]>>;
+  /** Apply `personSet` to a status a person set; otherwise who set it does not matter. */
+  respectHumanChanges: boolean;
+  /** `advance`: only forward along `ladder`. `lock`: never. */
+  personSet: "lock" | "advance";
+  /** The evidence ladder, earliest status first. */
+  ladder: readonly string[];
+}
+
+/** Absent for a record type, any configured status of that type may be set. */
+export type CrmStatusPolicy = Readonly<Partial<Record<CrmRecordType, CrmStatusRule>>>;
+
+/** What only a person can do in a CRM, done directly by the server's own test code. */
+export interface CrmConformanceHarness {
+  /** Set a record's status as a person would: stamps `person`, bumps statusVersion. */
+  setStatusAsPerson(recordType: CrmRecordType, recordId: string, status: string): Promise<void>;
+  /** Set the do-not-contact flag on a contact or a company record. */
+  setDoNotContact(recordType: CrmRecordType, recordId: string): Promise<void>;
+  /** Suppress an email address for the tenant. */
+  suppressEmail(email: string): Promise<void>;
+  /**
+   * Log a note as a person (`attributes.by = person`); returns its activity
+   * id. The summary may exceed 4000 characters; the server must truncate it
+   * on read.
+   */
+  addPersonNote(recordType: CrmRecordType, recordId: string, summary: string): Promise<string>;
+}
+
+export interface CrmConformanceTarget {
+  baseUrl: string;
+  apiKey: string;
+  tenantId: string;
+  fetchImpl?: FetchLike;
+  /** Run cases that create records and spend outreach allowance. */
+  write?: boolean;
+  /** Also drive the weekly first-touch cap to its limit (CI against a throwaway database only). */
+  spendWeeklyAllowance?: boolean;
+  /** A key for the same tenant without write scopes: writes must be 403 forbidden. */
+  readOnlyApiKey?: string;
+  /**
+   * A status the agent may not move a fresh record of this type to (from the
+   * type's first status). Absent, it is read off `statusPolicy`.
+   */
+  disallowedTransition?: { recordType: CrmRecordType; to: string };
+  /** The deployment's status policy, as the proxy bakes it. */
+  statusPolicy?: CrmStatusPolicy;
+  /** The deployment's suppressed statuses. */
+  suppressedStatuses?: { company: readonly string[]; contact: readonly string[] };
+  harness?: CrmConformanceHarness;
+  /** Count a case skipped for want of a harness as a failure. */
+  strict?: boolean;
+  /** Prefix for created externalIds and idempotency keys; default a random id. */
+  runId?: string;
+}
+
+export type CrmConformanceOutcome = "pass" | "fail" | "skip";
+
+export interface CrmConformanceCase {
+  id: string;
+  title: string;
+  outcome: CrmConformanceOutcome;
+  /** Why it failed or was skipped: fixed text, codes and statuses, never a reply body. */
+  detail?: string;
+}
+
+export interface CrmConformanceReport {
+  contract: "crm/1";
+  passed: number;
+  failed: number;
+  skipped: number;
+  cases: CrmConformanceCase[];
+}
+
+/** Run every case against one server and report each outcome. Never throws for a server fault. */
+export declare function runCrmConformance(
+  target: CrmConformanceTarget,
+): Promise<CrmConformanceReport>;

package/dist/src/crm-conformance.js

@@ -0,0 +1,11 @@
+import {
+  runCrmConformance
+} from "../chunk-vcz9zbb3.js";
+import"../chunk-hvntk8p5.js";
+import"../chunk-caqstrxb.js";
+import"../chunk-xt9gdsa0.js";
+import"../chunk-rvx0cncy.js";
+import"../chunk-5wgwscd0.js";
+export {
+  runCrmConformance
+};

package/dist/src/index.js

@@ -10,7 +10,7 @@ import {
   FoundationPipeline,
   NewsletterStack,
   deployStatements
-} from "../chunk-tfn9tvaa.js";
+} from "../chunk-68jxyg2n.js";
 import {
   BUN_VERSION,
   LAMBDA_ENTRY_POINTS,
@@ -34,7 +34,6 @@ import {
   skipBundle,
   verifyManifest
 } from "../chunk-pxhftba1.js";
-import"../chunk-dz91avrb.js";
 import {
   LIVE_ENDPOINT_NAME,
   WEB_SEARCH_CONNECTOR_VERSION,
@@ -47,8 +46,9 @@ import {
   loadInstanceFile,
   provisionsIntegration,
   requiresAuthenticatedQueue
-} from "../chunk-fjdgxw8h.js";
-import"../chunk-96fjaysn.js";
+} from "../chunk-pmjbzsq3.js";
+import"../chunk-dz91avrb.js";
+import"../chunk-rvx0cncy.js";
 import"../chunk-5wgwscd0.js";
 export {
   BUILD_TIMEOUT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deployfoundation/foundation-deploy",
-  "version": "0.2.54",
+  "version": "0.2.55",
   "description": "Deploys one Foundation instance from a published, signed release: the CDK app and the deploy tool.",
   "license": "UNLICENSED",
   "private": false,
@@ -9,7 +9,16 @@
     "foundation-deploy": "./dist/bin/foundation-deploy.js"
   },
   "exports": {
-    ".": "./dist/src/index.js"
+    ".": "./dist/src/index.js",
+    "./crm-conformance": {
+      "types": "./dist/src/crm-conformance.d.ts",
+      "default": "./dist/src/crm-conformance.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "crm-conformance": ["./dist/src/crm-conformance.d.ts"]
+    }
   },
   "files": [
     "dist",

package/src/crm-conformance.ts

@@ -0,0 +1,27 @@
+/**
+ * `@deployfoundation/foundation-deploy/crm-conformance`: the `crm/1`
+ * conformance suite, for a CRM's own CI to run in-process with its own
+ * harness (docs/crm-provider-contract.md#conformance).
+ *
+ *   import { runCrmConformance } from "@deployfoundation/foundation-deploy/crm-conformance";
+ *
+ * This is the published package's stable surface for the suite: the function,
+ * its target and report, and the harness interface. Its declarations are
+ * hand-written in `types/crm-conformance.d.ts`, because the source behind it
+ * lives in workspace packages that are bundled, never published;
+ * `test/crm-conformance-export.test.ts` holds the two to the same types.
+ */
+export type { CrmRecordType } from "@deployfoundation/foundation-connectors/crm";
+export type { FetchLike } from "@deployfoundation/foundation-connectors/github";
+export {
+  type CrmConformanceCase,
+  type CrmConformanceHarness,
+  type CrmConformanceOutcome,
+  type CrmConformanceReport,
+  type CrmConformanceTarget,
+  runCrmConformance,
+} from "@deployfoundation/foundation-capability-crm/contract/conformance";
+export type {
+  CrmStatusPolicy,
+  CrmStatusRule,
+} from "@deployfoundation/foundation-capability-crm/proxy/policy";

package/src/deploy/cli.ts

@@ -113,6 +113,20 @@ crm-check options
   --write              with --base-url only: also run the write cases, which
                        create records and spend the week's outreach allowance;
                        point it at a sandbox tenant
+  with --base-url --write, what the remaining write cases need:
+  --harness-url <url>  the CRM's harness endpoint (crm-harness/1), which does
+  --harness-key-stdin  what only a person can; its key comes on stdin
+  --readonly-key-stdin a key for the same tenant without write scopes, on stdin
+  --status-policy <file>
+                       the deployment's capabilities.crm.statusPolicy (JSON
+                       or YAML)
+  --suppressed-statuses <file>
+                       its capabilities.crm.outreach.suppressedStatuses
+  --spend-weekly-allowance
+                       drive this week's outreach caps to their limits
+                       (a throwaway database only)
+  Keys on stdin go one per line, in this order: the crm/1 key, the read-only
+  key, the harness key (each only when its flag is given).
 
 crm-replay options
   --from <file>        REQUIRED: the writes to replay, one JSON object per line
@@ -128,6 +142,24 @@ function flag(args: readonly string[], name: string): string | undefined {
   return index === -1 ? undefined : args[index + 1];
 }
 
+/** A flag that must carry a value when given: refuses `--x` alone or followed by another flag. */
+function valueFlag(args: readonly string[], name: string, what: string): string | undefined {
+  if (!args.includes(name)) return undefined;
+  const value = flag(args, name);
+  if (value === undefined || value.startsWith("-")) throw new Error(`${name} needs ${what}`);
+  return value;
+}
+
+/** `crm-check` inputs only the `--base-url` form takes: they feed the write cases. */
+const CRM_CHECK_TARGET_FLAGS = [
+  "--harness-url",
+  "--harness-key-stdin",
+  "--readonly-key-stdin",
+  "--status-policy",
+  "--suppressed-statuses",
+  "--spend-weekly-allowance",
+] as const;
+
 /** The AWS context for a command, with the instance file already resolved. */
 function contextFor(args: readonly string[]): AwsContext {
   const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
@@ -235,6 +267,15 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
     const tenantId = flag(args, "--tenant");
     if (baseUrl === undefined || tenantId === undefined || !args.includes("--key-stdin"))
       throw new Error("crm-check --base-url needs --tenant <id> and --key-stdin");
+    const harnessUrl = valueFlag(args, "--harness-url", "the CRM's harness endpoint URL");
+    // The harness acts as a person, so it is never called without its key,
+    // and the key, like every key here, comes on stdin.
+    if ((harnessUrl !== undefined) !== args.includes("--harness-key-stdin"))
+      throw new Error(
+        "crm-check --harness-url <url> and --harness-key-stdin go together: the harness key comes on stdin",
+      );
+    const statusPolicyFile = valueFlag(args, "--status-policy", "a file");
+    const suppressedStatusesFile = valueFlag(args, "--suppressed-statuses", "a file");
     const { crmCheckTarget, defaultCrmCommandDeps } = await import("./crm.ts");
     return crmCheckTarget(
       {
@@ -242,6 +283,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
         tenantId,
         write: args.includes("--write"),
         allowSkips: args.includes("--allow-skips"),
+        readOnlyKeyStdin: args.includes("--readonly-key-stdin"),
+        spendWeeklyAllowance: args.includes("--spend-weekly-allowance"),
+        ...(harnessUrl === undefined ? {} : { harnessUrl }),
+        ...(statusPolicyFile === undefined ? {} : { statusPolicyFile }),
+        ...(suppressedStatusesFile === undefined ? {} : { suppressedStatusesFile }),
       },
       defaultCrmCommandDeps(),
     );
@@ -330,6 +376,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
         throw new Error(
           "crm-check --write creates records and spends the week's outreach allowance, so it never runs against the instance's own tenant: use --base-url with a sandbox tenant",
         );
+      const targetOnly = CRM_CHECK_TARGET_FLAGS.filter((name) => args.includes(name));
+      if (targetOnly.length > 0)
+        throw new Error(
+          `crm-check --instance runs the read cases with the deployment's own key and policy; ${targetOnly.join(", ")} feed the write cases: use --base-url --write with a sandbox tenant`,
+        );
       const { crmCheck, defaultCrmCommandDeps } = await import("./crm.ts");
       return crmCheck(ctx, { allowSkips: args.includes("--allow-skips") }, defaultCrmCommandDeps());
     }

package/src/deploy/crm.ts

@@ -5,6 +5,9 @@
  *   foundation-deploy crm-key    --instance <path> --stdin
  *   foundation-deploy crm-check  --instance <path> [--allow-skips]
  *   foundation-deploy crm-check  --base-url <url> --tenant <id> --key-stdin [--write] [--allow-skips]
+ *                                [--harness-url <url> --harness-key-stdin] [--readonly-key-stdin]
+ *                                [--status-policy <file>] [--suppressed-statuses <file>]
+ *                                [--spend-weekly-allowance]
  *   foundation-deploy crm-replay --instance <path> --from <writes.jsonl> [--dry-run]
  *
  * - `crm-key` writes the `crm/1` key into the secret FoundationData created
@@ -14,9 +17,13 @@
  *   uses the deployment's base URL, tenant and stored key and runs only the
  *   read cases, since the write cases create records and spend the week's
  *   outreach allowance. With `--base-url` (no instance at all) it is what a
- *   CRM's own CI runs against a sandbox tenant, `--write` included. Strict
- *   unless `--allow-skips`: a case only a person can set up counts as failed
- *   when it could not run.
+ *   CRM's own CI runs against a sandbox tenant, `--write` included, with the
+ *   deployment inputs the remaining cases need: the CRM's harness endpoint
+ *   (`crm-harness/1`) for what only a person can do, a read-only key, the
+ *   deployment's status policy and suppressed statuses, and leave to spend
+ *   the week's caps. Every key comes on stdin, one per line. Strict unless
+ *   `--allow-skips`: a case only a person can set up counts as failed when it
+ *   could not run.
  * - `crm-replay` is the rollback half of a cutover: once `crm.provider` is
  *   back on `dynamodb`, it writes the agent's writes made in the company's CRM
  *   since the cutover (exported as JSONL) into the instance's own table,
@@ -54,12 +61,19 @@ import {
   parseCrmUpsertRecordsArgs,
 } from "@deployfoundation/foundation-connectors/crm";
 import { crmHttpBaseUrl, isCrmHttpKey } from "@deployfoundation/foundation-connectors/crm-http";
+import type { FetchLike } from "@deployfoundation/foundation-connectors/github";
 import {
   type CrmCapabilityConfig,
   type InstanceConfig,
   crmOutreachConfigured,
   parseInstanceConfig,
 } from "@deployfoundation/foundation-core";
+import {
+  RawCrmStatusPolicy,
+  RawCrmStatusesByType,
+} from "@deployfoundation/foundation-core/capabilities";
+import { parse as parseYaml } from "yaml";
+import type { z } from "zod";
 import { type AwsContext, aws, putSecretString, readSecretString, secretExists } from "./aws.ts";
 
 /** What these commands reach outside the process; tests replace every one. */
@@ -75,6 +89,8 @@ export interface CrmCommandDeps {
   /** A DocumentClient on the operator's own credentials. */
   documentClient: (ctx: AwsContext) => Promise<CrmDocumentClient>;
   readFile: (path: string) => string;
+  /** What the HTTP harness calls the CRM's harness endpoint with. */
+  fetch: FetchLike;
   log: (line: string) => void;
 }
 
@@ -175,15 +191,35 @@ export interface CrmCheckTargetOptions extends CrmCheckOptions {
   baseUrl: string;
   tenantId: string;
   write: boolean;
+  /** The CRM's harness endpoint (`crm-harness/1`); its key is read from stdin. */
+  harnessUrl?: string;
+  /** Read a key for the same tenant without write scopes from stdin (`read_only_scope`). */
+  readOnlyKeyStdin?: boolean;
+  /** The deployment's `capabilities.crm.statusPolicy`, as a JSON or YAML file. */
+  statusPolicyFile?: string;
+  /** The deployment's `capabilities.crm.outreach.suppressedStatuses`, as a JSON or YAML file. */
+  suppressedStatusesFile?: string;
+  /** Drive this week's first-touch and follow-up caps to their limits: a throwaway database only. */
+  spendWeeklyAllowance?: boolean;
 }
 
+/** The keys `crm-check --base-url` reads from stdin: one per line, in this order. */
+const STDIN_KEYS = [
+  { flag: "--key-stdin", name: "the crm/1 key" },
+  { flag: "--readonly-key-stdin", name: "the read-only key" },
+  { flag: "--harness-key-stdin", name: "the harness key" },
+] as const;
+
+type StdinKey = (typeof STDIN_KEYS)[number];
+
 /**
  * The suite against any `crm/1` server, no instance involved: what a CRM's
- * own CI runs from the published tool. The key comes from stdin.
+ * own CI runs from the published tool. Keys come from stdin; everything else
+ * is a flag or a file, all checked before stdin is read.
  */
 export async function crmCheckTarget(
   options: CrmCheckTargetOptions,
-  deps: Pick<CrmCommandDeps, "readStdin" | "runConformance" | "log">,
+  deps: Pick<CrmCommandDeps, "readStdin" | "runConformance" | "readFile" | "fetch" | "log">,
 ): Promise<number> {
   let baseUrl: string;
   try {
@@ -194,24 +230,153 @@ export async function crmCheckTarget(
   }
   if (!/^[\x21-\x7e]{1,256}$/.test(options.tenantId))
     throw new Error("--tenant must be the tenant id the server's /meta names");
-  const apiKey = (await deps.readStdin()).trim();
-  if (!isCrmHttpKey(apiKey)) throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+  // Each of these feeds write cases only: without --write it would do nothing.
+  const writeInputs = (
+    [
+      ["--harness-url", options.harnessUrl !== undefined],
+      ["--readonly-key-stdin", options.readOnlyKeyStdin === true],
+      ["--status-policy", options.statusPolicyFile !== undefined],
+      ["--suppressed-statuses", options.suppressedStatusesFile !== undefined],
+      ["--spend-weekly-allowance", options.spendWeeklyAllowance === true],
+    ] as const
+  )
+    .filter(([, given]) => given)
+    .map(([flag]) => flag);
+  if (!options.write && writeInputs.length > 0)
+    throw new Error(
+      `${writeInputs.join(", ")} only feed the write cases: add --write, against a sandbox tenant`,
+    );
+  // Loaded here, like the suite: no other command needs it.
+  const { createCrmHttpHarness, crmHarnessUrl } = await import(
+    "@deployfoundation/foundation-capability-crm/contract/http-harness"
+  );
+  let harnessUrl: string | undefined;
+  try {
+    harnessUrl = options.harnessUrl === undefined ? undefined : crmHarnessUrl(options.harnessUrl);
+  } catch {
+    throw new Error("--harness-url must be an HTTPS URL with no userinfo, query or fragment");
+  }
+  const statusPolicy =
+    options.statusPolicyFile === undefined
+      ? undefined
+      : deploymentInput(deps, "--status-policy", options.statusPolicyFile, RawCrmStatusPolicy);
+  const suppressedStatuses =
+    options.suppressedStatusesFile === undefined
+      ? undefined
+      : deploymentInput(
+          deps,
+          "--suppressed-statuses",
+          options.suppressedStatusesFile,
+          RawCrmStatusesByType,
+        );
+
+  const wanted = STDIN_KEYS.filter(
+    ({ flag }) =>
+      flag === "--key-stdin" ||
+      (flag === "--readonly-key-stdin" && options.readOnlyKeyStdin === true) ||
+      (flag === "--harness-key-stdin" && harnessUrl !== undefined),
+  );
+  const keys = stdinKeys(await deps.readStdin(), wanted);
+  const key = (flag: StdinKey["flag"]) => keys[wanted.findIndex((entry) => entry.flag === flag)];
+  const apiKey = key("--key-stdin") as string;
+  const readOnlyApiKey = key("--readonly-key-stdin");
+  const harnessKey = key("--harness-key-stdin");
+  const harness =
+    harnessUrl === undefined || harnessKey === undefined
+      ? undefined
+      : createCrmHttpHarness({
+          url: harnessUrl,
+          apiKey: harnessKey,
+          tenantId: options.tenantId,
+          fetchImpl: deps.fetch,
+        });
   const report = await deps.runConformance({
     baseUrl,
     apiKey,
     tenantId: options.tenantId,
     write: options.write,
     strict: !options.allowSkips,
+    ...(readOnlyApiKey === undefined ? {} : { readOnlyApiKey }),
+    ...(statusPolicy === undefined ? {} : { statusPolicy }),
+    ...(suppressedStatuses === undefined ? {} : { suppressedStatuses }),
+    ...(options.spendWeeklyAllowance === true ? { spendWeeklyAllowance: true } : {}),
+    ...(harness === undefined ? {} : { harness }),
   });
-  return reportConformance(report, baseUrl, deps.log);
+  return reportConformance(report, baseUrl, deps.log, harnessUrl);
+}
+
+/**
+ * The keys on stdin, one per non-blank line, exactly as many as the flags
+ * asked for. Errors name a line and its flag, never what it held.
+ */
+function stdinKeys(text: string, wanted: readonly StdinKey[]): string[] {
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  if (wanted.length === 1) {
+    if (lines.length !== 1 || !isCrmHttpKey(lines[0]))
+      throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+    return lines;
+  }
+  if (lines.length !== wanted.length)
+    throw new Error(
+      `stdin must hold ${wanted.length} keys, one per line: ${wanted
+        .map(({ name, flag }) => `${name} (${flag})`)
+        .join(", then ")}; it held ${lines.length}`,
+    );
+  lines.forEach((line, index) => {
+    const entry = wanted[index] as StdinKey;
+    if (!isCrmHttpKey(line))
+      throw new Error(
+        `stdin line ${index + 1}, ${entry.name} (${entry.flag}), is not a usable key: 16 to 1024 visible ASCII characters, no spaces`,
+      );
+  });
+  return lines;
+}
+
+/**
+ * A block of the deployment's `capabilities.crm`, from a JSON or YAML file,
+ * validated by the same schema as that block in `config.yaml`. Errors name
+ * the file and the rule; these files hold policy, never a key.
+ */
+function deploymentInput<T>(
+  deps: Pick<CrmCommandDeps, "readFile">,
+  flag: string,
+  path: string,
+  schema: z.ZodType<T, z.ZodTypeDef, unknown>,
+): T {
+  let text: string;
+  try {
+    text = deps.readFile(path);
+  } catch {
+    throw new Error(`${flag} ${path} could not be read`);
+  }
+  let value: unknown;
+  try {
+    value = parseYaml(text);
+  } catch {
+    throw new Error(`${flag} ${path} is not JSON or YAML`);
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success)
+    throw new Error(
+      `${flag} ${path}: ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "(top level)"}: ${issue.message}`)
+        .join("; ")}`,
+    );
+  return parsed.data;
 }
 
 function reportConformance(
   report: CrmConformanceReport,
   baseUrl: string,
   log: (line: string) => void,
+  harnessUrl?: string,
 ): number {
-  log(`crm/1 conformance against ${baseUrl}`);
+  log(
+    `crm/1 conformance against ${baseUrl}${harnessUrl === undefined ? "" : `, harness ${harnessUrl}`}`,
+  );
   for (const entry of report.cases) {
     const mark = entry.outcome === "fail" ? "FAIL" : entry.outcome;
     log(
@@ -486,6 +651,7 @@ export function defaultCrmCommandDeps(): CrmCommandDeps {
     crmTableName: crmTableNameFromStack,
     documentClient: operatorDocumentClient,
     readFile: (path) => readFileSync(path, "utf8"),
+    fetch: (input, init) => fetch(input, init),
     log: (line) => console.log(line),
   };
 }

package/src/stacks/api-stack.ts

@@ -1566,8 +1566,10 @@ export function addConfigLoadAlarm(
       `${args.instance.displayName}'s runtime is not serving the config deployed for it: the`,
       "config failed to load, so it runs on its last good config with company-data",
       "capabilities off, or on the built-in fallback. The config_fallback_active or",
-      "config_reload_failed line in the runtime's live log group names the refused field.",
-      "Fix config.yaml, run foundation-deploy check, then deploy or config:sync.",
+      "config_reload_failed line in the runtime's live log group says why: its error_message",
+      "names the refused field (record keys shown as *), the YAML error and line, or the",
+      "S3/KMS error and the IAM action it cites (error_type s3_read_failed).",
+      "Fix config.yaml or the grant, run foundation-deploy check, then deploy or config:sync.",
     ].join(" "),
     metric: filter.metric({ statistic: "Sum", period: cdk.Duration.hours(1) }),
     threshold: 1,