openings 0.1.0

package/src/enrichment-registry.ts

@@ -0,0 +1,137 @@
+import { readFile } from "node:fs/promises";
+import { atomicJson } from "./atomic-file.ts";
+import { withFileLock } from "./file-lock.ts";
+import type { Ats, DiscoveryProvenance, DomainEvidence } from "./types.ts";
+import { resolveSource } from "./source-verification.ts";
+
+export type EnrichmentState = "unresolved" | "matched" | "evidence_ready" | "verified" | "rejected";
+export type MatchMethod = "normalized_token" | "normalized_name" | "normalized_domain" | "search_result";
+
+export interface CompanyMatch { companyName: string; companyDomain: string; method: MatchMethod; reference: string }
+export interface IdentityEvidence { companyName: string; companyDomain: string; kind: DomainEvidence["kind"] | "provider_structured_domain"; reference: string; observedAt: string }
+export interface LeadAttempt { attemptedAt: string; outcome: "success" | "transient_failure" | "permanent_failure"; category?: string; detail?: string; nextEligibleAt?: string; evidenceRank?: number }
+export interface EnrichmentLead {
+  sourceKey: string; sourceUrl: string; ats: Ats; token: string;
+  discoveredFrom: DiscoveryProvenance[];
+  companyMatches: CompanyMatch[];
+  identityEvidence: IdentityEvidence[];
+  attempts: LeadAttempt[];
+  promotedAt?: string;
+}
+export interface EnrichmentRegistry { version: 1; updatedAt: string; leads: EnrichmentLead[] }
+
+const evidenceRank: Record<IdentityEvidence["kind"], number> = {
+  provider_structured_domain: 4,
+  company_redirect: 3,
+  company_registry: 2,
+  authoritative_dataset: 1,
+};
+
+export function deriveLeadState(lead: EnrichmentLead): EnrichmentState {
+  const latestAttempt = lead.attempts.at(-1);
+  if (latestAttempt?.outcome === "permanent_failure" && !supersededFailure(lead, latestAttempt)) return "rejected";
+  if (!lead.companyMatches.length) return lead.promotedAt && latestAttempt?.outcome === "success" ? "verified" : "unresolved";
+  const qualifying = lead.identityEvidence.filter((evidence) => !["lever", "ashby"].includes(lead.ats) || ["provider_structured_domain", "company_redirect"].includes(evidence.kind));
+  if (!qualifying.length) return lead.promotedAt && latestAttempt?.outcome === "success" ? "verified" : "matched";
+  const winningRank = Math.max(...qualifying.map((evidence) => evidenceRank[evidence.kind]));
+  const winningDomains = new Set(qualifying.filter((evidence) => evidenceRank[evidence.kind] === winningRank).map((evidence) => normalizeDomain(evidence.companyDomain)));
+  if (winningDomains.size !== 1) return "rejected";
+  const domain = [...winningDomains][0]!;
+  const state = lead.companyMatches.some((match) => normalizeDomain(match.companyDomain) === domain) ? "evidence_ready" : "rejected";
+  return state === "evidence_ready" && lead.promotedAt && latestAttempt?.outcome === "success" ? "verified" : state;
+}
+
+export function retryDisposition(lead: EnrichmentLead, now = new Date()): "fresh" | "retryable" | "cooling_down" | "repeatedly_failing" {
+  if (!lead.attempts.length) return "fresh";
+  const latest = lead.attempts.at(-1)!;
+  if (latest.outcome !== "transient_failure") return "retryable";
+  if (latest.nextEligibleAt && Date.parse(latest.nextEligibleAt) > now.getTime()) return "cooling_down";
+  const consecutive = consecutiveTransientFailures(lead.attempts);
+  return consecutive >= 3 ? "repeatedly_failing" : "retryable";
+}
+
+export function strongestEvidenceRank(lead: EnrichmentLead): number { return Math.max(0, ...lead.identityEvidence.map((evidence) => evidenceRank[evidence.kind])); }
+
+export async function readEnrichmentRegistry(path: string): Promise<EnrichmentRegistry> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!isRegistry(value)) throw new Error(`Invalid enrichment registry: ${path}`);
+    return value;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return { version: 1, updatedAt: new Date(0).toISOString(), leads: [] };
+    throw error;
+  }
+}
+
+export async function mergeEnrichmentLeads(path: string, additions: EnrichmentLead[], now = new Date()): Promise<{ added: number; updated: number; total: number; bytes: number; lockHeldMs: number; durationMs: number }> {
+  const startedAt = Date.now();
+  const result = await withFileLock(path, async () => {
+    const lockStartedAt = Date.now();
+    const registry = await readEnrichmentRegistry(path);
+    const byKey = new Map(registry.leads.map((lead) => [lead.sourceKey, lead]));
+    let added = 0;
+    let updated = 0;
+    for (const addition of additions) {
+      const current = byKey.get(addition.sourceKey);
+      if (!current) { byKey.set(addition.sourceKey, canonicalLead(addition)); added += 1; continue; }
+      byKey.set(addition.sourceKey, mergeLead(current, addition)); updated += 1;
+    }
+    const leads = [...byKey.values()].sort((left, right) => left.sourceKey.localeCompare(right.sourceKey));
+    const value = { version: 1, updatedAt: now.toISOString(), leads } satisfies EnrichmentRegistry;
+    await atomicJson(path, value);
+    return { added, updated, total: leads.length, bytes: Buffer.byteLength(JSON.stringify(value)), lockHeldMs: Date.now() - lockStartedAt };
+  }, { operation: "merge enrichment leads" });
+  return { ...result, durationMs: Date.now() - startedAt };
+}
+
+export function transientAttempt(attemptedAt: Date, consecutiveFailures: number, category: string, detail: string): LeadAttempt {
+  const delayMs = Math.min(7 * 86_400_000, 60_000 * 2 ** Math.max(0, consecutiveFailures - 1));
+  return { attemptedAt: attemptedAt.toISOString(), outcome: "transient_failure", category, detail, nextEligibleAt: new Date(attemptedAt.getTime() + delayMs).toISOString() };
+}
+
+function mergeLead(left: EnrichmentLead, right: EnrichmentLead): EnrichmentLead {
+  return canonicalLead({
+    ...left,
+    sourceUrl: right.sourceUrl,
+    discoveredFrom: unique([...left.discoveredFrom, ...right.discoveredFrom]),
+    companyMatches: unique([...left.companyMatches, ...right.companyMatches]),
+    identityEvidence: unique([...left.identityEvidence, ...right.identityEvidence]),
+    attempts: unique([...left.attempts, ...right.attempts]).sort((a, b) => a.attemptedAt.localeCompare(b.attemptedAt)),
+    promotedAt: right.promotedAt ?? left.promotedAt,
+  });
+}
+function canonicalLead(lead: EnrichmentLead): EnrichmentLead {
+  const sorted = <T>(values: T[]) => unique(values).sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  return { ...lead, discoveredFrom: sorted(lead.discoveredFrom), companyMatches: sorted(lead.companyMatches), identityEvidence: sorted(lead.identityEvidence), attempts: unique(lead.attempts).sort((a, b) => a.attemptedAt.localeCompare(b.attemptedAt) || JSON.stringify(a).localeCompare(JSON.stringify(b))) };
+}
+function unique<T>(values: T[]): T[] { return [...new Map(values.map((value) => [JSON.stringify(value), value])).values()]; }
+function normalizeDomain(value: string): string { return value.toLowerCase().replace(/^www\./, ""); }
+function consecutiveTransientFailures(attempts: LeadAttempt[]): number { let count = 0; for (const attempt of [...attempts].reverse()) { if (attempt.outcome !== "transient_failure") break; count += 1; } return count; }
+function isRegistry(value: unknown): value is EnrichmentRegistry {
+  if (!isRecord(value) || value.version !== 1 || typeof value.updatedAt !== "string" || !Array.isArray(value.leads)) return false;
+  return value.leads.every((lead) => isRecord(lead)
+    && typeof lead.sourceKey === "string" && /^(greenhouse|lever|ashby|workday|recruitee):.+/.test(lead.sourceKey)
+    && typeof lead.sourceUrl === "string" && typeof lead.token === "string"
+    && ["greenhouse", "lever", "ashby", "workday", "recruitee"].includes(String(lead.ats))
+    && Array.isArray(lead.discoveredFrom) && lead.discoveredFrom.every(validProvenance)
+    && Array.isArray(lead.companyMatches) && lead.companyMatches.every(validMatch)
+    && Array.isArray(lead.identityEvidence) && lead.identityEvidence.every(validEvidence)
+    && Array.isArray(lead.attempts) && lead.attempts.every(validAttempt)
+    && sourceIdentityMatches(lead)
+    && (lead.promotedAt === undefined || typeof lead.promotedAt === "string" && Number.isFinite(Date.parse(lead.promotedAt))));
+}
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function validProvenance(value: unknown): boolean { return isRecord(value) && ["search", "career_page", "provider_directory", "community", "dataset", "legacy"].includes(String(value.channel)) && typeof value.reference === "string"; }
+function validMatch(value: unknown): boolean { return isRecord(value) && typeof value.companyName === "string" && typeof value.companyDomain === "string" && /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(value.companyDomain) && ["normalized_token", "normalized_name", "normalized_domain", "search_result"].includes(String(value.method)) && typeof value.reference === "string"; }
+function validEvidence(value: unknown): boolean { return isRecord(value) && typeof value.companyName === "string" && typeof value.companyDomain === "string" && /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(value.companyDomain) && ["provider_structured_domain", "company_redirect", "company_registry", "authoritative_dataset"].includes(String(value.kind)) && typeof value.reference === "string" && typeof value.observedAt === "string" && Number.isFinite(Date.parse(value.observedAt)); }
+function validAttempt(value: unknown): boolean { return isRecord(value) && typeof value.attemptedAt === "string" && Number.isFinite(Date.parse(value.attemptedAt)) && ["success", "transient_failure", "permanent_failure"].includes(String(value.outcome)) && (value.nextEligibleAt === undefined || typeof value.nextEligibleAt === "string" && Number.isFinite(Date.parse(value.nextEligibleAt))) && (value.category === undefined || typeof value.category === "string") && (value.detail === undefined || typeof value.detail === "string") && (value.evidenceRank === undefined || typeof value.evidenceRank === "number" && Number.isFinite(value.evidenceRank)); }
+function sourceIdentityMatches(value: Record<string, unknown>): boolean {
+  const source = resolveSource(String(value.sourceUrl));
+  if (source) return source.ats === value.ats && source.token === value.token && `${source.ats}:${source.token.toLowerCase()}` === value.sourceKey;
+  if (value.ats !== "workday" || typeof value.token !== "string" || typeof value.sourceKey !== "string") return false;
+  try {
+    const host = new URL(String(value.sourceUrl)).hostname.toLowerCase();
+    return /\.myworkdayjobs\.com$/u.test(host) && value.token.startsWith(`${host}/`) && value.sourceKey === `workday:${value.token.toLowerCase()}`;
+  } catch { return false; }
+}
+function supersededFailure(lead: EnrichmentLead, attempt: LeadAttempt): boolean { return attempt.category === "identity_mismatch" && lead.identityEvidence.some((evidence) => Date.parse(evidence.observedAt) > Date.parse(attempt.attemptedAt) && evidenceRank[evidence.kind] > (attempt.evidenceRank ?? 0)); }

package/src/file-lock.ts

@@ -0,0 +1,85 @@
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+
+interface FileLockOptions { acquireTimeoutMs?: number; operation?: string }
+export interface FileLockStatus { locked: boolean; lockPath: string; pid?: number; operation?: string; createdAt?: string }
+
+export async function withFileLock<T>(path: string, operation: () => Promise<T>, options: FileLockOptions = {}): Promise<T> {
+  await mkdir(dirname(path), { recursive: true });
+  const lockPath = `${path}.lock`;
+  const handle = await acquire(lockPath, Math.max(1, options.acquireTimeoutMs ?? configuredTimeout()));
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), operation: options.operation ?? "file update" }));
+    return await operation();
+  } finally {
+    await handle.close().catch(() => undefined);
+    await unlink(lockPath).catch(() => undefined);
+  }
+}
+
+export async function inspectFileLock(path: string): Promise<FileLockStatus> {
+  const lockPath = `${path}.lock`;
+  try {
+    const value: unknown = JSON.parse(await readFile(lockPath, "utf8"));
+    if (!value || typeof value !== "object") return { locked: true, lockPath };
+    return { locked: true, lockPath,
+      ...( "pid" in value && typeof value.pid === "number" ? { pid: value.pid } : {}),
+      ...( "operation" in value && typeof value.operation === "string" ? { operation: value.operation } : {}),
+      ...( "createdAt" in value && typeof value.createdAt === "string" ? { createdAt: value.createdAt } : {}),
+    };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return { locked: false, lockPath };
+    return { locked: true, lockPath };
+  }
+}
+
+export async function forceReleaseFileLock(path: string): Promise<FileLockStatus> {
+  const status = await inspectFileLock(path);
+  if (status.locked) await unlink(status.lockPath);
+  return status;
+}
+
+function configuredTimeout(): number {
+  const value = Number(process.env.OPENINGS_LOCK_TIMEOUT_MS ?? 60_000);
+  return Number.isFinite(value) && value > 0 ? value : 60_000;
+}
+
+async function acquire(lockPath: string, timeoutMs: number) {
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      return await open(lockPath, "wx");
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+      if (await lockIsStale(lockPath)) { await unlink(lockPath).catch(() => undefined); continue; }
+      if (Date.now() - startedAt >= timeoutMs) throw new Error(`Timed out waiting ${timeoutMs}ms for ${lockPath} (${await describeHolder(lockPath)})`);
+      await new Promise((resolve) => setTimeout(resolve, Math.min(25, timeoutMs)));
+    }
+  }
+}
+
+async function describeHolder(path: string): Promise<string> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (typeof value !== "object" || value === null) return "holder unknown";
+    const pid = "pid" in value && typeof value.pid === "number" ? `pid ${value.pid}` : "pid unknown";
+    const operation = "operation" in value && typeof value.operation === "string" ? value.operation : "operation unknown";
+    const createdAt = "createdAt" in value && typeof value.createdAt === "string" ? value.createdAt : "time unknown";
+    return `${operation}, ${pid}, since ${createdAt}`;
+  } catch { return "holder unknown"; }
+}
+
+async function lockIsStale(path: string): Promise<boolean> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (typeof value === "object" && value !== null && "pid" in value && typeof value.pid === "number") {
+      // PID reuse can defer reclamation; it preserves mutual exclusion and is preferable to reclaiming a live writer.
+      try { process.kill(value.pid, 0); return false; }
+      catch (error) { if (error instanceof Error && "code" in error && error.code === "ESRCH") return true; }
+    }
+    return Date.now() - (await stat(path)).mtimeMs > 60_000;
+  } catch {
+    try { return Date.now() - (await stat(path)).mtimeMs > 60_000; }
+    catch (error) { return error instanceof Error && "code" in error && error.code === "ENOENT"; }
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+import companyData from "../data/companies.json";
+import { createCatalog } from "./catalog.ts";
+import type { Ats, Company } from "./types.ts";
+
+export const companies: Company[] = Object.entries(companyData).map(([slug, value]) => ({
+  slug,
+  name: value.name,
+  ats: value.ats as Ats,
+  token: value.token,
+  cohorts: "cohorts" in value ? value.cohorts as string[] : undefined,
+  companyDomain: "companyDomain" in value ? value.companyDomain as string : undefined,
+  sourceUrl: "sourceUrl" in value ? value.sourceUrl as string : undefined,
+  discoveredFrom: "discoveredFrom" in value ? value.discoveredFrom as Company["discoveredFrom"] : undefined,
+  verification: "verification" in value ? value.verification as Company["verification"] : undefined,
+  domainEvidence: "domainEvidence" in value ? value.domainEvidence as Company["domainEvidence"] : undefined,
+}));
+
+export const catalog = createCatalog({ companies });
+export { createCatalog } from "./catalog.ts";
+export type { Catalog } from "./catalog.ts";
+export type { Ats, Company, CrawlReport, Job, JobPartition, JobSnapshot, JobSummary, SearchQuery } from "./types.ts";
+export { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
+export type { CrawlReportPayload } from "./crawl-reporting.ts";
+export { parseCandidateProfile, ResumeInputError, validateCandidateProfileEvidence } from "./candidate-profile.ts";
+export type { CandidateFact, CandidateFactKind, CandidateInference, CandidateProfile, EvidenceSpan, EvidenceValidationResult, NormalizedResume, ResumeFormat, ResumeInput } from "./candidate-profile.ts";
+export { matchJobs } from "./job-matching.ts";
+export type { CandidateIntent, FilteredJob, JobMatch, JobMatchingResult, RoleFamily, RoleFamilyExpansion, SupportedRequirement, TitleExpansion, TransferableRequirement } from "./job-matching.ts";
+export { createJobRecommender, RecommendationError } from "./job-recommendations.ts";
+export type { JobRecommenderOptions, RecommendJobsInput, RecommendJobsResult, RecommendationRefreshInput, RecommendationRefreshResult, RefreshPolicy } from "./job-recommendations.ts";
+export { createJobFitAnalyzer, JobFitAnalysisError } from "./job-fit-analysis.ts";
+export type { AnalyzeJobFitInput, AnalyzeJobFitResult, JobFitAnalyzerOptions, JobFitAssessment, JobFitReason, PartiallySupportedRequirement } from "./job-fit-analysis.ts";
+export { createResumeOptimizer, ResumeOptimizationError } from "./resume-optimization.ts";
+export type { OptimizeResumeInput, OptimizeResumeResult, ResumeOptimizationOutput, ResumeOptimizerOptions, ResumeSuggestion } from "./resume-optimization.ts";
+export { createSelectedJobLookup } from "./selected-job-lookup.ts";
+export type { SelectedJobLookupOptions } from "./selected-job-lookup.ts";
+export { createJobCoverageReader, projectJobCoverage } from "./job-coverage.ts";
+export type { CountryJobCoverage, JobCoverageSummary } from "./job-coverage.ts";

package/src/intent-validation.ts

@@ -0,0 +1,28 @@
+import type { CandidateIntent } from "./job-matching.ts";
+
+type InvalidInput = (field: string, message: string) => Error;
+const arrayFields = ["roles", "countries", "locations", "seniority", "requiredSkills", "excludedTerms", "excludedCountries", "excludedLocations", "excludedRoles"] as const;
+
+export function validateCandidateIntent(value: unknown, invalid: InvalidInput, options: { optional?: boolean } = {}): CandidateIntent {
+  if (value === undefined && options.optional) return {};
+  if (!isRecord(value)) throw invalid("intent", "Candidate intent must be an object");
+  assertKnownKeys(value, [...arrayFields, "remote"], "intent", invalid);
+  for (const field of arrayFields) {
+    const candidate = value[field];
+    if (candidate !== undefined && (!Array.isArray(candidate) || !candidate.every((item) => typeof item === "string" && item.trim().length > 0))) throw invalid(`intent.${field}`, `${field} must be an array of non-empty strings`);
+    if (Array.isArray(candidate) && new Set(candidate).size !== candidate.length) throw invalid(`intent.${field}`, `${field} must not contain duplicate values`);
+  }
+  for (const field of ["countries", "excludedCountries"] as const) {
+    const countries = value[field];
+    if (Array.isArray(countries) && !countries.every((country) => typeof country === "string" && /^[A-Za-z]{2}$/.test(country))) throw invalid(`intent.${field}`, `${field} must contain two-letter country codes`);
+  }
+  if (value.remote !== undefined && typeof value.remote !== "boolean") throw invalid("intent.remote", "remote must be a boolean");
+  return value as unknown as CandidateIntent;
+}
+
+export function assertKnownKeys(value: Record<string, unknown>, allowed: readonly string[], field: string, invalid: InvalidInput): void {
+  const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unknown) throw invalid(`${field}.${unknown}`, `Unknown field: ${field}.${unknown}`);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/src/job-coverage.ts

@@ -0,0 +1,73 @@
+import { isEligibleForCountry } from "./locations.ts";
+import type { SnapshotStore } from "./crawler.ts";
+import type { Company, JobSnapshot } from "./types.ts";
+
+export interface CountryJobCoverage {
+  country: string;
+  indexedSourcesWithEligibleJobs: number;
+  eligibleJobs: number;
+  distinctEligibleEmployers: number;
+}
+
+export interface JobCoverageSummary {
+  snapshotUpdatedAt: string;
+  countries: CountryJobCoverage[];
+}
+
+export function createJobCoverageReader(options: { sources: Company[]; store: SnapshotStore }) {
+  return {
+    async getCoverage(value: unknown): Promise<JobCoverageSummary> {
+      const countries = validateCoverageInput(value);
+      const snapshot = await options.store.read();
+      if (!snapshot) throw new Error("No local job snapshot is available");
+      return projectJobCoverage(options.sources, snapshot, countries);
+    },
+  };
+}
+
+export function projectJobCoverage(sources: Company[], snapshot: JobSnapshot, countries: string[]): JobCoverageSummary {
+  const normalizedCountries = [...new Set(countries.map(normalizeCountry))];
+  const indexedSources = sources.flatMap((source) => {
+    const partition = snapshot.partitions[source.slug];
+    return partition ? [{ source, jobs: partition.jobs }] : [];
+  });
+
+  return {
+    snapshotUpdatedAt: snapshot.updatedAt,
+    countries: normalizedCountries.map((country) => {
+      const eligibleSources = indexedSources.filter(({ jobs }) => jobs.some((job) => isEligibleForCountry(job, country)));
+      return {
+        country,
+        indexedSourcesWithEligibleJobs: eligibleSources.length,
+        eligibleJobs: eligibleSources.reduce((total, { jobs }) => total + jobs.filter((job) => isEligibleForCountry(job, country)).length, 0),
+        distinctEligibleEmployers: new Set(eligibleSources.flatMap(({ source }) => source.companyDomain ? [normalizeDomain(source.companyDomain)] : [])).size,
+      };
+    }),
+  };
+}
+
+function normalizeCountry(country: string): string {
+  const normalized = country.toUpperCase();
+  if (!/^[A-Z]{2}$/u.test(normalized)) throw new Error("Coverage requires two-letter country codes");
+  return normalized;
+}
+
+function normalizeDomain(domain: string): string {
+  return domain.trim().toLowerCase().replace(/^www\./u, "");
+}
+
+function validateCoverageInput(value: unknown): string[] {
+  if (!isRecord(value)) throw new Error("Coverage input must be an object");
+  const unknown = Object.keys(value).find((key) => key !== "countries");
+  if (unknown) throw new Error(`get_job_coverage does not accept field: ${unknown}`);
+  if (!Array.isArray(value.countries) || value.countries.length === 0) throw new Error("get_job_coverage requires at least one country");
+  if (value.countries.length > 20) throw new Error("get_job_coverage accepts at most 20 countries");
+  if (!value.countries.every((country) => typeof country === "string" && /^[a-z]{2}$/iu.test(country))) {
+    throw new Error("countries must contain only two-letter country codes");
+  }
+  return value.countries;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/job-fit-analysis.ts

@@ -0,0 +1,247 @@
+import { parseCandidateProfile, type CandidateProfile, type ResumeInput } from "./candidate-profile.ts";
+import { matchJobs, type CandidateIntent, type JobMatch, type SupportedRequirement, type TransferableRequirement } from "./job-matching.ts";
+import { assertKnownKeys, isRecord, validateCandidateIntent } from "./intent-validation.ts";
+import type { Job } from "./types.ts";
+import { evaluateScreeningRequirements, type ScreeningRequirement } from "./screening-requirements.ts";
+
+export interface AnalyzeJobFitInput { jobId: string; resume: ResumeInput; intent?: CandidateIntent }
+export interface JobFitReason {
+  claim: string;
+  candidateFactIds?: string[];
+  jobEvidence: { field: "title" | "description" | "eligibility" | "location" | "workMode" | "company"; quote: string; start?: number; end?: number };
+}
+export interface JobFitAssessment { fit: "strong" | "good" | "stretch" | "poor"; reasons: JobFitReason[] }
+export interface PartiallySupportedRequirement extends SupportedRequirement {
+  via: TransferableRequirement["via"] | "experience_below_requirement";
+}
+export interface AnalyzeJobFitResult {
+  job: Job;
+  profile: CandidateProfile;
+  scores: JobMatch["scores"];
+  supported: SupportedRequirement[];
+  partiallySupported: PartiallySupportedRequirement[];
+  unsupported: string[];
+  screeningRisks: string[];
+  interviewPreparationGaps: string[];
+  assessment: JobFitAssessment;
+}
+
+export interface JobFitAnalyzerOptions { getJob(id: string): Promise<Job | null> }
+
+export class JobFitAnalysisError extends Error {
+  constructor(readonly code: "invalid_job_fit_input" | "job_not_found", message: string, readonly field?: string) { super(message); }
+}
+
+export function createJobFitAnalyzer(options: JobFitAnalyzerOptions) {
+  return {
+    async analyze(value: unknown): Promise<AnalyzeJobFitResult> {
+      const input = validateJobFitInput(value);
+      const profile = parseCandidateProfile(input.resume);
+      const job = await options.getJob(input.jobId);
+      if (!job) throw new JobFitAnalysisError("job_not_found", `Unknown job: ${input.jobId}`, "jobId");
+      const intent = input.intent ?? {};
+      const filtered = matchJobs(profile, intent, [job], 1);
+      const relevance = filtered.matches[0] ?? matchJobs(profile, softIntent(intent), [job], 1).matches[0]!;
+      const screening = evaluateScreeningRequirements(profile, job);
+      const structured = structuredRequirements(job, profile, screening);
+      const supported = mergeSupported(relevance.supported, structured.supported);
+      const partiallySupported = mergePartial(relevance.transferable, structured.partial);
+      const resolved = new Set([...supported, ...partiallySupported].map((item) => item.requirement.toLocaleLowerCase()));
+      const certificationRequirements = [...structured.supported.map((item) => item.requirement), ...structured.unsupported]
+        .filter((item) => item.toLocaleLowerCase().endsWith(" certification"));
+      const matchingGaps = relevance.gaps.filter((gap) => !certificationRequirements.some((item) => item.toLocaleLowerCase() === `${gap.toLocaleLowerCase()} certification`));
+      const unsupported = compactRequirements(unique([...matchingGaps, ...structured.unsupported])
+        .filter((requirement) => !resolved.has(requirement.toLocaleLowerCase()))
+        .filter((requirement) => !supported.some((item) => item.requirement.toLocaleLowerCase() === `${requirement.toLocaleLowerCase()} certification`)));
+      const hardRisks = filtered.filteredOut.flatMap((candidate) => candidate.reasons.map(describeFilterRisk));
+      const requirementRisks = unsupported.map((requirement) =>
+        requirement.startsWith("Work authorization in ")
+          ? `Work authorization is required but cannot be inferred from resume silence or geographic intent: ${requirement.slice("Work authorization in ".length)}`
+          : screening.some((item) => item.requirement === requirement)
+            ? `Resume does not provide evidence satisfying mandatory ${screening.find((item) => item.requirement === requirement)!.kind} requirement: ${requirement}`
+          : `No explicit or transferable resume evidence supports required skill: ${requirement}`,
+      );
+      const partialScreeningRisks = screening.filter((item) => item.status === "partial").map((item) => `Resume evidence does not meet minimum requirement: ${item.requirement}`);
+      const seniorityRisks = relevance.reasons.filter((reason) => reason.startsWith("seniority differs"));
+      const screeningRisks = [...hardRisks, ...seniorityRisks, ...partialScreeningRisks, ...requirementRisks];
+      const fit = hardRisks.length || screening.some((item) => item.status !== "supported") || (!supported.length && !partiallySupported.length && unsupported.length)
+        ? "poor"
+        : relevance.fit === "strong" && unsupported.length ? "good" : relevance.fit;
+      return {
+        job,
+        profile,
+        scores: relevance.scores,
+        supported,
+        partiallySupported,
+        unsupported,
+        screeningRisks,
+        interviewPreparationGaps: [
+          ...partiallySupported.map((item) => `Prepare examples connecting ${item.via} evidence to the ${item.requirement} requirement without claiming direct experience`),
+          ...unsupported.map((requirement) => `Prepare a truthful response about the unsupported ${requirement} requirement; do not add it to the resume as experience`),
+        ],
+        assessment: {
+          fit,
+          reasons: assessmentReasons(job, profile, relevance.reasons, screeningRisks, supported, partiallySupported),
+        },
+      };
+    },
+  };
+}
+
+function structuredRequirements(job: Job, profile: CandidateProfile, screening: ScreeningRequirement[]): {
+  supported: SupportedRequirement[];
+  partial: PartiallySupportedRequirement[];
+  unsupported: string[];
+} {
+  const supported: SupportedRequirement[] = [];
+  const partial: PartiallySupportedRequirement[] = [];
+  const unsupported: string[] = [];
+  const text = job.description;
+
+  for (const item of screening) {
+    if (item.status === "supported") supported.push({ requirement: item.requirement, factIds: item.factIds });
+    else if (item.status === "partial") partial.push({ requirement: item.requirement, via: "experience_below_requirement", factIds: item.factIds });
+    else unsupported.push(item.requirement);
+  }
+
+  for (const match of text.matchAll(/\b(?:authorized|authorization)\s+to\s+work\s+in\s+([A-Za-z][A-Za-z ]{1,30}?)(?=[.,;\n]|\s+(?:is|required|must)\b)/gi)) {
+    const country = match[1]!.trim();
+    unsupported.push(`Work authorization in ${country}`);
+  }
+
+  for (const match of text.matchAll(/\b([A-Za-z][A-Za-z0-9+.#-]{1,30})\s+certification\s+(?:is\s+)?(?:required|mandatory|must)\b/gi)) {
+    const name = match[1]!;
+    const label = `${name} certification`;
+    const fact = profile.facts.find((item) => item.kind === "certification" && includesTerm(item.value, name));
+    if (fact) supported.push({ requirement: label, factIds: [fact.id] }); else unsupported.push(label);
+  }
+  unsupported.push(...explicitRequirementLabels(text));
+  return { supported, partial, unsupported };
+}
+
+function explicitRequirementLabels(text: string): string[] {
+  const labels: string[] = [];
+  for (const sentence of text.split(/[.!?\n;]+/).map((value) => value.trim()).filter(Boolean)) {
+    const suffix = /^(.+?)\s+(?:is|are)\s+(?:strictly\s+)?required$/i.exec(sentence)?.[1];
+    const must = /^(?:candidates?\s+)?must\s+(?:have|possess|demonstrate)?\s*(.+)$/i.exec(sentence)?.[1];
+    const value = suffix ?? must;
+    if (!value || /\b(?:authorized|authorization)\s+to\s+work\b/i.test(value)) continue;
+    for (const atom of value.split(/,|\band\b/i)) {
+      const label = atom.trim().replace(/^(?:a|an|the|minimum of)\s+/i, "").replace(/^(?:experience|proficiency)\s+(?:with|in)\s+/i, "").trim();
+      if (label.length >= 2) labels.push(label[0]!.toUpperCase() + label.slice(1));
+    }
+  }
+  return unique(labels);
+}
+
+function assessmentReasons(job: Job, profile: CandidateProfile, matchingReasons: string[], risks: string[], supported: SupportedRequirement[], partial: PartiallySupportedRequirement[]): JobFitReason[] {
+  const result: JobFitReason[] = [];
+  for (const item of [...supported, ...partial]) {
+    result.push({ claim: `${item.requirement} is supported to the stated degree by resume evidence`, candidateFactIds: item.factIds, jobEvidence: jobDescriptionEvidence(job, item.requirement) });
+  }
+  for (const reason of matchingReasons.filter((value) => value.includes("title") || value.startsWith("seniority"))) {
+    const resumeGroundedIds = reason.startsWith("seniority")
+      ? profile.inferences.filter((item) => item.kind === "seniority").flatMap((item) => item.derivedFromFactIds)
+      : reason === "title aligns with resume role evidence"
+        ? [...profile.facts.filter((item) => item.kind === "role").map((item) => item.id), ...profile.inferences.filter((item) => item.kind === "role_family").flatMap((item) => item.derivedFromFactIds)]
+        : [];
+    result.push({ claim: reason, ...(resumeGroundedIds.length ? { candidateFactIds: unique(resumeGroundedIds) } : {}), jobEvidence: { field: "title", quote: job.title, start: 0, end: job.title.length } });
+  }
+  for (const risk of risks) {
+    const riskFactIds = risk.startsWith("seniority differs")
+      ? profile.inferences.filter((item) => item.kind === "seniority").flatMap((item) => item.derivedFromFactIds)
+      : partial.filter((item) => risk.includes(item.requirement)).flatMap((item) => item.factIds);
+    result.push({ claim: risk, ...(riskFactIds.length ? { candidateFactIds: unique(riskFactIds) } : {}), jobEvidence: evidenceForRisk(job, risk) });
+  }
+  const merged = new Map<string, JobFitReason>();
+  for (const reason of result) {
+    const key = JSON.stringify([reason.claim, reason.jobEvidence]);
+    const existing = merged.get(key);
+    if (!existing) merged.set(key, reason);
+    else merged.set(key, { ...existing, candidateFactIds: unique([...(existing.candidateFactIds ?? []), ...(reason.candidateFactIds ?? [])]) });
+  }
+  return [...merged.values()];
+}
+
+function evidenceForRisk(job: Job, risk: string): JobFitReason["jobEvidence"] {
+  if (/country/i.test(risk)) return { field: "eligibility", quote: JSON.stringify({ eligibleCountries: job.eligibleCountries, excludedCountries: job.excludedCountries }) };
+  if (/location/i.test(risk)) return { field: "location", quote: job.location };
+  if (/excluded role/i.test(risk) || risk.startsWith("seniority differs")) return { field: "title", quote: job.title, start: 0, end: job.title.length };
+  if (/remote|work-mode/i.test(risk)) return { field: "workMode", quote: job.workMode };
+  if (/excluded term/i.test(risk)) {
+    const term = risk.split(":", 2)[1]?.trim() ?? "";
+    for (const [field, value] of [["title", job.title], ["company", job.company], ["location", job.location], ["description", job.description]] as const) {
+      const start = value.toLocaleLowerCase().indexOf(term.toLocaleLowerCase());
+      if (start >= 0) return { field, quote: value.slice(start, start + term.length), start, end: start + term.length };
+    }
+  }
+  return jobDescriptionEvidence(job, riskRequirement(risk));
+}
+
+function riskRequirement(risk: string): string {
+  return risk.match(/required skill: (.+)$/)?.[1] ?? risk.match(/intent: (.+)$/)?.[1] ?? "";
+}
+
+function jobDescriptionEvidence(job: Job, requirement: string): JobFitReason["jobEvidence"] {
+  const start = requirement ? job.description.toLocaleLowerCase().indexOf(requirement.toLocaleLowerCase()) : -1;
+  if (start >= 0) return { field: "description", quote: job.description.slice(start, start + requirement.length), start, end: start + requirement.length };
+  return { field: "description", quote: job.description };
+}
+
+function includesTerm(value: string, term: string): boolean {
+  return new RegExp(`(^|[^A-Za-z0-9+.#])${escapeRegex(term)}(?=$|[^A-Za-z0-9+.#])`, "i").test(value);
+}
+
+function escapeRegex(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+function unique(values: string[]): string[] { return [...new Set(values.map((value) => value.trim()).filter(Boolean))]; }
+function compactRequirements(values: string[]): string[] {
+  return values.filter((value, index) => !values.some((other, otherIndex) => otherIndex !== index && other.length < value.length && includesTerm(value, other)));
+}
+function mergeSupported(...groups: SupportedRequirement[][]): SupportedRequirement[] {
+  const merged = new Map<string, SupportedRequirement>();
+  for (const item of groups.flat()) {
+    const key = item.requirement.toLocaleLowerCase();
+    const existing = merged.get(key);
+    if (existing) existing.factIds = unique([...existing.factIds, ...item.factIds]); else merged.set(key, { ...item, factIds: [...item.factIds] });
+  }
+  return [...merged.values()];
+}
+function mergePartial(...groups: PartiallySupportedRequirement[][]): PartiallySupportedRequirement[] {
+  const merged = new Map<string, PartiallySupportedRequirement>();
+  for (const item of groups.flat()) if (!merged.has(item.requirement.toLocaleLowerCase())) merged.set(item.requirement.toLocaleLowerCase(), item);
+  return [...merged.values()];
+}
+
+function validateJobFitInput(value: unknown): AnalyzeJobFitInput {
+  if (!isRecord(value)) throw invalidFitInput("input", "Job fit input must be an object");
+  assertKnownKeys(value, ["jobId", "resume", "intent"], "input", invalidFitInput);
+  if (typeof value.jobId !== "string" || !value.jobId.trim()) throw invalidFitInput("jobId", "jobId must be a non-empty string");
+  if (!isRecord(value.resume)) throw invalidFitInput("resume", "Resume input must be an object");
+  assertKnownKeys(value.resume, ["content", "format"], "resume", invalidFitInput);
+  const intent = validateCandidateIntent(value.intent, invalidFitInput, { optional: true });
+  return { jobId: value.jobId, resume: value.resume as unknown as ResumeInput, ...(value.intent === undefined ? {} : { intent }) };
+}
+
+function invalidFitInput(field: string, message: string): JobFitAnalysisError {
+  return new JobFitAnalysisError("invalid_job_fit_input", message, field);
+}
+
+function softIntent(intent: CandidateIntent): CandidateIntent {
+  const { countries: _countries, locations: _locations, remote: _remote, excludedCountries: _excludedCountries, excludedLocations: _excludedLocations, excludedRoles: _excludedRoles, excludedTerms: _excludedTerms, ...soft } = intent;
+  return soft;
+}
+
+function describeFilterRisk(reason: string): string {
+  const [kind, detail] = reason.split(":", 2);
+  const descriptions: Record<string, string> = {
+    country_not_eligible: `Job is not eligible for requested country: ${detail}`,
+    country_excluded: `Job is eligible in an excluded country: ${detail}`,
+    location_mismatch: "Job location does not match explicit location intent",
+    location_excluded: `Job is in an excluded location: ${detail}`,
+    role_excluded: `Job matches an excluded role: ${detail}`,
+    remote_required: "Job is not explicitly remote",
+    non_remote_required: "Job does not satisfy explicit non-remote intent",
+    excluded_term: `Job contains an excluded term: ${detail}`,
+  };
+  return descriptions[kind ?? ""] ?? reason;
+}