@thejob/schema 2.4.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejob/schema",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/index.ts

@@ -118,6 +118,17 @@ export * from "./skill/skill.schema.js";
 export * from "./billing/billing.schema.js";
 export * from "./billing/billing.constant.js";
 
+/**
+ * Taxonomy schemas and constants (thejob-taxonomy-service: concepts, backbone,
+ * vocabularies, misses, the review queue).
+ *
+ * Constants here are `as const` arrays rather than enums; see the note at the top
+ * of `taxonomy.constant.ts`.
+ */
+export * from "./taxonomy/taxonomy.schema.js";
+export * from "./taxonomy/taxonomy.constant.js";
+export * from "./taxonomy/taxonomy-filter.schema.js";
+
 /**
  * Social account schemas and constants.
  */

package/src/marketing/marketing.schema.ts

@@ -300,6 +300,23 @@ export const CampaignSchema = object({
    * state transition, so it belongs in the state.
    */
   dryRun: boolean().optional().default(true).label("Dry Run"),
+  /**
+   * Re-eligibility: when someone this campaign already mailed may get it again.
+   *
+   * Absent: on every run they match (job alerts, digests). `0`: once per
+   * person. `N`: again only after N days. Opt-in, because most recurring
+   * campaigns exist to mail the same people repeatedly.
+   */
+  resendAfterDays: number()
+    .integer()
+    .min(0)
+    .max(365)
+    // `null` clears it back to "every run": a PATCH can only `$set`, and JSON
+    // has no `undefined` to send.
+    .nullable()
+    .optional()
+    .default(undefined)
+    .label("Resend After (days)"),
   maxRecipients: number()
     .integer()
     .min(1)

package/src/taxonomy/taxonomy-filter.schema.ts

@@ -0,0 +1,84 @@
+/**
+ * The taxonomy filters: the closed vocabulary of facets each thejob-taxonomy-service
+ * list can filter on. The counterparts of `FeedbackFilterSchema` and
+ * `SkillFilterSchema`, read by the service through `parseFilter`.
+ *
+ * Every facet is a field the matching document schema declares, named as it is
+ * there, OR within a facet and AND across facets. Absent means "no constraint".
+ *
+ * Not facets, and absent for that reason: the reserved list params (`search`,
+ * `page`, `limit`, `sortBy`, `sortDirection`, `fields`) and `vocabulary`, which
+ * the service reserves as the SCOPE of a vocabulary's lists (a concept, node,
+ * miss or draft belongs to exactly one vocabulary, and a list never mixes them).
+ */
+import { boolean, object } from "yup";
+import { enumFacet, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+import {
+  SupportedAuditStatuses,
+  SupportedProposalFilters,
+  SupportedProposalStatuses,
+  SupportedReleaseKinds,
+  SupportedReleaseStatuses,
+  SupportedTaxonomyNodeKinds,
+  SupportedUnmatchedReasons,
+  SupportedUnmatchedResolutions,
+} from "./taxonomy.constant.js";
+
+const ConceptFilterShape = object({
+  /** Type ids. Open: which types exist is the vocabulary's data. */
+  type: tokens("Type"),
+  /** Category node ids the concept is placed under (`memberships.categoryId`). */
+  categoryId: tokens("Category"),
+  /** True: only live concepts with no backbone home (the uncategorized backlog). */
+  unplaced: boolean().optional().label("Unplaced"),
+}).label("Concept Filter");
+
+export const ConceptFilterSchema = rejectUnknownKeys(ConceptFilterShape, () =>
+  Object.keys(ConceptFilterShape.fields),
+);
+
+const TaxonomyNodeFilterShape = object({
+  kind: enumFacet(SupportedTaxonomyNodeKinds, "Kind"),
+  /** Parent node ids: a node's children. */
+  parentId: tokens("Parent"),
+}).label("Taxonomy Node Filter");
+
+export const TaxonomyNodeFilterSchema = rejectUnknownKeys(TaxonomyNodeFilterShape, () =>
+  Object.keys(TaxonomyNodeFilterShape.fields),
+);
+
+const UnmatchedFilterShape = object({
+  resolution: enumFacet(SupportedUnmatchedResolutions, "Resolution"),
+  reason: enumFacet(SupportedUnmatchedReasons, "Reason"),
+}).label("Unmatched Filter");
+
+export const UnmatchedFilterSchema = rejectUnknownKeys(UnmatchedFilterShape, () =>
+  Object.keys(UnmatchedFilterShape.fields),
+);
+
+const ConceptProposalFilterShape = object({
+  status: enumFacet(SupportedProposalStatuses, "Status"),
+  /** A kind, or `uncategorized`: concept and placement drafts with no home yet. */
+  kind: enumFacet(SupportedProposalFilters, "Kind"),
+}).label("Concept Proposal Filter");
+
+export const ConceptProposalFilterSchema = rejectUnknownKeys(ConceptProposalFilterShape, () =>
+  Object.keys(ConceptProposalFilterShape.fields),
+);
+
+const ReleaseFilterShape = object({
+  kind: enumFacet(SupportedReleaseKinds, "Kind"),
+  status: enumFacet(SupportedReleaseStatuses, "Status"),
+}).label("Release Filter");
+
+export const ReleaseFilterSchema = rejectUnknownKeys(ReleaseFilterShape, () =>
+  Object.keys(ReleaseFilterShape.fields),
+);
+
+const AuditFilterShape = object({
+  status: enumFacet(SupportedAuditStatuses, "Status"),
+}).label("Audit Filter");
+
+export const AuditFilterSchema = rejectUnknownKeys(AuditFilterShape, () =>
+  Object.keys(AuditFilterShape.fields),
+);

package/src/taxonomy/taxonomy.constant.ts

@@ -0,0 +1,127 @@
+/**
+ * Taxonomy vocabulary (thejob-taxonomy-service).
+ *
+ * Every value here is stored in Mongo and compared as a literal by the service,
+ * so the strings are data, not style. Two conventions differ from the rest of the
+ * package, both deliberate:
+ *
+ * 1. **`as const` arrays, not enums.** The service compares and assigns these as
+ *    string literals (`status: 'draft'`) in hundreds of places; a TS string enum
+ *    would make every one of them a type error. The array is the single list,
+ *    and the type is derived from it, the same way as `SupportedSalaryCurrencies`.
+ * 2. **Some values keep underscores** (`spoken_language`, `new_concept`,
+ *    `rolled_back`). They are stored as written; changing one is a data
+ *    migration, not a rename.
+ */
+
+/** Who owns a concept. Only `seed` may be rewritten by a re-seed. */
+export const SupportedConceptSources = ["seed", "manual", "import"] as const;
+export type ConceptSource = (typeof SupportedConceptSources)[number];
+
+/** Who owns a backbone node or a vocabulary. Only `seed` may be rewritten by a re-seed. */
+export const SupportedTaxonomySources = ["seed", "manual"] as const;
+export type TaxonomySource = (typeof SupportedTaxonomySources)[number];
+
+/** The three levels of a vocabulary's backbone, root first. */
+export const SupportedTaxonomyNodeKinds = ["category", "subcategory", "group"] as const;
+export type TaxonomyNodeKind = (typeof SupportedTaxonomyNodeKinds)[number];
+
+/** Cheap rules that reject a miss before any model sees it, per vocabulary. */
+export const SupportedPrefilterRules = [
+  "spoken_language",
+  "no_letters",
+  "url_or_email",
+  "fragment",
+] as const;
+export type PrefilterRule = (typeof SupportedPrefilterRules)[number];
+
+/** Triage state of a miss. */
+export const SupportedUnmatchedResolutions = ["pending", "added", "rejected"] as const;
+export type UnmatchedResolution = (typeof SupportedUnmatchedResolutions)[number];
+
+/** Why a miss is not a gap: the term names several concepts and no context picked one. */
+export const SupportedUnmatchedReasons = ["ambiguous"] as const;
+export type UnmatchedReason = (typeof SupportedUnmatchedReasons)[number];
+
+/**
+ * What approving a proposal does. `concept`: a new concept. `alias`: another name
+ * for an existing concept. `placement`: a home for a concept that has none.
+ */
+export const SupportedProposalKinds = ["concept", "alias", "placement"] as const;
+export type ProposalKind = (typeof SupportedProposalKinds)[number];
+
+/** The review queue's filter: a kind, or `uncategorized` (drafts with no home yet). */
+export const SupportedProposalFilters = [...SupportedProposalKinds, "uncategorized"] as const;
+export type ProposalFilter = (typeof SupportedProposalFilters)[number];
+
+export const SupportedProposalStatuses = ["draft", "approved", "discarded"] as const;
+export type ProposalStatus = (typeof SupportedProposalStatuses)[number];
+
+export const SupportedProposalMessageRoles = ["operator", "model"] as const;
+export type ProposalMessageRole = (typeof SupportedProposalMessageRoles)[number];
+
+/** The resolver's judgement of a miss against the concepts it was shown. */
+export const SupportedResolverVerdicts = [
+  "same",
+  "narrower",
+  "broader",
+  "related",
+  "new_concept",
+  "out_of_scope",
+] as const;
+export type ResolverVerdict = (typeof SupportedResolverVerdicts)[number];
+
+/** A human's check of one auto-accepted key. */
+export const SupportedAuditStatuses = ["pending", "correct", "wrong"] as const;
+export type AuditStatus = (typeof SupportedAuditStatuses)[number];
+
+/** Where a batch of key writes came from. */
+export const SupportedReleaseKinds = ["seed", "manual", "review", "auto"] as const;
+export type ReleaseKind = (typeof SupportedReleaseKinds)[number];
+
+export const SupportedReleaseStatuses = ["open", "rolled_back"] as const;
+export type ReleaseStatus = (typeof SupportedReleaseStatuses)[number];
+
+/**
+ * How a term resolved. `exact` and `canonical` are deterministic key hits,
+ * `fuzzy` a scored search hit above the threshold, `none` no answer.
+ */
+export const SupportedMatchTypes = ["exact", "canonical", "fuzzy", "none"] as const;
+export type MatchType = (typeof SupportedMatchTypes)[number];
+
+/** The service's maintenance jobs, as started from the API or the schedule. */
+export const SupportedTaxonomyJobKinds = [
+  "describe-concepts",
+  "retype-concepts",
+  "generate-aliases",
+  "alias-backfill",
+  "close-gaps",
+  "propose-placements",
+  "place-unplaced",
+  "calibrate-placement",
+  "reseed",
+  "reindex",
+  "calibrate-resolver",
+  "golden",
+  "resolve-backlog",
+] as const;
+export type TaxonomyJobKind = (typeof SupportedTaxonomyJobKinds)[number];
+
+export const SupportedTaxonomyJobStates = ["running", "succeeded", "failed", "cancelled"] as const;
+export type TaxonomyJobState = (typeof SupportedTaxonomyJobStates)[number];
+
+/** `<vocabulary>_<slug>`, e.g. `skills_power-bi`. The vocabulary is the part before `_`. */
+export const CONCEPT_ID_PATTERN = /^[a-z][a-z0-9-]*_[a-z0-9-]+$/;
+
+/** Never `_`: concept ids use it to separate the vocabulary from the slug. */
+export const VOCABULARY_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Backbone node ids, e.g. `CAT_01_TECH`. Interpolated into search filters, so nothing else is allowed. */
+export const TAXONOMY_NODE_ID_PATTERN = /^[A-Za-z0-9_]{1,64}$/;
+
+/** A concept type id, e.g. `programming_language`. */
+export const CONCEPT_TYPE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** Schedule bounds, in hours: the floor protects the AI budget, the ceiling keeps it a schedule. */
+export const SCHEDULE_MIN_HOURS = 1;
+export const SCHEDULE_MAX_HOURS = 24 * 30;

package/src/taxonomy/taxonomy.schema.ts

@@ -0,0 +1,404 @@
+import { array, boolean, number, object, string } from "yup";
+import {
+  CONCEPT_ID_PATTERN,
+  CONCEPT_TYPE_PATTERN,
+  SCHEDULE_MAX_HOURS,
+  SCHEDULE_MIN_HOURS,
+  SupportedAuditStatuses,
+  SupportedConceptSources,
+  SupportedPrefilterRules,
+  SupportedProposalKinds,
+  SupportedProposalMessageRoles,
+  SupportedProposalStatuses,
+  SupportedReleaseKinds,
+  SupportedReleaseStatuses,
+  SupportedResolverVerdicts,
+  SupportedTaxonomyJobKinds,
+  SupportedTaxonomyNodeKinds,
+  SupportedTaxonomySources,
+  SupportedUnmatchedReasons,
+  SupportedUnmatchedResolutions,
+  TAXONOMY_NODE_ID_PATTERN,
+  VOCABULARY_ID_PATTERN,
+} from "./taxonomy.constant.js";
+
+/**
+ * The documents thejob-taxonomy-service stores and serves.
+ *
+ * Timestamps are epoch milliseconds (numbers), and ids are the service's own
+ * (`conceptId`, `nodeId`, ...), so none of these extend `DbDefaultSchema`.
+ *
+ * Optional fields really are absent on some documents, which is why they are
+ * `.optional()` rather than defaulted: several are resume markers or audit
+ * stamps whose ABSENCE carries meaning ("not looked at yet").
+ */
+
+const conceptId = () => string().matches(CONCEPT_ID_PATTERN, "conceptId must look like <vocabulary>_<slug>");
+const vocabularyId = () => string().matches(VOCABULARY_ID_PATTERN, "vocabulary must match [a-z][a-z0-9-]{0,31}");
+const nodeId = () => string().matches(TAXONOMY_NODE_ID_PATTERN, "node ids look like CAT_01_TECH");
+const strings = () => array(string().trim().min(1).required());
+
+// ─── Vocabularies ────────────────────────────────────────────────────────────
+
+/** One concept type a vocabulary allows, e.g. `programming_language`. */
+export const VocabularyTypeSchema = object({
+  id: string().matches(CONCEPT_TYPE_PATTERN, "type ids match [a-z][a-z0-9_]*").required().label("Type ID"),
+  /** Shown to the model when it classifies a concept; include examples. */
+  description: string().defined().label("Description"),
+}).label("Vocabulary Type");
+
+/**
+ * A kind of concept the service holds (skills, languages, roles). Adding one is
+ * data (an API call), never a code change: every prompt is built from these
+ * fields.
+ */
+export const VocabularySchema = object({
+  vocabularyId: vocabularyId().required().label("Vocabulary ID"),
+  name: string().trim().min(1).required().label("Name"),
+  /** What one concept is called in prompts and messages: "skill", "role". */
+  noun: string().trim().min(1).required().label("Noun"),
+  nounPlural: string().trim().min(1).required().label("Noun (plural)"),
+  /** What belongs in this vocabulary, for prompts. */
+  description: string().trim().min(1).required().label("Description"),
+  /** Where its terms are written, for the "swap it in" test: "a job posting". */
+  appearsIn: string().trim().min(1).required().label("Appears In"),
+  /** Things that are NOT concepts of this vocabulary, for prompts. */
+  outOfScope: string().trim().min(1).required().label("Out of Scope"),
+  types: array(VocabularyTypeSchema.required())
+    .min(1)
+    .required()
+    .test("unique-type-ids", "type ids must be unique", (types) =>
+      !types || new Set(types.map((t) => t.id)).size === types.length,
+    )
+    .label("Types"),
+  /** The type a concept gets when nothing more specific is known. One of `types`. */
+  defaultType: string()
+    .required()
+    .test("default-type-listed", "defaultType must be one of the type ids", function (value) {
+      const types = (this.parent as { types?: { id: string }[] }).types ?? [];
+      return types.some((t) => t.id === value);
+    })
+    .label("Default Type"),
+  prefilter: array(string().oneOf(SupportedPrefilterRules).required()).default([]).label("Prefilter"),
+  /**
+   * Words that qualify a term without changing what it names ("fluent",
+   * "native"), dropped from its canonical lookup form in THIS vocabulary only.
+   */
+  qualifiers: strings().optional().label("Qualifiers"),
+  /** Extra instructions per model task; each is optional. */
+  guidance: object({
+    describe: string().optional(),
+    classify: string().optional(),
+    aliases: string().optional(),
+    verify: string().optional(),
+    place: string().optional(),
+  }).label("Guidance"),
+  source: string().oneOf(SupportedTaxonomySources).required().label("Source"),
+  createdAt: number().required().label("Created At"),
+  updatedAt: number().required().label("Updated At"),
+}).label("Vocabulary");
+
+// ─── Backbone ────────────────────────────────────────────────────────────────
+
+/**
+ * One node of a vocabulary's 3-level backbone (category > subcategory > group),
+ * stored flat with `parentId` and `path` so any level can be read directly.
+ */
+export const TaxonomyNodeSchema = object({
+  nodeId: nodeId().required().label("Node ID"),
+  vocabulary: vocabularyId().required().label("Vocabulary"),
+  kind: string().oneOf(SupportedTaxonomyNodeKinds).required().label("Kind"),
+  name: string().trim().min(1).required().label("Name"),
+  /** Groups carry a description; categories and subcategories usually do not. */
+  description: string().optional().label("Description"),
+  aliases: strings().default([]).label("Aliases"),
+  /** null for categories (the roots). */
+  parentId: string().nullable().defined().label("Parent ID"),
+  /** Ancestor ids from the root down to and including this node. */
+  path: array(string().required()).default([]).label("Path"),
+  source: string().oneOf(SupportedTaxonomySources).optional().label("Source"),
+  createdAt: number().required().label("Created At"),
+  updatedAt: number().required().label("Updated At"),
+}).label("Taxonomy Node");
+
+// ─── Concepts ────────────────────────────────────────────────────────────────
+
+/**
+ * Where a concept sits in its vocabulary's backbone. A concept may have several
+ * (the same name filed under several categories merges into one concept) or none
+ * (live but uncategorized, waiting for a placement).
+ */
+export const ConceptMembershipSchema = object({
+  categoryId: string().required().label("Category ID"),
+  categoryName: string().required().label("Category Name"),
+  subcategoryId: string().required().label("Subcategory ID"),
+  subcategoryName: string().required().label("Subcategory Name"),
+  groupId: string().required().label("Group ID"),
+  groupName: string().required().label("Group Name"),
+  /** The source record this membership came from; '' when written by hand. */
+  sourceId: string().default("").label("Source ID"),
+}).label("Concept Membership");
+
+/**
+ * A canonical concept: what `/normalize` resolves free text onto.
+ *
+ * Which keys a concept answers to is NOT here: the service keeps them in its
+ * own `matchKeys` store. `aliases` is alias TEXT for people to read.
+ */
+export const ConceptSchema = object({
+  /** `<vocabulary>_<slug>`, e.g. `skills_power-bi`. Primary key. */
+  conceptId: conceptId().required().label("Concept ID"),
+  vocabulary: vocabularyId().required().label("Vocabulary"),
+  name: string().trim().min(1).max(200).required().label("Name"),
+  /** One of the vocabulary's type ids; checked against the vocabulary by the service. */
+  type: string().trim().matches(CONCEPT_TYPE_PATTERN, "type must be a type id").required().label("Type"),
+  description: string().trim().max(2000).default("").label("Description"),
+  aliases: strings().default([]).label("Aliases"),
+  memberships: array(ConceptMembershipSchema.required()).default([]).label("Memberships"),
+  /** Always concepts of the same vocabulary. */
+  relatedConceptIds: strings().default([]).label("Related Concepts"),
+  source: string().oneOf(SupportedConceptSources).required().label("Source"),
+  createdAt: number().required().label("Created At"),
+  updatedAt: number().required().label("Updated At"),
+  /** Resume marker of `retype-concepts`: set once the type was examined. */
+  retypedAt: number().optional().label("Retyped At"),
+  /** Resume marker of `generate-aliases`: set even when no alias was added. */
+  aliasedAt: number().optional().label("Aliased At"),
+  /** Set while `description` is a stand-in; removed once a real one is written. */
+  descriptionPending: boolean().isTrue().optional().label("Description Pending"),
+}).label("Concept");
+
+// ─── Misses ──────────────────────────────────────────────────────────────────
+
+/**
+ * A term callers sent that the taxonomy could not resolve: the ranked work list
+ * for growing it. Never expired; `resolution` closes the loop.
+ */
+export const UnmatchedTermSchema = object({
+  vocabulary: vocabularyId().required().label("Vocabulary"),
+  /** The raw input as first received. */
+  term: string().required().label("Term"),
+  /** The dedupe key, so "React JS" and "react.js" share a row. */
+  normalizedTerm: string().required().label("Normalized Term"),
+  count: number().integer().min(0).required().label("Count"),
+  firstSeenAt: number().required().label("First Seen At"),
+  lastSeenAt: number().required().label("Last Seen At"),
+  /** Which callers sent it, capped. */
+  sources: array(
+    object({
+      service: string().required(),
+      context: string().optional(),
+    }).required(),
+  )
+    .default([])
+    .label("Sources"),
+  resolution: string().oneOf(SupportedUnmatchedResolutions).required().label("Resolution"),
+  resolvedConceptId: string().optional().label("Resolved Concept"),
+  /** `ambiguous`: the concept exists; the caller gave no context that picked one. */
+  reason: string().oneOf(SupportedUnmatchedReasons).optional().label("Reason"),
+  /** The concepts an ambiguous term could mean. */
+  candidates: array(string().required()).optional().label("Candidates"),
+  /** Who rejected it when it was not a human: `prefilter:<rule>` or `model`. */
+  rejectedBy: string().optional().label("Rejected By"),
+}).label("Unmatched Term");
+
+// ─── Proposals (the review queue) ────────────────────────────────────────────
+
+/** A scored backbone group a draft could be placed in. */
+export const ProposalCandidateSchema = object({
+  groupId: string().required(),
+  groupName: string().required(),
+  subcategoryId: string().required(),
+  subcategoryName: string().required(),
+  categoryId: string().required(),
+  categoryName: string().required(),
+  score: number().required(),
+  nearestMembers: array(string().required()).default([]),
+}).label("Proposal Candidate");
+
+/** One turn of a draft's refinement chat. */
+export const ProposalMessageSchema = object({
+  role: string().oneOf(SupportedProposalMessageRoles).required(),
+  /** The operator's instruction, or the model's note on what it changed and why. */
+  content: string().defined(),
+  /** Which model answered. Absent on operator turns. */
+  model: string().optional(),
+  at: number().required(),
+}).label("Proposal Message");
+
+/** A home that does not exist yet, named level by level. "" means no opinion on that level. */
+export const SuggestedHomeSchema = object({
+  categoryName: string().defined(),
+  subcategoryName: string().defined(),
+  groupName: string().defined(),
+}).label("Suggested Home");
+
+/** The resolver's verdict on the existing concepts it was shown for a miss. */
+export const ResolverVerificationSchema = object({
+  verdict: string().oneOf(SupportedResolverVerdicts).required(),
+  /** The shown concept the verdict is about; null for `new_concept` / `out_of_scope`. */
+  conceptId: string().nullable().defined(),
+  evidence: string().defined(),
+  /** What the judge took the term to mean, abbreviations expanded. */
+  means: string().optional(),
+  /** For `same`: did the independent confirm step agree? */
+  consistent: boolean().optional(),
+  confirm: object({
+    answer: string().oneOf(["yes", "no"] as const).required(),
+    evidence: string().defined(),
+  })
+    .optional()
+    .default(undefined),
+}).label("Resolver Verification");
+
+/**
+ * A draft between a miss and the taxonomy. Nothing in a draft is matchable;
+ * approving it is the only way it reaches the concepts.
+ */
+export const ConceptProposalSchema = object({
+  proposalId: string().required().label("Proposal ID"),
+  vocabulary: vocabularyId().required().label("Vocabulary"),
+  /** The miss this closes; `normalizedTerm` links back to its unmatched row. */
+  term: string().required().label("Term"),
+  normalizedTerm: string().required().label("Normalized Term"),
+  /** Demand at proposal time, so the queue ranks without a join. */
+  count: number().integer().min(0).required().label("Count"),
+  /** Other misses folded into this draft because they name the same new concept. */
+  mergedTerms: array(
+    object({
+      term: string().required(),
+      normalizedTerm: string().required(),
+      count: number().integer().min(0).required(),
+    }).required(),
+  )
+    .optional()
+    .label("Merged Terms"),
+  /** Absent on drafts that predate the field: read as `concept`. */
+  kind: string().oneOf(SupportedProposalKinds).optional().label("Kind"),
+  /** For `alias`: the concept the term names. For `placement`: the concept to place. */
+  targetConceptId: string().optional().label("Target Concept"),
+  targetName: string().optional().label("Target Name"),
+
+  // The draft concept, editable until approved. Empty strings are valid here:
+  // an alias draft carries no draft concept of its own.
+  name: string().defined().label("Name"),
+  type: string().defined().label("Type"),
+  description: string().defined().label("Description"),
+  aliases: array(string().required()).default([]).label("Aliases"),
+  /** Empty when no group fits: approved that way, the concept goes live uncategorized. */
+  memberships: array(ConceptMembershipSchema.required()).default([]).label("Memberships"),
+  suggestedHome: SuggestedHomeSchema.nullable().optional().default(undefined).label("Suggested Home"),
+  /** Resolved to concepts that exist; names that matched nothing are dropped. */
+  relatedConceptIds: array(string().required()).default([]).label("Related Concepts"),
+
+  /** Every placement candidate considered, best first. */
+  candidates: array(ProposalCandidateSchema.required()).default([]).label("Candidates"),
+  needsReview: boolean().required().label("Needs Review"),
+  reason: string().optional().label("Reason"),
+  verification: ResolverVerificationSchema.optional().default(undefined).label("Verification"),
+  /** What the auto-accept gate decided for an alias verdict. */
+  autoAccept: object({
+    accepted: boolean().required(),
+    reason: string().optional(),
+    tier: string().optional(),
+    calibrationId: string().optional(),
+    releaseId: string().optional(),
+  })
+    .optional()
+    .default(undefined)
+    .label("Auto Accept"),
+
+  /** Which model drafted it. */
+  model: string().defined().label("Model"),
+  /** The refinement conversation, oldest first. */
+  messages: array(ProposalMessageSchema.required()).default([]).label("Messages"),
+  status: string().oneOf(SupportedProposalStatuses).required().label("Status"),
+  /** Set when approved: the concept this became. */
+  resolvedConceptId: string().optional().label("Resolved Concept"),
+  createdAt: number().required().label("Created At"),
+  updatedAt: number().required().label("Updated At"),
+}).label("Concept Proposal");
+
+// ─── Releases and audits ─────────────────────────────────────────────────────
+
+/** A group of key writes that is undone together. Every key write belongs to one. */
+export const ReleaseSchema = object({
+  releaseId: string().required().label("Release ID"),
+  kind: string().oneOf(SupportedReleaseKinds).required().label("Kind"),
+  status: string().oneOf(SupportedReleaseStatuses).required().label("Status"),
+  createdBy: string().required().label("Created By"),
+  createdAt: number().required().label("Created At"),
+  note: string().optional().label("Note"),
+  rolledBackAt: number().optional().label("Rolled Back At"),
+  rolledBackBy: string().optional().label("Rolled Back By"),
+}).label("Release");
+
+/** A sampled auto-accepted key, waiting for (or carrying) a human's verdict. */
+export const AuditSchema = object({
+  auditId: string().required().label("Audit ID"),
+  releaseId: string().required().label("Release ID"),
+  key: string().required().label("Key"),
+  term: string().required().label("Term"),
+  conceptId: string().required().label("Concept ID"),
+  tier: string().optional().label("Tier"),
+  status: string().oneOf(SupportedAuditStatuses).required().label("Status"),
+  createdAt: number().required().label("Created At"),
+  resolvedAt: number().optional().label("Resolved At"),
+  resolvedBy: string().optional().label("Resolved By"),
+}).label("Audit");
+
+// ─── Operations ──────────────────────────────────────────────────────────────
+
+/**
+ * Operator-editable runtime settings and kill switches. One document; every
+ * replica obeys it within seconds.
+ */
+export const ResolverSettingsSchema = object({
+  autoAccept: object({
+    /** Stop switch for WRITING auto keys. Off until a calibration passes. */
+    enabled: boolean().required(),
+    /** Minimum calibrated precision (Wilson 95% lower bound) for a tier to auto-accept. */
+    target: number().min(0.5).lessThan(1).required(),
+    maxPerRun: number().integer().min(0).required(),
+    maxPerDay: number().integer().min(0).required(),
+    /** Share of each auto release sampled into the audit queue (0..1). */
+    auditRate: number().min(0).max(1).required(),
+  }).label("Auto Accept"),
+  /** Stop switch for SERVING auto keys: false hides them from lookups at once. */
+  serveAutoKeys: boolean().required().label("Serve Auto Keys"),
+  /** Minimum Meilisearch ranking score (0..1) for a fuzzy hit to be considered. */
+  fuzzyMinScore: number().min(0).max(1).required().label("Fuzzy Min Score"),
+  /** Per-client limit on public search, per minute per replica. 0 disables it. */
+  searchRateLimitPerMin: number().integer().min(0).required().label("Search Rate Limit"),
+  /** Master switch for scheduled maintenance jobs. */
+  scheduledJobs: boolean().required().label("Scheduled Jobs"),
+  updatedAt: number().optional().label("Updated At"),
+  updatedBy: string().optional().label("Updated By"),
+  /** Why auto-accept was last switched off automatically. */
+  trippedReason: string().optional().label("Tripped Reason"),
+}).label("Resolver Settings");
+
+/** How often one maintenance job runs on the schedule. */
+export const TaxonomyScheduleSchema = object({
+  kind: string().oneOf(SupportedTaxonomyJobKinds).required().label("Job"),
+  enabled: boolean().required().label("Enabled"),
+  everyHours: number().min(SCHEDULE_MIN_HOURS).max(SCHEDULE_MAX_HOURS).required().label("Every (hours)"),
+  /** Last time the scheduler fired this job. */
+  lastRunAt: number().optional().label("Last Run At"),
+  updatedAt: number().required().label("Updated At"),
+}).label("Taxonomy Schedule");
+
+// ─── Normalize ───────────────────────────────────────────────────────────────
+
+/**
+ * Optional caller context for `/normalize`, used ONLY to choose between the
+ * meanings of an ambiguous term. It never changes an unambiguous answer.
+ */
+export const NormalizeContextSchema = object({
+  /** The title of the record the terms come from. */
+  title: string().max(200).optional(),
+  /** Backbone node ids (category, subcategory or group). */
+  categoryIds: array(nodeId().required()).max(10).optional(),
+  /** Other terms from the same record, in the same vocabulary. */
+  siblings: array(string().max(200).required()).max(50).optional(),
+}).label("Normalize Context");