@thejob/schema 2.5.0 → 2.7.0

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");