@oxyhq/crowdsource-contracts 0.1.0

package/src/resources.ts

@@ -0,0 +1,489 @@
+/**
+ * Resources and relations — the universal content unit (§5.2–§5.7).
+ *
+ * "Applications send data, never executable code" (§5.2). Everything in this
+ * module follows from that one sentence:
+ *
+ *   * The resource union is CLOSED and discriminated on `type`, and each
+ *     variant declares exactly which fields it may carry. There is no free-form
+ *     branch, so there is no place to put a rendering instruction.
+ *   * Every object is `.strict()`. In the outbound direction an unknown field
+ *     is harmless forward compatibility (§10.11); inbound it is not. A field
+ *     that is silently dropped is context an application believes it sent and a
+ *     jury never sees — which is how a case gets decided on incomplete material
+ *     — and a field that is silently kept is a rendering input nobody reviewed.
+ *     §10.11 makes exactly this exception: unknown fields must not break
+ *     clients "except where the schema forbids them for safety".
+ *   * A media type must agree with its resource type, so an `image` cannot
+ *     declare `text/html` and be handed to something that trusts the label.
+ *   * §5.7 custom payloads are bounded JSON with no `$`-prefixed keys, which
+ *     removes every JSON Schema reference mechanism at once — `$ref` to a
+ *     remote document IS the "remote component" §5.7 forbids, and resolving one
+ *     is an SSRF against CrowdSource itself.
+ *
+ * What is deliberately NOT here: any filter on the CONTENT of text fields. The
+ * material under review is hostile by definition — a harassment report quotes
+ * the harassment, a phishing report quotes the phishing link. A lexical
+ * blocklist would reject the evidence and protect nothing, because the contract
+ * has no field whose value is ever interpreted as markup or code.
+ */
+
+import { z } from 'zod';
+
+import {
+  CONTRACT_LIMITS,
+  CustomPayloadSchema,
+  HttpUrlSchema,
+  IdentifierSchema,
+  LanguageTagSchema,
+  MetadataBagSchema,
+  MimeTypeSchema,
+  Sha256DigestSchema,
+  TimestampSchema,
+} from './primitives';
+import { PolicyVersionSchema } from './policies';
+import { SensitivityHintSchema } from './taxonomy';
+
+/** A resource id, unique within one envelope (§5.2 `id`). */
+export const ResourceIdSchema = IdentifierSchema;
+export type ResourceId = z.infer<typeof ResourceIdSchema>;
+
+/**
+ * A pseudonymous reference to an actor, resolved within one envelope.
+ *
+ * Never a real identity: §13.5 requires a pseudonymous principal wherever one
+ * suffices. `principalBindings` is the only place a ref is tied to anything,
+ * and even there it is tied to a binding proof id, not to a name.
+ */
+export const PrincipalRefSchema = IdentifierSchema;
+export type PrincipalRef = z.infer<typeof PrincipalRefSchema>;
+
+/** §5.2 `role`: why this resource is in the case. */
+export const RESOURCE_ROLES = [
+  'subject',
+  'attachment',
+  'context',
+  'parent',
+  'quoted',
+  'evidence',
+  'metadata',
+  'policy_context',
+] as const;
+export const ResourceRoleSchema = z.enum(RESOURCE_ROLES);
+export type ResourceRole = z.infer<typeof ResourceRoleSchema>;
+
+/** §5.3 standard resource types. */
+export const RESOURCE_TYPES = [
+  'text',
+  'image',
+  'video',
+  'audio',
+  'document',
+  'link',
+  'profile',
+  'conversation',
+  'listing',
+  'location',
+  'metadata',
+  'custom',
+] as const;
+export const ResourceTypeSchema = z.enum(RESOURCE_TYPES);
+export type ResourceType = z.infer<typeof ResourceTypeSchema>;
+
+/** §5.3 text formatting. Never HTML: `markdown_subset` is a subset for a reason. */
+export const TEXT_FORMATTINGS = ['plain', 'markdown_subset'] as const;
+export const TextFormattingSchema = z.enum(TEXT_FORMATTINGS);
+export type TextFormatting = z.infer<typeof TextFormattingSchema>;
+
+/**
+ * A reference to bytes held outside the envelope (§5.2 `asset`).
+ *
+ * Exactly one of `uploadId` and `url` — never both, never neither. Two
+ * locations for one piece of evidence means two answers to "what exactly did
+ * the jury look at", and §5.6 requires the case to pin the exact version that
+ * was reported. `sha256` is required for the same reason: it is what makes the
+ * answer verifiable after the application has deleted the original.
+ */
+export const AssetRefSchema = z
+  .strictObject({
+    uploadId: IdentifierSchema.optional(),
+    url: HttpUrlSchema.optional(),
+    mimeType: MimeTypeSchema,
+    sha256: Sha256DigestSchema,
+    sizeBytes: z.number().int().positive().optional(),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    durationSeconds: z.number().positive().optional(),
+  })
+  .superRefine((asset, ctx) => {
+    const hasUpload = asset.uploadId !== undefined;
+    const hasUrl = asset.url !== undefined;
+    if (hasUpload === hasUrl) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['uploadId'],
+        message: 'an asset must reference exactly one of uploadId or url',
+      });
+    }
+  });
+export type AssetRef = z.infer<typeof AssetRefSchema>;
+
+const mediaTypeMismatch = (
+  ctx: z.RefinementCtx,
+  mimeType: string,
+  allowedPrefixes: readonly string[],
+): void => {
+  if (!allowedPrefixes.some((prefix) => mimeType.startsWith(prefix))) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['asset', 'mimeType'],
+      message: `must be one of ${allowedPrefixes.join(', ')}* for this resource type`,
+    });
+  }
+};
+
+const resourceBaseShape = {
+  id: ResourceIdSchema,
+  role: ResourceRoleSchema,
+  /** §5.2: BCP 47 "where applicable" — a text of unknown language is real. */
+  language: LanguageTagSchema.optional(),
+  /** §5.2: the moment of the ORIGINAL object, not of the report. */
+  createdAt: TimestampSchema.optional(),
+  authorPrincipalRef: PrincipalRefSchema.optional(),
+  /** §5.2: a prior classification of exposure, never shown as a verdict. */
+  sensitivity: SensitivityHintSchema.optional(),
+};
+
+/**
+ * `sha256` is required on every resource whose content travels inline, and
+ * optional on asset-backed ones where `asset.sha256` carries it instead.
+ *
+ * That split is not a preference; it is what both reference envelopes do.
+ * Appendix A's `res_post` and `res_parent` carry a top-level digest and its
+ * `res_image` carries the digest on the asset only. §5.6 asks for "SHA 256 of
+ * each resource", so one of the two is always present.
+ */
+const inlineResourceShape = { ...resourceBaseShape, sha256: Sha256DigestSchema };
+const assetResourceShape = { ...resourceBaseShape, sha256: Sha256DigestSchema.optional() };
+
+const TextResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('text'),
+  data: z.strictObject({
+    text: z.string().min(1).max(CONTRACT_LIMITS.TEXT_RESOURCE_MAX_LENGTH),
+    formatting: TextFormattingSchema.optional(),
+  }),
+});
+
+const ImageResourceSchema = z
+  .strictObject({
+    ...assetResourceShape,
+    type: z.literal('image'),
+    asset: AssetRefSchema,
+  })
+  .superRefine((resource, ctx) => mediaTypeMismatch(ctx, resource.asset.mimeType, ['image/']));
+
+const VideoResourceSchema = z
+  .strictObject({
+    ...assetResourceShape,
+    type: z.literal('video'),
+    asset: AssetRefSchema,
+    data: z
+      .strictObject({
+        timeRange: z
+          .strictObject({
+            startSeconds: z.number().nonnegative(),
+            endSeconds: z.number().positive(),
+          })
+          .refine((range) => range.endSeconds > range.startSeconds, {
+            message: 'endSeconds must be greater than startSeconds',
+            path: ['endSeconds'],
+          })
+          .optional(),
+      })
+      .optional(),
+  })
+  .superRefine((resource, ctx) => {
+    mediaTypeMismatch(ctx, resource.asset.mimeType, ['video/']);
+    if (resource.asset.durationSeconds === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['asset', 'durationSeconds'],
+        message: 'a video asset must declare durationSeconds',
+      });
+    }
+  });
+
+const AudioResourceSchema = z
+  .strictObject({
+    ...assetResourceShape,
+    type: z.literal('audio'),
+    asset: AssetRefSchema,
+    data: z
+      .strictObject({
+        transcript: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
+      })
+      .optional(),
+  })
+  .superRefine((resource, ctx) => {
+    mediaTypeMismatch(ctx, resource.asset.mimeType, ['audio/']);
+    if (resource.asset.durationSeconds === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['asset', 'durationSeconds'],
+        message: 'an audio asset must declare durationSeconds',
+      });
+    }
+  });
+
+const DocumentResourceSchema = z
+  .strictObject({
+    ...assetResourceShape,
+    type: z.literal('document'),
+    asset: AssetRefSchema,
+    data: z.strictObject({
+      title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+      extractedText: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
+    }),
+  })
+  .superRefine((resource, ctx) =>
+    mediaTypeMismatch(ctx, resource.asset.mimeType, ['application/', 'text/']),
+  );
+
+const LinkResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('link'),
+  data: z.strictObject({
+    url: HttpUrlSchema,
+    title: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+    resolvedHost: z
+      .string()
+      .max(253)
+      .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/, 'must be a hostname')
+      .optional(),
+    snapshot: z.string().max(CONTRACT_LIMITS.EXTRACTED_TEXT_MAX_LENGTH).optional(),
+  }),
+});
+
+const ProfileResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('profile'),
+  data: z.strictObject({
+    /**
+     * Every field is optional on purpose. A federated or unresolved actor
+     * routinely has no display name, and requiring one would push applications
+     * into synthesising a name — the opposite of what the profile-identity rule
+     * in the ecosystem instructions asks for.
+     */
+    displayName: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+    bio: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+    /** An `image` resource in the same envelope. */
+    avatarRef: ResourceIdSchema.optional(),
+    claims: MetadataBagSchema.optional(),
+  }),
+});
+
+const ConversationResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('conversation'),
+  data: z.strictObject({
+    /**
+     * Ordered (§5.3). §13.5 asks for five messages around the incident rather
+     * than the whole thread, which is why this is a bounded list of ids the
+     * application chose, not a pointer to a conversation.
+     */
+    messageResourceIds: z
+      .array(ResourceIdSchema)
+      .min(1)
+      .max(CONTRACT_LIMITS.CONVERSATION_MESSAGES_MAX),
+  }),
+});
+
+const ListingResourceSchema = z
+  .strictObject({
+    ...inlineResourceShape,
+    type: z.literal('listing'),
+    data: z.strictObject({
+      title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+      description: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+      price: z.number().finite().nonnegative().optional(),
+      currency: z
+        .string()
+        .regex(/^[A-Z]{3}$/, 'must be an ISO 4217 alphabetic code')
+        .optional(),
+      sellerRef: PrincipalRefSchema.optional(),
+      mediaRefs: z.array(ResourceIdSchema).max(CONTRACT_LIMITS.LISTING_MEDIA_REFS_MAX).optional(),
+    }),
+  })
+  .superRefine((resource, ctx) => {
+    const hasPrice = resource.data.price !== undefined;
+    const hasCurrency = resource.data.currency !== undefined;
+    if (hasPrice !== hasCurrency) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['data', hasPrice ? 'currency' : 'price'],
+        message: 'price and currency must travel together',
+      });
+    }
+  });
+
+/** Two decimal places ≈ 1.1 km — coarse enough not to locate a person. */
+const COARSE_COORDINATE_DECIMALS = 2;
+
+const isCoarse = (value: number): boolean =>
+  Number.isInteger(value * 10 ** COARSE_COORDINATE_DECIMALS);
+
+const LocationResourceSchema = z
+  .strictObject({
+    ...inlineResourceShape,
+    type: z.literal('location'),
+    data: z.strictObject({
+      label: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+      latitude: z.number().min(-90).max(90).optional(),
+      longitude: z.number().min(-180).max(180).optional(),
+    }),
+  })
+  .superRefine((resource, ctx) => {
+    const { label, latitude, longitude } = resource.data;
+    if (label === undefined && latitude === undefined && longitude === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['data'],
+        message: 'a location must carry a label, coordinates, or both',
+      });
+    }
+    if ((latitude === undefined) !== (longitude === undefined)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['data', latitude === undefined ? 'latitude' : 'longitude'],
+        message: 'latitude and longitude must travel together',
+      });
+    }
+    /**
+     * §5.3 says "coarse location or place label" and §13.5 requires precise
+     * location to be redacted before community review. Precision is a property
+     * of the number itself, so the contract can refuse the precise value rather
+     * than trusting every downstream renderer to round it.
+     */
+    if (latitude !== undefined && !isCoarse(latitude)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['data', 'latitude'],
+        message: `must be coarse: at most ${COARSE_COORDINATE_DECIMALS} decimal places`,
+      });
+    }
+    if (longitude !== undefined && !isCoarse(longitude)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['data', 'longitude'],
+        message: `must be coarse: at most ${COARSE_COORDINATE_DECIMALS} decimal places`,
+      });
+    }
+  });
+
+const MetadataResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('metadata'),
+  data: MetadataBagSchema.refine((bag) => Object.keys(bag).length >= 1, {
+    message: 'a metadata resource must carry at least one field',
+  }),
+});
+
+const CustomResourceSchema = z.strictObject({
+  ...inlineResourceShape,
+  type: z.literal('custom'),
+  /** The schema the application registered for this shape (§5.7). */
+  schemaId: IdentifierSchema,
+  /**
+   * Validated twice: structurally here, then against the registered JSON Schema
+   * at ingress. The registered schema decides what the fields MEAN; this decides
+   * that they are fields at all.
+   */
+  payload: CustomPayloadSchema,
+});
+
+/**
+ * One resource (§5.2).
+ *
+ * A discriminated union rather than one object with everything optional: the
+ * latter would accept an `image` with inline text and no asset, which is not a
+ * resource anybody can review.
+ */
+export const ResourceSchema = z.discriminatedUnion('type', [
+  TextResourceSchema,
+  ImageResourceSchema,
+  VideoResourceSchema,
+  AudioResourceSchema,
+  DocumentResourceSchema,
+  LinkResourceSchema,
+  ProfileResourceSchema,
+  ConversationResourceSchema,
+  ListingResourceSchema,
+  LocationResourceSchema,
+  MetadataResourceSchema,
+  CustomResourceSchema,
+]);
+export type Resource = z.infer<typeof ResourceSchema>;
+
+/** §5.5 relation types. */
+export const RELATION_TYPES = [
+  'has_attachment',
+  'replies_to',
+  'quotes',
+  'authored_by',
+  'contextualizes',
+  'previous_version',
+  'contains',
+  'refers_to',
+] as const;
+export const RelationTypeSchema = z.enum(RELATION_TYPES);
+export type RelationType = z.infer<typeof RelationTypeSchema>;
+
+/**
+ * Relation types whose `to` names a principal rather than a resource.
+ *
+ * §5.5 defines `authored_by` as "a resource was created by a principal", so its
+ * target is a `principalRef`. Every other relation in the table joins two
+ * resources. No example in the plan exercises `authored_by`, so this reading is
+ * recorded here rather than assumed: it is what makes §5.5's "the backend must
+ * validate that every referenced id exists in the envelope" checkable at all,
+ * since the two id spaces are separate.
+ */
+export const PRINCIPAL_TARGETED_RELATION_TYPES = ['authored_by'] as const;
+
+/**
+ * A relation (§5.5).
+ *
+ * `from` and `to` are only shape-checked here. Whether they RESOLVE is decided
+ * by `CaseEnvelopeSchema`, which is the smallest scope that can see both the
+ * resource list and the principal list.
+ */
+export const RelationSchema = z.strictObject({
+  from: ResourceIdSchema,
+  type: RelationTypeSchema,
+  to: IdentifierSchema,
+});
+export type Relation = z.infer<typeof RelationSchema>;
+
+/**
+ * A custom resource schema an application registers (§5.7).
+ *
+ * `jsonSchema` reuses the custom-payload grammar, which forbids `$`-prefixed
+ * keys. That single restriction removes `$ref`, `$dynamicRef`, `$recursiveRef`
+ * and `$id` in one move — every mechanism by which a registered schema could
+ * point at a document CrowdSource would then have to fetch. §5.7's "no remote
+ * components" is not a rendering rule alone; a remote `$ref` is also an SSRF
+ * with a tenant holding the pen.
+ *
+ * The cost is `$defs`, `$schema` and `$comment`, which flat custom-field
+ * schemas do not need. Recursive tenant schemas are not supported and are not
+ * meant to be.
+ */
+export const ResourceSchemaRegistrationSchema = z.strictObject({
+  schemaId: IdentifierSchema,
+  version: PolicyVersionSchema,
+  title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+  description: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+  jsonSchema: CustomPayloadSchema,
+});
+export type ResourceSchemaRegistration = z.infer<typeof ResourceSchemaRegistrationSchema>;

package/src/reviews.ts

@@ -0,0 +1,159 @@
+/**
+ * What one reviewer submits (§9.2, §9.3) and how they step away (§4.1).
+ *
+ * §9.2 splits the form in two — describe the material, then evaluate it against
+ * a rule — to reduce anchoring on the reporter's category and to let the same
+ * description be reused under different policies. §9.3 then gives one flat
+ * result object. Both are true at once: a `ReviewFinding` carries the step-one
+ * fields (`code`, `resourceIds`, `severity`, `confidence`) and the step-two
+ * fields (`policyRuleIds`), and the enclosing submission carries the step-two
+ * verdict (`outcome`, `recommendedActions`). The split is a property of the
+ * interface, not of the payload, so it is documented here rather than nested.
+ *
+ * The submission is `.strict()`, and that is a safety decision, not tidiness.
+ * A review belongs to an assignment the server issued; the assignment id comes
+ * from the route, the case and the reviewer come from the assignment. If this
+ * object tolerated a `caseId`, an `assignmentId` or a `reviewerId`, the day
+ * somebody read one of them would be the day a reviewer could vote on a case
+ * they were never drawn for — against "nobody chooses the case they review".
+ * Strict makes that field impossible rather than merely unused.
+ */
+
+import { z } from 'zod';
+
+import { CONTRACT_LIMITS, UnitIntervalSchema } from './primitives';
+import { PolicyRuleIdSchema } from './policies';
+import { ResourceIdSchema } from './resources';
+import {
+  FindingContextSchema,
+  RecommendedActionSchema,
+  SeveritySchema,
+  TaxonomyCodeSchema,
+} from './taxonomy';
+
+/**
+ * What a single reviewer can conclude.
+ *
+ * Narrower than §9.6's decision outcomes on purpose. `inconclusive` is what the
+ * consensus engine reports when a panel does not agree — a single reviewer
+ * cannot fail to agree with themselves, and "the absence of consensus is
+ * neither guilt nor innocence" only holds if `inconclusive` is produced by the
+ * engine and never voted for. `duplicate`, `escalated` and `superseded` are
+ * likewise case-level states, not opinions about material. The plan never
+ * enumerates review outcomes; this is that gap resolved toward the invariant.
+ */
+export const REVIEW_OUTCOMES = [
+  'violation',
+  'no_violation',
+  'insufficient_context',
+  'content_unavailable',
+] as const;
+export const ReviewOutcomeSchema = z.enum(REVIEW_OUTCOMES);
+export type ReviewOutcome = z.infer<typeof ReviewOutcomeSchema>;
+
+/** §9.5 feeds this into `contextFactor`: 1.0 if sufficient, 0.5 otherwise. */
+export const CONTEXT_SUFFICIENCIES = ['sufficient', 'insufficient'] as const;
+export const ContextSufficiencySchema = z.enum(CONTEXT_SUFFICIENCIES);
+export type ContextSufficiency = z.infer<typeof ContextSufficiencySchema>;
+
+/**
+ * One structured finding from one reviewer (§9.3).
+ *
+ * `resourceIds` is required and non-empty: §9.4 makes the affected resource one
+ * of the dimensions consensus is measured on, so a finding that does not say
+ * what it is about cannot be agreed with or disagreed with.
+ *
+ * `policyRuleIds` is optional: step one of the form can complete without step
+ * two — a reviewer may classify material accurately and find no rule that
+ * covers it, which is exactly the `no_violation`-with-findings case §6.2
+ * describes.
+ *
+ * `context` is §9.2's and §9.4's "excepción", written as §6.2 writes it: beside
+ * the code and the severity, because "artistic nudity" is a different
+ * description of the material from "nudity" rather than a different verdict
+ * about it. Optional, and absence means no exception applies.
+ *
+ * `confidence` communicates quality and triggers escalation (§9.5). It never
+ * weights the vote.
+ */
+export const ReviewFindingSchema = z.strictObject({
+  code: TaxonomyCodeSchema,
+  resourceIds: z.array(ResourceIdSchema).min(1).max(CONTRACT_LIMITS.RESOURCE_REFS_PER_FINDING_MAX),
+  severity: SeveritySchema,
+  context: FindingContextSchema.optional(),
+  confidence: UnitIntervalSchema,
+  policyRuleIds: z.array(PolicyRuleIdSchema).max(CONTRACT_LIMITS.POLICY_RULE_IDS_MAX).optional(),
+});
+export type ReviewFinding = z.infer<typeof ReviewFindingSchema>;
+
+/**
+ * The body of `POST /v1/reviewer/assignments/{id}/reviews` — §9.3's "result of
+ * a review".
+ *
+ * `recommendedActions` is a list of action tokens here, where a decision's
+ * `recommendedActions` are objects that name their target resources. That
+ * difference is in the plan (§9.3 versus Appendix B) and is kept: a reviewer
+ * recommends a course of action, and the consensus process is what binds an
+ * agreed recommendation to the specific resources it applies to.
+ */
+export const ReviewSubmissionSchema = z
+  .strictObject({
+    outcome: ReviewOutcomeSchema,
+    contextSufficiency: ContextSufficiencySchema,
+    findings: z.array(ReviewFindingSchema).max(CONTRACT_LIMITS.FINDINGS_MAX),
+    recommendedActions: z
+      .array(RecommendedActionSchema)
+      .max(CONTRACT_LIMITS.RECOMMENDED_ACTIONS_MAX),
+    /**
+     * §13.5 and the "sensitive content never reaches logs" invariant apply to
+     * this field as much as to the evidence: a note is free text a human wrote
+     * while looking at the material, so it is bounded here and must be treated
+     * as case content everywhere downstream — never logged, never attested.
+     */
+    notes: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+  })
+  .superRefine((review, ctx) => {
+    if (review.outcome === 'insufficient_context' && review.contextSufficiency !== 'insufficient') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['contextSufficiency'],
+        message: 'an outcome of insufficient_context requires contextSufficiency "insufficient"',
+      });
+    }
+    if (review.outcome === 'violation' && review.findings.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['findings'],
+        message: 'a violation outcome requires at least one finding',
+      });
+    }
+  });
+export type ReviewSubmission = z.infer<typeof ReviewSubmissionSchema>;
+
+/**
+ * §4.1: a reviewer may declare a conflict, a language they do not have,
+ * material too sensitive for them, or context they cannot obtain — "without
+ * penalty". These four are the plan's own list, made structured as §10.3 asks.
+ */
+export const RECUSAL_REASONS = [
+  'conflict_of_interest',
+  'language',
+  'too_sensitive',
+  'insufficient_context',
+] as const;
+export const RecusalReasonSchema = z.enum(RECUSAL_REASONS);
+export type RecusalReason = z.infer<typeof RecusalReasonSchema>;
+
+/**
+ * The body of `POST /v1/reviewer/assignments/{id}/recuse`.
+ *
+ * Strict for the same reason as the submission, and with no free-text field
+ * beyond a short optional note: a recusal is routing information, and the more
+ * it can say about the case, the more it becomes a channel for case content to
+ * leak into operational data.
+ */
+export const RecusalSubmissionSchema = z.strictObject({
+  reason: RecusalReasonSchema,
+  note: z.string().max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH).optional(),
+});
+export type RecusalSubmission = z.infer<typeof RecusalSubmissionSchema>;