openings 0.1.0

package/src/mcp.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env bun
+import { createRuntime } from "./runtime.ts";
+import { createToolHandler } from "./tools.ts";
+
+interface RpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+interface ToolHandler {
+  list(): Array<{ name: string; description: string; inputSchema: Record<string, unknown> }>;
+  call(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createMcpHandler(tools: ToolHandler) {
+  return async (value: unknown) => {
+    if (!isRpcRequest(value)) return { jsonrpc: "2.0" as const, id: invalidRequestId(value), error: { code: -32600, message: "Invalid Request" } };
+    const request = value;
+    if (!("id" in request)) return null;
+    const base = { jsonrpc: "2.0" as const, id: request.id ?? null };
+    try {
+      if (request.method === "initialize") {
+        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: "0.1.0" } } };
+      }
+      if (request.method === "ping") return { ...base, result: {} };
+      if (request.method === "tools/list") return { ...base, result: { tools: tools.list() } };
+      if (request.method === "tools/call") {
+        if (!isRecord(request.params)) throw new Error("tools/call params must be an object");
+        const name = request.params.name;
+        const args = request.params.arguments;
+        if (typeof name !== "string") throw new Error("tools/call requires a tool name");
+        if (args !== undefined && !isRecord(args)) throw new Error("tools/call arguments must be an object");
+        try {
+          const result = await tools.call(name, args ?? {});
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], isError: false } };
+        } catch (error) {
+          const details = errorDetails(error);
+          const payload = { error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } };
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError: true } };
+        }
+      }
+      if (request.method.startsWith("notifications/")) return null;
+      return { ...base, error: { code: -32601, message: `Method not found: ${request.method}` } };
+    } catch (error) {
+      return { ...base, error: { code: -32602, message: error instanceof Error ? error.message : String(error) } };
+    }
+  };
+}
+
+function isRpcRequest(value: unknown): value is RpcRequest {
+  if (!isRecord(value) || value.jsonrpc !== "2.0" || typeof value.method !== "string") return false;
+  return !("id" in value) || value.id === null || typeof value.id === "string" || typeof value.id === "number";
+}
+
+function invalidRequestId(value: unknown): string | number | null {
+  if (!isRecord(value)) return null;
+  return typeof value.id === "string" || typeof value.id === "number" || value.id === null ? value.id : null;
+}
+
+function errorDetails(error: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(error)) return undefined;
+  const allowed = new Set(["code", "field", "format", "supportedFormats"]);
+  const entries = Object.entries(error).filter(([key, value]) => allowed.has(key) && value !== undefined);
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export async function serve() {
+  const runtime = createRuntime();
+  const catalog = {
+    search: async (query: import("./types.ts").SearchQuery) => (await runtime.search(query, { offline: false, staleDays: 14 })).jobs,
+    get: async (id: string) => (await runtime.get(id, { offline: false, staleDays: 14 })).job,
+  };
+  const handle = createMcpHandler(createToolHandler(catalog, runtime));
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const response = await handle(JSON.parse(line));
+        if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+      } catch {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } })}\n`);
+      }
+    }
+  }
+}
+
+if (import.meta.main) await serve();

package/src/package-mcp.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+process.env.OPENINGS_DATA_DIR ??= join(homedir(), ".openings");
+
+const { serve } = await import("./mcp.ts");
+await serve();

package/src/recruitee-round.ts

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { atomicJson } from "./atomic-file.ts";
+import { assertArtifactFile, openingsRootFor } from "./artifact-path.ts";
+import { deriveLeadState, mergeEnrichmentLeads, readEnrichmentRegistry, type EnrichmentLead } from "./enrichment-registry.ts";
+import { withFileLock } from "./file-lock.ts";
+import { stampReport } from "./report-meta.ts";
+import type { SourceCandidate } from "./types.ts";
+
+export interface JoinedRecruiteeIdentity {
+  token: string;
+  companyName: string;
+  companyDomain: string;
+  reference: string;
+  method: "normalized_token" | "normalized_domain";
+  provenanceKind: "authoritative_dataset" | "company_owned_page" | "business_registry";
+}
+
+interface ArtifactOptions { artifactRoot: string; existingCompanyDomains?: string[]; now?: Date }
+interface GenerationManifest { version: 1; generation: string; registryPath: string; candidatesPath: string; reportPath: string; identitiesPath: string }
+
+const approvedDatasetReferences = new Set([".openings/company-domains.json", ".openings/lever-ashby-seeds.json", "data/companies-career-page.md"]);
+const approvedBusinessRegistryDomains = ["mca.gov.in", "data.gov.in"];
+
+export async function buildRecruiteeRoundArtifacts(identities: JoinedRecruiteeIdentity[], options: ArtifactOptions) {
+  const root = resolve(options.artifactRoot);
+  if (!root.split(sep).includes(".openings")) throw new Error("Round 5 artifact root must be under .openings");
+  const securityRoot = openingsRootFor(root);
+  const manifestPath = join(root, "current.json");
+  await assertArtifactFile(manifestPath, securityRoot);
+  const now = options.now ?? new Date();
+  return withFileLock(manifestPath, async () => {
+    const priorManifest = await readManifest(manifestPath, root);
+    if (priorManifest) await assertArtifactFile(priorManifest.identitiesPath, securityRoot);
+    const priorIdentities = priorManifest ? await readIdentities(priorManifest.identitiesPath) : [];
+    const allIdentities = uniqueIdentities([...priorIdentities, ...identities].map(validateIdentity));
+    const existing = new Set((options.existingCompanyDomains ?? []).map(normalizeDomain));
+    const grouped = new Map<string, JoinedRecruiteeIdentity[]>();
+    for (const identity of allIdentities) { const values = grouped.get(identity.token) ?? []; values.push(identity); grouped.set(identity.token, values); }
+
+    const leads: EnrichmentLead[] = [];
+    const candidates: SourceCandidate[] = [];
+    const quarantines: Array<{ token: string; domains: string[] }> = [];
+    const excluded: Array<{ token: string; companyDomain: string }> = [];
+    for (const [token, values] of [...grouped].sort(([left], [right]) => left.localeCompare(right))) {
+      const domains = [...new Set(values.map((value) => value.companyDomain))].sort();
+      if (domains.length !== 1) { quarantines.push({ token, domains }); continue; }
+      const companyDomain = domains[0]!;
+      if (existing.has(companyDomain)) { excluded.push({ token, companyDomain }); continue; }
+      const primary = [...values].sort((left, right) => left.reference.localeCompare(right.reference) || left.companyName.localeCompare(right.companyName))[0]!;
+      const sourceUrl = `https://${token}.recruitee.com`;
+      const discoveredFrom = { channel: "dataset" as const, reference: primary.reference };
+      const lead: EnrichmentLead = { sourceKey: `recruitee:${token}`, sourceUrl, ats: "recruitee", token, discoveredFrom: [discoveredFrom], companyMatches: values.map((value) => ({ companyName: value.companyName, companyDomain, method: value.method, reference: value.reference })), identityEvidence: [], attempts: [] };
+      if (deriveLeadState(lead) !== "matched") throw new Error(`Round 5 lead ${token} did not derive matched state`);
+      leads.push(lead);
+      candidates.push({ companyName: primary.companyName, companyDomain, sourceUrl, discoveredFrom });
+    }
+
+    const generation = createHash("sha256").update(JSON.stringify({ now: now.toISOString(), identities: allIdentities, existing: [...existing].sort() })).digest("hex").slice(0, 20);
+    const generationRoot = join(root, "generations", generation);
+    const registryPath = join(generationRoot, "registry.json");
+    const candidatesPath = join(generationRoot, "candidates.json");
+    const reportPath = join(generationRoot, "join-report.json");
+    const identitiesPath = join(generationRoot, "identities.json");
+    for (const path of [registryPath, candidatesPath, reportPath, identitiesPath]) await assertArtifactFile(path, securityRoot);
+    const report = stampReport("round5-recruitee-join:1", 1, { identities: allIdentities.length, matched: leads.length, quarantined: quarantines.length, excludedExisting: excluded.length, registryPath, candidatesPath, quarantines, excluded }, now);
+    await atomicJson(registryPath, { version: 1, updatedAt: now.toISOString(), leads });
+    await atomicJson(candidatesPath, candidates);
+    await atomicJson(reportPath, report);
+    await atomicJson(identitiesPath, allIdentities);
+    const manifest: GenerationManifest = { version: 1, generation, registryPath, candidatesPath, reportPath, identitiesPath };
+    await atomicJson(manifestPath, manifest);
+    return { ...report, manifestPath, generation };
+  }, { operation: "publish paired Round 5 Recruitee artifacts" });
+}
+
+export async function prepareRecruiteeRoundArtifacts(identityPath: string, catalogPath: string, options: ArtifactOptions) {
+  const identities = await readIdentities(identityPath);
+  const catalog: unknown = JSON.parse(await readFile(catalogPath, "utf8"));
+  if (!record(catalog)) throw new Error("Round 5 catalog must be a JSON object");
+  const existingCompanyDomains = Object.values(catalog).flatMap((value) => record(value) && typeof value.companyDomain === "string" ? [value.companyDomain] : []);
+  return buildRecruiteeRoundArtifacts(identities, { ...options, existingCompanyDomains });
+}
+
+export async function mergeAttemptedRoundLeads(isolatedRegistryPath: string, sharedRegistryPath: string, now = new Date()) {
+  if (resolve(isolatedRegistryPath) === resolve(sharedRegistryPath)) throw new Error("Isolated and shared enrichment registries must be different files");
+  const root = roundRootFromRegistry(isolatedRegistryPath);
+  await assertArtifactFile(isolatedRegistryPath, openingsRootFor(root));
+  const manifestPath = join(root, "current.json");
+  await assertArtifactFile(manifestPath, openingsRootFor(root));
+  // Publication and merging share this outer lock; the registry lock is always acquired second.
+  return withFileLock(manifestPath, async () => {
+    const manifest = await readManifest(manifestPath, root);
+    if (!manifest || resolve(manifest.registryPath) !== resolve(isolatedRegistryPath)) throw new Error("Isolated registry must be the current Round 5 generation registry");
+    return withFileLock(isolatedRegistryPath, async () => {
+      const isolated = await readEnrichmentRegistry(isolatedRegistryPath);
+      const attempted = isolated.leads.filter((lead) => lead.attempts.length > 0);
+      const merge = await mergeEnrichmentLeads(sharedRegistryPath, attempted, now);
+      return { selected: attempted.length, ...merge };
+    }, { operation: "merge attempted Round 5 Recruitee leads" });
+  }, { operation: "select current Round 5 Recruitee generation" });
+}
+
+async function readManifest(path: string, root: string): Promise<GenerationManifest | undefined> { try { const value: unknown = JSON.parse(await readFile(path, "utf8")); if (!record(value) || value.version !== 1 || typeof value.generation !== "string" || !/^[a-f0-9]{20}$/.test(value.generation) || typeof value.registryPath !== "string" || typeof value.candidatesPath !== "string" || typeof value.reportPath !== "string" || typeof value.identitiesPath !== "string") throw new Error("Invalid Round 5 artifact manifest"); const generationRoot = join(root, "generations", value.generation); const expected: GenerationManifest = { version: 1, generation: value.generation, registryPath: join(generationRoot, "registry.json"), candidatesPath: join(generationRoot, "candidates.json"), reportPath: join(generationRoot, "join-report.json"), identitiesPath: join(generationRoot, "identities.json") }; const supplied = value as unknown as GenerationManifest; for (const key of ["registryPath", "candidatesPath", "reportPath", "identitiesPath"] as const) if (resolve(supplied[key]) !== resolve(expected[key])) throw new Error("Round 5 manifest contains an unexpected artifact path"); return expected; } catch (error) { if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined; throw error; } }
+async function readIdentities(path: string): Promise<JoinedRecruiteeIdentity[]> { const value: unknown = JSON.parse(await readFile(path, "utf8")); if (!Array.isArray(value)) throw new Error("Round 5 joined identities must be a JSON array"); return value.map(parseIdentity); }
+function uniqueIdentities(values: JoinedRecruiteeIdentity[]) { return [...new Map(values.map((value) => [JSON.stringify(value), value])).values()].sort((a, b) => a.token.localeCompare(b.token) || a.companyDomain.localeCompare(b.companyDomain) || a.reference.localeCompare(b.reference)); }
+function validateIdentity(value: JoinedRecruiteeIdentity): JoinedRecruiteeIdentity { const token = value.token.trim().toLowerCase(); const companyName = value.companyName.trim(); const companyDomain = normalizeDomain(value.companyDomain); const reference = value.reference.trim(); if (!/^[a-z0-9-]+$/.test(token)) throw new Error(`Invalid Recruitee token: ${value.token}`); if (!companyName) throw new Error("Joined companyName must be non-empty"); if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(companyDomain)) throw new Error(`Invalid joined company domain: ${value.companyDomain}`); if (!["normalized_token", "normalized_domain"].includes(value.method)) throw new Error("Round 5 identity method must be an explicit exact non-search match"); const normalizedToken = normalizeMatchValue(token); const observedMatch = value.method === "normalized_token" ? normalizeMatchValue(companyName) : normalizeMatchValue(companyDomain.split(".")[0]!); if (observedMatch !== normalizedToken) throw new Error(`Round 5 ${value.method} does not exactly match the Recruitee token`); if (!["authoritative_dataset", "company_owned_page", "business_registry"].includes(value.provenanceKind)) throw new Error("Round 5 identity requires authoritative provenance"); if (value.provenanceKind === "authoritative_dataset" && !approvedDatasetReferences.has(reference)) throw new Error("Round 5 authoritative_dataset reference is not an approved dataset"); if (value.provenanceKind !== "authoritative_dataset") { let url: URL; try { url = new URL(reference); } catch { throw new Error("Manual Round 5 identity references must be HTTPS URLs"); } if (url.protocol !== "https:") throw new Error("Manual Round 5 identity references must be HTTPS URLs"); if (value.provenanceKind === "company_owned_page" && !domainContains(url.hostname, companyDomain)) throw new Error("Company-owned identity reference must match the joined company domain"); if (value.provenanceKind === "business_registry" && !approvedBusinessRegistryDomains.some((domain) => domainContains(url.hostname, domain))) throw new Error("Round 5 business_registry reference is not an approved business registry"); } return { ...value, token, companyName, companyDomain, reference }; }
+function parseIdentity(value: unknown): JoinedRecruiteeIdentity { if (!record(value) || typeof value.token !== "string" || typeof value.companyName !== "string" || typeof value.companyDomain !== "string" || typeof value.reference !== "string" || typeof value.method !== "string" || typeof value.provenanceKind !== "string") throw new Error("Each Round 5 identity requires token, companyName, companyDomain, reference, method, and provenanceKind strings"); return validateIdentity(value as unknown as JoinedRecruiteeIdentity); }
+function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function normalizeDomain(value: string): string { return value.trim().toLowerCase().replace(/^www\./, ""); }
+function normalizeMatchValue(value: string): string { return value.toLowerCase().replace(/[^a-z0-9]/g, ""); }
+function domainContains(host: string, domain: string) { const value = normalizeDomain(host); return value === domain || value.endsWith(`.${domain}`); }
+function roundRootFromRegistry(path: string): string { const absolute = resolve(path); const marker = `${sep}generations${sep}`; const index = absolute.lastIndexOf(marker); if (index < 0) throw new Error("Isolated registry must belong to a Round 5 generation"); return absolute.slice(0, index); }

package/src/report-meta.ts

@@ -0,0 +1,17 @@
+export interface ReportMeta {
+  schemaVersion: number;
+  pipelineVersion: string;
+  generatedAt: string;
+}
+
+export function stampReport<T extends object>(pipelineVersion: string, schemaVersion: number, payload: T, now = new Date()): T & ReportMeta {
+  return { ...payload, schemaVersion, pipelineVersion, generatedAt: now.toISOString() };
+}
+
+export function assertCompatibleReport(value: unknown, pipelineVersion: string, schemaVersion: number): asserts value is ReportMeta & Record<string, unknown> {
+  if (!value || typeof value !== "object") throw new Error("Report must be a JSON object");
+  const report = value as Record<string, unknown>;
+  if (report.pipelineVersion !== pipelineVersion || report.schemaVersion !== schemaVersion || typeof report.generatedAt !== "string" || !Number.isFinite(Date.parse(report.generatedAt))) {
+    throw new Error(`Incompatible report: expected ${pipelineVersion} schema ${schemaVersion}; regenerate it with the current CLI`);
+  }
+}

package/src/requirement-vocabulary.ts

@@ -0,0 +1,111 @@
+export type TransferabilityKind = "backend_programming" | "frontend_programming" | "data_engineering" | "cloud_infrastructure";
+
+interface RequirementDefinition {
+  canonical: string;
+  display: string;
+  aliases?: string[];
+  evidence: "exact_skill" | "fact_phrase";
+  matching?: { caseSensitive?: boolean; excludedPhrases?: string[]; excludedPatterns?: string[] };
+}
+
+interface TransferabilityEdge {
+  target: string;
+  sources: string[];
+  via: TransferabilityKind;
+  rationale: string;
+}
+
+const requirementDefinitions: RequirementDefinition[] = [
+  ...exactSkills([["java", "Java"]]),
+  exactSkill("go", "Go", undefined, { caseSensitive: true, excludedPhrases: ["go-to-market", "go-live", "on-the-go"] }),
+  ...exactSkills([
+    ["golang", "Golang"], ["python", "Python"], ["ruby", "Ruby"], ["node.js", "Node.js"],
+    ["postgresql", "PostgreSQL"], ["sql", "SQL"], ["javascript", "JavaScript"], ["typescript", "TypeScript"],
+    ["vue", "Vue"], ["angular", "Angular"], ["spark", "Spark"], ["hadoop", "Hadoop"], ["dbt", "dbt"], ["airflow", "Airflow"],
+    ["snowflake", "Snowflake"], ["aws", "AWS"], ["azure", "Azure"], ["gcp", "GCP"], ["kubernetes", "Kubernetes"],
+    ["docker", "Docker"], ["terraform", "Terraform"], ["kafka", "Kafka"], ["databricks", "Databricks"], ["redis", "Redis"],
+    ["mongodb", "MongoDB"], ["linux", "Linux"], ["nosql", "NoSQL"], ["c++", "C++"], ["machine learning", "Machine learning"],
+    ["jenkins", "Jenkins"], ["spring boot", "Spring Boot"],
+  ]),
+  exactSkill("react", "React", ["react.js", "reactjs"]),
+  exactSkill("spring", "Spring", undefined, {
+    excludedPatterns: [String.raw`\bspring(?:\s*[/,&-]\s*(?:fall|summer|winter))*\s+(?:semester\s+)?(?:19|20)\d{2}\b`],
+  }),
+  exactSkill("ci/cd", "CI/CD", ["continuous integration and continuous delivery", "continuous integration/continuous delivery"]),
+  exactSkill("llm", "LLM", ["large language model", "large language models"]),
+  phrase("financial products", "Financial products"),
+  phrase("data warehouses", "Data warehouses", ["data warehouse"]),
+  phrase("etl pipelines", "ETL pipelines", ["etl pipeline"]),
+  phrase("high-volume messaging", "High-volume messaging"),
+  phrase("streaming platforms", "Streaming platforms", ["streaming platform"]),
+  phrase("transaction processing", "Transaction processing", ["transaction-processing"]),
+  phrase("restful services", "RESTful services"),
+  phrase("microservices", "Microservices"),
+];
+
+// Empty by default. Every future edge requires a durable rationale and public-behavior tests.
+const transferabilityEdges: TransferabilityEdge[] = [];
+
+const definitionsByCanonical = new Map(requirementDefinitions.map((definition) => [definition.canonical, definition]));
+
+export function detectRequirementTerms(value: string): string[] {
+  const occurrences = requirementDefinitions.flatMap((definition) => matchingTerms(definition).flatMap((term) => findOccurrences(value, term, definition)));
+  const accepted: typeof occurrences = [];
+  for (const occurrence of occurrences.sort((left, right) => right.length - left.length || left.start - right.start)) {
+    if (!accepted.some((candidate) => occurrence.start < candidate.end && occurrence.end > candidate.start)) accepted.push(occurrence);
+  }
+  const matched = new Set(accepted.map((occurrence) => occurrence.definition.canonical));
+  return requirementDefinitions.filter((definition) => matched.has(definition.canonical)).map((definition) => definition.display);
+}
+
+export function matchesExactSkillEvidence(requirement: string, skill: string): boolean {
+  const definition = definitionsByCanonical.get(requirement.toLocaleLowerCase());
+  if (definition?.evidence !== "exact_skill") return false;
+  const normalized = skill.trim().toLocaleLowerCase();
+  return [definition.canonical, definition.display, ...(definition.aliases ?? [])].some((value) => value.toLocaleLowerCase() === normalized);
+}
+
+export function requiresExactSkillEvidence(requirement: string): boolean {
+  return definitionsByCanonical.get(requirement.toLocaleLowerCase())?.evidence === "exact_skill";
+}
+
+export function findTransferability(requirement: string, skills: Array<{ id: string; value: string }>): { via: TransferabilityKind; factIds: string[] } | undefined {
+  const edge = transferabilityEdges.find((candidate) => candidate.target === requirement.toLocaleLowerCase());
+  if (!edge) return undefined;
+  const facts = skills.filter((skill) => edge.sources.includes(skill.value.toLocaleLowerCase()));
+  return facts.length ? { via: edge.via, factIds: facts.map((fact) => fact.id) } : undefined;
+}
+
+function exactSkills(values: Array<[canonical: string, display: string]>): RequirementDefinition[] {
+  return values.map(([canonical, display]) => ({ canonical, display, evidence: "exact_skill" }));
+}
+
+function exactSkill(canonical: string, display: string, aliases?: string[], matching?: RequirementDefinition["matching"]): RequirementDefinition {
+  return { canonical, display, aliases, evidence: "exact_skill", matching };
+}
+
+function phrase(canonical: string, display: string, aliases?: string[]): RequirementDefinition {
+  return { canonical, display, aliases, evidence: "fact_phrase" };
+}
+
+function matchingTerms(definition: RequirementDefinition): string[] {
+  const base = definition.matching?.caseSensitive ? [definition.display, ...(definition.aliases ?? [])] : [definition.canonical, ...(definition.aliases ?? [])];
+  return [...new Set(base.flatMap((term) => [term, term.replace(/-/gu, " "), term.replace(/ /gu, "-")]))];
+}
+
+function findOccurrences(value: string, term: string, definition: RequirementDefinition): Array<{ definition: RequirementDefinition; start: number; end: number; length: number }> {
+  let searchable = value;
+  for (const excluded of definition.matching?.excludedPhrases ?? []) searchable = maskMatches(searchable, new RegExp(escapeRegex(excluded), "giu"));
+  for (const pattern of definition.matching?.excludedPatterns ?? []) searchable = maskMatches(searchable, new RegExp(pattern, "giu"));
+  const escaped = escapeRegex(term);
+  const flags = definition.matching?.caseSensitive ? "gu" : "giu";
+  const matches = searchable.matchAll(new RegExp(`(^|[^a-z0-9+#])(${escaped})(?=$|[^a-z0-9+#])`, flags));
+  return [...matches].map((match) => {
+    const start = match.index + match[1]!.length;
+    const end = start + match[2]!.length;
+    return { definition, start, end, length: end - start };
+  });
+}
+
+function escapeRegex(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"); }
+function maskMatches(value: string, pattern: RegExp): string { return value.replace(pattern, (match) => " ".repeat(match.length)); }

package/src/resume-optimization.ts

@@ -0,0 +1,118 @@
+import type { CandidateProfile, NormalizedResume, ResumeInput } from "./candidate-profile.ts";
+import type { AnalyzeJobFitResult, JobFitReason } from "./job-fit-analysis.ts";
+import { assertKnownKeys, isRecord } from "./intent-validation.ts";
+import type { Job } from "./types.ts";
+
+export type ResumeOptimizationOutput = "suggestions" | "unified_diff" | "revised_markdown";
+export interface OptimizeResumeInput { jobId: string; resume: ResumeInput; output: ResumeOptimizationOutput }
+export interface ResumeSuggestion {
+  action: "elevate";
+  proposedText: string;
+  factIds: string[];
+  jobEvidence: JobFitReason["jobEvidence"];
+  rationale: string;
+}
+export interface OptimizeResumeResult {
+  job: Job;
+  profile: CandidateProfile;
+  output: ResumeOptimizationOutput;
+  suggestions: ResumeSuggestion[];
+  gaps: string[];
+  content?: string;
+  diffBase?: NormalizedResume;
+  originalOverwritten: false;
+}
+export interface ResumeOptimizerOptions { analyzeJobFit(input: unknown): Promise<AnalyzeJobFitResult> }
+
+export class ResumeOptimizationError extends Error {
+  constructor(readonly code: "invalid_resume_optimization_input", message: string, readonly field?: string) { super(message); }
+}
+
+export function createResumeOptimizer(options: ResumeOptimizerOptions) {
+  return {
+    async optimize(value: unknown): Promise<OptimizeResumeResult> {
+      const input = validateInput(value);
+      const analysis = await options.analyzeJobFit({ jobId: input.jobId, resume: input.resume });
+      const facts = new Map(analysis.profile.facts.map((fact) => [fact.id, fact]));
+      const suggestions: ResumeSuggestion[] = [];
+      const used = new Set<string>();
+      for (const support of analysis.supported) {
+        const jobReason = analysis.assessment.reasons.find((candidate) => candidate.candidateFactIds?.some((id) => support.factIds.includes(id)));
+        for (const fact of analysis.profile.facts.filter((candidate) => achievementFactKinds.has(candidate.kind) && includesPhrase(candidate.value, support.requirement))) {
+          if (used.has(fact.id)) continue;
+          used.add(fact.id);
+          suggestions.push({
+            action: "elevate",
+            proposedText: fact.value,
+            factIds: [fact.id],
+            jobEvidence: jobReason?.jobEvidence ?? { field: "description", quote: analysis.job.description },
+            rationale: `Elevate this complete existing achievement because it demonstrates ${support.requirement}`,
+          });
+        }
+        for (const factId of support.factIds) {
+          const fact = facts.get(factId);
+          if (!fact || !editableFactKinds.has(fact.kind) || used.has(fact.id)) continue;
+          used.add(fact.id);
+          suggestions.push({
+            action: "elevate",
+            proposedText: fact.value,
+            factIds: [fact.id],
+            jobEvidence: jobReason?.jobEvidence ?? { field: "description", quote: analysis.job.description },
+            rationale: `Elevate this existing resume fact because it directly supports ${support.requirement}`,
+          });
+        }
+      }
+      return {
+        job: analysis.job,
+        profile: analysis.profile,
+        output: input.output,
+        suggestions,
+        gaps: analysis.unsupported,
+        ...(input.output === "revised_markdown" ? { content: revisedMarkdown(analysis.profile.normalizedResume.text, suggestions) } : {}),
+        ...(input.output === "unified_diff" ? { content: unifiedDiff(analysis.profile.normalizedResume.text, suggestions) } : {}),
+        ...(input.output === "unified_diff" ? { diffBase: analysis.profile.normalizedResume } : {}),
+        originalOverwritten: false,
+      };
+    },
+  };
+}
+
+const editableFactKinds = new Set(["skill", "outcome", "experience_statement", "project", "project_statement", "education", "certification"]);
+const achievementFactKinds = new Set(["outcome", "experience_statement", "project_statement"]);
+
+function includesPhrase(value: string, phrase: string): boolean {
+  const escaped = phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^A-Za-z0-9+.#])${escaped}(?=$|[^A-Za-z0-9+.#])`, "i").test(value);
+}
+
+function revisedMarkdown(original: string, suggestions: ResumeSuggestion[]): string {
+  if (!suggestions.length) return original;
+  return `# Targeted Highlights\n\n${suggestions.map((suggestion) => `- ${suggestion.proposedText}`).join("\n")}\n\n${original}`;
+}
+
+function unifiedDiff(original: string, suggestions: ResumeSuggestion[]): string {
+  if (!suggestions.length) return "";
+  const originalLines = original.split("\n");
+  const inserted = ["# Targeted Highlights", "", ...suggestions.map((suggestion) => `- ${suggestion.proposedText}`), ""];
+  return [
+    "--- resume",
+    "+++ resume.optimized.md",
+    `@@ -1,${originalLines.length} +1,${originalLines.length + inserted.length} @@`,
+    ...inserted.map((line) => `+${line}`),
+    ...originalLines.map((line) => ` ${line}`),
+  ].join("\n");
+}
+
+function validateInput(value: unknown): OptimizeResumeInput {
+  if (!isRecord(value)) throw invalid("input", "Resume optimization input must be an object");
+  assertKnownKeys(value, ["jobId", "resume", "output"], "input", invalid);
+  if (typeof value.jobId !== "string" || !value.jobId.trim()) throw invalid("jobId", "jobId must be a non-empty string");
+  if (!isRecord(value.resume)) throw invalid("resume", "Resume input must be an object");
+  assertKnownKeys(value.resume, ["content", "format"], "resume", invalid);
+  if (!(["suggestions", "unified_diff", "revised_markdown"] as unknown[]).includes(value.output)) throw invalid("output", "output must be suggestions, unified_diff, or revised_markdown");
+  return { jobId: value.jobId, resume: value.resume as unknown as ResumeInput, output: value.output as ResumeOptimizationOutput };
+}
+
+function invalid(field: string, message: string): ResumeOptimizationError {
+  return new ResumeOptimizationError("invalid_resume_optimization_input", message, field);
+}

package/src/runtime.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import { fetchSourceJobs } from "./catalog.ts";
+import { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
+import { catalog as liveCatalog, companies } from "./index.ts";
+import { createLocalJobs } from "./local-jobs.ts";
+import { createJobRecommender } from "./job-recommendations.ts";
+import { createJobFitAnalyzer } from "./job-fit-analysis.ts";
+import { createResumeOptimizer } from "./resume-optimization.ts";
+import { createSelectedJobLookup } from "./selected-job-lookup.ts";
+import { createFileSnapshotStore } from "./snapshot-store.ts";
+import { createJobCoverageReader } from "./job-coverage.ts";
+import { createJobSearchPreparer } from "./job-search-preparation.ts";
+
+export function createRuntime(options: { dataDir?: string; concurrency?: number; crawlDelayMs?: number; workdayPageDelayMs?: number; sourceCacheHours?: number; sourceLimit?: number } = {}) {
+  const dataDir = options.dataDir ?? process.env.OPENINGS_DATA_DIR ?? join(process.cwd(), ".openings");
+  const store = createFileSnapshotStore(join(dataDir, "snapshot.json"));
+  const aggregatorUrl = resolveAggregatorUrl(process.env.OPENINGS_AGGREGATOR_URL);
+  const onCrawled = aggregatorUrl ? createCrawlReporter({ url: aggregatorUrl }) : undefined;
+  const local = createLocalJobs({
+    sources: companies,
+    store,
+    fetchJobs: (source, signal, observer) => fetchSourceJobs(source, globalThis.fetch, signal, observer),
+    concurrency: options.concurrency,
+    sourceStartDelayMs: options.crawlDelayMs,
+    sourceFreshnessMs: (options.sourceCacheHours ?? 0) * 60 * 60 * 1000,
+    sourceLimit: options.sourceLimit,
+    workdayPageDelayMs: options.workdayPageDelayMs,
+    onCrawled,
+  });
+  const recommender = createJobRecommender({ sources: companies, store, crawl: local.crawl });
+  const coverage = createJobCoverageReader({ sources: companies, store });
+  const preparationLocal = createLocalJobs({
+    sources: companies,
+    store,
+    fetchJobs: (source, signal, observer) => fetchSourceJobs(source, globalThis.fetch, signal, observer),
+    concurrency: options.concurrency,
+    timeoutMs: 90_000,
+    maxAttempts: 1,
+    sourceStartDelayMs: options.crawlDelayMs,
+    workdayPageDelayMs: options.workdayPageDelayMs,
+    onCrawled,
+  });
+  const preparation = createJobSearchPreparer({ sources: companies, store, crawl: preparationLocal.crawl, seed: aggregatorUrl ? () => fetchSeedSnapshot(aggregatorUrl) : undefined });
+  const getSelectedJob = createSelectedJobLookup({
+    getSnapshotJob: async (id) => (await local.get(id, { offline: true, staleDays: 14 })).job,
+    getDetailedJob: (id) => liveCatalog.get(id),
+  });
+  const analyzer = createJobFitAnalyzer({ getJob: getSelectedJob });
+  const optimizer = createResumeOptimizer({ analyzeJobFit: analyzer.analyze });
+  return { ...local, prepareJobSearch: preparation.prepare, getJobCoverage: coverage.getCoverage, recommend: recommender.recommend, analyzeJobFit: analyzer.analyze, optimizeResume: optimizer.optimize };
+}

package/src/safe-get.ts

@@ -0,0 +1,88 @@
+import { lookup } from "node:dns/promises";
+import { request } from "node:https";
+import { isIP } from "node:net";
+import { connect as connectTls } from "node:tls";
+
+export interface SafeGetResult { status: number; finalUrl: string; contentType: string; body: string; requestCount: number }
+export type ResolveGetHost = (hostname: string) => Promise<string[]>;
+export class SafeGetError extends Error { constructor(message: string, readonly requestCount: number, readonly failedRequestCount: number, readonly safety: boolean) { super(message); } }
+
+export async function fetchSafeGet(value: string, options: { timeoutMs?: number; maxBytes?: number; maxRequests?: number; allowedDomain?: string; allowedOrigin?: string; resolveHost?: ResolveGetHost } = {}): Promise<SafeGetResult> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const maxBytes = options.maxBytes ?? 2 * 1024 * 1024;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+  let requests = 0;
+  let requestInFlight = false;
+  try {
+    let current = checkedUrl(value);
+    const allowedDomain = normalizeHost(options.allowedDomain ?? current.hostname);
+    const allowedOrigin = normalizeOriginHost(options.allowedOrigin ?? current.hostname);
+    for (let redirects = 0; redirects <= 3; redirects += 1) {
+      if (redirects >= (options.maxRequests ?? 4)) throw new Error("GET request budget exhausted during redirects");
+      if (!withinDomain(current.hostname, allowedDomain) || normalizeOriginHost(current.hostname) !== allowedOrigin) throw new Error("GET URL left the approved origin");
+      const addresses = isIP(current.hostname) ? [current.hostname] : await resolveWithAbort((options.resolveHost ?? resolveAddresses)(current.hostname), controller.signal);
+      if (!addresses.length || addresses.some((address) => !isPublicAddress(address))) throw new Error(`URL resolves to a non-public address: ${current.hostname}`);
+      requests += 1;
+      requestInFlight = true;
+      const response = await pinnedGet(current, addresses[0]!, controller.signal, maxBytes);
+      requestInFlight = false;
+      if (![301, 302, 303, 307, 308].includes(response.status)) return { ...response, finalUrl: current.href, requestCount: requests };
+      const location = response.location;
+      if (!location) return { ...response, finalUrl: current.href, requestCount: requests };
+      const next = checkedUrl(new URL(location, current).href);
+      if (!withinDomain(next.hostname, allowedDomain) || normalizeOriginHost(next.hostname) !== allowedOrigin) throw new Error("GET redirect left the approved origin");
+      current = next;
+    }
+    throw new Error("GET redirect limit exceeded");
+  } catch (error) { const message = error instanceof Error ? error.message : String(error); throw new SafeGetError(message, requests, requestInFlight ? 1 : 0, /non-public|approved origin|company domain|credential-free HTTPS|request budget|redirect limit|content encoding|exceeds \d+ bytes/i.test(message)); }
+  finally { clearTimeout(timer); }
+}
+
+function checkedUrl(value: string): URL {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.port && url.port !== "443" || url.username || url.password) throw new Error("Probe URL must use credential-free HTTPS on port 443");
+  return url;
+}
+
+function pinnedGet(url: URL, address: string, signal: AbortSignal, maxBytes: number): Promise<{ status: number; contentType: string; body: string; location?: string }> {
+  return new Promise((resolve, reject) => {
+    const req = request(url, {
+      method: "GET", signal, servername: url.hostname, agent: false,
+      headers: { accept: "text/html,application/xml,text/xml,text/plain", "accept-encoding": "identity", "user-agent": "Openings/0.1 (+https://github.com/)" },
+      createConnection: () => connectTls({ host: address, port: 443, servername: url.hostname }),
+    }, (response) => {
+      const encoding = String(response.headers["content-encoding"] ?? "identity").toLowerCase();
+      if (encoding !== "identity") { response.destroy(); reject(new Error(`Unsupported content encoding: ${encoding}`)); return; }
+      const chunks: Buffer[] = [];
+      let bytes = 0;
+      response.on("data", (chunk: Buffer) => {
+        bytes += chunk.length;
+        if (bytes > maxBytes) { response.destroy(new Error(`Response exceeds ${maxBytes} bytes`)); return; }
+        chunks.push(chunk);
+      });
+      response.once("error", reject);
+      response.once("end", () => resolve({ status: response.statusCode ?? 500, contentType: String(response.headers["content-type"] ?? ""), body: Buffer.concat(chunks).toString("utf8"), location: typeof response.headers.location === "string" ? response.headers.location : undefined }));
+    });
+    req.once("error", reject);
+    req.end();
+  });
+}
+
+async function resolveAddresses(hostname: string): Promise<string[]> { return (await lookup(hostname, { all: true, verbatim: true })).map(({ address }) => address); }
+function normalizeHost(value: string) { return value.toLowerCase().replace(/^www\./, ""); }
+function normalizeOriginHost(value: string) { return value.toLowerCase(); }
+function withinDomain(host: string, domain: string): boolean { const value = normalizeHost(host); return value === domain || value.endsWith(`.${domain}`); }
+function resolveWithAbort<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+function isPublicAddress(address: string): boolean {
+  if (isIP(address) === 4) { const [a, b] = address.split(".").map(Number); return !(a === 0 || a === 10 || a === 127 || a === 100 && b! >= 64 && b! <= 127 || a === 169 && b === 254 || a === 172 && b! >= 16 && b! <= 31 || a === 192 && (b === 0 || b === 168) || a === 198 && (b === 18 || b === 19 || b === 51) || a === 203 && b === 0 || a! >= 224); }
+  if (isIP(address) === 6) { const value = address.toLowerCase(); return !(value === "::" || value === "::1" || value.startsWith("::ffff:") || value.startsWith("fc") || value.startsWith("fd") || /^fe[89ab]/.test(value) || value.startsWith("ff") || value.startsWith("2001:db8")); }
+  return false;
+}