@opengeni/contracts 0.50.0 → 1.0.0

package/src/company-profile.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+import {
+  AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES,
+  AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import { HumanInputQuestion } from "./index";
 
 export const COMPANY_PROFILE_SCALAR_MAX_CHARS = 2_048;
 export const COMPANY_PROFILE_ENTRY_MAX_CHARS = 1_024;
@@ -100,10 +107,56 @@ export const CompanyProfileContent = z
   });
 export type CompanyProfileContent = z.infer<typeof CompanyProfileContent>;
 
+/**
+ * The same profile, bounded for an **agent** author. The human `account:admin`
+ * route keeps `CompanyProfileContent` and its wider limits; this is the shape
+ * persisted by the first-party `company_profile_propose` tool. The current tool
+ * accepts only identity and mission and writes empty compatibility lists, but
+ * the validator must still read historical revisions without rewriting them.
+ */
+export const AgentAuthoredCompanyProfileContent = CompanyProfileContent.superRefine(
+  (value, context) => {
+    for (const field of ["identity", "mission"] as const) {
+      const scalar = value[field];
+      if (scalar !== null && scalar.length > AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS) {
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} is ${scalar.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+        });
+      }
+    }
+    for (const field of ["products", "customers", "goals", "constraints"] as const) {
+      for (const [index, entry] of value[field].entries()) {
+        if (entry.content.length > AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS) {
+          context.addIssue({
+            code: "custom",
+            path: [field, index, "content"],
+            message: `this entry is ${entry.content.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+          });
+        }
+      }
+    }
+    const contentBytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    if (contentBytes > AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES) {
+      context.addIssue({
+        code: "custom",
+        message: `this profile is ${contentBytes} UTF-8 bytes. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+      });
+    }
+  },
+);
+export type AgentAuthoredCompanyProfileContent = z.infer<typeof AgentAuthoredCompanyProfileContent>;
+
 export const CompanyProfileRevisionIntent = z.enum(["active", "proposal"]);
 export type CompanyProfileRevisionIntent = z.infer<typeof CompanyProfileRevisionIntent>;
 
-export const CompanyProfileProvenanceSource = z.enum(["human", "durable_learning", "migration"]);
+export const CompanyProfileProvenanceSource = z.enum([
+  "human",
+  "agent_admin",
+  "durable_learning",
+  "migration",
+]);
 export type CompanyProfileProvenanceSource = z.infer<typeof CompanyProfileProvenanceSource>;
 
 export const CompanyProfilePrincipalKind = z.enum(["human_session", "agent_attempt", "service"]);
@@ -240,6 +293,119 @@ export const CompanyProfileMutationResponse = z.object({
 });
 export type CompanyProfileMutationResponse = z.infer<typeof CompanyProfileMutationResponse>;
 
+export const COMPANY_PROFILE_AGENT_APPROVE_OPTION = "activate" as const;
+export const COMPANY_PROFILE_AGENT_REJECT_OPTION = "skip" as const;
+
+export const CompanyProfileAgentPolicyMode = z.enum(["off", "suggest", "automatic"]);
+export type CompanyProfileAgentPolicyMode = z.infer<typeof CompanyProfileAgentPolicyMode>;
+
+export const CompanyProfileAgentPolicy = z.object({
+  organizationId: z.string().uuid(),
+  mode: CompanyProfileAgentPolicyMode,
+  version: z.number().int().nonnegative(),
+  updatedAt: z.string().datetime({ offset: true }),
+  changed: z.boolean().optional(),
+});
+export type CompanyProfileAgentPolicy = z.infer<typeof CompanyProfileAgentPolicy>;
+
+export const UpdateCompanyProfileAgentPolicyRequest = z
+  .object({
+    mode: CompanyProfileAgentPolicyMode,
+    expectedVersion: z.number().int().nonnegative(),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateCompanyProfileAgentPolicyRequest = z.infer<
+  typeof UpdateCompanyProfileAgentPolicyRequest
+>;
+
+export const CompanyProfileAgentAttempt = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    agentSubjectId: z.string().trim().min(1).max(1_024),
+  })
+  .strict();
+export type CompanyProfileAgentAttempt = z.infer<typeof CompanyProfileAgentAttempt>;
+
+export const CompanyProfileAgentProposalRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    profile: CompanyProfileContent,
+    reason: z.string().trim().min(1).max(COMPANY_PROFILE_REASON_MAX_CHARS),
+  })
+  .strict();
+export type CompanyProfileAgentProposalRequest = z.infer<typeof CompanyProfileAgentProposalRequest>;
+
+// z.lazy avoids an import cycle because HumanInputQuestion is declared in the
+// root contracts module that re-exports this file.
+export const CompanyProfileAgentHumanInputPrompt = z.object({
+  questions: z.array(z.lazy(() => HumanInputQuestion)).length(1),
+  allowSkip: z.literal(false),
+});
+export type CompanyProfileAgentHumanInputPrompt = z.infer<
+  typeof CompanyProfileAgentHumanInputPrompt
+>;
+
+export const CompanyProfileAgentReviewRequiredReceipt = z.object({
+  status: z.literal("confirmation_required"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  revision: CompanyProfileRevision,
+  policyMode: z.literal("suggest"),
+  humanInput: CompanyProfileAgentHumanInputPrompt,
+  confirmWith: z.literal("company_profile_confirm"),
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentReviewRequiredReceipt = z.infer<
+  typeof CompanyProfileAgentReviewRequiredReceipt
+>;
+
+export const CompanyProfileAgentAutomaticActivationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  automaticActivationReceiptId: z.string().uuid(),
+  policyMode: z.literal("automatic"),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentAutomaticActivationReceipt = z.infer<
+  typeof CompanyProfileAgentAutomaticActivationReceipt
+>;
+
+export const CompanyProfileAgentProposalReceipt = z.discriminatedUnion("status", [
+  CompanyProfileAgentReviewRequiredReceipt,
+  CompanyProfileAgentAutomaticActivationReceipt,
+]);
+export type CompanyProfileAgentProposalReceipt = z.infer<typeof CompanyProfileAgentProposalReceipt>;
+
+export const CompanyProfileAgentConfirmRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    proposalReceiptId: z.string().uuid(),
+    humanInputRequestId: z.string().uuid(),
+  })
+  .strict();
+export type CompanyProfileAgentConfirmRequest = z.infer<typeof CompanyProfileAgentConfirmRequest>;
+
+export const CompanyProfileAgentConfirmationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  confirmationReceiptId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  humanInputRequestId: z.string().uuid(),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentConfirmationReceipt = z.infer<
+  typeof CompanyProfileAgentConfirmationReceipt
+>;
+
 export const CompanyProfileDiffRequest = z
   .object({ fromRevisionId: z.string().uuid(), toRevisionId: z.string().uuid() })
   .refine((value) => value.fromRevisionId !== value.toRevisionId, {

package/src/connect.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { IntegrationInstanceKey, IntegrationSource } from "./index";
+
+const opaqueId = z.string().min(1).max(512);
+export const ConnectOwnership = z.enum(["personal", "workspace"]);
+export type ConnectOwnership = z.infer<typeof ConnectOwnership>;
+export const ConnectProvider = z
+  .object({
+    id: opaqueId,
+    label: z.string().min(1).max(256),
+    family: opaqueId,
+    readiness: z.enum(["available", "needs_configuration", "operator_only", "unsupported"]),
+    reason: z.string().max(1024).optional(),
+    ownership: z.array(ConnectOwnership).max(2),
+    setup: z
+      .array(
+        z.enum(["none", "oauth", "credentials", "device", "installation", "openapi", "graphql"]),
+      )
+      .max(7),
+  })
+  .strict();
+export type ConnectProvider = z.infer<typeof ConnectProvider>;
+export const ConnectAccount = z
+  .object({
+    id: opaqueId,
+    providerId: opaqueId,
+    version: z.number().int().positive().optional(),
+    label: z.string().max(256),
+    ownership: ConnectOwnership,
+    status: z.enum(["connected", "auth_needed", "disabled"]),
+  })
+  .strict();
+export type ConnectAccount = z.infer<typeof ConnectAccount>;
+export const ConnectResource = z
+  .object({ id: opaqueId, label: z.string().max(512), kind: opaqueId })
+  .strict();
+export type ConnectResource = z.infer<typeof ConnectResource>;
+export const ConnectNextAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("authorize"), url: z.string().url().max(16_384) }).strict(),
+  z
+    .object({
+      type: z.literal("credentials"),
+      fields: z
+        .array(
+          z
+            .object({
+              name: opaqueId,
+              label: z.string().max(256),
+              required: z.boolean(),
+              secret: z.boolean(),
+              options: z
+                .array(z.object({ value: opaqueId, label: z.string().max(512) }).strict())
+                .max(1000)
+                .optional(),
+            })
+            .strict(),
+        )
+        .max(32),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("wait"),
+      pollAfterMs: z.number().int().min(250).max(60_000),
+      userCode: z.string().max(128).optional(),
+      verificationUrl: z.string().url().max(2048).optional(),
+    })
+    .strict(),
+  z
+    .object({ type: z.literal("select_account"), accounts: z.array(ConnectAccount).max(100) })
+    .strict(),
+  z
+    .object({
+      type: z.literal("select_resources"),
+      resources: z.array(ConnectResource).max(100),
+      cursor: z.string().max(2048).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("preview"),
+      previewId: opaqueId,
+      contentHash: opaqueId,
+      operations: z.array(ConnectResource).max(2000),
+    })
+    .strict(),
+  z.object({ type: z.literal("none") }).strict(),
+]);
+export type ConnectNextAction = z.infer<typeof ConnectNextAction>;
+export const ConnectInstallationTarget = z
+  .object({
+    instanceKey: IntegrationInstanceKey,
+    displayName: z.string().min(1).max(200),
+    expectedInstanceVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+export type ConnectInstallationTarget = z.infer<typeof ConnectInstallationTarget>;
+export const ConnectAttemptState = z.enum([
+  "ready",
+  "requires_user_action",
+  "credential_input",
+  "provider_wait",
+  "account_selection",
+  "resource_selection",
+  "preview",
+  "installing",
+  "connected_but_incomplete",
+  "complete",
+  "cancelled",
+  "expired",
+  "failed",
+  "uncertain",
+]);
+export const ConnectAttempt = z
+  .object({
+    id: opaqueId,
+    workspaceId: opaqueId,
+    providerId: opaqueId,
+    ownership: ConnectOwnership,
+    revision: z.number().int().positive(),
+    state: ConnectAttemptState,
+    credentialsCommitted: z.boolean(),
+    integrationInstalled: z.boolean(),
+    completionRequirement: z.enum(["connection", "integration", "provider_setup"]),
+    nextAction: ConnectNextAction,
+    expiresAt: z.string().datetime({ offset: true }),
+    account: ConnectAccount.optional(),
+    installationTarget: ConnectInstallationTarget.optional(),
+    source: IntegrationSource.optional(),
+    error: z
+      .object({ code: opaqueId, message: z.string().max(2048), retryable: z.boolean() })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (
+      value.state === "complete" &&
+      value.completionRequirement === "integration" &&
+      !value.integrationInstalled
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Complete setup requires an installed integration",
+      });
+    }
+    if (
+      value.state === "complete" &&
+      value.completionRequirement === "connection" &&
+      !value.credentialsCommitted
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Connection setup requires committed credentials",
+      });
+    }
+    if (
+      ["complete", "cancelled", "expired"].includes(value.state) &&
+      value.nextAction.type !== "none"
+    ) {
+      context.addIssue({ code: "custom", message: "A terminal setup has no next action" });
+    }
+  });
+export type ConnectAttempt = z.infer<typeof ConnectAttempt>;
+export const ConnectAdvance = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("credentials"),
+      values: z.record(z.string().max(256), z.string().max(16_384)),
+    })
+    .strict(),
+  z.object({ type: z.literal("account"), accountId: opaqueId }).strict(),
+  z.object({ type: z.literal("resources"), resourceIds: z.array(opaqueId).max(1000) }).strict(),
+  z
+    .object({
+      type: z.literal("install"),
+      previewId: opaqueId,
+      contentHash: opaqueId,
+      operationIds: z.array(opaqueId).max(2000),
+    })
+    .strict(),
+  z.object({ type: z.literal("retry") }).strict(),
+]);
+export type ConnectAdvance = z.infer<typeof ConnectAdvance>;
+export const ConnectOperationRequest = z
+  .object({
+    expectedRevision: z.number().int().positive().safe(),
+    idempotencyKey: opaqueId,
+  })
+  .strict();
+export const AdvanceConnectRequest = ConnectOperationRequest.extend({ action: ConnectAdvance });
+export const BeginConnectRequest = z
+  .object({
+    providerId: opaqueId,
+    ownership: ConnectOwnership,
+    // URL parsing validates separately; never transform this original string.
+    returnUrl: z.string().min(1).max(4096),
+    idempotencyKey: opaqueId,
+    reconnectAccountId: opaqueId.optional(),
+    installationTarget: ConnectInstallationTarget.optional(),
+  })
+  .strict();

package/src/connection-account-label.ts

@@ -0,0 +1,46 @@
+/** Display identity from an already authorized connection. Never used to select credentials. */
+export function connectionAccountIdentityLabel(
+  metadata: Record<string, unknown>,
+  fallback: string,
+): string {
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value.trim()
+      ? value
+          .replace(/[\u0000-\u001f\u007f]/gu, " ")
+          .trim()
+          .slice(0, 180)
+      : undefined;
+  const nestedName = (value: unknown): unknown =>
+    value && typeof value === "object" ? (value as Record<string, unknown>).name : value;
+  const name =
+    [
+      metadata.email,
+      metadata.providerEmail,
+      metadata.googleEmail,
+      metadata.gmailEmail,
+      metadata.accountLabel,
+      metadata.displayName,
+      metadata.providerDisplayName,
+      metadata.googleDisplayName,
+      metadata.accountName,
+      metadata.name,
+      metadata.slackUserName,
+      metadata.username,
+      metadata.slackUserId,
+    ]
+      .map(text)
+      .find(Boolean) ?? fallback;
+  const workspace = [
+    metadata.slackTeamName,
+    metadata.teamName,
+    metadata.workspaceName,
+    metadata.team_name,
+    metadata.workspace_name,
+    nestedName(metadata.team),
+    nestedName(metadata.workspace),
+    metadata.slackTeamId,
+  ]
+    .map(text)
+    .find(Boolean);
+  return [...new Set([name, workspace].filter(Boolean))].join(" · ");
+}

package/src/connection-authority.ts

@@ -0,0 +1,213 @@
+import { z } from "zod";
+import { ConnectionKind, SessionTenancyVisibility } from "./index";
+
+export const ConnectionAuthoritySelectionSource = z.enum(["explicit_workspace", "sender"]);
+export type ConnectionAuthoritySelectionSource = z.infer<typeof ConnectionAuthoritySelectionSource>;
+
+export const ConnectionUseSelectionSource = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$/u);
+export type ConnectionUseSelectionSource = z.infer<typeof ConnectionUseSelectionSource>;
+
+const AcceptedConnectionWork = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("turn"),
+      turnId: z.string().uuid(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("scheduled_task"),
+      taskId: z.string().uuid(),
+      taskAuthorityRevision: z.number().int().positive(),
+      runId: z.string().uuid(),
+    })
+    .strict(),
+]);
+
+/**
+ * Internal, credential-free authority frozen when work is accepted. Personal
+ * owner identity is retained only for live authorization and usage/audit
+ * attribution; it is never part of the public delegation envelope.
+ */
+export const ConnectionUseAuthoritySnapshot = z
+  .object({
+    organizationId: z.string().uuid(),
+    originWorkspaceId: z.string().uuid(),
+    targetWorkspaceId: z.string().uuid(),
+    targetSessionId: z.string().uuid(),
+    targetSessionVisibility: SessionTenancyVisibility,
+    targetSessionAuthorityEpoch: z.number().int().positive(),
+    acceptedWork: AcceptedConnectionWork,
+    connectionId: z.string().uuid(),
+    connectionGeneration: z.number().int().positive(),
+    connectionStatus: z.literal("active"),
+    providerDomain: z.string().min(1).max(2048),
+    connectionKind: ConnectionKind,
+    scope: z.enum(["workspace", "user"]),
+    ownerSubjectId: z.string().min(1).max(512).nullable(),
+    ownerOrganizationMembershipId: z.string().uuid().nullable(),
+    ownerMembershipAuthorizationRevision: z.number().int().positive().nullable().default(null),
+    authoritySource: ConnectionAuthoritySelectionSource,
+    selectionSources: z.array(ConnectionUseSelectionSource).min(1).max(128),
+    userDelegation: z.null(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const ownedBySubject = value.scope !== "workspace";
+    const delegated = value.scope === "user";
+    if (ownedBySubject !== (value.ownerSubjectId !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerSubjectId"],
+        message: "personal connections retain an owner subject",
+      });
+    }
+    if (delegated !== (value.ownerOrganizationMembershipId !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerOrganizationMembershipId"],
+        message: "only user connections retain an owner membership",
+      });
+    }
+    if (delegated !== (value.ownerMembershipAuthorizationRevision !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerMembershipAuthorizationRevision"],
+        message: "only user connections retain an owner membership revision",
+      });
+    }
+    if (delegated && value.authoritySource !== "sender") {
+      context.addIssue({
+        code: "custom",
+        path: ["authoritySource"],
+        message: "user connections require authenticated sender provenance",
+      });
+    }
+    if (!delegated && value.authoritySource === "sender") {
+      context.addIssue({
+        code: "custom",
+        path: ["authoritySource"],
+        message: "workspace connections cannot claim sender provenance",
+      });
+    }
+    if (!delegated && value.originWorkspaceId !== value.targetWorkspaceId) {
+      context.addIssue({
+        code: "custom",
+        path: ["originWorkspaceId"],
+        message: "workspace connections must be owned by the target workspace",
+      });
+    }
+  });
+export type ConnectionUseAuthoritySnapshot = z.infer<typeof ConnectionUseAuthoritySnapshot>;
+
+export const ConnectionUseDenialReason = z.enum([
+  "tenant_mismatch",
+  "workspace_access_inactive",
+  "session_inactive",
+  "session_identity_changed",
+  "session_visibility_changed",
+  "session_authority_epoch_changed",
+  "accepted_attempt_authority_required",
+  "accepted_snapshot_digest_changed",
+  "connection_missing",
+  "connection_identity_changed",
+  "connection_generation_changed",
+  "connection_status_inactive",
+  "connection_owner_changed",
+  "owner_membership_inactive",
+  "authority_missing",
+  "authority_identity_changed",
+  "authority_generation_changed",
+  "authority_status_inactive",
+  "grant_missing",
+  "grant_identity_changed",
+  "grant_generation_changed",
+  "grant_status_inactive",
+  "grant_expired",
+  "grant_already_consumed",
+]);
+export type ConnectionUseDenialReason = z.infer<typeof ConnectionUseDenialReason>;
+
+const ConnectionUseAttributionFields = z
+  .object({
+    organizationId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    connectionId: z.string().uuid(),
+    connectionGeneration: z.number().int().positive(),
+    scope: z.enum(["workspace", "user", "legacy_user"]),
+    ownerSubjectId: z.string().min(1).max(512).nullable(),
+    authorityId: z.string().uuid().nullable(),
+    grantId: z.string().uuid().nullable(),
+  })
+  .strict();
+
+function refineConnectionUseAttribution(
+  value: z.infer<typeof ConnectionUseAttributionFields>,
+  context: z.RefinementCtx,
+): void {
+  const personal = value.scope !== "workspace";
+  for (const field of ["ownerSubjectId"] as const) {
+    if (personal !== (value[field] !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: [field],
+        message: personal
+          ? `personal attribution requires ${field}`
+          : `workspace attribution cannot carry ${field}`,
+      });
+    }
+  }
+  const owned = value.scope === "user";
+  for (const field of ["authorityId"] as const) {
+    if (owned !== (value[field] !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: [field],
+        message: owned
+          ? `personal attribution requires ${field}`
+          : `non-personal attribution cannot carry ${field}`,
+      });
+    }
+  }
+  if (!owned && value.grantId !== null) {
+    context.addIssue({
+      code: "custom",
+      path: ["grantId"],
+      message: "only historical personal attribution can carry a grant",
+    });
+  }
+}
+
+/** Metadata-only attribution emitted after pre-use authorization. */
+export const ConnectionUseAttribution = ConnectionUseAttributionFields.extend({
+  scope: z.enum(["workspace", "user"]),
+  grantId: z.null(),
+}).superRefine(refineConnectionUseAttribution);
+export type ConnectionUseAttribution = z.infer<typeof ConnectionUseAttribution>;
+
+export const ConnectionUseAuditFact = ConnectionUseAttributionFields.extend({
+  outcome: z.enum(["authorized", "denied"]),
+  denialReason: ConnectionUseDenialReason.nullable(),
+  occurredAt: z.string().datetime({ offset: true }),
+}).superRefine((value, context) => {
+  refineConnectionUseAttribution(value, context);
+  if ((value.outcome === "denied") !== (value.denialReason !== null)) {
+    context.addIssue({
+      code: "custom",
+      path: ["denialReason"],
+      message: "only denied connection use carries a denial reason",
+    });
+  }
+});
+export type ConnectionUseAuditFact = z.infer<typeof ConnectionUseAuditFact>;
+
+export const ConnectionUseAuthorizationResult = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("authorized"), attribution: ConnectionUseAttribution }).strict(),
+  z.object({ status: z.literal("denied"), reason: ConnectionUseDenialReason }).strict(),
+]);
+export type ConnectionUseAuthorizationResult = z.infer<typeof ConnectionUseAuthorizationResult>;