@oxyhq/crowdsource-contracts 0.1.0

package/src/decisions.ts

@@ -0,0 +1,216 @@
+/**
+ * Decisions (§9.6, §9.9, Appendix B).
+ *
+ * "A published decision is never edited, only superseded." No parse can see a
+ * second write, so schema-level immutability would be theatre — and a shallow
+ * `Object.freeze` on the parsed result would be worse than theatre, since it
+ * would leave `findings` mutable while looking like a guarantee. Immutability
+ * is enforced where it is real: the store never updates a published revision.
+ *
+ * What the schema CAN enforce is the shape of the supersession chain, and it
+ * does: revision 1 supersedes nothing, and every later revision names what it
+ * replaced. §9.9's worked example is exactly that, and a revision 2 that
+ * supersedes nothing would be an edit wearing a new number.
+ *
+ * Decisions travel outbound, to tenants and to the reviewer app, so they are
+ * `.loose()`: §10.11 requires unknown fields not to break clients, and passing
+ * them through rather than stripping them means a client that persists a
+ * decision keeps whatever a newer CrowdSource added. This is the opposite of
+ * the inbound rule in `case-envelope.ts`, for the opposite reason.
+ */
+
+import { z } from 'zod';
+
+import { CONTRACT_LIMITS, IdentifierSchema, TimestampSchema, UnitIntervalSchema } from './primitives';
+import { DecisionPolicyVersionsSchema, PolicyRuleIdSchema } from './policies';
+import { ResourceIdSchema } from './resources';
+import { ContextSufficiencySchema } from './reviews';
+import {
+  FindingAttributionSchema,
+  FindingContextSchema,
+  FindingScopeSchema,
+  RecommendedActionSchema,
+  SeveritySchema,
+  TaxonomyCodeSchema,
+} from './taxonomy';
+
+/** §3.2 decision states. */
+export const DECISION_STATUSES = ['provisional', 'final', 'superseded', 'corrected'] as const;
+export const DecisionStatusSchema = z.enum(DECISION_STATUSES);
+export type DecisionStatus = z.infer<typeof DecisionStatusSchema>;
+
+/**
+ * §9.6 outcomes.
+ *
+ * `inconclusive` is its own outcome and must never collapse into
+ * `no_violation`: a jury that reviewed the case and did not reach the threshold
+ * has said something different from a jury that agreed nothing was wrong. Both
+ * are here, distinctly, and no code in this package maps one to the other.
+ */
+export const DECISION_OUTCOMES = [
+  'violation',
+  'no_violation',
+  'insufficient_context',
+  'inconclusive',
+  'content_unavailable',
+  'duplicate',
+  'escalated',
+] as const;
+export const DecisionOutcomeSchema = z.enum(DECISION_OUTCOMES);
+export type DecisionOutcome = z.infer<typeof DecisionOutcomeSchema>;
+
+/**
+ * A confirmed finding (Appendix B).
+ *
+ * Carries two fields a `ReviewFinding` does not. `scope` says how far the
+ * finding reaches and is what §11.7.5 gates an Oxy Trust effect on;
+ * `attribution` names whose conduct it is. Neither belongs on an individual
+ * review: a reviewer classifies material, and it is the consensus process that
+ * decides the classification is confirmed and therefore attributable.
+ *
+ * `attribution` is optional because plenty of confirmed findings attribute
+ * nothing to anybody — material can violate a rule without any principal having
+ * behaved badly.
+ *
+ * `context` carries §6.2's exception through unchanged from the reviews that
+ * agreed on it. It is one of §9.4's six consensus dimensions, so a published
+ * finding that dropped it would be a decision nobody could reproduce from the
+ * ballots.
+ */
+export const DecisionFindingSchema = z.looseObject({
+  code: TaxonomyCodeSchema,
+  resourceIds: z.array(ResourceIdSchema).min(1).max(CONTRACT_LIMITS.RESOURCE_REFS_PER_FINDING_MAX),
+  severity: SeveritySchema,
+  context: FindingContextSchema.optional(),
+  scope: FindingScopeSchema,
+  attribution: FindingAttributionSchema.optional(),
+  policyRuleIds: z.array(PolicyRuleIdSchema).max(CONTRACT_LIMITS.POLICY_RULE_IDS_MAX).optional(),
+});
+export type DecisionFinding = z.infer<typeof DecisionFindingSchema>;
+
+/**
+ * A recommended action bound to what it applies to (Appendix B).
+ *
+ * §10.7's webhook example writes recommended actions as bare strings, the way
+ * §9.3 writes them for a single review. Appendix B — the reference Decision —
+ * writes them as objects. The object form wins for decisions: a decision that
+ * recommends removal without saying what to remove is not actionable, and an
+ * application that acts on it is guessing. The string form survives where the
+ * plan uses it, on a review.
+ *
+ * `targetResourceIds` is optional because some actions have no target —
+ * `escalate`, `no_global_effect` and `no_action` are about the case, not about
+ * a resource.
+ */
+export const DecisionRecommendedActionSchema = z.looseObject({
+  action: RecommendedActionSchema,
+  targetResourceIds: z
+    .array(ResourceIdSchema)
+    .max(CONTRACT_LIMITS.RESOURCE_REFS_PER_FINDING_MAX)
+    .optional(),
+});
+export type DecisionRecommendedAction = z.infer<typeof DecisionRecommendedActionSchema>;
+
+/** Floating point: `winningVotes / decisiveVotes` will not be exact. */
+const AGREEMENT_TOLERANCE = 1e-6;
+
+/**
+ * The panel that produced the decision (Appendix B).
+ *
+ * The arithmetic is checked here because it is the auditable trace of "one
+ * qualified person, one vote": `agreement` must equal
+ * `winningVotes / decisiveVotes` (§9.5), and the counts must nest. If a
+ * weighting ever crept into the engine, `agreement` would stop matching the
+ * count of people, and this is where that shows up.
+ *
+ * `size` is not restricted to {3, 5, 7}. Those are §9.4's community panel
+ * sizes, but §9.4 also routes critical categories to specialist pools that do
+ * not use the standard jury at all, and an appeal panel is only bounded below.
+ */
+export const DecisionJurySchema = z
+  .looseObject({
+    size: z.number().int().positive().max(CONTRACT_LIMITS.JURY_SIZE_MAX),
+    /** Reviews that expressed a decisive opinion — the denominator of §9.5. */
+    decisiveVotes: z.number().int().positive().max(CONTRACT_LIMITS.JURY_SIZE_MAX),
+    winningVotes: z.number().int().nonnegative().max(CONTRACT_LIMITS.JURY_SIZE_MAX),
+    agreement: UnitIntervalSchema,
+    specialistPresent: z.boolean(),
+  })
+  .superRefine((jury, ctx) => {
+    if (jury.decisiveVotes > jury.size) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['decisiveVotes'],
+        message: 'decisiveVotes cannot exceed the panel size',
+      });
+      return;
+    }
+    if (jury.winningVotes > jury.decisiveVotes) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['winningVotes'],
+        message: 'winningVotes cannot exceed decisiveVotes',
+      });
+      return;
+    }
+    const expected = jury.winningVotes / jury.decisiveVotes;
+    if (Math.abs(jury.agreement - expected) > AGREEMENT_TOLERANCE) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['agreement'],
+        message: `agreement must equal winningVotes / decisiveVotes (${expected})`,
+      });
+    }
+  });
+export type DecisionJury = z.infer<typeof DecisionJurySchema>;
+
+/**
+ * One immutable revision of a case's outcome (Appendix B).
+ *
+ * Every field except `supersedesDecisionId` is required, following §12.8, which
+ * marks `supersedes_decision_id` as the only nullable column on the decisions
+ * table. The DTO uses that column's name; §9.9's prose sketch writes the same
+ * link as `supersedes`.
+ */
+export const DecisionSchema = z
+  .looseObject({
+    id: IdentifierSchema,
+    caseId: IdentifierSchema,
+    revision: z.number().int().positive(),
+    status: DecisionStatusSchema,
+    outcome: DecisionOutcomeSchema,
+    contextSufficiency: ContextSufficiencySchema,
+    confidence: UnitIntervalSchema,
+    findings: z.array(DecisionFindingSchema).max(CONTRACT_LIMITS.FINDINGS_MAX),
+    recommendedActions: z
+      .array(DecisionRecommendedActionSchema)
+      .max(CONTRACT_LIMITS.RECOMMENDED_ACTIONS_MAX),
+    jury: DecisionJurySchema,
+    policyVersions: DecisionPolicyVersionsSchema,
+    supersedesDecisionId: IdentifierSchema.optional(),
+    publishedAt: TimestampSchema,
+  })
+  .superRefine((decision, ctx) => {
+    if (decision.revision === 1 && decision.supersedesDecisionId !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['supersedesDecisionId'],
+        message: 'the first revision of a case supersedes nothing',
+      });
+    }
+    if (decision.revision > 1 && decision.supersedesDecisionId === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['supersedesDecisionId'],
+        message: 'a revision after the first must name the decision it supersedes',
+      });
+    }
+    if (decision.outcome === 'violation' && decision.findings.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['findings'],
+        message: 'a violation outcome requires at least one finding',
+      });
+    }
+  });
+export type Decision = z.infer<typeof DecisionSchema>;

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Public entry point for `@oxyhq/crowdsource-contracts`.
+ *
+ * The contracts every CrowdSource surface agrees on: the backend, the reviewer
+ * and console clients, the published SDKs, and third-party integrators. One
+ * entry point because the package publishes one `exports` path — this is the
+ * package boundary, not a convenience barrel over an internal tree.
+ *
+ * Two version numbers live here and mean different things. `/v1` is the route
+ * prefix and is not this package's business. `CASE_ENVELOPE_SCHEMA_VERSION`
+ * travels inside the payload and is validated separately (§10.11). Additive
+ * changes bump neither.
+ *
+ * Where strictness lands, and why, since it is the one thing a reader will want
+ * to look up:
+ *
+ *   * **Inbound from a tenant or a reviewer — strict.** The Case Envelope tree,
+ *     the review submission, the recusal, the policy set, the resource schema
+ *     registration. A dropped field here is context a jury never sees or an
+ *     input nobody reviewed, and §10.11 makes the exception explicitly for
+ *     fields "the schema forbids for safety".
+ *   * **Outbound to a tenant — loose.** Decisions, webhook envelopes and event
+ *     payloads pass unknown fields through, so a newer CrowdSource never breaks
+ *     an older client and a receiver that persists `event.data` keeps all of it.
+ *   * **Internal, to Oxy Trust — strict.** The reputation event carries no
+ *     resource ids and no free text on purpose; an unrecognised field is how
+ *     content reaches a reputation ledger. The `.v1` in the event type is what
+ *     handles evolution there.
+ *
+ * Open bags (`metadata`, custom payloads, registered JSON Schemas) are the
+ * deliberate exception in both directions: open by definition, but flat or
+ * depth-bounded, scalar-typed, key-restricted and free of prototype-bearing
+ * names.
+ */
+
+export * from './primitives';
+export * from './taxonomy';
+export * from './policies';
+export * from './resources';
+export * from './case-envelope';
+export * from './reviews';
+export * from './decisions';
+export * from './webhooks';
+export * from './reputation-events';
+export * from './json-schema';

package/src/json-schema.ts

@@ -0,0 +1,89 @@
+/**
+ * The same contracts as JSON Schema, for integrators who are not on TypeScript.
+ *
+ * §15.2 asks for "Zod and exportable JSON Schema". Conversion is deliberately
+ * lazy — a function, not a frozen constant — so importing the package to
+ * validate one report does not pay for thirteen schema conversions.
+ *
+ * **What JSON Schema does NOT carry.** Zod refinements have no JSON Schema
+ * equivalent and are dropped silently by the conversion. Everything structural
+ * survives — types, enums, patterns, bounds, required keys, `additionalProperties`
+ * — and every cross-field and cross-reference rule does not:
+ *
+ *   * §5.5 reference resolution (relations, `primaryResourceId`, allegation
+ *     resource ids, author and seller refs, conversation members, avatars)
+ *   * the `oxy_user` binding-proof requirement
+ *   * exactly-one-of `uploadId`/`url`, media type agreement, coarse coordinates,
+ *     price-with-currency
+ *   * `agreement = winningVotes / decisiveVotes` and the vote count nesting
+ *   * revision 1 supersedes nothing / later revisions must
+ *   * `externalReportId` matching between request and envelope
+ *
+ * So a payload that passes the JSON Schema is well-FORMED, not accepted. The
+ * server validates with Zod, and that is the authority. This is stated here
+ * because an integrator who assumes otherwise will build against a contract
+ * that is looser than the one they will meet in production, and will discover
+ * the difference as a 422.
+ */
+
+import { z } from 'zod';
+
+import { CaseEnvelopeSchema, CreateReportRequestSchema, CreateReportResponseSchema } from './case-envelope';
+import { DecisionSchema } from './decisions';
+import { PolicySetVersionSchema } from './policies';
+import { ReputationEventSchema } from './reputation-events';
+import { RelationSchema, ResourceSchema, ResourceSchemaRegistrationSchema } from './resources';
+import { RecusalSubmissionSchema, ReviewSubmissionSchema } from './reviews';
+import { KnownWebhookEventSchema, WebhookEventEnvelopeSchema } from './webhooks';
+
+/** A JSON Schema document, as produced by the conversion. */
+export type JsonSchemaDocument = z.core.JSONSchema.BaseSchema;
+
+export const CONTRACT_JSON_SCHEMA_NAMES = [
+  'case-envelope',
+  'create-report-request',
+  'create-report-response',
+  'resource',
+  'relation',
+  'resource-schema-registration',
+  'policy-set-version',
+  'review-submission',
+  'recusal-submission',
+  'decision',
+  'webhook-event-envelope',
+  'known-webhook-event',
+  'reputation-event',
+] as const;
+
+export type ContractJsonSchemaName = (typeof CONTRACT_JSON_SCHEMA_NAMES)[number];
+
+/**
+ * The Zod schema behind each published name.
+ *
+ * Typed as an exhaustive `Record` so adding a name without a schema — or a
+ * schema without a name — is a compile error rather than a runtime hole in the
+ * exported contract set.
+ */
+export const CONTRACT_SCHEMAS: Record<ContractJsonSchemaName, z.ZodType> = {
+  'case-envelope': CaseEnvelopeSchema,
+  'create-report-request': CreateReportRequestSchema,
+  'create-report-response': CreateReportResponseSchema,
+  resource: ResourceSchema,
+  relation: RelationSchema,
+  'resource-schema-registration': ResourceSchemaRegistrationSchema,
+  'policy-set-version': PolicySetVersionSchema,
+  'review-submission': ReviewSubmissionSchema,
+  'recusal-submission': RecusalSubmissionSchema,
+  decision: DecisionSchema,
+  'webhook-event-envelope': WebhookEventEnvelopeSchema,
+  'known-webhook-event': KnownWebhookEventSchema,
+  'reputation-event': ReputationEventSchema,
+};
+
+/** JSON Schema draft 2020-12, so `$defs` and `unevaluatedProperties` mean what integrators expect. */
+const JSON_SCHEMA_TARGET = 'draft-2020-12';
+
+/** The JSON Schema for one published contract. */
+export function crowdSourceJsonSchema(name: ContractJsonSchemaName): JsonSchemaDocument {
+  return z.toJSONSchema(CONTRACT_SCHEMAS[name], { target: JSON_SCHEMA_TARGET });
+}

package/src/policies.ts

@@ -0,0 +1,203 @@
+/**
+ * The application-policy layer (§6.1 layer 2) and policy versioning (§6.4).
+ *
+ * The taxonomy says what the material contains; a policy set says whether that
+ * violates THIS application's rules. The two are versioned independently and
+ * every decision records both (plus the Oxy conduct policy version), because
+ * §6.4 forbids a policy update from silently changing what a past decision
+ * meant.
+ *
+ * The security boundary of this module is §6.4's last line: "rules must be
+ * expressed as data, not as arbitrary code supplied by the tenant". A rule here
+ * therefore has an id, a title, the taxonomy codes it responds to, a default
+ * severity and recommended actions — and no expression, predicate, script,
+ * template or callback field of any kind. That absence is the control. It is
+ * enforced by `.strict()`: a policy set carrying an unrecognised key is
+ * rejected outright rather than accepted with the key quietly dropped, because
+ * "dropped" and "never evaluated" look identical right up until something
+ * decides to evaluate it.
+ */
+
+import { z } from 'zod';
+
+import { CONTRACT_LIMITS, LanguageTagSchema, TimestampSchema } from './primitives';
+import { RecommendedActionSchema, SeveritySchema, TaxonomyCodeSchema } from './taxonomy';
+
+/** A namespaced policy set id, e.g. `mention.community`. */
+export const PolicySetIdSchema = z
+  .string()
+  .min(3)
+  .max(CONTRACT_LIMITS.IDENTIFIER_MAX_LENGTH)
+  .regex(
+    /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/,
+    'must be a dotted lowercase namespace, e.g. "mention.community"',
+  );
+
+/** A rule id within a policy set, e.g. `mention.harassment.2`. */
+export const PolicyRuleIdSchema = z
+  .string()
+  .min(3)
+  .max(CONTRACT_LIMITS.IDENTIFIER_MAX_LENGTH)
+  .regex(
+    /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/,
+    'must be a dotted lowercase namespace, e.g. "mention.harassment.2"',
+  );
+
+/**
+ * An immutable policy version token, e.g. `2026.07`, `mention.2026.07`,
+ * `oxy.2026.1`.
+ *
+ * Deliberately not semver: the plan's own tokens are calendar-shaped and
+ * tenant-prefixed, and a policy version is an opaque label pointing at a frozen
+ * document — nothing compares two of them for ordering.
+ */
+export const PolicyVersionSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+    'must start with a letter or digit and contain only letters, digits, ".", "_" or "-"',
+  );
+
+/**
+ * The version of the Oxy Conduct Policy every decision is stamped with (§6.4).
+ *
+ * §6.1 assigns the third layer — "should this conduct affect global Oxy trust?"
+ * — to the Oxy Conduct Policy, evaluated by the Reputation Bridge. That bridge
+ * does not exist yet, and this constant is deliberately NOT a promise that it
+ * does. What it is: the label a decision published today records, so that when
+ * the bridge arrives it can tell which conduct policy a historical decision was
+ * decided under and refuse to re-interpret it under a newer one. §6.4's "a
+ * policy update never silently rewrites historical decisions" is unenforceable
+ * without a version on every decision from the first one.
+ *
+ * The value is Appendix B's. It is pinned here, in the package both the
+ * decision DTO and the reputation event import, so the two cannot drift into
+ * describing the same decision under two different conduct policies.
+ */
+export const OXY_CONDUCT_POLICY_VERSION = 'oxy.2026.1';
+
+/**
+ * The policy an envelope asks to be evaluated under (§5.1 `policy`).
+ *
+ * `locale` selects the language the policy text is shown to the reviewer in
+ * (Appendix A), and is not the language of the reported material — that is
+ * `resource.language`.
+ */
+export const CasePolicyRefSchema = z.strictObject({
+  policySetId: PolicySetIdSchema,
+  version: PolicyVersionSchema,
+  locale: LanguageTagSchema.optional(),
+});
+export type CasePolicyRef = z.infer<typeof CasePolicyRefSchema>;
+
+/**
+ * The three policy versions a decision is decided under (§6.4).
+ *
+ * Field names follow Appendix B (`taxonomy`), which is the reference Decision.
+ * §6.4's prose calls the same field `universalTaxonomyVersion` and §11.6's
+ * internal event calls it `universal`; see `ReputationPolicyVersionsSchema` for
+ * why both spellings survive.
+ */
+export const DecisionPolicyVersionsSchema = z.looseObject({
+  taxonomy: PolicyVersionSchema,
+  application: PolicyVersionSchema,
+  oxyConduct: PolicyVersionSchema,
+});
+export type DecisionPolicyVersions = z.infer<typeof DecisionPolicyVersionsSchema>;
+
+/**
+ * The same three versions as carried by the internal reputation event (§11.6).
+ *
+ * §11.6 spells the first key `universal` where Appendix B spells it `taxonomy`.
+ * Both are reference payloads in the approved plan and both are load-bearing
+ * for a different consumer, so each surface keeps the spelling its own
+ * reference document uses rather than one of the two documents being quietly
+ * rewritten here. Unifying them is a one-line change and worth doing when the
+ * event contract is agreed with OxyHQServices — it is called out in the package
+ * README as the single naming inconsistency the contract preserves on purpose.
+ */
+export const ReputationPolicyVersionsSchema = z.strictObject({
+  universal: PolicyVersionSchema,
+  application: PolicyVersionSchema,
+  oxyConduct: PolicyVersionSchema,
+});
+export type ReputationPolicyVersions = z.infer<typeof ReputationPolicyVersionsSchema>;
+
+/** §6.4: a draft may be edited, a published version may not. */
+export const POLICY_SET_STATUSES = ['draft', 'published'] as const;
+export const PolicySetStatusSchema = z.enum(POLICY_SET_STATUSES);
+export type PolicySetStatus = z.infer<typeof PolicySetStatusSchema>;
+
+/**
+ * One rule inside a policy version — data, never code.
+ *
+ * `taxonomyCodes` is what binds layer 2 back to layer 1: the rule declares
+ * which universal findings it responds to, so a jury classifies once (§9.2 step
+ * one) and any number of applications evaluate that same classification against
+ * their own rules (§6.2).
+ */
+export const PolicyRuleSchema = z.strictObject({
+  id: PolicyRuleIdSchema,
+  title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+  description: z.string().max(CONTRACT_LIMITS.LONG_TEXT_MAX_LENGTH).optional(),
+  taxonomyCodes: z.array(TaxonomyCodeSchema).min(1).max(CONTRACT_LIMITS.FINDINGS_MAX),
+  defaultSeverity: SeveritySchema.optional(),
+  recommendedActions: z
+    .array(RecommendedActionSchema)
+    .max(CONTRACT_LIMITS.RECOMMENDED_ACTIONS_MAX)
+    .optional(),
+});
+export type PolicyRule = z.infer<typeof PolicyRuleSchema>;
+
+const POLICY_RULES_MAX = 500;
+
+/**
+ * A policy set at one version (§6.4).
+ *
+ * The `status`/`publishedAt` pairing is the immutability rule expressed where a
+ * schema can express it: a published version must record when it was published,
+ * and a draft must not claim to have been. Actual immutability — never
+ * rewriting a published version's rules — is a storage rule the registry
+ * enforces; no parse can see a second write.
+ */
+export const PolicySetVersionSchema = z
+  .strictObject({
+    policySetId: PolicySetIdSchema,
+    version: PolicyVersionSchema,
+    status: PolicySetStatusSchema,
+    title: z.string().min(1).max(CONTRACT_LIMITS.SHORT_TEXT_MAX_LENGTH),
+    locale: LanguageTagSchema.optional(),
+    publishedAt: TimestampSchema.optional(),
+    rules: z.array(PolicyRuleSchema).min(1).max(POLICY_RULES_MAX),
+  })
+  .superRefine((policySet, ctx) => {
+    if (policySet.status === 'published' && policySet.publishedAt === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['publishedAt'],
+        message: 'a published policy version must record publishedAt',
+      });
+    }
+    if (policySet.status === 'draft' && policySet.publishedAt !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['publishedAt'],
+        message: 'a draft policy version must not record publishedAt',
+      });
+    }
+
+    const seen = new Set<string>();
+    policySet.rules.forEach((rule, index) => {
+      if (seen.has(rule.id)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['rules', index, 'id'],
+          message: `duplicate rule id "${rule.id}"`,
+        });
+      }
+      seen.add(rule.id);
+    });
+  });
+export type PolicySetVersion = z.infer<typeof PolicySetVersionSchema>;