@verevoir/context 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.2.0 — 2026-05-23
+
+**Breaking restructure** — replaces `@verevoir/context/sources` with a per-source subpath pattern + a generic `wrapWithCache` primitive.
+
+```ts
+// 0.1.x
+import { cachedReadFile } from '@verevoir/context/sources';
+await cachedReadFile(env, repoUrl, path);
+
+// 0.2.x — convenience subpath
+import { readFile } from '@verevoir/context/github';
+await readFile(env, repoUrl, path);
+
+// 0.2.x — custom adapter via the generic decorator
+import { wrapWithCache } from '@verevoir/context';
+import { mySource } from 'my-source-pkg';
+const cached = wrapWithCache(mySource);
+await cached.readFile(env, sourceUrl, path);
+```
+
+**The model** (per Adam's substrate framing): a cache implements the same contract as the source it wraps. So `@verevoir/context/github` is a drop-in replacement for `@verevoir/sources/github` — same `SourceAdapter` shape, plus caching. Same for `@verevoir/context/fs`.
+
+**Two new subpaths**:
+
+- `@verevoir/context/github` = `wrapWithCache(github)` from `@verevoir/sources/github`. Optional peer dep on `@verevoir/sources`.
+- `@verevoir/context/fs` = `wrapWithCache(fs)` from `@verevoir/sources/fs`. Optional peer dep on `@verevoir/sources`.
+
+**New export at the root**: `wrapWithCache(source, { store? })` — decorator that adds read-through caching to any SourceAdapter. For custom adapter implementations that aren't shipped as a convenience subpath.
+
+Behaviour: `readFile` caches; `writeFile` passes through and populates the cache with the just-written content; everything else is pass-through at v0. Per-method caching (listFiles, getRepoTree) can layer in later if profiling shows it matters.
+
+**Removed**: `@verevoir/context/sources` (the generic adapter-pluggable bridge that 0.1.x exposed). The per-source convenience + the generic `wrapWithCache` together cover the use cases more cleanly.
+
 ## 0.1.0 — 2026-05-23
 
 Initial release.

package/README.md

@@ -10,9 +10,10 @@ Pairs naturally with [`@verevoir/sources`](https://github.com/verevoir/sources)
 
 ## Subpaths
 
-- `@verevoir/context` — core `ContextStore` (content + symbol cache), `grep` over cached content, `IndexKey` + `SymbolEntry` types. No external dependencies.
-- `@verevoir/context/code` — tree-sitter symbol extraction (`parseSymbols`, `detectLanguage`) + `findSymbols` over the store. Optional peer deps on `tree-sitter`, `tree-sitter-typescript`, `tree-sitter-javascript`.
-- `@verevoir/context/sources` — `cachedReadFile` bridge that pairs the store with `@verevoir/sources/github`. Optional peer dep on `@verevoir/sources`.
+- `@verevoir/context` — core `ContextStore` (content + symbol cache), `grep` over cached content, `wrapWithCache` decorator that adds read-through caching to any `@verevoir/sources` adapter, `IndexKey` + `SymbolEntry` types. No external dependencies; the decorator type-checks against `@verevoir/sources` but doesn't import it at runtime unless you call it.
+- `@verevoir/context/code` — tree-sitter symbol extraction (`parseSymbols`, `detectLanguage`) + `findSymbols` over the store. Optional peer deps on tree-sitter packages.
+- `@verevoir/context/github` — cached GitHub source. Drop-in replacement for `@verevoir/sources/github` that adds read-through caching. Identical contract.
+- `@verevoir/context/fs` — cached local-filesystem source. Drop-in replacement for `@verevoir/sources/fs` that adds read-through caching. Identical contract.
 
 ## Install
 
@@ -65,21 +66,53 @@ const hits = findSymbols('auth', {
 // → [{ name: 'AuthHandler', kind: 'class', ... }, { name: 'authenticate', kind: 'method', ... }]
 ```
 
-### Cached reads against `@verevoir/sources`
+### Cached source — convenience subpaths
+
+Drop-in replacements for `@verevoir/sources/<kind>` that add read-through caching. Same `SourceAdapter` contract; consumers swap the import path to gain caching, no other code changes.
 
 ```ts
 import { envFromProcessEnv } from '@verevoir/sources';
-import { cachedReadFile } from '@verevoir/context/sources';
+import { readFile, writeFile } from '@verevoir/context/github';
 
 const env = envFromProcessEnv();
 if (!env) throw new Error('GITHUB_TOKEN not set');
 
-// First call fetches and caches; second call hits the cache.
-const a = await cachedReadFile(env, 'https://github.com/acme/charts', 'README.md');
-const b = await cachedReadFile(env, 'https://github.com/acme/charts', 'README.md');
-// `b` came from cache; only one HTTP call was made.
+// First call hits the GitHub API; second call serves from cache.
+const a = await readFile(env, 'https://github.com/acme/charts', 'README.md');
+const b = await readFile(env, 'https://github.com/acme/charts', 'README.md');
+
+// Writes pass through and populate the cache.
+await writeFile(
+  env,
+  'https://github.com/acme/charts',
+  'docs/notes.md',
+  '# Notes\n',
+  'feature/notes',
+  'Add notes'
+);
 ```
 
+```ts
+import { readFile } from '@verevoir/context/fs';
+const env = { token: '', forkOrg: '' }; // fs adapter ignores both
+
+const r = await readFile(env, '/path/to/project', 'src/index.ts');
+```
+
+### Cached source — custom adapters
+
+Bring your own SourceAdapter implementation; wrap it once to get the same caching behaviour.
+
+```ts
+import { wrapWithCache } from '@verevoir/context';
+import { mySource } from 'my-source-pkg'; // implements @verevoir/sources's SourceAdapter
+
+const cached = wrapWithCache(mySource);
+const r = await cached.readFile(env, sourceUrl, path);
+```
+
+`wrapWithCache(source, { store? })` returns a `SourceAdapter`-shaped facade. Cache hits return `sha: ''` (the source's sha is not preserved across cache rounds; callers that need a real sha should re-fetch from cache-miss or call the underlying source).
+
 ## Key shape
 
 The cache key is `(sourceId, version, itemId)`:
@@ -105,7 +138,7 @@ interface SymbolEntry {
 
 ## Per-instance + singleton
 
-The default singleton `contextStore` is shared across imports of the same module. Tests and multi-tenant consumers can call `createContextStore()` to get an isolated instance and pass it via the `store` option on `grep`, `findSymbols`, and `cachedReadFile`.
+The default singleton `contextStore` is shared across imports of the same module. Tests and multi-tenant consumers can call `createContextStore()` to get an isolated instance and pass it via the `store` option on `grep`, `findSymbols`, and `wrapWithCache`.
 
 ## What this is NOT
 

package/dist/fs/index.d.ts

@@ -0,0 +1,10 @@
+export declare const fs: import("@verevoir/sources").SourceAdapter;
+export declare const readFile: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, path: string, ref?: string) => Promise<import("@verevoir/sources").ReadFileResult>;
+export declare const listFiles: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, prefix: string, ref?: string) => Promise<import("@verevoir/sources").DirEntry[]>;
+export declare const getRepoTree: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, ref?: string) => Promise<import("@verevoir/sources").RepoTree>;
+export declare const writeFile: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, path: string, content: string, branch: string, commitMessage: string) => Promise<void>;
+export declare const ensureBranch: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, branch: string) => Promise<void>;
+export declare const ensureFork: (env: import("@verevoir/sources").SourceEnv, upstreamUrl: string) => Promise<string>;
+export declare const openPullRequest: (env: import("@verevoir/sources").SourceEnv, targetUrl: string, head: string, base: string, title: string, body: string) => Promise<string>;
+export declare const getDefaultBranch: (env: import("@verevoir/sources").SourceEnv, repoUrl: string) => Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/fs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,EAAE,2CAAuB,CAAC;AAEvC,eAAO,MAAM,QAAQ,kJAAuB,CAAC;AAC7C,eAAO,MAAM,SAAS,gJAAwB,CAAC;AAC/C,eAAO,MAAM,WAAW,8HAA0B,CAAC;AACnD,eAAO,MAAM,SAAS,sJAAwB,CAAC;AAC/C,eAAO,MAAM,YAAY,gGAA2B,CAAC;AACrD,eAAO,MAAM,UAAU,sFAAyB,CAAC;AACjD,eAAO,MAAM,eAAe,6IAA8B,CAAC;AAC3D,eAAO,MAAM,gBAAgB,kFAA+B,CAAC"}

package/dist/fs/index.js

@@ -0,0 +1,22 @@
+// @verevoir/context/fs — cached local-filesystem source.
+//
+// Drop-in replacement for `@verevoir/sources/fs` that adds
+// read-through caching via the root `ContextStore`. SourceAdapter
+// contract identical; consumers swap the import path to add
+// caching, no other code changes.
+//
+// All caching logic lives in `wrapWithCache` at the root — this
+// file is just the wiring. Per Adam's substrate framing
+// (2026-05-23): "specific cache == cache + specific source".
+import { fs as rawFs } from '@verevoir/sources/fs';
+import { wrapWithCache } from '../index.js';
+export const fs = wrapWithCache(rawFs);
+export const readFile = fs.readFile.bind(fs);
+export const listFiles = fs.listFiles.bind(fs);
+export const getRepoTree = fs.getRepoTree.bind(fs);
+export const writeFile = fs.writeFile.bind(fs);
+export const ensureBranch = fs.ensureBranch.bind(fs);
+export const ensureFork = fs.ensureFork.bind(fs);
+export const openPullRequest = fs.openPullRequest.bind(fs);
+export const getDefaultBranch = fs.getDefaultBranch.bind(fs);
+//# sourceMappingURL=index.js.map

package/dist/fs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,2DAA2D;AAC3D,kEAAkE;AAClE,4DAA4D;AAC5D,kCAAkC;AAClC,EAAE;AACF,gEAAgE;AAChE,wDAAwD;AACxD,6DAA6D;AAE7D,OAAO,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC"}

package/dist/github/index.d.ts

@@ -0,0 +1,10 @@
+export declare const github: import("@verevoir/sources").SourceAdapter;
+export declare const readFile: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, path: string, ref?: string) => Promise<import("@verevoir/sources").ReadFileResult>;
+export declare const listFiles: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, prefix: string, ref?: string) => Promise<import("@verevoir/sources").DirEntry[]>;
+export declare const getRepoTree: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, ref?: string) => Promise<import("@verevoir/sources").RepoTree>;
+export declare const writeFile: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, path: string, content: string, branch: string, commitMessage: string) => Promise<void>;
+export declare const ensureBranch: (env: import("@verevoir/sources").SourceEnv, repoUrl: string, branch: string) => Promise<void>;
+export declare const ensureFork: (env: import("@verevoir/sources").SourceEnv, upstreamUrl: string) => Promise<string>;
+export declare const openPullRequest: (env: import("@verevoir/sources").SourceEnv, targetUrl: string, head: string, base: string, title: string, body: string) => Promise<string>;
+export declare const getDefaultBranch: (env: import("@verevoir/sources").SourceEnv, repoUrl: string) => Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/github/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/github/index.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,MAAM,2CAA2B,CAAC;AAK/C,eAAO,MAAM,QAAQ,kJAA+B,CAAC;AACrD,eAAO,MAAM,SAAS,gJAAgC,CAAC;AACvD,eAAO,MAAM,WAAW,8HAAkC,CAAC;AAC3D,eAAO,MAAM,SAAS,sJAAgC,CAAC;AACvD,eAAO,MAAM,YAAY,gGAAmC,CAAC;AAC7D,eAAO,MAAM,UAAU,sFAAiC,CAAC;AACzD,eAAO,MAAM,eAAe,6IAAsC,CAAC;AACnE,eAAO,MAAM,gBAAgB,kFAAuC,CAAC"}

package/dist/github/index.js

@@ -0,0 +1,25 @@
+// @verevoir/context/github — cached GitHub source.
+//
+// Drop-in replacement for `@verevoir/sources/github` that adds
+// read-through caching via the root `ContextStore`. The
+// SourceAdapter contract is identical; consumers swap the import
+// path to add caching, no other code changes.
+//
+// All caching logic lives in `wrapWithCache` at the root — this
+// file is just the wiring. Per Adam's substrate framing
+// (2026-05-23): "specific cache == cache + specific source".
+import { github as rawGithub } from '@verevoir/sources/github';
+import { wrapWithCache } from '../index.js';
+export const github = wrapWithCache(rawGithub);
+// Re-export the individual functions for ergonomic destructured
+// imports. Same shape as `@verevoir/sources/github` — only the
+// behaviour (cache-hit / cache-populate) differs.
+export const readFile = github.readFile.bind(github);
+export const listFiles = github.listFiles.bind(github);
+export const getRepoTree = github.getRepoTree.bind(github);
+export const writeFile = github.writeFile.bind(github);
+export const ensureBranch = github.ensureBranch.bind(github);
+export const ensureFork = github.ensureFork.bind(github);
+export const openPullRequest = github.openPullRequest.bind(github);
+export const getDefaultBranch = github.getDefaultBranch.bind(github);
+//# sourceMappingURL=index.js.map

package/dist/github/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/github/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,+DAA+D;AAC/D,wDAAwD;AACxD,iEAAiE;AACjE,8CAA8C;AAC9C,EAAE;AACF,gEAAgE;AAChE,wDAAwD;AACxD,6DAA6D;AAE7D,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAE/C,gEAAgE;AAChE,+DAA+D;AAC/D,kDAAkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC"}

package/dist/index.d.ts

@@ -88,4 +88,33 @@ export interface GrepOptions {
  * the consumer has fetched into the store — does not fan out to
  * the underlying source. Pure local lookup. */
 export declare function grep(pattern: string, scope: GrepScope, options?: GrepOptions): GrepHit[];
+import type { SourceAdapter } from '@verevoir/sources';
+export interface WrapWithCacheOptions {
+    /** Store to read/write. Defaults to the module's singleton. */
+    store?: ContextStore;
+}
+/** Returns a `SourceAdapter`-shaped facade that reads through the
+ * ContextStore. A drop-in replacement for the underlying source:
+ * the contract is identical, the wrapping is invisible to callers.
+ *
+ * - `readFile` checks the cache; on miss, fetches via the source
+ *   and populates the cache. Cache hits return `sha: ''` (the
+ *   source's sha is not preserved across cache rounds; callers
+ *   that need a real sha should go to the source directly or
+ *   re-fetch from cache-miss).
+ * - `writeFile` passes through, then populates the cache with the
+ *   just-written content so subsequent reads see it without a
+ *   refetch.
+ * - All other methods are pure pass-throughs at v0; the symbol
+ *   cache and grep operate on what the cache already holds, fed
+ *   primarily by `readFile`. Per-method caching (listFiles tree
+ *   memoisation, etc.) can layer in later if profiling shows it
+ *   matters.
+ *
+ * Per Adam's substrate model (2026-05-23): a specific cache IS a
+ * specific source — same contract — so the consumer just imports
+ * `@verevoir/context/<kind>` and gets caching for free, without
+ * having to thread the adapter through every call site.
+ */
+export declare function wrapWithCache(source: SourceAdapter, options?: WrapWithCacheOptions): SourceAdapter;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA;;2CAE2C;AAC3C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzF,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;mEAGmE;AACnE,MAAM,WAAW,QAAQ;IACvB;kEAC8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;4BAEwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAcD;;;;;;+CAM+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,SAAS,CAAC;IACrD,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACxD,kDAAkD;IAClD,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACpC;;6BAEyB;IACzB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D;4DACwD;IACxD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9D;2CACuC;IACvC,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAmDjD;AAED;qDACqD;AACrD,eAAO,MAAM,YAAY,EAAE,YAAmC,CAAC;AAM/D,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,OAAO,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAKD;;+CAE+C;AAC/C,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,EAAE,CA+B5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA;;2CAE2C;AAC3C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzF,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;mEAGmE;AACnE,MAAM,WAAW,QAAQ;IACvB;kEAC8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;4BAEwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAcD;;;;;;+CAM+C;AAC/C,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,SAAS,CAAC;IACrD,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACxD,kDAAkD;IAClD,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACpC;;6BAEyB;IACzB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D;4DACwD;IACxD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9D;2CACuC;IACvC,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAmDjD;AAED;qDACqD;AACrD,eAAO,MAAM,YAAY,EAAE,YAAmC,CAAC;AAM/D,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,OAAO,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAKD;;+CAE+C;AAC/C,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,EAAE,CA+B5F;AAMD,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAiEf"}

package/dist/index.js

@@ -10,9 +10,11 @@
 //     payload is code; populated lazily by the `/code` subpath)
 //
 // Pure in-memory. No I/O — the cache holds what consumers put in it.
-// Bridges to actual sources live in subpaths (`/code` for tree-sitter
-// symbol extraction; `/sources` for the cached-read helper that pairs
-// with `@verevoir/sources`).
+// `wrapWithCache(source)` here returns a SourceAdapter-shaped facade
+// that reads through the cache; per-source convenience wrappers live
+// in subpaths (`@verevoir/context/github` = wrap-cache + github,
+// `@verevoir/context/fs` = wrap-cache + fs). Tree-sitter symbol
+// extraction lives in `/code`.
 //
 // Scope: per-process. A Cloud Run instance, a long-running worker,
 // a CLI invocation — each holds its own. Cross-instance share lands
@@ -124,4 +126,69 @@ export function grep(pattern, scope, options = {}) {
     }
     return hits;
 }
+/** Returns a `SourceAdapter`-shaped facade that reads through the
+ * ContextStore. A drop-in replacement for the underlying source:
+ * the contract is identical, the wrapping is invisible to callers.
+ *
+ * - `readFile` checks the cache; on miss, fetches via the source
+ *   and populates the cache. Cache hits return `sha: ''` (the
+ *   source's sha is not preserved across cache rounds; callers
+ *   that need a real sha should go to the source directly or
+ *   re-fetch from cache-miss).
+ * - `writeFile` passes through, then populates the cache with the
+ *   just-written content so subsequent reads see it without a
+ *   refetch.
+ * - All other methods are pure pass-throughs at v0; the symbol
+ *   cache and grep operate on what the cache already holds, fed
+ *   primarily by `readFile`. Per-method caching (listFiles tree
+ *   memoisation, etc.) can layer in later if profiling shows it
+ *   matters.
+ *
+ * Per Adam's substrate model (2026-05-23): a specific cache IS a
+ * specific source — same contract — so the consumer just imports
+ * `@verevoir/context/<kind>` and gets caching for free, without
+ * having to thread the adapter through every call site.
+ */
+export function wrapWithCache(source, options = {}) {
+    const store = options.store ?? contextStore;
+    return {
+        async readFile(env, sourceUrl, path, ref) {
+            const version = ref ?? '';
+            const key = { sourceId: sourceUrl, version, itemId: path };
+            const cached = store.getContent(key);
+            if (cached !== undefined) {
+                return { content: cached, sha: '' };
+            }
+            const result = await source.readFile(env, sourceUrl, path, ref);
+            store.setContent(key, result.content);
+            return result;
+        },
+        async listFiles(env, sourceUrl, prefix, ref) {
+            return source.listFiles(env, sourceUrl, prefix, ref);
+        },
+        async getRepoTree(env, sourceUrl, ref) {
+            return source.getRepoTree(env, sourceUrl, ref);
+        },
+        async writeFile(env, sourceUrl, path, content, branch, commitMessage) {
+            await source.writeFile(env, sourceUrl, path, content, branch, commitMessage);
+            // Populate cache with the just-written content. `setContent`
+            // invalidates any cached symbols for the same key, so
+            // downstream find_symbol re-parses on the next query.
+            const key = { sourceId: sourceUrl, version: branch, itemId: path };
+            store.setContent(key, content);
+        },
+        async ensureBranch(env, sourceUrl, branch) {
+            return source.ensureBranch(env, sourceUrl, branch);
+        },
+        async ensureFork(env, upstreamUrl) {
+            return source.ensureFork(env, upstreamUrl);
+        },
+        async openPullRequest(env, targetUrl, head, base, title, body) {
+            return source.openPullRequest(env, targetUrl, head, base, title, body);
+        },
+        async getDefaultBranch(env, sourceUrl) {
+            return source.getDefaultBranch(env, sourceUrl);
+        },
+    };
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,mBAAmB;AACnB,EAAE;AACF,0DAA0D;AAC1D,gEAAgE;AAChE,8BAA8B;AAC9B,EAAE;AACF,8DAA8D;AAC9D,kEAAkE;AAClE,gEAAgE;AAChE,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,6BAA6B;AAC7B,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,oDAAoD;AAiCpD,mEAAmE;AACnE,sDAAsD;AACtD,mEAAmE;AACnE,oCAAoC;AACpC,MAAM,GAAG,GAAG,MAAM,CAAC;AACnB,SAAS,OAAO,CAAC,GAAa;IAC5B,OAAO,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,GAAG,GAAG,CAAC,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;AAClE,CAAC;AACD,SAAS,aAAa,CAAC,QAAgB,EAAE,OAAe;IACtD,OAAO,GAAG,QAAQ,GAAG,GAAG,GAAG,OAAO,GAAG,GAAG,EAAE,CAAC;AAC7C,CAAC;AA4BD,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEjD,OAAO;QACL,UAAU,CAAC,GAAG;YACZ,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,UAAU,CAAC,GAAG,EAAE,OAAO;YACrB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACzB,yDAAyD;YACzD,uDAAuD;YACvD,sBAAsB;YACtB,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QACD,UAAU,CAAC,GAAG;YACZ,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,UAAU,CAAC,GAAG,EAAE,OAAO;YACrB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,cAAc,CAAC,GAAG;YAChB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QACD,iBAAiB,CAAC,QAAQ,EAAE,OAAO;YACjC,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC/B,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QACD,gBAAgB,CAAC,QAAQ,EAAE,OAAO;YAChC,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,GAAG,GAAa,EAAE,CAAC;YACzB,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChC,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBACzB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QACD,QAAQ;YACN,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;qDACqD;AACrD,MAAM,CAAC,MAAM,YAAY,GAAiB,kBAAkB,EAAE,CAAC;AAmC/D,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B;;+CAE+C;AAC/C,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,KAAgB,EAAE,UAAuB,EAAE;IAC/E,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,IAAI,gBAAgB,CAAC;IACnD,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,IAAI,oBAAoB,CAAC;IAC7D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,MAAM,IAAI,GAAc,EAAE,CAAC;IAE3B,KAAK,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxD,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;gBAAE,OAAO,IAAI,CAAC;YACpC,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAChE,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAS;YACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;oBAAE,OAAO,IAAI,CAAC;gBACpC,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAChE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAAE,SAAS;gBACzC,IAAI,CAAC,IAAI,CAAC;oBACR,QAAQ;oBACR,MAAM;oBACN,UAAU,EAAE,CAAC,GAAG,CAAC;oBACjB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;oBACd,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;oBACvD,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;iBAClD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/sources/index.d.ts

@@ -1,5 +1,12 @@
-import { type SourceEnv } from '@verevoir/sources';
+import { type SourceEnv, type ReadFileResult } from '@verevoir/sources';
 import { type ContextStore } from '../index.js';
+/** Minimal shape an adapter must satisfy to be cached. Any
+ * `@verevoir/sources/<kind>` subpath's `readFile` matches; full
+ * `SourceAdapter` matches by construction. Keeps the bridge usable
+ * with read-only adapters that don't implement the write half. */
+export interface CachedReadAdapter {
+    readFile(env: SourceEnv, sourceUrl: string, path: string, ref?: string): Promise<ReadFileResult>;
+}
 export interface CachedReadOptions {
     /** Source version to use as the cache key. Defaults to the empty
      * string — the canonical "default branch / latest" sentinel. */
@@ -7,16 +14,25 @@ export interface CachedReadOptions {
     /** Store to read/write. Defaults to the module's singleton. */
     store?: ContextStore;
 }
-/** Read a file from a GitHub repo via `@verevoir/sources/github`,
- * with an in-process cache layered on top via `ContextStore`. Misses
- * fetch and populate the store; hits return immediately.
+/** Read a file via any `SourceAdapter`'s `readFile`, with an
+ * in-process cache layered on top via `ContextStore`. Misses fetch
+ * and populate the store; hits return immediately.
  *
- * The cache key is `(repoUrl, version, path)` — the empty-string
+ * The cache key is `(sourceUrl, version, path)` — the empty-string
  * version sentinel keeps default-branch reads in a stable slot so
  * different call sites reading the same file at default share the
  * cache.
  *
- * For non-GitHub sources, callers can implement an equivalent bridge
- * using their adapter's `readFile` and the same store. */
-export declare function cachedReadFile(env: SourceEnv, repoUrl: string, path: string, options?: CachedReadOptions): Promise<string>;
+ * Usage:
+ *
+ * ```ts
+ * import { github } from '@verevoir/sources/github';
+ * import { fs } from '@verevoir/sources/fs';
+ * import { cachedReadFile } from '@verevoir/context/sources';
+ *
+ * await cachedReadFile(github, env, repoUrl, path);
+ * await cachedReadFile(fs, env, '/local/path', 'README.md');
+ * ```
+ */
+export declare function cachedReadFile(adapter: CachedReadAdapter, env: SourceEnv, sourceUrl: string, path: string, options?: CachedReadOptions): Promise<string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/sources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sources/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAErF,MAAM,WAAW,iBAAiB;IAChC;oEACgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;0DAU0D;AAC1D,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAWjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sources/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAErF;;;kEAGkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAClG;AAED,MAAM,WAAW,iBAAiB;IAChC;oEACgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/sources/index.js

@@ -5,33 +5,48 @@
 // for a given `(sourceId, version, itemId)` triggers the adapter
 // fetch; subsequent calls return cached content without re-fetching.
 //
+// Adapter-agnostic since 0.2.0 — pass any `SourceAdapter`-shaped
+// object with at least `readFile`. Lets the same store/cache layer
+// front GitHub reads (via `@verevoir/sources/github`), local-FS
+// reads (via `@verevoir/sources/fs`), or any other adapter that
+// matches the contract. The store doesn't care about the source
+// kind; the cache key is opaque text either way.
+//
 // Peer dep on `@verevoir/sources` is optional in the package
 // manifest — consumers using `@verevoir/context` purely as an
 // in-memory cache (writing their own values via `setContent`) don't
 // need to install it.
-import { readFile } from '@verevoir/sources/github';
 import { contextStore as defaultContextStore } from '../index.js';
-/** Read a file from a GitHub repo via `@verevoir/sources/github`,
- * with an in-process cache layered on top via `ContextStore`. Misses
- * fetch and populate the store; hits return immediately.
+/** Read a file via any `SourceAdapter`'s `readFile`, with an
+ * in-process cache layered on top via `ContextStore`. Misses fetch
+ * and populate the store; hits return immediately.
  *
- * The cache key is `(repoUrl, version, path)` — the empty-string
+ * The cache key is `(sourceUrl, version, path)` — the empty-string
  * version sentinel keeps default-branch reads in a stable slot so
  * different call sites reading the same file at default share the
  * cache.
  *
- * For non-GitHub sources, callers can implement an equivalent bridge
- * using their adapter's `readFile` and the same store. */
-export async function cachedReadFile(env, repoUrl, path, options = {}) {
+ * Usage:
+ *
+ * ```ts
+ * import { github } from '@verevoir/sources/github';
+ * import { fs } from '@verevoir/sources/fs';
+ * import { cachedReadFile } from '@verevoir/context/sources';
+ *
+ * await cachedReadFile(github, env, repoUrl, path);
+ * await cachedReadFile(fs, env, '/local/path', 'README.md');
+ * ```
+ */
+export async function cachedReadFile(adapter, env, sourceUrl, path, options = {}) {
     const version = options.version ?? '';
     const store = options.store ?? defaultContextStore;
-    const key = { sourceId: repoUrl, version, itemId: path };
+    const key = { sourceId: sourceUrl, version, itemId: path };
     const cached = store.getContent(key);
     if (cached !== undefined)
         return cached;
     // Map empty-string sentinel back to "no ref" for the adapter.
     const ref = version === '' ? undefined : version;
-    const { content } = await readFile(env, repoUrl, path, ref);
+    const { content } = await adapter.readFile(env, sourceUrl, path, ref);
     store.setContent(key, content);
     return content;
 }

package/dist/sources/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sources/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,iEAAiE;AACjE,qEAAqE;AACrE,EAAE;AACF,6DAA6D;AAC7D,8DAA8D;AAC9D,oEAAoE;AACpE,sBAAsB;AAGtB,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAqB,MAAM,aAAa,CAAC;AAUrF;;;;;;;;;;0DAU0D;AAC1D,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAc,EACd,OAAe,EACf,IAAY,EACZ,UAA6B,EAAE;IAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IACnD,MAAM,GAAG,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACzD,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,8DAA8D;IAC9D,MAAM,GAAG,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IACjD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5D,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sources/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,iEAAiE;AACjE,qEAAqE;AACrE,EAAE;AACF,iEAAiE;AACjE,mEAAmE;AACnE,gEAAgE;AAChE,gEAAgE;AAChE,gEAAgE;AAChE,iDAAiD;AACjD,EAAE;AACF,6DAA6D;AAC7D,8DAA8D;AAC9D,oEAAoE;AACpE,sBAAsB;AAGtB,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAqB,MAAM,aAAa,CAAC;AAkBrF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAA0B,EAC1B,GAAc,EACd,SAAiB,EACjB,IAAY,EACZ,UAA6B,EAAE;IAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IACnD,MAAM,GAAG,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,8DAA8D;IAC9D,MAAM,GAAG,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IACjD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACtE,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verevoir/context",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "In-process content + symbol cache for LLM context windows. Keyed (source, version, item). Tree-sitter symbol extraction + grep + cached-read bridge as subpath imports.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,9 +15,13 @@
       "types": "./dist/code/index.d.ts",
       "import": "./dist/code/index.js"
     },
-    "./sources": {
-      "types": "./dist/sources/index.d.ts",
-      "import": "./dist/sources/index.js"
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "import": "./dist/github/index.js"
+    },
+    "./fs": {
+      "types": "./dist/fs/index.d.ts",
+      "import": "./dist/fs/index.js"
     }
   },
   "files": [
@@ -57,7 +61,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.8.0",
-    "@verevoir/sources": "^0.1.0",
+    "@verevoir/sources": "^0.2.0",
     "prettier": "^3",
     "tree-sitter": "^0.21.1",
     "tree-sitter-javascript": "^0.23.1",