Glossary

Use these words consistently. Each word should mean one thing.

Source Catalog

  • family: reusable job-site type, such as Workday, Greenhouse, jobs.ch, RSS, or custom HTML.
  • source: concrete job site, board, company career page, or tenant. Examples: UBS Workday, Roche Workday, jobs.ch CH.
  • Adapter: language-neutral dock contract for one family, one special source, or one browser-compatible read provider. It is not a TypeScript-only implementation body.
  • implementation: private blackbox behind the Adapter dock. It may be TypeScript, Rust, WASM, Tauri native helper code, browser automation, Jina or a provider chain, a feed reader, CareerVector's single-URL observe() path, or another suitable implementation path.
  • RADAR: CareerVector workspace entry surface for finding or importing jobs. It can search the shared database, add a URL manually, or surface machine-made candidates. It is not an Adapter, Method, source, or submitted data shape.
  • scrapeUrl: CareerVector's single-URL chain runner. It tries ordered browser-compatible adapters/providers and returns scrape telemetry plus the shared Observation payload when one can be produced.
  • Method: small source-method label used for dashboards and routing, such as sitemap-jsonld, html-bespoke, headless-proxy, or feed-api.
  • Env: runtime capability bundle passed through the Adapter dock, including fetch, user agent, abort signal, and policy hints.
  • ObservationOptions: runtime envelope hints used to complete an Observation.
  • ParsedAd: internal normalized parse helper. It may help an implementation build an Observation, but it is not submitted output. Raw source/API/provider output is private implementation detail.
  • binding: configuration that connects one source to one Adapter, including seed URLs, freshness, risk, limits, selectors, and source-specific hints.

Work

  • task: one bounded unit of work, such as discover URLs, fetch one page, parse one page, embed one text chunk, or verify one observation.
  • task class: resource class for work. Current classes are scrape, chunk, enrich, embed, and verify.
  • task kind: concrete kind of work. Current kinds are discover-urls, fetch-page, parse-page, chunk-text, enrich-observation, embed-text, and verify-observation.
  • lease: temporary assignment of one task to one device.
  • device: durable enrolled machine identity that reports capabilities and can receive leases.
  • session: one running app instance/process on a device.
  • device leader: the local session currently allowed to advertise capacity and execute leased tasks for the device.
  • Observation: canonical submitted task output. For ad observations it is the full envelope anchored to one ad_id. The current contract calls the submitted sparse payload map fields; each field contains a cell and may include evidence refs and observed_at.

Shared Boundary

  • payload: the information-carrying job/ad/role content. This is why the system exists: title, organization, description, location, compensation, workload, employment type, posting dates, and similar domain content.
  • metadata: node-specific machinery such as ids, URLs, language identity, leases, task ids, trust/churn/cooldown, workflow status, files, and timestamps.
  • state: mutable operational metadata used to run workflows, resolve conflicts, and keep costs low. State is not shared payload.
  • ad: shared identity for one public job listing in one observed language. Canonical identity is URL x language via adIdFromUrlLanguage(url, language).
  • role: URL-family identity above one or more language-specific ads, derived with roleIdFromUrl(url). It has payload like every other tree node, but it is not a submitted observation target, and semantic cross-URL reduction is async work outside the hot submission path.
  • workspace job: CareerVector's private workspace record for a user's application workflow. It has payload like every other tree node, plus private workspace state. It is not part of the Cockroach observation envelope and is never Adapter output.
  • field: named payload attribute from the shared payload vocabulary. The same field vocabulary is valid at role, ad, and workspace-job level; presence is sparse.
  • cell: sparse payload for one field on one tree node. A cell stores the value shape and optional evidence/timestamp references for that field. Trust is device-level, not cell confidence.
  • resolved cell: value exposed to a read surface after role payload, ad payload, and private workspace payload have been overlaid.
  • current cell: compact current value exposed to read surfaces for one payload field on one ad after submitObservation has applied the latest valid value.
  • evidence: source material or reference that supports observations and cells, such as URL, content hash, object key, extracted snippet, or fetch metadata. Evidence is provenance and audit material; it is not trust itself.
  • chunk: stable text segment derived from evidence or resolved text for extraction, full-text search, RAG, or embedding.
  • embedding: vector record for a stable input key, usually a chunk, field text, ad projection, or role projection. It rides inside an Observation when produced by a device task; it is not separate submitted output.
  • fact: accepted field/cell value with provenance. Use this as shorthand only when the field/cell distinction is not relevant.
  • integration flow: either JobCache top-down distributed ingest or CareerVector bottom-up workspace lookup/write. Both emit and consume the same @cv/jobcache Observation shape at the shared boundary. CareerVector workspace-origin Observations are handed off by D1 jobcache_commands rows committed in the same workspace batch, then drained by JobCache.
  • read surface: consumer of resolved ad/workspace state, such as CareerVector workspace UI, CareerVector API, MCP, search, QA, ops, or export surfaces.

Observations anchor to one URL x language ad_id. Shared JobCache data is ad-centered, while the read model is a tree: URL-family role payload -> ad payload -> workspace-job payload. Workspace jobs remain private CareerVector records. Evidence, chunks, and embeddings attach by stable ad, field, chunk, and input keys. They do not form a parallel JobCache or CareerVector data shape.

Avoid

  • Do not use provider for job sites. Use source.
  • Do not use worker for JobCache execution. It collides with Cloudflare Workers, web workers, and service workers. Use device for the durable enrolled machine and session for a running process.
  • Do not use runner for JobCache execution. It collides with CI/CD runners.
  • Do not use scraper as a data-model word. It means Adapter plus browser, device, or runtime while executing scrape tasks.
  • Do not use posting as the canonical product identity unless referring to a historical table name or one observed source row. Use ad for the canonical listing node.
  • Submitted JobCache payloads are Observation payloads.
  • The submitted ad shape uses field, fields, and cell.
  • Do not put metadata/state into the payload vocabulary just because one UI displays it. If a field only makes sense on one tree level, it is metadata or state for that node, not shared payload. status_id is workspace workflow state; evaluations may roll upward later, but are not in the v0 shared payload tree.
  • Do not add generic addressing fields or role/workspace job addresses to submitted observations.
  • Do not use adapter_pack, source_instance, source_binding, submitted-output candidate aliases, or work_task in new docs/code unless a migration needs to refer to superseded wording.
Source: jobcache/wiki/content/architecture/glossary.md