Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(workspace): architecture page for the multi-repo workspace layer (#4509)
Raghav Chamadiya66bc2f85c94d
diff --git a/docs/architecture/README.md b/docs/architecture/README.mdindex fb575cc10..e7a1a6aa9 100644--- a/docs/architecture/README.md+++ b/docs/architecture/README.md@@ -15,6 +15,7 @@ curious; you don't need them to *use* repowise (start with| [security.md](security.md) | Security signals internals: per-kind matching rules, placeholder skipping, baseline keys, and the JS/TS precision checks || [test-intelligence.md](test-intelligence.md) | The inferred test tier: call and import walks, their measured precision and recall, the resolution-origin filter, and why nothing is stored || [language-support.md](language-support.md) | The language pipeline internals and the step-by-step recipe for adding a new language |+| [workspace.md](workspace.md) | The multi-repo workspace layer: per-repo contract extraction, matching, the system graph and its evidence state, artifacts and incremental rules, and the recipes for adding a contract dialect or a service-name source || [forges.md](forges.md) | Git host support: the forges package, its invariants, and the recipes for adding a host or a CI system || [agent-platform.md](agent-platform.md) | Agent identities, provider specs, integration targets and adapters, and the recipes for adding an agent integration or an agent CLI indexing backend || [graph-algorithms.md](graph-algorithms.md) | The graph algorithms (PageRank, betweenness, Tarjan SCC, Leiden/Louvain community detection, shortest path) with the math and complexity |diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.mdindex ce931f749..eea57aa6e 100644--- a/docs/architecture/language-support.md+++ b/docs/architecture/language-support.md@@ -1317,7 +1317,8 @@ mislead the masker.| **Data** | DDL `CREATE`/`ALTER`, Alembic `op.create_table`, Laravel `Schema::create`/`Schema::table`, Knex migrations, ORM models (SQLAlchemy, SQLModel, Django, JPA, EF Core, ActiveRecord, Eloquent, Prisma, TypeORM, Sequelize, Drizzle) | SQL string literals in app code (sqlglot-parsed, verb-anchored-regex fallback), Laravel `DB::table`, Knex queries |See [docs/scale/WORKSPACES.md](../scale/WORKSPACES.md) for the user-facing-workspace guide.+workspace guide, and [workspace.md](workspace.md) for the layer's pipeline,+registries and contributor recipes.---diff --git a/docs/architecture/workspace.md b/docs/architecture/workspace.mdnew file mode 100644index 000000000..97de1a955--- /dev/null+++ b/docs/architecture/workspace.md@@ -0,0 +1,430 @@+# Workspace layer internals++Contributor reference for the multi-repo workspace layer: how contracts are read,+matched and folded into one system graph, what each artifact stores, and how to+extend it. For what users run and see, start with+[scale/WORKSPACES.md](../scale/WORKSPACES.md); for why a given link did or did not+form, [reference/WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md).++All code lives in `packages/core/src/repowise/core/workspace/` unless a path says+otherwise.++## What the layer does++Each workspace repo is indexed on its own, exactly as in single-repo mode, into its+own `.repowise/wiki.db`. The workspace layer runs after those indexes and adds what+no single repo can see: contracts one repo provides and another consumes, package+dependencies between repos, co-change across repos, and a service-level graph that+cycles, metrics, conformance, blast radius and test impact all read.++It reuses ingestion instead of re-deriving it:++| Reused | From | Used for |+|--------|------|----------|+| `FileTraverser` | `ingestion/traverser.py` | The extraction walk, so the scanned set honours `.gitignore` and prunes nested repos like the repo's own index |+| `walk_repo` | `fs_walk.py` | Service-boundary detection and the service-name walk |+| The symbol table in `wiki.db` | `repo_index.py` (`RepoIndex`, `WorkspaceIndex`) | Index-backed routes and typed clients (`extractors/from_index.py`, `extractors/http/index_clients.py`), binding contracts to symbol ids, signature schemas |+| `mask_source` | `ingestion/source_mask.py` | Comment masks for Python and JS/TS |+| `mask_comments_and_strings` | `analysis/security/masking.py` | Comment masks for C-like languages, and the network probe |+| `has_working_tree_changes` | `ingestion/change_detector.py` | Whether a repo's stored contracts can be reused |+| Test reachability | `analysis/test_reachability.py`, `analysis/test_selection.py` | Cross-repo test impact |++The per-repo graph (files, symbols, call edges) is never merged across repos. The+workspace graph is one level up: nodes are services, edges are contracts, package+dependencies and co-changes. Its trust model follows the per-repo rule in+[GRAPH.md](../layers/GRAPH.md#every-edge-says-how-it-got-there): every contract and+link names how it was made, from a closed vocabulary with one confidence per value.++## Module map++| Module | Role |+|--------|------|+| `scanner.py` | Finds git repositories under a directory for `repowise init` |+| `config.py` | `.repowise-workspace.yaml`: repos, `ContractConfig` (each field declares its stage), `ConformanceConfig`, `analysis_fingerprint` |+| `update/` | The workspace update: stale-repo selection and per-repo updates (`workspace_pass.py`, `repo.py`), then the cross-repo phases (`phases.py`) |+| `extractors/` | Contract dialects per type (`http/`, `grpc/`, `topic/`, `socket/`, `data/`), plus `openapi.py`, `masstransit.py`, `service_boundary.py`; layout in [language-support.md](language-support.md#workspace-contract-extraction) |+| `extractors/base.py`, `extractors/dialect.py` | The one walk, `ScanContext` (per-file gate memo and comment mask), `run_dialect`, `DialectExtractor` |+| `code_api.py` | A library's published surface as a `code` contract |+| `origins.py` | `ContractOrigin` and `LinkStrategy`, each with one confidence per value |+| `service_names/` | The service-name map: one module per config source, registry in `__init__.py` |+| `matching/` | The shared exact pass plus per-type passes (`http.py`, `topic.py`, `data.py`), registered in `MATCHERS` |+| `contracts.py` | `run_contract_extraction`, `ContractStore`, reuse and fingerprints, `CONTRACTS_VERSION` |+| `manifests.py`, `maven_dependencies.py`, `cross_repo.py` | Package dependencies by ecosystem, cross-repo co-change, the overlay |+| `system_graph.py` | `build_system_graph`, `SystemGraph.adjacency()` |+| `graph_evidence.py` | `measured` / `partial` / `insufficient` for one graph |+| `network_probe.py` | Counts files that call out but yielded no consumer contract |+| `diagnostics.py` | Per-repo counts, unmatched reasons, coverage |+| `cycles.py`, `conformance.py`, `architecture_metrics.py`, `blast_radius.py`, `breaking_change.py`, `test_impact.py` | The views over the graph and the links |+| `reads.py` | Read projections shared by REST and MCP |+| `store.py` | `workspace.db`, a derived lookup store rebuilt from each repo's `wiki.db` |++## Pipeline++`repowise update --workspace` (alias `repowise workspace update`) updates stale+repos, then `update/phases.py::run_cross_repo_hooks` runs the cross-repo phases. A+workspace with fewer than two repos runs none, and only repos with a `.repowise/`+index take part.++| Step | Code | Output |+|------|------|--------|+| 1. Service boundaries | `extractors/service_boundary.py`, from manifest markers in `manifests.ECOSYSTEMS` | Boundaries per repo, detected once and passed to extraction and the graph |+| 2a. Co-change and packages | `cross_repo.py::run_cross_repo_analysis` | `cross_repo_edges.json` |+| 2b. Contract extraction and matching (runs alongside 2a) | `contracts.py::run_contract_extraction` | `contracts.json` |+| 3. System graph | `system_graph.py::run_system_graph_build` | `system_graph.json`, diagnostics embedded |+| 4. Breaking changes | `breaking_change.py`, the new store against the one on disk before step 2b | `breaking_changes.json` |+| 5. Conformance and cycles | `conformance.py`, `cycles.py` | `conformance.json` |+| 6. Workspace store | `store.py::refresh_workspace_store` | `workspace.db` |++Architecture metrics, blast radius and test impact are computed on read.++### Per-repo extraction++`_extract_one_repo` walks each repo once, over the union of the enabled extractors'+extensions, and hands the file list to every extractor. Each file becomes one+`ScanContext`. Every dialect runs through `extractors/dialect.py::run_dialect`:++1. **Extension**, then **gate**: the file must hold one of the dialect's `requires`+ tokens. `ScanContext.has_any` memoizes each token per file, so a token named by+ several dialects or table rows is searched for once. A contract file format+ (`.proto`, `.sql`, `.prisma`) declares `EVERY_FILE`.+2. **Extract**: the dialect returns contracts built with `build_contract`, which+ takes an `origin` and sets the confidence from it.+3. **Comment rule**: `run_dialect` drops a contract whose line is only a comment.+ The shared match helpers (`call_sites`, `code_matches`, `outside_comments`,+ `consumer_contracts`) skip a match that starts in a comment, so a commented-out+ decorator or mount sets no state. The mask is built the first time a match asks,+ so a file nothing matched in never pays for it.++`DialectExtractor` drives the topic, socket, gRPC and data types. HTTP keeps its own+`HttpExtractor` because it adds two passes (router mounts collected across files,+then index-backed routes and client calls), and each of its dialects still goes+through `run_dialect`. A dialect whose contracts span files offers `repo_pass()`:+it is handed every gated file, then names its contracts once.++After the dialects, `code_api.py` adds published-package contracts,+`merge_openapi_providers` folds an OpenAPI operation into the code route it+describes, `bind_symbol_ids` binds each contract to a symbol in the repo's index,+and `network_probe.count_unrecognised_call_files` counts the files that call out+with no consumer contract read from them.++### Matching++Matching always runs over the whole merged contract set, never a subset. The first+two steps run in `run_contract_extraction` before `matching.run_matching`; manual+links are appended after it.++1. **Service-name map** (`service_names/`): every source walks each repo once and+ reads only files its gate admits, plus the workspace root's own files. Claims+ settle into one `name -> repo` entry; a name claimed for two repos is left+ unmapped. The sources and their rules are in+ [WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md#service-names).+2. **Target resolution** (`matching/http.py::annotate_consumer_targets`): each HTTP+ consumer's host or base token is resolved, in order, through a+ `contracts.service_bases` entry, a repo alias (also the leading label of an+ internal DNS name such as `catalog.svc.cluster.local`), and the service-name map.+ The consumer's `meta` records `target_repo`, `target_via` (the source) and, for a+ map entry, `target_evidence` (the file). A public dotted host nothing maps is+ `external` and never linked.+3. **Exact pass** (`matching/__init__.py::_exact_pass`): normalized ids, HTTP method+ and gRPC service wildcards included. Strategy `exact_id`, `pattern_matched` for a+ pattern subscription, `service_mapped` when the provider sits in the consumer's+ resolved target. A target the map placed does not fall back to another repo that+ serves the same path (`common.prefer_target_repo`).+4. **Type passes**, in `MATCHERS` order: HTTP `base_resolved_pass`, `candidate_pass`+ (`unique_path`, `ambiguous_path`, `prefix_stripped`) and `service_pass`; topic+ `binding_pass` (`binding_routed`); data `shared_table_pass` (`shared_table`).+5. **Service links**: `service_pass` gives each HTTP consumer whose target is a+ workspace repo, but whose path no provider serves, one `host_only` link with no+ provider file. These live in `ContractStore.service_links`, apart from+ `contract_links`. A target that only equals a repo alias draws none.+6. **Manual links** from `contracts.manual_links` are appended with strategy+ `manual`.++### System graph and its adjacency++`build_system_graph` folds contract links, service links, package dependencies and+co-changes into service nodes and typed edges (`http`, `grpc`, `socket`, `event`,+`db`, `package` are structural; `co_change` is behavioral). Edges sharing source,+target and kind collapse into one weighted edge that keeps the strategy of its+strongest link.++`SystemGraph.adjacency()` is the only place that decides which edges a walk follows:+structural edges in dependency direction by default, `impact=True` for the+blast-radius direction, `behavioral=True` to add co-change both ways. Parallel edges+between one pair stay separate, so a caller can tell an `event` leg+(`ASYNC_EDGE_KINDS`) from a sync one. `cycles.py`, `architecture_metrics.py` and+`blast_radius.py` build no adjacency of their own;+`test_system_graph.py::test_adjacency_is_the_one_view_every_walk_reads` pins its+shape (parallel edges kept, `impact` flips direction, `behavioral` adds co-change+both ways).++### Consumers++| Consumer | Reads | Output |+|----------|-------|--------|+| `cycles.detect_cycles` | `adjacency()` | Cycles with `leg_kinds` per leg and `async_legs`; an event leg still closes a cycle; capped at `MAX_CYCLES` |+| `architecture_metrics.compute_architecture_metrics` | `adjacency()`, `detect_cycles` | Propagation cost, core, roles, 1-10 score |+| `conformance.build_conformance_report` | Structural edges, declared rules | Violations, cycles, `cycles_determined` |+| `blast_radius.cross_repo_blast_radius` | `adjacency(impact=True)`, co-change at `BEHAVIORAL_EDGE_WEIGHT` | Impacted services by distance, `undetermined_targets` |+| `breaking_change` | `contract_links`, previous and new stores | Provider breaks with the consumer files they reach |+| `test_impact.analyze_workspace_test_impact` | `contract_links`, each consumer repo's test reachability from the link's `consumer_symbol_id` | Tests to run, unresolved rows with reasons |+| `diagnostics.build_diagnostics` | Contracts, `contract_links`, extraction stats | Counts, unmatched reasons, weak links, coverage |++Service links reach the graph views (cycles, metrics, conformance, blast radius).+Breaking changes, test impact and diagnostics read `contract_links` only, since a+service link has no provider route.++### Evidence state++`graph_evidence.graph_evidence(graph)` runs once over the graph and returns a state+with named reasons. Each rule is one function in `_RULES`:++| Reason | State |+|--------|-------|+| `too_few_services` | `insufficient` |+| `no_cross_service_edges` | `insufficient` |+| `build_edges_only` (every edge is a `package` edge) | `partial` |+| `isolated_services` | `partial` |+| `repos_without_contracts` (read, yielded nothing) | `partial` |++The state is the worst any reason implies; no reason is `measured`. What each output+does with it:++| Output | `insufficient` | `partial` |+|--------|----------------|-----------|+| Architecture metrics | Score, propagation cost, core size and cycle count are `None`, core members and roles empty; type `undetermined` | Figures computed, reasons attached |+| Conformance, `workspace check` | `cycles_determined: false`; "dependency cycles not determined", exit 0 | "no dependency cycles among the edges detected (partial evidence)" |+| Blast radius | `evidence` attached | `evidence` attached |+| MCP `get_architecture`, `get_blast_radius`, `get_conformance`, REST | Carry the same `evidence` block | Same |++In every state, blast radius lists in `undetermined_targets` each target the walked+adjacency has no edge at, so an empty impact set there reads as not seen.++Test impact reads the links rather than the graph: an empty answer is+`no_contract_links` when the map links nothing and `no_matching_links` when it links+something but not these files. HTTP coverage in diagnostics counts each file the+network probe flagged in its denominator, so a client library no dialect reads+lowers the figure; it is `None` for an artifact written before the probe.++### Persistence++Everything lives in `.repowise-workspace/`:++| File | Holds | Stamp |+|------|-------|-------|+| `contracts.json` | `contracts`, `contract_links`, `service_links`, `service_names`, `extraction_stats`, `repo_provenance` | `CONTRACTS_VERSION`; per repo `head`, `config_fp`, `extracted_at`; the service-name map's `fingerprint` |+| `cross_repo_edges.json` | Co-change pairs, package dependencies, repo summaries | File mtime against each repo's `state.json` |+| `system_graph.json` | Nodes, edges, diagnostics, `repo_provenance` | `version` |+| `breaking_changes.json` | Provider breaks since the previous store | `generated_at` |+| `conformance.json` | Violations, cycles, `evidence` | |+| `analysis_config.json` | The `contracts:` and `conformance:` settings the last analysis ran with | `WorkspaceConfig.analysis_fingerprint()` |+| `member_refresh.json` | One digest per member repo | `update_cmd/member_refresh.py::member_fingerprint` |+| `workspace.db` | Path and symbol lookup, components, recent changes, health, freshness | Each repo's `state.json`; safe to delete |++`member_refresh.py` lives in `packages/cli/src/repowise/cli/commands/update_cmd/`.+Each repo's own `wiki.db` also carries a schema stamp in `PRAGMA user_version`+(`persistence/database.py::schema_stamp`), so opening an unchanged store skips the+schema reconcile.++### Incremental rules++| Change | Re-extracts | Re-matches | Reuses |+|--------|-------------|------------|--------|+| A repo's HEAD moved, its tree is dirty, or upstream marked it changed | That repo | Everything | Every other repo's stored rows |+| An extraction setting (`detect_*`, `exclude_globs`, `contract_project_pattern`), the published-package set or the message-type set | Every repo | Everything | The co-change overlay, when no repo changed |+| A matching setting (`service_bases`, `manual_links`) or a `conformance:` rule | Nothing | Everything | All stored rows; the service-name map when its fingerprint holds |+| `CONTRACTS_VERSION` moved, or no stored contracts | Every repo, once | Everything | Nothing |+| Nothing | Nothing; the cross-repo phases do not run | Nothing | Everything |++Details the table compresses:++- `ContractConfig` fields declare `stage` in field metadata; the extraction+ fingerprint (`_extraction_config_fingerprint`) hashes only extraction settings.+ `test_contract_config.py::test_every_setting_declares_its_stage` fails on a field+ that declares neither.+- Files repowise writes itself (`.claude/CLAUDE.md` and the other managed editor+ files) do not make a tree dirty; a user's edit to one does.+- `WorkspaceIndex.ensure` opens symbol indexes only for re-extracted repos and the+ repos that publish packages they may import.+- The co-change overlay is reused when it covers exactly the current repos and no+ repo was re-indexed after it was written.+- The service-name map's fingerprint covers each repo's HEAD, the workspace root's+ gated files and the registered source names. It is reused only on a run that+ re-extracts no repo.+- A no-change update refreshes read snapshots, editor files and the DB freshness+ stamp only for members whose `member_fingerprint` moved. The digest covers the+ store and its WAL, `state.json`, `config.yaml`, the gitignore stack, the editor+ files, HEAD, the repowise version with the editor generator and templates, and+ the UTC date, so an unchanged repo still refreshes once a day. A configured+ database (`REPOWISE_DB_URL`) and an explicit `--agents-md` always refresh; a+ failed refresh is not stamped.++## Seams and registries++| Registry | Where | An entry declares | Enforced by |+|----------|-------|-------------------|-------------|+| HTTP dialects | `extractors/http/__init__.py` `PROVIDER_DIALECTS`, `CONSUMER_DIALECTS` | `name`, `extensions`, `requires`, `extract` | `test_dialect_registry.py`, `test_extraction_dialect_budget.py` |+| Topic, socket, gRPC, data dialects | `DIALECTS` in `extractors/topic/`, `socket/`, `grpc/`; `PROVIDER_DIALECTS` and `CONSUMER_DIALECTS` in `data/` | The same; a table dialect's rows each declare `requires` and an `origin`, and the dialect's gate is the union of its rows' (`rows_gate`) | The same two, plus `test_origins.py` |+| Contract origins | `origins.py` `ContractOrigin`, `ORIGIN_CONFIDENCE` | One confidence per value | `test_origins.py` |+| Link strategies | `origins.py` `LinkStrategy`, `STRATEGY_CONFIDENCE` | One factor per value; `match_type_for` derives exact, candidate or manual | `test_origins.py` |+| Type matchers | `matching/__init__.py` `MATCHERS` | Optional `deferred`, `accepts`, `keys`, `passes` | Per-type matching tests |+| Service-name sources | `service_names/__init__.py` `SOURCES`, sorted by name | `name`, `filenames`, optional `under` and `marker`, `read` | `test_service_names.py` |+| Evidence rules | `graph_evidence.py` `_RULES` | One function returning a reason or `None` | `test_graph_evidence.py` |+| Network probe | `network_probe.py` `PROBE_ROWS`, sorted by language | `language`, `extensions`, `tokens`, `hash_comments` | `test_network_probe.py` |+| Edge kinds | `system_graph.py` `_CONTRACT_TYPE_TO_EDGE_KIND` | Contract type to edge kind | `test_system_graph.py::test_contract_type_to_edge_kind` |+| Package ecosystems | `manifests.py` `ECOSYSTEMS` | Service markers and an optional manifest scanner | `test_manifests.py` |++What the registry tests assert:++- `test_dialect_registry.py`: every registered dialect has a non-empty gate, and+ `EVERY_FILE` only on contract formats (`.proto`, `.sql`, `.prisma`); every table+ row has a gate and an `origin` from `ContractOrigin`; names are unique per+ contract type; a token is searched for once per file however many dialects name+ it.+- `test_extraction_dialect_budget.py`: every source-code dialect costs at most 40%+ of one identifier-led regex pass over the same text, timed in the same process.+- `test_service_names.py`: `SOURCES` is sorted and unique, every module's `SOURCE` is+ registered, a broad glob (`*.yaml`) carries `under` or a `marker`, and only gated+ files are opened.+- `test_network_probe.py`: rows are sorted and unique by language, no extension+ belongs to two rows, and every token compiles.+- `test_extraction_walk_budget.py`: one tree walk per repo, each file read once.++## Trust model++A contract's confidence is its origin's; a link's is its weaker end's times its+strategy's factor (`origins.link_confidence`). The value tables, with what each+origin and strategy establishes, are in+[WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md#how-a-contract-and-a-link-were-made).+Rules that follow from them:++- A dialect picks an existing origin; it never sets a number. A new way of+ establishing a contract adds one `ContractOrigin` row.+- `match_type` is derived from the strategy, never set on its own. Candidate+ strategies are `ambiguous_path`, `prefix_stripped` and `host_only`.+- A system-graph edge carries the strategy of the link that gave it its confidence,+ `manifest` for a package edge, and none for co-change.+- A stored link without a strategy is read through `legacy_strategy`; that store's+ version is older, so the next update re-extracts it.+- Diagnostics reports links at or below `WEAK_LINK_CONFIDENCE_THRESHOLD` (0.4) as+ weak.++The evidence state is the graph-level counterpart: a link's confidence says how far+to trust one edge, and `graph_evidence` says whether the set of edges is enough to+support a score, a cycle verdict or an empty impact set.++## Performance model++- **One walk per repo** for extraction, over the union of the enabled extractors'+ extensions, shared by every extractor. Service-name sources share a second, pruned+ walk that reads only gated config files.+- **Gates once per file.** A dialect's gate is a substring test memoized per token in+ `ScanContext`, so adding a dialect that names known tokens adds no search.+ Ungated dialects fail the registry test, and a dialect that costs as much as an+ ungated scan fails the budget test.+- **Comment masks on demand.** Built once per file, the first time a match asks.+- **Network probe**: one compiled alternation per extension, one search per file that+ produced no consumer; the comment mask is paid only on a hit.+- **Matching is dict-indexed** and runs over the whole set every time; it costs+ milliseconds against seconds of extraction.+- **Graph views are linear** in nodes and edges; cycle enumeration runs on a+ service-granular graph and is capped.+- **A no-change update** runs no cross-repo phase and touches no unchanged member.+ What remains is module import and the per-repo HEAD and staleness probes.++## Contributor recipes++### Add a contract dialect++1. Pick the contract type and create one module in `extractors/http/`, `topic/`,+ `socket/`, `grpc/` or `data/`. A broker or client that fits an existing table+ shape (`TopicCall`, `SocketCall`, the gRPC stub rules in `grpc/languages.py`) is+ rows in a table, not new code.+2. Declare `name` and `extensions` (from `extractors/langs.py`).+3. Declare `requires`: tokens one of which every match needs, such as the library's+ import or the decorator's name. Each table row declares its own. Use+ `EVERY_FILE` only for a contract file format.+4. Declare an `origin` from `ContractOrigin` on each row, or pass one to+ `build_contract` (HTTP: `build_provider_contract` / `build_consumer_contract` in+ `http/dialect.py`; data: `build_table_provider` / `build_table_consumer` in+ `data/dialect.py`). Pick the value whose description matches what established+ the contract.+5. Read through the shared helpers (`calls.call_sites`, `calls.code_matches`,+ `strings.Arg`) so the comment rule and constant resolution apply. Do not add a+ comment check, constant table or path normalizer of your own.+6. If contracts span files, offer `repo_pass()` returning a `RepoPass`.+7. Append the dialect to its type's registry tuple. Order matters only where two+ dialects read one call alike: the first contract per file, id and role is kept.+8. If the two ends can name one thing differently, add a pass or `keys` rule to the+ type's `TypeMatcher` in `matching.MATCHERS`.+9. Add the dialect's tests beside its type's (`test_topic_dialects.py`,+ `test_socket_dialects.py`, `test_framework_dialects.py`,+ `test_data_contracts.py`, the `test_*_clients.py` files): a real snippet that+ yields the contract, one that must not (a lookalike call, a commented-out use),+ and the origin. Run `test_dialect_registry.py`, `test_dialect_comments.py`,+ `test_extraction_dialect_budget.py` and `test_origins.py`.+10. Add the library to the support matrix in+ [WORKSPACES.md](../scale/WORKSPACES.md#api-contract-extraction). If the change+ alters stored rows, check `git log` on `contracts.py` since the last release tag+ before touching `CONTRACTS_VERSION`: it moves at most once per release.++### Add a service-name source++1. Create one module in `service_names/` that defines `read(file: SourceFile)`+ yielding `Claim` rows, and a module-level `SOURCE = ServiceNameSource(...)`.+2. Declare the gate: `filenames` (case-insensitive globs on the file name), plus+ `under` (ancestor directory names) or `marker` (text that must occur) when a glob+ could admit ordinary files. Parse with `yaml_docs.load_yaml_docs` for YAML.+3. In each `Claim`, say where the name points: `at` (the directory the service is+ built from), `aliases` (repo aliases the file names, such as an image basename),+ `ref` (an `ENV` key whose value is a host, resolved through the finished host+ map) or `own_repo` (the repo holding the file, kept only when it is the only name+ the source places there). Use `base.host_of` to read address values.+4. Add `SOURCE` to `SOURCES`, keeping it sorted by `name`.+5. Copy a real config file into `tests/fixtures/service_names/<estate>/`, with+ `.keep` files for the repo directories it names, and add a test in+ `test_service_names.py` asserting the names it maps and the ones it must not+ (a test-resource file, a template, a name shared by two repos).+6. Add a row to the sources table in+ [WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md#service-names).++### Add a probe row or an evidence rule++A client library the probe should count is one token in its language's+`PROBE_ROWS` entry; a new language is one row. A new kind of missing evidence is one+function in `graph_evidence._RULES` returning an `EvidenceReason` with its state;+add its case to `test_graph_evidence.py`.++## Limits++- Ruby, VB and SQL files have no comment mask, so a commented-out match there is+ read. A Python docstring example is read, because the mask keeps strings.+- A gate is a substring test: it keeps a dialect off files it can find nothing in,+ not off every file that mentions its token.+- Service names are workspace-wide, not scoped per compose project or cluster. Two+ stacks reusing one name collide and the name is dropped. Helm templates and+ `ExternalName` services are not read.+- Only HTTP consumers resolve targets through the map, and only HTTP has service+ links.+- A `host_only` edge is service-level: it has no provider route, so breaking-change+ diffs and test impact do not follow it.+- The network probe is lexical. It reads only extensions some extractor walks,+ counts a token inside a string literal, counts each file once whatever its call+ count, and a file whose calls were located but unresolved can be counted both+ there and as unresolved.+- Evidence is read from the graph alone. `build_edges_only` treats every `package`+ edge as a build reference.+- A member's refresh digest does not read the working tree: an uncommitted edit the+ editor generator reads live shows at the next commit, index write or day.+- An extraction setting edit re-extracts every repo.+- Data contracts have no field-level diff, and OpenAPI comparison has a fixed+ boundary; both are stated in+ [WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md#data-contracts).++## See also++- [scale/WORKSPACES.md](../scale/WORKSPACES.md): commands, configuration, the system graph and every view, as users see them+- [reference/WORKSPACE_CONTRACTS.md](../reference/WORKSPACE_CONTRACTS.md): origin and strategy tables, service names, per-transport matching rules+- [language-support.md](language-support.md#workspace-contract-extraction): the extractor tree and the framework matrix+- [layers/GRAPH.md](../layers/GRAPH.md): the per-repo graph and the origin rule this layer follows+- [test-intelligence.md](test-intelligence.md): the test reachability cross-repo test impact joins againstdiff --git a/docs/reference/WORKSPACE_CONTRACTS.md b/docs/reference/WORKSPACE_CONTRACTS.mdindex bfb13b80b..2815d4182 100644--- a/docs/reference/WORKSPACE_CONTRACTS.md+++ b/docs/reference/WORKSPACE_CONTRACTS.md@@ -5,6 +5,8 @@ contracts, for when you need to know why a link did or did not form. Start from[Extraction Diagnostics](../scale/WORKSPACES.md#extraction-diagnostics), whichnames the reason for each unmatched consumer. The support matrix of frameworksand libraries is in [API Contract Extraction](../scale/WORKSPACES.md#api-contract-extraction).+The pipeline behind it, and how to add a dialect or a service-name source, is in+[architecture/workspace.md](../architecture/workspace.md).## How a contract and a link were madediff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.mdindex 8386c959a..0b099104d 100644--- a/docs/scale/WORKSPACES.md+++ b/docs/scale/WORKSPACES.md@@ -33,6 +33,8 @@ Use a workspace when your project spans multiple git repositories that are relatWith a single repo, `repowise init` needs no workspace.+How the layer is built, and how to extend it: [architecture/workspace.md](../architecture/workspace.md).+---## Quick Start