[GRV-26]: Establish attribution catalog and repair boundary guard (#44)

## Summary

Part of the **llm-cost architecture contracts** Project. Two
deliverables, both scoped to the `llm-cost-attribution` package (per
this issue's title + `llm-cost-attribution` label):

1. **Repair the boundary guard** so its config reflects the package
after the estimation extraction.
2. **Establish the attribution use-case catalog** as the canonical,
complete source of truth for the attribution surface.

### Repair boundary guard —
`packages/llm-cost-attribution/scripts/check-boundary.mjs`

The boundary config carried two **dead references** to modules that were
extracted to `llm-cost-estimation` (in GRV-2 / the estimation split) but
never removed here:

- `src/enrich.mjs` in `coreModules`
- `src/linear-estimate-source.mjs` in `adapterModules`

Neither file exists in this package, so `existsSync` silently skipped
them — the guard *claimed* to protect/classify modules it can no longer
see. Repaired by:

- Removing both dead entries.
- Replacing stale remediation text that still pointed at the moved
`LinearEstimateSource` with port-neutral attribution guidance
(`SessionSource` / `IssueMatcher` / `UsageRecordSource` /
`UsageRecordSink`). The defensive `@linear` / `https` / `fs` /
`child_process` forbidden-package rules are kept.

To repair the *class* of bug (not just the instance),
`test/boundary.test.mjs` now:

- Adds **config-integrity tests** asserting every configured
`coreModules` / `adapterModules` path exists on disk, so dead or phantom
entries fail CI instead of silently passing.
- Exercises the core-imports-adapter rule against a **real** adapter
(`attribution-adapters.mjs`) instead of the removed Linear adapter.

### Establish attribution catalog —
`docs/architecture/use-case-catalog.md`

- Added a canonical intro, the inward dependency rule, and the linkage
to the boundary guard that enforces it.
- Cataloged the two remaining public use cases that were documented in
the package catalog/README but missing here:
**CreateAttributionWorkflow** and **ListKnownIssues**. The catalog now
covers the full attribution public surface.

## Verification

- `npm test` (llm-cost-attribution): **200 pass / 0 fail** (was 198; +2
new config-integrity tests).
- `node scripts/check-boundary.mjs`: **Boundary check passed**.
- `node --check` on changed `scripts/check-boundary.mjs` and
`test/boundary.test.mjs`: ✓.
- Project-acceptance, llm-cost-architecture-contracts — **GRV-26's
portion is fully green**:
  - `architecture-boundary.check.mjs` (runs the repaired guard): ✓
  - `attribution-ports.test.mjs`: ✓
  - catalog/API alignment: **no findings for `llm-cost-attribution`**.
- Rebased onto latest `origin/main` (includes #43 / GRV-27).

## Out of scope (observed, not fixed here)

The non-required project-acceptance gate still reports **one** finding,
in the separate **`llm-cost-estimation`** package, left by the
just-merged GRV-27 (#43):
`packages/llm-cost-estimation/docs/use-cases.md:67` marks the
now-implemented `forecastProjectCost` as planned/stubbed. That is
estimation-catalog territory (GRV-27's rollout), not this attribution
issue — flagged here as a breadcrumb for a follow-up rather than mixing
packages in one PR. `pr-build` (the required gate) excludes the
project-acceptance directory, so this does not block merge.

Co-authored-by: riddim-developer-bot <developer-bot@riddimsoftware.com>

Author: riddim-developer-bot[bot]

docs/architecture/use-case-catalog.md

@@ -1,5 +1,21 @@
 # Use Case Catalog
 
+The canonical catalog of every application-layer use case in `llm-cost-attribution`:
+its actor, goal, entities/values, ports, primary adapters, and the inward boundary
+rule it relies on. Each entry names its `Current implementation` so the catalog and
+the source stay traceable.
+
+**Dependency rule.** Core modules import no filesystem, transcript, usage-JSONL, CLI,
+HTTP/Linear, or `child_process` API — only ports (`SessionSource`, `IssueMatcher`,
+`UsageRecordSource`, `UsageRecordSink`, and the forecaster's `EstimateTaggedUsageSource`
+/ `PricingTable` / `QuotaModel` / `DiffSource`) cross inward. This rule is enforced by
+`packages/llm-cost-attribution/scripts/check-boundary.mjs` (`npm run test:boundary`) and
+the project-acceptance boundary check; the guard's `coreModules` / `adapterModules` lists
+must stay aligned with the modules cataloged here.
+
+**Convention:** every PR that adds or changes a use case updates this catalog in the
+same PR.
+
 ### ForecastIssueCost
 Actor: Operator
 Goal: Forecast token, turn, $ API-equivalent, and Codex quota cost for one issue from historical issues with the same size and model.
@@ -53,6 +69,17 @@ Ports: none — pure function over in-memory pairs.
 Primary adapters: none. Joining (DiffSource → FeatureCostPair) lives in JoinCostWithFeature.
 Current implementation: `packages/llm-cost-attribution/src/correlate.mjs`
 
+### CreateAttributionWorkflow
+Actor: Operator (library integrator)
+Goal: Bind the four attribution ports into one workflow object so callers can compute issue/worktree cost and backfill usage from their own sources and sinks, with no filesystem assumptions baked into the core.
+Inputs: `{ sessionSource, issueMatcher, usageRecordSource, usageRecordSink, recordedAt? }` — caller-supplied port implementations.
+Outputs: a workflow object exposing `computeIssueCost`, `computeWorktreeCost`, `computeIssueCostFromUsage`, `iterateUsageFromSessions`, and `backfillUsage`.
+Entities / values: ParsedSession, UsageRecord, IssueRollup, UsageBackfillSummary.
+Ports: SessionSource, IssueMatcher, UsageRecordSource, UsageRecordSink.
+Primary adapters: none in the core — each convenience wrapper (`computeIssueCost`, etc.) wires the real transcript/usage adapters (`transcriptSessionSource`, `cwdIssueMatcher`, `usageJsonlRecordSource`, `appendingUsageRecordSink`) at the edge, while tests supply in-memory ports.
+Notes: pure composition entry point for the port-based core — imports no filesystem/transcript/usage-JSONL/CLI/HTTP/Linear/child_process (enforced by `npm run test:boundary` and the project-acceptance boundary check).
+Current implementation: `packages/llm-cost-attribution/src/attribution-workflow.mjs` (`createAttributionWorkflow`)
+
 ### ComputeIssueCost
 Actor: Operator
 Goal: Roll up token/turn/quota cost for one issue from caller-supplied sessions, without assuming the data came from local Claude/Codex transcript directories.
@@ -103,3 +130,14 @@ Entities / values: UsageRecord, IssueRollup.
 Ports: UsageRecordSource.
 Primary adapters: `usageJsonlRecordSource` over the usage-JSONL reader (drops malformed lines); in-memory sources in tests. The `computeIssueCostFromUsage` convenience wrapper wires the reader at the edge.
 Current implementation: `packages/llm-cost-attribution/src/attribution-workflow.mjs` (`computeIssueCostFromUsageRecords`)
+
+### ListKnownIssues
+Actor: Operator
+Goal: Enumerate every issue identifier that has at least one local Claude or Codex session, for pickers and dashboards, without computing any rollup.
+Inputs: options selecting the local transcript roots (defaults to the standard Claude/Codex session directories).
+Outputs: a sorted list of issue identifiers discovered across local transcripts.
+Entities / values: ParsedSession (read for its identifier only).
+Ports: none — adapter-only enumeration over the transcript readers.
+Primary adapters: Claude/Codex transcript readers.
+Notes: adapter-only; it lives at the edge rather than the core because it reads the local transcript filesystem directly, so it is not subject to the core dependency rule.
+Current implementation: `packages/llm-cost-attribution/src/index.mjs` (`listKnownIssues`)

packages/llm-cost-attribution/scripts/check-boundary.mjs

@@ -11,14 +11,12 @@ export const BOUNDARY_CONFIG = {
     'src/forecast.mjs',
     'src/quantiles.mjs',
     'src/project-forecast.mjs',
-    'src/enrich.mjs',
     'src/correlate.mjs',
     'src/cost-feature-join.mjs',
     'src/attribution-ports.mjs',
     'src/attribution-workflow.mjs',
   ],
   adapterModules: [
-    { path: 'src/linear-estimate-source.mjs', kind: 'Linear adapter' },
     { path: 'src/pricing.mjs', kind: 'pricing adapter/access point' },
     { path: 'src/quota.mjs', kind: 'quota adapter/access point' },
     { path: 'src/transcripts/', kind: 'transcript filesystem adapter' },
@@ -37,12 +35,12 @@ export const BOUNDARY_CONFIG = {
     {
       pattern: /^(?:node:)?https?$/,
       kind: 'HTTP API',
-      remediation: 'HTTP access belongs in LinearEstimateSource or another adapter. Depend on a port instead.',
+      remediation: 'HTTP access belongs in an adapter, not the attribution core. Depend on a port instead.',
     },
     {
       pattern: /^@linear(?:\/|$)/,
       kind: 'Linear SDK',
-      remediation: 'Depend on the EstimateTaggedUsageSource / LinearEstimateSource port instead.',
+      remediation: 'The Linear SDK has no place in the attribution core; the Linear estimate adapter lives in llm-cost-estimation. Depend on an injected port instead.',
     },
     {
       pattern: /^(?:node:)?child_process$/,
@@ -185,7 +183,7 @@ function formatPackageViolation(sourcePath, specifier, violation, docsPath) {
 function formatAdapterViolation(sourcePath, specifier, resolvedPath, kind, docsPath) {
   return (
     `${sourcePath} imports ${specifier} (${kind}; resolves to ${resolvedPath}) - ` +
-    `Depend on the EstimateTaggedUsageSource / LinearEstimateSource port instead. See ${docsPath}.`
+    `Depend on an attribution port (SessionSource / IssueMatcher / UsageRecordSource / UsageRecordSink) instead. See ${docsPath}.`
   );
 }
 

packages/llm-cost-attribution/test/boundary.test.mjs

@@ -1,11 +1,14 @@
 import { strict as assert } from 'node:assert';
+import { existsSync } from 'node:fs';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, it } from 'node:test';
 import { spawnSync } from 'node:child_process';
 
+import { BOUNDARY_CONFIG } from '../scripts/check-boundary.mjs';
+
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CHECK_BOUNDARY = join(PACKAGE_ROOT, 'scripts/check-boundary.mjs');
 
@@ -41,15 +44,15 @@ describe('boundary checker', () => {
     });
   });
 
-  it('fails when a core module imports the Linear adapter', async () => {
+  it('fails when a core module imports the attribution transcript/usage adapter', async () => {
     await withFixture({
-      'src/forecast.mjs': "import { LinearEstimateSource } from './linear-estimate-source.mjs';\nvoid LinearEstimateSource;\n",
+      'src/forecast.mjs': "import { transcriptSessionSource } from './attribution-adapters.mjs';\nvoid transcriptSessionSource;\n",
     }, async (root) => {
       const result = runBoundary(root);
       assert.notEqual(result.status, 0);
-      assert.match(result.stderr, /src\/forecast\.mjs imports \.\/linear-estimate-source\.mjs/);
-      assert.match(result.stderr, /Linear adapter/);
-      assert.match(result.stderr, /EstimateTaggedUsageSource \/ LinearEstimateSource port/);
+      assert.match(result.stderr, /src\/forecast\.mjs imports \.\/attribution-adapters\.mjs/);
+      assert.match(result.stderr, /attribution transcript\/usage adapter/);
+      assert.match(result.stderr, /SessionSource \/ IssueMatcher \/ UsageRecordSource \/ UsageRecordSink/);
       assert.match(result.stderr, /docs\/architecture\/use-case-catalog\.md/);
     });
   });
@@ -123,3 +126,27 @@ describe('boundary checker', () => {
     });
   });
 });
+
+describe('boundary config integrity', () => {
+  it('every configured core module exists in the package', () => {
+    for (const modulePath of BOUNDARY_CONFIG.coreModules) {
+      assert.ok(
+        existsSync(join(PACKAGE_ROOT, modulePath)),
+        `coreModules references a path that no longer exists: ${modulePath}. ` +
+          'A core module that has moved or been deleted is silently skipped by the guard - ' +
+          'remove or correct the entry so the boundary config reflects the real package.',
+      );
+    }
+  });
+
+  it('every configured adapter module exists in the package', () => {
+    for (const entry of BOUNDARY_CONFIG.adapterModules) {
+      assert.ok(
+        existsSync(join(PACKAGE_ROOT, entry.path)),
+        `adapterModules references a path that no longer exists: ${entry.path} (${entry.kind}). ` +
+          'A phantom adapter entry classifies nothing - ' +
+          'remove or correct the entry so the boundary config reflects the real package.',
+      );
+    }
+  });
+});