witan-code 0.9.0__tar.gz → 0.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. {witan_code-0.9.0 → witan_code-0.10.0}/CHANGELOG.md +122 -2
  2. {witan_code-0.9.0 → witan_code-0.10.0}/PKG-INFO +115 -10
  3. {witan_code-0.9.0 → witan_code-0.10.0}/README.md +113 -8
  4. witan_code-0.10.0/docs/BRANCH_INDEXING.md +337 -0
  5. {witan_code-0.9.0 → witan_code-0.10.0}/docs/CLI_REFERENCE.md +6 -2
  6. {witan_code-0.9.0 → witan_code-0.10.0}/docs/USER_GUIDE.md +18 -11
  7. {witan_code-0.9.0 → witan_code-0.10.0}/pyproject.toml +2 -2
  8. {witan_code-0.9.0 → witan_code-0.10.0}/tests/conftest.py +15 -0
  9. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_branches.py +239 -0
  10. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_cli_dispatch.py +25 -4
  11. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_context.py +3 -1
  12. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_graph.py +48 -9
  13. witan_code-0.10.0/tests/test_identity.py +143 -0
  14. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_indexer_scope.py +170 -24
  15. witan_code-0.10.0/tests/test_ingest.py +220 -0
  16. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_maintenance.py +51 -3
  17. witan_code-0.10.0/tests/test_reaper.py +394 -0
  18. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_remote_proxy.py +1 -1
  19. witan_code-0.10.0/tests/test_remote_store.py +342 -0
  20. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_server.py +2 -1
  21. witan_code-0.10.0/tests/test_store.py +366 -0
  22. witan_code-0.10.0/tests/test_views.py +218 -0
  23. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/bridge.py +25 -14
  24. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/cli.py +213 -62
  25. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/config.py +114 -3
  26. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/context.py +16 -9
  27. witan_code-0.10.0/witan_code/graph.py +248 -0
  28. witan_code-0.10.0/witan_code/identity.py +106 -0
  29. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/indexer.py +33 -19
  30. witan_code-0.10.0/witan_code/ingest.py +340 -0
  31. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries/code_read.gq +14 -0
  32. witan_code-0.10.0/witan_code/reaper.py +224 -0
  33. witan_code-0.10.0/witan_code/remote/store.py +264 -0
  34. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/server.py +252 -43
  35. witan_code-0.10.0/witan_code/store.py +618 -0
  36. witan_code-0.10.0/witan_code/views.py +177 -0
  37. witan_code-0.9.0/docs/BRANCH_INDEXING.md +0 -199
  38. witan_code-0.9.0/tests/test_store.py +0 -112
  39. witan_code-0.9.0/witan_code/graph.py +0 -145
  40. witan_code-0.9.0/witan_code/store.py +0 -202
  41. {witan_code-0.9.0 → witan_code-0.10.0}/.gitignore +0 -0
  42. {witan_code-0.9.0 → witan_code-0.10.0}/config/claude.json +0 -0
  43. {witan_code-0.9.0 → witan_code-0.10.0}/config/copilot.json +0 -0
  44. {witan_code-0.9.0 → witan_code-0.10.0}/config/pi.json +0 -0
  45. {witan_code-0.9.0 → witan_code-0.10.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
  46. {witan_code-0.9.0 → witan_code-0.10.0}/docs/PACKAGE_MAP.md +0 -0
  47. {witan_code-0.9.0 → witan_code-0.10.0}/docs/STAGE2_STITCHING.md +0 -0
  48. {witan_code-0.9.0 → witan_code-0.10.0}/docs/SYMBOL_FORMAT.md +0 -0
  49. {witan_code-0.9.0 → witan_code-0.10.0}/docs/SYMBOL_TABLE.md +0 -0
  50. {witan_code-0.9.0 → witan_code-0.10.0}/install.sh +0 -0
  51. {witan_code-0.9.0 → witan_code-0.10.0}/tests/__init__.py +0 -0
  52. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_bridge.py +0 -0
  53. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_cli_hooks.py +0 -0
  54. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_cli_output_format.py +0 -0
  55. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_config.py +0 -0
  56. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_config_targets.py +0 -0
  57. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_crossrepo.py +0 -0
  58. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_edges.py +0 -0
  59. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_elicit.py +0 -0
  60. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_enrichment.py +0 -0
  61. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_hooks.py +0 -0
  62. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_indexer.py +0 -0
  63. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_languages.py +0 -0
  64. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_package_map.py +0 -0
  65. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_repo.py +0 -0
  66. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_setup.py +0 -0
  67. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_stitch.py +0 -0
  68. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_symbol_table.py +0 -0
  69. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_tasks.py +0 -0
  70. {witan_code-0.9.0 → witan_code-0.10.0}/tests/test_visualize.py +0 -0
  71. {witan_code-0.9.0 → witan_code-0.10.0}/uv.lock +0 -0
  72. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/__init__.py +0 -0
  73. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/__main__.py +0 -0
  74. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/bridge_extractors.py +0 -0
  75. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/edges.py +0 -0
  76. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/elicit.py +0 -0
  77. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/extensions/pi/codegraph.ts +0 -0
  78. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/hooks.py +0 -0
  79. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/maintenance.py +0 -0
  80. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/output.py +0 -0
  81. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/package_map.py +0 -0
  82. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries/bridge.gq +0 -0
  83. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries/code_mutations.gq +0 -0
  84. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries/delete.gq +0 -0
  85. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/bash.scm +0 -0
  86. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/hcl.scm +0 -0
  87. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/python.scm +0 -0
  88. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/sql.scm +0 -0
  89. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/typescript.scm +0 -0
  90. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/queries_ts/yaml.scm +0 -0
  91. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/remote/__init__.py +0 -0
  92. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/remote/oidc.py +0 -0
  93. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/remote/proxy.py +0 -0
  94. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/repo.py +0 -0
  95. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/schema/bridge-schema.pg +0 -0
  96. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/schema/code-schema.pg +0 -0
  97. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/setup.py +0 -0
  98. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/skills/witan-code/SKILL.md +0 -0
  99. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/stitch.py +0 -0
  100. {witan_code-0.9.0 → witan_code-0.10.0}/witan_code/visualize.py +0 -0
@@ -6,10 +6,130 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
7
  a MINOR bump may include breaking changes).
8
8
 
9
+ ## [0.10.0] - 2026-08-01
10
+
11
+ ### Added
12
+
13
+ - **Index onto a cluster code graph from outside the cluster —
14
+ `code_transport = "mcp"` (ADR-0005 path c).** The omnigraph-server holding
15
+ the code graphs is ClusterIP-only and stays that way, so until now a
16
+ developer's checkout could reach it only through `kubectl port-forward`.
17
+ Set the transport (env `WITAN_CODE_TRANSPORT`) and every store operation
18
+ travels to the deployed witan MCP endpoint — the one exposed boundary —
19
+ which performs it against the cluster graph **as the caller**: it resolves
20
+ the actor from the validated JWT, looks up that actor's own omnigraph token,
21
+ and applies the branch-view ownership guard server-side. The client keeps
22
+ everything that needs a working tree; `indexer`/`bridge` are unchanged, and
23
+ `RemoteStoreClient` stands in for an `OmnigraphClient`. It holds one
24
+ connection open for the run rather than one per call, since an index is
25
+ thousands of store operations, and reconnects once on a dropped one.
26
+ Deliberate consequences: a write through this route can only target a view
27
+ the caller's own actor owns, and can never target the shared
28
+ default-branch view — that one's writer is the CI indexer, in-cluster over
29
+ `code_server`, which is unchanged. Compaction and view reaping refuse here
30
+ too; they belong to the cluster's own scheduled jobs.
31
+ - **`code_store_*` tools** — the server half of the above: `read`, `mutate`,
32
+ `load`, `open`, `views`, `graphs`, mirroring the store operations the write
33
+ path performs rather than modelling indexing itself, so indexing policy
34
+ stays with the client that has the checkout. Mediated, not arbitrary:
35
+ `query` may only name a query file bundled with the server, and the graph is
36
+ resolved from a repo URI against the server's own configuration. Registered
37
+ **only on a deployment** (`WITAN_OIDC_ISSUER` set; override with
38
+ `WITAN_CODE_STORE_TOOLS`) — a local stdio server writes its stores directly,
39
+ so serving them there would add six machine-facing tools to every agent's
40
+ tool list to serve a caller that cannot exist.
41
+
42
+ - **`witan-code reap-views` — a stale branch-view reaper for the shared graph.**
43
+ With per-writer views on one cluster graph, every developer's every git branch
44
+ gets a view and nothing ever removes one. This sweeps views nobody has written
45
+ in `WITAN_CODE_VIEW_MAX_IDLE_DAYS` (default 14; `0` disables). It is not
46
+ `branches --prune` with a wider scope: prune asks whether *this checkout* still
47
+ has the git branch, which is unanswerable about a store every user writes, and
48
+ it keeps refusing there. This asks the store's own commit log how long ago a
49
+ view was last written. `main` is never reaped (idle by design between merges),
50
+ and neither is a view with no commits of its own — it holds nothing that isn't
51
+ already on its fork point, and omnigraph records no branch-creation time to
52
+ age it by, so reaping it would race the indexer that just made it. Reports by
53
+ default; `--apply` deletes, and refuses on a shared graph unless
54
+ `WITAN_CODE_INDEX_ROLE=ci`. Unparseable `commit list` output raises rather
55
+ than reading as "never written" — `None` is what tells the reaper to leave a
56
+ view alone, so degrading a parse failure to it would turn an omnigraph output
57
+ change into a reaper that reports success forever while sprawl grows. A
58
+ disabled window (`0`) skips the per-view aging entirely instead of scanning
59
+ and discarding, and a graph that cannot be surveyed is reported and
60
+ non-zero-exited without stranding the other stores in the sweep. See
61
+ `docs/BRANCH_INDEXING.md` § Reaping stale views and witan `docs/adr/0006`.
62
+
63
+ ### Changed
64
+
65
+ - **`graph.check_writable` takes `is_remote: bool`, not a `client`.** It only
66
+ ever read that one bit off the client, and the MCP tier serving somebody
67
+ else's write has no client of its own to read it from — the answer there is
68
+ "shared, by construction", since that is the only reason the request exists.
69
+ Taking the bit lets both sides ask the same question.
70
+ - **Cedar can gate `main` vs WIP, but not view ownership** — corrected from
71
+ 0.9.0's claim that one rule could. omnigraph 0.8.1 compiles a bundle rule to a
72
+ bare `permit(...)` with no `when {}` clause, and its only branch predicate is
73
+ the three-valued protected/unprotected scope: there is no branch-name pattern
74
+ and no `principal.actor` to compare a prefix against. The `act-<sub>/` prefix
75
+ is therefore enforced by the client write guard alone. The policy bundle now
76
+ pins this gap with a deliberately-`allow` test case, so an omnigraph release
77
+ that closes it fails the build instead of passing unnoticed.
78
+
79
+ - **Requires `witan-core>=0.7`.** The mtime-stamped schema re-apply
80
+ (`_schema_apply` / `_schema_apply_if_changed` / `_schema_stamp` in
81
+ `witan_code/store.py`) moved up into `witan_core.omnigraph` as
82
+ `schema_apply` / `schema_apply_if_changed` / `schema_stamp_path`, so
83
+ witan-council can pick up additive schema changes on an existing store the
84
+ same way. No behavior change here — `ensure_store` and `ensure_bridge_store`
85
+ call the shared functions with the same arguments — but the floor moves,
86
+ because resolving witan-core 0.6 would now fail at import.
87
+
9
88
  ## [0.9.0] - 2026-07-31
10
89
 
11
90
  ### Added
12
91
 
92
+ - **Branch views are namespaced per writer, and the purge follows view
93
+ ownership.** A git branch is not a unique key for an index: two checkouts on
94
+ `feature-x` — two developers, one developer in two worktrees, an agent and
95
+ its human — are two working trees, and a view named for the branch alone
96
+ meant the second writer silently overwrote the first with a different
97
+ uncommitted state. A view is now named `[<actor>/]<branch>` on a per-repo
98
+ graph and `[<actor>/]<repo-slug>/<branch>` on the bridge, where `<actor>` is
99
+ the ADR-0004 `act-<sub>` id resolved from the `witan login` session (shared
100
+ derivation with the deployed server, `witan_core.identity`; never `$USER`,
101
+ which is not what the cluster's tokens and Cedar policies are written
102
+ against). Set `WITAN_ACTOR`, or `actor` on a `[targets.<name>]` block, for a
103
+ writer with no interactive login. The actor comes first in both schemes on
104
+ purpose: ownership is then a *prefix*, so one comparison, one reaper sweep,
105
+ and one Cedar rule cover both stores.
106
+
107
+ Isolation did not cost visibility, which is the whole reason branch views
108
+ live on the shared graph: `code_indexed_branches(branch=<git branch>)` (CLI:
109
+ `witan code branches --branch <b>`) lists every writer's view of a branch
110
+ with its owner, and any listed view name goes straight back as `branch=` to
111
+ `code_find_definition` / `code_search_symbol` / `code_symbols_in_file`.
112
+ Default reads follow the checkout's branch to *this* actor's view first,
113
+ then any other writer's, then `main`.
114
+
115
+ `graph.owns_view` is now the single predicate behind both `check_writable`
116
+ and `indexer._may_purge`, replacing two separate approximations of the same
117
+ question: a local store has one user who is its writer, CI owns the shared
118
+ default view, and every actor owns its own branch views. A developer may
119
+ therefore purge their own branch view again — under the old "remote and not
120
+ the designated writer" rule they could not, so files they had deleted
121
+ lingered in their own view. Writing a view owned by another actor, or an
122
+ un-owned branch view, is refused on a shared graph. Purely local use is
123
+ unchanged: no identity, no prefix, no migration, and no login needed to
124
+ index offline. `branches --prune` remains refused against a shared graph —
125
+ no client can tell whose views are live. See
126
+ [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md#per-writer-branch-views).
127
+
128
+ **Breaking (tool surface):** `code_indexed_branches` returns
129
+ `{repo, views: [{view, branch, actor}]}` instead of
130
+ `{repo, branches: [str]}`, and no longer lists `main` (the default view is
131
+ not an in-flight branch view).
132
+
13
133
  - **`WITAN_CODE_INDEX_ROLE` — an explicit writer role for the shared
14
134
  default-branch view.** On the deployed cluster a per-repo code graph is one
15
135
  graph for the whole team, and its `main` view — the one every reader falls
@@ -28,9 +148,9 @@ a MINOR bump may include breaking changes).
28
148
  views stay writable by anyone: they are branch-scoped, so in-flight work
29
149
  never lands on the shared view. That exemption is deliberate — per-user
30
150
  branch views live *on* the shared graph, so isolated agents can see each
31
- other's work as it happens. Two follow-ups that decision requires
151
+ other's work as it happens. The two follow-ups that decision required
32
152
  (namespacing views per writer, and re-scoping the purge to "this actor owns
33
- the view being written") are noted in the doc and not in this change. See
153
+ the view being written") landed in the entry above. See
34
154
  [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view).
35
155
 
36
156
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.9.0
3
+ Version: 0.10.0
4
4
  Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
5
  Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
6
  Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -25,7 +25,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
25
25
  Requires-Dist: tree-sitter-typescript<0.24,>=0.23
26
26
  Requires-Dist: tree-sitter-yaml<0.8,>=0.7
27
27
  Requires-Dist: tree-sitter<0.26,>=0.25
28
- Requires-Dist: witan-core[cli,remote]<1,>=0.6
28
+ Requires-Dist: witan-core[cli,remote]<1,>=0.7
29
29
  Provides-Extra: tasks
30
30
  Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
31
31
  Description-Content-Type: text/markdown
@@ -333,11 +333,15 @@ symlink alternative:
333
333
 
334
334
  | Variable | Default | Purpose |
335
335
  |----------|---------|---------|
336
- | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores |
336
+ | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores. Unused when `WITAN_CODE_SERVER` is set |
337
+ | `WITAN_CODE_SERVER` | — | base URL of the deployed omnigraph-server holding the code graphs. Set, every code graph is a graph on that server (`--server <url> --graph code-<repo>`) instead of a local directory. Reachable from inside the cluster only — intended for CI/in-cluster indexers, not laptops. See [Shared cluster graphs](#shared-cluster-graphs) |
338
+ | `WITAN_CODE_TOKEN` | — | bearer token presented to `WITAN_CODE_SERVER`. Per-actor: the server resolves the writer from it |
339
+ | `WITAN_CODE_TRANSPORT` | `direct` | how a cluster code graph is reached. `mcp` writes through the deployed witan MCP endpoint (`WITAN_REMOTE_URL`) instead of addressing the omnigraph-server — the supported path from outside the cluster. See [Writing through the MCP tier](#writing-through-the-mcp-tier) |
337
340
  | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
338
341
  | `WITAN_REPO` | — | override the detected repo slug |
339
342
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
340
343
  | `WITAN_CODE_INDEX_ROLE` | `client` | `ci` designates this process the writer of a shared graph's default-branch view. Only meaningful against a shared cluster graph; local stores are unaffected. See [Branch indexing](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view) |
344
+ | `WITAN_ACTOR` | derived from the `witan login` session | the identity that owns the branch views this process writes; an `act-…` id or a raw OIDC `sub`. For a non-interactive writer (CI, a maintenance job). See [Branch indexing](docs/BRANCH_INDEXING.md#per-writer-branch-views) |
341
345
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
342
346
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
343
347
  | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
@@ -351,6 +355,95 @@ and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
351
355
  at `<dir>/_bridge.omni` and is created lazily on the first index that yields any
352
356
  bindings.
353
357
 
358
+ ### Shared cluster graphs
359
+
360
+ Set `code_server` (env `WITAN_CODE_SERVER`) and each repo's code graph is
361
+ instead a graph on the deployed omnigraph-server, addressed as `--server <url>
362
+ --graph <id>` with the id from `witan_code.config.graph_id()` — e.g.
363
+ `https://github.com/mitodl/ol-django` → `code-github-com-mitodl-ol-django`.
364
+ The bridge graph is the fixed `code-bridge`. That id function is a contract
365
+ shared byte-for-byte with ol-infrastructure's provisioning
366
+ (`applications/omnigraph/data_tier.py`), which is what *declares* the graphs
367
+ and applies their schema; this client never creates one, and indexing a repo
368
+ the cluster has no graph for fails immediately with the id it expected and the
369
+ ids the server actually serves.
370
+
371
+ This is the **data tier** and is independent of `remote_url`
372
+ ([Remote mode](#remote-mode)), which routes read *tools* through a deployed
373
+ witan MCP endpoint. Indexing needs a git checkout, so the indexer always runs
374
+ locally; `code_server` only changes where it writes. Either tier can be remote
375
+ without the other.
376
+
377
+ > **Who this is for.** `code_server` addresses the omnigraph-server
378
+ > *directly*, which only works from inside the cluster — the data tier is a
379
+ > ClusterIP service with no external route, while the witan MCP tier is the
380
+ > one that is publicly exposed. So:
381
+ >
382
+ > - **CI / in-cluster indexers** use `code_server` as documented here.
383
+ > - **Everyone else** sets `code_transport = "mcp"` and writes through the
384
+ > deployed witan endpoint — see below.
385
+ >
386
+ > Do not configure `code_server` on a laptop: it needs a `kubectl
387
+ > port-forward` and is not the supported path. Reads are unaffected either way.
388
+
389
+ ### Writing through the MCP tier
390
+
391
+ `code_transport = "mcp"` (env `WITAN_CODE_TRANSPORT`) makes the deployed witan
392
+ endpoint — the same `remote_url` the read commands already use — the address
393
+ of every code graph. It is the supported way to index onto the cluster from a
394
+ machine that is not in it:
395
+
396
+ ```toml
397
+ [targets.hosted]
398
+ remote_url = "https://witan.example.org/mcp"
399
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
400
+ code_transport = "mcp"
401
+ match_orgs = ["ol-platform-engineering"]
402
+ ```
403
+
404
+ Then `witan-code index` runs exactly as it always has — parsing your working
405
+ tree locally, because that is the part that needs a checkout — and its store
406
+ operations travel to the deployment, which performs them against the cluster
407
+ graph *as you*: it resolves your actor from the JWT `witan-code login`
408
+ obtained and looks up your own omnigraph token (ADR-0004). Nothing about
409
+ your local process decides who the write is attributed to.
410
+
411
+ Two consequences follow from that, and they are the point rather than
412
+ limitations:
413
+
414
+ - **You can only write views you own.** The deployment applies the same
415
+ ownership rule the client does (`[<actor>/]<branch>`, see
416
+ [Branch indexing](docs/BRANCH_INDEXING.md)) — but against the actor in your
417
+ token, so naming someone else's view is refused rather than honoured.
418
+ - **You cannot write the shared default-branch view through this path at
419
+ all.** Its single writer is the CI indexer, which runs in-cluster. Index a
420
+ non-default git branch, which is what a developer is doing anyway.
421
+
422
+ Store maintenance (`optimize`/`cleanup`) and stale-view reaping are refused
423
+ here too: they run inside the cluster against the storage root, not from
424
+ whichever machine indexed last.
425
+
426
+ Requires `remote_url` + `oidc_issuer` (a bare `code_transport = "mcp"` with no
427
+ endpoint is a configuration error, not a silent fall back to a local store).
428
+ The indexer holds one connection open for the run rather than one per store
429
+ operation; the per-prompt hook block, being a fresh process each time, pays a
430
+ connection and a round trip or two per prompt, and stays silent if the
431
+ deployment is unreachable or the login has expired.
432
+
433
+ Two things a cluster graph cannot answer, and doesn't pretend to:
434
+
435
+ - **Size and last-modified** are properties of a store directory. `witan-code
436
+ repos` and `code_indexed_repos` report `?`/null for both rather than a
437
+ plausible zero; `files` stays real, since it is a query.
438
+ - **Compaction.** `witan-code optimize`/`cleanup` refuse a cluster graph —
439
+ they are direct-storage commands, and compacting the shared storage root is
440
+ the cluster's own scheduled job, not every client's at the end of every
441
+ session.
442
+
443
+ Who may write which view on a shared graph is a separate question, answered by
444
+ `index_role` and the per-writer view naming — see
445
+ [Branch indexing](docs/BRANCH_INDEXING.md).
446
+
354
447
  ### config.toml
355
448
 
356
449
  witan-code reads the same `config.toml` as witan (witan-council) — a global
@@ -360,8 +453,9 @@ CLI `--target` flag yet), or auto-detection against the current
360
453
  repo/checkout (`match_paths` > `match_repos` > `match_hosts` > `match_orgs`
361
454
  — see witan's README/`witan/config.py` docstring for the full precedence).
362
455
  Because the file is shared, one target block can carry witan's
363
- `server`/`graph`/`token` alongside `code_dir` under
364
- the same name — each server reads only the fields it knows:
456
+ `server`/`graph`/`token` alongside witan-code's `code_dir` (or
457
+ `code_server`/`code_token`) under the same name — each server reads only the
458
+ fields it knows:
365
459
 
366
460
  ```toml
367
461
  [targets.work]
@@ -369,6 +463,14 @@ server = "http://witan.internal:8080" # witan (witan-council)
369
463
  code_dir = "/mnt/work/witan-code" # witan-code
370
464
  match_orgs = ["myorg"]
371
465
 
466
+ [targets.cluster]
467
+ # The shared data tier: code graphs live on the deployed omnigraph-server,
468
+ # one `code-<repo>` graph each. For a CI or in-cluster indexer — the server is
469
+ # not reachable from a laptop. See Shared cluster graphs.
470
+ code_server = "https://omnigraph.example.org"
471
+ code_token = "..."
472
+ match_orgs = ["ol-platform-engineering"]
473
+
372
474
  [targets.hosted]
373
475
  # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
374
476
  remote_url = "https://witan.example.org/mcp"
@@ -417,7 +519,7 @@ graph):
417
519
  | Tool | Returns |
418
520
  |------|---------|
419
521
  | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
420
- | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
522
+ | `code_indexed_branches(branch=None)` | the in-flight branch views each repo's store carries, and who owns each; pass a git branch to see every writer's view of it |
421
523
 
422
524
  ## CLI
423
525
 
@@ -428,10 +530,13 @@ graph):
428
530
  - `index [PATH]` — incremental; skips files whose content hash is unchanged.
429
531
  - `reindex [PATH]` — force rebuild a path.
430
532
  - `repos` — list all indexed repos with file count, symbol count, and store size.
431
- - `branches [--prune]` — list omnigraph branches per store; `--prune` deletes
432
- the current repo's store branches whose git branch is gone (plus
433
- `_detached`). Non-default git branches index onto same-named omnigraph
434
- branches so in-flight work never overwrites the shared `main` view — see
533
+ - `branches [--branch B] [--prune]` — list the in-flight branch views per
534
+ store; `--branch` shows every writer's view of one git branch (how you find
535
+ a teammate's WIP — pass a listed view name to a read command's `--branch`),
536
+ `--prune` deletes the current repo's views whose git branch is gone (plus
537
+ `_detached`). A non-default git branch indexes onto its own view, named for
538
+ its writer as well as the branch, so in-flight work neither overwrites the
539
+ shared `main` view nor another checkout of the same branch — see
435
540
  [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md).
436
541
  - `deps [--kind K] [--repo SUBSTR] [--html PATH] [--open-browser]` —
437
542
  visualize cross-repo dependencies from the bridge store. Prints a Rich
@@ -301,11 +301,15 @@ symlink alternative:
301
301
 
302
302
  | Variable | Default | Purpose |
303
303
  |----------|---------|---------|
304
- | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores |
304
+ | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores. Unused when `WITAN_CODE_SERVER` is set |
305
+ | `WITAN_CODE_SERVER` | — | base URL of the deployed omnigraph-server holding the code graphs. Set, every code graph is a graph on that server (`--server <url> --graph code-<repo>`) instead of a local directory. Reachable from inside the cluster only — intended for CI/in-cluster indexers, not laptops. See [Shared cluster graphs](#shared-cluster-graphs) |
306
+ | `WITAN_CODE_TOKEN` | — | bearer token presented to `WITAN_CODE_SERVER`. Per-actor: the server resolves the writer from it |
307
+ | `WITAN_CODE_TRANSPORT` | `direct` | how a cluster code graph is reached. `mcp` writes through the deployed witan MCP endpoint (`WITAN_REMOTE_URL`) instead of addressing the omnigraph-server — the supported path from outside the cluster. See [Writing through the MCP tier](#writing-through-the-mcp-tier) |
305
308
  | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
306
309
  | `WITAN_REPO` | — | override the detected repo slug |
307
310
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
308
311
  | `WITAN_CODE_INDEX_ROLE` | `client` | `ci` designates this process the writer of a shared graph's default-branch view. Only meaningful against a shared cluster graph; local stores are unaffected. See [Branch indexing](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view) |
312
+ | `WITAN_ACTOR` | derived from the `witan login` session | the identity that owns the branch views this process writes; an `act-…` id or a raw OIDC `sub`. For a non-interactive writer (CI, a maintenance job). See [Branch indexing](docs/BRANCH_INDEXING.md#per-writer-branch-views) |
309
313
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
310
314
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
311
315
  | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
@@ -319,6 +323,95 @@ and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
319
323
  at `<dir>/_bridge.omni` and is created lazily on the first index that yields any
320
324
  bindings.
321
325
 
326
+ ### Shared cluster graphs
327
+
328
+ Set `code_server` (env `WITAN_CODE_SERVER`) and each repo's code graph is
329
+ instead a graph on the deployed omnigraph-server, addressed as `--server <url>
330
+ --graph <id>` with the id from `witan_code.config.graph_id()` — e.g.
331
+ `https://github.com/mitodl/ol-django` → `code-github-com-mitodl-ol-django`.
332
+ The bridge graph is the fixed `code-bridge`. That id function is a contract
333
+ shared byte-for-byte with ol-infrastructure's provisioning
334
+ (`applications/omnigraph/data_tier.py`), which is what *declares* the graphs
335
+ and applies their schema; this client never creates one, and indexing a repo
336
+ the cluster has no graph for fails immediately with the id it expected and the
337
+ ids the server actually serves.
338
+
339
+ This is the **data tier** and is independent of `remote_url`
340
+ ([Remote mode](#remote-mode)), which routes read *tools* through a deployed
341
+ witan MCP endpoint. Indexing needs a git checkout, so the indexer always runs
342
+ locally; `code_server` only changes where it writes. Either tier can be remote
343
+ without the other.
344
+
345
+ > **Who this is for.** `code_server` addresses the omnigraph-server
346
+ > *directly*, which only works from inside the cluster — the data tier is a
347
+ > ClusterIP service with no external route, while the witan MCP tier is the
348
+ > one that is publicly exposed. So:
349
+ >
350
+ > - **CI / in-cluster indexers** use `code_server` as documented here.
351
+ > - **Everyone else** sets `code_transport = "mcp"` and writes through the
352
+ > deployed witan endpoint — see below.
353
+ >
354
+ > Do not configure `code_server` on a laptop: it needs a `kubectl
355
+ > port-forward` and is not the supported path. Reads are unaffected either way.
356
+
357
+ ### Writing through the MCP tier
358
+
359
+ `code_transport = "mcp"` (env `WITAN_CODE_TRANSPORT`) makes the deployed witan
360
+ endpoint — the same `remote_url` the read commands already use — the address
361
+ of every code graph. It is the supported way to index onto the cluster from a
362
+ machine that is not in it:
363
+
364
+ ```toml
365
+ [targets.hosted]
366
+ remote_url = "https://witan.example.org/mcp"
367
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
368
+ code_transport = "mcp"
369
+ match_orgs = ["ol-platform-engineering"]
370
+ ```
371
+
372
+ Then `witan-code index` runs exactly as it always has — parsing your working
373
+ tree locally, because that is the part that needs a checkout — and its store
374
+ operations travel to the deployment, which performs them against the cluster
375
+ graph *as you*: it resolves your actor from the JWT `witan-code login`
376
+ obtained and looks up your own omnigraph token (ADR-0004). Nothing about
377
+ your local process decides who the write is attributed to.
378
+
379
+ Two consequences follow from that, and they are the point rather than
380
+ limitations:
381
+
382
+ - **You can only write views you own.** The deployment applies the same
383
+ ownership rule the client does (`[<actor>/]<branch>`, see
384
+ [Branch indexing](docs/BRANCH_INDEXING.md)) — but against the actor in your
385
+ token, so naming someone else's view is refused rather than honoured.
386
+ - **You cannot write the shared default-branch view through this path at
387
+ all.** Its single writer is the CI indexer, which runs in-cluster. Index a
388
+ non-default git branch, which is what a developer is doing anyway.
389
+
390
+ Store maintenance (`optimize`/`cleanup`) and stale-view reaping are refused
391
+ here too: they run inside the cluster against the storage root, not from
392
+ whichever machine indexed last.
393
+
394
+ Requires `remote_url` + `oidc_issuer` (a bare `code_transport = "mcp"` with no
395
+ endpoint is a configuration error, not a silent fall back to a local store).
396
+ The indexer holds one connection open for the run rather than one per store
397
+ operation; the per-prompt hook block, being a fresh process each time, pays a
398
+ connection and a round trip or two per prompt, and stays silent if the
399
+ deployment is unreachable or the login has expired.
400
+
401
+ Two things a cluster graph cannot answer, and doesn't pretend to:
402
+
403
+ - **Size and last-modified** are properties of a store directory. `witan-code
404
+ repos` and `code_indexed_repos` report `?`/null for both rather than a
405
+ plausible zero; `files` stays real, since it is a query.
406
+ - **Compaction.** `witan-code optimize`/`cleanup` refuse a cluster graph —
407
+ they are direct-storage commands, and compacting the shared storage root is
408
+ the cluster's own scheduled job, not every client's at the end of every
409
+ session.
410
+
411
+ Who may write which view on a shared graph is a separate question, answered by
412
+ `index_role` and the per-writer view naming — see
413
+ [Branch indexing](docs/BRANCH_INDEXING.md).
414
+
322
415
  ### config.toml
323
416
 
324
417
  witan-code reads the same `config.toml` as witan (witan-council) — a global
@@ -328,8 +421,9 @@ CLI `--target` flag yet), or auto-detection against the current
328
421
  repo/checkout (`match_paths` > `match_repos` > `match_hosts` > `match_orgs`
329
422
  — see witan's README/`witan/config.py` docstring for the full precedence).
330
423
  Because the file is shared, one target block can carry witan's
331
- `server`/`graph`/`token` alongside `code_dir` under
332
- the same name — each server reads only the fields it knows:
424
+ `server`/`graph`/`token` alongside witan-code's `code_dir` (or
425
+ `code_server`/`code_token`) under the same name — each server reads only the
426
+ fields it knows:
333
427
 
334
428
  ```toml
335
429
  [targets.work]
@@ -337,6 +431,14 @@ server = "http://witan.internal:8080" # witan (witan-council)
337
431
  code_dir = "/mnt/work/witan-code" # witan-code
338
432
  match_orgs = ["myorg"]
339
433
 
434
+ [targets.cluster]
435
+ # The shared data tier: code graphs live on the deployed omnigraph-server,
436
+ # one `code-<repo>` graph each. For a CI or in-cluster indexer — the server is
437
+ # not reachable from a laptop. See Shared cluster graphs.
438
+ code_server = "https://omnigraph.example.org"
439
+ code_token = "..."
440
+ match_orgs = ["ol-platform-engineering"]
441
+
340
442
  [targets.hosted]
341
443
  # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
342
444
  remote_url = "https://witan.example.org/mcp"
@@ -385,7 +487,7 @@ graph):
385
487
  | Tool | Returns |
386
488
  |------|---------|
387
489
  | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
388
- | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
490
+ | `code_indexed_branches(branch=None)` | the in-flight branch views each repo's store carries, and who owns each; pass a git branch to see every writer's view of it |
389
491
 
390
492
  ## CLI
391
493
 
@@ -396,10 +498,13 @@ graph):
396
498
  - `index [PATH]` — incremental; skips files whose content hash is unchanged.
397
499
  - `reindex [PATH]` — force rebuild a path.
398
500
  - `repos` — list all indexed repos with file count, symbol count, and store size.
399
- - `branches [--prune]` — list omnigraph branches per store; `--prune` deletes
400
- the current repo's store branches whose git branch is gone (plus
401
- `_detached`). Non-default git branches index onto same-named omnigraph
402
- branches so in-flight work never overwrites the shared `main` view — see
501
+ - `branches [--branch B] [--prune]` — list the in-flight branch views per
502
+ store; `--branch` shows every writer's view of one git branch (how you find
503
+ a teammate's WIP — pass a listed view name to a read command's `--branch`),
504
+ `--prune` deletes the current repo's views whose git branch is gone (plus
505
+ `_detached`). A non-default git branch indexes onto its own view, named for
506
+ its writer as well as the branch, so in-flight work neither overwrites the
507
+ shared `main` view nor another checkout of the same branch — see
403
508
  [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md).
404
509
  - `deps [--kind K] [--repo SUBSTR] [--html PATH] [--open-browser]` —
405
510
  visualize cross-repo dependencies from the bridge store. Prints a Rich