Hot Paths

Use this before editing. It is a map, not a substitute for reading live code. Prefer rg over trusting line numbers.

Data Model

• Product/business constraints:
  • studies/business-model/README.md
  • studies/architecture/README.md
• Op catalog and apply:
  • lib/mutations/src/opsCatalog.ts
  • lib/mutations/src/apply.ts
  • lib/mutations/src/url-normalize.ts
• Read/write helpers:
  • lib/domain/src/read-chain.ts
  • lib/domain/src/jobcache.ts
  • lib/domain/src/cell-origins.ts
• Migration:
  • existing migration scripts under ui/scripts/
  • shared-corpus migrations under migrations/
  • migrations/drop-job-id-allocator.sql

Invariants:

• ad_id is deterministic from normalized URL.
• URL normalization and hash truncation are immutable post-ship.
• Workspace human/agent writes go through job.* ops into workspace.jobs[job_id].attributes.
• A workspace job entry is { url, attributes }.
• System/pipeline scrape/extract writes shared ad facts through jobcache.
• Role facts are aggregate/shared facts, not directly user-written workspace state.

Workspace Client

• lib/workspace-client/src/client.ts
• lib/workspace-client/src/sub-doc.ts
• lib/workspace-client/src/optimistic.ts
• lib/workspace-client/src/transport/http.ts

Current blocker:

lib/mutations, workspace-client, app routes, MCP, and dashboard code must all agree that workspace ops are job.* and the workspace sub-doc is jobs.

Fixing this is not a mechanical rename only. It changes:

• valid sub-doc list,
• routeOp/opKindToSubDoc,
• tailored op routing,
• client tests and browser components that dispatch job operations.

API Server Commit Path

• lib/server/src/workspace-subdoc.ts
• lib/server/src/workspace-ops.ts
• api/src/routers/workspaces.ts — workspace REST routes (Hono), including GET /workspaces/:id/sub/:subDoc and GET/POST /workspaces/:id/jobs[/...]

Invariants:

• Durable workspace writes go through workspace op application.
• Missing sub-doc rows are corruption, not empty documents.
• Read-only mirrors must reject writes.
• job.create apply must ensure shared ad/role knowledge exists or enqueue that work.

Dashboard And Job Detail

• ui/src/lib/components/dashboard/Dashboard.svelte
• ui/src/lib/components/dashboard/table/DataCell.svelte
• ui/src/lib/components/dashboard/job-detail/
• ui/src/lib/pipeline.svelte.ts

Cleanup task:

Replace direct workspace.jobs[jobId].field assumptions with a resolved job view produced through the read chain.

Workspace Intelligence / Process Requests

• lib/server/src/process-requests.ts
• lib/server/src/dispatch-fallback.ts
• api/src/lib/server/process-commands.ts
• api/src/routers/workspaces.ts (/workspaces/:id/process-requests routes)
• ui/src/lib/components/ui/WorkspaceIntelligence.svelte

Invariants:

• Browser execution is the cheap path when a workspace tab is open.
• Server fallback exists for headless/MCP user intent.
• Process request IDs should key on (workspaceId, ad_id, stage) after the shared ad is known, while public/API language remains job.
• Do not build a separate agent-only pipeline.

MCP

• mcp/src/tools/add_job.ts
• mcp/src/tools/update_job.ts
• mcp/src/tools/delete_job.ts
• mcp/src/tools/list_jobs.ts
• mcp/src/tools/get_job.ts
• mcp/src/tools/process-request-id.ts
• mcp/test/

Current state:

MCP should speak public jobs: add/update/delete/list/get map to job.* ops and resolved workspace job projections.

CVL

• ui/src/lib/components/cvl/CvGenerator.svelte
• ui/src/lib/components/cvl/CVLEditor.svelte
• ui/src/lib/components/cvl/editors/
• lib/mutations/src/apply.ts node/tailored handlers

Invariants:

• CVL is a recursive Node tree.
• DocumentStack-like shapes are projections, not a second truth.
• Tailored CV/CL placement is under workspace.jobs[job_id].attributes.tailored_cv / tailored_cl unless the user explicitly decides to lift it.