diff --git a/.chisel/calibration/calibration.md b/.chisel/calibration/calibration.md new file mode 100644 index 0000000000..a5777e0c67 --- /dev/null +++ b/.chisel/calibration/calibration.md @@ -0,0 +1,144 @@ +# Chisel Quality Calibration + +Calibration v1 · cartography v1 · revision `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` · 2026-07-27T15:55:07Z +Sample: `fabro-workflow`, `fabro-http`, `fabro-web-app`, `repository-ci` · Control: `fabro-checkpoint` at `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` +Evaluators: GPT-5 (Codex primary and independent reviewers) + +## How to Use This Calibration + +Judge each mapped component against its purpose and direct repository evidence. +Do not grade on a curve. Apply one score per lens, and count a finding under +only its primary lens. + +**Isolated** means contained at an edge; normal callers and routine changes do +not encounter it. **Central** means part of a mapped entry point, common path, +or recurring change. A **routine change** is an ordinary extension or +maintenance task implied by the component's mapped purpose. + +Infer routine work from the mapped purpose and traced common paths; a public +method alone does not establish frequency. A directly evidenced central concern +caps the component's lens score rather than being averaged against healthier +sub-responsibilities. Necessary delegation inside a clear owner is not pressure, +and size or internal busyness alone does not lower ownership. + +Use **N/E** when evidence is insufficient. Never convert missing evidence into +a numeric score, and do not penalize a missing lifecycle path without evidence +that the mapped purpose requires it. Score 4 requires a positive production +mechanism and no material friction; tests may corroborate that mechanism but +cannot create it or become a second authority merely by asserting its contract. + +## Lenses + +### `ownership-boundaries` — Ownership and boundaries + +**Does each responsibility and lifecycle have a clear home, with dependencies +pointing in the intended direction?** Includes responsibility, state, resource, +dependency, and lifecycle placement; excludes local control flow, naming, +types, API meaning, and repeated policy alone. + +### `simplicity` — Simplicity + +**Is the implementation no more complex, indirect, or general than necessary?** +Includes common-path traceability, control flow, indirection, abstraction, and +configuration burden; excludes placement, domain meaning, and independently +repeated knowledge. + +### `domain-model` — Domain model + +**Does each domain concept have one clear meaning and valid shape?** Includes +types, terminology, legal states, conversions, validation, and API semantics; +excludes module placement, lifecycle ownership, and repetition preserving one +meaning. + +### `duplication-knowledge` — Duplication of knowledge + +**Are policies, invariants, decisions, and transformations authoritative rather +than repeated?** Includes semantic repetition and manual synchronization; +excludes harmless syntax, coincidental similarity, and unification that would +create a parameterized mega-abstraction. + +## Observable Anchors + +| Score | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge | +|---:|---|---|---|---| +| 4 | One owner contains the mapped responsibility's state and complete lifecycle. | A production mechanism makes the necessary common path directly traceable. | Canonical types reject invalid states before every common-path interpretation. | One authoritative mechanism enforces each recurring policy, invariant, or transformation. | +| 3 | Ownership friction is isolated outside routine changes. | Unnecessary indirection is isolated outside routine changes. | Meaning or validation friction is isolated outside routine changes. | Repeated knowledge is isolated outside routine changes. | +| 2 | Routine changes coordinate competing owners or reverse the mapped dependency direction. | Routine changes repeatedly navigate competing paths, avoidable layers, or configuration machinery. | Routine changes reconcile recurring meanings, conversions, or invalid intermediate states. | Routine changes manually synchronize the same policy, invariant, or transformation across recurring locations. | +| 1 | No stable owner or dependency direction can be identified for the responsibility. | No stable common path can be traced through the implementation. | No stable meaning or legal shape can be identified for a core concept. | No stable authority can be identified for recurring domain knowledge. | + +## Decision Rules + +1. A directly evidenced central concern caps the component's lens score; do not average it against healthier sub-responsibilities. +2. Judge ownership against the map, not type names; when routine callers reconstruct a mapped lifecycle from low-level primitives, ownership fits 2. +3. A check owns trigger coverage for every path it scans; non-triggering routine targets are ownership pressure, while nonexistent selector values are domain-model pressure. +4. An unused production dependency or parallel entry layer is isolated simplicity friction, capping 4 at 3 when the common path remains direct. +5. Caller validation or a typed destination does not isolate an invalid-capable mapped entry; routine common-path use of that shape fits 2. +6. Concrete second semantic representations cap 4 at 3; score 2 only when an ordinary mapped change must synchronize them, not merely because call sites repeat. + +## Confidence + +Confidence describes evidence quality, not severity. **High** requires direct +evidence across relevant common and boundary paths; final High also requires +independent readings to converge. **Medium** has a material ambiguity or +coverage gap. **Low** is partial or substantially inferential. + +## Classifying a Finding + +- Where should this responsibility or lifecycle live? → `ownership-boundaries` +- Why is this much machinery necessary? → `simplicity` +- What does this name, type, state, or API value mean? → `domain-model` +- Why is this knowledge authoritative in several places? → `duplication-knowledge` + +Tags are diagnostic metadata, not additional scores: + +```text +abstraction-burden boundary-leakage configuration-sprawl +control-flow conversion-sprawl dependency-direction +generality indirection invalid-states +lifecycle misplaced-responsibility +ownership repeated-invariant repeated-policy +repeated-test-knowledge repeated-transformation +state-coupling type-sprawl vocabulary-drift +``` + +## Repository Examples + +### `ownership-boundaries` + +- `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` shows a central orchestrator can own callback order through focused delegates; reviewers must still inspect terminal paths before calling lifecycle ownership contained. +- `apps/fabro-web/app/lib/api-client.ts:apiData` and `apps/fabro-web/app/lib/queries.ts:useRun` keep shared transport and read lifecycles out of route composition; a busy route alone is not boundary leakage. + +### `simplicity` + +- `lib/foundation/fabro-http/src/lib.rs:define_builder!` makes async and blocking construction traceable through one necessary mechanism; local macro indirection can reinforce simplicity. +- `lib/components/fabro-workflow/src/operations/start.rs:RunSession::run` exposes a linear phase sequence, while service reshaping across phase inputs shows that a stable path can still carry recurring machinery. + +### `domain-model` + +- `lib/components/fabro-workflow/src/event/events.rs:Event::StageCompleted` uses string status before `lib/components/fabro-workflow/src/event/convert.rs:stage_status_from_string` reparses it; a typed durable result does not isolate this common-path intermediate. +- `lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` and `ProxyPolicy::resolve_with_env_value` demonstrate a closed policy vocabulary whose invalid boundary values are rejected. + +### `duplication-knowledge` + +- `lib/components/fabro-workflow/src/event/names.rs:event_name` and `lib/components/fabro-workflow/src/event/convert.rs:event_body_from_event` show manual mappings that a routine event extension must synchronize, even when exhaustive matches detect omissions. +- `.github/workflows/rust.yml:on.push.paths` and `.github/workflows/rust.yml:on.pull_request.paths` demonstrate duplicated trigger knowledge: one source-area change requires two manual policy edits. + +## Control Baseline + +`fabro-checkpoint` at `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`: + +| Lens | Score | Confidence | +|---|---:|---| +| Ownership and boundaries | 2 | High | +| Simplicity | 3 | High | +| Domain model | 2 | Medium | +| Duplication of knowledge | 3 | Medium | + +## Recalibration Triggers + +Recalibrate only for a rubric change, a material cartography change, a model +change with demonstrated drift, or inconsistent scores on the control sample. + +## Open Questions + +None. diff --git a/.chisel/calibration/work/adjudication.md b/.chisel/calibration/work/adjudication.md new file mode 100644 index 0000000000..8f3f7bb285 --- /dev/null +++ b/.chisel/calibration/work/adjudication.md @@ -0,0 +1,249 @@ +# Calibration Adjudication + +Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +Cartography: v1 at `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`. +The only later commit adds cartography artifacts, so the mapped code paths are +unchanged at the assessed revision. + +Sample: `fabro-workflow`, `fabro-http`, `fabro-web-app`, `repository-ci`. +Control: `fabro-checkpoint`. + +## Independent Score Matrix + +Cells list reviewer 1 / reviewer 2 / reviewer 3. + +| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge | +|---|---:|---:|---:|---:| +| `fabro-workflow` | 2 / 3 / 4 | 2 / 2 / 2 | 2 / 3 / 2 | 2 / 2 / 2 | +| `fabro-http` | 4 / 4 / 4 | 4 / 4 / 4 | 4 / 3 / 4 | 3 / 4 / 4 | +| `fabro-web-app` | 4 / 4 / 3 | 2 / 2 / 2 | 2 / 2 / 2 | 2 / 2 / 2 | +| `repository-ci` | 4 / 4 / 3 | 3 / 3 / 3 | 2 / 3 / 2 | 2 / 2 / 2 | + +Unanimous pairs establish that central machinery may still have a stable path: +`fabro-workflow` is 2 for simplicity and duplication; `fabro-web-app` is 2 for +simplicity, domain model, and duplication; and `repository-ci` is 3 for +simplicity and 2 for duplication. `fabro-http` is unanimously 4 for ownership +and simplicity. + +## Material Disagreements + +### `fabro-workflow` × ownership and boundaries — 2 / 3 / 4 + +- **Evidence:** `pipeline/mod.rs` and `pipeline/types.rs` give the normal run + explicit phase owners; `lifecycle/mod.rs:WorkflowLifecycle` owns callback + ordering through focused delegates. +- **Counterevidence:** terminal completion and failure are also constructed in + `pipeline/finalize.rs:build_terminal_event`, + `operations/start.rs:emit_workflow_run_failed`, + `operations/start.rs:persist_terminal_engine_failure`, completion/drop + guards, retry, and archive operations. +- **Ambiguous rule:** two reviewers judged the clear normal path; one judged + whether the same lifecycle has one home across normal and exceptional paths. +- **Discriminator:** inspect every recurring terminal path. A routine + terminal-contract change crossing several operation owners is score-2 + ownership pressure even when the success path is well partitioned. +- **Draft adjudication:** 2. + +### `fabro-workflow` × domain model — 2 / 3 / 2 + +- **Evidence:** `pipeline/types.rs` encodes phase states and canonical product + records are reused. +- **Counterevidence:** `event/events.rs:Event::StageCompleted` carries a string + status; `lifecycle/event.rs:EventLifecycle::after_node` serializes a typed + outcome and `event/convert.rs:stage_status_from_string` reparses it with an + unknown-value fallback. +- **Ambiguous rule:** whether a typed durable event isolates an invalid + intermediate representation on the common producer path. +- **Discriminator:** common-path invalid intermediate states are central even + when the durable result is typed. +- **Draft adjudication:** 2. + +### `fabro-http` × domain model — 4 / 3 / 4 + +- **Evidence:** `ProxyPolicy`, `resolve_with_env_value`, and + `HttpClientBuildError` form a closed policy with explicit precedence and + rejection. +- **Counterevidence:** public builders expose both + `proxy_policy(ProxyPolicy::Disabled)` and lower-level `no_proxy()`. +- **Ambiguous rule:** whether a lower-level transport control creates a second + meaning for the repository policy. +- **Discriminator:** an escape hatch does not split the canonical concept when + the typed policy remains closed and its precedence is enforced. +- **Draft adjudication:** 4. + +### `fabro-http` × duplication of knowledge — 3 / 4 / 4 + +- **Evidence:** `define_builder!` is the shared async/blocking authority and + `ProxyPolicy::resolve` owns precedence. +- **Counterevidence:** adding a policy variant synchronizes the enum, parser, + expected-value error text, behavior match, and tests. +- **Ambiguous rule:** whether co-location and exhaustive matching make all + policy vocabulary authoritative. +- **Discriminator:** hypothetical variants do not establish routine + recurrence; exhaustive compiler-checked behavior remains one authority + unless direct evidence shows recurring manual synchronization. +- **Draft adjudication:** 4. + +### `fabro-web-app` × ownership and boundaries — 4 / 4 / 3 + +- **Evidence:** `entry.tsx`, route graphs, `lib/api-client.ts`, queries, + mutations, effect hooks, and the build script give shared responsibilities + visible homes. +- **Counterevidence:** `install-app.tsx` and `routes/run-stages.tsx` contain + several central transformations and presentation concerns. +- **Ambiguous rule:** whether a busy but clearly identified route owner is + boundary pressure or simplicity pressure. +- **Discriminator:** do not lower ownership for internal complexity unless + routine changes cross another owner or reverse the mapped dependency + direction. +- **Draft adjudication:** 4. + +### `repository-ci` × ownership and boundaries — 4 / 4 / 3 + +- **Evidence:** Rust and TypeScript workflows have distinct validation jobs, + narrow permissions, and delegate build procedures to repository commands. +- **Counterevidence:** the Rust clippy job embeds the repository's legacy-auth + vocabulary check. +- **Ambiguous rule:** whether enforcement of a product migration invariant is + misplaced when CI owns validation but not the underlying vocabulary. +- **Discriminator:** a named invariant check may live in CI, but its product + vocabulary must remain authoritative elsewhere; this isolated boundary + friction fits 3. +- **Draft adjudication:** 3. + +### `repository-ci` × domain model — 2 / 3 / 2 + +- **Evidence:** job, runner, permission, and test-mode vocabulary is otherwise + coherent. +- **Counterevidence:** `rust.yml:on.*.paths` names nonexistent `openapi/**` + rather than `docs/public/api-reference/fabro-api.yaml`, and + `zizmor.yml:rules.stale-action-refs.ignore` identifies exceptions by stale + line positions. +- **Ambiguous rule:** whether configuration references are domain vocabulary + or only duplicated operational data. +- **Discriminator:** identifiers that control central behavior are domain + vocabulary; missing or stale referents create score-2 pressure. +- **Draft adjudication:** 2. + +## Draft Anchor Decisions + +- Anchor score 4 on a positive enforcing mechanism, never absence of a defect. +- Separate owner clarity from the amount of machinery inside that owner. +- Treat invalid common-path intermediate states as domain-model pressure. +- Treat repeated semantic decisions as duplication only when routine changes + require manual synchronization. +- Treat mapped configuration identifiers as domain vocabulary. +- Reserve N/E for a lens without direct evidence; no sampled pair required it. + +## Consistency Review + +The fresh reviewer applied only the written draft to `fabro-checkpoint` and +reported: + +| Lens | Score | Evidence confidence | +|---|---:|---| +| Ownership and boundaries | 2 | Medium | +| Simplicity | 3 | High | +| Domain model | 2 | High | +| Duplication of knowledge | 2 | High | + +The control exposed four material wording problems: + +1. The draft did not say how a component-level score combines several + responsibilities, or whether positive mechanisms and friction can coexist + at score 4. +2. Necessary layered delegation could satisfy the original ownership and + simplicity score-2 wording. +3. The domain rules did not say when a public low-level API is an escape hatch + or what score a common invalid intermediate implies. +4. Decision rule 5 contradicted the duplication anchor by assigning routine + string synchronization to score 3. + +The revision now says that a central concern caps rather than averages, score 4 +requires a positive production mechanism without material friction, public +surface alone does not establish routine work, and missing paths are not +negative without mapped-purpose evidence. The anchors now distinguish competing +owners from necessary delegation and maintainer navigation from runtime +layering. Decision rules 2–6 resolve scoped lifecycle handoff, necessary +delegation, common-path invalid states, direct evidence of recurring +synchronization, and configuration identifiers. Tests corroborate production +authorities but are not second authorities merely because they restate a +contract. + +All 16 wording observations in `consistency-review.md` are covered by those +changes or by the existing primary-lens and confidence sections. No consistency +objection remains open before validation. + +## Validation + +### Round 1 + +| Assignment | Validator 1 | Validator 2 | Validator 3 | Result | +|---|---:|---:|---:|---| +| `fabro-workflow` × ownership | 2 | 2 | 2 | Resolved | +| `fabro-workflow` × domain | 2 | 2 | 2 | Resolved | +| `fabro-http` × domain | 4 | 4 | 4 | Resolved | +| `fabro-http` × duplication | 4 | 4 | 3 | Repeated adjacent split | +| `fabro-web-app` × ownership | 4 | 4 | 4 | Resolved | +| `repository-ci` × ownership | 4 | 2 | 4 | Non-adjacent split | +| `repository-ci` × domain | 2 | 2 | 2 | Resolved | +| Control × ownership | 2 | 4 | 2 | Non-adjacent split | +| Control × simplicity | 4 | 4 | 3 | Adjacent split | +| Control × domain | 2 | 3 | 2 | Adjacent split | +| Control × duplication | 3 | 2 | 3 | Adjacent split | + +The sample's workflow lifecycle, event status, HTTP policy model, web +composition, and CI identifier anchors now converge. Six assignments require +the permitted final simplification: + +- HTTP diagnostic allowed-value text is a concrete second semantic + representation, even though the macro is the behavioral authority. +- A CI check owns trigger coverage for every path its embedded policy scans; + this is distinct from the domain meaning of a nonexistent selector. +- Control ownership is judged against the mapped metadata-branch purpose, not + against narrower names on `Store` and `BranchStore`. +- The control's unused dependency and unused parallel entry layer are isolated + simplicity friction rather than evidence-free public breadth. +- Validation in an external caller does not make an invalid-capable mapped + entry type enforce its own legal shape. +- Repeated fixed Git protocol syntax is a concrete second representation, but + multiple current call sites alone do not make changing that protocol an + ordinary mapped change. + +Decision rules 2–6 now state those discriminators directly. Round 2 will +re-score only the six unresolved assignments. + +### Round 2 + +| Assignment | Validator 1 | Validator 2 | Validator 3 | Result | +|---|---:|---:|---:|---| +| `fabro-http` × duplication | 3 | 3 | 3 | Resolved | +| `repository-ci` × ownership | 2 | 2 | 2 | Resolved | +| Control × ownership | 2 | 2 | 2 | Resolved | +| Control × simplicity | 3 | 3 | 3 | Resolved | +| Control × domain | 2 | 2 | 2 | Resolved | +| Control × duplication | 3 | 3 | 3 | Resolved | + +All round-2 scores converge. The final control baseline is ownership 2 +(High), simplicity 3 (High), domain model 2 (Medium), and duplication of +knowledge 3 (Medium). Domain confidence remains Medium because one validator +found a material ambiguity over whether low-level Git path validation belongs +inside the component. Duplication confidence remains Medium because stable +protocol syntax is concrete repetition but has limited demonstrated change +burden. + +Across both validation rounds, the final disputed sample scores are: + +| Component | Ownership and boundaries | Domain model | Duplication of knowledge | +|---|---:|---:|---:| +| `fabro-workflow` | 2 | 2 | — | +| `fabro-http` | — | 4 | 3 | +| `fabro-web-app` | 4 | — | — | +| `repository-ci` | 2 | 2 | — | + +No non-adjacent or repeated adjacent split remains. + +## Open Questions + +None. diff --git a/.chisel/calibration/work/consistency-review.md b/.chisel/calibration/work/consistency-review.md new file mode 100644 index 0000000000..e41ff2c260 --- /dev/null +++ b/.chisel/calibration/work/consistency-review.md @@ -0,0 +1,112 @@ +# Chisel Consistency Review: `fabro-checkpoint` + +Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +Scope: `lib/components/fabro-checkpoint/**` only. The scored evidence is the manifest, production source, and unit tests at the pinned revision. I did not inspect callers, sample reviews, adjudication, or any other file under `.chisel/calibration/work/`. + +## Scores + +| Lens | Score | Confidence | +|---|---:|---| +| `ownership-boundaries` | 2 | Medium | +| `simplicity` | 3 | High | +| `domain-model` | 2 | High | +| `duplication-knowledge` | 2 | High | + +Confidence here describes this reading's evidence quality. The rubric's additional requirement that a final High confidence needs independent convergence can only be decided during adjudication. + +## `ownership-boundaries`: 2 + +The central branch lifecycle crosses two public owners. `BranchStore` stores the branch name and owns bootstrap plus normal branch reads and writes (`branch.rs:20-209`), but branch cleanup is exposed only as `Store::delete_ref(branch)` (`git.rs:215-226`). `BranchStore` keeps both its `Store` reference and branch name private and has no cleanup/archive operation. A caller therefore has to retain the same raw branch identity and leave the branch-scoped interface for cleanup. Bootstrap sequencing is also caller-owned: `BranchStore::new` does not establish the branch, writes fail when it is absent, and every writable test explicitly calls `ensure_branch` first (`branch.rs:26-81, 282-343`). This is recurring lifecycle work rather than an isolated edge, especially under decision rule 1. Primary tags: `lifecycle`, `ownership`. + +Strongest counterevidence: once initialized, `BranchStore::write_with` keeps the read-modify-write sequence together and delegates only Git object/ref primitives to `Store` (`branch.rs:56-82`). The dependency direction is stable: branch storage depends on the lower-level Git store, not vice versa. + +Why adjacent scores do not fit: + +- **1 does not fit:** `BranchStore` is a stable, identifiable owner for the common branch-scoped read/write responsibility, and `Store` is a coherent lower-level Git owner. +- **3 does not fit:** the split includes explicit bootstrap and cleanup paths. Decision rule 1 says recurring terminal ownership cannot be treated as isolated merely because the success path is clear. + +Confidence is Medium because the split is direct, but the scoped evidence cannot show whether archive, retry, and cleanup are deliberately owned by a higher-level caller. + +## `simplicity`: 3 + +The common write path is directly traceable: `write_entry`/`write_entries` prepare blobs, `write_with` reads the tip tree, applies one mutation, writes one commit, and advances one ref (`branch.rs:56-109`). `Store::read_tree` and `Store::write_tree` use a single flat `TreeEntries` representation with private recursive helpers (`git.rs:39-99, 141-159, 229-310`). These are positive reinforcing mechanisms, not just an absence of complexity. + +The remaining simplicity pressure is isolated configuration burden. The manifest declares `fabro-store`, `serde`, and the dev dependency `chrono` (`Cargo.toml:16-28`), but none is referenced anywhere in the component source or tests at this revision. The public `Store::repo` escape hatch (`git.rs:112-114`) and the lower-level object API also add surface area, but normal branch writes do not have to choose among competing implementations. Primary tag: `configuration-sprawl`. + +Strongest counterevidence to lowering the score: the component has one linear common mutation path, and its indirection corresponds directly to Git's blob/tree/commit/ref structure. + +Why adjacent scores do not fit: + +- **2 does not fit:** ordinary reads and writes do not repeatedly traverse competing orchestration paths or configuration machinery; the `BranchStore` to `Store` layering is stable and direct. +- **4 does not fit:** the centralized mutation path is a qualifying positive mechanism, but the unused manifest dependencies are concrete unnecessary configuration rather than necessary machinery. + +Confidence is High because all component files are in scope, so the dependency non-use and the full common write path are directly observable. + +## `domain-model`: 2 + +The common tree-entry producer accepts invalid intermediate path states. `TreeEntries` hides its map, but its public `set` accepts any `Into` without validating a relative Git path (`git.rs:46-61`). Both `BranchStore::write_entry` and `write_entries` feed caller-provided `&str` paths directly into it (`branch.rs:84-109`), and `build_dir_node` later assigns meaning by splitting the strings on `/` (`git.rs:270-294`). Empty components, leading/trailing separators, and file/directory prefix collisions are therefore representable in the canonical intermediate type and reach late Git-tree construction rather than being rejected at the common boundary. Branch identity is likewise an arbitrary `String` until `git2` receives the synthesized ref name (`branch.rs:20-38`, `git.rs:182-197`). This is central invalid-state pressure under decision rule 3, not an isolated low-level escape hatch. Primary tag: `invalid-states`. + +The small helper `sharded_path` is corroborating boundary evidence: its contract says the input is a hex ID, but its public signature accepts any `&str` and slices at a caller-provided byte offset (`branch.rs:211-220`), so a non-ASCII input can panic rather than be rejected as invalid input. + +Strongest counterevidence: `FileMode` is a closed enum and `TreeEntries` keeps ordering and representation private (`git.rs:13-99`). `Error` also distinguishes a missing branch from generic Git failures (`error.rs:5-18`). The component therefore has stable concepts even though common constructors do not preserve all their invariants. + +Why adjacent scores do not fit: + +- **1 does not fit:** branch storage, tree entries, file modes, authors, and trailers all have recognizable, stable meanings. +- **3 does not fit:** raw paths and branch names enter the common public read/write boundary, so validation friction is not isolated outside routine use. + +Confidence is High because the accepting producers and their downstream interpretation are both visible within the scoped common path. + +## `duplication-knowledge`: 2 + +The transformation “find a path in a commit tree, treat only `NotFound` as absence, load the entry as a blob, and copy its bytes” is independently implemented by `BranchStore::read_entry`, `BranchStore::read_entries`, and `Store::read_blob_at` (`branch.rs:119-158`, `git.rs:200-213`). An ordinary maintenance change to missing-entry or entry-kind behavior must synchronize all three common read locations. Ref qualification is also repeated in `update_ref`, `resolve_ref`, and `delete_ref` (`git.rs:182-226`). + +Trailer grammar supplies independent corroboration at the commit-message edge: `": "` formatting/detection is separately encoded by `append`, `parse`, `format_message`, and `has_trailing_trailer_block` (`trailer.rs:9-25, 28-42, 45-65, 68-87`). Primary tags: `repeated-transformation`, `repeated-policy`. + +Strongest counterevidence: important write knowledge is authoritative. `BranchStore::write_with` centralizes tip loading, parent linkage, commit creation, and ref advancement, while `GitAuthor::default` centralizes the fallback identity (`branch.rs:56-82`, `author.rs:13-35`). + +Why adjacent scores do not fit: + +- **1 does not fit:** the repeated implementations currently agree, and stable authorities exist for branch mutation, author defaults, and file-mode conversion. +- **3 does not fit:** the repeated blob-read transformation appears on the public latest-entry and multi-entry common paths, so a routine storage-policy change encounters it centrally rather than only at an edge. + +Confidence is High because the repeated transformations and the mechanisms that are already centralized can both be enumerated completely inside the scoped component. + +## Rubric wording audit + +The following rules or anchors were ambiguous or non-discriminating in this application. I resolved each explicitly rather than silently choosing an interpretation. + +1. **One component score across several responsibilities.** The instruction says to judge “each mapped component,” while the anchors use singular phrases such as “a mapped responsibility” and “a core concept.” It does not say whether to average sub-responsibilities, take the worst concern, or weight by centrality. I scored the mapped checkpoint-storage responsibility and let a directly evidenced central concern cap the lens; isolated author/trailer helpers could affect a score only at 3 versus 4. + +2. **How to establish “routine” and “central” with component-only evidence.** A public method may be a mapped entry point without being frequent, and scoped evidence cannot establish caller frequency. I treated bootstrap, latest reads/writes, and cleanup as routine because they are ordinary lifecycle operations implied by branch storage. I did not infer frequency for unrelated external call sites. + +3. **N/E threshold versus an absent lifecycle path.** “Use N/E when evidence is insufficient” does not say whether a missing archive/retry API is negative evidence, out of scope, or grounds for N/E. I scored paths that are directly present (bootstrap, normal operation, cleanup), did not penalize an unobserved archive/retry design, and lowered ownership confidence for the coverage gap. + +4. **Score 3 and score 4 overlap in every lens.** A positive reinforcing mechanism can coexist with isolated friction, so the score-4 requirement and score-3 anchor can both be true. I treated any evidenced unnecessary/frictional mechanism as a cap at 3; score 4 requires both a positive mechanism and no material friction in the mapped responsibility. This is why the unused manifest dependencies keep simplicity at 3 despite `write_with`. + +5. **What qualifies as a “positive reinforcing mechanism.”** The rubric does not say whether tests, encapsulation alone, or a production authority qualifies. I required an operative production mechanism that funnels behavior or rejects invalid construction. Tests alone did not qualify. + +6. **Ownership score 2 versus ordinary delegation.** “Cross recurring owners or dependency boundaries” could penalize every layered implementation. Decision rule 2 partly resolves this, but “same responsibility” remains subjective. I treated `BranchStore` calling `Store` during a write as ordinary delegation; I counted cleanup only because the caller must leave the branch-scoped owner and supply its identity again. + +7. **Decision rule 1 when terminal operations live at a lower abstraction.** The rule says not to isolate recurring terminal owners but does not define whether a lower-level deletion primitive is a second owner or a delegate. Because `BranchStore` offers no cleanup interface and keeps the needed state private, I treated `Store::delete_ref` as a lifecycle-owner crossing, not merely internal machinery. + +8. **Simplicity score 2’s “repeatedly traverse.”** It is unclear whether this means runtime calls passing through multiple necessary layers, or maintainers choosing among competing paths repeatedly. I used the latter interpretation, consistent with the lens question and decision rule 2; necessary Git layers did not lower the score. + +9. **Decision rule 2’s “simplicity pressure.”** The rule labels machinery inside an owner as pressure even though the lens expressly permits necessary complexity and gives no score consequence for “pressure.” I treated machinery as evidence to test for necessity, not as an automatic deduction. + +10. **Domain score 4 versus decision rule 4’s escape hatch.** “Every common boundary” is not defined, and a public low-level API can be called common or an escape hatch depending on external usage. I treated `TreeEntries::set` as common because `BranchStore::write_with`, `write_entry`, and `write_entries` use it directly; `Store::repo` was treated as an escape hatch. + +11. **Decision rule 3 does not identify a score boundary.** It says a typed durable value does not “repair domain pressure,” but does not say whether a common invalid intermediate means 2 or merely prevents 4. I mapped common-path invalid intermediates to the score-2 anchor (“routine changes reconcile ... invalid intermediate states”); isolated invalid intermediates would map to 3. + +12. **Duplication score 2 versus decision rule 5.** Rule 5 says to score 3 when a routine vocabulary change requires synchronization, while the score-2 anchor says routine synchronization of the same policy/invariant/transformation is score 2. Those statements conflict unless “vocabulary” is an unstated special case. I treated rule 5 narrowly as an exception for localized, string-only vocabulary at an edge. The score-2 finding here rests instead on repeated behavioral blob-read transformations on common paths. + +13. **What test repetition counts as knowledge duplication.** The `repeated-test-knowledge` tag suggests tests can count, but the anchors do not distinguish duplicated policy from assertions that intentionally restate expected behavior. I did not count an assertion of a production contract as a second authority. Repeated test fixture setup was only isolated counterevidence and did not drive a numeric score. + +14. **Decision rule 6 lacks a lens and defines neither “current referent” nor “line selector.”** Its opening phrase points toward `domain-model`, while duplicated CI selectors could point toward `duplication-knowledge`; its mandatory score 2 also bypasses centrality analysis. It had no referent in this component, so I did not apply it. If applicable, I would classify a single invalid identifier under domain model and synchronized copies under duplication. + +15. **The “primary lens only” rule does not explain multi-causal facts.** Raw strings can simultaneously expose invalid states, repeat vocabulary, and force lifecycle handoffs. I assigned each negative fact once by its primary question: lifecycle handoff to ownership, unused dependencies to simplicity, raw path legality to domain, and repeated lookup/ref/trailer behavior to duplication. + +16. **Confidence High cannot be finalized by one reviewer.** “Final High also requires independent readings to converge” is not decidable during an independent review. I reported evidence-quality confidence now and left final convergence to adjudication. + +All other score-1 versus score-2 distinctions were discriminating here: the component consistently has identifiable owners, paths, concepts, and intended policies, so none of the “no stable ... can be identified” anchors fit. diff --git a/.chisel/calibration/work/reviewer-1.md b/.chisel/calibration/work/reviewer-1.md new file mode 100644 index 0000000000..d6c0140da4 --- /dev/null +++ b/.chisel/calibration/work/reviewer-1.md @@ -0,0 +1,182 @@ +# Calibration review — reviewer 1 + +Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +Scope: `fabro-workflow`, `fabro-http`, `fabro-web-app`, and `repository-ci` as routed by `.chisel/cartography/codebase-map.md`. I excluded `apps/fabro-web/app/components/playground/**` from `fabro-web-app`, and limited `repository-ci` to `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`. The routed paths have no changes between the map revision and the reviewed revision. + +## Provisional ratings + +| Component | Ownership boundaries | Simplicity | Domain model | Duplication of knowledge | +| --- | --- | --- | --- | --- | +| `fabro-workflow` | **2 — High** | **2 — High** | **2 — High** | **2 — High** | +| `fabro-http` | **4 — High** | **4 — High** | **4 — High** | **3 — High** | +| `fabro-web-app` | **4 — High** | **2 — High** | **2 — High** | **2 — High** | +| `repository-ci` | **4 — High** | **3 — High** | **2 — High** | **2 — High** | + +## `fabro-workflow` + +### Ownership boundaries — 2, High confidence + +The component has a clear top-level phase boundary: `pipeline/mod.rs` orders parse, transform, validate, initialize, execute, finalize, and pull-request processing; `pipeline/types.rs` gives those phases distinct result types. `pipeline/execute.rs:execute`, `graph.rs:WorkflowGraph`, and `node_handler.rs:WorkflowNodeHandler` also make the boundary with the generic `fabro-core` executor explicit. `lifecycle/mod.rs:WorkflowLifecycle` composes named lifecycle owners instead of placing every callback in the executor. + +The pressure appears in terminal-run ownership. The normal path is owned by `pipeline/finalize.rs:finalize` and `pipeline/finalize.rs:build_terminal_event`, while engine/bootstrap failures are handled by `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, and the completion/drop guards in `operations/start.rs`. Retry and archive operations also synthesize terminal events in `operations/retry.rs` and `operations/archive.rs`. These paths are understandable individually, but terminal state, persistence, and event emission do not have one stable lifecycle home. + +A representative routine change is adding terminal metadata that must be present for every failed or concluded run. It would require checking or changing `pipeline/finalize.rs:build_terminal_event`, `pipeline/finalize.rs:finalize`, `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, the start-operation guards, and the corresponding terminal paths in `operations/retry.rs` and `operations/archive.rs`. + +Strongest counterevidence: the main successful-run path is explicit and strongly partitioned, and `WorkflowLifecycle` plus `RunServices` give many responsibilities named owners. + +Why adjacent scores do not fit: 3 understates the issue because terminal completion is a central lifecycle concern, not an edge-only exception; an ordinary terminal-contract change must inspect several authorities. 1 does not fit because the normal path and the exceptional paths are still traceable and deliberately named. + +### Simplicity — 2, High confidence + +The top-level flow is readable, but routine run startup crosses a large amount of central wiring. `operations/start.rs:start` enters `execute_persisted_run`, constructs `RunSession`, and then `RunSession::run` coordinates logging, SHA listeners, initialization, cleanup/drain guards, execution, finalization, and pull-request handling. `pipeline/types.rs:InitOptions` carries a large set of run inputs, and `operations/start.rs:RunSession::run` assembles them before handing control to `pipeline/initialize.rs`. The resulting services are then repartitioned through `services.rs:RunServices`, `services.rs:EngineServices`, and `pipeline/execute.rs:execute`. + +A representative routine change is adding a run-scoped service needed by node handlers. It would pass through `operations/start.rs:StartServices` or `RunSession`, `pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, `pipeline/types.rs:Initialized`, `services.rs:RunServices`, `services.rs:EngineServices`, and the destructuring/building in `pipeline/execute.rs:execute`. + +Strongest counterevidence: the phase result types in `pipeline/types.rs` and the extracted executor/lifecycle adapters make the long path navigable; the complexity is structured rather than accidental. + +Why adjacent scores do not fit: 3 does not fit because the pressure is on the common startup and execution path, and a small run-scoped dependency change propagates through several central handoff types. 1 does not fit because the ordered pipeline and named handoffs still provide a stable path through the component. + +### Domain model — 2, High confidence + +The strongest positive mechanism is the phase model in `pipeline/types.rs`: `Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` constrain which data exists at each stage. Canonical run records are reused from `fabro-types`, and `services.rs:RunServices` documents cancellation ownership. + +However, the core event path weakens those guarantees. `event/events.rs:Event::StageCompleted` carries `status: String`; lifecycle code such as `lifecycle/event.rs` converts `StageOutcome` to a string, and `event/convert.rs:stage_status_from_string` parses it back when creating the durable event. An unknown value is not rejected: it is warned about and converted to `StageOutcome::Failed`. The durable model in `fabro-types` is typed, but the internal central event model permits invalid status values and gives them a lossy fallback meaning. `WorkflowRunCompleted` similarly carries a string status internally. + +Strongest counterevidence: the durable event body and most run/pipeline records use named enums and phase-specific types, so this is not a component with generally unmodeled state. + +Why adjacent scores do not fit: 3 does not fit because stage and run outcomes are central workflow vocabulary used on every execution, and the internal-to-durable boundary permits and silently reinterprets invalid values. 1 does not fit because canonical typed outcomes exist and dominate downstream storage; the break is concentrated at the internal event boundary. + +### Duplication of knowledge — 2, High confidence + +Adding an event requires coordinated knowledge in several central authorities. The internal variant lives in `event/events.rs:Event`; its wire name is separately selected by `event/names.rs:event_name`; durable fields are declared in `fabro-types::EventBody`; conversion is implemented in `event/convert.rs:event_body_from_event`; stored-field behavior is selected in `event/stored_fields.rs:stored_event_fields_for_variant`; and tracing behavior is implemented on `Event`. `docs/internal/events-strategy.md` documents this multi-site procedure, confirming that this is the expected recurring event-evolution path rather than a one-off remnant. + +A representative routine change is adding a persisted workflow event. It touches `event/events.rs:Event`, `event/names.rs:event_name`, the `Event` tracing method, `fabro_types::EventBody`, `event/convert.rs:event_body_from_event`, `event/stored_fields.rs:stored_event_fields_for_variant`, emitters, and any event consumers. + +Strongest counterevidence: `event/emitter.rs:Emitter::emit_with_scope` constructs the canonical run event once before dispatch, exhaustive matches make omissions visible to the compiler, and the strategy document gives maintainers one checklist. + +Why adjacent scores do not fit: 3 does not fit because event evolution is frequent, central workflow work and requires synchronized changes across representations and crates. 1 does not fit because each representation has a stated role and there is a single canonicalization point before dispatch. + +Lens-boundary note: the internal `Event`/durable `EventBody` split could be described as a domain-model issue or duplication. I treated the repeated declarations and conversion sites as duplication of knowledge; the separate `String`-to-`StageOutcome` loss of meaning is the domain-model issue. Likewise, repeated terminal constructors are secondary duplication, but I classified the primary problem as ownership because the key question is which operation owns terminal lifecycle completion. + +## `fabro-http` + +### Ownership boundaries — 4, High confidence + +`lib/foundation/fabro-http/src/lib.rs` is a small, focused owner for HTTP client construction and proxy policy. Callers get approved async or blocking builders and convenience clients from this crate. Repository lint policy in `clippy.toml` disallows direct `reqwest` constructors and points callers to `fabro-http`, so the boundary is reinforced rather than merely conventional. `ProxyPolicy::resolve` also owns the environment-variable authority through `fabro_static::EnvVars::FABRO_HTTP_PROXY_POLICY`. + +Strongest counterevidence: the crate deliberately re-exports several `reqwest` types and carries lint exceptions for those facade exports, so callers are not isolated from every transport detail. + +Why adjacent scores do not fit: 3 does not fit because construction policy, environment precedence, test defaults, and transport facade all have one enforced home with no observed competing builder authority. + +### Simplicity — 4, High confidence + +The common path is short: choose `HttpClientBuilder` or `BlockingHttpClientBuilder`, optionally configure it, resolve `ProxyPolicy`, and build the underlying client. `define_builder!` generates the shared async/blocking surface once, while the async-only `read_timeout` extension remains plainly visible next to the macro invocation. Convenience functions such as `http_client`, `blocking_http_client`, `test_http_client`, and `blocking_test_http_client` expose the common cases directly. + +Strongest counterevidence: macro generation means the two concrete builder implementations are not visible as ordinary source, and async-only options must be added outside the shared definition. + +Why adjacent scores do not fit: 3 does not fit because the macro removes rather than creates routine common-option work: a shared builder option is added in one readable location, while the generated types remain thin wrappers. + +### Domain model — 4, High confidence + +`ProxyPolicy` names the only supported policies, `ProxyPolicy::parse` rejects unknown values, and `ProxyPolicy::resolve_with_env_value` makes precedence explicit: a caller override wins, then the environment value, then the system default. Test helpers force `Disabled`, making local test semantics deliberate. `HttpClientBuildError` distinguishes policy configuration failure from transport construction failure. + +Strongest counterevidence: callers can express no-proxy behavior through both `proxy_policy(ProxyPolicy::Disabled)` and the lower-level `no_proxy()` builder method, and the facade re-exports lower-level proxy types. + +Why adjacent scores do not fit: 3 does not fit because the overlapping entry points do not introduce an ambiguous stored state or silent fallback: the policy values and their precedence are explicit, and invalid environment vocabulary fails closed. + +### Duplication of knowledge — 3, High confidence + +The builder macro is a strong anti-duplication mechanism for async and blocking clients. The remaining policy vocabulary is manually repeated: `ProxyPolicy` variants, `ProxyPolicy::parse`, the expected-value text in `HttpClientBuildError::InvalidProxyPolicy`, and the policy match in the generated `build` method must agree. + +A representative routine change is adding another supported proxy policy. It would touch `ProxyPolicy`, `ProxyPolicy::parse`, the expected-value message on `HttpClientBuildError::InvalidProxyPolicy`, the `define_builder!` build-time match, and policy tests in the same source file. + +Strongest counterevidence: every repeated policy decision is co-located in one small file, and the exhaustive build match makes a missing behavioral branch a compile error. + +Why adjacent scores do not fit: 4 does not fit because the accepted vocabulary and error vocabulary are independently maintained strings. 2 does not fit because the synchronization is confined to one authority and does not force routine callers or neighboring components to change. + +Lens-boundary note: macro use could be counted as simplicity indirection, but its primary effect here is eliminating async/blocking duplication. The generated control flow is small enough that I did not lower simplicity for it. + +## `fabro-web-app` + +### Ownership boundaries — 4, High confidence + +The app has explicit composition points. `app/entry.tsx` selects normal or install mode and installs shared providers; `app/router.tsx` and `app/install-router.tsx` own the two route trees. `app/lib/api-client.ts` owns generated-client construction and uniform API errors, `app/lib/query-keys.ts` owns cache keys, and `app/lib/queries.ts` owns shared reads. The React effects policy is embodied by approved wrappers in `app/hooks/effects.ts`; direct effect usage is concentrated in hooks and live-event libraries rather than route/component bodies. `scripts/build.ts` separately owns deterministic asset building and atomic publication. + +Strongest counterevidence: some cache mutation and API-write coordination remains in route handlers, particularly in the large run and installation screens, so not every server interaction passes through a single application-service layer. + +Why adjacent scores do not fit: 3 does not fit because routing, reads, client configuration, effects, and build publication each have a visible and consistently used owner; route-local writes are appropriate UI orchestration rather than a competing global authority. + +### Simplicity — 2, High confidence + +The normal routing shell is simple, but two central screens concentrate substantial policy and presentation. `app/routes/run-stages.tsx` combines event-to-turn reduction, event filtering, grouping, stage/activity interpretation, row and panel rendering, stage renderer selection, and the route page. `app/install-app.tsx` similarly combines installation state transitions, controller behavior, forms, and view composition. Cross-tab stream coordination in `app/lib/cross-tab-sse.ts` is another large central mechanism. + +A representative routine change is showing a new kind of stage activity in the run timeline. It requires following `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES`, `app/routes/run-stages.tsx:STAGE_ACTIVITY_EVENT_SET`, `app/routes/run-stages.tsx:buildStageActivity`, the route's turn/activity types, and the corresponding render helpers in the same large route module. + +Strongest counterevidence: shared event lists, query keys, generated API types, and route helpers provide landmarks, and the activity reducer is deterministic rather than dispersed among many components. + +Why adjacent scores do not fit: 3 does not fit because run-stage interpretation is a common product path and small presentation changes require navigating large modules that mix reduction and rendering concerns. 1 does not fit because the route and install flows remain typed, testable, and traceable from explicit entry points. + +### Domain model — 2, High confidence + +Generated API types provide a strong canonical model for ordinary request/response queries, and several local models use discriminated unions. The live-event boundary is weaker. `app/lib/sse.ts:EventPayload` permits an optional event name plus arbitrary fields. `app/lib/run-events.ts:RunEventPayload` and `app/lib/live-events.ts:LiveEventPayload` repeat mostly optional envelope fields with `properties: unknown`. `app/lib/sse.ts:subscribeToSharedEventSource` parses JSON and casts it to the requested payload type without runtime validation. Common live UI behavior therefore accepts payloads that lack the fields implied by their event names. + +There is additional vocabulary translation in `app/data/runs.ts:RunStatus`, which locally reproduces API run-state kinds and adds presentation state, and compatibility shape probing in `app/lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance`. + +Strongest counterevidence: generated types remain the authority for normal API calls, `session-stream.ts` and query paths use generated event-envelope types where possible, and the local run status adds a genuine presentation concept rather than merely renaming every API state. + +Why adjacent scores do not fit: 3 does not fit because SSE drives common live run behavior and its central payload model makes invalid event/field combinations representable and unchecked. 1 does not fit because static generated models are sound and the weak representation is concentrated at live and compatibility boundaries. + +### Duplication of knowledge — 2, High confidence + +Live refresh policy is repeated in separate manually curated authorities. `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` lists events that invalidate run summaries, while `app/lib/board-events.ts:BOARD_STATUS_EVENTS` independently lists many of the same run, interview, and pull-request lifecycle events for board refresh. The duplicated payload interfaces in `run-events.ts` and `live-events.ts` add another synchronization surface. + +A representative routine change is adding a lifecycle event that changes both a run summary and its board status. It requires updating `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` and `app/lib/board-events.ts:BOARD_STATUS_EVENTS`, then checking phase derivation in `app/lib/run-phases.ts:deriveRunPhases` and live consumers if the event also changes the visible run phase. + +Strongest counterevidence: stage activity vocabulary is centralized in `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` and imported by the run-stages route; query keys and server contract types are also centralized or generated. + +Why adjacent scores do not fit: 3 does not fit because the repeated invalidation lists govern common live behavior, and a missing update produces stale UI rather than a compile-time failure. 1 does not fit because each list has a clear local purpose and several other high-change vocabularies already have a single authority. + +Lens-boundary note: the repeated loose live-event interfaces are both duplicate declarations and a weak model. I treated representable invalid payloads and unchecked casts as the domain-model finding; I used independently maintained event-invalidation sets as the primary duplication finding. The size of `run-stages.tsx` is primarily simplicity pressure, not evidence that its route ownership is unclear. + +## `repository-ci` + +### Ownership boundaries — 4, High confidence + +`.github/workflows/rust.yml` and `.github/workflows/typescript.yml` have an explicit language split and named jobs for formatting, linting, generated documentation, tests, type checking, and builds. Each workflow sets narrow permissions, concurrency behavior is visible, and toolchain/action versions are pinned. The TypeScript build job's Rust build step has a clear purpose: verify the embedded production SPA through the repository's actual build command. + +Strongest counterevidence: the Rust clippy job contains a repository-specific legacy-auth `git grep` policy check, rather than delegating that policy to a named script or dedicated job. + +Why adjacent scores do not fit: 3 does not fit because the special check is still plainly owned by repository validation, while language-level checks, permissions, and production build validation have unambiguous homes and no competing workflow was observed. + +### Simplicity — 3, High confidence + +The workflows are short and linear, with direct commands corresponding to local development commands. Friction is isolated: setup steps are repeated across jobs, the clippy job embeds a multi-pattern shell assertion for legacy auth identity removal, and the ignored twin E2E selection is encoded directly in a long `nextest` expression. These cost attention but do not obscure the overall validation flow. + +A representative routine change is adding a new TypeScript validation job. It would repeat the checkout, Bun setup, and dependency-install sequence already present in `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and `jobs.build`, then add the new command. + +Strongest counterevidence: each job can be understood independently, commands are explicit, and there is no multi-layer reusable-workflow indirection. + +Why adjacent scores do not fit: 4 does not fit because repeated setup and inline special policies add avoidable local friction. 2 does not fit because ordinary check changes still have a direct path through one small workflow and do not cross a complex control structure. + +### Domain model — 2, High confidence + +Some configuration identifiers no longer denote repository reality. Both push and pull-request triggers in `.github/workflows/rust.yml` refer to `openapi/**`, but that path does not exist; the actual API contract is `docs/public/api-reference/fabro-api.yaml`, which the same workflow's legacy-auth check names directly. `.github/workflows/typescript.yml` also omits that contract path even though the TypeScript API client is generated from it. A contract-only change can therefore fall outside the configured validation vocabulary. + +`.github/zizmor.yml:rules.stale-action-refs.ignore` identifies three exceptions by `rust.yml` source line. History shows those locations originally denoted Rust toolchain actions, while the current line numbers point elsewhere after workflow edits. The exception's identity is coupled to incidental layout rather than the action it is meant to describe. + +Strongest counterevidence: jobs, test modes, toolchain versions, permissions, and build profiles are otherwise named explicitly and line up with repository commands. + +Why adjacent scores do not fit: 3 does not fit because the stale/nonexistent identifiers affect whether central source-of-truth changes are validated and whether static-validation exceptions retain their intended meaning. 1 does not fit because most CI vocabulary remains stable and the affected values can be corrected from clear repository authorities. + +### Duplication of knowledge — 2, High confidence + +Trigger-path knowledge is repeated in every workflow and twice within each workflow: `.github/workflows/rust.yml:on.push.paths` duplicates `on.pull_request.paths`, and `.github/workflows/typescript.yml` does the same. Cross-language contract inputs then require synchronized edits in both files. The stale `openapi/**` entry and omission of `docs/public/api-reference/fabro-api.yaml` are direct evidence that this repeated knowledge has drifted. + +A representative routine change is moving or adding a source-of-truth file that must trigger all relevant CI. It requires updating `rust.yml:on.push.paths`, `rust.yml:on.pull_request.paths`, `typescript.yml:on.push.paths`, and `typescript.yml:on.pull_request.paths`; there is no shared authority that makes one update cover the four consumers. + +Strongest counterevidence: commands and action versions are local to their jobs, so much of the visible repetition is deliberate job isolation, and each language workflow is small. + +Why adjacent scores do not fit: 3 does not fit because trigger selection is central to CI's purpose, the synchronization crosses both event sections and language workflows, and actual drift is present. 1 does not fit because the duplicated lists are easy to locate and most entries still agree. + +Lens-boundary note: the stale OpenAPI trigger could be scored only as duplicate path knowledge. I used the repeated four-list maintenance burden for duplication, while treating the fact that `openapi/**` currently has no referent—and that line-based Zizmor identities no longer name the intended actions—as domain vocabulary drift. diff --git a/.chisel/calibration/work/reviewer-2.md b/.chisel/calibration/work/reviewer-2.md new file mode 100644 index 0000000000..a9082f5c06 --- /dev/null +++ b/.chisel/calibration/work/reviewer-2.md @@ -0,0 +1,176 @@ +# Calibration Sample Review — Reviewer 2 + +Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +This review uses the component boundaries in `.chisel/cartography/codebase-map.md`. In particular, `fabro-web-app` excludes `apps/fabro-web/app/components/playground/**`, and `repository-ci` contains only `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`. + +## Score summary + +| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge | +|---|---:|---:|---:|---:| +| `fabro-workflow` | 3 (Medium) | 2 (High) | 3 (Medium) | 2 (High) | +| `fabro-http` | 4 (High) | 4 (High) | 3 (High) | 4 (High) | +| `fabro-web-app` | 4 (Medium) | 2 (Medium) | 2 (Medium) | 2 (Medium) | +| `repository-ci` | 4 (High) | 3 (High) | 3 (High) | 2 (High) | + +## `fabro-workflow` + +### `ownership-boundaries` — 3, Medium confidence + +The component has a recognizable high-level owner and intended dependency direction. `lib/components/fabro-workflow/src/operations/mod.rs` owns run-level operations, while `lib/components/fabro-workflow/src/pipeline/mod.rs` owns the ordered phase API. `lib/components/fabro-workflow/src/pipeline/types.rs:Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` make phase ownership explicit. `lib/components/fabro-workflow/src/services.rs:RunServices` and `EngineServices` distinguish run-lifetime services from node-execution services, and `lib/components/fabro-workflow/src/node_handler.rs:WorkflowNodeHandler` is a visible adapter to `fabro-core`. + +The friction is at the public edge: `lib/components/fabro-workflow/src/lib.rs` exposes operations, pipeline phases, handlers, records, services, runtime storage, and several `#[doc(hidden)]` modules. Callers can therefore enter below the complete lifecycle as well as through `lib/components/fabro-workflow/src/operations/start.rs:start`. This weakens containment, but it does not create a competing production owner. + +**Strongest counterevidence:** The typed phase outputs and the `RunServices`/`EngineServices` split strongly reinforce one workflow lifecycle. + +**Why adjacent scores do not fit:** A 4 does not fit because the broad facade exposes enough lifecycle internals to make the boundary porous. A 2 does not fit because the normal `start` path and each phase owner remain identifiable and dependencies are delegated to dedicated crates. + +### `simplicity` — 2, High confidence + +The stable common path is traceable, but routine work crosses substantial central machinery: `lib/components/fabro-workflow/src/operations/start.rs:start` → `execute_persisted_run` → `RunSession::new` → `RunSession::run` → `pipeline::initialize` → `pipeline::execute` → `pipeline::finalize` → `pipeline::pull_request`. Along that path, `StartServices`, `RunSession`, and `lib/components/fabro-workflow/src/pipeline/types.rs:InitOptions` each carry many run concerns, while bootstrap, completion, cleanup, steering-drain, sandbox, and event-flush guards add multiple exit paths. `lib/components/fabro-workflow/src/pipeline/initialize.rs:initialize` also coordinates sandbox creation/reconnection, hooks, credentials, Git setup, handler construction, and resume state. + +**Representative routine change:** Adding one run-scoped execution service would normally thread through `operations/start.rs:StartServices`, `RunSession`, and `RunSession::new`; `pipeline/types.rs:InitOptions`; `pipeline/initialize.rs:initialize`; and `services.rs:RunServices` or `EngineServices`. + +**Strongest counterevidence:** `operations/start.rs:RunSession::run` presents the main phases in a linear order, and the phase-specific types preserve that order despite the setup machinery. + +**Why adjacent scores do not fit:** A 3 does not fit because the pressure is on the main run path rather than at an edge. A 1 does not fit because there is a stable phase sequence and named service bundles to follow. + +### `domain-model` — 3, Medium confidence + +The strongest mechanism is the phase-state model in `lib/components/fabro-workflow/src/pipeline/types.rs`; private fields on `Validated` and `Persisted` and opaque `ResumeState` prevent several invalid transitions. `lib/components/fabro-workflow/src/pipeline/finalize.rs:classify_engine_result` is also a clear authority for translating an engine result into `StageOutcome`, failure detail, and `RunStatus`. + +The main friction is the extensible, string-valued handler vocabulary on the common graph path. `lib/components/fabro-workflow/src/handler/mod.rs:HandlerRegistry::resolve` works with type strings and falls back to the default handler, while `default_registry` registers the built-in strings. Validation in `fabro-validate` protects normal runs, but execution itself does not carry a closed built-in handler type. + +**Strongest counterevidence:** `pipeline/types.rs:ResumeState::from_projection`, the phase output types, and `pipeline/finalize.rs:classify_engine_result` give important workflow concepts one enforced shape. + +**Why adjacent scores do not fit:** A 4 does not fit because handler identity remains string-valued and default-resolved through a central execution boundary. A 2 does not fit because validation and typed phase states canonicalize the normal run before execution. + +### `duplication-knowledge` — 2, High confidence + +Event knowledge is repeated across central authorities. `lib/components/fabro-workflow/src/event/events.rs:Event` defines the emitter-facing shape, `lib/components/fabro-workflow/src/event/convert.rs:event_body_from_event` translates it to the stored `fabro_types::EventBody`, `lib/components/fabro-workflow/src/event/names.rs:event_name` separately assigns wire names, and `lib/components/fabro-workflow/src/event/stored_fields.rs:stored_event_fields_for_variant` separately assigns envelope metadata. These exhaustive matches help detect omissions, but every ordinary event extension still requires synchronized semantic decisions. + +**Representative routine change:** Adding a stored workflow event can touch `event/events.rs:Event`, `event/convert.rs:event_body_from_event`, `event/names.rs:event_name`, `event/stored_fields.rs:stored_event_fields_for_variant`, and the canonical `lib/foundation/fabro-types/src/run_event/mod.rs:EventBody` authority. + +**Strongest counterevidence:** `event/convert.rs:to_run_event_at` is the single assembly point, and Rust's exhaustive matches turn many missed updates into compile failures. + +**Why adjacent scores do not fit:** A 3 does not fit because event emission and persistence are central, recurring behavior. A 1 does not fit because the authorities are explicit and compiler-checked rather than unidentifiable. + +## `fabro-http` + +### `ownership-boundaries` — 4, High confidence + +`lib/foundation/fabro-http/src/lib.rs` has one focused transport-construction boundary. `HttpClientBuilder`, `BlockingHttpClientBuilder`, `ProxyPolicy`, the client aliases, and the production/test constructors all live there; the crate depends only on `fabro-static`, `reqwest`, and `thiserror`. Repository policy reinforces the boundary through `clippy.toml:disallowed-methods`, which directs raw reqwest construction to this facade. + +**Strongest counterevidence:** The public reqwest aliases and re-exports make the abstraction intentionally permeable, so it does not own higher-level request behavior. + +**Why the adjacent score does not fit:** A 3 does not fit because exposing reqwest types is part of the mapped purpose, while construction policy and proxy resolution still have one clear owner. + +### `simplicity` — 4, High confidence + +`lib/foundation/fabro-http/src/lib.rs:define_builder` expresses shared async/blocking forwarding once. Both builders end at the same short `ProxyPolicy::resolve` and `build` path, and `http_client`, `test_http_client`, `blocking_http_client`, and `blocking_test_http_client` are thin named entry points. A shared reqwest builder option is normally added once to the macro. + +**Strongest counterevidence:** The macro hides generated methods, and async-only `HttpClientBuilder::read_timeout` must sit outside it. + +**Why the adjacent score does not fit:** A 3 does not fit because this indirection directly removes twin implementations and leaves callers with a single conventional builder path. + +### `domain-model` — 3, High confidence + +`lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` gives the repository policy two named states, `ProxyPolicy::resolve_with_env_value` defines explicit-over-environment precedence, and `HttpClientBuildError::InvalidProxyPolicy` rejects unknown values. The tests cover default, environment, invalid, and explicit-override cases. + +The isolated ambiguity is that `HttpClientBuilder::no_proxy` and `HttpClientBuilder::proxy_policy(ProxyPolicy::Disabled)` both publicly express disabled proxy behavior, but `no_proxy` mutates the inner builder without updating the policy field. Their relationship is not represented or documented in the type. + +**Strongest counterevidence:** The closed enum, typed error, and resolver tests make the environment-facing policy meaning unusually explicit. + +**Why adjacent scores do not fit:** A 4 does not fit because two public controls overlap without an encoded relationship. A 2 does not fit because the overlap is local and every normal constructor still passes through one two-state resolver. + +### `duplication-knowledge` — 4, High confidence + +The builder macro is the authority for behavior shared by synchronous and asynchronous clients, and every constructor delegates to those builders. The production/test and async/blocking helper names repeat syntax, not policy: test behavior is expressed once as `ProxyPolicy::Disabled`. + +**Strongest counterevidence:** Four constructor helpers and the separate async-only impl are superficially repetitive. + +**Why the adjacent score does not fit:** A 3 does not fit because changing proxy precedence or disabled behavior has one authority; the remaining repetition does not require synchronized policy decisions. + +## `fabro-web-app` + +### `ownership-boundaries` — 4, Medium confidence + +The main browser lifecycle has clear homes. `apps/fabro-web/app/entry.tsx` selects install or normal routing and owns root providers; `app/router.tsx:routes` owns the product route graph; `app/install-router.tsx:installRoutes` owns first-run routing; `app/lib/api-client.ts` owns HTTP normalization; `app/lib/queries.ts` and `app/lib/mutations.ts` own shared server access; and `app/hooks/effects.ts` contains reusable browser-effect lifecycles. Route modules own page-specific composition. The separately mapped playground enters through `app/router.tsx` without its excluded implementation being absorbed into this assessment. + +**Strongest counterevidence:** `app/routes/run-stages.tsx` and `app/install-app.tsx` each combine page state, domain projection, and rendering in one route-owned file. + +**Why the adjacent score does not fit:** A 3 does not fit because those combinations create local complexity, but no competing owner or reversed dependency was identified; shared cross-route responsibilities still have clear modules. + +### `simplicity` — 2, Medium confidence + +Two common product paths carry central transformation machinery. `apps/fabro-web/app/routes/run-stages.tsx` turns event envelopes into `TurnType` values in `buildStageActivity`, then separately groups, filters, timelines, labels, summarizes, and renders them through `buildChatItems`, `groupConsecutiveTools`, `filterDisplayItems`, `buildThreadDnaItems`, and the route's view components. `apps/fabro-web/app/install-app.tsx` similarly contains the install reducer, session hydration, controller, step forms, review, finishing, payload construction, and supporting controls in one flow. + +**Representative routine change:** Changing how a tool event appears on the stage page requires tracing `run-stages.tsx:buildStageActivity`, `buildChatItems`/`groupConsecutiveTools`, `buildThreadDnaItems`, `turnLabel`, `turnSummary`, `EventDetails`, and `StageChatView`. + +**Strongest counterevidence:** The stage path uses discriminated unions and mostly pure exported transformations with focused tests, so each individual step can be reasoned about. + +**Why adjacent scores do not fit:** A 3 does not fit because the long transformation chains are central to major routes. A 1 does not fit because the named pure functions provide a stable trace through both flows. + +### `domain-model` — 2, Medium confidence + +Generated API types provide a useful boundary, but the central event path accepts several simultaneous shapes. `apps/fabro-web/app/lib/run-events.ts:RunEventPayload` makes event identity and metadata optional and `stageIdFromPayload` falls back from `stage_id` to `node_id` to `properties.node_id`. `app/routes/run-stages.tsx:activityEventStageId` repeats that shape tolerance for stored `EventEnvelope`s, while `buildStageActivity` reads tool, text, argument, and output values from both `properties` and legacy top-level fields via `app/lib/unknown.ts`. + +**Representative routine change:** Moving one stage-event field to its canonical envelope location can require coordinated interpretation changes in `lib/run-events.ts:RunEventPayload` and `stageIdFromPayload`, plus `routes/run-stages.tsx:activityEventStageId` and `buildStageActivity`. + +**Strongest counterevidence:** Once parsed, `run-stages.tsx:TurnType`, `StageRenderer`, and generated `StageHandler`/`StageState` types give the UI clear closed shapes. + +**Why adjacent scores do not fit:** A 3 does not fit because the multi-shape event interpretation is on live invalidation and the main stage view, not an edge. A 1 does not fit because generated types and discriminated UI projections establish a stable canonical shape after parsing. + +### `duplication-knowledge` — 2, Medium confidence + +Stage-state presentation policy is authoritative in several common views. `apps/fabro-web/app/lib/stage-sidebar.ts:ACTIVE_STAGE_STATES`, `IN_FLIGHT_STAGE_STATES`, `SUCCEEDED_STAGE_STATES`, `STAGE_STATUS_TONE`, and `STAGE_STATUS_LABEL` define classifications and visuals, while `app/components/stage-sidebar.tsx:statusConfig`, `app/components/run-waterfall.tsx:stageBarClass` and `isStageInFlight`, and `app/components/stage-popover.tsx:StatusPill` make parallel state decisions. + +**Representative routine change:** Adding a generated `StageState` requires reviewing or changing all of those authorities so the sidebar, waterfall, and popover agree on activity, success, label, and tone. + +**Strongest counterevidence:** Generated `StageState` plus exhaustive `Record` mappings catch many omissions, and `lib/stage-sidebar.ts` already centralizes several shared classifications. + +**Why adjacent scores do not fit:** A 3 does not fit because stage status is central to multiple routine run views and synchronization is recurring. A 1 does not fit because the generated enum is a clear semantic authority and TypeScript catches many missing cases. + +## `repository-ci` + +### `ownership-boundaries` — 4, High confidence + +The two workflows divide validation by ecosystem: `.github/workflows/rust.yml:jobs` owns Rust format, lint, generated-doc, workspace test, twin-mode ignored tests, and manual macOS validation; `.github/workflows/typescript.yml:jobs` owns web/client typecheck, web tests, and the embedded-SPA production build. Both use top-level empty permissions and job-local read permission. The cross-language Cargo build in the TypeScript build job validates the mapped embedded-SPA integration rather than creating a second build owner. + +**Strongest counterevidence:** The Rust clippy job contains a repository-wide legacy-auth guard that also scans TypeScript and API paths. + +**Why the adjacent score does not fit:** A 3 does not fit because that cross-language invariant remains an explicitly named CI check, while job and workflow lifecycle ownership stays clear. + +### `simplicity` — 3, High confidence + +The main flow is explicit: named jobs perform checkout, tool setup, and one or two direct repository commands. The isolated friction is `.github/workflows/rust.yml:jobs.clippy.steps.Verify legacy auth identity removal`, where a long regular expression and shell exit-status protocol are embedded in a lint job. The twin-mode test semantics also need a substantial comment and package expression in `jobs.test`. + +**Strongest counterevidence:** Separate jobs, direct commands, pinned tools, and no reusable-workflow indirection make routine CI behavior easy to locate. + +**Why adjacent scores do not fit:** A 4 does not fit because the legacy guard and twin-mode selection require non-obvious local interpretation. A 2 does not fit because that machinery is isolated and ordinary check changes still follow a direct job structure. + +### `domain-model` — 3, High confidence + +Job names, triggers, permissions, platforms, and commands have consistent meanings in the GitHub Actions structure. Exact action SHAs and named modes such as `--profile ci` reduce ambiguity. The main gap is that `.github/workflows/rust.yml:jobs.test` relies on the external default meaning of `FABRO_TEST_MODE` for its twin run rather than setting the mode in the workflow; the comment is the only local declaration of that state. + +**Strongest counterevidence:** The command, package selector, and explanation tightly describe the intended twin-only behavior, and every job has an explicit runner and permission set. + +**Why adjacent scores do not fit:** A 4 does not fit because a central test mode is implicit in an external default. A 2 does not fit because the rest of the workflow vocabulary is coherent and the implicit state is limited to one documented test step. + +### `duplication-knowledge` — 2, High confidence + +Trigger policy is repeated verbatim between `on.push.paths` and `on.pull_request.paths` in both workflow files. Action versions and bootstrap steps are also copied across every job. `.github/zizmor.yml:rules.stale-action-refs.ignore` adds line-number references to `rust.yml`, creating another manually synchronized representation; at this revision its listed lines 37, 49, and 62 are respectively a blank line, the `fmt` job key, and a Cargo command rather than action references. + +**Representative routine change:** Adding a new Rust-owned source area requires matching edits to `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths`; upgrading checkout requires synchronized edits in `jobs.fmt`, `clippy`, `generated-docs`, `test`, and `test-macos`, followed by review of `.github/zizmor.yml:rules.stale-action-refs.ignore`. + +**Strongest counterevidence:** The duplication is explicit and small enough to inspect, and each actual validation command appears once in its intended job. + +**Why adjacent scores do not fit:** A 3 does not fit because triggers and action versions are central, recurring maintenance knowledge and the stale line selectors demonstrate drift. A 1 does not fit because the canonical workflows and intended checks remain identifiable. + +## Lens-boundary confusion + +- The `fabro-workflow` `Event`/`EventBody` split could be described as two domain shapes. I assigned its score effect to `duplication-knowledge` because the discriminating problem is the synchronized event name, conversion, and envelope-field decisions, not an inability to identify either type's meaning. +- The size and mixed contents of `fabro-web-app` route files could look like misplaced responsibility. I assigned the main effect to `simplicity` because the route remains the clear owner; the problem is tracing the amount of local machinery. +- Repeated `StageState` maps could be treated as domain drift. I assigned them to `duplication-knowledge` because the generated enum preserves meaning and the observed burden is repeating presentation/classification policy across views. +- The `.github/zizmor.yml` line selectors could be treated as invalid configuration meaning. I assigned their main effect to `duplication-knowledge` because the failure mechanism is manual synchronization with line positions; `repository-ci` domain scoring instead uses the implicit twin-mode default. +- `fabro-http`'s macro could be treated as simplicity indirection, while its two proxy-disable controls could be treated as duplicate policy. I treated the macro as a positive simplicity/duplication mechanism and the overlapping controls as `domain-model` friction because the unresolved question is what each public control means. diff --git a/.chisel/calibration/work/reviewer-3.md b/.chisel/calibration/work/reviewer-3.md new file mode 100644 index 0000000000..98558bff4f --- /dev/null +++ b/.chisel/calibration/work/reviewer-3.md @@ -0,0 +1,490 @@ +# Calibration Sample Review — Reviewer 3 + +Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +Scope follows `.chisel/cartography/codebase-map.md`: `fabro-workflow`, +`fabro-http`, `fabro-web-app`, and `repository-ci`. The `fabro-web-app` +reading excludes `apps/fabro-web/app/components/playground/**`; +`repository-ci` includes only `.github/workflows/rust.yml`, +`.github/workflows/typescript.yml`, and `.github/zizmor.yml`. + +## Provisional Matrix + +| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge | +|---|---:|---:|---:|---:| +| `fabro-workflow` | 4 / High | 2 / High | 2 / High | 2 / High | +| `fabro-http` | 4 / High | 4 / High | 4 / High | 4 / High | +| `fabro-web-app` | 3 / High | 2 / High | 2 / High | 2 / High | +| `repository-ci` | 3 / High | 3 / High | 2 / High | 2 / High | + +## `fabro-workflow` + +### `ownership-boundaries` — 4, High confidence + +Evidence: + +- `lib/components/fabro-workflow/src/pipeline/mod.rs` exposes an ordered phase + facade, while `pipeline/types.rs:Parsed`, `Transformed`, `Validated`, + `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` give each + phase an explicit handoff. +- `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and + `HandlerRegistry` own workflow-specific dispatch; + `src/node_handler.rs:WorkflowNodeHandler` is the narrow adapter to + `fabro_core::handler::NodeHandler`. +- `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` states + that it owns callback ordering and delegates event, hook, fidelity, + auto-status, circuit-breaker, Git, and artifact work to focused lifecycle + objects. +- `lib/components/fabro-workflow/Cargo.toml:[dependencies]` points from the + orchestrator to parsing, validation, sandbox, persistence, model, and generic + execution crates; generic traversal remains in `fabro-core`. + +Strongest counterevidence: startup state is carried through +`operations/start.rs:StartServices`, `RunSession`, +`pipeline/types.rs:InitOptions`, and `services.rs:RunServices` / +`EngineServices`, so the lifecycle boundary has substantial wiring. + +Why adjacent scores do not fit: 3 would treat that wiring as unclear ownership, +but the common path consistently identifies phase, handler, lifecycle, and +generic-executor owners. The counterevidence is primarily machinery inside the +intended orchestration owner, not a competing dependency direction or lifecycle +home. + +### `simplicity` — 2, High confidence + +Evidence: + +- The normal start path crosses + `operations/start.rs:start` → `execute_persisted_run` → + `RunSession::new` → `RunSession::run` → + `pipeline::initialize` → `pipeline::execute` → + `pipeline::finalize` → `pipeline::pull_request`. +- The same run-scoped collaborators are reshaped across + `operations/start.rs:StartServices`, `RunSession`, + `pipeline/types.rs:InitOptions`, `services.rs:RunServices`, and + `EngineServices`. +- `lifecycle/mod.rs:WorkflowLifecycle::new` takes the full set of lifecycle + collaborators and has an explicit `too_many_arguments` exception before + constructing seven sub-lifecycles with shared coordination state. + +Strongest counterevidence: the phase-state types in +`pipeline/types.rs` and the focused handler/lifecycle modules make this +machinery traceable; the common path is not hidden. + +Why adjacent scores do not fit: 3 does not fit because every ordinary run +traverses the service reshaping and multi-stage cleanup/finalization path; this +is central rather than edge friction. 1 does not fit because the named phase +sequence and handoff types provide a stable path through the machinery. + +Representative routine change: adding a run-scoped execution-audit sink for +handlers would require threading it through +`operations/start.rs:StartServices`, `RunSession`, +`RunSession::new`, `RunSession::run`, +`pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, and +`services.rs:RunServices` or `EngineServices`. + +### `domain-model` — 2, High confidence + +Evidence: + +- Positive mechanisms are substantial: + `pipeline/types.rs:Validated` hides its graph and exposes validation + operations, `ResumeState::from_projection` creates opaque resume state, and + `run_status.rs` plus `outcome.rs` reuse canonical types from `fabro-types` and + `fabro-core`. +- A central exception remains: + `event/events.rs:Event::StageCompleted` represents `status` as `String`, while + execution uses typed `outcome.rs:StageOutcome`. + `event/convert.rs:stage_status_from_string` reparses the string and maps every + unknown value to a failed outcome. +- The common producer + `lifecycle/event.rs:EventLifecycle::after_node` converts the typed outcome to + a string before the canonical event conversion converts it back. + +Strongest counterevidence: the pipeline phase types, `RunStatus`, +`StageOutcome`, `StageId`, and the durable `fabro_types::EventBody` otherwise +give the main workflow concepts canonical typed shapes. + +Why adjacent scores do not fit: 3 does not fit because stage completion is on +the execution hot path and accepts states the canonical outcome enum rejects. +1 does not fit because the canonical types and phase states still give the +workflow a coherent vocabulary overall. + +Representative routine change: adding or changing a stage outcome would touch +the canonical `lib/foundation/fabro-core/src/outcome.rs:StageOutcome`, string +construction in `lifecycle/event.rs:EventLifecycle::after_node`, +`event/events.rs:Event::StageCompleted`, +`event/convert.rs:stage_status_from_string`, and terminal interpretation in +`pipeline/finalize.rs:classify_engine_result`. + +### `duplication-knowledge` — 2, High confidence + +Evidence: + +- `event/events.rs:Event` defines the internal event shape, + `event/names.rs:event_name` independently maps every variant to its external + name, `event/stored_fields.rs:stored_event_fields` independently selects + envelope fields, and `event/convert.rs:event_body_from_event` constructs the + canonical `fabro_types::EventBody`. +- `docs/internal/events-strategy.md:Adding A New Event` explicitly requires + synchronized edits to the internal event, tracing, external name, + `EventBody`, stored fields, conversion, and consumers. +- Exhaustive matches make omissions visible, but they do not make one of those + mappings authoritative for the others. + +Strongest counterevidence: `event/emitter.rs:Emitter` canonicalizes each emitted +event once, all listeners receive the same `RunEvent`, and exhaustive matching +plus conversion tests detect much of the synchronization drift. + +Why adjacent scores do not fit: 3 does not fit because adding an event is a +routine extension to this component and centrally requires several independent +authorities. 1 does not fit because the events strategy clearly identifies all +authorities and the compiler/test suite gives a stable update path. + +Representative routine change: adding `run.suspended` would touch +`event/events.rs:Event`, `events.rs:Event::trace`, +`event/names.rs:event_name`, +`lib/foundation/fabro-types/src/run_event/mod.rs:EventBody`, +`event/stored_fields.rs:stored_event_fields`, +`event/convert.rs:event_body_from_event`, and relevant store/UI consumers. + +## `fabro-http` + +### `ownership-boundaries` — 4, High confidence + +Evidence: + +- The component is one focused source module: + `lib/foundation/fabro-http/src/lib.rs` owns the reqwest facade, + `ProxyPolicy`, client builders, build errors, and deterministic test clients. +- `src/lib.rs:HttpClientBuilder::build` and + `BlockingHttpClientBuilder::build` are the construction boundary where the + process proxy policy is applied. +- `clippy.toml:disallowed-methods` denies direct reqwest client constructors and + points callers to this component; `fabro_static::EnvVars` supplies the one + environment-variable name without introducing higher-level configuration. + +Strongest counterevidence: the facade deliberately re-exports many reqwest +types, and exceptional consumers still carry direct reqwest dependencies for +generated clients or incompatible dependency versions. + +Why adjacent scores do not fit: 3 does not fit because the normal async, +blocking, production, and test construction paths all converge on the same +owned policy, with a repository lint reinforcing that boundary. + +### `simplicity` — 4, High confidence + +Evidence: + +- `src/lib.rs:define_builder!` expresses the common async/blocking builder once; + the four convenience constructors are thin calls to the same builders. +- The common flow is direct: + `HttpClientBuilder::new` → optional reqwest options → + `HttpClientBuilder::build` → `ProxyPolicy::resolve` → reqwest build. +- The only async-only option is visibly isolated in + `HttpClientBuilder::read_timeout`. + +Strongest counterevidence: the macro hides the two generated impls and every +new exposed reqwest option requires another forwarding method. + +Why adjacent scores do not fit: 3 does not fit because the macro removes a real +parallel API synchronization burden while leaving the common client-building +path locally readable; its indirection is not encountered beyond this file. + +### `domain-model` — 4, High confidence + +Evidence: + +- `src/lib.rs:ProxyPolicy` has exactly the two supported states, + `ProxyPolicy::resolve_with_env_value` makes explicit configuration override + environment fallback, and invalid/non-Unicode values become + `HttpClientBuildError`. +- `src/lib.rs:HttpClientBuildError` distinguishes invalid policy from underlying + reqwest construction failure. +- `test_http_client` and `blocking_test_http_client` select the typed + `ProxyPolicy::Disabled` rather than relying on ambient test environment state. + +Strongest counterevidence: the environment boundary is necessarily stringly, +and `ProxyPolicy::parse` accepts case variants before producing the enum. + +Why adjacent scores do not fit: 3 does not fit because invalid strings are +rejected at the boundary, precedence is explicit, and all downstream paths use +the closed enum. + +### `duplication-knowledge` — 4, High confidence + +Evidence: + +- `src/lib.rs:define_builder!` is the single authority for shared async and + blocking options and policy application. +- `ProxyPolicy::resolve` is the single production authority for explicit/env/ + default precedence. +- `clippy.toml:disallowed-methods` prevents ordinary callers from silently + recreating client-construction policy outside the component. + +Strongest counterevidence: async and blocking convenience constructors remain +as four syntactically similar functions, and `read_timeout` cannot live in the +shared macro surface. + +Why adjacent scores do not fit: 3 does not fit because the remaining repetition +does not duplicate a policy or require independent decisions; it exposes +parallel entry points backed by the same authority. + +## `fabro-web-app` + +### `ownership-boundaries` — 3, High confidence + +Evidence: + +- `apps/fabro-web/app/entry.tsx:AppRuntime` owns browser bootstrap and global + runtime providers; `router.tsx:routes` and + `install-router.tsx:installRoutes` own the two route graphs. +- `app/lib/queries.ts` and `app/lib/mutations.ts` own server reads and writes; + `app/lib/api-client.ts` owns transport/error normalization. +- `app/hooks/effects.ts` and purpose-named hooks such as + `useRunEvents` and `useInstallRestartHealthPolling` contain browser resource + lifecycles rather than leaving them in route rendering. +- `routes/run-detail.tsx:RunDetail` delegates its header, actions, model, + lifecycle-toast, tab-shell, and docked-control responsibilities to the + `routes/run-detail/**` modules. + +Strongest counterevidence: two mapped common paths still concentrate several +responsibilities: +`install-app.tsx:InstallApp` / `useInstallController` contains state, +hydration, submission, step routing, payload construction, and rendering, while +`routes/run-stages.tsx:RunStages` / `buildStageActivity` contains event +interpretation and a large part of stage presentation. + +Why adjacent scores do not fit: 4 does not fit because those central route +modules are not merely edge exceptions. 2 does not fit because routes, API +access, queries, mutations, browser effects, and build lifecycle still have +stable homes and dependencies generally point through those homes. + +### `simplicity` — 2, High confidence + +Evidence: + +- The first-run common path is concentrated in + `install-app.tsx:installReducer`, `useInstallController`, `InstallApp`, + `LlmStep`, `ObjectStoreStep`, `SandboxStep`, `GithubStep`, + `buildObjectStorePayload`, and `buildSandboxPayload`. +- The run-stage common path combines + `routes/run-stages.tsx:selectStageRenderer`, + `buildStageActivity`, filtering, debug views, waterfall construction, and + `RunStages`. +- Cross-tab event sharing introduces a second substantial state machine at + `app/lib/cross-tab-sse.ts:CrossTabSseCoordinator`, beneath the already + separate shared-event-source logic in `app/lib/sse.ts:subscribeToSharedEventSource`. + +Strongest counterevidence: reducers, discriminated unions, shared query hooks, +purpose-named integration hooks, and extracted run-detail modules make many +individual flows explicit and testable. + +Why adjacent scores do not fit: 3 does not fit because installation, run-stage +inspection, and live refresh are mapped common paths, not optional edge +machinery. 1 does not fit because each path still has identifiable entry +points, state machines, and tests. + +Representative routine change: adding an installation step for telemetry would +touch `install-app.tsx:INSTALL_STEPS`, `InstallState`, `InstallAction`, +`installReducer`, `useInstallController`, `InstallApp`, a new step component, +review-summary helpers, `install-api.ts`, and the generated install API +authority in `docs/public/api-reference/fabro-api.yaml`. + +### `domain-model` — 2, High confidence + +Evidence: + +- Positive mechanisms include generated API types throughout the query and + route layers, `mode.ts:FabroMode`, and exhaustive display maps such as + `lib/sandbox-state.ts:SANDBOX_STATE_DISPLAY`. +- The central SSE boundary instead uses + `lib/sse.ts:EventPayload`, where `event` is optional and all other fields are + unknown, then extends it as + `lib/run-events.ts:RunEventPayload` with optional string identifiers and + another untyped `properties` map. +- `lib/run-events.ts:stageIdFromPayload` accepts `stage_id`, `node_id`, or + `properties.node_id` as the stage identity. +- `lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance` + cast generated values into compatibility shapes and infer lifecycle from + either `kind`, `instance`, or legacy `runtime` / `provider` fields. + +Strongest counterevidence: normal HTTP reads and writes use +`@qltysh/fabro-api-client` types, and `Record` display maps +make many API vocabulary changes compile-visible. + +Why adjacent scores do not fit: 3 does not fit because SSE drives normal run +refresh and stage views while permitting absent event and identity fields with +multiple meanings. 1 does not fit because generated HTTP types and local +discriminated unions still provide a coherent model for most operations. + +Representative routine change: making stage identity canonical across live +events would touch the wire authority +`docs/public/api-reference/fabro-api.yaml`, +`lib/sse.ts:EventPayload`, `lib/run-events.ts:RunEventPayload`, +`stageIdFromPayload`, and consumers such as +`routes/run-stages.tsx:buildStageActivity`. + +### `duplication-knowledge` — 2, High confidence + +Evidence: + +- `lib/board-events.ts:BOARD_STATUS_EVENTS` independently decides which run + events refresh lists, while `lib/run-events.ts:RUN_SUMMARY_EVENTS`, + `TERMINAL_EVENTS`, and other sets decide detail invalidations. +- `lib/run-phases.ts:deriveRunPhases` independently matches the same lifecycle + event vocabulary to build the pre-stage timeline. +- `lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` is a positive local authority + shared with `routes/run-stages.tsx:buildStageActivity`, but it covers only one + slice of the broader manual event policy. + +Strongest counterevidence: list and detail invalidation are genuinely different +consumer decisions, `query-keys.ts:queryKeys` centralizes cache identities, and +the stage-activity list is deliberately shared with its reducer. + +Why adjacent scores do not fit: 3 does not fit because a normal lifecycle-event +extension that affects board and run detail requires synchronized policy edits +in separate common subscriptions. 1 does not fit because each consumer's +authority is named, localized, and covered by focused tests. + +Representative routine change: adding a `run.suspended` transition that should +refresh both list and detail views would touch +`board-events.ts:BOARD_STATUS_EVENTS`, +`run-events.ts:RUN_SUMMARY_EVENTS` (and possibly `TERMINAL_EVENTS` if its +semantics require it), `board-events.test.tsx`, `run-events.test.tsx`, and the +upstream event/OpenAPI authorities. + +## `repository-ci` + +### `ownership-boundaries` — 3, High confidence + +Evidence: + +- `.github/workflows/rust.yml:jobs` owns Rust formatting, lint, generated-doc, + Linux test, twin-E2E, and manual macOS validation. +- `.github/workflows/typescript.yml:jobs` owns browser/client typecheck, web + tests, and the embedded-SPA release build. +- Both workflows set top-level empty permissions and grant only + `contents: read` per job; all third-party actions are commit-pinned. +- Generated-document and embedded-SPA behavior is delegated to + `cargo dev docs check` and `cargo dev build`, leaving those build procedures + in `fabro-build-tooling`. + +Strongest counterevidence: +`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]` +contains an authentication-migration vocabulary grep inside the general CI +workflow, so an auth-domain transition also has a policy home here. + +Why adjacent scores do not fit: 4 does not fit because that product-domain +policy crosses into the CI owner and the trigger boundary has drift discussed +under domain model. 2 does not fit because the normal validation jobs and their +delegated build/test authorities remain clearly owned and directional. + +Representative routine change: renaming or restoring an authentication identity +would require changing the product types and also the legacy-name authority in +`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]`. + +### `simplicity` — 3, High confidence + +Evidence: + +- Each job is a short checkout/setup/command sequence, and the two workflows + split by the repository's Rust and Bun validation surfaces. +- `.github/workflows/rust.yml:jobs.test` explains the non-obvious twin-mode + expression and why it must not use the strict E2E profile. +- `.github/workflows/typescript.yml:jobs.build` delegates the mixed Rust/SPA + build to one repository command rather than reproducing its internals. + +Strongest counterevidence: checkout, tool setup, install, permissions, runner, +and cache declarations are repeated across every job; the inline legacy-auth +shell condition is more elaborate than the surrounding declarative checks. + +Why adjacent scores do not fit: 4 does not fit because routine maintenance must +scan repeated job scaffolding and one bespoke shell policy. 2 does not fit +because a contributor can still trace each common validation path directly +from one named job to one repository command. + +### `domain-model` — 2, High confidence + +Evidence: + +- `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths` contain + `openapi/**`, but that directory does not exist at the assessed revision. +- The actual contract authority is + `docs/public/api-reference/fabro-api.yaml`, as named by + `AGENTS.md:API workflow`, + `lib/foundation/fabro-api/build.rs:main`, and + `lib/packages/fabro-api-client/package.json:scripts.generate`. +- Neither `.github/workflows/rust.yml:on.*.paths` nor + `.github/workflows/typescript.yml:on.*.paths` names that actual contract + path, even though both generated clients depend on it. + +Strongest counterevidence: job names, Rust versus TypeScript scope, twin versus +live test meaning, and toolchain versions are otherwise explicit; the commands +the jobs run correspond to checked-in project commands. + +Why adjacent scores do not fit: 3 does not fit because an ordinary edit to the +HTTP source of truth falls outside both central validation trigger models. 1 +does not fit because the workflows still have a stable and mostly accurate +vocabulary for jobs, branches, tools, and commands. + +Representative routine change: editing only +`docs/public/api-reference/fabro-api.yaml` should exercise Rust generation and +TypeScript typecheck/build, but its meaning would have to be repaired in +`.github/workflows/rust.yml:on.push.paths`, +`.github/workflows/rust.yml:on.pull_request.paths`, +`.github/workflows/typescript.yml:on.push.paths`, and +`.github/workflows/typescript.yml:on.pull_request.paths`. + +### `duplication-knowledge` — 2, High confidence + +Evidence: + +- Each workflow repeats its path set under both `on.push.paths` and + `on.pull_request.paths`; a new CI-relevant repository path has two authorities + per language. +- `.github/workflows/rust.yml:jobs.fmt`, `jobs.clippy`, + `jobs.generated-docs`, `jobs.test`, and `jobs.test-macos` independently repeat + checkout pins, credential policy, runner/toolchain setup, and often cache + setup. +- `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and + `jobs.build` independently repeat checkout, Bun setup, and frozen install. + +Strongest counterevidence: independent jobs preserve failure isolation and +least-privilege permissions, while the substantive docs/build procedures are +delegated to repository commands rather than copied into YAML. + +Why adjacent scores do not fit: 3 does not fit because path and tool-bootstrap +knowledge is repeated on every routine trigger or tool-version update. 1 does +not fit because all copies remain confined to two small workflow files and the +substantive check authorities are still identifiable. + +Representative routine change: adding a new Rust-relevant `tools/**` tree would +require synchronized edits to +`.github/workflows/rust.yml:on.push.paths` and +`on.pull_request.paths`; updating the Rust checkout/toolchain baseline requires +reviewing the pins in every `rust.yml:jobs.*.steps` copy. + +## Lens-Boundary Notes + +- The repeated startup carriers in `fabro-workflow` could be labeled ownership + or simplicity. I counted their unclear amount of machinery under simplicity; + ownership was judged from whether each phase, resource lifecycle, and + dependency direction has a named home. +- The workflow's internal `Event` and durable `EventBody` have documented + distinct meanings. I therefore counted the many synchronized mappings under + duplication, not domain model. The separate `StageCompleted.status: String` + finding drives the domain-model score because it admits invalid states. +- Large web route files are not ownership findings merely because they are + large. They lower simplicity where common behavior is difficult to trace; the + ownership score moves only where several responsibilities remain concentrated + despite otherwise clear route/data/effect homes. +- In the web event layer, optional/untyped payload shape is a domain-model + finding. Repeating lifecycle-event policy across list, detail, and phase + consumers is a duplication finding. +- In CI, the stale `openapi/**` referent is a domain-model finding because the + path no longer means the API authority it purports to cover. Repeating trigger + and setup lists is separately a duplication finding. +- The `fabro-http` builder macro adds local indirection, but its primary effect + is to make shared async/blocking policy authoritative. I treated it as a + positive duplication mechanism rather than simplicity friction. diff --git a/.chisel/calibration/work/validation-1.md b/.chisel/calibration/work/validation-1.md new file mode 100644 index 0000000000..6954086ae7 --- /dev/null +++ b/.chisel/calibration/work/validation-1.md @@ -0,0 +1,424 @@ +# Chisel calibration validation 1 + +Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +This is an independent reading of only the requested assignments. Scores use the +mapped purposes and the final calibration rubric. Boundary evidence is included +where it establishes whether a scoped mechanism is on a production common path. + +## Summary + +| Component | Lens | Score | Evidence confidence | +|---|---|---:|---| +| `fabro-workflow` | `ownership-boundaries` | 2 | High | +| `fabro-workflow` | `domain-model` | 2 | High | +| `fabro-http` | `domain-model` | 4 | High | +| `fabro-http` | `duplication-knowledge` | 4 | High | +| `fabro-web-app` | `ownership-boundaries` | 4 | Medium | +| `repository-ci` | `ownership-boundaries` | 4 | Medium | +| `repository-ci` | `domain-model` | 2 | High | +| `fabro-checkpoint` | `ownership-boundaries` | 2 | High | +| `fabro-checkpoint` | `simplicity` | 4 | Medium | +| `fabro-checkpoint` | `domain-model` | 2 | High | +| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium | + +## `fabro-workflow` + +### `ownership-boundaries`: 2 + +- **Evidence:** `lifecycle/mod.rs:53-80` presents `WorkflowLifecycle` as the + callback owner, and `lifecycle/git.rs:77-93, 397-401` gives `GitLifecycle` + its own `last_git_sha` state. The normal `RunSession::run` path nevertheless + creates a second `last_git_sha`, reconstructs it by listening to emitted + checkpoint, terminal, and Git events, then passes it back into finalization + (`operations/start.rs:821-856, 914-923`). Terminal responsibility is split + again: engine outcomes become terminal events in + `pipeline/finalize.rs:524-596`, while bootstrap, initialization, and + finalization errors become `run.failed` through the outer operation in + `operations/start.rs:176-285, 288-346`. These crossings occur on the normal + run and error paths, not at an optional edge. +- **Strongest counterevidence:** `operations/start.rs:796-953` is a recognizable + top-level owner for the initialize → execute → finalize → pull-request + sequence, and `WorkflowLifecycle` explicitly orders focused delegates for + each executor callback (`lifecycle/mod.rs:221-469`). +- **Why adjacent scores do not fit:** 3 does not fit because the caller always + mirrors and resupplies Git identity on the common run path, and terminal + failure handling routinely selects between two owners. 1 does not fit because + both the executor callback owner and the outer run-session owner are stable + and traceable; the problem is their competition, not the absence of owners. +- **Rule discrimination:** Decision rule 2 is decisive for the mirrored + `last_git_sha`. The phrase “complete lifecycle” is otherwise ambiguous about + whether an executor lifecycle may end before durability finalization; the + explicit state round-trip makes the result 2 without relying on that + ambiguity. + +### `domain-model`: 2 + +- **Evidence:** The internal durable event shape stores + `Event::StageCompleted.status` as `String` + (`event/events.rs:264-272`). Both synthetic terminal-stage completion and + ordinary successful stage completion stringify the canonical + `StageOutcome` (`lifecycle/event.rs:215-240, 355-366`), after which the + mandatory event conversion reparses it and converts an unknown value to + `Failed` (`event/convert.rs:14-24, 309-333`). This typed → string → typed path + is part of every successful stage-completion event. +- **Strongest counterevidence:** `fabro_types::StageOutcome` is a stable + canonical type, most event fields are typed, and the fallback prevents an + unrecognized string from escaping into the stored projection. +- **Why adjacent scores do not fit:** 3 does not fit because common production + completion events depend on the invalid intermediate rather than using it as + a compatibility edge. 1 does not fit because the canonical status meaning is + clear and the conversion point is explicit. +- **Rule discrimination:** Decision rule 4 and the rubric's repository example + make this assignment unambiguous. + +## `fabro-http` + +### `domain-model`: 4 + +- **Evidence:** `ProxyPolicy` is a closed `System | Disabled` vocabulary; + parsing rejects every other boundary value + (`src/lib.rs:23-35`). Resolution gives explicit configuration precedence over + the environment, defaults absence to `System`, and rejects non-Unicode input + (`src/lib.rs:38-60`). Every async and blocking builder reaches that resolver + before construction (`src/lib.rs:160-166, 172-193`), while the deterministic + test helpers select the typed `Disabled` value + (`src/lib.rs:195-213`). +- **Strongest counterevidence:** The builder also exposes raw `no_proxy()` and + `proxy()` operations (`src/lib.rs:96-106`), so callers can combine an + underlying reqwest choice with `ProxyPolicy`; Unix-socket production callers + do use `no_proxy()` (`lib/foundation/fabro-client/src/client.rs:2123-2134`). +- **Why adjacent scores do not fit:** 3 does not fit because the common + policy-controlled constructors never interpret an invalid policy: they + return `HttpClientBuildError`. The raw builder operations represent valid + per-client transport configuration, not a second string vocabulary. 2 and 1 + do not fit because no common-path conversion or unstable meaning is present. +- **Rule discrimination:** Decision rule 4 is potentially non-discriminating + if every forwarded low-level builder method is called an “escape hatch.” + Here `no_proxy()` carries no invalid intermediate and does not weaken + `ProxyPolicy::resolve`, so treating it as ordinary typed builder + configuration preserves the rule's distinction. + +### `duplication-knowledge`: 4 + +- **Evidence:** `define_builder!` holds the complete shared async/blocking + builder policy once, including proxy resolution and construction + (`src/lib.rs:72-170`), and is instantiated for the two reqwest client kinds + (`src/lib.rs:172-193`). The four convenience constructors delegate to those + builders rather than reproducing policy (`src/lib.rs:195-213`). +- **Strongest counterevidence:** The generated facade necessarily lists each + forwarded reqwest method, and the test and non-test convenience constructors + have similar bodies. +- **Why adjacent scores do not fit:** 3 does not fit because the similar + forwarding and wrappers are syntax over one policy authority, not separately + maintained transport knowledge. 2 does not fit because a proxy-policy change + is made once in the macro/resolver, not synchronized across async and + blocking implementations. 1 does not fit because the authority is explicit. +- **Rule discrimination:** The rubric's `define_builder!` example directly + distinguishes shared macro expansion from semantic duplication; no material + ambiguity remains. + +## `fabro-web-app` + +### `ownership-boundaries`: 4 + +- **Evidence:** `entry.tsx:17-49` owns browser startup, chooses the normal or + installation route graph once, and installs shared SWR runtime policy. + `router.tsx:97-184` owns normal route composition. Shared transport and error + handling live in `lib/api-client.ts:64-160, 213-310`; shared reads such as + `useRun` and `useRunState` live in `lib/queries.ts:182-193`; run mutations and + their cache lifecycle live in `lib/mutations.ts:65-132`; and run-scoped SSE + subscription, invalidation, resync, and cleanup live in + `lib/run-events.ts:129-309`. The representative busy route composes those + owners rather than reimplementing them + (`routes/run-detail.tsx:79-145, 313-379`). +- **Strongest counterevidence:** Some route-local CRUD actions call the shared + API facade directly, and `run-detail.tsx:193-205` coordinates delete state, + cache invalidation, toast, and navigation in the route. +- **Why adjacent scores do not fit:** 3 does not fit because the counterevidence + is local page UX ownership; it does not split a shared transport, read, + mutation, or subscription lifecycle. 2 does not fit because routine run-page + changes use the established owners rather than coordinating competing ones. + 1 does not fit because startup, routing, transport, caching, and streaming + each have readily identifiable homes. +- **Rule discrimination:** “One owner” is mildly non-discriminating for a large + browser application unless responsibility is evaluated at lifecycle + granularity. Using the rubric's `apiData`/`useRun` example, route composition + is not itself a second owner. Confidence is Medium because this is the + largest sampled scope. + +## `repository-ci` + +### `ownership-boundaries`: 4 + +- **Evidence:** `rust.yml:3-40` owns Rust branch/PR/manual triggers and + concurrency, while its jobs contain format, lint, generated-doc, Linux test, + twin E2E, and manual macOS lifecycles (`rust.yml:48-147`). + `typescript.yml:3-34` owns the corresponding TypeScript triggers and + concurrency, and its jobs contain typecheck, test, and integrated SPA/Rust + build lifecycles (`typescript.yml:36-77`). Delegation to `cargo dev` is the + mapped dependency on build tooling, not reverse ownership. +- **Strongest counterevidence:** The TypeScript build invokes a Rust build + (`typescript.yml:75-77`), and invalid path selectors mean some intended + changes do not start the declared workflows. +- **Why adjacent scores do not fit:** 3 does not fit because the cross-language + build is the intentional embedded-SPA integration boundary, not friction, and + selector validity is classified under domain model by decision rule 6. 2 + does not fit because no routine job requires coordination between competing + CI owners. 1 does not fit because the two language validation homes and their + dependency direction are explicit. +- **Rule discrimination:** The score-4 phrase “complete lifecycle” is + non-discriminating for hosted CI if it is read to require repository + ownership of GitHub's runner lifecycle. This score treats the checked-in + trigger/job lifecycle as the mapped responsibility and the platform as an + intended boundary. + +### `domain-model`: 2 + +- **Evidence:** Both Rust trigger selectors name `openapi/**` + (`rust.yml:18,34`), but that revision has no tracked target there; the actual + API contract is `docs/public/api-reference/fabro-api.yaml`, which the + TypeScript client generation command consumes + (`lib/packages/fabro-api-client/package.json:7`). The real contract path is + absent from both workflow path filters. In addition, all three zizmor + `stale-action-refs` identifiers target `rust.yml:37`, `:49`, and `:62` + (`zizmor.yml:1-6`), which are respectively the end of trigger setup, the + `fmt` job key, and a `run` command—not action references at this revision. + These invalid identifiers sit directly in trigger and static-validation + configuration. +- **Strongest counterevidence:** The workflow/job vocabulary itself is stable, + all jobs and action pins have clear meanings, and changes under the large + valid Rust and TypeScript source selectors do trigger their expected suites. +- **Why adjacent scores do not fit:** 3 does not fit because the dead OpenAPI + selector is present in both routine branch and PR paths, while every scoped + zizmor exception lacks a current target. 1 does not fit because the overall + workflow and job model remains stable; the defect is a recurring set of + invalid identifiers. +- **Rule discrimination:** Decision rule 6 is decisive that these are domain + pressure rather than ownership or duplication. It does not state when one or + more dead selectors move from 3 to 2; centrality in both trigger modes and + total staleness of the scoped zizmor selectors supply that discrimination + here. + +## Control: `fabro-checkpoint` + +### `ownership-boundaries`: 2 + +- **Evidence:** The mapped component claims metadata branches, but its + production boundary consumer owns the metadata writer's branch, parent OID, + discovery, remote, and push lifecycle + (`fabro-workflow/src/run_metadata.rs:272-282, 313-439`). On every snapshot, + that caller validates entries, individually drives `Store` through blobs, + tree, commit, and ref update, and retains the parent identity for the next + write (`run_metadata.rs:313-350`). `BranchStore` provides a contained + read-modify-write owner (`branch.rs:17-24, 42-81`) but has no production + caller at this revision. +- **Strongest counterevidence:** The dependency direction is intended + (`fabro-workflow` depends on `fabro-checkpoint`), and the low-level `Store` + consistently owns Git object/ref operations (`git.rs:101-227`). +- **Why adjacent scores do not fit:** 3 does not fit because the lifecycle + crossing occurs on every metadata snapshot, not in an isolated adapter. 1 + does not fit because low-level Git ownership and the caller's higher-level + writer ownership are both stable; the problem is the split between them. +- **Rule discrimination:** Decision rule 2 applies because the caller retains + and resupplies branch/parent identity to complete successive writes. The + rubric does not say whether a deliberately low-level `Store` narrows the + mapped ownership claim; the explicit mapped claim to metadata branches makes + this crossing discriminating. + +### `simplicity`: 4 + +- **Evidence:** The production `Store` has direct blob, tree, commit, and ref + operations (`git.rs:123-226`). Tree conversion is a single read recursion and + a single bottom-up write path (`git.rs:229-310`). At the higher level, + `BranchStore::write_with` is a linear resolve → read → mutate → write → commit + → update sequence (`branch.rs:56-81`), and entry operations are small + delegates (`branch.rs:84-117`). Necessary Git layering is visible rather than + hidden behind competing configuration machinery. +- **Strongest counterevidence:** There are two entry levels, and the production + metadata writer uses the lower-level `Store` instead of `BranchStore`. +- **Why adjacent scores do not fit:** 3 does not fit because choosing the + low-level entry is required for replace-whole-tree and remote-parent behavior, + not unnecessary indirection. 2 does not fit because the scoped common + operations do not navigate competing implementations or configuration. 1 + does not fit because both paths are directly traceable. +- **Rule discrimination:** Ownership rule 2 could otherwise cause the + out-of-scope metadata writer's machinery to be counted again as simplicity + friction. The lens exclusions make that non-discriminating evidence here; + within the scoped implementation, the production primitives are direct. + +### `domain-model`: 2 + +- **Evidence:** `TreeEntries::set` accepts any `String` path without validation + (`git.rs:46-60`), and `write_tree` later interprets it by splitting on `/` + (`git.rs:149-153, 270-293`). The common metadata caller must therefore define + and apply `validate_metadata_path` outside this component before every + `TreeEntries` construction + (`fabro-workflow/src/run_metadata.rs:313-332, 471-480`). The component also + maps every unrecognized Git file mode to `Blob` + (`git.rs:21-35, 229-250`) rather than rejecting an unsupported state. +- **Strongest counterevidence:** `FileMode` is otherwise a closed enum, Git + object IDs use `git2::Oid`, and the current production metadata caller does + reject empty, absolute, dot-segment, and empty-segment paths before writing. +- **Why adjacent scores do not fit:** 3 does not fit because external path + validation is mandatory on every common metadata snapshot and the canonical + `TreeEntries` shape can always hold an invalid path. 1 does not fit because + the intended path and mode meanings remain clear and production does have a + validation step. +- **Rule discrimination:** Decision rule 4 clearly places the caller-validated + `TreeEntries` intermediate at 2. Whether unknown Git modes are a compatibility + escape hatch is ambiguous by itself, but it is not needed to choose the + score. + +### `duplication-knowledge`: 3 + +- **Evidence:** Branch-to-full-ref formatting is repeated in `Store::update_ref`, + `resolve_ref`, and `delete_ref` (`git.rs:182-225`), and the boundary metadata + writer has another `full_ref` transformation + (`fabro-workflow/src/run_metadata.rs:364-439`). `BranchStore::read_entry`, + `read_entries`, `list_entries`, and `tip_tree` also repeat parts of branch-tip + resolution (`branch.rs:119-184`). These repetitions are local and stable, but + there is no single helper enforcing them. +- **Strongest counterevidence:** Mutation sequencing is authoritative in + `BranchStore::write_with` (`branch.rs:56-81`), metadata branch naming has one + `META_BRANCH_PREFIX` constant (`lib.rs:7`), Git-author defaults have one + `Default` implementation (`author.rs:13-20`), and the repeated ref syntax is a + fixed Git protocol form rather than frequently changing Fabro policy. +- **Why adjacent scores do not fit:** 4 does not fit because ref normalization + and branch-tip traversal are still represented in several places. 2 does not + fit because there is no direct evidence that a routine checkpoint change + must alter those stable protocol transformations in sync; the repetitions are + isolated implementation knowledge. 1 does not fit because each policy has an + identifiable local authority even where a helper is absent. +- **Rule discrimination:** Decision rule 5 leaves a real 3-versus-4 ambiguity: + repeated `refs/heads/` can be classified as harmless protocol syntax. I score + 3 because the same branch-to-ref transformation crosses the component + boundary, but do not score 2 without evidence of routine synchronization. + +## Overall rubric observations + +- Decision rule 2 successfully distinguishes focused delegates from a lifecycle + that sends identity back through an event/caller round trip. +- Decision rule 6 prevents dead CI selectors from being double-counted as + ownership defects, but needs centrality/recurrence evidence to distinguish 2 + from 3. +- “One owner” and “complete lifecycle” need responsibility-sized interpretation + for route trees and hosted CI; otherwise healthy composition cannot reach 4. +- Decision rule 5 correctly keeps stable protocol repetition from automatically + becoming score 2, but the line between harmless syntax and a repeated + transformation remains the least discriminating part of this sample. + +## Round 2 revalidation + +| Component | Lens | Score | Confidence | +|---|---|---:|---| +| `fabro-http` | `duplication-knowledge` | 3 | Medium | +| `repository-ci` | `ownership-boundaries` | 2 | High | +| `fabro-checkpoint` | `ownership-boundaries` | 2 | High | +| `fabro-checkpoint` | `simplicity` | 3 | High | +| `fabro-checkpoint` | `domain-model` | 2 | High | +| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium | + +### `fabro-http` × `duplication-knowledge`: 3 + +- **Decisive evidence:** Proxy disabling has two concrete semantic + representations in the mapped entry layer: callers may set + `ProxyPolicy::Disabled` (`src/lib.rs:23-27, 90-94`), or call the separately + exposed `no_proxy()` builder operation (`src/lib.rs:96-100`). The former is + interpreted by calling the same underlying `inner.no_proxy()` transformation + during `build` (`src/lib.rs:160-165`). Both forms are used on direct boundary + paths: test constructors select the enum (`src/lib.rs:199-213`), while the + Unix-socket transport selects `no_proxy()` + (`lib/foundation/fabro-client/src/client.rs:2123-2134`). +- **Adjacent scores:** 4 does not fit revised rule 6 because there is a concrete + second representation of the same no-proxy decision. 2 does not fit because + an ordinary proxy-policy extension does not require manually synchronizing + those call sites; async and blocking policy construction still share the one + `define_builder!` mechanism (`src/lib.rs:72-193`). 1 does not fit because the + resolver remains a stable authority. +- **Remaining ambiguity:** `no_proxy()` can reasonably be viewed as a lower-level + reqwest operation rather than a second Fabro policy. Revised rule 6 makes 3 + the conservative result because `ProxyPolicy::Disabled` is implemented by + that exact operation, but this classification keeps confidence at Medium. + +### `repository-ci` × `ownership-boundaries`: 2 + +- **Decisive evidence:** The Rust check explicitly scans + `docs/public/api-reference/fabro-api.yaml` in its legacy-identity guard + (`rust.yml:80-92`), but neither push nor pull-request triggers include that + real path (`rust.yml:3-35`); they include the nonexistent `openapi/**` + selector instead (`rust.yml:18,34`). A routine API-contract change can + therefore change a scanned target without starting its owning check. +- **Adjacent scores:** 3 does not fit because the non-triggering target is on a + routine branch/PR check path, not an isolated manual edge. 1 does not fit + because the workflow, jobs, and intended trigger owner remain identifiable. + 4 is directly excluded by revised rule 3's trigger-coverage requirement. +- **Remaining ambiguity:** `typescript.yml:76` also invokes a Rust build from a + narrower trigger set, but that broader interpretation is unnecessary; the + explicitly scanned, non-triggering API contract is sufficient for 2. + +### `fabro-checkpoint` × `ownership-boundaries`: 2 + +- **Decisive evidence:** The mapped owner exposes low-level `Store` primitives, + while the routine metadata caller reconstructs the mapped branch lifecycle: + `RunMetadataWriter` owns branch, parent, and discovery state + (`fabro-workflow/src/run_metadata.rs:272-282`), then validates entries and + sequences blob, tree, commit, ref update, and retained parent state on every + snapshot (`run_metadata.rs:313-350`). No production boundary uses the + component's higher-level `BranchStore`. +- **Adjacent scores:** 3 does not fit because every metadata snapshot traverses + the split. 1 does not fit because the low-level Git owner and caller-side + lifecycle are both stable. 4 is directly excluded by revised rule 2: the + routine caller reconstructs a lifecycle the map assigns to this component. +- **Remaining ambiguity:** A narrower map that assigned only Git object + primitives to `fabro-checkpoint` could make this healthy delegation, but the + actual map explicitly assigns metadata branches and checkpoint commits. + +### `fabro-checkpoint` × `simplicity`: 3 + +- **Decisive evidence:** `Cargo.toml:16-24` carries `fabro-store` as a production + dependency, but scoped production code does not use it. The component also + exposes `BranchStore` as a parallel entry layer (`branch.rs:17-24`) that has + no production caller at this revision; the common metadata path uses `Store` + directly. The active `Store` path itself remains linear and direct + (`git.rs:123-226`). +- **Adjacent scores:** 4 is explicitly capped at 3 by revised rule 4 for the + unused production dependency and parallel unused entry layer. 2 does not fit + because routine production work does not repeatedly navigate those unused + elements; its `Store` path is direct. 1 does not fit because a stable common + path is easy to trace. +- **Remaining ambiguity:** Either isolated fact independently supplies the + revised rule's cap, so there is no material score ambiguity. + +### `fabro-checkpoint` × `domain-model`: 2 + +- **Decisive evidence:** `TreeEntries::set` accepts arbitrary string paths + (`git.rs:46-60`) before `write_tree` interprets them structurally + (`git.rs:149-153, 270-293`). Every common metadata snapshot must validate + those paths outside the mapped entry before constructing `TreeEntries` + (`fabro-workflow/src/run_metadata.rs:313-332, 471-480`). +- **Adjacent scores:** 3 does not fit revised rule 5 because caller validation + does not isolate an invalid-capable mapped entry used on every snapshot. 1 + does not fit because path meaning is stable and the caller does enforce it. + 4 is excluded because the canonical entry type itself admits invalid states. +- **Remaining ambiguity:** Unknown Git modes also collapse to `Blob` + (`git.rs:21-35`), but that compatibility question is not needed for the + score; the routine path shape is decisive. + +### `fabro-checkpoint` × `duplication-knowledge`: 3 + +- **Decisive evidence:** The short branch name is converted to + `refs/heads/{branch}` independently in `Store::update_ref`, `resolve_ref`, and + `delete_ref` (`git.rs:182-225`), while the routine boundary writer carries a + second `full_ref` conversion + (`fabro-workflow/src/run_metadata.rs:364-439`). These are concrete repeated + representations, but of stable Git protocol knowledge. +- **Adjacent scores:** 4 does not fit revised rule 6 because the + branch-to-full-ref transformation has a concrete second representation. 2 + does not fit because no ordinary mapped change is shown to require + synchronizing the stable Git namespace transformations; repeated call sites + alone are insufficient. 1 does not fit because the transformation and its + local authorities are clear. +- **Remaining ambiguity:** The literal can also be classified as harmless Git + syntax, which the lens excludes. Its repetition across the mapped boundary + supports 3, but the harmless-syntax distinction keeps confidence at Medium. diff --git a/.chisel/calibration/work/validation-2.md b/.chisel/calibration/work/validation-2.md new file mode 100644 index 0000000000..b33efa10fb --- /dev/null +++ b/.chisel/calibration/work/validation-2.md @@ -0,0 +1,450 @@ +# Chisel calibration validation 2 + +Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c` + +This is an independent reading of the final rubric. I did not seek or infer +earlier scores. + +## Scores + +| Component | Lens | Score | Evidence confidence | +|---|---|---:|---| +| `fabro-workflow` | `ownership-boundaries` | 2 | High | +| `fabro-workflow` | `domain-model` | 2 | High | +| `fabro-http` | `domain-model` | 4 | High | +| `fabro-http` | `duplication-knowledge` | 4 | Medium | +| `fabro-web-app` | `ownership-boundaries` | 4 | Medium | +| `repository-ci` | `ownership-boundaries` | 2 | High | +| `repository-ci` | `domain-model` | 2 | High | +| `fabro-checkpoint` | `ownership-boundaries` | 4 | Medium | +| `fabro-checkpoint` | `simplicity` | 4 | Medium | +| `fabro-checkpoint` | `domain-model` | 3 | Medium | +| `fabro-checkpoint` | `duplication-knowledge` | 2 | Medium | + +## Disputed assignments + +### `fabro-workflow` × `ownership-boundaries` — 2 + +**Direct evidence.** `WorkflowLifecycle` is a real central owner for engine +callback ordering: it contains the event, hook, fidelity, status, circuit +breaker, git, and artifact delegates and orders them in every callback +(`src/lifecycle/mod.rs:53-80`, `223-470`). The full run lifecycle nevertheless +crosses that owner on normal paths. `WorkflowLifecycle::on_run_end` only runs +the hook (`src/lifecycle/mod.rs:467-469`); `pipeline::finalize` separately builds +and emits the terminal event and stops the sandbox +(`src/pipeline/finalize.rs:524-635`); `RunSession::run` separately owns +initialize/execute/finalize, progress flushing, steering drain, and a second +sandbox cleanup guard (`src/operations/start.rs:796-953`); detached bootstrap +and completion guards own additional terminal-failure paths +(`src/operations/start.rs:956-1139`). A routine change to terminal ordering or +cleanup must account for these owners. + +**Strongest counterevidence.** The split is deliberate. In particular, +`finalize` documents why the terminal event must follow metadata flushing, and +the scope guards cover panic/interruption paths that an async lifecycle callback +cannot reliably cover. + +**Why adjacent scores do not fit.** Score 3 does not fit because the split is on +every ordinary terminal path, not an isolated compatibility path. Score 1 does +not fit because the owners and dependency direction are identifiable: +`RunSession` is the outer orchestrator and `WorkflowLifecycle` consistently owns +engine callbacks. + +**Rule discrimination.** Decision rule 2 is useful here, but “complete routine +lifecycle operations” must include terminal emission and resource cleanup, not +only engine callbacks. Without that reading, the positive orchestrator example +could make 3 and 2 hard to distinguish. + +### `fabro-workflow` × `domain-model` — 2 + +**Direct evidence.** The canonical execution result is the typed +`StageOutcome`, re-exported in `src/outcome.rs:1-12`. The common stage-completion +event instead stores `status: String` (`src/event/events.rs:264-293`). +`EventLifecycle::after_node` converts the typed value to a string for every +successful completion (`src/lifecycle/event.rs:319-378`), and +`event_body_from_event` reparses it into `StageOutcome` +(`src/event/convert.rs:309-348`). Unknown strings are silently reinterpreted as +a non-retryable failure (`src/event/convert.rs:14-24`). The same string +intermediate is used for synthetic terminal stages +(`src/lifecycle/event.rs:183-242`). + +**Strongest counterevidence.** Durable `fabro_types::StageCompletedProps` is +typed, and ordinary producers derive the string from a typed value rather than +accepting arbitrary user text. + +**Why adjacent scores do not fit.** Score 3 does not fit because the conversion +and invalid intermediate occur on the common event path for every completed +stage. Score 1 does not fit because `StageOutcome` supplies a stable canonical +meaning and most execution code uses it directly. + +**Rule discrimination.** Decision rule 4 and the repository example are +decisive. The rule would be non-discriminating if “compatibility escape hatch” +were allowed to describe the central `Event` type merely because the durable +type is healthier. + +### `fabro-http` × `domain-model` — 4 + +**Direct evidence.** `ProxyPolicy` is a closed two-variant vocabulary +(`src/lib.rs:23-27`). The environment boundary parses case-insensitively and +rejects every other value with a typed `HttpClientBuildError` +(`src/lib.rs:29-70`). Explicit policy has a documented precedence in +`resolve_with_env_value`, and both async and blocking builders resolve the +policy immediately before applying it (`src/lib.rs:38-59`, `160-166`, +`172-193`). The common production and test constructors all pass through those +builders (`src/lib.rs:195-213`). + +**Strongest counterevidence.** The builders also expose the lower-level +`no_proxy()` and `proxy()` methods (`src/lib.rs:96-106`), so callers can express +transport configuration outside the high-level enum. + +**Why adjacent scores do not fit.** Score 3 does not fit because the lower-level +methods are intentional reqwest-facade escape hatches; the common constructors +and environment boundary do not rely on an invalid or ambiguous policy value. +There is positive production enforcement rather than a test-only contract. + +**Rule discrimination.** Decision rule 4 discriminates well if “low-level +escape hatch” is read literally. If any alternate builder method were treated +as a second domain meaning, scores 3 and 4 would become difficult to distinguish +for facades. + +### `fabro-http` × `duplication-knowledge` — 4 + +**Direct evidence.** `define_builder!` is one production mechanism for all +shared async/blocking builder methods and for applying proxy policy +(`src/lib.rs:72-170`); the two concrete builders are declarations of that +mechanism (`src/lib.rs:172-193`). `ProxyPolicy::resolve` is the single authority +for explicit-versus-environment precedence (`src/lib.rs:38-59`), and the four +convenience constructors delegate to the builders (`src/lib.rs:195-213`). +Workspace boundary evidence reinforces this authority: `clippy.toml` disallows +raw reqwest client constructors in favor of these functions/builders. + +**Strongest counterevidence.** The tokens `system` and `disabled` also appear in +the human-readable error text, and the async/blocking test constructors repeat +the choice of `ProxyPolicy::Disabled`. + +**Why adjacent scores do not fit.** Score 3 does not fit because the repeated +tokens and two one-line convenience constructors do not form independent +authorities for a recurring transformation. The macro and resolver are what +enforce behavior. + +**Rule discrimination.** Decision rule 5 is useful but leaves a small judgment +gap around repeated diagnostic vocabulary. Here that repetition is +non-discriminating: adding a variant would make the exhaustive application +match fail to compile, while one diagnostic sentence is not a second policy +engine. This is why confidence is Medium rather than High. + +### `fabro-web-app` × `ownership-boundaries` — 4 + +**Direct evidence.** Shared HTTP configuration, authentication redirect, and +error normalization live in `app/lib/api-client.ts:64-160,213-309`. Read state +and cache keys live in `app/lib/queries.ts` and +`app/lib/query-keys.ts`; for example, `useRun` owns the run-detail fetch/cache +lifecycle (`queries.ts:182-187`). Shared run mutations and their cache updates +live in `app/lib/mutations.ts:42-208`. Run SSE connection sharing, cleanup, and +cache invalidation live in `app/lib/sse.ts:42-189` and +`app/lib/run-events.ts:129-308`. Browser resources with more specialized +lifecycles are likewise contained: terminal WebSocket/xterm/listener cleanup is +in `app/hooks/use-terminal-session.ts:62-229`, and install polling owns its +timer, interval, and abort controller in +`app/hooks/use-install-effects.ts:72-127`. + +`RunDetail` composes these owners and retains view-local state and interaction +ordering (`app/routes/run-detail.tsx:79-145,148-379`). Its size does not make it +the owner of transport or resource cleanup. + +**Strongest counterevidence.** Several feature routes perform feature-local +create/edit/delete calls and SWR invalidation directly, and `RunDetail` owns the +delete dialog, pending state, toast, list invalidation, and navigation +(`run-detail.tsx:193-205`) rather than using a single mutation hook for that +entire interaction. + +**Why adjacent scores do not fit.** Score 3 does not fit without a concrete +isolated lifecycle that has competing owners. The direct route mutations keep +their feature interaction lifecycle local and still use the shared transport; +they are not evidence that ordinary reads, SSE, or browser resources leak into +route composition. + +**Rule discrimination.** The final repository example is discriminating: +“busy route” must not itself count as boundary leakage. Confidence remains +Medium because the application scope is broad, although the representative +read, mutation, live-update, terminal, install, and route boundaries converge. + +### `repository-ci` × `ownership-boundaries` — 2 + +**Direct evidence.** The Rust workflow’s Clippy job owns a repository-wide +“legacy auth identity removal” guard that scans `lib/apps`, `lib/components`, +`lib/foundation`, `apps`, `lib/packages`, and the OpenAPI document +(`.github/workflows/rust.yml:80-91`). The workflow’s path filters do not include +`apps/**`, `lib/packages/**`, or +`docs/public/api-reference/fabro-api.yaml` +(`rust.yml:3-35`). A routine change in a scanned TypeScript/package/API path can +therefore introduce a forbidden identity without starting the job that owns the +guard. The policy lifecycle is placed under a narrower Rust trigger than the +responsibility it claims. + +**Strongest counterevidence.** The primary Rust and TypeScript build/test +responsibilities otherwise have clear workflow homes, read-only permissions, +and stable concurrency ownership (`rust.yml:38-147`; +`typescript.yml:30-77`). The TypeScript production build’s Rust step is a +legitimate composition point because it builds the Rust binary with the +embedded SPA. + +**Why adjacent scores do not fit.** Score 3 does not fit because the trigger +mismatch affects ordinary changes in multiple scanned source areas, not an +isolated maintenance path. Score 1 does not fit because the two main language +workflows and their jobs still have stable owners and dependency direction. + +**Rule discrimination.** No final rule explicitly says how to classify a check +whose declared scan scope exceeds its trigger scope. The ownership lens’s +“complete lifecycle” language is sufficient, but an explicit trigger/target +coverage rule would make 2 versus 3 less ambiguous. + +### `repository-ci` × `domain-model` — 2 + +**Direct evidence.** Every value in `.github/zizmor.yml` is a line-addressed +identifier: `rust.yml:37`, `rust.yml:49`, and `rust.yml:62` +(`.github/zizmor.yml:1-6`). At this revision those lines are respectively a +blank separator, the `fmt` job key, and a `run:` step—not action references. +Thus none is a current target for the configured `stale-action-refs` ignores. +Routine edits to `rust.yml` can change the accidental referents again without +changing the selectors. + +**Strongest counterevidence.** The syntax still communicates an intended +workflow-and-line selector, and the main workflow job/status vocabulary is +otherwise stable. + +**Why adjacent scores do not fit.** Score 3 does not fit because all three +values in the entire scoped zizmor configuration lack their intended current +referent; this is not one isolated compatibility value. Score 1 does not fit +because the selector format and intended concept remain identifiable even +though the instances are stale. + +**Rule discrimination.** Decision rule 6 is decisive and correctly keeps this +under domain model rather than ownership. It would not by itself distinguish 2 +from 3; the fact that every configured identifier is stale and line edits make +the condition recur supplies that distinction. + +## Control: `fabro-checkpoint` + +### `fabro-checkpoint` × `ownership-boundaries` — 4 + +**Direct evidence.** `git::Store` owns the `git2::Repository` and the low-level +blob/tree/commit/ref operations (`src/git.rs:101-227`). +`branch::BranchStore` owns branch identity, author identity, and the complete +local read-modify-write lifecycle, including parent resolution, tree read, +commit, and ref update (`src/branch.rs:17-82`). Author and trailer concerns are +focused modules rather than state hidden in callers (`src/author.rs`; +`src/trailer.rs`). Boundary evidence points in the intended direction: +`fabro-workflow` depends on these primitives, while its +`RunMetadataWriter` owns the additional temp repository, remote discovery, +credentials, push, and degradation lifecycle. That is a higher-level owner +using a lower-level delegate, not a reverse dependency. + +**Strongest counterevidence.** The production metadata writer uses `Store` +directly and manually sequences blob, tree, commit, and ref operations +(`fabro-workflow/src/run_metadata.rs:313-361`) instead of using `BranchStore`. +The crate name/description can make that look like the mapped checkpoint +lifecycle has escaped the component. + +**Why adjacent scores do not fit.** Score 3 does not fit if responsibilities are +classified by their actual state: `Store` owns local Git mechanics, +`BranchStore` owns local branch writes, and `RunMetadataWriter` owns remote run +metadata. No concrete resource is acquired by one of those owners and released +by another. + +**Rule discrimination.** Decision rule 2 is ambiguous for intentionally +low-level facades. Passing a branch to `Store::update_ref` should not alone mean +“resupplying identity” when the caller owns the higher-level remote branch +lifecycle and `Store` never claimed it. If the mapped purpose is instead read +as all run-checkpoint lifecycle, this assignment could become 2; that purpose +boundary should be fixed before using the control for strict agreement. + +### `fabro-checkpoint` × `simplicity` — 4 + +**Direct evidence.** The local branch write path is linear in +`BranchStore::write_with`: resolve parent, read tree, apply one caller mutation, +write tree, commit, update ref (`src/branch.rs:56-81`). Single-file, +multi-file, and delete operations are thin delegates to that path +(`src/branch.rs:84-117`). The lower-level tree conversion is one direct +flat-to-nested algorithm (`src/git.rs:229-309`), and trailer formatting/parsing +uses straightforward local control flow (`src/trailer.rs:9-87`). + +**Strongest counterevidence.** `BranchStore` has no external production caller +at this revision; the actual metadata path uses the lower-level `Store` API. +There is also some unused-looking surface such as `MetadataError` and generic +branch read/list/log helpers. + +**Why adjacent scores do not fit.** Score 3 does not fit because no direct +production evidence shows routine changes navigating the unused surface or +competing implementations. The production `Store` call sequence is itself +linear. The rubric explicitly says a public method alone does not establish +frequency, so unused API breadth cannot by itself create common-path +indirection. + +**Rule discrimination.** The score-4 requirement for a “production mechanism” +is mildly ambiguous when the clearest high-level mechanism has no production +caller but its lower-level mechanism does. Treating compiled non-test code as +sufficient would make the rule non-discriminating; this score instead relies on +the directly used `Store` path also being traceable. + +### `fabro-checkpoint` × `domain-model` — 3 + +**Direct evidence.** The common metadata boundary validates every path before +putting it into `TreeEntries` +(`fabro-workflow/src/run_metadata.rs:319-336,471-481`), explicitly selects +`FileMode::Blob`, and converts author strings with the fallible +`git2::Signature::now` before committing (`run_metadata.rs:337-345`). Within the +control, `FileMode` and `TreeEntries` give Git tree entries a stable meaning +(`src/git.rs:13-99`), and Git failures stay typed (`src/error.rs:3-32`). + +There is nevertheless isolated model friction. `TreeEntries::set` accepts any +string path with no invariant-bearing path type (`src/git.rs:59-61`); +`FileMode::from_i32` maps every unrecognized Git mode to `Blob` +(`src/git.rs:30-35`); `GitAuthor` has public raw string fields +(`src/author.rs:6-11`); and `BranchStore` says trees grow monotonically while +also exposing `delete_entry` (`src/branch.rs:17-19,111-117`). + +**Strongest counterevidence.** These are not merely hypothetical invalid +shapes: low-level public callers can bypass the production metadata-path +validation, and Git supports meaningful modes omitted by `FileMode`. + +**Why adjacent scores do not fit.** Score 4 does not fit because the low-level +types themselves do not reject invalid paths/authors or preserve every Git +mode. Score 2 does not fit because the directly traced production metadata path +validates before interpretation and does not depend on the fallback +`from_i32`; the friction is in lower-level escape paths and the currently +unused `BranchStore`, not every common snapshot. + +**Rule discrimination.** Decision rule 4 is useful but ambiguous about whether +a common caller validating raw values before a low-level API counts as a +“common-path invalid intermediate.” The rule should distinguish an actually +reparsed/ambiguous value from a raw value that has already passed one boundary +check but lacks an invariant-bearing Rust type. + +### `fabro-checkpoint` × `duplication-knowledge` — 2 + +**Direct evidence.** The branch-name-to-full-ref transformation +`refs/heads/{branch}` is repeated independently in `Store::update_ref`, +`Store::resolve_ref`, and `Store::delete_ref` +(`src/git.rs:182-225`). The direct production boundary repeats it again in +`RunMetadataWriter::full_ref` +(`fabro-workflow/src/run_metadata.rs:425-439`). A routine addition or change to +branch ref handling must preserve the same transformation in each location. +The trailer grammar has a second, smaller recurrence: `": "` is independently +formatted, parsed, and detected in `append`, `parse`, `format_message`, and +`has_trailing_trailer_block` (`src/trailer.rs:11-12,28-40,45-59,68-86`). + +**Strongest counterevidence.** Both grammars are tiny and stable, tests cover +the trailer forms, and the three Store methods currently agree. A helper could +look like cosmetic deduplication rather than a material abstraction. + +**Why adjacent scores do not fit.** Score 3 does not fit because branch +resolution/update/deletion are ordinary Store operations and direct boundary +code already supplies a fourth recurrence; this is not only a hypothetical +future variant. Score 1 does not fit because the repeated transformations are +stable and readily identifiable even though they lack a single authority. + +**Rule discrimination.** Decision rule 5 is decisive only if “direct evidence +of routine recurrence” includes several current operations applying the same +transformation. If it instead requires historical change evidence, the final +rule would be non-discriminating for a revision-only review and this assignment +would move toward 3. + +## Round 2 revalidation + +These scores supersede the corresponding Round 1 scores. + +### `fabro-http` × `duplication-knowledge` — 3 (Medium) + +**Decisive evidence.** `ProxyPolicy::parse` is the behavioral authority for the +external `system`/`disabled` vocabulary, while +`HttpClientBuildError::InvalidProxyPolicy` separately enumerates those values +in its diagnostic (`src/lib.rs:29-35,63-66`). The builder macro remains one +authority for applying the policy to both client kinds (`src/lib.rs:72-193`). + +**Adjacent scores and ambiguity.** Score 4 does not fit because the diagnostic +is a concrete second representation that can drift. Score 2 does not fit +because proxy behavior is not independently reimplemented: the shared +resolver and macro enforce it, and the two no-proxy convenience constructors +are call sites rather than separate authorities (`src/lib.rs:195-213`). The +remaining ambiguity is whether changing the closed proxy vocabulary is routine +enough to make the diagnostic synchronization central; I treat it as isolated. + +### `repository-ci` × `ownership-boundaries` — 2 (High) + +**Decisive evidence.** The Rust workflow's legacy-auth check scans `apps`, +`lib/packages`, and `docs/public/api-reference/fabro-api.yaml` +(`rust.yml:80-91`), but its push and pull-request path filters omit all three +(`rust.yml:3-35`). Under decision rule 3, that check owns trigger coverage for +every path it scans, so routine changes in those targets bypass its lifecycle. + +**Adjacent scores and ambiguity.** Score 3 does not fit because the missing +triggers affect several routine source and contract paths, not an isolated +edge. Score 1 does not fit because the Rust and TypeScript workflow owners and +dependency direction remain stable. No material ambiguity remains under the +new trigger-coverage rule. + +### `fabro-checkpoint` × `ownership-boundaries` — 2 (High) + +**Decisive evidence.** The map assigns checkpoint commits, trees, metadata +branches, authorship, and trailers to this component. The routine +`RunMetadataWriter` caller reconstructs that mapped lifecycle from `Store` +primitives: it writes blobs and a tree, creates the commit and author/message, +updates the ref, and pushes +(`fabro-workflow/src/run_metadata.rs:313-361`). Decision rule 2 therefore +places ownership at 2 even though the crate dependency points toward +`fabro-checkpoint`. + +**Adjacent scores and ambiguity.** Score 3 does not fit because this is the +common metadata snapshot path, not an edge case. Score 1 does not fit because +the dependency direction and the low-level `Store` role are stable, and +`BranchStore::write_with` demonstrates a coherent lifecycle owner inside the +crate (`src/branch.rs:56-81`). The only remaining ambiguity is how specialized +the metadata commit is, but the map explicitly includes metadata branches. + +### `fabro-checkpoint` × `simplicity` — 3 (High) + +**Decisive evidence.** `fabro-store` and `serde` are production dependencies +with no source use (`Cargo.toml:16-24`), and `BranchStore` is a parallel +high-level entry layer with no production caller outside this crate. Decision +rule 4 makes those isolated simplicity frictions and caps 4 at 3. + +**Adjacent scores and ambiguity.** Score 4 does not fit because the unused +production edges and parallel layer are concrete. Score 2 does not fit because +the production `Store` path remains direct; normal callers do not navigate the +unused dependencies or `BranchStore`. Whether `BranchStore` is retained for a +future caller is ambiguous, but the unused dependencies alone sustain 3. + +### `fabro-checkpoint` × `domain-model` — 2 (Medium) + +**Decisive evidence.** The mapped Git-tree entry accepts any `String` path +through `TreeEntries::set` (`src/git.rs:44-61`), while the routine metadata +writer must validate paths before constructing those entries +(`fabro-workflow/src/run_metadata.rs:319-336,471-481`). Decision rule 5 says +caller validation does not isolate an invalid-capable mapped entry. +`FileMode::from_i32` also collapses every unrecognized mode to `Blob` +(`src/git.rs:29-35`). + +**Adjacent scores and ambiguity.** Score 3 does not fit because raw paths cross +the common write boundary. Score 1 does not fit because tree entries, modes, +and authors retain stable meanings and the caller does validate its input. +Confidence is Medium because a deliberately low-level Git store can reasonably +leave some path constraints to higher-level schemas, although the revised rule +weighs against that interpretation. + +### `fabro-checkpoint` × `duplication-knowledge` — 3 (Medium) + +**Decisive evidence.** The `refs/heads/{branch}` transformation is repeated in +three `Store` operations and once at the workflow boundary +(`src/git.rs:182-225`; `fabro-workflow/src/run_metadata.rs:425-439`). +Trailer formatting, parsing, and block detection also encode the `": "` +convention separately (`src/trailer.rs:11-12,28-40,45-59,68-86`). These are +concrete second representations, so decision rule 6 caps 4 at 3. + +**Adjacent scores and ambiguity.** Score 2 does not fit on the current evidence: +adding a Store operation or trailer key may repeat a call-site convention, but +does not require an ordinary mapped change to modify all existing locations. +Score 4 does not fit because the representations are nevertheless concrete and +can drift. The remaining ambiguity is whether broader trailer-syntax support +would be routine maintenance; if so, its formatter/parser/detector +synchronization would support 2. diff --git a/.chisel/calibration/work/validation-3.md b/.chisel/calibration/work/validation-3.md new file mode 100644 index 0000000000..3969b0b13d --- /dev/null +++ b/.chisel/calibration/work/validation-3.md @@ -0,0 +1,447 @@ +# Chisel calibration validation 3 + +Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`. + +This is an independent reading of the final rubric and the assigned component +scopes. I traced representative production entry points and direct boundary +callers. I did not inspect prior calibration scores or any other file in +`.chisel/calibration/work/`. + +## Score summary + +| Component | Lens | Score | Evidence confidence | +| --- | --- | ---: | --- | +| `fabro-workflow` | ownership-boundaries | 2 | High | +| `fabro-workflow` | domain-model | 2 | High | +| `fabro-http` | domain-model | 4 | High | +| `fabro-http` | duplication-knowledge | 3 | Medium | +| `fabro-web-app` | ownership-boundaries | 4 | Medium | +| `repository-ci` | ownership-boundaries | 4 | Medium | +| `repository-ci` | domain-model | 2 | High | +| `fabro-checkpoint` | ownership-boundaries | 2 | High | +| `fabro-checkpoint` | simplicity | 3 | Medium | +| `fabro-checkpoint` | domain-model | 2 | High | +| `fabro-checkpoint` | duplication-knowledge | 3 | Medium | + +## `fabro-workflow` + +### `ownership-boundaries`: 2 (High) + +- **Evidence:** `src/lifecycle/mod.rs:53-80,221-469` provides a real central + `WorkflowLifecycle` and explicitly orders focused event, hook, fidelity, Git, + artifact, status, and circuit-breaker delegates. Its terminal callback, + however, only forwards `on_run_end` to the hook. Normal terminal persistence, + metadata completion, terminal event emission, and sandbox stopping instead + live in `src/pipeline/finalize.rs:524-635`. Bootstrap and execution failures + take another terminal path in `src/operations/start.rs:176-345`, while + `RunSession::run` also installs cleanup and drain guards at + `src/operations/start.rs:889-947`. A routine terminal-lifecycle change must + therefore coordinate the lifecycle orchestrator, finalizer, and detached + failure/guard paths. +- **Strongest counterevidence:** The normal phase sequence is plainly owned by + `RunSession::run` (`initialize -> execute -> finalize -> pull_request`), and + callback ordering inside graph execution has one obvious owner, + `WorkflowLifecycle`. +- **Why 3 does not fit:** Terminal completion, failure, persistence, and cleanup + are common paths, not isolated edge compatibility. The split therefore + remains central even though each individual phase is understandable. +- **Why 1 does not fit:** Stable phase owners and a stable dependency direction + are readily identifiable; the problem is coordination among them, not the + absence of ownership. +- **Rule discrimination:** The repository example correctly requires terminal + inspection and rule 1 makes the common terminal split score-capping. Decision + rule 2 is less literal here because no single identity is resupplied across + every split, but the score does not depend on that rule. + +### `domain-model`: 2 (High) + +- **Evidence:** `src/lifecycle/event.rs:319-390` starts with the typed + `StageOutcome` on an `Outcome`, serializes it with + `outcome.status.to_string()`, and stores the result in the + `Event::StageCompleted.status: String` field declared at + `src/event/events.rs:264-293`. Every successful stage then passes through + `src/event/convert.rs:14-24,309-348`, which reparses the string and silently + converts an unknown value into a non-retryable failure. This is the ordinary + durable-event path, not an import-only compatibility path. +- **Strongest counterevidence:** The destination event model already has the + canonical `fabro_types::StageOutcome`, parallel-branch completion carries it + directly, and other core run concepts use typed IDs, reasons, timings, and an + opaque `ResumeState` (`src/pipeline/types.rs:252-285`). +- **Why 3 does not fit:** The invalid intermediate occurs for each ordinary + successful stage before durable interpretation, so it is central rather than + an isolated escape hatch. +- **Why 1 does not fit:** `StageOutcome` itself has a stable, typed meaning; the + defect is the recurring string round trip between two typed points. +- **Rule discrimination:** Decision rule 4 is directly discriminating here: + this is exactly a common-path invalid intermediate. + +## `fabro-http` + +### `domain-model`: 4 (High) + +- **Evidence:** `src/lib.rs:23-61` gives proxy behavior a closed + `ProxyPolicy::{System, Disabled}` vocabulary. The environment boundary + accepts case-insensitive valid names, rejects every other value with a typed + `HttpClientBuildError`, handles non-Unicode values explicitly, gives explicit + policy precedence over the environment, and resolves absence to `System`. + Both generated builders invoke this resolver before constructing a client + (`src/lib.rs:72-193`), and the test-client entry points select + `ProxyPolicy::Disabled` rather than passing an unchecked string + (`src/lib.rs:195-213`). +- **Strongest counterevidence:** The facade deliberately exposes reqwest's + lower-level `Proxy` and `.no_proxy()` operations, so callers can compose + transport details outside the two-value environment policy. +- **Why 3 does not fit:** Those operations are typed builder choices, not + unvalidated representations of the `FABRO_HTTP_PROXY_POLICY` value. Every + common construction path still validates that boundary before use; I found no + material meaning or validation friction. +- **Why 1-2 do not fit:** There is one stable meaning, one resolver, and no + recurring conversion through an invalid intermediate. +- **Rule discrimination:** Decision rule 4 could be read ambiguously if every + low-level builder method is called a policy escape hatch. The rubric's own + `ProxyPolicy` example resolves that ambiguity in favor of the closed, + validated environment-policy model. + +### `duplication-knowledge`: 3 (Medium) + +- **Evidence:** `define_builder!` at `src/lib.rs:72-193` is one authoritative + production mechanism for the shared async/blocking builder surface and for + applying the resolved proxy policy. The four convenience constructors route + through those builders. The remaining repeated knowledge is narrow: + `"system"` and `"disabled"` appear both in the parser and in the manually + maintained `InvalidProxyPolicy` expectation text + (`src/lib.rs:29-35,63-69`). +- **Strongest counterevidence:** The macro removes the materially risky + async/blocking synchronization, and the compiler forces the policy-application + match to cover every enum variant. The two test helpers' use of + `ProxyPolicy::Disabled` is ordinary reuse, not a second policy authority. +- **Why 4 does not fit:** The user-facing valid-value list is a small second + representation that can drift from the parser, so there is some isolated + repeated domain knowledge. +- **Why 2 does not fit:** There is no direct evidence that routine changes + repeatedly synchronize separate async/blocking implementations. A future + enum variant is hypothetical, and rule 5 specifically says exhaustive + compiler-checked branches and hypothetical variants do not establish + competing authorities. +- **Rule discrimination:** Rule 5 cleanly rules out 2 but is non-discriminating + between 3 and 4 for a duplicated allowed-value error message. I treat that + message as real but isolated maintenance friction, hence 3. + +## `fabro-web-app` + +### `ownership-boundaries`: 4 (Medium) + +- **Evidence:** `app/entry.tsx:17-48` owns root creation, global SWR policy, + build-version guarding, toast mounting, and the single normal/install router + choice. `app/router.tsx:97-184` owns normal route composition, while + `app/install-router.tsx:6-22` owns the install graph. Shared HTTP translation + and unauthorized handling live in `app/lib/api-client.ts:213-309`; shared + reads such as `useRun` live in `app/lib/queries.ts:182-187`; recurring run + mutations and cache follow-up live in + `app/lib/mutations.ts:65-149`. Route components compose these owners. + Separately, `scripts/build.ts:183-249,289-368` contains the complete + app-local build, atomic publication, and old-build pruning lifecycle and + publishes only `apps/fabro-web/dist`; boundary tooling mirrors that output + into the Rust SPA rather than the web build writing across the boundary. +- **Strongest counterevidence:** Some route-specific CRUD mutations import + `apiData` and generated API objects directly, and the install feature spans + `install-app.tsx`, `install-api.ts`, `install-query.ts`, and effect hooks. + `run-detail.tsx` is also a busy composition point. +- **Why 3 does not fit:** The direct calls remain at the route-specific UX + owner and still use the shared transport/error boundary; shared read and + recurring run-lifecycle responsibilities are not reimplemented there. + Install state, transport, query, and browser effects have distinct homes. + I found no isolated lifecycle that must leave its owner and resupply identity. +- **Why 1-2 do not fit:** Runtime, routing, transport, queries, route UX, and + build publication all have stable owners with dependencies pointing from + composition toward shared services. +- **Rule discrimination:** The final repository example is useful and + discriminating: a large route is not by itself boundary leakage. The score + would change if direct routes reimplemented shared transport or cache + lifecycles, but representative boundary checks did not show that. + +## `repository-ci` + +### `ownership-boundaries`: 4 (Medium) + +- **Evidence:** `.github/workflows/rust.yml:48-147` owns Rust formatting, + lint/architecture checks, generated docs, Linux tests, twin E2E selection, + and manual macOS tests. `.github/workflows/typescript.yml:36-77` owns web and + generated-client typechecks, web tests, and the production embedded-SPA + integration build. Each workflow owns its concurrency and least-privilege job + permissions. The TypeScript workflow's `cargo dev build` is the intentional + integration boundary that consumes the web bundle; it does not create a + competing implementation of the web build. +- **Strongest counterevidence:** The TypeScript build job invokes Rust build + tooling, path scopes overlap around `lib/apps/fabro-spa/**`, and + `.github/zizmor.yml` is configuration whose consumer is not shown in these + files. +- **Why 3 does not fit:** Cross-language integration is part of the mapped CI + purpose and has one concrete home. The stale configuration values discussed + below are domain-model findings, while duplicated push/pull selectors are + duplication findings; counting either again as ownership friction would + violate the rubric's primary-lens rule. +- **Why 1-2 do not fit:** The Rust and TypeScript responsibilities and their + dependency direction are stable. Routine validation changes have an obvious + workflow owner rather than requiring competing lifecycle owners. +- **Rule discrimination:** The instruction not to penalize an unevidenced + missing lifecycle matters for the unseen zizmor consumer. The rubric is + otherwise discriminating once repeated selector policy is kept out of the + ownership lens. + +### `domain-model`: 2 (High) + +- **Evidence:** Both Rust trigger selectors name `openapi/**` + (`.github/workflows/rust.yml:6-19,22-35`), but that revision has no tracked + `openapi/` target. The actual Rust generator and TypeScript generator consume + `docs/public/api-reference/fabro-api.yaml` + (`lib/foundation/fabro-api/build.rs:159` and + `lib/packages/fabro-api-client/package.json:7`), a path omitted from both + workflow trigger models. This makes a core API-spec change invisible to the + intended CI trigger. In addition, all three + `.github/zizmor.yml:4-6` line selectors target + `.github/workflows/rust.yml` lines 37, 49, and 62, which are respectively + `workflow_dispatch`, the `fmt` job key, and a shell `run`, not action + references for `stale-action-refs`. +- **Strongest counterevidence:** Most configured branches, paths, action SHAs, + runner labels, job names, and commands have clear current targets, and both + workflow documents have a stable overall schema. +- **Why 3 does not fit:** The dead OpenAPI selector sits in both central Rust + push and pull-request triggers and omits the actual source of truth. It is not + merely an isolated stale lint suppression. +- **Why 1 does not fit:** The CI configuration language and almost all values + remain interpretable; the problem is recurring invalid/no-target identifiers, + not the absence of a stable configuration model. +- **Rule discrimination:** Decision rule 6 correctly classifies the no-target + identifiers as domain pressure, but it does not itself distinguish 2 from 3. + The centrality of the API source-of-truth trigger is what selects 2. + +## Control: `fabro-checkpoint` + +### `ownership-boundaries`: 2 (High) + +- **Evidence:** Inside the component, `BranchStore` owns a branch string and + author and delegates Git objects to `Store` + (`src/branch.rs:17-82`), which is a sensible direction. At the production + boundary, however, no production caller constructs `BranchStore`. + `fabro-workflow/src/run_metadata.rs:272-451` instead keeps `Store`, branch, + author, `parent_oid`, and discovery state as separate fields, manually writes + blobs and trees, supplies parents to `Store::write_commit`, resupplies the + branch to `Store::update_ref`, and owns fetch/push discovery. Other checkpoint + commit and trailer lifecycle work also remains in `fabro-workflow`. Thus the + mapped checkpoint/metadata-branch lifecycle crosses the scoped owner on the + normal production path. +- **Strongest counterevidence:** `Store` is itself a mapped public entry point, + the dependency direction remains `fabro-workflow -> fabro-checkpoint`, and + remote authentication/push orchestration reasonably belongs near a workflow + run rather than in a low-level Git object store. +- **Why 3 does not fit:** The caller-held branch and parent identity are used on + every metadata snapshot, not only in an isolated migration or uncommon + fallback. +- **Why 1 does not fit:** Low-level Git ownership and the higher workflow + orchestration are both stable and understandable; they simply split one + routine persistence lifecycle. +- **Rule discrimination:** Decision rule 2 is directly discriminating: + `RunMetadataWriter` retains and repeatedly resupplies the identity needed to + complete operations on `Store`. The mapped breadth of “metadata branches” + makes this more than ordinary parameter passing. + +### `simplicity`: 3 (Medium) + +- **Evidence:** The production low-level path is traceable: + `Store::write_blob -> TreeEntries::set -> Store::write_tree -> + Store::write_commit -> Store::update_ref` + (`src/git.rs:123-188`). `BranchStore::write_with` also gives branch-oriented + writes one linear read/modify/write implementation + (`src/branch.rs:56-117`). The recursive flat-tree conversion is justified by + Git's nested tree representation. The friction is isolated: `BranchStore` is + a sizeable second entry layer with tests but no production caller at this + revision, and `Cargo.toml:18` declares `fabro-store` although scoped + production code does not reference it. +- **Strongest counterevidence:** The two entry points represent legitimate + abstraction levels, and the mapped cartography names both. None of the normal + `Store` operations requires navigating configuration machinery or dynamic + dispatch. +- **Why 4 does not fit:** The unused higher layer/dependency is concrete, + avoidable surface and configuration burden, even though it is off the current + production common path. +- **Why 2 does not fit:** Routine production writes do not repeatedly choose + between `Store` and `BranchStore`; the observed caller consistently uses + `Store`, and that path is direct. +- **Rule discrimination:** The “public method alone does not establish + frequency” rule prevents treating `BranchStore` as a competing common path. + It is less discriminating between 3 and 4; the concrete unused dependency and + unused entry layer are why I select 3. + +### `domain-model`: 2 (High) + +- **Evidence:** `GitAuthor::from_options` accepts arbitrary name/email strings + (`src/author.rs:22-30`), while `BranchStore::new` only interprets them by + calling `Signature::now(...).expect(...)` + (`src/branch.rs:26-39`). `TreeEntries` stores paths as unrestricted `String` + and `BranchStore::write_entry/write_entries` put caller strings into it + without validation (`src/git.rs:46-90`, + `src/branch.rs:84-109`); interpretation and possible rejection occur later + while rebuilding Git trees. `FileMode::from_i32` also maps every unknown Git + mode to `Blob` (`src/git.rs:21-36`) rather than preserving or rejecting an + unknown shape. These invalid-capable intermediates sit on the mapped storage + entry paths. +- **Strongest counterevidence:** `FileMode` is closed for values the component + writes, normal metadata callers validate paths before constructing + `TreeEntries`, Git itself rejects malformed signatures/trees, and object IDs + use git2's typed `Oid`. +- **Why 3 does not fit:** Raw author and path values are carried by the ordinary + entry-point types and interpreted later; they are not confined to a separate + compatibility importer. +- **Why 1 does not fit:** Authors, tree entries, modes, branches, and commits all + have stable intended meanings. The issue is delayed validation and lossy + fallback, not an unidentifiable core concept. +- **Rule discrimination:** Decision rule 4 is discriminating here: these are + common-path invalid-capable intermediate shapes rather than a low-level + escape hatch unused by the entry path. + +### `duplication-knowledge`: 3 (Medium) + +- **Evidence:** Important transformations are mostly authoritative: + `FileMode::{as_i32,from_i32}` contains the mode mapping, + `BranchStore::write_with` contains branch read/modify/write, and + `GitAuthor::default` contains the default identity. The narrow repeated + knowledge is the bare-branch to full-ref transformation + `format!("refs/heads/{branch}")` in each of + `Store::{update_ref,resolve_ref,delete_ref}` + (`src/git.rs:182-225`), with another full-ref rendering at the direct + workflow metadata boundary. Trailer rendering also spells + `"{}: {}"` in both `append` and `format_message` + (`src/trailer.rs:9-65`). +- **Strongest counterevidence:** The repeated ref syntax is stable low-level Git + syntax, the three ref methods implement different operations, and the + apparent duplication in single-entry/multi-entry or tip/commit reads has + intentionally different result shapes. Unifying those operations would risk + a parameterized mega-helper. +- **Why 4 does not fit:** Full-ref and trailer-line rendering have small but real + second representations rather than one helper/type enforcing each + transformation. +- **Why 2 does not fit:** There is no direct evidence of routine changes + repeatedly synchronizing those stable renderings, and hypothetical future ref + methods do not satisfy decision rule 5. The repeated knowledge is isolated + from ordinary checkpoint-format extension. +- **Rule discrimination:** Rule 5 usefully rules out 2 but is + non-discriminating between 3 and 4 for repeated, stable protocol syntax. I + score 3 because the repetitions are concrete, while keeping confidence + Medium because their maintenance materiality is limited. + +## Round 2 revalidation + +I independently reapplied the simplified decision rules to only the requested +assignments. Scores below supersede the corresponding Round 1 judgments for +this revalidation. + +| Component | Lens | Round 2 score | Confidence | +| --- | --- | ---: | --- | +| `fabro-http` | duplication-knowledge | 3 | High | +| `repository-ci` | ownership-boundaries | 2 | High | +| `fabro-checkpoint` | ownership-boundaries | 2 | High | +| `fabro-checkpoint` | simplicity | 3 | High | +| `fabro-checkpoint` | domain-model | 2 | High | +| `fabro-checkpoint` | duplication-knowledge | 3 | Medium | + +### `fabro-http` × `duplication-knowledge`: 3 (High) + +- **Decisive evidence:** `define_builder!` remains the one mechanism for the + materially recurring async/blocking builder policy + (`src/lib.rs:72-193`). The parser and `InvalidProxyPolicy` message still hold + a concrete second representation of the allowed `"system"`/`"disabled"` + vocabulary (`src/lib.rs:29-35,63-69`). +- **Adjacent scores:** 4 does not fit because revised rule 6 explicitly caps a + concrete second semantic representation at 3. Score 2 does not fit because an + ordinary mapped change does not currently synchronize separate async and + blocking implementations; adding a future policy variant is not direct + recurrence evidence. +- **Remaining ambiguity:** None material. Revised rule 6 now resolves the prior + 3-versus-4 uncertainty. + +### `repository-ci` × `ownership-boundaries`: 2 (High) + +- **Decisive evidence:** The Rust workflow's architecture check scans + `apps`, `lib/packages`, and + `docs/public/api-reference/fabro-api.yaml` + (`.github/workflows/rust.yml:80-91`), but its push and pull-request triggers + omit all three routine target paths (`rust.yml:6-19,22-35`). Its Cargo jobs + also consume the real API specification through + `lib/foundation/fabro-api/build.rs`, yet that specification does not trigger + the workflow. The TypeScript workflow likewise consumes the generated API + client and performs the embedded integration build without making the source + specification a trigger. Under revised rule 3, each check owns this coverage; + the omitted routine targets are therefore central ownership pressure. +- **Adjacent scores:** 3 does not fit because API, app, and package changes are + routine targets of checks the workflow actually runs, not isolated edge + inputs. Score 1 does not fit because Rust and TypeScript job ownership and + dependency direction otherwise remain stable. +- **Remaining ambiguity:** None material. The nonexistent `openapi/**` value is + still a separate domain-model finding; the ownership finding rests on the + real scanned/consumed paths that fail to trigger. + +### `fabro-checkpoint` × `ownership-boundaries`: 2 (High) + +- **Decisive evidence:** The mapped higher owner is `BranchStore`, but the + routine production metadata caller instead retains `Store`, branch, author, + parent, and discovery state and reconstructs blob/tree/commit/ref lifecycle + from `Store` primitives in + `fabro-workflow/src/run_metadata.rs:272-451`. Revised rule 2 names this shape + directly. +- **Adjacent scores:** 3 does not fit because reconstruction occurs on every + metadata snapshot, not at an isolated edge. Score 1 does not fit because the + low-level `Store` and workflow-level caller are stable, identifiable owners; + the concern is the lifecycle split between them. +- **Remaining ambiguity:** The workflow reasonably owns remote authentication, + but that does not remove its reconstruction of the mapped checkpoint and + metadata-branch persistence lifecycle. + +### `fabro-checkpoint` × `simplicity`: 3 (High) + +- **Decisive evidence:** The current production `Store` write sequence is + linear and direct (`src/git.rs:123-188`). `BranchStore` is a parallel mapped + entry layer with no production caller at this revision, and `Cargo.toml:18` + declares the unused production dependency `fabro-store`. Revised rule 4 + classifies exactly this as isolated simplicity friction that caps 4 at 3. +- **Adjacent scores:** 4 does not fit because the parallel unused layer and + dependency are concrete. Score 2 does not fit because routine callers do not + navigate competing paths or machinery; they consistently follow the direct + `Store` path. +- **Remaining ambiguity:** None material after rule 4. `BranchStore` being a + mapped entry does not make it frequent when the boundary search finds no + production caller. + +### `fabro-checkpoint` × `domain-model`: 2 (High) + +- **Decisive evidence:** Mapped entry shapes accept unrestricted author and path + strings: `GitAuthor::from_options` stores raw values before + `BranchStore::new` interprets them with `Signature::now(...).expect(...)` + (`src/author.rs:22-30`, `src/branch.rs:26-39`), and + `TreeEntries`/`write_entry` carry unchecked string paths until Git-tree + construction (`src/git.rs:46-90`, `src/branch.rs:84-109`). Revised rule 5 + says caller validation and a typed destination do not isolate this + invalid-capable mapped entry. +- **Adjacent scores:** 3 does not fit because the invalid-capable shapes are on + mapped entry paths, not a compatibility-only edge. Score 1 does not fit + because the intended meanings of authors, paths, modes, and commits remain + stable. +- **Remaining ambiguity:** None material. Normal callers supplying valid values + does not make the entry type canonical by construction. + +### `fabro-checkpoint` × `duplication-knowledge`: 3 (Medium) + +- **Decisive evidence:** Bare branch names are independently rendered as + `refs/heads/{branch}` in `Store::update_ref`, `resolve_ref`, and `delete_ref` + (`src/git.rs:182-225`), and trailer lines are independently rendered in + `trailer::append` and `format_message` (`src/trailer.rs:9-65`). These are + concrete second semantic representations, so revised rule 6 excludes 4. +- **Adjacent scores:** 4 does not fit because the second renderings are real. + Score 2 does not fit because no evidenced ordinary mapped change must + synchronize the stable Git ref or trailer syntax across those locations; + future ref operations are hypothetical, while the existing operations have + distinct behavior. +- **Remaining ambiguity:** Limited ambiguity remains over whether stable + protocol syntax is material enough to count as semantic repetition at all. + Rule 6 does not define that threshold, so confidence remains Medium; if it + counts, 3 is the rule-directed score. diff --git a/.chisel/cartography/codebase-map.json b/.chisel/cartography/codebase-map.json new file mode 100644 index 0000000000..42b523f3ff --- /dev/null +++ b/.chisel/cartography/codebase-map.json @@ -0,0 +1,926 @@ +{ + "schema_version": 1, + "cartography_version": 1, + "created_at": "2026-07-27T14:07:02Z", + "repository": { + "name": "fabro", + "root": ".", + "revision": "2bcf94fed8a9b429f18d9196fa824711d6f4cb0a", + "short_revision": "2bcf94fed" + }, + "instructions": [ + "AGENTS.md", + "CLAUDE.md", + "CONTRIBUTING.md" + ], + "overview": "Fabro is a Cargo workspace whose CLI and HTTP server compose shared workflow, agent, model, sandbox, persistence, integration, and foundation crates. A Bun workspace contains the React web application, Astro marketing site, Remotion composition, and OpenAPI-derived TypeScript client tooling; the OpenAPI document is the shared HTTP contract. Public and internal documentation, protocol twins, fixture corpora, evaluation tooling, build/release/deployment automation, and repository-local agent workflows form separate support boundaries around the product runtime.", + "global_exclusions": [ + { + "globs": [ + "lib/packages/fabro-api-client/src/**" + ], + "reason": "Generated TypeScript/Axios output written by the package's pinned OpenAPI Generator command; generated headers and .openapi-generator metadata corroborate the output boundary." + }, + { + "globs": [ + "apps/marketing/.vercel/**" + ], + "reason": "Vercel CLI link metadata whose own README identifies it as automatically created local project/team state." + }, + { + "globs": [ + "lib/apps/fabro-spa/assets/**" + ], + "reason": "Placeholder for ignored embedded-SPA build output; repository instructions and .gitignore identify the directory as generated." + }, + { + "globs": [ + "docs/brainstorms/**", + "docs/ideation/**", + "docs/plans/**", + "docs/superpowers/plans/**", + "docs/superpowers/specs/**", + "docs/internal/cargo-target-apfs-churn-plan.md", + "docs/internal/cli-workflow-coupling-audit.md", + "docs/internal/event-schema-competitive-analysis.md", + "docs/internal/fabro-event-schema-v2-proposal.md", + "docs/internal/mcp-server-qa-test-plan.md", + "docs/internal/plan-events-as-source-of-truth-follow-ups.md", + "docs/internal/plan-events-as-source-of-truth.md", + "docs/internal/slow-test-opportunities-2026-04-07.md" + ], + "reason": "Point-in-time brainstorms, implementation plans, audits, research, handoffs, and superseded proposals rather than maintained source contracts." + }, + { + "globs": [ + "docs/internal/demo/*.svg", + "docs/internal/demo/*.png", + "docs/public/images/*-workflow.svg", + "docs/public/images/tutorial-*.svg", + "docs/public/images/brave-search-research.svg", + "docs/public/images/how-fabro-works.svg", + "docs/public/images/nlspec-conformance.svg", + "docs/public/images/plan-implement-readme.svg" + ], + "reason": "Graphviz-generated SVG and PNG renderings whose executable or documentation graph sources remain assigned." + }, + { + "globs": [ + "docs/internal/licenses/**" + ], + "reason": "Vendored third-party Graphviz license text rather than Fabro source." + }, + { + "globs": [ + "evals/swe-bench/scoreboard/**" + ], + "reason": "Committed evaluation records generated by record_results.py, not executable evaluation source." + }, + { + "globs": [ + ".fabro/skills/rust-style-guide/**" + ], + "reason": "Vendored policy payload copied from the brynary/rust-style-guide repository at a recorded commit." + }, + { + "globs": [ + "Cargo.lock", + "bun.lock" + ], + "reason": "Machine-maintained dependency resolution snapshots consumed in locked or frozen mode." + }, + { + "globs": [ + ".claude/skills/*/watermark" + ], + "reason": "Generated progress-state commit SHAs overwritten by the owning skill workflows." + }, + { + "globs": [ + ".fabro/project.toml.bak" + ], + "reason": "Stale backup of the canonical .fabro/project.toml configuration." + }, + { + "globs": [ + ".fabro/workflows/goal/workflow.svg", + ".github/assets/**" + ], + "reason": "Non-runtime workflow illustration and unreferenced pull-request review screenshots." + }, + { + "globs": [ + "CLAUDE.md", + "install.sh", + "install.md" + ], + "reason": "Tracked symlink aliases whose canonical targets are assigned elsewhere, avoiding duplicate assessment of identical content." + }, + { + "globs": [ + "LICENSE.md" + ], + "reason": "Repository legal text rather than an implementation or documentation component." + } + ], + "components": [ + { + "id": "fabro-cli", + "name": "Fabro CLI Application", + "purpose": "Provides the fabro command-line process, command dispatch, terminal presentation, server bootstrap, and hidden run-worker entry.", + "globs": ["lib/apps/fabro-cli/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-cli/src/main.rs:main", "lib/apps/fabro-cli/src/args.rs:Commands"], + "owns": ["CLI process and command lifecycle, output contracts, command context, local server discovery, and the run-worker subprocess entry"], + "depends_on": ["fabro-acp", "fabro-agent", "fabro-api", "fabro-auth", "fabro-build-support", "fabro-checkpoint", "fabro-client", "fabro-config", "fabro-dump", "fabro-environment", "fabro-github", "fabro-graphviz", "fabro-hooks", "fabro-http", "fabro-install", "fabro-interview", "fabro-llm", "fabro-manifest", "fabro-mcp", "fabro-mcp-server", "fabro-model", "fabro-oauth", "fabro-proc", "fabro-redact", "fabro-sandbox", "fabro-server", "fabro-static", "fabro-store", "fabro-telemetry", "fabro-template", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-vault", "fabro-workflow", "workflow-test-corpus"], + "evidence": ["lib/apps/fabro-cli/Cargo.toml — declares the fabro binary and its direct workspace dependencies", "lib/apps/fabro-cli/src/main.rs:main_inner — constructs shared command state and dispatches the complete command surface"] + }, + { + "id": "fabro-mcp-server", + "name": "Fabro MCP Stdio Server", + "purpose": "Exposes Fabro run operations as an MCP stdio tool service and generates supported MCP client configuration.", + "globs": ["lib/apps/fabro-mcp-server/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-mcp-server/src/lib.rs:start", "lib/apps/fabro-mcp-server/src/config.rs:init_agent"], + "owns": ["MCP stdio service lifecycle, tool router, lazy Fabro client backend, and MCP client configuration updates"], + "depends_on": ["fabro-api", "fabro-client", "fabro-config", "fabro-manifest", "fabro-model", "fabro-server", "fabro-tool", "fabro-types", "fabro-util"], + "evidence": ["lib/apps/fabro-mcp-server/Cargo.toml — declares a distinct MCP server library package", "lib/apps/fabro-mcp-server/src/server.rs:start — owns the rmcp stdio service lifecycle"] + }, + { + "id": "fabro-server", + "name": "Fabro HTTP Server", + "purpose": "Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, workers, schedulers, sessions, authentication, and integrations.", + "globs": ["lib/apps/fabro-server/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-server/src/serve.rs:serve_command", "lib/apps/fabro-server/src/server.rs:build_router"], + "owns": ["Server startup and shutdown, AppState, API and web routing, authentication, scheduling, worker control, and integration coordination"], + "depends_on": ["fabro-agent", "fabro-api", "fabro-auth", "fabro-automation", "fabro-build-support", "fabro-client", "fabro-config", "fabro-db", "fabro-environment", "fabro-github", "fabro-graphviz", "fabro-hooks", "fabro-http", "fabro-http-api-contract", "fabro-install", "fabro-interview", "fabro-llm", "fabro-manifest", "fabro-mcp-store", "fabro-model", "fabro-proc", "fabro-redact", "fabro-sandbox", "fabro-slack", "fabro-spa", "fabro-static", "fabro-store", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-variable", "fabro-vault", "fabro-workflow"], + "evidence": ["lib/apps/fabro-server/Cargo.toml — declares the HTTP server package and its application dependencies", "lib/apps/fabro-server/src/server.rs:AppState — centralizes the service's stores, runtimes, schedulers, credentials, integrations, and shutdown state"] + }, + { + "id": "fabro-spa", + "name": "Embedded SPA Assets", + "purpose": "Provides compile-time embedded production SPA lookup, bytes, and content hashes to the Rust server.", + "globs": ["lib/apps/fabro-spa/Cargo.toml", "lib/apps/fabro-spa/src/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-spa/src/lib.rs:get", "lib/apps/fabro-spa/src/lib.rs:AssetBytes"], + "owns": ["Compile-time SPA embedding, asset lookup, byte and hash metadata, and source-map exclusion"], + "depends_on": [], + "evidence": ["lib/apps/fabro-spa/Cargo.toml — declares a distinct embedded-assets package", "lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets — defines compile-time asset embedding and lookup", "lib/apps/fabro-server/src/static_files.rs — consumes the embedded asset interface"] + }, + { + "id": "fabro-acp", + "name": "Agent Client Protocol Runtime", + "purpose": "Launches and controls Agent Client Protocol processes through Fabro sandboxes and translates their sessions into run results.", + "globs": ["lib/components/fabro-acp/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-acp/src/command.rs:AcpProcessSpec", "lib/components/fabro-acp/src/session.rs:run_acp_turn"], + "owns": ["ACP process specifications, transport and session lifetime, live steering, cancellation, and exit translation"], + "depends_on": ["fabro-sandbox", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-acp/Cargo.toml — declares the ACP backend and optional sandbox runtime edge", "lib/components/fabro-acp/tests/session.rs — exercises the ACP session boundary"] + }, + { + "id": "fabro-agent", + "name": "Coding Agent Runtime", + "purpose": "Runs programmable coding-agent sessions with model profiles, context management, native and MCP tools, permissions, and subagents.", + "globs": ["lib/components/fabro-agent/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-agent/src/session.rs:Session", "lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry"], + "owns": ["Agent session history, prompts and profiles, tool execution, context compaction, permissions, questions, todos, and subagents"], + "depends_on": ["fabro-auth", "fabro-config", "fabro-http", "fabro-llm", "fabro-mcp", "fabro-model", "fabro-sandbox", "fabro-static", "fabro-template", "fabro-types", "fabro-util", "fabro-vault"], + "evidence": ["lib/components/fabro-agent/Cargo.toml — describes a programmable agentic loop and its runtime dependencies", "lib/components/fabro-agent/src/lib.rs — exposes the session, profile, tool, permission, history, and subagent facade"] + }, + { + "id": "fabro-automation", + "name": "Automation Definitions and Storage", + "purpose": "Validates, versions, imports, and durably stores scheduled, API-triggered, and manual automation definitions.", + "globs": ["lib/components/fabro-automation/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-automation/src/store.rs:AutomationStore", "lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once"], + "owns": ["Automation identifiers, targets, triggers, revisions, SQLite records, and legacy import"], + "depends_on": ["fabro-db"], + "evidence": ["lib/components/fabro-automation/Cargo.toml — declares the automation domain and durable storage boundary", "lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs — evolves the owned persistence format"] + }, + { + "id": "fabro-checkpoint", + "name": "Git Checkpoint Storage", + "purpose": "Stores workflow checkpoints and metadata in Git commits and dedicated metadata branches.", + "globs": ["lib/components/fabro-checkpoint/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-checkpoint/src/branch.rs:BranchStore", "lib/components/fabro-checkpoint/src/git.rs:Store"], + "owns": ["Checkpoint commits, Git trees, metadata branches, authorship, trailers, and checkpoint errors"], + "depends_on": ["fabro-config", "fabro-store", "fabro-types"], + "evidence": ["lib/components/fabro-checkpoint/Cargo.toml — identifies Git-backed workflow checkpoint storage", "lib/components/fabro-checkpoint/src/lib.rs — exposes the branch, Git, author, trailer, and error surface"] + }, + { + "id": "fabro-dump", + "name": "Run Dump Materialization", + "purpose": "Materializes stored run projections, events, checkpoints, artifacts, and blobs into a portable directory tree.", + "globs": ["lib/components/fabro-dump/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-dump/src/lib.rs:RunDump", "lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir"], + "owns": ["Dump layout, stage ranking, blob hydration, serialization, and directory writing"], + "depends_on": ["fabro-store", "fabro-types"], + "evidence": ["lib/components/fabro-dump/Cargo.toml — gives the operation a distinct crate and storage dependency", "lib/components/fabro-dump/src/lib.rs:RunDump — contains the public dump-building lifecycle"] + }, + { + "id": "fabro-environment", + "name": "Environment Definitions and Storage", + "purpose": "Validates, seeds, versions, imports, and durably stores server-owned execution environment definitions.", + "globs": ["lib/components/fabro-environment/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-environment/src/store.rs:EnvironmentStore", "lib/components/fabro-environment/src/store.rs:seed_default_environment"], + "owns": ["Environment identifiers, revisions, drafts, SQLite records, built-in seeding, and legacy import"], + "depends_on": ["fabro-config", "fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-environment/Cargo.toml — declares a server-owned environment domain and store", "lib/components/fabro-environment/tests/store.rs — exercises the independent persistence boundary"] + }, + { + "id": "fabro-github", + "name": "GitHub Authentication and API", + "purpose": "Resolves GitHub credentials and performs authenticated App, repository, branch, and pull-request operations.", + "globs": ["lib/components/fabro-github/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-github/src/lib.rs:GitHubCredentials", "lib/components/fabro-github/src/lib.rs:create_pull_request"], + "owns": ["GitHub credentials and token minting, API translation, repository URL handling, and pull-request lifecycle calls"], + "depends_on": ["fabro-http", "fabro-redact", "fabro-static", "fabro-types"], + "evidence": ["lib/components/fabro-github/Cargo.toml — describes the GitHub App authentication and API adapter", "lib/components/fabro-github/src/lib.rs:GitHubContext — defines the credential context and testable HTTP boundary"] + }, + { + "id": "fabro-graphviz", + "name": "Workflow Graph Language", + "purpose": "Parses Graphviz DOT into Fabro's typed graph model and handles conditions, stylesheets, fidelity, and graph rendering.", + "globs": ["lib/components/fabro-graphviz/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-graphviz/src/parser/mod.rs:parse", "lib/components/fabro-graphviz/src/render.rs:render_dot"], + "owns": ["DOT lexer, parser, semantic conversion, graph errors, condition and stylesheet syntax, and rendering normalization"], + "depends_on": ["fabro-types", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-graphviz/Cargo.toml — names the crate as the DOT parser and graph data model", "lib/components/fabro-graphviz/src/parser/mod.rs:parse — is the source-to-typed-graph entry point"] + }, + { + "id": "fabro-hooks", + "name": "Workflow Lifecycle Hooks", + "purpose": "Configures and executes user-defined workflow hooks and bridges tool hooks into the agent runtime.", + "globs": ["lib/components/fabro-hooks/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-hooks/src/runner.rs:HookRunner", "lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback"], + "owns": ["Hook definitions and selection, execution context, result merging, command and HTTP dispatch, and agent bridging"], + "depends_on": ["fabro-agent", "fabro-auth", "fabro-http", "fabro-llm", "fabro-model", "fabro-redact", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-hooks/Cargo.toml — identifies the workflow hook boundary and runtime dependencies", "lib/components/fabro-hooks/tests/host_command_hooks.rs — tests host hooks through the public lifecycle"] + }, + { + "id": "fabro-install", + "name": "Installation Persistence", + "purpose": "Prepares, persists, and rolls back shared CLI/server installation settings, credentials, development tokens, and default environments.", + "globs": ["lib/components/fabro-install/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-install/src/lib.rs:InstallPersistencePlan", "lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct"], + "owns": ["Install persistence plans, settings and environment mutations, vault writes, development tokens, and rollback"], + "depends_on": ["fabro-config", "fabro-db", "fabro-environment", "fabro-static", "fabro-types", "fabro-util", "fabro-vault"], + "evidence": ["lib/components/fabro-install/Cargo.toml — declares shared install primitives for CLI and server", "lib/components/fabro-install/src/lib.rs:InstallPersistencePlan — groups the files, tokens, and vault state committed by one install"] + }, + { + "id": "fabro-interview", + "name": "Human Interaction Runtime", + "purpose": "Represents workflow questions and answers and provides console, callback, queue, control, recording, replay, and automatic interviewer implementations.", + "globs": ["lib/components/fabro-interview/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-interview/src/lib.rs:Interviewer", "lib/components/fabro-interview/src/control.rs:ControlInterviewer"], + "owns": ["Question and answer protocol, interviewer request lifetime, timeout behavior, delivery, recording, and replay"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-interview/Cargo.toml — defines interviewer traits and implementations as one crate", "lib/components/fabro-interview/src/lib.rs:Interviewer — is the shared asynchronous human-interaction interface"] + }, + { + "id": "fabro-llm", + "name": "Unified LLM Client", + "purpose": "Provides a provider-neutral generation API with routing, middleware, retries, token and cost accounting, provider adapters, and wire codecs.", + "globs": ["lib/components/fabro-llm/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-llm/src/client.rs:Client", "lib/components/fabro-llm/src/provider.rs:ProviderAdapter"], + "owns": ["Normalized generation types, adapter registry, provider authentication and transport, codecs, retries, middleware, and accounting"], + "depends_on": ["fabro-auth", "fabro-http", "fabro-model", "fabro-redact", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-llm/Cargo.toml — declares the unified multi-provider client", "lib/components/fabro-llm/tests/it/wire/mod.rs — verifies provider codecs against one normalized boundary"] + }, + { + "id": "fabro-manifest", + "name": "Run Manifest Construction", + "purpose": "Resolves workflow and configuration inputs, collects static dependencies, and constructs self-contained run manifests with Git provenance.", + "globs": ["lib/components/fabro-manifest/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-manifest/src/lib.rs:build_run_manifest", "lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput"], + "owns": ["Manifest input and output, configuration resolution, workflow dependency collection, Git context, and pre-run push preparation"], + "depends_on": ["fabro-api", "fabro-config", "fabro-github", "fabro-graphviz", "fabro-template", "fabro-types", "fabro-workflow"], + "evidence": ["lib/components/fabro-manifest/Cargo.toml — declares manifest construction and its graph, Git, and workflow dependencies", "lib/components/fabro-manifest/src/lib.rs:build_run_manifest — is the shared assembly operation used by CLI, server, and MCP server"] + }, + { + "id": "fabro-mcp", + "name": "MCP Client Runtime", + "purpose": "Connects to configured Model Context Protocol servers, manages connections, discovers tools, and dispatches qualified calls.", + "globs": ["lib/components/fabro-mcp/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-mcp/src/client.rs:McpClient", "lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager"], + "owns": ["MCP client connections, stdio and HTTP transports, connection-manager state, tool discovery, and result conversion"], + "depends_on": ["fabro-config", "fabro-http", "fabro-types"], + "evidence": ["lib/components/fabro-mcp/Cargo.toml — declares the MCP client and transport features", "lib/components/fabro-mcp/tests/stdio_integration.rs — verifies the external process boundary over stdio"] + }, + { + "id": "fabro-mcp-store", + "name": "MCP Server Catalog Storage", + "purpose": "Durably stores, revisions, caches, and imports server-managed MCP server definitions.", + "globs": ["lib/components/fabro-mcp-store/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-mcp-store/src/store.rs:McpServerStore", "lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once"], + "owns": ["MCP definition records, optimistic revisions, catalog cache, and legacy directory import"], + "depends_on": ["fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-mcp-store/Cargo.toml — declares durable MCP catalog storage", "lib/components/fabro-mcp-store/src/lib.rs — explicitly assigns persistence ownership to this crate"] + }, + { + "id": "fabro-sandbox", + "name": "Execution Sandbox Abstraction", + "purpose": "Defines sandbox and provider contracts and implements local, Docker, and Daytona execution lifecycles.", + "globs": ["lib/components/fabro-sandbox/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-sandbox/src/sandbox.rs:Sandbox", "lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry"], + "owns": ["Sandbox filesystem, process, and terminal interface; provider lifecycle; clone setup; reconnect behavior; and provider implementations"], + "depends_on": ["fabro-config", "fabro-github", "fabro-http", "fabro-proc", "fabro-redact", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-sandbox/Cargo.toml — defines provider features around a common sandbox crate", "lib/components/fabro-sandbox/src/provider.rs:SandboxProvider — separates provider lifecycle from per-sandbox operations"] + }, + { + "id": "fabro-slack", + "name": "Slack Interaction Integration", + "purpose": "Connects to Slack Socket Mode and translates questions, answers, run events, and threads between Slack and Fabro.", + "globs": ["lib/components/fabro-slack/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-slack/src/connection.rs:run", "lib/components/fabro-slack/src/client.rs:SlackClient"], + "owns": ["Slack credentials, Socket Mode lifecycle, API client, block rendering, payload parsing, thread registry, and dispatch"], + "depends_on": ["fabro-http", "fabro-interview", "fabro-static", "fabro-types", "fabro-workflow"], + "evidence": ["lib/components/fabro-slack/Cargo.toml — declares the Slack interviewer integration", "lib/components/fabro-slack/src/connection.rs:run — owns the Socket Mode event loop"] + }, + { + "id": "fabro-store", + "name": "Run and Authentication Persistence", + "purpose": "Persists run events, projections, blobs, artifacts, summaries, catalog indexes, and authentication grants over SlateDB, object storage, and SQLite.", + "globs": ["lib/components/fabro-store/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-store/src/slate/mod.rs:Database", "lib/components/fabro-store/src/run_state.rs:RunProjectionReducer"], + "owns": ["Run event and projection lifecycle, blob and artifact layout, summary indexes, auth records, locking, and storage errors"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-store/src/lib.rs — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth", "lib/components/fabro-store/src/slate/mod.rs:Database — is the shared storage root for the owned stores"] + }, + { + "id": "fabro-tool", + "name": "Run-Control Tools", + "purpose": "Defines and executes shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend.", + "globs": ["lib/components/fabro-tool/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-tool/src/common.rs:FabroToolBackend", "lib/components/fabro-tool/src/common.rs:tool_definitions"], + "owns": ["Tool names and schemas, parameter validation, backend-neutral operations, result records, and text rendering"], + "depends_on": ["fabro-api", "fabro-client", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-tool/Cargo.toml — identifies shared run-control tool behavior over API/client contracts", "lib/components/fabro-tool/src/common.rs:FabroToolBackend — is the abstraction shared by CLI, server, workflow, and MCP server"] + }, + { + "id": "fabro-tracker", + "name": "Issue Tracker Adapters", + "purpose": "Provides a common issue-tracker interface with GitHub Projects and Linear implementations.", + "globs": ["lib/components/fabro-tracker/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-tracker/src/lib.rs:Tracker", "lib/components/fabro-tracker/src/github.rs:GitHubTracker"], + "owns": ["Normalized issues and blockers, candidate selection and transitions, and GitHub Projects and Linear GraphQL adapters"], + "depends_on": ["fabro-github", "fabro-http"], + "evidence": ["lib/components/fabro-tracker/Cargo.toml — declares the tracker trait and provider adapters", "lib/components/fabro-tracker/src/lib.rs:Tracker — defines the provider-neutral issue workflow"] + }, + { + "id": "fabro-validate", + "name": "Workflow Graph Validation", + "purpose": "Runs built-in and catalog-aware lint rules over typed workflow graphs and returns structured diagnostics.", + "globs": ["lib/components/fabro-validate/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-validate/src/lib.rs:validate", "lib/components/fabro-validate/src/lib.rs:LintRule"], + "owns": ["Validation diagnostics, rule interface and registry, graph and catalog traversal, and error escalation"], + "depends_on": ["fabro-acp", "fabro-graphviz", "fabro-model", "fabro-types", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-validate/Cargo.toml — declares graph validation and its graph/catalog dependencies", "lib/components/fabro-validate/src/rules/mod.rs:built_in_rules — forms the explicit built-in rule registry"] + }, + { + "id": "fabro-variable", + "name": "Workflow Variable Storage", + "purpose": "Validates, durably stores, snapshots, and imports workflow-visible non-sensitive variables.", + "globs": ["lib/components/fabro-variable/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-variable/src/lib.rs:VariableStore", "lib/components/fabro-variable/src/lib.rs:import_legacy_json_once"], + "owns": ["Variable validation, SQLite records, render-context snapshots, and legacy JSON import"], + "depends_on": ["fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-variable/Cargo.toml — defines workflow-visible variables as a storage concern", "lib/components/fabro-variable/tests/store.rs — verifies its independent persistence and import contract"] + }, + { + "id": "fabro-workflow", + "name": "Workflow Orchestration Engine", + "purpose": "Transforms, validates, initializes, executes, persists, resumes, and finalizes graph-defined Fabro runs.", + "globs": ["lib/components/fabro-workflow/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-workflow/src/operations/start.rs:start", "lib/components/fabro-workflow/src/pipeline/execute.rs:execute"], + "owns": ["Run operations, workflow phases, node handlers, run services, events, checkpoints, Git, artifacts, hooks, status, steering, and cancellation"], + "depends_on": ["fabro-acp", "fabro-agent", "fabro-auth", "fabro-checkpoint", "fabro-config", "fabro-core", "fabro-dump", "fabro-github", "fabro-graphviz", "fabro-hooks", "fabro-http", "fabro-interview", "fabro-llm", "fabro-mcp", "fabro-model", "fabro-redact", "fabro-sandbox", "fabro-static", "fabro-store", "fabro-template", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-vault", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-workflow/Cargo.toml — declares the DOT-based runner and component dependencies", "lib/components/fabro-workflow/src/pipeline/mod.rs — exposes the ordered transform, validate, initialize, execute, and finalize phases"] + }, + { + "id": "fabro-build-support", + "name": "Rust Build-Script Support", + "purpose": "Supplies shared compile-time Git and Cargo profile metadata to Fabro application build scripts.", + "globs": ["lib/foundation/build-support/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/build-support/git_metadata.rs:collect_from", "lib/foundation/build-support/git_metadata.rs:cargo_profile"], + "owns": ["Compile-time Git SHA discovery, Cargo rerun paths, and profile discovery"], + "depends_on": [], + "evidence": ["lib/foundation/build-support/Cargo.toml — declares the shared build-support package", "lib/foundation/build-support/git_metadata.rs:BuildGitMetadata — defines build-script Git and profile metadata", "lib/apps/fabro-cli/build.rs — consumes the shared metadata collector", "lib/apps/fabro-server/build.rs — consumes the shared metadata collector"] + }, + { + "id": "fabro-build-tooling", + "name": "Fabro Build and Developer Tooling", + "purpose": "Runs repository build, documentation, SPA, container, benchmark, release, and test-support automation.", + "globs": ["lib/foundation/fabro-dev/**", "test/bin/release_test.sh", "test/analysis/bench-tests-diff.sql"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-dev/src/main.rs:main"], + "owns": ["Developer CLI dispatch, subprocess plans, generated-reference checks, build and release workflows, and benchmark analysis"], + "depends_on": ["container-packaging-and-deployment", "fabro-cli", "fabro-config", "fabro-macros-metadata", "fabro-spa", "fabro-util", "fabro-web-app", "public-documentation", "repository-development-policy"], + "evidence": ["lib/foundation/fabro-dev/src/lib.rs:Command — dispatches build, Docker, docs, release, SPA, and benchmark commands"] + }, + { + "id": "fabro-api", + "name": "Generated Rust API Client", + "purpose": "Generates the low-level Rust HTTP client and API type facade from OpenAPI while reusing canonical product types and verifying wire parity.", + "globs": ["lib/foundation/fabro-api/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-api/build.rs:main", "lib/foundation/fabro-api/src/lib.rs:ApiClient"], + "owns": ["OpenAPI compatibility transformations, generation settings, type replacement map, generated-client facade, and wire/type parity tests"], + "depends_on": ["fabro-automation", "fabro-config", "fabro-environment", "fabro-http-api-contract", "fabro-model", "fabro-types"], + "evidence": ["lib/foundation/fabro-api/build.rs:main — reads the OpenAPI contract and writes generated Rust code to OUT_DIR", "lib/foundation/fabro-api/tests/run_event_round_trip.rs — verifies identity and JSON parity for canonical reused types"] + }, + { + "id": "fabro-auth", + "name": "Provider Credential Resolution", + "purpose": "Resolves provider credentials and headers from environment or vault sources, refreshes OAuth credentials, and drives authentication strategies.", + "globs": ["lib/foundation/fabro-auth/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver", "lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy"], + "owns": ["Credential-source precedence, provider discovery, OAuth refresh and write-back, header interpolation, and interactive auth state"], + "depends_on": ["fabro-http", "fabro-model", "fabro-oauth", "fabro-redact", "fabro-static", "fabro-types", "fabro-vault"], + "evidence": ["lib/foundation/fabro-auth/Cargo.toml — declares typed provider credential resolution", "lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve — composes catalog policy, source lookup, headers, and refresh"] + }, + { + "id": "fabro-client", + "name": "High-Level Fabro Service Client", + "purpose": "Provides an authenticated Fabro service client over HTTP or Unix sockets with endpoint wrappers, SSE streams, refresh, and local auth storage.", + "globs": ["lib/foundation/fabro-client/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect", "lib/foundation/fabro-client/src/target.rs:ServerTarget"], + "owns": ["Connected transport state, operation wrappers, SSE buffering, token refresh, target normalization, and per-server CLI auth files"], + "depends_on": ["fabro-api", "fabro-http", "fabro-model", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-client/Cargo.toml — distinguishes the high-level client from the generated API client", "lib/foundation/fabro-client/src/client.rs:ClientState — owns transport, generated client, token, URL, and refresh coordination"] + }, + { + "id": "fabro-config", + "name": "Layered Configuration and Runtime Paths", + "purpose": "Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical paths.", + "globs": ["lib/foundation/fabro-config/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder", "lib/foundation/fabro-config/src/resolve/mod.rs"], + "owns": ["Source layers and merge semantics, defaults, parsing and validation, migrations, home/storage/runtime paths, daemon, envfile, and logging configuration"], + "depends_on": ["fabro-macros-metadata", "fabro-model", "fabro-proc", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-config/Cargo.toml — declares the centralized configuration crate", "lib/foundation/fabro-config/src/builders.rs — composes defaults and layers into dense runtime settings"] + }, + { + "id": "fabro-core", + "name": "Generic Graph Execution Kernel", + "purpose": "Executes generic directed graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts.", + "globs": ["lib/foundation/fabro-core/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-core/src/executor.rs:Executor::run", "lib/foundation/fabro-core/src/handler.rs:NodeHandler"], + "owns": ["Execution state, graph traversal, handler and lifecycle contracts, retry and visit decisions, cancellation, and stall watchdog"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-core/Cargo.toml — identifies a generic kernel without higher-level workflow dependencies", "lib/foundation/fabro-core/src/executor.rs:Executor::run — owns the traversal and execution lifecycle"] + }, + { + "id": "fabro-db", + "name": "Shared SQLite Database Foundation", + "purpose": "Opens and migrates the shared SQLite database, manages rollback snapshots and permissions, and defines the bundled schema.", + "globs": ["lib/foundation/fabro-db/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-db/src/lib.rs:Database::connect", "lib/foundation/fabro-db/src/lib.rs:Database::migrate"], + "owns": ["SQLite pool policy, migration registry, snapshots, backup paths, permissions, tables, and indexes"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-db/Cargo.toml — declares the shared SQLite foundation", "lib/foundation/fabro-db/migrations/2026071101_secrets.sql — is one migration in the compiled shared schema"] + }, + { + "id": "fabro-http", + "name": "Shared HTTP Transport Construction", + "purpose": "Centralizes reqwest type exposure and synchronous and asynchronous HTTP client construction with Fabro proxy policy.", + "globs": ["lib/foundation/fabro-http/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder", "lib/foundation/fabro-http/src/lib.rs:test_http_client"], + "owns": ["Approved reqwest facade, proxy-policy resolution, client builders, and deterministic no-proxy test clients"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-http/Cargo.toml — declares the shared reqwest wrapper", "lib/foundation/fabro-http/src/lib.rs:ProxyPolicy — defines the common transport-construction policy"] + }, + { + "id": "fabro-macros-metadata", + "name": "Compile-Time Macros and Option Metadata", + "purpose": "Supplies Fabro derive and attribute macros plus the runtime option-metadata model used by configuration and documentation tooling.", + "globs": ["lib/foundation/fabro-macros/**", "lib/foundation/fabro-options-metadata/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata", "lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata"], + "owns": ["Macro expansion for E2E gates, layer combination, and option metadata plus the runtime visitor and option-tree representation"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl — generates implementations against the runtime metadata crate", "lib/foundation/fabro-macros/tests/options_metadata.rs — tests the compiler/runtime pair together"] + }, + { + "id": "fabro-model", + "name": "LLM Model and Provider Catalog", + "purpose": "Defines provider and model identity, capabilities, billing metadata, embedded catalog data, override merging, and selection.", + "globs": ["lib/foundation/fabro-model/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin", "lib/foundation/fabro-model/src/catalog.rs:Catalog::select"], + "owns": ["Provider and model IDs, catalog sources and indexes, auth declarations, capabilities, controls, codecs, reasoning, pricing, and billing"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-model/Cargo.toml — names model metadata and resolution as the crate responsibility", "lib/foundation/fabro-model/src/catalog/providers/openai.toml — is one tracked built-in provider catalog source"] + }, + { + "id": "fabro-oauth", + "name": "OAuth PKCE and Callback Flow", + "purpose": "Implements generic OAuth PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh.", + "globs": ["lib/foundation/fabro-oauth/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow", "lib/foundation/fabro-oauth/src/lib.rs:refresh_token"], + "owns": ["PKCE and state, authorization URLs, callback listener and shutdown, callback validation, exchange, and refresh"], + "depends_on": ["fabro-http", "fabro-redact", "fabro-static", "fabro-util"], + "evidence": ["lib/foundation/fabro-oauth/Cargo.toml — declares a generic OAuth 2.0 PKCE flow", "lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle — owns the ephemeral callback server lifecycle"] + }, + { + "id": "fabro-proc", + "name": "OS Process Primitives", + "purpose": "Wraps platform process primitives for signals, groups, advisory locks, pre-exec hooks, liveness, and process-title rewriting.", + "globs": ["lib/foundation/fabro-proc/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-proc/src/signal.rs:process_running", "lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid"], + "owns": ["Unix signals and process groups, cross-platform liveness, locks, child pre-exec configuration, and argv/title state"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-proc/Cargo.toml — describes safe process-management wrappers", "lib/foundation/fabro-proc/c/capture_argv.c — establishes the FFI boundary for title rewriting"] + }, + { + "id": "fabro-redact", + "name": "Secret and Credential Redaction", + "purpose": "Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded rules and entropy scanning.", + "globs": ["lib/foundation/fabro-redact/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-redact/src/lib.rs:redact_string", "lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl"], + "owns": ["Rule source and engine, entropy thresholds, overlap merging, structured redaction policy, and safe URL display"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-redact/build.rs:main — compiles the tracked Gitleaks rule source into OUT_DIR", "lib/foundation/fabro-redact/src/lib.rs:redact_string — composes entropy and rule-based detection"] + }, + { + "id": "fabro-static", + "name": "Shared Static Conventions", + "purpose": "Defines dependency-light canonical environment-variable names and registries for bootstrap and optional vault secrets.", + "globs": ["lib/foundation/fabro-static/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-static/src/env_vars.rs:EnvVars", "lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret"], + "owns": ["Canonical environment names and bootstrap and optional secret classification"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-static/Cargo.toml — declares a no-dependency static registry", "lib/foundation/fabro-static/src/env_vars.rs:EnvVars — centralizes environment names used across the workspace"] + }, + { + "id": "fabro-telemetry", + "name": "Analytics and Crash Telemetry", + "purpose": "Initializes analytics and crash reporting, builds anonymous context, buffers events, and delivers them across CLI and server lifecycles.", + "globs": ["lib/foundation/fabro-telemetry/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-telemetry/src/lib.rs:init_cli", "lib/foundation/fabro-telemetry/src/lib.rs:shutdown"], + "owns": ["Process-global telemetry state, identifiers, buffer thread, event context, command sanitization, Segment delivery, and panic capture"], + "depends_on": ["fabro-http", "fabro-static", "fabro-util"], + "evidence": ["lib/foundation/fabro-telemetry/Cargo.toml — declares analytics and crash reporting", "lib/foundation/fabro-telemetry/src/lib.rs:Global — owns sender, identity, context, level, and background thread"] + }, + { + "id": "fabro-template", + "name": "Template Rendering and Dependency Discovery", + "purpose": "Renders MiniJinja templates with source-aware diagnostics, rooted stores, wrappers, and static dependency discovery.", + "globs": ["lib/foundation/fabro-template/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-template/src/lib.rs:render_named", "lib/foundation/fabro-template/src/store.rs:TemplateStore"], + "owns": ["Template context, render modes, diagnostics, include safety, stores, caching and recording, and dependency closure"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-template/Cargo.toml — declares the shared rendering boundary", "lib/foundation/fabro-template/src/dependency.rs — owns include and import extraction and closure discovery"] + }, + { + "id": "fabro-test", + "name": "Shared Integration-Test Infrastructure", + "purpose": "Provides isolated CLI/server test contexts, twin and live mode control, process harnessing, snapshot normalization, and HTTP assertions.", + "globs": ["lib/foundation/fabro-test/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-test/src/lib.rs:TestContext", "lib/foundation/fabro-test/src/lib.rs:TestMode"], + "owns": ["Temporary test home and storage, managed processes, mode and secret gating, environment isolation, snapshot filters, twins, and HTTP diagnostics"], + "depends_on": ["fabro-config", "fabro-http", "fabro-install", "fabro-proc", "fabro-static", "fabro-types", "fabro-util", "twin-github", "twin-openai", "workflow-test-corpus"], + "evidence": ["lib/foundation/fabro-test/Cargo.toml — declares shared integration-test utilities and twin dependencies", "lib/foundation/fabro-test/src/lib.rs:TestContext — owns isolated paths, subprocesses, filters, and managed server state"] + }, + { + "id": "fabro-types", + "name": "Shared Product Contracts and State Records", + "purpose": "Defines serializable identifiers, settings, run and session events, projections, and other product vocabulary exchanged across Fabro boundaries.", + "globs": ["lib/foundation/fabro-types/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-types/src/lib.rs", "lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent"], + "owns": ["Canonical serde shapes and IDs for runs, stages, sessions, events, settings, projections, sandboxes, integrations, billing, and repositories"], + "depends_on": ["fabro-model", "fabro-util"], + "evidence": ["lib/foundation/fabro-types/Cargo.toml — describes shared record structs and enums", "lib/foundation/fabro-types/src/lib.rs — is the single facade for canonical product vocabulary"] + }, + { + "id": "fabro-util", + "name": "Cross-Cutting Runtime and CLI Utilities", + "purpose": "Provides shared environment, filesystem, shell, terminal, logging, token, error, time, backoff, warning, and glob primitives.", + "globs": ["lib/foundation/fabro-util/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-util/src/lib.rs", "lib/foundation/fabro-util/src/shell.rs:shell_quote"], + "owns": ["Low-level helper contracts plus warning, buffered log, environment, home, token, terminal, backoff, error, and glob state"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-util/Cargo.toml — identifies shared runtime and terminal helpers", "lib/foundation/fabro-util/src/run_log.rs — owns the buffered run-log guard lifecycle"] + }, + { + "id": "fabro-vault", + "name": "Secret Vault and SQLite Store", + "purpose": "Validates and stores workflow-visible secrets in file, memory, or SQLite stores with revision-aware updates and legacy import.", + "globs": ["lib/foundation/fabro-vault/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-vault/src/lib.rs:Vault::load", "lib/foundation/fabro-vault/src/store.rs:SecretStore::open"], + "owns": ["Secret validation and redacted entries, atomic file persistence, SQL CRUD, revisions, snapshots, and legacy import"], + "depends_on": ["fabro-db", "fabro-static", "fabro-types"], + "evidence": ["lib/foundation/fabro-vault/Cargo.toml — declares workflow-visible secret storage", "lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision — exposes concurrent refresh write-back semantics"] + }, + { + "id": "fabro-web-app", + "name": "Fabro Browser Application", + "purpose": "Builds and runs the React SPA for normal operations and first-run installation.", + "globs": ["apps/fabro-web/**"], + "exclude_globs": ["apps/fabro-web/app/components/playground/**"], + "entry_points": ["apps/fabro-web/app/entry.tsx", "apps/fabro-web/scripts/build.ts"], + "owns": ["Browser bundle and route graphs, install flow, shared browser runtime and UI, product operations UX, and public assets"], + "depends_on": ["fabro-api-client-generation", "fabro-http-api-contract", "fabro-workflow-playground"], + "evidence": ["apps/fabro-web/package.json — declares the React application, custom build, tests, and API-client workspace edge", "apps/fabro-web/app/entry.tsx — creates the browser root and selects normal or install routing"] + }, + { + "id": "fabro-workflow-playground", + "name": "Browser Workflow Playground", + "purpose": "Provides a self-contained workflow drafting, simulation, chat, visualization, file-generation, download, and run-launch surface.", + "globs": ["apps/fabro-web/app/components/playground/**"], + "exclude_globs": [], + "entry_points": ["apps/fabro-web/app/components/playground/playground.tsx:Playground", "apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft"], + "owns": ["Workflow draft schema and persistence, simulation, canvas, chat adaptation, generated project files, download, and launch controls"], + "depends_on": ["fabro-http-api-contract", "fabro-web-app"], + "evidence": ["apps/fabro-web/app/components/playground/playground.tsx:Playground — exposes a prop boundary framed for re-embedding", "apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft — owns versioned browser persistence"] + }, + { + "id": "fabro-marketing-site", + "name": "Fabro Marketing Site", + "purpose": "Builds and deploys the public Fabro site with landing content, blog, roadmap, showcase, install resources, and social assets.", + "globs": ["apps/marketing/**", "test/bin/install_test.sh"], + "exclude_globs": ["apps/marketing/.vercel/**"], + "entry_points": ["apps/marketing/src/pages/index.astro", "apps/marketing/astro.config.mjs", "apps/marketing/public/install.sh"], + "owns": ["Astro routes and layout, content collections, marketing presentation, workflow showcases, install resources, redirects, and deployment configuration"], + "depends_on": [], + "evidence": ["apps/marketing/package.json — declares an independent Astro application", "apps/marketing/src/content.config.ts — defines typed roadmap, blog, and showcase collections", "test/bin/install_test.sh — black-box tests the site's canonical install script"] + }, + { + "id": "fabro-remotion-video", + "name": "Fabro Remotion Composition", + "purpose": "Renders the branded FabroIntro motion-graphics video.", + "globs": ["apps/remotion/**"], + "exclude_globs": [], + "entry_points": ["apps/remotion/src/index.ts", "apps/remotion/src/Root.tsx:RemotionRoot"], + "owns": ["Composition registration, frame timeline, image format, logo animation, brand assets, and rendered-video lifecycle"], + "depends_on": [], + "evidence": ["apps/remotion/package.json — declares an independent Remotion project and render target", "apps/remotion/src/Root.tsx:RemotionRoot — declares composition identity, dimensions, frame rate, and duration"] + }, + { + "id": "fabro-api-client-generation", + "name": "TypeScript API Client Generation", + "purpose": "Configures, normalizes, and type-checks the generated TypeScript/Axios client for the Fabro HTTP contract.", + "globs": ["lib/packages/fabro-api-client/package.json", "lib/packages/fabro-api-client/openapitools.json", "lib/packages/fabro-api-client/scripts/**", "lib/packages/fabro-api-client/tests/**", "lib/packages/fabro-api-client/tsconfig.json"], + "exclude_globs": [], + "entry_points": ["lib/packages/fabro-api-client/package.json:scripts.generate", "lib/packages/fabro-api-client/scripts/normalize-generated.ts"], + "owns": ["Generator versions and options, output location, normalization, strict compilation, and hand-written generated-shape invariants"], + "depends_on": ["fabro-http-api-contract"], + "evidence": ["lib/packages/fabro-api-client/package.json — invokes pinned OpenAPI Generator against the shared YAML and writes src", "lib/packages/fabro-api-client/tests/principal-exhaustive.ts — asserts a generated union contract at compile time"] + }, + { + "id": "public-documentation", + "name": "Public Documentation", + "purpose": "Owns authored Fabro user documentation, Mintlify presentation, the repository landing page, and published web-screenshot maintenance.", + "globs": ["README.md", "docs/public/**", "docs/internal/updating-web-screenshots.md"], + "exclude_globs": ["docs/public/api-reference/fabro-api.yaml", "docs/public/changelog/**", "docs/public/images/*-workflow.svg", "docs/public/images/tutorial-*.svg", "docs/public/images/brave-search-research.svg", "docs/public/images/how-fabro-works.svg", "docs/public/images/nlspec-conformance.svg", "docs/public/images/plan-implement-readme.svg"], + "entry_points": ["README.md", "docs/public/docs.json", "docs/public/getting-started/introduction.mdx"], + "owns": ["Mintlify navigation and presentation, public guides and reference prose, curated images and screenshots, syntax definitions, and repository overview"], + "depends_on": ["documentation-demo-workflows", "fabro-cli", "fabro-http-api-contract", "public-release-history"], + "evidence": ["docs/public/docs.json — declares the Mintlify theme, navigation, OpenAPI, and changelog surfaces", "README.md — links to the published docs and embeds their canonical assets", "docs/internal/updating-web-screenshots.md — defines the screenshot capture and verification workflow"] + }, + { + "id": "public-release-history", + "name": "Published Changelog", + "purpose": "Preserves and publishes dated user-facing release and change records independently of current reference documentation.", + "globs": ["docs/public/changelog/**"], + "exclude_globs": [], + "entry_points": ["docs/public/changelog/2026-07-25.mdx"], + "owns": ["Dated titles, migration warnings, feature summaries, and historical behavior notes"], + "depends_on": ["public-documentation"], + "evidence": ["docs/public/docs.json — gives the changelog its own top-level tab and enumerates every page", "docs/public/changelog/2026-07-25.mdx — is the newest dated release entry at the assessed revision"] + }, + { + "id": "fabro-http-api-contract", + "name": "Fabro HTTP API Contract", + "purpose": "Defines the OpenAPI-first wire contract used by the server, generated clients, conformance tests, and published API reference.", + "globs": ["docs/public/api-reference/fabro-api.yaml"], + "exclude_globs": [], + "entry_points": ["docs/public/api-reference/fabro-api.yaml"], + "owns": ["HTTP routes, request and response schemas, authentication declarations, and API-facing wire documentation"], + "depends_on": [], + "evidence": ["AGENTS.md — identifies the OpenAPI file as the HTTP interface source of truth", "lib/foundation/fabro-api/build.rs:main — consumes the contract for Rust generation", "lib/apps/fabro-server/tests/it/openapi_conformance.rs — reads it for router conformance"] + }, + { + "id": "documentation-demo-workflows", + "name": "Executable Documentation Demos", + "purpose": "Provides runnable workflow definitions, configuration, and prompts used by public tutorials and demonstrations.", + "globs": ["docs/internal/demo/*.fabro", "docs/internal/demo/*.toml", "docs/internal/demo/prompts/**"], + "exclude_globs": [], + "entry_points": ["docs/internal/demo/01-hello.fabro", "docs/internal/demo/14-search-imagegen.toml"], + "owns": ["Executable example graphs, the image-generation run configuration, and shared demo prompt text"], + "depends_on": ["fabro-cli", "fabro-sandbox", "fabro-workflow"], + "evidence": ["docs/public/tutorials/hello-world.mdx — invokes a demo workflow path directly", "docs/internal/demo/14-search-imagegen.toml — selects the demo graph, environment, and output assets"] + }, + { + "id": "internal-engineering-guidance", + "name": "Internal Engineering Guidance", + "purpose": "Records active repository-wide engineering policies and maintained architecture and runtime contracts.", + "globs": ["docs/internal/*-strategy.md", "docs/internal/*-policy.md", "docs/internal/events.md", "docs/internal/fabro-event-schema-v2-concrete-shape.md", "docs/internal/llm-client-resolution.md", "docs/internal/run-directory-keys.md"], + "exclude_globs": [], + "entry_points": ["docs/internal/events-strategy.md", "docs/internal/testing-strategy.md", "docs/internal/error-handling-strategy.md"], + "owns": ["Logging, events, testing, migrations, secrets, error handling, React effects, panic, event catalog, LLM resolution, parallelism, and run-file guidance"], + "depends_on": ["fabro-cli", "fabro-config", "fabro-server", "fabro-types", "fabro-web-app", "fabro-workflow"], + "evidence": ["AGENTS.md — makes the strategy and policy documents mandatory before related changes", "docs/internal/events.md — is the maintained serialized event catalog"] + }, + { + "id": "product-context", + "name": "Internal Product Context", + "purpose": "Maintains product intent, audience, current shape, success signals, and stable technical and product constraints.", + "globs": ["docs/internal/product/**"], + "exclude_globs": [], + "entry_points": ["docs/internal/product/product-description.md", "docs/internal/product/current-state.md"], + "owns": ["Business problem, personas, product description, current state, success metrics, and product-level technical requirements"], + "depends_on": [], + "evidence": ["docs/internal/product/current-state.md — identifies itself as a concise current product snapshot", "docs/internal/product/technical-requirements.md — records stable constraints for product changes"] + }, + { + "id": "twin-openai", + "name": "OpenAI Protocol Twin", + "purpose": "Provides a deterministic OpenAI-compatible HTTP service for black-box and protocol-contract tests.", + "globs": ["test/twin/openai/**"], + "exclude_globs": [], + "entry_points": ["test/twin/openai/src/main.rs:main", "test/twin/openai/src/lib.rs:build_app"], + "owns": ["OpenAI-compatible routes, scenario queues, request logs, deterministic IDs, streaming and failure behavior, admin APIs, and debug UI"], + "depends_on": ["fabro-http", "fabro-static"], + "evidence": ["test/twin/openai/Cargo.toml — declares a fake OpenAI-compatible library and binary", "test/twin/openai/src/state.rs:AppState — owns namespaced counters, scenario queues, and request logs"] + }, + { + "id": "twin-github", + "name": "GitHub Protocol Twin", + "purpose": "Provides an in-process fake GitHub service with seeded mutable state and temporary Git repositories.", + "globs": ["test/twin/github/**"], + "exclude_globs": [], + "entry_points": ["test/twin/github/src/server.rs:TestServer::start", "test/twin/github/src/server.rs:build_router"], + "owns": ["Fake GitHub App, OAuth, REST, GraphQL, smart-HTTP, repositories, pull requests, releases, projects, tokens, and test keys"], + "depends_on": ["fabro-http"], + "evidence": ["test/twin/github/Cargo.toml — declares an independent fake GitHub service", "test/twin/github/src/state.rs:AppState — owns the seeded and mutable GitHub-domain state"] + }, + { + "id": "workflow-test-corpus", + "name": "Shared Workflow Compatibility Fixtures", + "purpose": "Supplies reusable workflow, compatibility, configuration, prompt, partial, and template inputs to cross-crate tests.", + "globs": ["test/*.fabro", "test/attractor/**", "test/dot-compatibility/**", "test/templated_inputs/**", "test/templated_unbound_imported/**", "test/templated_unbound_partial/**", "test/templates/**"], + "exclude_globs": [], + "entry_points": ["test/simple.fabro", "test/attractor/simple_example.dot", "test/templates/static_dependencies/workflow.fabro"], + "owns": ["Representative workflow syntax and behavior cases, Attractor compatibility graphs, DOT fixtures, and template dependency trees"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture — resolves named inputs from the shared test directory", "lib/components/fabro-workflow/tests/it/attractor_compat.rs — enumerates the Attractor corpus"] + }, + { + "id": "documentation-workflow-tests", + "name": "Documentation Workflow Conformance", + "purpose": "Extracts, curates, validates, preflights, and executes workflow examples and companion files derived from Fabro documentation.", + "globs": ["test/docs/**"], + "exclude_globs": [], + "entry_points": ["test/docs/run_tests.sh", "test/docs/extract_dots.py:main", "test/docs/CHECKLIST.md"], + "owns": ["Documentation example corpus, extraction and stub generation, validation and execution phases, parallel runner state, and checklist"], + "depends_on": ["fabro-cli", "fabro-workflow", "public-documentation"], + "evidence": ["test/docs/run_tests.sh — discovers and runs every tracked documentation workflow", "test/docs/extract_dots.py:main — extracts complete graphs and creates companion fixtures"] + }, + { + "id": "swe-bench-evaluation", + "name": "SWE-Bench Evaluation Workflow", + "purpose": "Generates Fabro patches for SWE-bench Lite, grades them, monitors runs, builds environments, and records normalized summaries.", + "globs": ["evals/swe-bench/*.py", "evals/swe-bench/*.fabro", "evals/swe-bench/*.txt", "evals/swe-bench/README.md"], + "exclude_globs": [], + "entry_points": ["evals/swe-bench/run_eval.py:main", "evals/swe-bench/evaluate_daytona.py:main", "evals/swe-bench/record_results.py:main"], + "owns": ["Dataset selection, per-instance workflow generation, sandbox specs, subprocess orchestration, patch extraction, grading, monitoring, and scoreboard schema"], + "depends_on": ["fabro-cli", "fabro-sandbox", "fabro-workflow"], + "evidence": ["evals/swe-bench/README.md — defines the generate, evaluate, and record lifecycle", "evals/swe-bench/run_eval.py:run_instance — creates per-instance Fabro inputs and invokes the CLI"] + }, + { + "id": "repository-development-policy", + "name": "Repository Development Policy", + "purpose": "Defines workspace, dependency, formatting, lint, test, version-control, contributor, and coding-agent development contracts.", + "globs": [".cargo/**", ".config/**", ".gitattributes", ".gitignore", "AGENTS.md", "CONTRIBUTING.md", "Cargo.toml", "package.json", "bunfig.toml", "clippy.toml", "rustfmt.toml"], + "exclude_globs": [], + "entry_points": ["Cargo.toml:[workspace]", "package.json:workspaces", "AGENTS.md"], + "owns": ["Workspace membership and policy, tool aliases, test profiles, lints and formatting, tracked path treatment, contributor workflow, and agent instructions"], + "depends_on": ["fabro-build-tooling"], + "evidence": ["Cargo.toml — declares Rust workspace members, dependencies, lints, and profiles", ".cargo/config.toml — exposes cargo dev and repository test policy", "AGENTS.md — defines architectural and workflow instructions"] + }, + { + "id": "repository-ci", + "name": "Pull-Request and Branch CI", + "purpose": "Runs branch and pull-request validation for Rust and TypeScript and configures GitHub Actions static validation.", + "globs": [".github/workflows/rust.yml", ".github/workflows/typescript.yml", ".github/zizmor.yml"], + "exclude_globs": [], + "entry_points": [".github/workflows/rust.yml", ".github/workflows/typescript.yml"], + "owns": ["Path triggers, formatting, linting, generated-doc checks, tests, E2E modes, TypeScript checks, builds, concurrency, and workflow-lint policy"], + "depends_on": ["fabro-api-client-generation", "fabro-build-tooling", "fabro-web-app", "public-documentation", "repository-development-policy", "twin-openai"], + "evidence": [".github/workflows/rust.yml — runs Rust formatting, lint, generated-document, workspace test, and twin E2E jobs", ".github/workflows/typescript.yml — checks and builds the Bun workspace and embedded SPA"] + }, + { + "id": "release-distribution-automation", + "name": "Release and Package Publication", + "purpose": "Cuts nightly releases and publishes CLI archives, GitHub Releases, multi-architecture images, attestations, and Homebrew formulas.", + "globs": [".github/workflows/nightly.yml", ".github/workflows/release.yml", "installer/**"], + "exclude_globs": [], + "entry_points": [".github/workflows/nightly.yml", ".github/workflows/release.yml", "installer/fabro.rb.template"], + "owns": ["Nightly tag creation, release matrix, archives and checksums, attestations, GitHub Releases, image publication, and Homebrew channels"], + "depends_on": ["container-packaging-and-deployment", "fabro-build-tooling", "fabro-cli", "fabro-web-app", "repository-development-policy"], + "evidence": [".github/workflows/release.yml — packages target matrices and publishes releases, images, and formulas", "installer/fabro.rb.template — defines platform archives, checksums, installation, and smoke tests"] + }, + { + "id": "container-packaging-and-deployment", + "name": "Container Packaging and Deployment", + "purpose": "Packages Fabro as a runtime container and defines local, production, Tailscale, and split-web Compose deployments.", + "globs": [".dockerignore", ".env.example", "Dockerfile", "docker-compose*.yaml", "docker/**"], + "exclude_globs": [], + "entry_points": ["Dockerfile", "docker/entrypoint.sh", "docker-compose.yaml"], + "owns": ["Container image layout, runtime packages and user, storage and Docker socket handoff, preflight checks, proxy behavior, Compose topology, volumes, ports, and health checks"], + "depends_on": ["fabro-build-tooling", "fabro-cli", "fabro-server", "fabro-web-app"], + "evidence": ["Dockerfile — consumes the architecture-specific staged binary and installs the runtime entrypoint", "docker-compose.yaml — defines the primary image, state, socket, port, and health-check contract"] + }, + { + "id": "fabro-repository-automation", + "name": "Fabro-Native Repository Automation", + "purpose": "Configures Fabro's development environment and named workflow graphs, prompts, permissions, and project defaults for repository work.", + "globs": [".fabro/Dockerfile", ".fabro/project.toml", ".fabro/workflows/**"], + "exclude_globs": [".fabro/workflows/goal/workflow.svg"], + "entry_points": [".fabro/project.toml", ".fabro/workflows/implement-plan/workflow.fabro", ".fabro/workflows/smoke/workflow.fabro"], + "owns": ["Repository pull-request defaults, Daytona development environment, named workflow catalog, local prompts, GitHub permissions, and maintenance commands"], + "depends_on": ["fabro-build-tooling", "fabro-cli", "fabro-config", "fabro-github", "fabro-graphviz", "fabro-sandbox", "fabro-workflow", "repository-development-policy"], + "evidence": [".fabro/project.toml — selects the repository environment, resources, lifecycle, labels, and pull-request defaults", ".fabro/workflows/implement-plan/workflow.fabro — invokes repository Cargo and Bun verification and build tooling"] + }, + { + "id": "coding-agent-automation", + "name": "Repository Coding-Agent Automation", + "purpose": "Supplies repository-local review prompts, documentation and changelog skills, edit hooks, and an image-generation helper to coding agents.", + "globs": [".ai/prompts/**", ".claude/settings.json", ".claude/skills/**", "bin/agent/**"], + "exclude_globs": [".claude/skills/*/watermark"], + "entry_points": [".ai/prompts/code-review-fast.md", ".claude/skills/changelog/SKILL.md", ".claude/skills/docs/SKILL.md", "bin/agent/imagegen"], + "owns": ["Code-review orchestration, changelog and documentation maintenance, post-edit formatting hook, and agent image-generation command"], + "depends_on": ["public-documentation", "public-release-history"], + "evidence": [".ai/prompts/code-review-deep-1.md — begins the multi-stage review artifact pipeline", ".claude/skills/docs/SKILL.md — defines the code-to-public-documentation update workflow", ".claude/settings.json — registers the repository post-edit Rust formatting hook"] + } + ], + "unmapped_files": [ + "docs/internal/assets/brand/github-header-v2-mesh.png", + "docs/internal/assets/brand/github-header-v2-mesh.svg", + "docs/internal/assets/brand/logo/logotype-black.svg", + "docs/internal/assets/brand/logo/logotype.svg", + "docs/internal/assets/brand/logo/symbol-black.svg", + "docs/internal/assets/brand/logo/symbol.svg", + "docs/internal/assets/brand/palette-lockups.svg", + "docs/internal/assets/brand/palette-mockup-icons.svg", + "docs/internal/assets/brand/palette-mockup.svg", + "docs/internal/assets/brand/palette.png", + "docs/internal/assets/brand/palette.svg", + "docs/internal/assets/brand/social-card.html", + "docs/internal/assets/brand/social-card.png", + "docs/internal/assets/brand/twitter-card-v0.176.1.html", + "docs/internal/assets/brand/twitter-card-v0.176.1.png" + ], + "coverage": { + "relevant_file_count": 3104, + "assigned_file_count": 2256, + "excluded_file_count": 833, + "unmapped_file_count": 15 + }, + "open_questions": [ + "Should the currently unreferenced docs/internal/assets brand collateral be assigned to a maintained brand component, or remain explicitly unmapped until an ownership and update workflow is identified?", + "Should the first-run browser installer become a separate component if its route and state lifecycle gains an independent entry point, rather than remaining inside fabro-web-app?", + "Should fabro-workflow eventually split run-operation/materialization ownership from pipeline execution if those facades acquire independent state and public contracts?" + ] +} diff --git a/.chisel/cartography/codebase-map.md b/.chisel/cartography/codebase-map.md new file mode 100644 index 0000000000..27a800d71d --- /dev/null +++ b/.chisel/cartography/codebase-map.md @@ -0,0 +1,669 @@ +# Chisel Codebase Map + +Cartography v1 · revision `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` · 2026-07-27T14:07:02Z +Assigned 2256 files · excluded 833 · unmapped 15 · instructions: AGENTS.md, CLAUDE.md, CONTRIBUTING.md + +Fabro is a Cargo workspace whose CLI and HTTP server compose shared workflow, agent, model, sandbox, persistence, integration, and foundation crates. A Bun workspace contains the React web application, Astro marketing site, Remotion composition, and OpenAPI-derived TypeScript client tooling; the OpenAPI document is the shared HTTP contract. Public and internal documentation, protocol twins, fixture corpora, evaluation tooling, build/release/deployment automation, and repository-local agent workflows form separate support boundaries around the product runtime. + +## Components + +### `fabro-cli` — Fabro CLI Application + +- **Purpose:** Provides the fabro command-line process, command dispatch, terminal presentation, server bootstrap, and hidden run-worker entry. +- **Paths:** `lib/apps/fabro-cli/**` +- **Entry points:** `lib/apps/fabro-cli/src/main.rs:main`, `lib/apps/fabro-cli/src/args.rs:Commands` +- **Owns:** CLI process and command lifecycle, output contracts, command context, local server discovery, and the run-worker subprocess entry +- **Depends on:** `fabro-acp`, `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-build-support`, `fabro-checkpoint`, `fabro-client`, `fabro-config`, `fabro-dump`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp`, `fabro-mcp-server`, `fabro-model`, `fabro-oauth`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-server`, `fabro-static`, `fabro-store`, `fabro-telemetry`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `fabro-workflow`, `workflow-test-corpus` +- **Evidence:** lib/apps/fabro-cli/Cargo.toml — declares the fabro binary and its direct workspace dependencies; lib/apps/fabro-cli/src/main.rs:main_inner — constructs shared command state and dispatches the complete command surface + +### `fabro-mcp-server` — Fabro MCP Stdio Server + +- **Purpose:** Exposes Fabro run operations as an MCP stdio tool service and generates supported MCP client configuration. +- **Paths:** `lib/apps/fabro-mcp-server/**` +- **Entry points:** `lib/apps/fabro-mcp-server/src/lib.rs:start`, `lib/apps/fabro-mcp-server/src/config.rs:init_agent` +- **Owns:** MCP stdio service lifecycle, tool router, lazy Fabro client backend, and MCP client configuration updates +- **Depends on:** `fabro-api`, `fabro-client`, `fabro-config`, `fabro-manifest`, `fabro-model`, `fabro-server`, `fabro-tool`, `fabro-types`, `fabro-util` +- **Evidence:** lib/apps/fabro-mcp-server/Cargo.toml — declares a distinct MCP server library package; lib/apps/fabro-mcp-server/src/server.rs:start — owns the rmcp stdio service lifecycle + +### `fabro-server` — Fabro HTTP Server + +- **Purpose:** Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, workers, schedulers, sessions, authentication, and integrations. +- **Paths:** `lib/apps/fabro-server/**` +- **Entry points:** `lib/apps/fabro-server/src/serve.rs:serve_command`, `lib/apps/fabro-server/src/server.rs:build_router` +- **Owns:** Server startup and shutdown, AppState, API and web routing, authentication, scheduling, worker control, and integration coordination +- **Depends on:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-automation`, `fabro-build-support`, `fabro-client`, `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-http-api-contract`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp-store`, `fabro-model`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-slack`, `fabro-spa`, `fabro-static`, `fabro-store`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-variable`, `fabro-vault`, `fabro-workflow` +- **Evidence:** lib/apps/fabro-server/Cargo.toml — declares the HTTP server package and its application dependencies; lib/apps/fabro-server/src/server.rs:AppState — centralizes the service's stores, runtimes, schedulers, credentials, integrations, and shutdown state + +### `fabro-spa` — Embedded SPA Assets + +- **Purpose:** Provides compile-time embedded production SPA lookup, bytes, and content hashes to the Rust server. +- **Paths:** `lib/apps/fabro-spa/Cargo.toml`, `lib/apps/fabro-spa/src/**` +- **Entry points:** `lib/apps/fabro-spa/src/lib.rs:get`, `lib/apps/fabro-spa/src/lib.rs:AssetBytes` +- **Owns:** Compile-time SPA embedding, asset lookup, byte and hash metadata, and source-map exclusion +- **Evidence:** lib/apps/fabro-spa/Cargo.toml — declares a distinct embedded-assets package; lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets — defines compile-time asset embedding and lookup; lib/apps/fabro-server/src/static_files.rs — consumes the embedded asset interface + +### `fabro-acp` — Agent Client Protocol Runtime + +- **Purpose:** Launches and controls Agent Client Protocol processes through Fabro sandboxes and translates their sessions into run results. +- **Paths:** `lib/components/fabro-acp/**` +- **Entry points:** `lib/components/fabro-acp/src/command.rs:AcpProcessSpec`, `lib/components/fabro-acp/src/session.rs:run_acp_turn` +- **Owns:** ACP process specifications, transport and session lifetime, live steering, cancellation, and exit translation +- **Depends on:** `fabro-sandbox`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-acp/Cargo.toml — declares the ACP backend and optional sandbox runtime edge; lib/components/fabro-acp/tests/session.rs — exercises the ACP session boundary + +### `fabro-agent` — Coding Agent Runtime + +- **Purpose:** Runs programmable coding-agent sessions with model profiles, context management, native and MCP tools, permissions, and subagents. +- **Paths:** `lib/components/fabro-agent/**` +- **Entry points:** `lib/components/fabro-agent/src/session.rs:Session`, `lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry` +- **Owns:** Agent session history, prompts and profiles, tool execution, context compaction, permissions, questions, todos, and subagents +- **Depends on:** `fabro-auth`, `fabro-config`, `fabro-http`, `fabro-llm`, `fabro-mcp`, `fabro-model`, `fabro-sandbox`, `fabro-static`, `fabro-template`, `fabro-types`, `fabro-util`, `fabro-vault` +- **Evidence:** lib/components/fabro-agent/Cargo.toml — describes a programmable agentic loop and its runtime dependencies; lib/components/fabro-agent/src/lib.rs — exposes the session, profile, tool, permission, history, and subagent facade + +### `fabro-automation` — Automation Definitions and Storage + +- **Purpose:** Validates, versions, imports, and durably stores scheduled, API-triggered, and manual automation definitions. +- **Paths:** `lib/components/fabro-automation/**` +- **Entry points:** `lib/components/fabro-automation/src/store.rs:AutomationStore`, `lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once` +- **Owns:** Automation identifiers, targets, triggers, revisions, SQLite records, and legacy import +- **Depends on:** `fabro-db` +- **Evidence:** lib/components/fabro-automation/Cargo.toml — declares the automation domain and durable storage boundary; lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs — evolves the owned persistence format + +### `fabro-checkpoint` — Git Checkpoint Storage + +- **Purpose:** Stores workflow checkpoints and metadata in Git commits and dedicated metadata branches. +- **Paths:** `lib/components/fabro-checkpoint/**` +- **Entry points:** `lib/components/fabro-checkpoint/src/branch.rs:BranchStore`, `lib/components/fabro-checkpoint/src/git.rs:Store` +- **Owns:** Checkpoint commits, Git trees, metadata branches, authorship, trailers, and checkpoint errors +- **Depends on:** `fabro-config`, `fabro-store`, `fabro-types` +- **Evidence:** lib/components/fabro-checkpoint/Cargo.toml — identifies Git-backed workflow checkpoint storage; lib/components/fabro-checkpoint/src/lib.rs — exposes the branch, Git, author, trailer, and error surface + +### `fabro-dump` — Run Dump Materialization + +- **Purpose:** Materializes stored run projections, events, checkpoints, artifacts, and blobs into a portable directory tree. +- **Paths:** `lib/components/fabro-dump/**` +- **Entry points:** `lib/components/fabro-dump/src/lib.rs:RunDump`, `lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir` +- **Owns:** Dump layout, stage ranking, blob hydration, serialization, and directory writing +- **Depends on:** `fabro-store`, `fabro-types` +- **Evidence:** lib/components/fabro-dump/Cargo.toml — gives the operation a distinct crate and storage dependency; lib/components/fabro-dump/src/lib.rs:RunDump — contains the public dump-building lifecycle + +### `fabro-environment` — Environment Definitions and Storage + +- **Purpose:** Validates, seeds, versions, imports, and durably stores server-owned execution environment definitions. +- **Paths:** `lib/components/fabro-environment/**` +- **Entry points:** `lib/components/fabro-environment/src/store.rs:EnvironmentStore`, `lib/components/fabro-environment/src/store.rs:seed_default_environment` +- **Owns:** Environment identifiers, revisions, drafts, SQLite records, built-in seeding, and legacy import +- **Depends on:** `fabro-config`, `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-environment/Cargo.toml — declares a server-owned environment domain and store; lib/components/fabro-environment/tests/store.rs — exercises the independent persistence boundary + +### `fabro-github` — GitHub Authentication and API + +- **Purpose:** Resolves GitHub credentials and performs authenticated App, repository, branch, and pull-request operations. +- **Paths:** `lib/components/fabro-github/**` +- **Entry points:** `lib/components/fabro-github/src/lib.rs:GitHubCredentials`, `lib/components/fabro-github/src/lib.rs:create_pull_request` +- **Owns:** GitHub credentials and token minting, API translation, repository URL handling, and pull-request lifecycle calls +- **Depends on:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-types` +- **Evidence:** lib/components/fabro-github/Cargo.toml — describes the GitHub App authentication and API adapter; lib/components/fabro-github/src/lib.rs:GitHubContext — defines the credential context and testable HTTP boundary + +### `fabro-graphviz` — Workflow Graph Language + +- **Purpose:** Parses Graphviz DOT into Fabro's typed graph model and handles conditions, stylesheets, fidelity, and graph rendering. +- **Paths:** `lib/components/fabro-graphviz/**` +- **Entry points:** `lib/components/fabro-graphviz/src/parser/mod.rs:parse`, `lib/components/fabro-graphviz/src/render.rs:render_dot` +- **Owns:** DOT lexer, parser, semantic conversion, graph errors, condition and stylesheet syntax, and rendering normalization +- **Depends on:** `fabro-types`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-graphviz/Cargo.toml — names the crate as the DOT parser and graph data model; lib/components/fabro-graphviz/src/parser/mod.rs:parse — is the source-to-typed-graph entry point + +### `fabro-hooks` — Workflow Lifecycle Hooks + +- **Purpose:** Configures and executes user-defined workflow hooks and bridges tool hooks into the agent runtime. +- **Paths:** `lib/components/fabro-hooks/**` +- **Entry points:** `lib/components/fabro-hooks/src/runner.rs:HookRunner`, `lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback` +- **Owns:** Hook definitions and selection, execution context, result merging, command and HTTP dispatch, and agent bridging +- **Depends on:** `fabro-agent`, `fabro-auth`, `fabro-http`, `fabro-llm`, `fabro-model`, `fabro-redact`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-hooks/Cargo.toml — identifies the workflow hook boundary and runtime dependencies; lib/components/fabro-hooks/tests/host_command_hooks.rs — tests host hooks through the public lifecycle + +### `fabro-install` — Installation Persistence + +- **Purpose:** Prepares, persists, and rolls back shared CLI/server installation settings, credentials, development tokens, and default environments. +- **Paths:** `lib/components/fabro-install/**` +- **Entry points:** `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan`, `lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct` +- **Owns:** Install persistence plans, settings and environment mutations, vault writes, development tokens, and rollback +- **Depends on:** `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-static`, `fabro-types`, `fabro-util`, `fabro-vault` +- **Evidence:** lib/components/fabro-install/Cargo.toml — declares shared install primitives for CLI and server; lib/components/fabro-install/src/lib.rs:InstallPersistencePlan — groups the files, tokens, and vault state committed by one install + +### `fabro-interview` — Human Interaction Runtime + +- **Purpose:** Represents workflow questions and answers and provides console, callback, queue, control, recording, replay, and automatic interviewer implementations. +- **Paths:** `lib/components/fabro-interview/**` +- **Entry points:** `lib/components/fabro-interview/src/lib.rs:Interviewer`, `lib/components/fabro-interview/src/control.rs:ControlInterviewer` +- **Owns:** Question and answer protocol, interviewer request lifetime, timeout behavior, delivery, recording, and replay +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-interview/Cargo.toml — defines interviewer traits and implementations as one crate; lib/components/fabro-interview/src/lib.rs:Interviewer — is the shared asynchronous human-interaction interface + +### `fabro-llm` — Unified LLM Client + +- **Purpose:** Provides a provider-neutral generation API with routing, middleware, retries, token and cost accounting, provider adapters, and wire codecs. +- **Paths:** `lib/components/fabro-llm/**` +- **Entry points:** `lib/components/fabro-llm/src/client.rs:Client`, `lib/components/fabro-llm/src/provider.rs:ProviderAdapter` +- **Owns:** Normalized generation types, adapter registry, provider authentication and transport, codecs, retries, middleware, and accounting +- **Depends on:** `fabro-auth`, `fabro-http`, `fabro-model`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-llm/Cargo.toml — declares the unified multi-provider client; lib/components/fabro-llm/tests/it/wire/mod.rs — verifies provider codecs against one normalized boundary + +### `fabro-manifest` — Run Manifest Construction + +- **Purpose:** Resolves workflow and configuration inputs, collects static dependencies, and constructs self-contained run manifests with Git provenance. +- **Paths:** `lib/components/fabro-manifest/**` +- **Entry points:** `lib/components/fabro-manifest/src/lib.rs:build_run_manifest`, `lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput` +- **Owns:** Manifest input and output, configuration resolution, workflow dependency collection, Git context, and pre-run push preparation +- **Depends on:** `fabro-api`, `fabro-config`, `fabro-github`, `fabro-graphviz`, `fabro-template`, `fabro-types`, `fabro-workflow` +- **Evidence:** lib/components/fabro-manifest/Cargo.toml — declares manifest construction and its graph, Git, and workflow dependencies; lib/components/fabro-manifest/src/lib.rs:build_run_manifest — is the shared assembly operation used by CLI, server, and MCP server + +### `fabro-mcp` — MCP Client Runtime + +- **Purpose:** Connects to configured Model Context Protocol servers, manages connections, discovers tools, and dispatches qualified calls. +- **Paths:** `lib/components/fabro-mcp/**` +- **Entry points:** `lib/components/fabro-mcp/src/client.rs:McpClient`, `lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager` +- **Owns:** MCP client connections, stdio and HTTP transports, connection-manager state, tool discovery, and result conversion +- **Depends on:** `fabro-config`, `fabro-http`, `fabro-types` +- **Evidence:** lib/components/fabro-mcp/Cargo.toml — declares the MCP client and transport features; lib/components/fabro-mcp/tests/stdio_integration.rs — verifies the external process boundary over stdio + +### `fabro-mcp-store` — MCP Server Catalog Storage + +- **Purpose:** Durably stores, revisions, caches, and imports server-managed MCP server definitions. +- **Paths:** `lib/components/fabro-mcp-store/**` +- **Entry points:** `lib/components/fabro-mcp-store/src/store.rs:McpServerStore`, `lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once` +- **Owns:** MCP definition records, optimistic revisions, catalog cache, and legacy directory import +- **Depends on:** `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-mcp-store/Cargo.toml — declares durable MCP catalog storage; lib/components/fabro-mcp-store/src/lib.rs — explicitly assigns persistence ownership to this crate + +### `fabro-sandbox` — Execution Sandbox Abstraction + +- **Purpose:** Defines sandbox and provider contracts and implements local, Docker, and Daytona execution lifecycles. +- **Paths:** `lib/components/fabro-sandbox/**` +- **Entry points:** `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry` +- **Owns:** Sandbox filesystem, process, and terminal interface; provider lifecycle; clone setup; reconnect behavior; and provider implementations +- **Depends on:** `fabro-config`, `fabro-github`, `fabro-http`, `fabro-proc`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-sandbox/Cargo.toml — defines provider features around a common sandbox crate; lib/components/fabro-sandbox/src/provider.rs:SandboxProvider — separates provider lifecycle from per-sandbox operations + +### `fabro-slack` — Slack Interaction Integration + +- **Purpose:** Connects to Slack Socket Mode and translates questions, answers, run events, and threads between Slack and Fabro. +- **Paths:** `lib/components/fabro-slack/**` +- **Entry points:** `lib/components/fabro-slack/src/connection.rs:run`, `lib/components/fabro-slack/src/client.rs:SlackClient` +- **Owns:** Slack credentials, Socket Mode lifecycle, API client, block rendering, payload parsing, thread registry, and dispatch +- **Depends on:** `fabro-http`, `fabro-interview`, `fabro-static`, `fabro-types`, `fabro-workflow` +- **Evidence:** lib/components/fabro-slack/Cargo.toml — declares the Slack interviewer integration; lib/components/fabro-slack/src/connection.rs:run — owns the Socket Mode event loop + +### `fabro-store` — Run and Authentication Persistence + +- **Purpose:** Persists run events, projections, blobs, artifacts, summaries, catalog indexes, and authentication grants over SlateDB, object storage, and SQLite. +- **Paths:** `lib/components/fabro-store/**` +- **Entry points:** `lib/components/fabro-store/src/slate/mod.rs:Database`, `lib/components/fabro-store/src/run_state.rs:RunProjectionReducer` +- **Owns:** Run event and projection lifecycle, blob and artifact layout, summary indexes, auth records, locking, and storage errors +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-store/src/lib.rs — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth; lib/components/fabro-store/src/slate/mod.rs:Database — is the shared storage root for the owned stores + +### `fabro-tool` — Run-Control Tools + +- **Purpose:** Defines and executes shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend. +- **Paths:** `lib/components/fabro-tool/**` +- **Entry points:** `lib/components/fabro-tool/src/common.rs:FabroToolBackend`, `lib/components/fabro-tool/src/common.rs:tool_definitions` +- **Owns:** Tool names and schemas, parameter validation, backend-neutral operations, result records, and text rendering +- **Depends on:** `fabro-api`, `fabro-client`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-tool/Cargo.toml — identifies shared run-control tool behavior over API/client contracts; lib/components/fabro-tool/src/common.rs:FabroToolBackend — is the abstraction shared by CLI, server, workflow, and MCP server + +### `fabro-tracker` — Issue Tracker Adapters + +- **Purpose:** Provides a common issue-tracker interface with GitHub Projects and Linear implementations. +- **Paths:** `lib/components/fabro-tracker/**` +- **Entry points:** `lib/components/fabro-tracker/src/lib.rs:Tracker`, `lib/components/fabro-tracker/src/github.rs:GitHubTracker` +- **Owns:** Normalized issues and blockers, candidate selection and transitions, and GitHub Projects and Linear GraphQL adapters +- **Depends on:** `fabro-github`, `fabro-http` +- **Evidence:** lib/components/fabro-tracker/Cargo.toml — declares the tracker trait and provider adapters; lib/components/fabro-tracker/src/lib.rs:Tracker — defines the provider-neutral issue workflow + +### `fabro-validate` — Workflow Graph Validation + +- **Purpose:** Runs built-in and catalog-aware lint rules over typed workflow graphs and returns structured diagnostics. +- **Paths:** `lib/components/fabro-validate/**` +- **Entry points:** `lib/components/fabro-validate/src/lib.rs:validate`, `lib/components/fabro-validate/src/lib.rs:LintRule` +- **Owns:** Validation diagnostics, rule interface and registry, graph and catalog traversal, and error escalation +- **Depends on:** `fabro-acp`, `fabro-graphviz`, `fabro-model`, `fabro-types`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-validate/Cargo.toml — declares graph validation and its graph/catalog dependencies; lib/components/fabro-validate/src/rules/mod.rs:built_in_rules — forms the explicit built-in rule registry + +### `fabro-variable` — Workflow Variable Storage + +- **Purpose:** Validates, durably stores, snapshots, and imports workflow-visible non-sensitive variables. +- **Paths:** `lib/components/fabro-variable/**` +- **Entry points:** `lib/components/fabro-variable/src/lib.rs:VariableStore`, `lib/components/fabro-variable/src/lib.rs:import_legacy_json_once` +- **Owns:** Variable validation, SQLite records, render-context snapshots, and legacy JSON import +- **Depends on:** `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-variable/Cargo.toml — defines workflow-visible variables as a storage concern; lib/components/fabro-variable/tests/store.rs — verifies its independent persistence and import contract + +### `fabro-workflow` — Workflow Orchestration Engine + +- **Purpose:** Transforms, validates, initializes, executes, persists, resumes, and finalizes graph-defined Fabro runs. +- **Paths:** `lib/components/fabro-workflow/**` +- **Entry points:** `lib/components/fabro-workflow/src/operations/start.rs:start`, `lib/components/fabro-workflow/src/pipeline/execute.rs:execute` +- **Owns:** Run operations, workflow phases, node handlers, run services, events, checkpoints, Git, artifacts, hooks, status, steering, and cancellation +- **Depends on:** `fabro-acp`, `fabro-agent`, `fabro-auth`, `fabro-checkpoint`, `fabro-config`, `fabro-core`, `fabro-dump`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-interview`, `fabro-llm`, `fabro-mcp`, `fabro-model`, `fabro-redact`, `fabro-sandbox`, `fabro-static`, `fabro-store`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-workflow/Cargo.toml — declares the DOT-based runner and component dependencies; lib/components/fabro-workflow/src/pipeline/mod.rs — exposes the ordered transform, validate, initialize, execute, and finalize phases + +### `fabro-build-support` — Rust Build-Script Support + +- **Purpose:** Supplies shared compile-time Git and Cargo profile metadata to Fabro application build scripts. +- **Paths:** `lib/foundation/build-support/**` +- **Entry points:** `lib/foundation/build-support/git_metadata.rs:collect_from`, `lib/foundation/build-support/git_metadata.rs:cargo_profile` +- **Owns:** Compile-time Git SHA discovery, Cargo rerun paths, and profile discovery +- **Evidence:** lib/foundation/build-support/Cargo.toml — declares the shared build-support package; lib/foundation/build-support/git_metadata.rs:BuildGitMetadata — defines build-script Git and profile metadata; lib/apps/fabro-cli/build.rs — consumes the shared metadata collector; lib/apps/fabro-server/build.rs — consumes the shared metadata collector + +### `fabro-build-tooling` — Fabro Build and Developer Tooling + +- **Purpose:** Runs repository build, documentation, SPA, container, benchmark, release, and test-support automation. +- **Paths:** `lib/foundation/fabro-dev/**`, `test/bin/release_test.sh`, `test/analysis/bench-tests-diff.sql` +- **Entry points:** `lib/foundation/fabro-dev/src/main.rs:main` +- **Owns:** Developer CLI dispatch, subprocess plans, generated-reference checks, build and release workflows, and benchmark analysis +- **Depends on:** `container-packaging-and-deployment`, `fabro-cli`, `fabro-config`, `fabro-macros-metadata`, `fabro-spa`, `fabro-util`, `fabro-web-app`, `public-documentation`, `repository-development-policy` +- **Evidence:** lib/foundation/fabro-dev/src/lib.rs:Command — dispatches build, Docker, docs, release, SPA, and benchmark commands + +### `fabro-api` — Generated Rust API Client + +- **Purpose:** Generates the low-level Rust HTTP client and API type facade from OpenAPI while reusing canonical product types and verifying wire parity. +- **Paths:** `lib/foundation/fabro-api/**` +- **Entry points:** `lib/foundation/fabro-api/build.rs:main`, `lib/foundation/fabro-api/src/lib.rs:ApiClient` +- **Owns:** OpenAPI compatibility transformations, generation settings, type replacement map, generated-client facade, and wire/type parity tests +- **Depends on:** `fabro-automation`, `fabro-config`, `fabro-environment`, `fabro-http-api-contract`, `fabro-model`, `fabro-types` +- **Evidence:** lib/foundation/fabro-api/build.rs:main — reads the OpenAPI contract and writes generated Rust code to OUT_DIR; lib/foundation/fabro-api/tests/run_event_round_trip.rs — verifies identity and JSON parity for canonical reused types + +### `fabro-auth` — Provider Credential Resolution + +- **Purpose:** Resolves provider credentials and headers from environment or vault sources, refreshes OAuth credentials, and drives authentication strategies. +- **Paths:** `lib/foundation/fabro-auth/**` +- **Entry points:** `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver`, `lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy` +- **Owns:** Credential-source precedence, provider discovery, OAuth refresh and write-back, header interpolation, and interactive auth state +- **Depends on:** `fabro-http`, `fabro-model`, `fabro-oauth`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-vault` +- **Evidence:** lib/foundation/fabro-auth/Cargo.toml — declares typed provider credential resolution; lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve — composes catalog policy, source lookup, headers, and refresh + +### `fabro-client` — High-Level Fabro Service Client + +- **Purpose:** Provides an authenticated Fabro service client over HTTP or Unix sockets with endpoint wrappers, SSE streams, refresh, and local auth storage. +- **Paths:** `lib/foundation/fabro-client/**` +- **Entry points:** `lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect`, `lib/foundation/fabro-client/src/target.rs:ServerTarget` +- **Owns:** Connected transport state, operation wrappers, SSE buffering, token refresh, target normalization, and per-server CLI auth files +- **Depends on:** `fabro-api`, `fabro-http`, `fabro-model`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-client/Cargo.toml — distinguishes the high-level client from the generated API client; lib/foundation/fabro-client/src/client.rs:ClientState — owns transport, generated client, token, URL, and refresh coordination + +### `fabro-config` — Layered Configuration and Runtime Paths + +- **Purpose:** Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical paths. +- **Paths:** `lib/foundation/fabro-config/**` +- **Entry points:** `lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder`, `lib/foundation/fabro-config/src/resolve/mod.rs` +- **Owns:** Source layers and merge semantics, defaults, parsing and validation, migrations, home/storage/runtime paths, daemon, envfile, and logging configuration +- **Depends on:** `fabro-macros-metadata`, `fabro-model`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-config/Cargo.toml — declares the centralized configuration crate; lib/foundation/fabro-config/src/builders.rs — composes defaults and layers into dense runtime settings + +### `fabro-core` — Generic Graph Execution Kernel + +- **Purpose:** Executes generic directed graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts. +- **Paths:** `lib/foundation/fabro-core/**` +- **Entry points:** `lib/foundation/fabro-core/src/executor.rs:Executor::run`, `lib/foundation/fabro-core/src/handler.rs:NodeHandler` +- **Owns:** Execution state, graph traversal, handler and lifecycle contracts, retry and visit decisions, cancellation, and stall watchdog +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-core/Cargo.toml — identifies a generic kernel without higher-level workflow dependencies; lib/foundation/fabro-core/src/executor.rs:Executor::run — owns the traversal and execution lifecycle + +### `fabro-db` — Shared SQLite Database Foundation + +- **Purpose:** Opens and migrates the shared SQLite database, manages rollback snapshots and permissions, and defines the bundled schema. +- **Paths:** `lib/foundation/fabro-db/**` +- **Entry points:** `lib/foundation/fabro-db/src/lib.rs:Database::connect`, `lib/foundation/fabro-db/src/lib.rs:Database::migrate` +- **Owns:** SQLite pool policy, migration registry, snapshots, backup paths, permissions, tables, and indexes +- **Evidence:** lib/foundation/fabro-db/Cargo.toml — declares the shared SQLite foundation; lib/foundation/fabro-db/migrations/2026071101_secrets.sql — is one migration in the compiled shared schema + +### `fabro-http` — Shared HTTP Transport Construction + +- **Purpose:** Centralizes reqwest type exposure and synchronous and asynchronous HTTP client construction with Fabro proxy policy. +- **Paths:** `lib/foundation/fabro-http/**` +- **Entry points:** `lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder`, `lib/foundation/fabro-http/src/lib.rs:test_http_client` +- **Owns:** Approved reqwest facade, proxy-policy resolution, client builders, and deterministic no-proxy test clients +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-http/Cargo.toml — declares the shared reqwest wrapper; lib/foundation/fabro-http/src/lib.rs:ProxyPolicy — defines the common transport-construction policy + +### `fabro-macros-metadata` — Compile-Time Macros and Option Metadata + +- **Purpose:** Supplies Fabro derive and attribute macros plus the runtime option-metadata model used by configuration and documentation tooling. +- **Paths:** `lib/foundation/fabro-macros/**`, `lib/foundation/fabro-options-metadata/**` +- **Entry points:** `lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata` +- **Owns:** Macro expansion for E2E gates, layer combination, and option metadata plus the runtime visitor and option-tree representation +- **Evidence:** lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl — generates implementations against the runtime metadata crate; lib/foundation/fabro-macros/tests/options_metadata.rs — tests the compiler/runtime pair together + +### `fabro-model` — LLM Model and Provider Catalog + +- **Purpose:** Defines provider and model identity, capabilities, billing metadata, embedded catalog data, override merging, and selection. +- **Paths:** `lib/foundation/fabro-model/**` +- **Entry points:** `lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::select` +- **Owns:** Provider and model IDs, catalog sources and indexes, auth declarations, capabilities, controls, codecs, reasoning, pricing, and billing +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-model/Cargo.toml — names model metadata and resolution as the crate responsibility; lib/foundation/fabro-model/src/catalog/providers/openai.toml — is one tracked built-in provider catalog source + +### `fabro-oauth` — OAuth PKCE and Callback Flow + +- **Purpose:** Implements generic OAuth PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh. +- **Paths:** `lib/foundation/fabro-oauth/**` +- **Entry points:** `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow`, `lib/foundation/fabro-oauth/src/lib.rs:refresh_token` +- **Owns:** PKCE and state, authorization URLs, callback listener and shutdown, callback validation, exchange, and refresh +- **Depends on:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-util` +- **Evidence:** lib/foundation/fabro-oauth/Cargo.toml — declares a generic OAuth 2.0 PKCE flow; lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle — owns the ephemeral callback server lifecycle + +### `fabro-proc` — OS Process Primitives + +- **Purpose:** Wraps platform process primitives for signals, groups, advisory locks, pre-exec hooks, liveness, and process-title rewriting. +- **Paths:** `lib/foundation/fabro-proc/**` +- **Entry points:** `lib/foundation/fabro-proc/src/signal.rs:process_running`, `lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid` +- **Owns:** Unix signals and process groups, cross-platform liveness, locks, child pre-exec configuration, and argv/title state +- **Evidence:** lib/foundation/fabro-proc/Cargo.toml — describes safe process-management wrappers; lib/foundation/fabro-proc/c/capture_argv.c — establishes the FFI boundary for title rewriting + +### `fabro-redact` — Secret and Credential Redaction + +- **Purpose:** Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded rules and entropy scanning. +- **Paths:** `lib/foundation/fabro-redact/**` +- **Entry points:** `lib/foundation/fabro-redact/src/lib.rs:redact_string`, `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` +- **Owns:** Rule source and engine, entropy thresholds, overlap merging, structured redaction policy, and safe URL display +- **Evidence:** lib/foundation/fabro-redact/build.rs:main — compiles the tracked Gitleaks rule source into OUT_DIR; lib/foundation/fabro-redact/src/lib.rs:redact_string — composes entropy and rule-based detection + +### `fabro-static` — Shared Static Conventions + +- **Purpose:** Defines dependency-light canonical environment-variable names and registries for bootstrap and optional vault secrets. +- **Paths:** `lib/foundation/fabro-static/**` +- **Entry points:** `lib/foundation/fabro-static/src/env_vars.rs:EnvVars`, `lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret` +- **Owns:** Canonical environment names and bootstrap and optional secret classification +- **Evidence:** lib/foundation/fabro-static/Cargo.toml — declares a no-dependency static registry; lib/foundation/fabro-static/src/env_vars.rs:EnvVars — centralizes environment names used across the workspace + +### `fabro-telemetry` — Analytics and Crash Telemetry + +- **Purpose:** Initializes analytics and crash reporting, builds anonymous context, buffers events, and delivers them across CLI and server lifecycles. +- **Paths:** `lib/foundation/fabro-telemetry/**` +- **Entry points:** `lib/foundation/fabro-telemetry/src/lib.rs:init_cli`, `lib/foundation/fabro-telemetry/src/lib.rs:shutdown` +- **Owns:** Process-global telemetry state, identifiers, buffer thread, event context, command sanitization, Segment delivery, and panic capture +- **Depends on:** `fabro-http`, `fabro-static`, `fabro-util` +- **Evidence:** lib/foundation/fabro-telemetry/Cargo.toml — declares analytics and crash reporting; lib/foundation/fabro-telemetry/src/lib.rs:Global — owns sender, identity, context, level, and background thread + +### `fabro-template` — Template Rendering and Dependency Discovery + +- **Purpose:** Renders MiniJinja templates with source-aware diagnostics, rooted stores, wrappers, and static dependency discovery. +- **Paths:** `lib/foundation/fabro-template/**` +- **Entry points:** `lib/foundation/fabro-template/src/lib.rs:render_named`, `lib/foundation/fabro-template/src/store.rs:TemplateStore` +- **Owns:** Template context, render modes, diagnostics, include safety, stores, caching and recording, and dependency closure +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-template/Cargo.toml — declares the shared rendering boundary; lib/foundation/fabro-template/src/dependency.rs — owns include and import extraction and closure discovery + +### `fabro-test` — Shared Integration-Test Infrastructure + +- **Purpose:** Provides isolated CLI/server test contexts, twin and live mode control, process harnessing, snapshot normalization, and HTTP assertions. +- **Paths:** `lib/foundation/fabro-test/**` +- **Entry points:** `lib/foundation/fabro-test/src/lib.rs:TestContext`, `lib/foundation/fabro-test/src/lib.rs:TestMode` +- **Owns:** Temporary test home and storage, managed processes, mode and secret gating, environment isolation, snapshot filters, twins, and HTTP diagnostics +- **Depends on:** `fabro-config`, `fabro-http`, `fabro-install`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`, `twin-github`, `twin-openai`, `workflow-test-corpus` +- **Evidence:** lib/foundation/fabro-test/Cargo.toml — declares shared integration-test utilities and twin dependencies; lib/foundation/fabro-test/src/lib.rs:TestContext — owns isolated paths, subprocesses, filters, and managed server state + +### `fabro-types` — Shared Product Contracts and State Records + +- **Purpose:** Defines serializable identifiers, settings, run and session events, projections, and other product vocabulary exchanged across Fabro boundaries. +- **Paths:** `lib/foundation/fabro-types/**` +- **Entry points:** `lib/foundation/fabro-types/src/lib.rs`, `lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent` +- **Owns:** Canonical serde shapes and IDs for runs, stages, sessions, events, settings, projections, sandboxes, integrations, billing, and repositories +- **Depends on:** `fabro-model`, `fabro-util` +- **Evidence:** lib/foundation/fabro-types/Cargo.toml — describes shared record structs and enums; lib/foundation/fabro-types/src/lib.rs — is the single facade for canonical product vocabulary + +### `fabro-util` — Cross-Cutting Runtime and CLI Utilities + +- **Purpose:** Provides shared environment, filesystem, shell, terminal, logging, token, error, time, backoff, warning, and glob primitives. +- **Paths:** `lib/foundation/fabro-util/**` +- **Entry points:** `lib/foundation/fabro-util/src/lib.rs`, `lib/foundation/fabro-util/src/shell.rs:shell_quote` +- **Owns:** Low-level helper contracts plus warning, buffered log, environment, home, token, terminal, backoff, error, and glob state +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-util/Cargo.toml — identifies shared runtime and terminal helpers; lib/foundation/fabro-util/src/run_log.rs — owns the buffered run-log guard lifecycle + +### `fabro-vault` — Secret Vault and SQLite Store + +- **Purpose:** Validates and stores workflow-visible secrets in file, memory, or SQLite stores with revision-aware updates and legacy import. +- **Paths:** `lib/foundation/fabro-vault/**` +- **Entry points:** `lib/foundation/fabro-vault/src/lib.rs:Vault::load`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::open` +- **Owns:** Secret validation and redacted entries, atomic file persistence, SQL CRUD, revisions, snapshots, and legacy import +- **Depends on:** `fabro-db`, `fabro-static`, `fabro-types` +- **Evidence:** lib/foundation/fabro-vault/Cargo.toml — declares workflow-visible secret storage; lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision — exposes concurrent refresh write-back semantics + +### `fabro-web-app` — Fabro Browser Application + +- **Purpose:** Builds and runs the React SPA for normal operations and first-run installation. +- **Paths:** `apps/fabro-web/**` +- **Excludes:** `apps/fabro-web/app/components/playground/**` +- **Entry points:** `apps/fabro-web/app/entry.tsx`, `apps/fabro-web/scripts/build.ts` +- **Owns:** Browser bundle and route graphs, install flow, shared browser runtime and UI, product operations UX, and public assets +- **Depends on:** `fabro-api-client-generation`, `fabro-http-api-contract`, `fabro-workflow-playground` +- **Evidence:** apps/fabro-web/package.json — declares the React application, custom build, tests, and API-client workspace edge; apps/fabro-web/app/entry.tsx — creates the browser root and selects normal or install routing + +### `fabro-workflow-playground` — Browser Workflow Playground + +- **Purpose:** Provides a self-contained workflow drafting, simulation, chat, visualization, file-generation, download, and run-launch surface. +- **Paths:** `apps/fabro-web/app/components/playground/**` +- **Entry points:** `apps/fabro-web/app/components/playground/playground.tsx:Playground`, `apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft` +- **Owns:** Workflow draft schema and persistence, simulation, canvas, chat adaptation, generated project files, download, and launch controls +- **Depends on:** `fabro-http-api-contract`, `fabro-web-app` +- **Evidence:** apps/fabro-web/app/components/playground/playground.tsx:Playground — exposes a prop boundary framed for re-embedding; apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft — owns versioned browser persistence + +### `fabro-marketing-site` — Fabro Marketing Site + +- **Purpose:** Builds and deploys the public Fabro site with landing content, blog, roadmap, showcase, install resources, and social assets. +- **Paths:** `apps/marketing/**`, `test/bin/install_test.sh` +- **Excludes:** `apps/marketing/.vercel/**` +- **Entry points:** `apps/marketing/src/pages/index.astro`, `apps/marketing/astro.config.mjs`, `apps/marketing/public/install.sh` +- **Owns:** Astro routes and layout, content collections, marketing presentation, workflow showcases, install resources, redirects, and deployment configuration +- **Evidence:** apps/marketing/package.json — declares an independent Astro application; apps/marketing/src/content.config.ts — defines typed roadmap, blog, and showcase collections; test/bin/install_test.sh — black-box tests the site's canonical install script + +### `fabro-remotion-video` — Fabro Remotion Composition + +- **Purpose:** Renders the branded FabroIntro motion-graphics video. +- **Paths:** `apps/remotion/**` +- **Entry points:** `apps/remotion/src/index.ts`, `apps/remotion/src/Root.tsx:RemotionRoot` +- **Owns:** Composition registration, frame timeline, image format, logo animation, brand assets, and rendered-video lifecycle +- **Evidence:** apps/remotion/package.json — declares an independent Remotion project and render target; apps/remotion/src/Root.tsx:RemotionRoot — declares composition identity, dimensions, frame rate, and duration + +### `fabro-api-client-generation` — TypeScript API Client Generation + +- **Purpose:** Configures, normalizes, and type-checks the generated TypeScript/Axios client for the Fabro HTTP contract. +- **Paths:** `lib/packages/fabro-api-client/package.json`, `lib/packages/fabro-api-client/openapitools.json`, `lib/packages/fabro-api-client/scripts/**`, `lib/packages/fabro-api-client/tests/**`, `lib/packages/fabro-api-client/tsconfig.json` +- **Entry points:** `lib/packages/fabro-api-client/package.json:scripts.generate`, `lib/packages/fabro-api-client/scripts/normalize-generated.ts` +- **Owns:** Generator versions and options, output location, normalization, strict compilation, and hand-written generated-shape invariants +- **Depends on:** `fabro-http-api-contract` +- **Evidence:** lib/packages/fabro-api-client/package.json — invokes pinned OpenAPI Generator against the shared YAML and writes src; lib/packages/fabro-api-client/tests/principal-exhaustive.ts — asserts a generated union contract at compile time + +### `public-documentation` — Public Documentation + +- **Purpose:** Owns authored Fabro user documentation, Mintlify presentation, the repository landing page, and published web-screenshot maintenance. +- **Paths:** `README.md`, `docs/public/**`, `docs/internal/updating-web-screenshots.md` +- **Excludes:** `docs/public/api-reference/fabro-api.yaml`, `docs/public/changelog/**`, `docs/public/images/*-workflow.svg`, `docs/public/images/tutorial-*.svg`, `docs/public/images/brave-search-research.svg`, `docs/public/images/how-fabro-works.svg`, `docs/public/images/nlspec-conformance.svg`, `docs/public/images/plan-implement-readme.svg` +- **Entry points:** `README.md`, `docs/public/docs.json`, `docs/public/getting-started/introduction.mdx` +- **Owns:** Mintlify navigation and presentation, public guides and reference prose, curated images and screenshots, syntax definitions, and repository overview +- **Depends on:** `documentation-demo-workflows`, `fabro-cli`, `fabro-http-api-contract`, `public-release-history` +- **Evidence:** docs/public/docs.json — declares the Mintlify theme, navigation, OpenAPI, and changelog surfaces; README.md — links to the published docs and embeds their canonical assets; docs/internal/updating-web-screenshots.md — defines the screenshot capture and verification workflow + +### `public-release-history` — Published Changelog + +- **Purpose:** Preserves and publishes dated user-facing release and change records independently of current reference documentation. +- **Paths:** `docs/public/changelog/**` +- **Entry points:** `docs/public/changelog/2026-07-25.mdx` +- **Owns:** Dated titles, migration warnings, feature summaries, and historical behavior notes +- **Depends on:** `public-documentation` +- **Evidence:** docs/public/docs.json — gives the changelog its own top-level tab and enumerates every page; docs/public/changelog/2026-07-25.mdx — is the newest dated release entry at the assessed revision + +### `fabro-http-api-contract` — Fabro HTTP API Contract + +- **Purpose:** Defines the OpenAPI-first wire contract used by the server, generated clients, conformance tests, and published API reference. +- **Paths:** `docs/public/api-reference/fabro-api.yaml` +- **Entry points:** `docs/public/api-reference/fabro-api.yaml` +- **Owns:** HTTP routes, request and response schemas, authentication declarations, and API-facing wire documentation +- **Evidence:** AGENTS.md — identifies the OpenAPI file as the HTTP interface source of truth; lib/foundation/fabro-api/build.rs:main — consumes the contract for Rust generation; lib/apps/fabro-server/tests/it/openapi_conformance.rs — reads it for router conformance + +### `documentation-demo-workflows` — Executable Documentation Demos + +- **Purpose:** Provides runnable workflow definitions, configuration, and prompts used by public tutorials and demonstrations. +- **Paths:** `docs/internal/demo/*.fabro`, `docs/internal/demo/*.toml`, `docs/internal/demo/prompts/**` +- **Entry points:** `docs/internal/demo/01-hello.fabro`, `docs/internal/demo/14-search-imagegen.toml` +- **Owns:** Executable example graphs, the image-generation run configuration, and shared demo prompt text +- **Depends on:** `fabro-cli`, `fabro-sandbox`, `fabro-workflow` +- **Evidence:** docs/public/tutorials/hello-world.mdx — invokes a demo workflow path directly; docs/internal/demo/14-search-imagegen.toml — selects the demo graph, environment, and output assets + +### `internal-engineering-guidance` — Internal Engineering Guidance + +- **Purpose:** Records active repository-wide engineering policies and maintained architecture and runtime contracts. +- **Paths:** `docs/internal/*-strategy.md`, `docs/internal/*-policy.md`, `docs/internal/events.md`, `docs/internal/fabro-event-schema-v2-concrete-shape.md`, `docs/internal/llm-client-resolution.md`, `docs/internal/run-directory-keys.md` +- **Entry points:** `docs/internal/events-strategy.md`, `docs/internal/testing-strategy.md`, `docs/internal/error-handling-strategy.md` +- **Owns:** Logging, events, testing, migrations, secrets, error handling, React effects, panic, event catalog, LLM resolution, parallelism, and run-file guidance +- **Depends on:** `fabro-cli`, `fabro-config`, `fabro-server`, `fabro-types`, `fabro-web-app`, `fabro-workflow` +- **Evidence:** AGENTS.md — makes the strategy and policy documents mandatory before related changes; docs/internal/events.md — is the maintained serialized event catalog + +### `product-context` — Internal Product Context + +- **Purpose:** Maintains product intent, audience, current shape, success signals, and stable technical and product constraints. +- **Paths:** `docs/internal/product/**` +- **Entry points:** `docs/internal/product/product-description.md`, `docs/internal/product/current-state.md` +- **Owns:** Business problem, personas, product description, current state, success metrics, and product-level technical requirements +- **Evidence:** docs/internal/product/current-state.md — identifies itself as a concise current product snapshot; docs/internal/product/technical-requirements.md — records stable constraints for product changes + +### `twin-openai` — OpenAI Protocol Twin + +- **Purpose:** Provides a deterministic OpenAI-compatible HTTP service for black-box and protocol-contract tests. +- **Paths:** `test/twin/openai/**` +- **Entry points:** `test/twin/openai/src/main.rs:main`, `test/twin/openai/src/lib.rs:build_app` +- **Owns:** OpenAI-compatible routes, scenario queues, request logs, deterministic IDs, streaming and failure behavior, admin APIs, and debug UI +- **Depends on:** `fabro-http`, `fabro-static` +- **Evidence:** test/twin/openai/Cargo.toml — declares a fake OpenAI-compatible library and binary; test/twin/openai/src/state.rs:AppState — owns namespaced counters, scenario queues, and request logs + +### `twin-github` — GitHub Protocol Twin + +- **Purpose:** Provides an in-process fake GitHub service with seeded mutable state and temporary Git repositories. +- **Paths:** `test/twin/github/**` +- **Entry points:** `test/twin/github/src/server.rs:TestServer::start`, `test/twin/github/src/server.rs:build_router` +- **Owns:** Fake GitHub App, OAuth, REST, GraphQL, smart-HTTP, repositories, pull requests, releases, projects, tokens, and test keys +- **Depends on:** `fabro-http` +- **Evidence:** test/twin/github/Cargo.toml — declares an independent fake GitHub service; test/twin/github/src/state.rs:AppState — owns the seeded and mutable GitHub-domain state + +### `workflow-test-corpus` — Shared Workflow Compatibility Fixtures + +- **Purpose:** Supplies reusable workflow, compatibility, configuration, prompt, partial, and template inputs to cross-crate tests. +- **Paths:** `test/*.fabro`, `test/attractor/**`, `test/dot-compatibility/**`, `test/templated_inputs/**`, `test/templated_unbound_imported/**`, `test/templated_unbound_partial/**`, `test/templates/**` +- **Entry points:** `test/simple.fabro`, `test/attractor/simple_example.dot`, `test/templates/static_dependencies/workflow.fabro` +- **Owns:** Representative workflow syntax and behavior cases, Attractor compatibility graphs, DOT fixtures, and template dependency trees +- **Evidence:** lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture — resolves named inputs from the shared test directory; lib/components/fabro-workflow/tests/it/attractor_compat.rs — enumerates the Attractor corpus + +### `documentation-workflow-tests` — Documentation Workflow Conformance + +- **Purpose:** Extracts, curates, validates, preflights, and executes workflow examples and companion files derived from Fabro documentation. +- **Paths:** `test/docs/**` +- **Entry points:** `test/docs/run_tests.sh`, `test/docs/extract_dots.py:main`, `test/docs/CHECKLIST.md` +- **Owns:** Documentation example corpus, extraction and stub generation, validation and execution phases, parallel runner state, and checklist +- **Depends on:** `fabro-cli`, `fabro-workflow`, `public-documentation` +- **Evidence:** test/docs/run_tests.sh — discovers and runs every tracked documentation workflow; test/docs/extract_dots.py:main — extracts complete graphs and creates companion fixtures + +### `swe-bench-evaluation` — SWE-Bench Evaluation Workflow + +- **Purpose:** Generates Fabro patches for SWE-bench Lite, grades them, monitors runs, builds environments, and records normalized summaries. +- **Paths:** `evals/swe-bench/*.py`, `evals/swe-bench/*.fabro`, `evals/swe-bench/*.txt`, `evals/swe-bench/README.md` +- **Entry points:** `evals/swe-bench/run_eval.py:main`, `evals/swe-bench/evaluate_daytona.py:main`, `evals/swe-bench/record_results.py:main` +- **Owns:** Dataset selection, per-instance workflow generation, sandbox specs, subprocess orchestration, patch extraction, grading, monitoring, and scoreboard schema +- **Depends on:** `fabro-cli`, `fabro-sandbox`, `fabro-workflow` +- **Evidence:** evals/swe-bench/README.md — defines the generate, evaluate, and record lifecycle; evals/swe-bench/run_eval.py:run_instance — creates per-instance Fabro inputs and invokes the CLI + +### `repository-development-policy` — Repository Development Policy + +- **Purpose:** Defines workspace, dependency, formatting, lint, test, version-control, contributor, and coding-agent development contracts. +- **Paths:** `.cargo/**`, `.config/**`, `.gitattributes`, `.gitignore`, `AGENTS.md`, `CONTRIBUTING.md`, `Cargo.toml`, `package.json`, `bunfig.toml`, `clippy.toml`, `rustfmt.toml` +- **Entry points:** `Cargo.toml:[workspace]`, `package.json:workspaces`, `AGENTS.md` +- **Owns:** Workspace membership and policy, tool aliases, test profiles, lints and formatting, tracked path treatment, contributor workflow, and agent instructions +- **Depends on:** `fabro-build-tooling` +- **Evidence:** Cargo.toml — declares Rust workspace members, dependencies, lints, and profiles; .cargo/config.toml — exposes cargo dev and repository test policy; AGENTS.md — defines architectural and workflow instructions + +### `repository-ci` — Pull-Request and Branch CI + +- **Purpose:** Runs branch and pull-request validation for Rust and TypeScript and configures GitHub Actions static validation. +- **Paths:** `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, `.github/zizmor.yml` +- **Entry points:** `.github/workflows/rust.yml`, `.github/workflows/typescript.yml` +- **Owns:** Path triggers, formatting, linting, generated-doc checks, tests, E2E modes, TypeScript checks, builds, concurrency, and workflow-lint policy +- **Depends on:** `fabro-api-client-generation`, `fabro-build-tooling`, `fabro-web-app`, `public-documentation`, `repository-development-policy`, `twin-openai` +- **Evidence:** .github/workflows/rust.yml — runs Rust formatting, lint, generated-document, workspace test, and twin E2E jobs; .github/workflows/typescript.yml — checks and builds the Bun workspace and embedded SPA + +### `release-distribution-automation` — Release and Package Publication + +- **Purpose:** Cuts nightly releases and publishes CLI archives, GitHub Releases, multi-architecture images, attestations, and Homebrew formulas. +- **Paths:** `.github/workflows/nightly.yml`, `.github/workflows/release.yml`, `installer/**` +- **Entry points:** `.github/workflows/nightly.yml`, `.github/workflows/release.yml`, `installer/fabro.rb.template` +- **Owns:** Nightly tag creation, release matrix, archives and checksums, attestations, GitHub Releases, image publication, and Homebrew channels +- **Depends on:** `container-packaging-and-deployment`, `fabro-build-tooling`, `fabro-cli`, `fabro-web-app`, `repository-development-policy` +- **Evidence:** .github/workflows/release.yml — packages target matrices and publishes releases, images, and formulas; installer/fabro.rb.template — defines platform archives, checksums, installation, and smoke tests + +### `container-packaging-and-deployment` — Container Packaging and Deployment + +- **Purpose:** Packages Fabro as a runtime container and defines local, production, Tailscale, and split-web Compose deployments. +- **Paths:** `.dockerignore`, `.env.example`, `Dockerfile`, `docker-compose*.yaml`, `docker/**` +- **Entry points:** `Dockerfile`, `docker/entrypoint.sh`, `docker-compose.yaml` +- **Owns:** Container image layout, runtime packages and user, storage and Docker socket handoff, preflight checks, proxy behavior, Compose topology, volumes, ports, and health checks +- **Depends on:** `fabro-build-tooling`, `fabro-cli`, `fabro-server`, `fabro-web-app` +- **Evidence:** Dockerfile — consumes the architecture-specific staged binary and installs the runtime entrypoint; docker-compose.yaml — defines the primary image, state, socket, port, and health-check contract + +### `fabro-repository-automation` — Fabro-Native Repository Automation + +- **Purpose:** Configures Fabro's development environment and named workflow graphs, prompts, permissions, and project defaults for repository work. +- **Paths:** `.fabro/Dockerfile`, `.fabro/project.toml`, `.fabro/workflows/**` +- **Excludes:** `.fabro/workflows/goal/workflow.svg` +- **Entry points:** `.fabro/project.toml`, `.fabro/workflows/implement-plan/workflow.fabro`, `.fabro/workflows/smoke/workflow.fabro` +- **Owns:** Repository pull-request defaults, Daytona development environment, named workflow catalog, local prompts, GitHub permissions, and maintenance commands +- **Depends on:** `fabro-build-tooling`, `fabro-cli`, `fabro-config`, `fabro-github`, `fabro-graphviz`, `fabro-sandbox`, `fabro-workflow`, `repository-development-policy` +- **Evidence:** .fabro/project.toml — selects the repository environment, resources, lifecycle, labels, and pull-request defaults; .fabro/workflows/implement-plan/workflow.fabro — invokes repository Cargo and Bun verification and build tooling + +### `coding-agent-automation` — Repository Coding-Agent Automation + +- **Purpose:** Supplies repository-local review prompts, documentation and changelog skills, edit hooks, and an image-generation helper to coding agents. +- **Paths:** `.ai/prompts/**`, `.claude/settings.json`, `.claude/skills/**`, `bin/agent/**` +- **Excludes:** `.claude/skills/*/watermark` +- **Entry points:** `.ai/prompts/code-review-fast.md`, `.claude/skills/changelog/SKILL.md`, `.claude/skills/docs/SKILL.md`, `bin/agent/imagegen` +- **Owns:** Code-review orchestration, changelog and documentation maintenance, post-edit formatting hook, and agent image-generation command +- **Depends on:** `public-documentation`, `public-release-history` +- **Evidence:** .ai/prompts/code-review-deep-1.md — begins the multi-stage review artifact pipeline; .claude/skills/docs/SKILL.md — defines the code-to-public-documentation update workflow; .claude/settings.json — registers the repository post-edit Rust formatting hook + +## Exclusions and Unmapped Code + +- `lib/packages/fabro-api-client/src/**` — Generated TypeScript/Axios output written by the package's pinned OpenAPI Generator command; generated headers and .openapi-generator metadata corroborate the output boundary. +- `apps/marketing/.vercel/**` — Vercel CLI link metadata whose own README identifies it as automatically created local project/team state. +- `lib/apps/fabro-spa/assets/**` — Placeholder for ignored embedded-SPA build output; repository instructions and .gitignore identify the directory as generated. +- `docs/brainstorms/**`, `docs/ideation/**`, `docs/plans/**`, `docs/superpowers/plans/**`, `docs/superpowers/specs/**`, `docs/internal/cargo-target-apfs-churn-plan.md`, `docs/internal/cli-workflow-coupling-audit.md`, `docs/internal/event-schema-competitive-analysis.md`, `docs/internal/fabro-event-schema-v2-proposal.md`, `docs/internal/mcp-server-qa-test-plan.md`, `docs/internal/plan-events-as-source-of-truth-follow-ups.md`, `docs/internal/plan-events-as-source-of-truth.md`, `docs/internal/slow-test-opportunities-2026-04-07.md` — Point-in-time brainstorms, implementation plans, audits, research, handoffs, and superseded proposals rather than maintained source contracts. +- `docs/internal/demo/*.svg`, `docs/internal/demo/*.png`, `docs/public/images/*-workflow.svg`, `docs/public/images/tutorial-*.svg`, `docs/public/images/brave-search-research.svg`, `docs/public/images/how-fabro-works.svg`, `docs/public/images/nlspec-conformance.svg`, `docs/public/images/plan-implement-readme.svg` — Graphviz-generated SVG and PNG renderings whose executable or documentation graph sources remain assigned. +- `docs/internal/licenses/**` — Vendored third-party Graphviz license text rather than Fabro source. +- `evals/swe-bench/scoreboard/**` — Committed evaluation records generated by record_results.py, not executable evaluation source. +- `.fabro/skills/rust-style-guide/**` — Vendored policy payload copied from the brynary/rust-style-guide repository at a recorded commit. +- `Cargo.lock`, `bun.lock` — Machine-maintained dependency resolution snapshots consumed in locked or frozen mode. +- `.claude/skills/*/watermark` — Generated progress-state commit SHAs overwritten by the owning skill workflows. +- `.fabro/project.toml.bak` — Stale backup of the canonical .fabro/project.toml configuration. +- `.fabro/workflows/goal/workflow.svg`, `.github/assets/**` — Non-runtime workflow illustration and unreferenced pull-request review screenshots. +- `CLAUDE.md`, `install.sh`, `install.md` — Tracked symlink aliases whose canonical targets are assigned elsewhere, avoiding duplicate assessment of identical content. +- `LICENSE.md` — Repository legal text rather than an implementation or documentation component. +- `docs/internal/assets/brand/github-header-v2-mesh.png` — unmapped +- `docs/internal/assets/brand/github-header-v2-mesh.svg` — unmapped +- `docs/internal/assets/brand/logo/logotype-black.svg` — unmapped +- `docs/internal/assets/brand/logo/logotype.svg` — unmapped +- `docs/internal/assets/brand/logo/symbol-black.svg` — unmapped +- `docs/internal/assets/brand/logo/symbol.svg` — unmapped +- `docs/internal/assets/brand/palette-lockups.svg` — unmapped +- `docs/internal/assets/brand/palette-mockup-icons.svg` — unmapped +- `docs/internal/assets/brand/palette-mockup.svg` — unmapped +- `docs/internal/assets/brand/palette.png` — unmapped +- `docs/internal/assets/brand/palette.svg` — unmapped +- `docs/internal/assets/brand/social-card.html` — unmapped +- `docs/internal/assets/brand/social-card.png` — unmapped +- `docs/internal/assets/brand/twitter-card-v0.176.1.html` — unmapped +- `docs/internal/assets/brand/twitter-card-v0.176.1.png` — unmapped + +## Open Questions + +- Should the currently unreferenced docs/internal/assets brand collateral be assigned to a maintained brand component, or remain explicitly unmapped until an ownership and update workflow is identified? +- Should the first-run browser installer become a separate component if its route and state lifecycle gains an independent entry point, rather than remaining inside fabro-web-app? +- Should fabro-workflow eventually split run-operation/materialization ownership from pipeline execution if those facades acquire independent state and public contracts? diff --git a/.chisel/cartography/work/docs.md b/.chisel/cartography/work/docs.md new file mode 100644 index 0000000000..482b37beac --- /dev/null +++ b/.chisel/cartography/work/docs.md @@ -0,0 +1,238 @@ +# Documentation cartography scout + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` + +Instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and the Chisel cartography prompt. Scope is every tracked file under `docs/**`, plus `README.md` and `install.md`. + +## Inventory + +There are **488** scoped tracked files: + +| Area | Files | +| --- | ---: | +| `docs/public/**` | 253 | +| `docs/internal/**` | 82 | +| `docs/plans/**` | 88 | +| `docs/brainstorms/**` | 11 | +| `docs/ideation/**` | 3 | +| `docs/superpowers/**` | 49 | +| `README.md`, `install.md` | 2 | + +## Proposed components + +### `public-documentation` — Public documentation + +- **Purpose:** Own the authored Fabro user documentation, Mintlify presentation/configuration, repository landing page, and the maintenance procedure for published web screenshots. +- **Globs:** + - `README.md` + - `docs/public/**` + - `docs/internal/updating-web-screenshots.md` +- **Exclude globs:** + - `docs/public/api-reference/fabro-api.yaml` — separate source contract + - `docs/public/changelog/**` — separate published release-history component + - all 22 generated public Graphviz SVG globs listed under exclusions below +- **Entry points:** + - `README.md` + - `docs/public/docs.json` + - `docs/public/getting-started/introduction.mdx` + - `docs/public/getting-started/quick-start.mdx` + - `docs/internal/updating-web-screenshots.md` +- **Owns:** + - Mintlify theme, navigation, tabs, and page ordering + - public concepts, guides, tutorials, administration material, and reference prose + - public documentation images, manually maintained SVG illustrations, logos, syntax definitions, and curated web screenshots + - repository-facing overview and documentation links + - web-screenshot capture and verification workflow +- **Depends on candidates:** `fabro-http-api-contract`, `documentation-demo-workflows`, the CLI/config components that refresh fenced reference regions. +- **Evidence:** + - `AGENTS.md:46-51` mounts `docs/public` as the Mintlify document root. + - `docs/public/docs.json` declares the Mintlify schema, theme, navigation, OpenAPI tab, and changelog tab. + - `README.md` links to `docs.fabro.sh` and embeds assets from `docs/public/images` and `docs/public/logo`. + - `docs/internal/updating-web-screenshots.md` names `docs/public/images/web/` as the screenshot destination, maps files to UI routes and doc consumers, and defines the refresh/verification workflow. + - `lib/foundation/fabro-dev/src/commands/docs.rs` exposes `cargo dev docs refresh/check`; `docs_cli_reference.rs` and `docs_options_reference.rs` update only fenced regions of `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx`. The two whole files remain assigned here because substantial prose outside those fences is authored. + - `test/docs/extract_dots.py` extracts workflow examples from the public docs for validation. +- **Assigned count:** **112**: 110 public-site files after the API contract, changelog, and 22 generated SVGs are removed, plus `README.md` and the screenshot-maintenance guide. + +### `public-release-history` — Published changelog + +- **Purpose:** Preserve and publish dated user-facing release/change records independently of current reference documentation. +- **Globs:** `docs/public/changelog/**` +- **Entry points:** `docs/public/docs.json` changelog navigation; newest page at the assessed revision is `docs/public/changelog/2026-07-25.mdx`. +- **Owns:** dated titles, migration warnings, feature summaries, and historical behavior notes. +- **Depends on candidates:** `public-documentation` for Mintlify navigation/presentation. +- **Evidence:** + - `docs/public/docs.json` gives changelog its own top-level tab and lists every dated page. + - The 120 `docs.json` changelog page entries exactly match the 120 tracked MDX files. + - Each page has date/title frontmatter and describes changes for that date. + - `lib/apps/fabro-server/tests/it/api/docs.rs:45-50` deliberately reads a changelog page as historical documentation. +- **Assigned count:** **120**. + +### `fabro-http-api-contract` — Fabro HTTP API contract + +- **Purpose:** Define the OpenAPI-first wire contract used by the server, generated clients/types, conformance tests, and published API reference. +- **Globs:** `docs/public/api-reference/fabro-api.yaml` +- **Entry points:** `docs/public/api-reference/fabro-api.yaml` +- **Owns:** HTTP routes, request/response schemas, authentication declarations, and API-facing wire documentation. +- **Depends on candidates:** none at the documentation layer; parent reconciliation should make its consumers depend on this component. +- **Consumers / evidence:** + - `AGENTS.md:55-61` explicitly calls this file the source of truth and documents the Rust and TypeScript regeneration workflow. + - `lib/foundation/fabro-api/build.rs:159` consumes it for Rust generation. + - `lib/packages/fabro-api-client/package.json:7` consumes it for TypeScript Axios generation. + - `lib/apps/fabro-server/src/server/handler/system.rs:694` embeds it in the server. + - `lib/apps/fabro-server/tests/it/openapi_conformance.rs:21` reads it for route/spec conformance. + - `docs/public/docs.json` points Mintlify's API tab at it. +- **Assigned count:** **1**. + +### `documentation-demo-workflows` — Executable documentation demos + +- **Purpose:** Provide runnable workflow definitions and supporting configuration/prompts used by public tutorials and demonstrations. +- **Globs:** + - `docs/internal/demo/*.fabro` + - `docs/internal/demo/*.toml` + - `docs/internal/demo/prompts/**` +- **Exclude globs:** + - `docs/internal/demo/*.svg` + - `docs/internal/demo/*.png` +- **Entry points:** + - `docs/internal/demo/01-hello.fabro` + - `docs/internal/demo/14-search-imagegen.toml` + - tutorial commands of the form `fabro run docs/internal/demo/.fabro` +- **Owns:** small executable example graphs, the image-generation demo run config, and shared demo prompt text. +- **Depends on candidates:** CLI runner, workflow engine/validator, agent tools, and configured sandbox/model providers. +- **Evidence:** + - Public tutorials such as `docs/public/tutorials/hello-world.mdx`, `parallel-review.mdx`, `multi-model.mdx`, `plan-implement.mdx`, and `ensemble.mdx` invoke these paths directly. + - `docs/public/core-concepts/models.mdx:250-251` also uses these graphs as runnable model examples. + - `docs/internal/demo/14-search-imagegen.toml` selects its graph, Daytona environment, snapshot, and output assets. + - `.fabro` files are complete Graphviz workflow entry documents with `goal`, start, and exit nodes. +- **Assigned count:** **16** (14 `.fabro`, one `.toml`, one prompt). + +### `internal-engineering-guidance` — Active engineering policies and architecture references + +- **Purpose:** Record active repository-wide engineering policies and maintained architectural/runtime contracts that guide implementation changes. +- **Globs:** + - `docs/internal/*-strategy.md` + - `docs/internal/*-policy.md` + - `docs/internal/events.md` + - `docs/internal/fabro-event-schema-v2-concrete-shape.md` + - `docs/internal/llm-client-resolution.md` + - `docs/internal/run-directory-keys.md` +- **Entry points:** + - `AGENTS.md:136-146` + - `docs/internal/events-strategy.md` + - `docs/internal/testing-strategy.md` + - `docs/internal/error-handling-strategy.md` +- **Owns:** + - logging, events, testing, migrations, secret handling, error handling, React-effect, and panic policies + - the maintained event catalog and implemented V2 event design explanation + - LLM client-resolution rules, parallel-execution semantics, and run scratch-file reference +- **Depends on candidates:** the runtime, server, CLI, web, configuration/auth, and workflow components whose contracts it describes. These are documentation dependencies rather than build edges. +- **Evidence:** + - `AGENTS.md:136-146` makes seven strategy/policy documents mandatory reading before related changes. + - `docs/internal/events-strategy.md` distinguishes durable product events from tracing and identifies their consumers. + - `docs/internal/events.md` is the maintained serialized event catalog and was updated near the assessed revision. + - `docs/internal/fabro-event-schema-v2-concrete-shape.md:5` says `Status: implemented`; it also says the hand-written Rust types, not this document, are the actual contract source of truth. + - `docs/internal/parallel-strategy.md:3` says `Status: implemented` and was updated with the shared-checkout behavior at the assessed revision. + - `lib/foundation/fabro-vault/src/store.rs:359` links implementation documentation back to `docs/internal/migrations-strategy.md`. +- **Assigned count:** **13**. + +### `product-context` — Internal product framing + +- **Purpose:** Maintain concise product intent, audience, current shape, success signals, and stable technical/product constraints. +- **Globs:** `docs/internal/product/**` +- **Entry points:** + - `docs/internal/product/product-description.md` + - `docs/internal/product/current-state.md` +- **Owns:** business problem, personas, product description, current-state snapshot, success metrics, and product-level technical requirements. +- **Depends on candidates:** none as a build edge; it informs product and documentation work across the repository. +- **Evidence:** + - The six documents have complementary named roles rather than dated implementation tasks. + - `docs/internal/product/current-state.md` explicitly describes a deliberately brief current product snapshot. + - `docs/internal/product/technical-requirements.md` explicitly calls its contents stable constraints product changes should respect. +- **Assigned count:** **6**. + +## Cross-scope assignment + +### `install.md` -> marketing-site component + +- **Count:** **1**. +- `install.md` is a tracked mode-`120000` symlink to `apps/marketing/public/install.md`. +- Commit `0cc02c294dac23e3ace7646528431e758e37eea1` states that Vercel deploys the marketing subtree, so the real file lives there and the repository-root path is a symlink. +- `apps/marketing/src/pages/index.astro` advertises `https://fabro.sh/install.md`. +- The root alias should therefore be claimed by the component that owns `apps/marketing/public/install.md`, rather than by `public-documentation`. + +## Evidence-backed exclusions + +### Historical brainstorm, plan, audit, and design records — 159 files + +These are point-in-time requirements, ideation, implementation plans, handoffs, one-time QA instructions, measurements, audits, or superseded proposals. They remain useful history but are not active source contracts or maintained policy components. + +| Glob/path | Count | Evidence | +| --- | ---: | --- | +| `docs/brainstorms/**` | 11 | Dated `*-requirements.md` brainstorm artifacts. | +| `docs/ideation/**` | 3 | Dated ideation records. | +| `docs/plans/**` | 88 | Dated implementation plans and handoffs. | +| `docs/superpowers/plans/**` | 45 | Dated execution plans. | +| `docs/superpowers/specs/**` | 4 | Dated feature/design specs. | +| `docs/internal/cargo-target-apfs-churn-plan.md` | 1 | Checkbox execution plan with an unfilled results section. | +| `docs/internal/cli-workflow-coupling-audit.md` | 1 | Snapshot audit organized around completed and remaining couplings. | +| `docs/internal/event-schema-competitive-analysis.md` | 1 | Dated comparative research report. | +| `docs/internal/fabro-event-schema-v2-proposal.md` | 1 | Explicit `Status: proposal`; the implemented concrete-shape document supersedes its framing. | +| `docs/internal/mcp-server-qa-test-plan.md` | 1 | Explicitly says it is a one-time manual QA pass, not a reusable testing template. | +| `docs/internal/plan-events-as-source-of-truth-follow-ups.md` | 1 | Prerequisite implementation plan. | +| `docs/internal/plan-events-as-source-of-truth.md` | 1 | Implementation plan/summary rather than current contract reference. | +| `docs/internal/slow-test-opportunities-2026-04-07.md` | 1 | Dated measurement dataset and implementation-status record. | + +This exclusion does **not** include `docs/public/changelog/**`: the changelog is a live, complete Mintlify publication surface and is mapped as its own component. + +### Generated Graphviz renderings — 44 files + +| Glob/path | Unique count | Evidence | +| --- | ---: | --- | +| `docs/internal/demo/*.svg` | 11 | Every file contains `Generated by graphviz`; each has a same-stem `.fabro` source. | +| `docs/internal/demo/*.png` | 11 | Same-stem raster renderings were introduced alongside the `.fabro` and generated SVG files; their pixel dimensions match the SVG point dimensions at Graphviz's 96-DPI raster scale. | +| `docs/public/images/*-workflow.svg` | 9 | Every matching tracked file contains `Generated by graphviz`. | +| `docs/public/images/tutorial-*.svg` | 10 | Every matching tracked file contains `Generated by graphviz`; one file overlaps the previous glob. | +| `docs/public/images/brave-search-research.svg` | 1 | Contains `Generated by graphviz`. | +| `docs/public/images/how-fabro-works.svg` | 1 | Contains `Generated by graphviz`. | +| `docs/public/images/nlspec-conformance.svg` | 1 | Contains `Generated by graphviz`. | +| `docs/public/images/plan-implement-readme.svg` | 1 | Contains `Generated by graphviz`. | + +The public SVG rows resolve to **22 unique files** because `tutorial-sub-workflow.svg` matches both broad globs. Curated UI screenshots and hand-authored SVG illustrations remain assigned to `public-documentation`; `docs/internal/updating-web-screenshots.md` establishes their manual capture and verification workflow. + +The fenced regions in `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx` are generated, but the files are mixed authored/generated documents. Cartography operates at file granularity, so both whole files stay assigned to `public-documentation`. + +### Vendored third-party legal text — 1 file + +- **Glob:** `docs/internal/licenses/graphviz-14.1.5-LICENSE` +- **Count:** **1**. +- **Evidence:** the filename pins Graphviz 14.1.5, the contents are the verbatim Eclipse Public License 2.0 plus secondary-license text, and the introducing commit is `chore: add vendored Graphviz license to docs-internal/licenses`. + +## Unmapped files + +- **Glob:** `docs/internal/assets/**` +- **Count:** **15**. +- These form a coherent collection of logos, palette mockups, headers, and HTML/PNG social-card pairs, but no tracked file consumes these exact paths at the assessed revision. +- `docs/internal/updating-web-screenshots.md` identifies `docs/public/logo/dark.svg` and `docs/public/logo/light.svg`, not the internal assets, as the source-of-truth logos. +- The collection has no manifest, status marker, or documented update workflow establishing whether it is maintained brand source, derived output, or historical design collateral. It should remain unmapped until that ownership is confirmed. + +## Coverage + +| Disposition | Count | +| --- | ---: | +| Assigned to proposed documentation components | 268 | +| Cross-scope assignment (`install.md` to marketing site) | 1 | +| **Assigned total** | **269** | +| Excluded historical records | 159 | +| Excluded generated renderings | 44 | +| Excluded vendored license | 1 | +| **Excluded total** | **204** | +| Unmapped internal brand collateral | 15 | +| **Scoped relevant total** | **488** | + +`269 + 204 + 15 = 488`; every scoped tracked file is assigned, excluded, or explicitly unmapped. + +## Open questions + +1. Are the 15 files under `docs/internal/assets/**` maintained brand sources, or intentionally retained historical collateral? A component should be added only if an owner/update workflow confirms the former. +2. Should the parent map keep `docs/internal/fabro-event-schema-v2-concrete-shape.md` in active engineering guidance, as proposed here based on `Status: implemented` and recent updates, or treat it as an implemented design record now that Rust event types and `events.md` carry the live contract? +3. Confirm the final marketing component ID that will claim the `install.md` symlink together with `apps/marketing/public/install.md`. diff --git a/.chisel/cartography/work/ops.md b/.chisel/cartography/work/ops.md new file mode 100644 index 0000000000..ef4b6c16ae --- /dev/null +++ b/.chisel/cartography/work/ops.md @@ -0,0 +1,461 @@ +# Repository operations cartography scout + +Assessed revision: +`2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`). + +Owned scope: root-level tracked files plus tracked files under `.ai/**`, +`.cargo/**`, `.claude/**`, `.config/**`, `.fabro/**`, `.github/**`, +`bin/**`, `docker/**`, and `installer/**`. Files under `lib/**`, `apps/**`, +`docs/**`, `test/**`, and `evals/**` were not counted. The +`lib/foundation/fabro-dev/**` and `lib/foundation/build-support/**` trees were +consulted only as boundary and dependency evidence because the foundation +scout owns them. + +Applicable instructions read: `AGENTS.md`, its `CLAUDE.md` symlink, and +`CONTRIBUTING.md`. + +## Inventory and boundary approach + +- `git ls-tree -r --name-only` at the assessed revision yields exactly 143 + tracked files in this scope: 24 root files, four under `.ai/`, one under + `.cargo/`, eight under `.claude/`, one under `.config/`, 87 under `.fabro/`, + seven under `.github/`, one under `bin/`, eight under `docker/`, and two + under `installer/`. +- Repository-wide manifests, tool configuration, and contributor rules are + grouped as one development-policy component. They form the shared contract + used by Cargo, Bun, nextest, rustfmt, Clippy, contributors, coding agents, + and CI; splitting every configuration file would create small boundaries + without independent entry points. +- Pull-request CI and release automation are separate. The former validates + changes on branch events, while the latter owns version tags and publication + of binary, container, GitHub Release, and Homebrew artifacts. +- Product container packaging and operator Compose deployment are grouped + because the image layout, entrypoint, runtime environment, proxy files, and + Compose stacks share one deployable artifact contract. The explicit + split-web proof-of-concept is retained in this proposed component, with the + question noted below. +- `.fabro/project.toml`, its development image, and the named workflow catalog + are grouped as the repository's Fabro-native automation surface. They share + the `fabro run ` consumer, project defaults, clone-based execution + environment, and repository-maintenance lifecycle. +- The smaller `.ai`, `.claude`, and `bin/agent` families are grouped as coding + agent automation. Their clients differ, but all supply repository-local + prompts, skills, hooks, or helper commands to agents working on this + repository. +- Machine-produced state, a backup, vendored policy text, non-runtime review + assets, legal/overview metadata, and canonical-file symlink aliases are + excluded with exact counts below. + +## Proposed components + +### `repository-development-policy` — Repository development policy + +- **Assigned file count:** 11 +- **Purpose:** Defines the repository-wide Rust and JavaScript workspace, + dependency, formatting, lint, test, version-control, contributor, and coding + agent development contract. +- **Globs:** + - `.cargo/**` + - `.config/**` + - `.gitattributes` + - `.gitignore` + - `AGENTS.md` + - `CONTRIBUTING.md` + - `Cargo.toml` + - `package.json` + - `bunfig.toml` + - `clippy.toml` + - `rustfmt.toml` +- **Exclude globs:** none +- **Entry points:** + - `Cargo.toml:[workspace]` + - `Cargo.toml:[workspace.dependencies]` + - `Cargo.toml:[workspace.lints]` + - `package.json:workspaces` + - `.cargo/config.toml:[alias]` + - `.config/nextest.toml` + - `AGENTS.md` + - `CONTRIBUTING.md` +- **Owns:** Rust and Bun workspace membership; shared Rust dependency and + version policy; workspace lint and compilation profiles; Bun linker + selection; Cargo developer aliases and test proxy policy; nextest timeout + profiles; rustfmt and Clippy policy; tracked/generated path treatment; and + repository-wide contributor and agent instructions. +- **Depends-on candidates:** `fabro-build-tooling` (the `cargo dev` alias + dispatches to its feature-gated binary). +- **Evidence:** + - `Cargo.toml` — declares all Rust workspace members, default members, + workspace package metadata, shared dependencies, lint policy, and build + profiles. + - `package.json` and `bunfig.toml` — declare the JavaScript workspace and + deterministic Bun workspace linker contract. + - `.cargo/config.toml` — exposes `cargo dev` as the CLI entry to + `fabro-dev`, defines the test alias, and supplies the repository test + proxy-policy environment. + - `.config/nextest.toml`, `clippy.toml`, and `rustfmt.toml` — are direct + configuration inputs to the repository's test, lint, and formatting + commands. + - `AGENTS.md` and `CONTRIBUTING.md` — define the repository-wide build/test + commands, architectural policies, and contribution workflow. + - `.gitattributes` and `.gitignore` — actively define generated-file + classification and the source/output boundary used by developers and CI. + - `lib/foundation/fabro-dev/Cargo.toml` and + `lib/foundation/fabro-dev/src/lib.rs:Command` — out-of-scope evidence that + the Cargo alias targets a distinct internal development CLI. + +### `repository-ci` — Pull-request and branch continuous integration + +- **Assigned file count:** 3 +- **Purpose:** Runs branch and pull-request validation for the Rust and + TypeScript workspaces and configures static validation of GitHub Actions + workflows. +- **Globs:** + - `.github/workflows/rust.yml` + - `.github/workflows/typescript.yml` + - `.github/zizmor.yml` +- **Exclude globs:** none +- **Entry points:** + - `.github/workflows/rust.yml` + - `.github/workflows/typescript.yml` + - `.github/zizmor.yml` +- **Owns:** branch/path trigger policy; Rust format, lint, generated-doc, test, + and twin-E2E jobs; TypeScript typecheck, test, and production-build jobs; + concurrency cancellation; CI test profile selection; and repository-local + workflow-linter exceptions. +- **Depends-on candidates:** `repository-development-policy`, + `fabro-build-tooling`, `fabro-web-app`, + `fabro-api-client-generation`, and `twin-openai`. The workflows are also + integration consumers of the full Rust workspace rather than a production + runtime dependency of each Rust component. +- **Evidence:** + - `.github/workflows/rust.yml` — path-gates Rust-relevant changes and runs + the pinned formatter, Clippy, generated-document check, workspace nextest + suite, and selected twin-mode E2E packages. + - `.github/workflows/typescript.yml` — installs the frozen Bun workspace, + typechecks the web app and generated-client package, runs web tests, and + invokes `cargo dev build` for the release-style embedded-SPA build. + - `.github/zizmor.yml` — is consumed alongside those workflows and names + workflow-specific action-reference exceptions. + - `lib/foundation/fabro-dev/src/commands/build.rs` — out-of-scope evidence + that `cargo dev build` refreshes the SPA and then forwards to Cargo build. + +### `release-distribution-automation` — Release and package publication + +- **Assigned file count:** 4 +- **Purpose:** Cuts nightly releases and publishes versioned CLI archives, + GitHub Releases, multi-architecture container images, attestations, and + stable/nightly Homebrew formulas. +- **Globs:** + - `.github/workflows/nightly.yml` + - `.github/workflows/release.yml` + - `installer/**` +- **Exclude globs:** none +- **Entry points:** + - `.github/workflows/nightly.yml` + - `.github/workflows/release.yml` + - `installer/fabro.rb.template` + - `installer/fabro-nightly.rb.template` +- **Owns:** scheduled nightly tag creation; cross-platform release target + matrix; CLI archive/checksum generation; provenance attestations; GitHub + Release creation; release container publication; stable and nightly release + channel selection; and Homebrew formula template substitution/publication. +- **Depends-on candidates:** `repository-development-policy`, + `fabro-build-tooling`, `container-packaging-and-deployment`, `fabro-cli`, + and `fabro-spa`. +- **Evidence:** + - `.github/workflows/nightly.yml` — mints the release-app token and invokes + `cargo --locked dev release --nightly` after ensuring the current commit + does not already have a nightly tag. + - `.github/workflows/release.yml` — is triggered by version tags, compiles + and packages five targets, attests archives and container images, creates + the GitHub Release, publishes the multi-architecture image, and updates + stable or nightly Homebrew formulas. + - `installer/fabro.rb.template` and + `installer/fabro-nightly.rb.template` — define the platform archive URLs, + checksum placeholders, installed binary, and Homebrew smoke test consumed + by the release workflow. + - `lib/foundation/fabro-dev/src/commands/release.rs` — out-of-scope evidence + that the developer CLI owns release version computation, test smoke, + `Cargo.toml`/`Cargo.lock` update, commit, tag, and push before the tag + workflow publishes artifacts. + - `lib/foundation/fabro-dev/src/commands/docker_build.rs` — out-of-scope + evidence that local image construction intentionally shares the release + pipeline's `tmp/docker-context//fabro` layout. + +### `container-packaging-and-deployment` — Container packaging and deployment + +- **Assigned file count:** 16 +- **Purpose:** Packages the Fabro CLI/server as a runtime container and + defines supported local, production, Tailscale, and split-web Compose + deployments around that image. +- **Globs:** + - `.dockerignore` + - `.env.example` + - `Dockerfile` + - `docker-compose*.yaml` + - `docker/**` +- **Exclude globs:** none +- **Entry points:** + - `Dockerfile` + - `docker/entrypoint.sh` + - `docker/preflight.sh` + - `docker-compose.yaml` + - `docker-compose.prod.yaml` + - `docker-compose.tailscale.yaml` + - `docker-compose.split-web.yaml` +- **Owns:** staged multi-architecture binary image layout; runtime package and + unprivileged-user setup; storage-home and Docker-socket group handoff; + deployment environment contract; preflight resource/daemon/network checks; + Caddy proxy/TLS behavior; Compose services, volumes, ports, and health + checks; and the split static-web/API deployment configuration. +- **Depends-on candidates:** `fabro-cli`, `fabro-server`, `fabro-web-app`, and + `fabro-build-tooling`. +- **Evidence:** + - `Dockerfile` — consumes the architecture-specific binary staged under + `tmp/docker-context`, installs runtime dependencies, and installs the + shared entrypoint. + - `docker/entrypoint.sh` — owns storage permissions, Docker socket group + mapping, and privilege drop before launching Fabro. + - `docker/preflight.sh` — is a standalone deployment readiness entry point + for Docker version/daemon, Compose, CPU, memory, disk, port, and registry + reachability. + - `docker-compose.yaml`, `docker-compose.local.yaml`, + `docker-compose.prod.yaml`, and `docker-compose.tailscale.yaml` — define + distinct operator compositions around the same Fabro image and runtime + state. + - `docker-compose.split-web.yaml` and `docker/split-web/**` — jointly own the + alternate edge/API/static-web composition; the local README documents its + request ownership and validation commands. + - `.github/workflows/release.yml` and + `lib/foundation/fabro-dev/src/commands/docker_build.rs` — release and local + developer consumers both stage the same per-architecture context consumed + by the root Dockerfile. + +### `fabro-repository-automation` — Fabro-native repository automation + +- **Assigned file count:** 41 +- **Purpose:** Configures Fabro's own development environment and supplies the + named workflow graphs, prompts, permissions, and project defaults used for + repository maintenance, integration demonstrations, and workflow examples. +- **Globs:** + - `.fabro/Dockerfile` + - `.fabro/project.toml` + - `.fabro/workflows/**` +- **Exclude globs:** + - `.fabro/workflows/goal/workflow.svg` +- **Entry points:** + - `.fabro/project.toml` + - `.fabro/workflows/*/workflow.toml` + - `.fabro/workflows/*/workflow.fabro` + - `.fabro/workflows/implement-plan/workflow.fabro` + - `.fabro/workflows/patch-cves/workflow.fabro` + - `.fabro/workflows/pr-simplify/workflow.fabro` + - `.fabro/workflows/smoke/workflow.fabro` +- **Owns:** repository-level pull-request defaults; the `fabro-dev` Daytona + environment and resource/lifecycle labels; its browser-capable Rust/Bun + development image; named workflow graph catalog; workflow-local prompts; + GitHub integration permissions; and repository verification/maintenance + command sequences. +- **Depends-on candidates:** `fabro-cli`, `fabro-config`, `fabro-workflow`, + `fabro-graphviz`, `fabro-sandbox`, `fabro-github`, + `fabro-build-tooling`, and `repository-development-policy`. +- **Evidence:** + - `.fabro/project.toml` — is the project-level Fabro configuration entry, + selecting the Daytona environment, `.fabro/Dockerfile`, resource limits, + lifecycle, labels, and pull-request defaults. + - `.fabro/Dockerfile` — supplies the clone-based workflow environment with + Git, ripgrep, browser/desktop support, GitHub CLI, pinned Rust tooling, + nextest, and Bun. + - `.fabro/workflows/*/workflow.toml` — provides per-workflow graph selection, + environment overrides, pull-request behavior, and GitHub token + permissions. + - `.fabro/workflows/*/workflow.fabro` — provides independently runnable + Graphviz workflow entries for demos, human interaction, GitHub + operations, implementation, verification, maintenance, and smoke tests. + - `.fabro/workflows/implement-plan/workflow.fabro` — invokes the + repository's Cargo/Bun verification contract and `cargo dev` generated-doc + and SPA lifecycle, tying maintenance workflows to the same developer + tooling as CI. + - `.fabro/workflows/patch-cves/**` and + `.fabro/workflows/pr-simplify/**` — pair bundled prompts with the explicit + GitHub permissions and pull-request behavior needed by repository + maintenance runs. + - `AGENTS.md` — documents `fabro run ` as resolving + `.fabro/workflows//workflow.toml`, establishing the catalog's common + consumer. + +### `coding-agent-automation` — Repository coding-agent automation + +- **Assigned file count:** 11 +- **Purpose:** Supplies repository-local code-review prompts, documentation + and changelog skills, edit hooks, and an image-generation helper to external + coding-agent clients. +- **Globs:** + - `.ai/prompts/**` + - `.claude/settings.json` + - `.claude/skills/**` + - `bin/agent/**` +- **Exclude globs:** + - `.claude/skills/*/watermark` +- **Entry points:** + - `.ai/prompts/code-review-fast.md` + - `.ai/prompts/code-review-deep-1.md` + - `.claude/skills/changelog/SKILL.md` + - `.claude/skills/docs/SKILL.md` + - `.claude/settings.json` + - `bin/agent/imagegen` +- **Owns:** fast and multi-stage deep code-review orchestration prompts; + changelog selection and MDX formatting procedure; code-to-documentation + mapping and update procedure; post-edit Rust formatting hook; and the + command-line Gemini image request/output flow. +- **Depends-on candidates:** `public-documentation` and + `public-release-history` are data/format consumers of the two skills; the + remaining prompts and helper use external agent, GitHub CLI, Git, and Gemini + interfaces rather than product runtime components. +- **Evidence:** + - `.ai/prompts/code-review-deep-{1,2,3}.md` — define a three-artifact review + pipeline from candidate discovery through analysis and false-positive + filtering. + - `.ai/prompts/code-review-fast.md` — defines pull-request eligibility, + parallel review/confidence filtering, and the GitHub comment output + contract. + - `.claude/skills/changelog/SKILL.md` and its references — define the + Git-history-to-Mintlify changelog workflow and output format. + - `.claude/skills/docs/SKILL.md` and its mapping reference — define the + Git-history-to-public-doc update workflow and map implementation paths to + published documentation pages. + - `.claude/settings.json` — registers the repository-local post-edit Rust + formatting hook. + - `bin/agent/imagegen` — is an executable helper that loads repository + environment credentials, calls the Gemini image endpoint, and writes the + decoded image. + +## Evidence-backed exclusions + +### Vendored Rust style-guide skill + +- **Glob:** `.fabro/skills/rust-style-guide/**` +- **Count:** 44 tracked files. +- **Reason/evidence:** Commit `9af0296469b902c9780a983dee5bee07b0abbcdf` + explicitly records all 44 files as vendored from + `brynary/rust-style-guide` commit `8fd2a4f`, trimmed to the runtime skill + payload. The files are copied policy/procedure content rather than authored + implementation owned by this repository. The skill entry point also routes + readers across the copied `guidelines/**` and `workflows/**` payload. + +### Dependency resolution outputs + +- **Paths:** `Cargo.lock`, `bun.lock` +- **Count:** two tracked files. +- **Reason/evidence:** These are machine-maintained dependency resolution + snapshots. `lib/foundation/fabro-dev/src/commands/release.rs` explicitly + runs `cargo update --workspace` and stages `Cargo.lock`, while all CI/release + consumers use Cargo `--locked` or Bun `--frozen-lockfile`; the manifests and + policies that generate and consume them remain assigned. + +### Skill watermarks + +- **Glob:** `.claude/skills/*/watermark` +- **Count:** two tracked files. +- **Reason/evidence:** Each file is a commit SHA used as generated progress + state. `.claude/skills/changelog/SKILL.md` and + `.claude/skills/docs/SKILL.md` each explicitly instruct their workflow to + overwrite its watermark with `git rev-parse HEAD`. + +### Project configuration backup + +- **Path:** `.fabro/project.toml.bak` +- **Count:** one tracked file. +- **Reason/evidence:** The `.bak` file preserves the previous inline + `[run.sandbox.daytona]`/snapshot configuration, while + `.fabro/project.toml` is the canonical current project configuration and + points to the separate `.fabro/Dockerfile`. + +### Non-runtime workflow and review assets + +- **Paths:** `.fabro/workflows/goal/workflow.svg`, `.github/assets/**` +- **Count:** three tracked files: one SVG workflow illustration and two PNG + screenshots. +- **Reason/evidence:** The goal workflow's runtime TOML points to + `workflow.fabro`, not the SVG, and the SVG has no tracked runtime consumer. + Commit `ac32963538f4441d40a47fcfcd868ca290d2b899` identifies the two PNGs as + live screenshots captured for a web-feature pull request and says they are + safe to remove from that change; no tracked source references them at the + assessed revision. + +### Canonical-file symlink aliases + +- **Paths:** `CLAUDE.md`, `install.sh`, `install.md` +- **Count:** three tracked symlinks. +- **Reason/evidence:** Git records each with mode `120000`. Their targets are + `AGENTS.md`, `apps/marketing/public/install.sh`, and + `apps/marketing/public/install.md`, respectively. The canonical instruction + file is assigned above, while the canonical install resources are owned by + the web scout's `fabro-marketing-site`; excluding aliases prevents the same + content from being assessed twice. + +### Root overview and legal metadata + +- **Paths:** `README.md`, `LICENSE.md` +- **Count:** two tracked files. +- **Reason/evidence:** `README.md` is the repository/product landing document + and routes readers to the public installation and documentation surfaces; + it does not define an independently executable or state-owning boundary. + `LICENSE.md` is the repository's MIT legal text. Neither should form a + quality-scored implementation component on its own. + +## Coverage ledger + +| Classification | Files | +| --- | ---: | +| `repository-development-policy` | 11 | +| `repository-ci` | 3 | +| `release-distribution-automation` | 4 | +| `container-packaging-and-deployment` | 16 | +| `fabro-repository-automation` | 41 | +| `coding-agent-automation` | 11 | +| Vendored Rust style-guide skill | 44 | +| Dependency resolution outputs | 2 | +| Skill watermarks | 2 | +| Project configuration backup | 1 | +| Non-runtime workflow and review assets | 3 | +| Canonical-file symlink aliases | 3 | +| Root overview and legal metadata | 2 | +| **Total** | **143** | + +Computed scope coverage: + +- **Relevant tracked files:** 143 +- **Assigned to proposed components:** 86 +- **Excluded with evidence:** 57 +- **Unmapped:** 0 + +The component and exclusion patterns above were resolved against the assessed +revision's `git ls-tree` inventory. They are disjoint, and +`86 + 57 + 0 = 143`. + +## Open boundary questions + +1. Should `repository-development-policy` remain one repository-wide + developer contract, or should the final map separate executable + workspace/tool configuration from the contributor/agent governance in + `AGENTS.md` and `CONTRIBUTING.md`? +2. Should `container-packaging-and-deployment` split into an image-packaging + component and an operator Compose-deployment component? The root + `Dockerfile` has a release/local-build lifecycle, while the Compose/Caddy + files own runtime topology, but both share the image and entrypoint + contract. +3. Should the explicitly named split-web proof-of-concept remain inside the + container deployment component, become a separate experimental deployment + component, or be excluded as non-production material? +4. Should `.fabro/project.toml` and `.fabro/Dockerfile` remain with the named + workflow catalog? They share the Fabro project/run consumer today, but the + environment image and project defaults could change independently from + individual graphs. +5. Should the small `.ai`, `.claude`, and `bin/agent` families remain grouped + as `coding-agent-automation`, or does the final map need separate + review-automation and documentation-maintenance boundaries despite their + small file counts? +6. Should root `README.md` remain excluded as repository overview metadata, + or should it be folded into the docs scout's `public-documentation` + component even though it sits outside `docs/**`? diff --git a/.chisel/cartography/work/review.md b/.chisel/cartography/work/review.md new file mode 100644 index 0000000000..e71fa83955 --- /dev/null +++ b/.chisel/cartography/work/review.md @@ -0,0 +1,198 @@ +# Independent cartography review + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` + +Reviewed artifact: +`.chisel/cartography/work/candidate-codebase-map.json`. + +This review is limited to component boundaries, dependencies, evidence, and +file disposition. It does not assess implementation quality. + +## Independent inventory check + +I resolved the fixed tree with `git ls-tree -r --name-only` and matched every +component glob, component exclusion, global exclusion, and declared unmapped +path independently of the candidate's renderer. + +- Tracked files: **3,104** +- Candidate claims: **2,256** +- Candidate global exclusions: **848** +- Candidate unmapped files: **0** +- Files without a disposition: **0** +- Files claimed by multiple components, or both claimed and globally excluded: + **0** +- Overlap between separate global-exclusion entries: **0** + +The candidate's mechanical accounting is therefore correct as written. +Component IDs are unique, all named dependencies resolve, all globs resolve, +and every evidence/entry-point path exists in the fixed tree. A symbol-text +check also found no missing Rust/TypeScript symbols among the qualified +references; the one non-symbol qualifier is the valid JSON property reference +`package.json:scripts.generate`. + +Mechanical coverage does not settle whether each disposition or boundary is +architecturally correct. The supported corrections below change the +classification of 15 files but leave the total inventory unchanged. + +## Supported corrections + +### 1. Move `docs/internal/assets/**` from global exclusion to `unmapped_files` + +All 15 files under `docs/internal/assets/**` are currently excluded because +they have no tracked consumer or documented update workflow. That establishes +that ownership is unresolved; it does not establish that the SVG, HTML, and +raster files are generated, vendored, build output, or historical records. +The candidate's own open question likewise asks whether they are maintained +brand sources. + +Until that question is answered, exclusion asserts more than the evidence +supports. Preserve the open question and list the 15 exact tracked paths as +unmapped. This changes coverage to **2,256 assigned, 833 excluded, 15 +unmapped**. + +### 2. Restore `fabro-spa` as a separate component + +`lib/apps/fabro-spa/Cargo.toml` declares an independent Rust package with the +specific responsibility “Embedded production SPA assets for Fabro.” +`lib/apps/fabro-spa/src/lib.rs` exposes the server-facing `get` and +`AssetBytes` interface, owns compile-time embedding and hashes, and is consumed +directly by `lib/apps/fabro-server/src/static_files.rs` and +`lib/apps/fabro-server/src/csp.rs`. + +Folding those two assigned files into `fabro-web-app` combines a browser +application with a Rust server adapter that has a different entry point, +consumer, toolchain, and reason to change. It also turns the precise dependency +`fabro-server -> fabro-spa` into the over-broad +`fabro-server -> fabro-web-app`. + +Add a `fabro-spa` component for `lib/apps/fabro-spa/Cargo.toml` and +`lib/apps/fabro-spa/src/**`; retain `lib/apps/fabro-spa/assets/**` as the +evidence-backed generated-output exclusion. Remove those assigned paths from +`fabro-web-app`, replace the server's web-app edge with +`fabro-server -> fabro-spa`, and let the SPA refresh tooling express the +build-time connection to the browser app. + +The two-file size is not by itself a reason to hide this package: it has a +manifest, public interface, owned compile-time lifecycle, and independent +consumer boundary, the same kind of evidence used to retain other small Rust +components in the candidate. + +### 3. Separate `fabro-build-support` from `fabro-build-tooling` + +`lib/foundation/build-support/Cargo.toml` is an independent package whose only +responsibility is build-script Git/profile metadata. +`lib/foundation/build-support/git_metadata.rs` exposes that public API, and +the direct consumers are `lib/apps/fabro-cli/build.rs` and +`lib/apps/fabro-server/build.rs`. + +The remaining `fabro-dev` package is an executable repository-development CLI +with SPA, documentation, release, benchmark, and container command +lifecycles. Combining these packages hides shared compile-time infrastructure +inside an unrelated command application; the candidate purpose has to join +“runs repository ... automation” with “supplies compile-time Git metadata” to +cover both. + +Add a `fabro-build-support` component for +`lib/foundation/build-support/**`. Keep `lib/foundation/fabro-dev/**`, +`test/bin/release_test.sh`, and `test/analysis/bench-tests-diff.sql` in the +existing development-tooling component. Add +`fabro-cli -> fabro-build-support` and +`fabro-server -> fabro-build-support`, which are explicit Cargo build +dependencies. + +### 4. Correct the shared fixture dependency direction + +`workflow-test-corpus` is inert input data. The candidate evidence identifies +the readers: + +- `fabro-test` resolves files beneath `../../../test/`; +- `fabro-cli` source/tests install the root and template fixtures; +- `fabro-graphviz` and `fabro-validate` enumerate + `test/dot-compatibility`; +- `fabro-workflow` enumerates `test/attractor`. + +Those consumers depend on the corpus, just as the generated API clients depend +on their source contract. The candidate currently records the reverse and +also names `fabro-template`, for which there is no direct corpus read. + +Make `workflow-test-corpus.depends_on` empty, add +`workflow-test-corpus` to the five direct consumer components above, and omit +the unsupported `fabro-template` edge. This correction does not require +redistributing the shared files. + +### 5. Add direct operational dependencies omitted from +`fabro-build-tooling` + +The candidate's purpose and evidence include operations whose source contains +explicit repository-component dependencies, but its dependency list contains +only Cargo library dependencies: + +- `docs_cli_reference.rs` invokes `fabro-cli` and writes + `docs/public/reference/cli.mdx`; +- `docs_options_reference.rs` writes the same public-documentation surface; +- `spa_refresh.rs` invokes the build in `apps/fabro-web` and mirrors its output + into `lib/apps/fabro-spa/assets`; +- `docker_build.rs` runs the root container build; +- `release.rs` reads and updates the root Cargo workspace contract. + +Add dependencies from `fabro-build-tooling` to `fabro-cli`, +`public-documentation`, `fabro-web-app`, the restored `fabro-spa`, +`container-packaging-and-deployment`, and +`repository-development-policy`. These are the same operational dependency +kind already used for CI, release, repository-workflow, and documentation +components; omitting them only for the development CLI makes the graph +inconsistent. + +### 6. Add `public-documentation -> public-release-history` + +`docs/public/docs.json`, owned by `public-documentation`, enumerates every +changelog page and gives the collection its top-level publication surface. +The existing `public-release-history -> public-documentation` edge captures +the changelog's dependence on Mintlify presentation, but it omits the direct +navigation/configuration dependency in the other direction. Retain the +existing edge and add the reciprocal edge. + +## Optional boundary questions + +These are plausible alternatives, but the fixed revision does not require +them as corrections: + +1. **First-run web installer.** The 14 install/mode files have a distinct + router, reducer, API facade, storage token, and lifecycle, so a + `fabro-web-install` component is supportable now; it does not need a + separate binary entry point to qualify. On the other hand, it is selected + by the shared browser entry and imports the app's common UI/runtime. For the + recommended map, keep it in `fabro-web-app` and preserve this as an open + boundary question. Splitting it would raise the component count by one. +2. **Shared workflow corpus ownership.** Its cross-crate consumers justify the + shared corpus component. Distributing the root/template, Attractor, and DOT + compatibility subcorpora to their consumers is also possible, but would + make the DOT corpus arbitrarily owned by one of two readers. Retain the + shared component unless later assessment proves its combined boundary + noisy. +3. **Workflow, LLM, store, and server subcomponents.** The candidate's broad + components have recognizable internal areas, but their crate facades, + shared state, and integration lifecycles currently support the retained + crate/service boundaries. No additional split is required at this + revision. + +No candidate component is supported for removal or merger. In particular, the +single-file OpenAPI contract and the small MCP, evaluation, CI, and release +components have independent source-of-truth, protocol, executable, or +publication lifecycles that justify their granularity. + +## Recommended disposition + +Apply the two supported package splits and retain the optional boundaries as +questions: + +- **Recommended component count:** **70** (candidate 68, plus + `fabro-spa` and `fabro-build-support`) +- **Relevant tracked files:** **3,104** +- **Assigned:** **2,256** +- **Excluded:** **833** +- **Unmapped:** **15** (`docs/internal/assets/**`, listed as exact paths) +- **Overlap or uncovered files:** **0** + +The counts satisfy `2,256 + 833 + 15 = 3,104`. The optional installer split +would produce 71 components without changing coverage. diff --git a/.chisel/cartography/work/rust-apps.md b/.chisel/cartography/work/rust-apps.md new file mode 100644 index 0000000000..4734558964 --- /dev/null +++ b/.chisel/cartography/work/rust-apps.md @@ -0,0 +1,216 @@ +# Rust Applications Cartography Scout + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`) + +Scope: tracked files under `lib/apps/**`. Root `Cargo.toml`, `.gitignore`, +`AGENTS.md`, and `CONTRIBUTING.md` were read only as workspace, exclusion, and +repository-instruction evidence; they are not included in the scope counts. +`CLAUDE.md` resolves to the same repository guidance as `AGENTS.md`. + +The primary proposal is one component per Cargo application package. These +boundaries are established by independent package manifests, binary or library +entry points, public interfaces, package-owned lifecycle/state, package test +suites, and explicit Cargo dependency edges. The CLI and server have broad +module trees, but their entry points and tests converge on one executable or +one shared server state/router respectively. + +## Inventory and coverage + +The inventory was computed with: + +```text +git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/apps +``` + +| Scope | Tracked | Assigned | Excluded | Unmapped | +| --- | ---: | ---: | ---: | ---: | +| `lib/apps/fabro-cli/**` | 241 | 241 | 0 | 0 | +| `lib/apps/fabro-mcp-server/**` | 5 | 5 | 0 | 0 | +| `lib/apps/fabro-server/**` | 112 | 112 | 0 | 0 | +| `lib/apps/fabro-spa/**` | 3 | 2 | 1 | 0 | +| **Total** | **361** | **360** | **1** | **0** | + +The one excluded tracked file is +`lib/apps/fabro-spa/assets/.gitkeep`. `AGENTS.md` states that embedded SPA +assets are refreshed build output and are gitignored except for `.gitkeep`; +`.gitignore` corroborates this with `lib/apps/fabro-spa/assets/*` and the +explicit `.gitkeep` exception. The placeholder is therefore excluded as +evidence of a generated build-output directory. No generated code, vendored +code, dependency trees, or other build output is tracked elsewhere in this +scope. + +## Proposed components + +### `fabro-cli` — Fabro CLI Application + +- **Purpose:** Provides the `fabro` command-line application, including command parsing and dispatch, terminal presentation, server/client bootstrap, and the hidden local run-worker process entry. +- **Assigned file count:** 241 +- **Globs:** + - `lib/apps/fabro-cli/Cargo.toml` + - `lib/apps/fabro-cli/build.rs` + - `lib/apps/fabro-cli/src/**` + - `lib/apps/fabro-cli/tests/**` +- **Exclude globs:** none +- **Entry points:** + - `lib/apps/fabro-cli/src/main.rs:main` + - `lib/apps/fabro-cli/src/main.rs:main_inner` + - `lib/apps/fabro-cli/src/args.rs:Cli` + - `lib/apps/fabro-cli/src/args.rs:Commands` + - `lib/apps/fabro-cli/src/commands/run/mod.rs:dispatch` +- **Owns:** + - The `fabro` process lifecycle, exit classification, telemetry bootstrap, and logging bootstrap. + - CLI argument and subcommand contracts plus human-readable and JSON output behavior. + - Per-command resolved settings, lazy API client/credential/catalog state in `CommandContext`. + - Local server discovery/startup and authenticated server connections. + - The hidden `__run-worker` subprocess entry and its terminal run-progress presentation. +- **Candidate `depends_on` IDs within this scout:** `fabro-mcp-server`, `fabro-server`. +- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-checkpoint`, `fabro-client`, `fabro-config`, `fabro-dump`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp`, `fabro-model`, `fabro-oauth`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-static`, `fabro-store`, `fabro-telemetry`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge. +- **Evidence:** + - `lib/apps/fabro-cli/Cargo.toml:[[bin]]` — declares package `fabro-cli` as the `fabro` binary with `src/main.rs` as its entry point and lists direct workspace dependencies, including `fabro-mcp-server` and `fabro-server`. + - `Cargo.toml:[workspace]` — includes `lib/apps/*` as members and selects `lib/apps/fabro-cli` as the default workspace member. + - `lib/apps/fabro-cli/src/main.rs:main_inner` — creates the shared command context and dispatches every `Commands` variant, including the server and run-worker paths. + - `lib/apps/fabro-cli/src/args.rs:Commands` — defines the complete top-level CLI command surface; `RunCommands` includes the hidden `__run-worker` entry. + - `lib/apps/fabro-cli/src/command_context.rs:CommandContext` — owns the per-invocation settings, output mode, storage path, lazy server client, credential source, and model catalog shared by commands. + - `lib/apps/fabro-cli/src/server_client.rs:connect_server_with_settings` — resolves local or remote targets and constructs the authenticated control-plane client used by command implementations. + - `lib/apps/fabro-cli/tests/it/main.rs` — assembles command, scenario, support, and end-to-end workflow tests around the same binary application boundary. + +### `fabro-mcp-server` — Fabro MCP Stdio Server + +- **Purpose:** Exposes Fabro run operations as an MCP stdio tool server and supplies MCP-client configuration generation and installation helpers used by the CLI. +- **Assigned file count:** 5 +- **Globs:** + - `lib/apps/fabro-mcp-server/Cargo.toml` + - `lib/apps/fabro-mcp-server/src/**` +- **Exclude globs:** none +- **Entry points:** + - `lib/apps/fabro-mcp-server/src/lib.rs:start` + - `lib/apps/fabro-mcp-server/src/server.rs:start` + - `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings` + - `lib/apps/fabro-mcp-server/src/config.rs:config_json` + - `lib/apps/fabro-mcp-server/src/config.rs:init_agent` +- **Owns:** + - The MCP stdio service lifecycle and registered Fabro tool router. + - Lazy construction of the Fabro client-backed tool backend. + - Translation from MCP run-create inputs to Fabro API run manifests. + - MCP client configuration rendering and updates to supported agent config files. +- **Candidate `depends_on` IDs within this scout:** `fabro-server`. +- **Manifest-backed cross-scope dependency candidates:** `fabro-api`, `fabro-client`, `fabro-config`, `fabro-manifest`, `fabro-model`, `fabro-tool`, `fabro-types`, `fabro-util`. +- **Evidence:** + - `lib/apps/fabro-mcp-server/Cargo.toml:[package]` — declares a distinct library package described as the Fabro MCP stdio server and lists a direct `fabro-server` dependency. + - `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings` — defines the public construction boundary, client factory, config path, and working directory used to start the service. + - `lib/apps/fabro-mcp-server/src/server.rs:start` — owns the `rmcp` stdio service lifecycle; `FabroMcpServer` owns the tool router and lazy backend. + - `lib/apps/fabro-mcp-server/src/manifest_builder.rs:McpRunManifestBuilder` — adapts MCP tool creation requests through `fabro_server::run_tool_manifest`. + - `lib/apps/fabro-cli/src/commands/mcp/mod.rs:dispatch` — the separate CLI package consumes this library solely through its public start/config/init interfaces. + +### `fabro-server` — Fabro HTTP Server + +- **Purpose:** Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, schedulers, worker processes, sessions, authentication, integrations, and startup/shutdown. +- **Assigned file count:** 112 +- **Globs:** + - `lib/apps/fabro-server/Cargo.toml` + - `lib/apps/fabro-server/build.rs` + - `lib/apps/fabro-server/migrations/**` + - `lib/apps/fabro-server/src/**` + - `lib/apps/fabro-server/tests/**` +- **Exclude globs:** none +- **Entry points:** + - `lib/apps/fabro-server/src/serve.rs:serve_command` + - `lib/apps/fabro-server/src/server.rs:AppState` + - `lib/apps/fabro-server/src/server.rs:build_router` + - `lib/apps/fabro-server/src/server.rs:build_router_with_options` + - `lib/apps/fabro-server/src/server.rs:spawn_scheduler` + - `lib/apps/fabro-server/src/lib.rs` +- **Owns:** + - Listener binding, resolved startup configuration, migrations, web enablement, and graceful shutdown. + - Shared `AppState`: managed runs, persistent stores, session runtimes, artifact storage, resource sampling, settings/catalog state, and integration services. + - API and web routing, authentication/principal middleware, static-file delivery, security headers, and OpenAPI conformance at the router boundary. + - Run and automation scheduling, worker launch/control/token state, cancellation escalation, and global event broadcast. + - Server-side install, diagnostics, GitHub webhook, Slack, environment, secret, variable, MCP-server, and sandbox coordination exposed through HTTP handlers. +- **Candidate `depends_on` IDs within this scout:** `fabro-spa`. +- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-automation`, `fabro-client`, `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp-store`, `fabro-model`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-slack`, `fabro-static`, `fabro-store`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-variable`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge. +- **Evidence:** + - `lib/apps/fabro-server/Cargo.toml:[package]` — declares a distinct HTTP-server library package, an integration-test target gated by `test-support`, and a direct `fabro-spa` dependency. + - `lib/apps/fabro-server/src/lib.rs` — exposes the server's supported module/API surface and gates `test_support` behind tests or the explicit feature. + - `lib/apps/fabro-server/src/serve.rs:serve_command` — resolves settings and secrets, runs database and compatibility migrations, builds stores/state/router, binds listeners, starts background services, and coordinates shutdown. + - `lib/apps/fabro-server/src/server.rs:AppState` — centralizes the service's run registry, stores, session and worker runtime state, schedulers, event channel, settings, credentials, integrations, and shutdown token. + - `lib/apps/fabro-server/src/server.rs:build_router_with_options` — composes real/demo APIs, auth/web routes, middleware, static assets, and the health surface around the shared state. + - `lib/apps/fabro-server/src/server/handler/mod.rs:real_routes` — registers the HTTP resource handlers that consume `AppState`. + - `lib/apps/fabro-server/tests/it/main.rs` — assembles API, conformance, pagination, and lifecycle scenario tests around the same library/router boundary. + +### `fabro-spa` — Embedded SPA Assets + +- **Purpose:** Provides the compile-time embedded production SPA asset lookup API and precomputed content hashes consumed by the HTTP server. +- **Assigned file count:** 2 +- **Globs:** + - `lib/apps/fabro-spa/Cargo.toml` + - `lib/apps/fabro-spa/src/**` + - `lib/apps/fabro-spa/assets/**` +- **Exclude globs:** + - `lib/apps/fabro-spa/assets/**` +- **Entry points:** + - `lib/apps/fabro-spa/src/lib.rs:get` + - `lib/apps/fabro-spa/src/lib.rs:AssetBytes` +- **Owns:** + - Compile-time embedding of production SPA files from `assets/`. + - Asset byte ownership and the SHA-256 metadata returned to server static-file handling. + - The invariant that source maps are not embedded. +- **Candidate `depends_on` IDs within this scout:** none +- **Manifest-backed cross-scope dependency candidates:** none +- **Evidence:** + - `lib/apps/fabro-spa/Cargo.toml:[package]` — declares a distinct library package for embedded production SPA assets and depends only on `rust-embed`. + - `lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets` — defines the compile-time asset folder and source-map exclusions. + - `lib/apps/fabro-spa/src/lib.rs:get` — is the package's public asset lookup interface and returns bytes with their precomputed SHA-256 value. + - `lib/apps/fabro-server/src/static_files.rs` — consumes `fabro_spa::get` and `fabro_spa::AssetBytes`, establishing the direction `fabro-server` → `fabro-spa`. + - `AGENTS.md` and `.gitignore` — identify `assets/` contents as refreshed, ignored build output while preserving only `.gitkeep`. + +## Dependency reconciliation notes + +The in-scope application dependency edges are exact production Cargo edges: + +```text +fabro-cli ───────────────→ fabro-server ───────────────→ fabro-spa + └──→ fabro-mcp-server ───→ fabro-server +``` + +The cross-scope dependency labels above use Cargo package names as provisional +component IDs. If another scout groups multiple packages into one component, +the parent map should translate those package edges to the reconciled +component ID. Build-time and dev-only edges should be handled consistently +across the final map; the primary candidate lists above include production +and build-time edges but do not add dev-only test-support dependencies. + +Dev-only workspace edges that may matter during reconciliation are: + +- `fabro-cli` tests additionally use `fabro-acp`, `fabro-macros`, + `fabro-server` with `test-support`, `fabro-types` with `test-support`, and + `fabro-workflow` with `test-support`. +- `fabro-server` tests additionally use `fabro-macros`, `fabro-sandbox` with + `test-support`, and `fabro-types` with `test-support`. + +## Exclusions and unmapped files + +- **Excluded:** `lib/apps/fabro-spa/assets/.gitkeep` — placeholder retained in + an otherwise ignored generated-asset directory. +- **Unmapped:** none. + +## Open boundary questions + +1. Should `fabro-server` remain one service component, as proposed, or should + the final repository map expose separate server transport/auth and + run/worker-coordination components? `serve_command`, `AppState`, and the + integration suite currently join those lifecycles, while the public auth + modules, handler tree, and worker-control modules offer possible + sub-boundaries. +2. Should the hidden `fabro __run-worker` path remain part of `fabro-cli`, as + proposed, or be represented as a run-worker component? It has a distinct + process lifecycle and is launched by `fabro-server`, but it shares the CLI + binary, manifest, dispatch, command context, and integration-test suite. +3. Should MCP client configuration/init behavior and the MCP stdio tool + service remain one `fabro-mcp-server` component, as proposed? They are + separate public operations but share one five-file package and one CLI + namespace. +4. Should `fabro-spa` remain a separate component, as proposed, or be folded + into `fabro-server` because all generated payloads are excluded and the + remaining package has two assigned files? Its separate Cargo package and + public asset/hash interface establish a dependency boundary, while its only + production consumer in this scope is the server. diff --git a/.chisel/cartography/work/rust-components.md b/.chisel/cartography/work/rust-components.md new file mode 100644 index 0000000000..64f672a176 --- /dev/null +++ b/.chisel/cartography/work/rust-components.md @@ -0,0 +1,391 @@ +# Cartography scout report: Rust components + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`) + +Scope: tracked files under `lib/components/**`, with workspace manifests and public consumers consulted only as boundary evidence. + +## Boundary synthesis + +The scope contains 23 non-published, shared in-repository Rust library crates. The primary proposal keeps one component per crate: every crate has its own manifest and crate root, exposes a distinct public vocabulary or execution facade, and owns a separate domain state, external protocol, or runtime lifecycle. This also keeps the regular Cargo dependency edges directional and makes every glob non-overlapping. + +The four SQLite-backed resource crates (`fabro-automation`, `fabro-environment`, `fabro-mcp-store`, and `fabro-variable`) use a similar storage pattern, but their identifiers, validation, import formats, tables, and public consumers differ; they are therefore proposed as separate components. The two-file crates (`fabro-dump`, `fabro-install`, and `fabro-manifest`) are also kept separate because each contains a substantial public operation and has a distinct dependency/consumer boundary rather than being a collection of incidental helpers. + +Checked-in snapshots, prompt templates, grammars, migrations, and test fixture keys are assigned to the component whose behavior they exercise. No tracked file in this scope has evidence of being vendored or build output, and no checked-in generated source is excluded. + +## Proposed components + +### `fabro-acp` — Agent Client Protocol runtime + +- Purpose: Launch and control Agent Client Protocol processes through Fabro sandboxes and translate their sessions into Fabro run results. +- Globs: `lib/components/fabro-acp/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-acp/src/lib.rs`, `lib/components/fabro-acp/src/command.rs:AcpProcessSpec`, `lib/components/fabro-acp/src/session.rs:run_acp_turn` +- Owns: ACP process specifications; ACP transport/session lifetime; live steering and cancellation handles; ACP process exit/error translation. +- Depends on candidates: `fabro-sandbox` +- Evidence: + - `lib/components/fabro-acp/Cargo.toml` — declares an ACP backend crate with a default `runtime` feature and an optional runtime dependency on `fabro-sandbox`. + - `lib/components/fabro-acp/src/lib.rs` — exposes the process specification and runtime session/control API while keeping transport internal. + - `lib/components/fabro-acp/tests/session.rs` — exercises the session boundary as an integration test. +- Scoped tracked files: 8 + +### `fabro-agent` — Coding agent runtime + +- Purpose: Run programmable coding-agent sessions, including model profiles, context management, native tools, permissions, MCP tools, and subagents. +- Globs: `lib/components/fabro-agent/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-agent/src/lib.rs`, `lib/components/fabro-agent/src/session.rs:Session`, `lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry`, `lib/components/fabro-agent/src/cli.rs:run_with_args` +- Owns: agent session state and history; agent/model profiles and prompt templates; tool registry and execution lifecycle; context compaction; todo/question/subagent runtimes; agent-emitted events. +- Depends on candidates: `fabro-llm`, `fabro-mcp`, `fabro-sandbox` +- Evidence: + - `lib/components/fabro-agent/Cargo.toml` — describes a programmable agentic loop and declares direct dependencies on the LLM, MCP, and sandbox crates. + - `lib/components/fabro-agent/src/lib.rs` — presents one crate-level facade spanning sessions, profiles, tools, permissions, history, and subagent supervision. + - `lib/components/fabro-agent/tests/it/main.rs` — anchors the crate's integration-test suite; profile prompt snapshots and `.j2` templates are behavioral assets of the same runtime. +- Scoped tracked files: 66 + +### `fabro-automation` — Automation definitions and storage + +- Purpose: Validate, version, import, and durably store scheduled, API-triggered, and manual Fabro automation definitions. +- Globs: `lib/components/fabro-automation/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-automation/src/lib.rs`, `lib/components/fabro-automation/src/store.rs:AutomationStore`, `lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once` +- Owns: automation IDs and revisions; automation targets and triggers; canonical revision calculation; automation SQLite records; legacy file-definition import. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-automation/Cargo.toml` — declares “Automation domain and durable storage for Fabro” and uses the shared database foundation. + - `lib/components/fabro-automation/src/lib.rs` — re-exports the automation domain, validation errors, revisions, store, and one-time importer as one API. + - `lib/components/fabro-automation/tests/store.rs` and `lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs` — cover and evolve the owned automation persistence format. +- Scoped tracked files: 9 + +### `fabro-checkpoint` — Git checkpoint storage + +- Purpose: Store workflow checkpoints and metadata in Git commits and dedicated metadata branches. +- Globs: `lib/components/fabro-checkpoint/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-checkpoint/src/lib.rs`, `lib/components/fabro-checkpoint/src/branch.rs:BranchStore`, `lib/components/fabro-checkpoint/src/git.rs:Store` +- Owns: Git tree entries and checkpoint commits; metadata-branch naming and access; checkpoint commit authorship and trailers; checkpoint-specific error types. +- Depends on candidates: `fabro-store` +- Evidence: + - `lib/components/fabro-checkpoint/Cargo.toml` — identifies Git-backed workflow checkpoint storage and directly depends on `fabro-store`. + - `lib/components/fabro-checkpoint/src/lib.rs` — exposes branch, Git, author, trailer, and checkpoint error modules behind one crate facade. + - `lib/components/fabro-checkpoint/src/branch.rs:BranchStore` and `lib/components/fabro-checkpoint/src/git.rs:Store` — provide the two persistence entry points over the same Git repository state. +- Scoped tracked files: 7 + +### `fabro-dump` — Run dump materialization + +- Purpose: Materialize a stored run projection, event history, checkpoints, artifacts, and referenced blobs into a portable directory tree. +- Globs: `lib/components/fabro-dump/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-dump/src/lib.rs:RunDump`, `lib/components/fabro-dump/src/lib.rs:RunDump::from_store_state_and_events`, `lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir` +- Owns: dump entry layout and filenames; stage ranking within dumps; blob hydration; dump serialization and directory writing. +- Depends on candidates: `fabro-store` +- Evidence: + - `lib/components/fabro-dump/Cargo.toml` — gives the crate a direct dependency on `fabro-store`, which supplies projections and event envelopes. + - `lib/components/fabro-dump/src/lib.rs:RunDump` — contains the public dump-building and writing lifecycle, with inline tests for its output contract. + - Workspace consumers `fabro-cli` and `fabro-workflow` both depend directly on `fabro-dump`, rather than accessing its behavior through `fabro-store`. +- Scoped tracked files: 2 + +### `fabro-environment` — Environment definitions and storage + +- Purpose: Validate, seed, version, import, and durably store server-owned execution environment definitions. +- Globs: `lib/components/fabro-environment/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-environment/src/lib.rs`, `lib/components/fabro-environment/src/store.rs:EnvironmentStore`, `lib/components/fabro-environment/src/store.rs:seed_default_environment` +- Owns: environment IDs and revisions; environment drafts and canonical revisions; environment SQLite records; built-in environment seeding; legacy directory import. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-environment/Cargo.toml` — declares the server-owned environment domain and durable storage. + - `lib/components/fabro-environment/src/lib.rs` — exports a specific environment domain/store API, including seeding and import operations. + - `lib/components/fabro-environment/tests/store.rs` — exercises the environment persistence boundary independently of the other resource stores. +- Scoped tracked files: 7 + +### `fabro-github` — GitHub authentication and API + +- Purpose: Resolve GitHub credentials and perform authenticated GitHub App, repository, branch, and pull-request API operations. +- Globs: `lib/components/fabro-github/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-github/src/lib.rs:GitHubCredentials`, `lib/components/fabro-github/src/lib.rs:GitHubContext`, `lib/components/fabro-github/src/lib.rs:create_pull_request`, `lib/components/fabro-github/src/lib.rs:resolve_authenticated_url` +- Owns: GitHub credential forms and token minting; GitHub API request/response translation; repository URL normalization and authenticated clone URLs; pull-request lifecycle calls. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-github/Cargo.toml` — describes GitHub App authentication and API helpers and declares the JWT/HTTP dependencies used at this boundary. + - `lib/components/fabro-github/src/lib.rs` — defines the credential context, testable HTTP abstraction, App token flow, and repository/PR operations in one public surface. + - `lib/components/fabro-github/tests/integration.rs` and `lib/components/fabro-github/src/testdata/rsa_private.pem` — exercise the external authentication/API boundary using a dedicated test key fixture. +- Scoped tracked files: 4 + +### `fabro-graphviz` — Workflow graph language + +- Purpose: Parse Graphviz DOT into Fabro's typed graph model and parse conditions/stylesheets or render graphs for presentation. +- Globs: `lib/components/fabro-graphviz/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-graphviz/src/lib.rs`, `lib/components/fabro-graphviz/src/parser/mod.rs:parse`, `lib/components/fabro-graphviz/src/condition.rs:parse_condition_expr`, `lib/components/fabro-graphviz/src/render.rs:render_dot` +- Owns: DOT lexer/parser/semantic conversion; graph parsing errors; condition and stylesheet syntax; Graphviz rendering normalization. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-graphviz/Cargo.toml` — names the crate as the DOT parser and typed graph data model. + - `lib/components/fabro-graphviz/src/parser/mod.rs:parse` — is the source-to-typed-graph entry point backed by separate lexer, grammar, AST, and semantic modules. + - `lib/components/fabro-graphviz/src/lib.rs` — exposes parsing-adjacent condition, fidelity, rendering, and stylesheet interfaces as the graph-language boundary. +- Scoped tracked files: 14 + +### `fabro-hooks` — Workflow lifecycle hooks + +- Purpose: Configure and execute user-defined workflow lifecycle hooks and bridge tool hooks into the agent runtime. +- Globs: `lib/components/fabro-hooks/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-hooks/src/lib.rs`, `lib/components/fabro-hooks/src/runner.rs:HookRunner`, `lib/components/fabro-hooks/src/executor.rs:HookExecutor`, `lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback` +- Owns: hook configuration and event selection; hook execution context; hook result/decision merging; HTTP/command hook dispatch; agent tool-hook bridging. +- Depends on candidates: `fabro-agent`, `fabro-llm` +- Evidence: + - `lib/components/fabro-hooks/Cargo.toml` — identifies workflow lifecycle hooks and directly depends on the agent and LLM components used by hook execution. + - `lib/components/fabro-hooks/src/lib.rs` — exposes hook definitions, decisions, runner, execution context, and the agent bridge. + - `lib/components/fabro-hooks/tests/host_command_hooks.rs` — tests host-command hooks through the public lifecycle boundary. +- Scoped tracked files: 8 + +### `fabro-install` — Installation persistence + +- Purpose: Prepare, persist, and roll back shared CLI/server installation settings, credentials, development tokens, and default environments. +- Globs: `lib/components/fabro-install/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan`, `lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct`, `lib/components/fabro-install/src/lib.rs:merge_server_settings` +- Owns: install persistence plans; settings and server-env mutations; vault writes/removals; development-token creation and rollback; default environment seeding during install. +- Depends on candidates: `fabro-environment` +- Evidence: + - `lib/components/fabro-install/Cargo.toml` — describes shared install primitives for CLI and server flows and directly depends on the environment store. + - `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan` — groups the files, env entries, token, and vault state committed by one install operation. + - Workspace consumers `fabro-cli` and `fabro-server` depend directly on this crate, making it a shared install boundary rather than CLI-local code. +- Scoped tracked files: 2 + +### `fabro-interview` — Human interaction runtime + +- Purpose: Represent workflow questions and answers and provide console, callback, queue, control, recording, replay, and automatic interviewer implementations. +- Globs: `lib/components/fabro-interview/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-interview/src/lib.rs:Interviewer`, `lib/components/fabro-interview/src/lib.rs:ask_with_timeout`, `lib/components/fabro-interview/src/control.rs:ControlInterviewer` +- Owns: question/answer protocol; interviewer request lifetime and timeout behavior; queued and controlled answer delivery; interview recording and replay. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-interview/Cargo.toml` — defines human-in-the-loop interviewer traits and implementations as the crate purpose. + - `lib/components/fabro-interview/src/lib.rs:Interviewer` — is the shared async interaction interface and re-exports all implementation strategies. + - `lib/components/fabro-interview/src/control_protocol.rs` and `lib/components/fabro-interview/src/control.rs` — own the worker-control delivery protocol and pending interaction state. +- Scoped tracked files: 10 + +### `fabro-llm` — Unified LLM client + +- Purpose: Provide a provider-neutral generation API with model routing, middleware, retries, token/cost accounting, provider adapters, and wire codecs. +- Globs: `lib/components/fabro-llm/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-llm/src/lib.rs`, `lib/components/fabro-llm/src/client.rs:Client`, `lib/components/fabro-llm/src/provider.rs:ProviderAdapter`, `lib/components/fabro-llm/src/generate.rs:generate`, `lib/components/fabro-llm/src/generate.rs:stream` +- Owns: normalized LLM request/response/stream types; provider adapter registry; provider-specific authentication and transport; request/response/stream wire translation; retry/middleware/generation orchestration; token and cost calculations. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-llm/Cargo.toml` — describes a unified multi-provider client and does not depend on another component crate. + - `lib/components/fabro-llm/src/provider.rs:ProviderAdapter` and `lib/components/fabro-llm/src/client.rs:Client` — define the adapter contract and client registry through which the provider modules are consumed. + - `lib/components/fabro-llm/tests/it/wire/mod.rs` and its provider-specific snapshot trees — verify that the codecs and adapters implement the same normalized client boundary. +- Scoped tracked files: 188 + +### `fabro-manifest` — Run manifest construction + +- Purpose: Resolve workflow/configuration inputs, collect static dependencies, and construct a self-contained run manifest with Git provenance. +- Globs: `lib/components/fabro-manifest/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-manifest/src/lib.rs:build_run_manifest`, `lib/components/fabro-manifest/src/lib.rs:build_run_overrides`, `lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput` +- Owns: manifest build input/output; configuration-layer resolution for manifest creation; workflow/file dependency collection; Git context and pre-run push preparation. +- Depends on candidates: `fabro-github`, `fabro-graphviz`, `fabro-workflow` +- Evidence: + - `lib/components/fabro-manifest/Cargo.toml` — declares run manifest construction and direct dependencies on graph parsing, GitHub support, and selected workflow utilities. + - `lib/components/fabro-manifest/src/lib.rs:build_run_manifest` — is a single public assembly operation that produces the API `RunManifest`. + - Workspace consumers `fabro-cli`, `fabro-server`, and `fabro-mcp-server` depend directly on the crate to share identical manifest construction. +- Scoped tracked files: 2 + +### `fabro-mcp` — MCP client runtime + +- Purpose: Connect to configured Model Context Protocol servers, manage their connection lifetimes, discover tools, and dispatch qualified tool calls. +- Globs: `lib/components/fabro-mcp/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-mcp/src/lib.rs`, `lib/components/fabro-mcp/src/client.rs:McpClient`, `lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager` +- Owns: MCP client connections; stdio and streaming HTTP transport selection; server connection manager state; tool discovery, qualified names, and call-result conversion. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-mcp/Cargo.toml` — describes the MCP client role and enables the rmcp client/transport features required by it. + - `lib/components/fabro-mcp/src/lib.rs` — exposes client, config, connection manager, and HTTP transport modules while keeping protocol handlers internal. + - `lib/components/fabro-mcp/tests/stdio_integration.rs` — verifies the external MCP process boundary over stdio. +- Scoped tracked files: 10 + +### `fabro-mcp-store` — MCP server catalog storage + +- Purpose: Durably store, revision, cache, and import server-managed MCP server definitions. +- Globs: `lib/components/fabro-mcp-store/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-mcp-store/src/lib.rs`, `lib/components/fabro-mcp-store/src/store.rs:McpServerStore`, `lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once` +- Owns: MCP server definition SQLite records; definition revisions and optimistic concurrency; synchronous catalog cache; legacy directory import. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-mcp-store/Cargo.toml` — declares server-managed MCP catalog durable storage. + - `lib/components/fabro-mcp-store/src/lib.rs` — explicitly states that the domain model is shared but this crate owns persistence, and exports only the store/error/import API. + - `lib/components/fabro-mcp-store/tests/store.rs` — exercises that persistence boundary independently from live MCP connections. +- Scoped tracked files: 6 + +### `fabro-sandbox` — Execution sandbox abstraction + +- Purpose: Define the execution sandbox and provider contracts and implement local, Docker, and Daytona sandbox lifecycles. +- Globs: `lib/components/fabro-sandbox/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-sandbox/src/lib.rs`, `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry` +- Owns: sandbox filesystem/process/terminal interface; provider creation, lookup, and removal lifecycle; local/Docker/Daytona implementations; clone-source setup and reconnect behavior; sandbox errors and redaction. +- Depends on candidates: `fabro-github` +- Evidence: + - `lib/components/fabro-sandbox/Cargo.toml` — defines provider features (`local`, `docker`, `daytona`) around the common sandbox crate and makes GitHub support optional for clone-based providers. + - `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox` and `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider` — separate per-sandbox operations from provider lifecycle management within one public boundary. + - `lib/components/fabro-sandbox/tests/docker_streaming.rs` and `lib/components/fabro-sandbox/tests/daytona_streaming_live.rs` — exercise provider implementations against the shared contract. +- Scoped tracked files: 23 + +### `fabro-slack` — Slack interaction integration + +- Purpose: Connect to Slack Socket Mode and translate workflow questions, answers, run lifecycle events, and thread replies between Slack and Fabro. +- Globs: `lib/components/fabro-slack/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-slack/src/connection.rs:run`, `lib/components/fabro-slack/src/client.rs:SlackClient`, `lib/components/fabro-slack/src/blocks.rs:question_to_blocks` +- Owns: Slack credential resolution; Socket Mode connection/event loop; Slack API client; block rendering; interaction payload parsing; run-to-thread registry and dispatch. +- Depends on candidates: `fabro-interview`, `fabro-workflow` +- Evidence: + - `lib/components/fabro-slack/Cargo.toml` — declares the Slack interviewer integration and directly depends on the interview and workflow components. + - `lib/components/fabro-slack/src/connection.rs:run` — owns the Socket Mode connection lifetime and dispatch loop. + - `lib/components/fabro-slack/src/interaction.rs` and `lib/components/fabro-slack/src/threads.rs` — translate external payloads into interview submissions and associate Slack threads with run state. +- Scoped tracked files: 11 + +### `fabro-store` — Run and authentication persistence + +- Purpose: Persist run event streams, projections, blobs, artifacts, summaries, catalog indexes, and server authentication grants over SlateDB, object storage, and SQLite. +- Globs: `lib/components/fabro-store/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-store/src/lib.rs`, `lib/components/fabro-store/src/slate/mod.rs:Database`, `lib/components/fabro-store/src/slate/run_store.rs:RunDatabase`, `lib/components/fabro-store/src/run_state.rs:RunProjectionReducer` +- Owns: run event append/read lifecycle; run projection reduction and caching; run/blob/artifact key layout; run catalog and summary indexes; authorization-code and refresh-token records; storage-specific errors and locking. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-store/src/lib.rs` — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth records. + - `lib/components/fabro-store/src/slate/mod.rs:Database` — is the shared storage root from which run, blob, catalog, auth-code, and refresh-token stores are obtained. + - `lib/components/fabro-store/tests/serializable_projection.rs` — tests the durable projection representation at the crate boundary. +- Scoped tracked files: 25 + +### `fabro-tool` — Run-control tools + +- Purpose: Define and execute the shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend. +- Globs: `lib/components/fabro-tool/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-tool/src/lib.rs`, `lib/components/fabro-tool/src/common.rs:FabroToolBackend`, `lib/components/fabro-tool/src/common.rs:tool_definitions`, `lib/components/fabro-tool/src/create.rs:create_runs` +- Owns: tool names, JSON schemas, and parameter validation; backend-neutral run-control operations; result DTOs and text rendering; API-client backend adapter. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-tool/Cargo.toml` — identifies shared run-control tool behavior and depends on foundation API/client contracts rather than the server or workflow implementation. + - `lib/components/fabro-tool/src/common.rs:FabroToolBackend` — is the abstraction shared by CLI, server, workflow, and MCP-server consumers. + - `lib/components/fabro-tool/src/lib.rs` — exports a matched set of validated operation/result/text interfaces for all supported tools. +- Scoped tracked files: 12 + +### `fabro-tracker` — Issue tracker adapters + +- Purpose: Provide a common issue-tracker interface with GitHub Projects and Linear implementations. +- Globs: `lib/components/fabro-tracker/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-tracker/src/lib.rs:Tracker`, `lib/components/fabro-tracker/src/github.rs:GitHubTracker`, `lib/components/fabro-tracker/src/linear.rs:LinearTracker` +- Owns: normalized issue and blocker records; candidate-issue query and state-transition contract; GitHub Projects GraphQL adapter; Linear GraphQL adapter. +- Depends on candidates: `fabro-github` +- Evidence: + - `lib/components/fabro-tracker/Cargo.toml` — declares the tracker trait/types boundary and directly depends on GitHub support for one adapter. + - `lib/components/fabro-tracker/src/lib.rs:Tracker` — defines a provider-neutral async issue workflow implemented by both provider modules. + - `lib/components/fabro-tracker/src/fixtures/github-app-test-key.pem` — is a test fixture owned by the GitHub tracker adapter, not a runtime credential or vendored file. +- Scoped tracked files: 5 + +### `fabro-validate` — Workflow graph validation + +- Purpose: Run built-in and catalog-aware lint rules over typed Fabro workflow graphs and return structured diagnostics. +- Globs: `lib/components/fabro-validate/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-validate/src/lib.rs:validate`, `lib/components/fabro-validate/src/lib.rs:validate_with_catalog`, `lib/components/fabro-validate/src/lib.rs:LintRule`, `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules` +- Owns: validation severity and diagnostic structure; lint-rule interface and built-in rule registry; graph/catalog validation traversal; validation error escalation. +- Depends on candidates: `fabro-acp`, `fabro-graphviz` +- Evidence: + - `lib/components/fabro-validate/Cargo.toml` — declares graph validation/linting and directly depends on graph parsing plus ACP backend validation. + - `lib/components/fabro-validate/src/lib.rs:LintRule` — provides the extension interface and public diagnostic API. + - `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules` and the 31 rule source files — form an explicit registry of independently tested rules under one validation lifecycle. +- Scoped tracked files: 36 + +### `fabro-variable` — Workflow variable storage + +- Purpose: Validate, durably store, snapshot, and import workflow-visible non-sensitive variables. +- Globs: `lib/components/fabro-variable/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-variable/src/lib.rs:VariableStore`, `lib/components/fabro-variable/src/lib.rs:VariableStore::value_map`, `lib/components/fabro-variable/src/lib.rs:import_legacy_json_once` +- Owns: variable name validation; variable SQLite records and timestamps; name-to-value snapshots for template contexts; legacy JSON import and backup. +- Depends on candidates: `[]` +- Evidence: + - `lib/components/fabro-variable/Cargo.toml` — defines workflow-visible, non-sensitive variables as a separate storage concern. + - `lib/components/fabro-variable/src/lib.rs:VariableStore` — exposes CRUD and render-context snapshot operations over that single domain. + - `lib/components/fabro-variable/tests/store.rs` — verifies its persistence/import contract independently from environments, automations, and MCP definitions. +- Scoped tracked files: 3 + +### `fabro-workflow` — Workflow orchestration engine + +- Purpose: Transform, validate, initialize, execute, persist, resume, and finalize graph-defined Fabro runs across handlers, lifecycle hooks, sandboxes, checkpoints, events, and human controls. +- Globs: `lib/components/fabro-workflow/**` +- Exclude globs: `[]` +- Entry points: `lib/components/fabro-workflow/src/operations/mod.rs`, `lib/components/fabro-workflow/src/operations/start.rs:start`, `lib/components/fabro-workflow/src/pipeline/mod.rs`, `lib/components/fabro-workflow/src/pipeline/execute.rs:execute`, `lib/components/fabro-workflow/src/handler/mod.rs:Handler` +- Owns: run operation lifecycle (create/start/resume/retry/rewind/fork/archive); workflow transform/validate/initialize/execute/finalize phases; node handler registry and built-in handlers; run-scoped services and cancellation; workflow event conversion/emission; checkpoint, Git, artifact, hook, and status lifecycles; steering and run control. +- Depends on candidates: `fabro-acp`, `fabro-agent`, `fabro-checkpoint`, `fabro-dump`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-interview`, `fabro-llm`, `fabro-mcp`, `fabro-sandbox`, `fabro-store`, `fabro-tool`, `fabro-validate` +- Evidence: + - `lib/components/fabro-workflow/Cargo.toml` — defines the DOT-based workflow runner and declares the component dependencies used to assemble the engine. + - `lib/components/fabro-workflow/src/pipeline/mod.rs` — exposes the ordered parse/transform/validate/initialize/execute/finalize phase boundary and its typed phase states. + - `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` — connect node execution to the run-scoped lifecycle under the same engine. + - `lib/components/fabro-workflow/tests/it/main.rs` and `lib/components/fabro-workflow/tests/materialize_run.rs` — exercise end-to-end orchestration and run materialization. +- Scoped tracked files: 122 + +## Coverage + +The fixed-revision inventory was computed with: + +```text +git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/components +``` + +| Component glob | Assigned tracked files | +| --- | ---: | +| `lib/components/fabro-acp/**` | 8 | +| `lib/components/fabro-agent/**` | 66 | +| `lib/components/fabro-automation/**` | 9 | +| `lib/components/fabro-checkpoint/**` | 7 | +| `lib/components/fabro-dump/**` | 2 | +| `lib/components/fabro-environment/**` | 7 | +| `lib/components/fabro-github/**` | 4 | +| `lib/components/fabro-graphviz/**` | 14 | +| `lib/components/fabro-hooks/**` | 8 | +| `lib/components/fabro-install/**` | 2 | +| `lib/components/fabro-interview/**` | 10 | +| `lib/components/fabro-llm/**` | 188 | +| `lib/components/fabro-manifest/**` | 2 | +| `lib/components/fabro-mcp/**` | 10 | +| `lib/components/fabro-mcp-store/**` | 6 | +| `lib/components/fabro-sandbox/**` | 23 | +| `lib/components/fabro-slack/**` | 11 | +| `lib/components/fabro-store/**` | 25 | +| `lib/components/fabro-tool/**` | 12 | +| `lib/components/fabro-tracker/**` | 5 | +| `lib/components/fabro-validate/**` | 36 | +| `lib/components/fabro-variable/**` | 3 | +| `lib/components/fabro-workflow/**` | 122 | +| **Total** | **580** | + +- Relevant tracked files: 580 +- Assigned files: 580 +- Excluded files: 0 +- Unmapped files: 0 +- Duplicate claims: 0 (the proposed crate-directory globs are disjoint) + +## Exclusions and unmapped files + +- Evidence-backed exclusions: none. +- Unmapped files: none. +- Checked-in `.snap`, `.j2`, `.lark`, migration, README, and test-key files remain assigned because they specify or exercise component behavior. + +## Boundary questions for reconciliation + +1. Should `fabro-workflow` remain one engine component, as proposed, or be split into a public run-operations/materialization component and an execution component? `src/operations/**` and `src/pipeline/**` expose recognizable facades, but `services.rs`, `event.rs`, `runtime_store.rs`, the root modules, and lifecycle/handler code tie both facades to the same run-scoped state and make a non-overlapping ownership split less clear. +2. Should `fabro-llm` remain one unified client component, as proposed, or should `src/providers/**`, `src/codec/**`, and `tests/it/wire/**` form a provider-protocol-adapters component? The adapter trait and wire-focused tests support that sub-boundary, while `adapter_registry.rs`, shared normalized types, transport helpers, and direct module references keep it inside one crate-level client lifecycle. +3. Should `fabro-store` remain one persistence component, as proposed, or should its authorization-code/refresh-token stores be separated from run/event/blob persistence? `slate::Database` exposes them from one storage root, but their record lifecycles are consumed by server authentication rather than workflow execution. diff --git a/.chisel/cartography/work/rust-foundation.md b/.chisel/cartography/work/rust-foundation.md new file mode 100644 index 0000000000..088542416d --- /dev/null +++ b/.chisel/cartography/work/rust-foundation.md @@ -0,0 +1,389 @@ +# Rust foundation cartography scout + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`) + +Scope: all 365 tracked files under `lib/foundation/**`. Root and consumer manifests, the OpenAPI specification, and public consumer entry points were consulted only as boundary evidence and are not part of this scope's coverage counts. + +Applicable instructions read: `AGENTS.md` and `CONTRIBUTING.md` (`CLAUDE.md` is a symlink to `AGENTS.md`). + +## Boundary approach + +- Most foundation crates are proposed as components in their own right because their manifests, crate-root facades, public state or lifecycle, focused tests, and reverse dependency edges describe a distinct responsibility. +- `build-support` and `fabro-dev` are grouped as `fabro-build-tooling`: the two-file build-support crate would otherwise be too narrow for a stable assessment, and both crates serve repository build/development lifecycle rather than product runtime. +- `fabro-macros` and `fabro-options-metadata` are grouped as `fabro-macros-metadata`: the proc-macro crate cannot expose runtime metadata itself, and the `OptionsMetadata` derive and runtime visitor model form one compiler/runtime contract. The proc-macro crate's `Combine` and `e2e_test` entry points remain part of that compiler-support component. +- The small `fabro-http`, `fabro-proc`, and `fabro-static` crates remain separate. Each is a dependency hub with a distinct public policy boundary (HTTP construction/proxy policy, OS process primitives, and shared string registries respectively), so grouping them would mix independent reasons to change. +- `fabro-types` and `fabro-util` remain crate-level components. Their crate-root facades and cross-module use are the stable public boundaries available at this revision; a finer file-family split would not have an independent manifest or facade and would create overlapping conceptual ownership. +- Production and normal compile-time internal dependencies are listed below. Dev-only edges to `fabro-test` are omitted except for the test-support component itself. + +## Proposed components + +### `fabro-build-tooling` — Fabro build and developer tooling + +- **File count:** 23 +- **Purpose:** Runs repository development, build, documentation, SPA, container, benchmark, and release automation and supplies compile-time Git metadata to product build scripts. +- **Globs:** `lib/foundation/build-support/**`, `lib/foundation/fabro-dev/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-dev/src/main.rs:main`, `lib/foundation/fabro-dev/src/lib.rs:run`, `lib/foundation/build-support/git_metadata.rs:collect_from`, `lib/foundation/build-support/git_metadata.rs:cargo_profile` +- **Owns:** developer CLI command dispatch; subprocess plans for build/docs/SPA/Docker/release/test benchmarking; reference generation checks; compile-time Git SHA, rerun paths, and Cargo profile discovery. +- **Depends on candidates:** `fabro-config`, `fabro-macros-metadata`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-dev/Cargo.toml` — declares an internal `fabro-dev` binary/library and integration-test target behind the `dev` feature. + - `lib/foundation/fabro-dev/src/lib.rs:Command` — dispatches the build, Docker, docs, release, SPA, and benchmark command families. + - `lib/foundation/fabro-dev/src/commands/mod.rs:PlannedCommand` — centralizes the subprocess lifecycle shared by those commands. + - `lib/foundation/fabro-dev/tests/it/main.rs` — provides the integration-test composition root for the developer CLI. + - `lib/foundation/build-support/Cargo.toml` and `lib/foundation/build-support/git_metadata.rs:BuildGitMetadata` — define a build-script-only support crate whose public result is embedded Git/build metadata; `lib/apps/fabro-cli/Cargo.toml` and `lib/apps/fabro-server/Cargo.toml` consume it as a build dependency. + +### `fabro-api` — Generated API contract and Rust client + +- **File count:** 60 +- **Purpose:** Generates the low-level Rust HTTP client and API type surface from the OpenAPI contract while reusing canonical Fabro domain types and verifying wire/type parity. +- **Globs:** `lib/foundation/fabro-api/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-api/build.rs:main`, `lib/foundation/fabro-api/src/lib.rs:ApiClient`, `lib/foundation/fabro-api/src/lib.rs:types` +- **Owns:** OpenAPI-to-Progenitor compatibility transformations; generated-client configuration; canonical type replacement map; low-level generated client facade; API/domain type identity and JSON round-trip tests. +- **Depends on candidates:** `fabro-config`, `fabro-model`, `fabro-types` +- **External dependency edges:** API types are also replaced with types from the `fabro-automation` and `fabro-environment` components. +- **Evidence:** + - `lib/foundation/fabro-api/Cargo.toml` — describes generated Rust types and HTTP client and declares `build.rs` generation dependencies. + - `lib/foundation/fabro-api/build.rs:main` — reads `docs/public/api-reference/fabro-api.yaml`, patches the generator view, registers canonical type replacements, and writes `OUT_DIR/codegen.rs`. + - `lib/foundation/fabro-api/src/lib.rs:generated` — includes the generated file behind a private module and exposes `ApiClient` plus a type facade. + - `lib/foundation/fabro-api/tests/run_event_round_trip.rs:run_event_reuses_canonical_type` and the other `tests/*_round_trip.rs` files — verify type identity and OpenAPI JSON shape across the exported contract. + - `docs/public/api-reference/fabro-api.yaml` — repository instructions identify this out-of-scope file as the HTTP contract source of truth. + +### `fabro-auth` — Provider credential resolution + +- **File count:** 16 +- **Purpose:** Resolves provider credentials and interpolated headers from environment or vault sources, refreshes OAuth credentials, and drives interactive authentication strategies. +- **Globs:** `lib/foundation/fabro-auth/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver`, `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource`, `lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy`, `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource` +- **Owns:** provider credential-source precedence; API authorization/header material; configured-provider discovery; OAuth refresh and vault write-back; API-key and Codex-device login strategy state. +- **Depends on candidates:** `fabro-http`, `fabro-model`, `fabro-oauth`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-vault` +- **Evidence:** + - `lib/foundation/fabro-auth/Cargo.toml` — describes typed provider credential storage/resolution and declares the model, OAuth, redaction, vault, HTTP, and type dependencies. + - `lib/foundation/fabro-auth/src/lib.rs` — exposes sources, resolver, strategies, refresh, and vault adapters as the crate facade. + - `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve` — composes catalog policy, vault/environment lookup, header interpolation, and OAuth refresh into the provider-facing credential. + - `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource` — provides the source abstraction used by environment, in-memory vault, and SQLite-backed vault implementations. + - `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource::persist_oauth_refreshes` — owns revision-aware persistence of refreshed OAuth state. + +### `fabro-client` — High-level Fabro service client + +- **File count:** 9 +- **Purpose:** Provides the high-level authenticated Fabro service client over HTTP or Unix sockets, including endpoint operations, SSE streams, token refresh, target normalization, and local CLI auth storage. +- **Globs:** `lib/foundation/fabro-client/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-client/src/client.rs:Client::builder`, `lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect`, `lib/foundation/fabro-client/src/target.rs:ServerTarget`, `lib/foundation/fabro-client/src/auth_store.rs:AuthStore`, `lib/foundation/fabro-client/src/client.rs:RunEventStream` +- **Owns:** connected client transport state; API operation wrappers and error classification; OAuth refresh coordination; HTTP/Unix target canonicalization; SSE buffering; per-server CLI authentication file and locking lifecycle. +- **Depends on candidates:** `fabro-api`, `fabro-http`, `fabro-model`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-client/Cargo.toml` — distinguishes the typed high-level client from the generated `fabro-api` dependency. + - `lib/foundation/fabro-client/src/client.rs:ClientState` and `Client` — own the generated client, raw HTTP client, bearer token, base URL, refresh lock, and optional transport reconnection. + - `lib/foundation/fabro-client/src/target.rs:ServerTarget::build_public_http_client` — defines the HTTP-versus-Unix-socket transport boundary. + - `lib/foundation/fabro-client/src/auth_store.rs:AuthStore` — owns the locked local authentication file lifecycle. + - `lib/foundation/fabro-client/src/lib.rs` — exposes the client, streams, credential, error, session, store, and target facade consumed by CLI/server/tool applications. + +### `fabro-config` — Layered configuration and runtime paths + +- **File count:** 52 +- **Purpose:** Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical storage/runtime paths. +- **Globs:** `lib/foundation/fabro-config/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:RunSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:load_server_runtime_settings`, `lib/foundation/fabro-config/src/lib.rs:load_config_file`, `lib/foundation/fabro-config/src/resolve/mod.rs` +- **Owns:** source-layer structs and merge semantics; built-in defaults; settings parsing/validation/resolution; configuration compatibility migrations; home, storage, runtime-directory, and run-scratch path conventions; daemon/envfile/log-filter configuration helpers. +- **Depends on candidates:** `fabro-macros-metadata`, `fabro-model`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-config/Cargo.toml` — declares the centralized configuration crate and its optional `clap` integration. + - `lib/foundation/fabro-config/src/lib.rs` — exposes layer types, builders, resolvers, parsing, storage, and runtime path facade. + - `lib/foundation/fabro-config/src/builders.rs` — composes defaults and source layers into dense user, server, run, workflow, and model-catalog settings. + - `lib/foundation/fabro-config/src/layers/combine.rs` and `lib/foundation/fabro-config/src/layers/*.rs` — define the layer merge contract and source-specific shapes. + - `lib/foundation/fabro-config/src/migrations.rs` plus `lib/foundation/fabro-config/migrations/*.rs` — register and implement the settings-file migration lifecycle. + - `lib/foundation/fabro-config/src/tests/*.rs` — exercise resolution independently for root, CLI, project, run, server, and workflow sources. + +### `fabro-core` — Generic graph execution kernel + +- **File count:** 13 +- **Purpose:** Executes generic directed workflow graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts. +- **Globs:** `lib/foundation/fabro-core/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-core/src/executor.rs:ExecutorBuilder`, `lib/foundation/fabro-core/src/executor.rs:Executor::run`, `lib/foundation/fabro-core/src/graph.rs:Graph`, `lib/foundation/fabro-core/src/handler.rs:NodeHandler`, `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle` +- **Owns:** in-memory execution state; node/edge traversal loop; handler and lifecycle extension contracts; retry/visit/cancellation decisions; stall-watchdog task lifecycle. +- **Depends on candidates:** `fabro-types`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-core/Cargo.toml` — identifies the crate as the generic workflow execution engine without depending on the higher-level workflow component. + - `lib/foundation/fabro-core/src/graph.rs` — defines generic graph, node, and edge contracts. + - `lib/foundation/fabro-core/src/executor.rs:Executor::run` — owns the traversal and execution lifecycle. + - `lib/foundation/fabro-core/src/state.rs:ExecutionState` — owns current node, outcomes, retries, visits, completed nodes, and context. + - `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle` and `lib/foundation/fabro-core/src/stall.rs:StallWatchdog` — expose the lifecycle hooks and owned background timeout task. + - `lib/components/fabro-workflow/Cargo.toml` — out-of-scope consumer evidence that the product workflow component adapts this lower-level kernel. + +### `fabro-db` — Shared SQLite database foundation + +- **File count:** 9 +- **Purpose:** Opens and migrates the shared SQLite database, manages migration rollback snapshots and private file permissions, and defines the bundled schema migration set. +- **Globs:** `lib/foundation/fabro-db/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-db/src/lib.rs:Database::connect`, `lib/foundation/fabro-db/src/lib.rs:Database::migrate`, `lib/foundation/fabro-db/src/lib.rs:Database::health_check`, `lib/foundation/fabro-db/src/lib.rs:DbPool` +- **Owns:** SQLite pool setup; WAL/synchronous/busy-timeout policy; schema migration registry; pre-migration snapshot and legacy-backup paths; database file permissions; shared tables and indexes declared in `migrations/*.sql`. +- **Depends on candidates:** `[]` +- **Evidence:** + - `lib/foundation/fabro-db/Cargo.toml` — declares a SQLite storage foundation with SQLx migration support. + - `lib/foundation/fabro-db/src/lib.rs:Database` — owns database connection, migration, snapshot, health-check, and pool access lifecycle. + - `lib/foundation/fabro-db/migrations/*.sql` — define the variables, environments, secrets, MCP servers, automations, and run-projection schema compiled into this crate's migrator. + - `lib/foundation/fabro-db/tests/sqlite.rs` — exercises migration, snapshot, permissions, and database behavior at the crate boundary. + - `lib/components/fabro-variable/Cargo.toml`, `lib/components/fabro-environment/Cargo.toml`, `lib/components/fabro-mcp-store/Cargo.toml`, `lib/components/fabro-automation/Cargo.toml`, and `lib/components/fabro-store/Cargo.toml` — out-of-scope manifests show multiple persistence components sharing this foundation. + +### `fabro-http` — Shared HTTP transport construction + +- **File count:** 2 +- **Purpose:** Centralizes reqwest type exposure and synchronous/asynchronous HTTP client construction with Fabro's proxy and test no-proxy policy. +- **Globs:** `lib/foundation/fabro-http/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder`, `lib/foundation/fabro-http/src/lib.rs:http_client`, `lib/foundation/fabro-http/src/lib.rs:test_http_client`, `lib/foundation/fabro-http/src/lib.rs:BlockingHttpClientBuilder` +- **Owns:** approved reqwest facade; proxy-policy resolution from `FABRO_HTTP_PROXY_POLICY`; async/blocking client builders; deterministic no-proxy test clients. +- **Depends on candidates:** `fabro-static` +- **Evidence:** + - `lib/foundation/fabro-http/Cargo.toml` — declares a shared reqwest-wrapper crate. + - `lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` and `HttpClientBuilder` — implement the shared transport-construction policy rather than domain HTTP behavior. + - The root `Cargo.toml` exposes `fabro-http` as a workspace dependency, and app/component manifests consume it directly, establishing it as a cross-cutting transport boundary. + +### `fabro-macros-metadata` — Compile-time macros and option metadata + +- **File count:** 6 +- **Purpose:** Supplies Fabro's derive/attribute macros and the runtime option-metadata model used by generated configuration and documentation tooling. +- **Globs:** `lib/foundation/fabro-macros/**`, `lib/foundation/fabro-options-metadata/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-macros/src/lib.rs:e2e_test`, `lib/foundation/fabro-macros/src/lib.rs:derive_combine`, `lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionSet` +- **Owns:** macro input parsing and expansion for E2E mode gates, configuration-layer combination, and option metadata; option visitor/tree representation; flattened lookup/display/serialization of option metadata. +- **Depends on candidates:** `[]` +- **Evidence:** + - `lib/foundation/fabro-macros/Cargo.toml` — declares the proc-macro crate and a dev dependency on the runtime metadata crate. + - `lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl` — generates implementations against `fabro_options_metadata::OptionsMetadata`. + - `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata` and `OptionSet` — provide the runtime half of that generated contract. + - `lib/foundation/fabro-macros/tests/options_metadata.rs` — tests the proc-macro/runtime pair together. + - `lib/foundation/fabro-config/Cargo.toml` and `lib/foundation/fabro-dev/Cargo.toml` — out-of-scope consumer evidence for configuration derives and generated option documentation. + +### `fabro-model` — LLM model and provider catalog + +- **File count:** 28 +- **Purpose:** Defines provider/model identity, capabilities, billing metadata, embedded catalog data, override merging, and model selection. +- **Globs:** `lib/foundation/fabro-model/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::from_builtin_with_overrides`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::select`, `lib/foundation/fabro-model/src/bootstrap_catalog.rs:catalog`, `lib/foundation/fabro-model/src/lib.rs` +- **Owns:** canonical provider/model IDs; embedded provider TOML catalog; catalog indexes and selection state; provider auth declarations; model capabilities, controls, codecs/adapters, reasoning levels, pricing, and billing calculations. +- **Depends on candidates:** `fabro-static` +- **Evidence:** + - `lib/foundation/fabro-model/Cargo.toml` — names provider identity, model metadata, and resolution as the crate responsibility and embeds catalog resources. + - `lib/foundation/fabro-model/src/catalog.rs:BuiltinCatalogToml` and `Catalog` — load embedded provider files into indexed selection state. + - `lib/foundation/fabro-model/src/catalog/providers/*.toml` — are the tracked built-in provider/model catalog sources. + - `lib/foundation/fabro-model/src/ids.rs` — defines open-ended provider and model identity shared by auth, config, API, and LLM consumers. + - `lib/foundation/fabro-model/src/billing.rs` and `src/types.rs` — define the catalog's billing and public model metadata surfaces. + +### `fabro-oauth` — OAuth PKCE and loopback callback flow + +- **File count:** 3 +- **Purpose:** Implements generic OAuth 2.0 PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh. +- **Globs:** `lib/foundation/fabro-oauth/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow`, `lib/foundation/fabro-oauth/src/lib.rs:start_callback_server_with_errors`, `lib/foundation/fabro-oauth/src/lib.rs:exchange_code`, `lib/foundation/fabro-oauth/src/lib.rs:refresh_token`, `lib/foundation/fabro-oauth/examples/login.rs:main` +- **Owns:** PKCE verifier/challenge and state generation; authorization URL encoding; ephemeral callback listener/task and shutdown handle; callback validation/result delivery; token response decoding and refresh requests. +- **Depends on candidates:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-oauth/Cargo.toml` — declares a generic OAuth 2.0 PKCE token-acquisition crate. + - `lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle` — owns the ephemeral callback server port and shutdown channel. + - `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow` — composes PKCE, callback server, browser, and token exchange into the top-level flow. + - `lib/foundation/fabro-oauth/examples/login.rs` — demonstrates the crate as a standalone protocol flow. + - `lib/foundation/fabro-auth/Cargo.toml` and `lib/apps/fabro-cli/Cargo.toml` — out-of-scope manifests establish both auth-library and direct CLI consumers. + +### `fabro-proc` — OS process primitives + +- **File count:** 8 +- **Purpose:** Wraps platform process primitives for signals, process groups, advisory file locking, pre-exec hooks, process liveness, and process-title rewriting. +- **Globs:** `lib/foundation/fabro-proc/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-proc/src/lib.rs`, `lib/foundation/fabro-proc/src/signal.rs:process_running`, `lib/foundation/fabro-proc/src/signal.rs:sigterm_process_group`, `lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid`, `lib/foundation/fabro-proc/src/title.rs:init` +- **Owns:** Unix signal/process-group calls; cross-platform liveness semantics; advisory locks; child pre-exec configuration; captured argv memory and process title state. +- **Depends on candidates:** `[]` +- **Evidence:** + - `lib/foundation/fabro-proc/Cargo.toml` — describes safe wrappers for process-management primitives and compiles the C argv capture helper. + - `lib/foundation/fabro-proc/src/lib.rs` — is a platform-gated facade over flock, pre-exec, signal, and title modules. + - `lib/foundation/fabro-proc/c/capture_argv.c` and `lib/foundation/fabro-proc/build.rs` — establish the FFI/build boundary for title rewriting. + - `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-cli/Cargo.toml`, and `lib/components/fabro-sandbox/Cargo.toml` — out-of-scope manifests show independent process-lifecycle consumers. + +### `fabro-redact` — Secret and credential redaction + +- **File count:** 8 +- **Purpose:** Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded Gitleaks rules and entropy scanning. +- **Globs:** `lib/foundation/fabro-redact/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-redact/src/lib.rs:redact_string`, `lib/foundation/fabro-redact/src/lib.rs:redacted_url_for_log`, `lib/foundation/fabro-redact/src/jsonl.rs:redact_jsonl_line`, `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` +- **Owns:** Gitleaks rule source and generated rule table; lazy rule engine; entropy thresholds; overlap merging and redaction marker; JSON field/object skip policy; safe URL display semantics. +- **Depends on candidates:** `[]` +- **Evidence:** + - `lib/foundation/fabro-redact/Cargo.toml` — declares the secret/credential redaction boundary. + - `lib/foundation/fabro-redact/build.rs:main` and `lib/foundation/fabro-redact/data/gitleaks.toml` — compile the tracked rule source into an untracked `OUT_DIR` table. + - `lib/foundation/fabro-redact/src/lib.rs:redact_string` — composes entropy and Gitleaks detection into one public redaction surface. + - `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` — owns the raw-versus-display URL credential boundary. + - `lib/foundation/fabro-redact/src/jsonl.rs` — applies the scanner to structured event/log content. + +### `fabro-static` — Shared static conventions + +- **File count:** 4 +- **Purpose:** Defines dependency-light canonical environment-variable names and the registry that classifies bootstrap and optional-vault secrets. +- **Globs:** `lib/foundation/fabro-static/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-static/src/env_vars.rs:EnvVars`, `lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret`, `lib/foundation/fabro-static/src/secret_registry.rs:optional_vault_secrets` +- **Owns:** canonical process environment string constants; bootstrap-secret set; optional vault-secret set and classification. +- **Depends on candidates:** `[]` +- **Evidence:** + - `lib/foundation/fabro-static/Cargo.toml` — declares a no-dependency static string registry. + - `lib/foundation/fabro-static/src/env_vars.rs:EnvVars` — centralizes environment names consumed across applications, components, and foundation crates. + - `lib/foundation/fabro-static/src/secret_registry.rs` — defines secret scope independently of vault/auth implementations. + - The root `Cargo.toml` exposes the crate as a workspace dependency, and `fabro-http`, `fabro-model`, `fabro-util`, auth, telemetry, server, CLI, sandbox, Slack, and GitHub manifests consume it. + +### `fabro-telemetry` — Analytics and crash telemetry + +- **File count:** 11 +- **Purpose:** Initializes analytics/crash reporting, builds anonymous telemetry context, buffers events, and hands delivery to blocking or detached senders across CLI and server lifecycles. +- **Globs:** `lib/foundation/fabro-telemetry/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-telemetry/src/lib.rs:init_cli`, `lib/foundation/fabro-telemetry/src/lib.rs:init_server`, `lib/foundation/fabro-telemetry/src/lib.rs:track`, `lib/foundation/fabro-telemetry/src/lib.rs:shutdown`, `lib/foundation/fabro-telemetry/src/panic.rs:install_panic_hook` +- **Owns:** process-global telemetry state; anonymous CLI/server identifiers; background buffer thread and shutdown join; analytics event shape/context; command sanitization; Segment delivery and detached subprocess handoff; Sentry panic capture. +- **Depends on candidates:** `fabro-http`, `fabro-static`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-telemetry/Cargo.toml` — declares analytics and crash reporting with HTTP, Sentry, Git, and process-spawn dependencies. + - `lib/foundation/fabro-telemetry/src/lib.rs:Global` — owns the process-global sender, identity, context, level, and background thread. + - `lib/foundation/fabro-telemetry/src/buffer.rs` and `src/sender.rs` — define buffered delivery and upload boundaries. + - `lib/foundation/fabro-telemetry/src/spawn.rs` — owns the detached subprocess handoff used at process exit. + - `lib/foundation/fabro-telemetry/src/panic.rs` — owns panic-hook event construction and capture. + +### `fabro-template` — Template rendering and dependency discovery + +- **File count:** 4 +- **Purpose:** Renders MiniJinja templates with Fabro context, source-aware diagnostics, rooted include stores, caching/recording wrappers, and static dependency discovery. +- **Globs:** `lib/foundation/fabro-template/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-template/src/lib.rs:render_source`, `lib/foundation/fabro-template/src/lib.rs:render_named`, `lib/foundation/fabro-template/src/lib.rs:TemplateContext`, `lib/foundation/fabro-template/src/store.rs:TemplateStore`, `lib/foundation/fabro-template/src/dependency.rs:discover_static_dependency_closure` +- **Owns:** template context/value exposure; strict and lenient render modes; source-location error diagnostics; include/import path safety and rooted resolution; filesystem/bundle/cache/recording stores; static dependency closure. +- **Depends on candidates:** `fabro-types`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-template/Cargo.toml` — declares the shared MiniJinja rendering boundary. + - `lib/foundation/fabro-template/src/lib.rs:TemplateContext` and `TemplateError` — define the public render input and source-aware failure surface. + - `lib/foundation/fabro-template/src/store.rs:TemplateStore` and `TemplateIncludeResolver` — define source loading and root containment. + - `lib/foundation/fabro-template/src/dependency.rs` — owns include/import extraction and dependency-closure discovery. + - `lib/components/fabro-agent/Cargo.toml`, `lib/components/fabro-workflow/Cargo.toml`, and `lib/components/fabro-manifest/Cargo.toml` — out-of-scope manifests show agent, workflow, and manifest consumers. + +### `fabro-test` — Shared integration-test infrastructure + +- **File count:** 3 +- **Purpose:** Provides isolated Fabro CLI/server integration-test contexts, twin/live mode control, process and environment harnessing, snapshot normalization, and HTTP assertion helpers. +- **Globs:** `lib/foundation/fabro-test/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-test/src/lib.rs:TestContext`, `lib/foundation/fabro-test/src/lib.rs:TestMode`, `lib/foundation/fabro-test/src/lib.rs:apply_test_isolation`, `lib/foundation/fabro-test/src/lib.rs:test_http_client`, `lib/foundation/fabro-test/src/http_assert.rs:expect_reqwest_status` +- **Owns:** per-test temporary home/storage/session/server lifecycle; E2E mode and live-secret gating; subprocess environment isolation; test daemon coordination; snapshot filters; twin service setup; Axum/reqwest response assertion diagnostics. +- **Depends on candidates:** `fabro-config`, `fabro-http`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util` +- **External dependency edges:** depends on the `fabro-install`, `twin-openai`, and `twin-github` test components. +- **Evidence:** + - `lib/foundation/fabro-test/Cargo.toml` — identifies the crate as integration-test utilities and declares test-only component/twin dependencies. + - `lib/foundation/fabro-test/src/lib.rs:TestContext` — owns isolated test paths, session state, Fabro binary invocation, filters, and managed server/storage state. + - `lib/foundation/fabro-test/src/lib.rs:TestMode` and `apply_test_isolation` — define the twin/live/strict and environment-isolation contracts used by the `e2e_test` macro. + - `lib/foundation/fabro-test/src/http_assert.rs` — centralizes response consumption and diagnostic assertion behavior for both server and network tests. + - Workspace app/component manifests list `fabro-test` only in dev-dependency/test contexts. + +### `fabro-types` — Shared product contracts and state records + +- **File count:** 78 +- **Purpose:** Defines the serializable identifiers, settings records, run/session/event/state projections, and other shared product vocabulary exchanged across Fabro crates and API boundaries. +- **Globs:** `lib/foundation/fabro-types/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-types/src/lib.rs`, `lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent`, `lib/foundation/fabro-types/src/run.rs:RunSpec`, `lib/foundation/fabro-types/src/settings/mod.rs`, `lib/foundation/fabro-types/src/outcome.rs:Outcome`, `lib/foundation/fabro-types/src/status.rs:RunStatus` +- **Owns:** canonical serde shapes and IDs for runs, stages, sessions, events, transcripts, outcomes, status, projections, sandboxes, MCP servers, variables, secrets, integrations, billing, repositories, pull requests, and dense/resolved settings; feature-gated shared test fixtures. +- **Depends on candidates:** `fabro-model`, `fabro-util` +- **Evidence:** + - `lib/foundation/fabro-types/Cargo.toml` — describes shared record structs/enums and exposes only `clap` and `test-support` feature boundaries. + - `lib/foundation/fabro-types/src/lib.rs` — is a single crate facade that re-exports the canonical shared product vocabulary across its module families. + - `lib/foundation/fabro-types/src/run_event/mod.rs` and `src/run_event/*.rs` — define the event contract consumed by workflow, storage, server, client, and API code. + - `lib/foundation/fabro-types/src/settings/mod.rs` and `src/settings/*.rs` — define the resolved settings contract consumed by `fabro-config` and runtime components. + - `lib/foundation/fabro-types/tests/*.rs` — verify serde and method contracts for run specs, events, failures, sandbox models, inventory, and stage handlers. + - `lib/foundation/fabro-api/build.rs` and its round-trip tests — boundary evidence that API generation intentionally reuses these types rather than generating parallel DTOs. + +### `fabro-util` — Cross-cutting runtime and CLI utilities + +- **File count:** 24 +- **Purpose:** Provides shared environment, filesystem, shell, terminal, logging, token, error-rendering, time, backoff, warning, and workspace-glob primitives used across Fabro crates. +- **Globs:** `lib/foundation/fabro-util/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-util/src/lib.rs`, `lib/foundation/fabro-util/src/shell.rs:shell_quote`, `lib/foundation/fabro-util/src/printer.rs:Printer`, `lib/foundation/fabro-util/src/home.rs:Home`, `lib/foundation/fabro-util/src/run_log.rs:BufferedFileAppender`, `lib/foundation/fabro-util/src/workspace_glob.rs:WorkspaceGlobSet` +- **Owns:** low-level helper contracts and any helper-owned state, including the global warning set, buffered run-log guard, environment abstraction, home directory, dev/session token formats, terminal styles/printers, backoff policy, error-chain rendering, and workspace glob compilation. +- **Depends on candidates:** `fabro-static` +- **Evidence:** + - `lib/foundation/fabro-util/Cargo.toml` — identifies shared terminal/path/environment/runtime helpers and has no product-component dependencies. + - `lib/foundation/fabro-util/src/lib.rs` — exposes the helper modules directly as the public crate facade. + - `lib/foundation/fabro-util/src/shell.rs` — owns shell quoting/joining used by workflow and developer tooling. + - `lib/foundation/fabro-util/src/run_log.rs` and `src/warnings.rs` — contain the component's stateful log-guard and warning-registry lifecycles. + - `lib/foundation/fabro-util/tests/dev_token.rs` and `tests/error_chain.rs` — test stable token-file and error-rendering contracts. + +### `fabro-vault` — Secret vault and SQLite secret store + +- **File count:** 4 +- **Purpose:** Validates and stores workflow-visible secrets in file/in-memory vaults or the shared SQLite database, including revision-aware updates and one-time legacy import. +- **Globs:** `lib/foundation/fabro-vault/**` +- **Exclude globs:** `[]` +- **Entry points:** `lib/foundation/fabro-vault/src/lib.rs:Vault::load`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::open`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::apply`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::snapshot`, `lib/foundation/fabro-vault/src/store.rs:import_legacy_json_once` +- **Owns:** secret-name/type validation; redacted secret entry representation; atomic JSON vault persistence; SQL secret CRUD; secret revisions and compare-and-swap refresh updates; snapshots; legacy JSON import and backup lifecycle. +- **Depends on candidates:** `fabro-db`, `fabro-static`, `fabro-types` +- **Evidence:** + - `lib/foundation/fabro-vault/Cargo.toml` — declares the workflow-visible secret vault and its database/type dependencies. + - `lib/foundation/fabro-vault/src/lib.rs:Vault` — owns file-backed or detached in-memory entries and atomic write behavior. + - `lib/foundation/fabro-vault/src/store.rs:SecretStore` — owns the SQLite-backed secret operations and snapshots. + - `lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision` — exposes the revision boundary used for concurrent OAuth refresh write-back. + - `lib/foundation/fabro-vault/tests/store.rs` — exercises store CRUD, validation, snapshots, and legacy import at the public boundary. + +## Coverage + +| Proposed component | Tracked files | +| --- | ---: | +| `fabro-build-tooling` | 23 | +| `fabro-api` | 60 | +| `fabro-auth` | 16 | +| `fabro-client` | 9 | +| `fabro-config` | 52 | +| `fabro-core` | 13 | +| `fabro-db` | 9 | +| `fabro-http` | 2 | +| `fabro-macros-metadata` | 6 | +| `fabro-model` | 28 | +| `fabro-oauth` | 3 | +| `fabro-proc` | 8 | +| `fabro-redact` | 8 | +| `fabro-static` | 4 | +| `fabro-telemetry` | 11 | +| `fabro-template` | 4 | +| `fabro-test` | 3 | +| `fabro-types` | 78 | +| `fabro-util` | 24 | +| `fabro-vault` | 4 | +| **Total assigned** | **365** | + +- **Relevant tracked files:** 365 +- **Assigned:** 365 +- **Excluded:** 0 +- **Unmapped:** 0 +- **Overlap:** 0; every proposed glob is a whole crate directory, and the two grouped components use disjoint crate directories. +- **Tracked exclusions:** none. Build outputs such as `OUT_DIR/codegen.rs` and `OUT_DIR/rules_generated.rs` are generated but are not tracked and therefore are not part of the 365-file inventory. No vendored or generated tracked source was found in scope. +- **Unmapped files:** `[]` + +## External boundary evidence consulted + +These files are outside the scoped inventory and are neither assigned nor counted as unmapped: + +- `Cargo.toml` — workspace membership, workspace dependencies, and lint policy. +- `docs/public/api-reference/fabro-api.yaml` — source contract read by `fabro-api/build.rs`. +- `lib/apps/fabro-cli/Cargo.toml`, `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-mcp-server/Cargo.toml` — application-level reverse dependency evidence. +- Relevant `lib/components/*/Cargo.toml` manifests — reverse dependency evidence for execution, storage, schema, types, templates, auth, HTTP, process, test, and API foundations. + +## Genuine boundary questions + +1. Should `build-support` remain grouped with `fabro-dev` in the final map, or should its compile-time consumer boundary make it a separate two-file component despite the resulting assessment granularity? +2. Should `fabro-macros` and `fabro-options-metadata` remain one component? Their `OptionsMetadata` compiler/runtime contract supports grouping, while `Combine` and `e2e_test` also connect the proc-macro crate to configuration and test infrastructure. +3. Should the SQL migration files under `fabro-db/migrations/**` remain with the shared database foundation, or should reconciliation assign table-specific migrations to the variable, environment, MCP-store, automation, and run-store components that own the corresponding query behavior? The current proposal follows compile-time ownership by `fabro-db`. +4. Is `fabro-types` an acceptable single assessment component, or does the final map need stable subcomponents for settings, run/event/projection, and other contract families? This revision exposes one manifest and one broad crate facade, so this scout found no non-overlapping public boundary for such a split. diff --git a/.chisel/cartography/work/tests-evals.md b/.chisel/cartography/work/tests-evals.md new file mode 100644 index 0000000000..7b66d58250 --- /dev/null +++ b/.chisel/cartography/work/tests-evals.md @@ -0,0 +1,332 @@ +# Cartography scout report: tests and evaluations + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`) + +Scope: all 180 tracked files under `test/**` and `evals/**`. Cargo workspace +manifests, test consumers, repository documentation sources, and implementation +entry points were consulted only as boundary evidence and are not included in +this scope's counts. + +Applicable instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and +`docs/internal/testing-strategy.md` (`CLAUDE.md` is a symlink to `AGENTS.md`). + +## Boundary decisions + +- `twin-openai` and `twin-github` are separate components. Each is a distinct + Cargo workspace member with its own protocol surface, router, state model, + lifecycle, fixtures, and consumers. Their common use as local fake services + is not enough to combine OpenAI scenario/stream behavior with GitHub + repository/authentication behavior. +- The checked-in workflow fixtures outside `test/docs/**` are proposed as a + shared `workflow-test-corpus` component. They are all user-facing workflow, + configuration, prompt, and template inputs, and they are intentionally + consumed across CLI, workflow, graph-language, rendering, and validation + tests. Keeping them together avoids assigning shared compatibility data to + one arbitrary production consumer. +- `test/docs/**` is proposed as a separate + `documentation-workflow-tests` component. It has its own extraction and + multi-phase runner entry points and owns a documentation-derived but curated + executable corpus. The tracked fixtures are test source: the checklist + records extracted, assembled, and adapted cases, and `run_tests.sh` executes + them directly. They are therefore assigned rather than excluded as generated + output. +- The SWE-bench tooling is a distinct evaluation component. It owns a + generation, grading, monitoring, environment-generation, and result-recording + workflow that is independent of the normal Cargo test lifecycle. +- `evals/swe-bench/scoreboard/**` is not executable evaluation source. The + evaluation README calls it a Git-tracked permanent record, and + `record_results.py` writes every tracked file shape beneath it. Those 16 + recorded outputs are proposed as a global exclusion. +- The two distribution shell tests and the benchmark-analysis SQL do not form a + coherent component together. They are recommended additions to existing + components, described after the component proposals. + +## Proposed components + +### `twin-openai` — OpenAI protocol twin + +- **File count:** 35 (28 Rust, 5 Markdown, 1 Cargo manifest, 1 `.gitignore`) +- **Purpose:** Provides a deterministic OpenAI-compatible HTTP service for + black-box and protocol-contract tests, including scripted successes, + failures, streaming, request inspection, and live shape comparison. +- **Globs:** `test/twin/openai/**` +- **Exclude globs:** `[]` +- **Entry points:** `test/twin/openai/src/main.rs:main`, + `test/twin/openai/src/lib.rs:build_app`, + `test/twin/openai/src/lib.rs:build_app_with_config`, + `test/twin/openai/src/app.rs:router` +- **Owns:** server bind/configuration lifecycle; `/v1/responses` and + `/v1/chat/completions` request/response contracts; bearer-token namespaces; + FIFO scenario queues; deterministic response IDs; normalized request logs; + SSE construction and transport-failure behavior; admin reset/scenario APIs; + debug UI and snapshots; local and opt-in live contract suites. +- **Depends on candidates:** `fabro-http`, `fabro-static` +- **Evidence:** + - `Cargo.toml` — lists `test/twin/openai` as a workspace member and exposes + `twin-openai` as a workspace dependency. + - `test/twin/openai/Cargo.toml` — declares a non-published library/binary + package described as a fake OpenAI-compatible server. + - `test/twin/openai/src/app.rs:router` and + `test/twin/openai/src/openai/mod.rs:router` — compose the health, OpenAI, + admin, and debug HTTP surfaces. + - `test/twin/openai/src/state.rs:AppState` — owns namespaced response + counters, scenario queues, and request logs. + - `test/twin/openai/src/engine/scenario.rs:ScenarioScript` — defines scripted + success, application-error, delay, partial/malformed stream, and hang + behavior. + - `test/twin/openai/tests/common/mod.rs:spawn_server` and the eight sibling + contract suites — exercise the service as a protocol boundary; the ignored + `live_openai_contract.rs` compares supported protocol shapes with the live + API. + - `lib/foundation/fabro-test/Cargo.toml` and + `lib/foundation/fabro-test/src/lib.rs:twin_openai` — show the shared + integration-test harness consuming this package as an in-process service. + +### `twin-github` — GitHub protocol twin + +- **File count:** 20 (17 Rust, 2 PEM fixtures, 1 Cargo manifest) +- **Purpose:** Provides an in-process fake GitHub service with seeded mutable + state and temporary Git repositories for black-box GitHub App, OAuth, API, + GraphQL, and smart-HTTP tests. +- **Globs:** `test/twin/github/**` +- **Exclude globs:** `[]` +- **Entry points:** `test/twin/github/src/server.rs:TestServer::start`, + `test/twin/github/src/server.rs:build_router`, + `test/twin/github/src/state.rs:AppState`, + `test/twin/github/src/fixtures.rs:FixtureState::into_app_state` +- **Owns:** ephemeral listener and shutdown lifecycle; temporary bare Git + repositories; fake apps, installations, repositories, branches, pull + requests, releases, projects, comments, webhook configuration, manifest + conversions, access tokens, OAuth codes/tokens/users; GitHub authentication + checks; bundled test RSA key pair. +- **Depends on candidates:** `fabro-http` +- **Evidence:** + - `Cargo.toml` — lists `test/twin/github` independently as a workspace member + and workspace dependency. + - `test/twin/github/Cargo.toml` — declares a non-published library package + described as a fake GitHub API server. + - `test/twin/github/src/handlers/mod.rs:build_router` — registers the GitHub + App, installation, branch, pull-request, manifest, OAuth, user, release, + GraphQL, and Git smart-HTTP routes. + - `test/twin/github/src/state.rs:AppState` — owns the central seeded and + mutable GitHub-domain state. + - `test/twin/github/src/server.rs:TestServer::start` — initializes temporary + Git repositories, binds an ephemeral listener, and controls graceful + shutdown. + - `test/twin/github/src/fixtures.rs:FixtureState` and + `test/twin/github/src/testdata/*.pem` — define reusable seeded service data + and the owned authentication fixtures. + - `lib/foundation/fabro-test/src/lib.rs:TwinGitHub` and + `lib/apps/fabro-cli/tests/it/support/auth_harness.rs` — show this twin + serving the CLI/server authentication integration boundary. + +### `workflow-test-corpus` — Shared workflow compatibility fixtures + +- **File count:** 42 + - 8 root `test/*.fabro` workflows + - 14 `test/attractor/*.dot` compatibility graphs + - 3 `test/dot-compatibility/*.fabro` graphs + - 17 templating/configuration files under the four templated fixture trees +- **Purpose:** Supplies reusable user-facing workflow, compatibility, + configuration, prompt, partial, and template inputs to cross-crate parser, + validator, renderer, workflow, and CLI tests. +- **Globs:** `test/*.fabro`, `test/attractor/**`, + `test/dot-compatibility/**`, `test/templated_inputs/**`, + `test/templated_unbound_imported/**`, + `test/templated_unbound_partial/**`, `test/templates/**` +- **Exclude globs:** `[]` +- **Entry points:** `test/simple.fabro`, + `test/attractor/simple_example.dot`, + `test/dot-compatibility/acp-agent-chain.fabro`, + `test/templates/static_dependencies/workflow.fabro`, + `test/templates/sibling_partial/workflow.fabro` +- **Owns:** representative valid and invalid workflow shapes; branching, + conditions, parallelism, styles, and legacy syntax cases; Attractor DOT + compatibility graphs; shared DOT parse/render/validation cases; template + input, import, include, sibling-partial, static-dependency, and + missing-dependency fixture trees. +- **Depends on candidates:** `fabro-cli`, `fabro-graphviz`, `fabro-template`, + `fabro-test`, `fabro-validate`, `fabro-workflow` +- **Evidence:** + - `docs/internal/testing-strategy.md` — explicitly recognizes checked-in + user-facing workflows, configs, prompts, and repository contents as shared + fixtures. + - `lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture` — + resolves named inputs from the repository `test/` directory for isolated + CLI tests. + - `lib/apps/fabro-cli/tests/it/cmd/validate.rs` and + `lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs` — consume the + root workflows and all templating fixture trees as black-box CLI inputs. + - `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — enumerates + and parses every graph in `test/attractor/**`. + - `lib/components/fabro-graphviz/src/render.rs:dot_compatibility_fixtures` + and + `lib/components/fabro-validate/src/lib.rs:dot_compatibility_fixtures` — + independently enumerate the same three `test/dot-compatibility/**` inputs, + establishing that corpus as shared rather than crate-local. + +### `documentation-workflow-tests` — Documentation workflow conformance + +- **File count:** 55 (40 Fabro workflows, 7 shell files, 5 Markdown files, 2 + run TOML files, 1 Python extractor) +- **Purpose:** Extracts, curates, validates, preflights, and executes workflow + examples and companion files derived from Fabro documentation. +- **Globs:** `test/docs/**` +- **Exclude globs:** `[]` +- **Entry points:** `test/docs/run_tests.sh`, + `test/docs/extract_dots.py:main`, `test/docs/CHECKLIST.md` +- **Owns:** documentation-example corpus layout; prompt and script stubs; + variable-bearing run configurations; extraction naming and stub generation; + validate/preflight/dry-run/live phase selection; parallel execution and + temporary result/run directories; the documented corpus checklist. +- **Depends on candidates:** `fabro-cli`, `fabro-workflow`, the final + documentation-site component +- **Evidence:** + - `test/docs/run_tests.sh:run_one` — discovers all 40 tracked `*.fabro` + examples and invokes the built `fabro` binary in validate, preflight, + dry-run, model-specific, or full execution modes. + - `test/docs/extract_dots.py:main` — reads documentation Markdown, extracts + complete DOT graphs, and creates companion prompt stubs and run + configurations under `test/docs`. + - `test/docs/CHECKLIST.md` — documents the 40-example corpus, distinguishes + extracted and assembled cases, records companion-file needs, and provides + the runner commands. + - `.claude/skills/docs/SKILL.md` — instructs documentation changes containing + full DOT graphs to run `./test/docs/run_tests.sh validate`, tying this + harness to the documentation change lifecycle. + +### `swe-bench-evaluation` — SWE-bench evaluation workflow + +- **File count:** 9 (6 Python scripts, 1 Fabro workflow, 1 requirements file, 1 + README) +- **Purpose:** Generates Fabro patches for SWE-bench Lite instances, grades + them through Daytona or the official harness, monitors runs, and records + normalized result summaries. +- **Globs:** `evals/swe-bench/*.py`, `evals/swe-bench/*.fabro`, + `evals/swe-bench/*.txt`, `evals/swe-bench/README.md` +- **Exclude globs:** `[]` (the sibling scoreboard is a global exclusion) +- **Entry points:** `evals/swe-bench/run_eval.py:main`, + `evals/swe-bench/evaluate_daytona.py:main`, + `evals/swe-bench/evaluate.py:main`, + `evals/swe-bench/record_results.py:main`, + `evals/swe-bench/status.py:main`, + `evals/swe-bench/gen_dockerfile.py:main` +- **Owns:** SWE-bench Lite dataset selection; per-instance goal/workflow/TOML + generation; Daytona snapshot and sandbox specifications; Fabro subprocess + orchestration and timeout cleanup; patch extraction; official and + Daytona-based grading; progress summaries; scoreboard record schema and + leaderboard regeneration. +- **Depends on candidates:** `fabro-cli`, `fabro-sandbox`, + `fabro-workflow` +- **External dependencies:** Hugging Face `datasets`, the `swebench` harness, + Daytona, and optionally Docker through the official harness. +- **Evidence:** + - `evals/swe-bench/README.md` — defines the three-stage generate, evaluate, + and record lifecycle, the two grading backends, and raw-versus-recorded + result locations. + - `evals/swe-bench/run_eval.py:run_instance` — creates per-instance Fabro + workflows/configs, invokes `fabro run`, and extracts produced patches. + - `evals/swe-bench/evaluate_daytona.py` — creates grading workflows and + executes held-out tests in Daytona snapshots. + - `evals/swe-bench/evaluate.py:main` — exposes the alternative official + Docker-backed `swebench.harness.run_evaluation` path. + - `evals/swe-bench/gen_dockerfile.py:generate_dockerfile` — translates + SWE-bench repository/version specs into reusable sandbox images. + - `evals/swe-bench/record_results.py:main` and + `regenerate_leaderboard` — define and write the tracked scoreboard record + formats. + +## Recommended additions to existing components + +These files are assigned in the coverage accounting but do not justify new +components: + +| File | Recommended component | Reason | +| --- | --- | --- | +| `test/bin/install_test.sh` | documentation/web scout's marketing-site component | It is a black-box shell contract test whose sole product target is `apps/marketing/public/install.sh`; it owns a fake `gh` executable and temporary install home only for that test. | +| `test/bin/release_test.sh` | `fabro-build-tooling` | It is an executable release-mode shell contract and changes with the repository release-automation lifecycle. | +| `test/analysis/bench-tests-diff.sql` | `fabro-build-tooling` | Its documented inputs are the two CSVs produced by `cargo dev bench-tests`, whose implementation is `lib/foundation/fabro-dev/src/commands/bench_tests.rs`. | + +## Global exclusion + +### Recorded SWE-bench scoreboards + +- **Globs:** `evals/swe-bench/scoreboard/**` +- **Tracked files:** 16 (1 leaderboard JSON plus 5 run directories containing + one `README.md`, one `meta.json`, and one `instances.jsonl` each) +- **Reason:** committed evaluation records generated by + `evals/swe-bench/record_results.py`, not executable evaluation source. +- **Evidence:** `evals/swe-bench/README.md` calls the directory a Git-tracked + permanent record; `record_results.py` writes `instances.jsonl`, `meta.json`, + each run `README.md`, and regenerates `leaderboard.json`. + +Raw `evals/swe-bench/results/**` data is also described as generated output, +but it is not tracked at the assessed revision and therefore is not part of +the 180-file inventory. + +No `test/docs/**` files are excluded. Although the extractor derives some +files from documentation, the tracked corpus includes assembled/adapted +executable fixtures and companion stubs/configuration, and the runner consumes +those files as test inputs. + +## Coverage + +| Assignment | Tracked files | +| --- | ---: | +| `twin-openai` | 35 | +| `twin-github` | 20 | +| `workflow-test-corpus` | 42 | +| `documentation-workflow-tests` | 55 | +| `swe-bench-evaluation` | 9 | +| Recommended addition to marketing-site component | 1 | +| Recommended additions to `fabro-build-tooling` | 2 | +| Global exclusion: SWE-bench scoreboards | 16 | +| **Scoped inventory** | **180** | + +- **Assigned:** 164 (161 in proposed test/evaluation components and 3 additions + to existing components) +- **Excluded:** 16 +- **Unmapped:** 0 +- **Overlap:** 0 +- **Accounting check:** `164 + 16 + 0 = 180` +- **Unmapped files:** `[]` + +## External boundary evidence consulted + +These files are outside the scoped inventory and are neither assigned nor +counted as unmapped: + +- `Cargo.toml` — workspace membership and workspace dependency declarations for + both twin services. +- `lib/foundation/fabro-test/Cargo.toml` and + `lib/foundation/fabro-test/src/lib.rs` — shared fixture installation and twin + service consumption. +- `lib/apps/fabro-cli/tests/it/**` — black-box workflow fixture and twin-GitHub + consumers. +- `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — Attractor + corpus consumer. +- `lib/components/fabro-graphviz/src/render.rs` and + `lib/components/fabro-validate/src/lib.rs` — shared DOT compatibility corpus + consumers. +- `docs/internal/testing-strategy.md` — repository test-layer and fixture + ownership policy. +- `.claude/skills/docs/SKILL.md` — documentation test-runner invocation policy. +- `apps/marketing/public/install.sh` — install shell-test target. +- `lib/foundation/fabro-dev/src/commands/bench_tests.rs` — benchmark CSV + producer consumed by the analysis SQL. + +## Genuine boundary questions + +1. Should `workflow-test-corpus` remain a distinct 42-file shared data + component, as proposed, or should reconciliation distribute its three + subcorpora to `fabro-cli` (25 general/template fixtures), + `fabro-workflow` (14 Attractor fixtures), and `fabro-graphviz` (3 shared DOT + compatibility fixtures)? The cross-crate consumers support a shared + boundary, while the production behaviors they exercise support attachment. +2. Should `documentation-workflow-tests` remain a separate executable harness, + or should its 55 files be included in the documentation-site component? + Its runner and phase lifecycle support separation; its source derivation and + documentation-change trigger support inclusion with documentation. +3. Should `test/bin/release_test.sh` be assigned to `fabro-build-tooling` as a + release-lifecycle contract, or remain separately unmapped until the final + map determines which current release entry point owns that shell contract? diff --git a/.chisel/cartography/work/validate-render.mjs b/.chisel/cartography/work/validate-render.mjs new file mode 100644 index 0000000000..33f1e4174c --- /dev/null +++ b/.chisel/cartography/work/validate-render.mjs @@ -0,0 +1,271 @@ +import { execFileSync } from "node:child_process"; +import { readFileSync, writeFileSync } from "node:fs"; + +function fail(message) { + throw new Error(message); +} + +function globRegex(glob) { + let source = "^"; + for (let index = 0; index < glob.length; index += 1) { + const character = glob[index]; + if (character === "*") { + if (glob[index + 1] === "*") { + source += ".*"; + index += 1; + } else { + source += "[^/]*"; + } + } else if (character === "?") { + source += "[^/]"; + } else { + source += character.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&"); + } + } + return new RegExp(`${source}$`); +} + +function matchesAny(path, globs) { + return globs.some((glob) => globRegex(glob).test(path)); +} + +function requireKeys(value, expected, label) { + const actual = Object.keys(value).sort(); + const wanted = [...expected].sort(); + if (JSON.stringify(actual) !== JSON.stringify(wanted)) { + fail( + `${label} keys differ\nexpected ${JSON.stringify(wanted)}\nfound ${JSON.stringify(actual)}`, + ); + } +} + +function referencedPath(reference) { + return reference.split(" — ", 1)[0].split(":", 1)[0]; +} + +function validate(map) { + requireKeys( + map, + [ + "schema_version", + "cartography_version", + "created_at", + "repository", + "instructions", + "overview", + "global_exclusions", + "components", + "unmapped_files", + "coverage", + "open_questions", + ], + "map", + ); + requireKeys( + map.repository, + ["name", "root", "revision", "short_revision"], + "repository", + ); + requireKeys( + map.coverage, + [ + "relevant_file_count", + "assigned_file_count", + "excluded_file_count", + "unmapped_file_count", + ], + "coverage", + ); + if (map.schema_version !== 1) fail("schema_version must be 1"); + if (map.cartography_version !== 1) fail("cartography_version must be 1"); + + const files = execFileSync( + "git", + ["ls-tree", "-r", "--name-only", map.repository.revision], + { encoding: "utf8" }, + ) + .trim() + .split("\n") + .filter(Boolean); + const fileSet = new Set(files); + const ids = map.components.map(({ id }) => id); + if (new Set(ids).size !== ids.length) fail("component IDs are not unique"); + for (const id of ids) { + if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) { + fail(`invalid component ID: ${id}`); + } + } + + const allGlobs = []; + for (const exclusion of map.global_exclusions) { + requireKeys(exclusion, ["globs", "reason"], "global exclusion"); + allGlobs.push(...exclusion.globs); + } + for (const component of map.components) { + requireKeys( + component, + [ + "id", + "name", + "purpose", + "globs", + "exclude_globs", + "entry_points", + "owns", + "depends_on", + "evidence", + ], + `component ${component.id}`, + ); + allGlobs.push(...component.globs, ...component.exclude_globs); + for (const dependency of component.depends_on) { + if (!ids.includes(dependency)) { + fail(`${component.id} depends on missing component ${dependency}`); + } + if (dependency === component.id) { + fail(`${component.id} depends on itself`); + } + } + for (const reference of [...component.entry_points, ...component.evidence]) { + const path = referencedPath(reference); + if (!fileSet.has(path)) { + fail(`${component.id} references missing path ${path}`); + } + } + } + for (const instruction of map.instructions) { + if (!fileSet.has(instruction)) fail(`missing instruction ${instruction}`); + } + for (const glob of allGlobs) { + if (!files.some((path) => globRegex(glob).test(path))) { + fail(`glob resolves to no tracked files: ${glob}`); + } + } + + const excluded = new Set( + files.filter((path) => + map.global_exclusions.some(({ globs }) => matchesAny(path, globs)), + ), + ); + const claims = new Map(); + for (const component of map.components) { + for (const path of files) { + if ( + matchesAny(path, component.globs) && + !matchesAny(path, component.exclude_globs) + ) { + if (excluded.has(path)) { + fail(`${path} is both globally excluded and claimed by ${component.id}`); + } + const previous = claims.get(path); + if (previous) { + fail(`${path} is claimed by both ${previous} and ${component.id}`); + } + claims.set(path, component.id); + } + } + } + + for (const path of map.unmapped_files) { + if (!fileSet.has(path)) fail(`unmapped file does not exist: ${path}`); + if (excluded.has(path) || claims.has(path)) { + fail(`unmapped file also has another disposition: ${path}`); + } + } + const unmapped = new Set(map.unmapped_files); + const missing = files.filter( + (path) => !claims.has(path) && !excluded.has(path) && !unmapped.has(path), + ); + if (missing.length > 0) { + fail(`files lack a disposition:\n${missing.join("\n")}`); + } + + const computed = { + relevant_file_count: files.length, + assigned_file_count: claims.size, + excluded_file_count: excluded.size, + unmapped_file_count: unmapped.size, + }; + if (JSON.stringify(computed) !== JSON.stringify(map.coverage)) { + fail( + `coverage mismatch\nexpected ${JSON.stringify(computed)}\nfound ${JSON.stringify(map.coverage)}`, + ); + } + if ( + computed.assigned_file_count + + computed.excluded_file_count + + computed.unmapped_file_count !== + computed.relevant_file_count + ) { + fail("coverage counts do not add up"); + } + return computed; +} + +function inline(values) { + return values.map((value) => `\`${value}\``).join(", "); +} + +function render(map) { + const lines = [ + "# Chisel Codebase Map", + "", + `Cartography v${map.cartography_version} · revision \`${map.repository.revision}\` · ${map.created_at}`, + `Assigned ${map.coverage.assigned_file_count} files · excluded ${map.coverage.excluded_file_count} · unmapped ${map.coverage.unmapped_file_count} · instructions: ${map.instructions.join(", ")}`, + "", + map.overview, + "", + "## Components", + ]; + + for (const component of map.components) { + lines.push( + "", + `### \`${component.id}\` — ${component.name}`, + "", + `- **Purpose:** ${component.purpose}`, + `- **Paths:** ${inline(component.globs)}`, + ); + if (component.exclude_globs.length > 0) { + lines.push(`- **Excludes:** ${inline(component.exclude_globs)}`); + } + if (component.entry_points.length > 0) { + lines.push(`- **Entry points:** ${inline(component.entry_points)}`); + } + if (component.owns.length > 0) { + lines.push(`- **Owns:** ${component.owns.join("; ")}`); + } + if (component.depends_on.length > 0) { + lines.push(`- **Depends on:** ${inline(component.depends_on)}`); + } + if (component.evidence.length > 0) { + lines.push(`- **Evidence:** ${component.evidence.join("; ")}`); + } + } + + if (map.global_exclusions.length > 0 || map.unmapped_files.length > 0) { + lines.push("", "## Exclusions and Unmapped Code", ""); + for (const exclusion of map.global_exclusions) { + lines.push(`- ${inline(exclusion.globs)} — ${exclusion.reason}`); + } + for (const path of map.unmapped_files) { + lines.push(`- \`${path}\` — unmapped`); + } + } + + if (map.open_questions.length > 0) { + lines.push("", "## Open Questions", ""); + for (const question of map.open_questions) { + lines.push(`- ${question}`); + } + } + lines.push(""); + return lines.join("\n"); +} + +const [inputPath, outputPath] = process.argv.slice(2); +if (!inputPath) fail("usage: validate-render.mjs [map.md]"); +const map = JSON.parse(readFileSync(inputPath, "utf8")); +const coverage = validate(map); +if (outputPath) writeFileSync(outputPath, render(map)); +process.stdout.write(`${JSON.stringify(coverage)}\n`); diff --git a/.chisel/cartography/work/web.md b/.chisel/cartography/work/web.md new file mode 100644 index 0000000000..0441611e4e --- /dev/null +++ b/.chisel/cartography/work/web.md @@ -0,0 +1,305 @@ +# JavaScript/TypeScript cartography proposal + +Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` + +Owned scout scope: every tracked file under `apps/**` and +`lib/packages/**` at the assessed revision. `package.json`, `bun.lock`, and +`docs/public/api-reference/fabro-api.yaml` were consulted only as dependency +evidence and are not included in the scope counts. Applicable repository +instructions are `AGENTS.md` (the `CLAUDE.md` project instructions) and +`CONTRIBUTING.md`. + +## Boundary decisions + +- `apps/fabro-web` contains three coherent assessable responsibilities, not + just one directory-shaped component: + - the normal-mode React application, shared browser runtime, and bundle + production; + - the alternate first-run installation mode, with its own route graph, + reducer/form lifecycle, session token, API facade, and focused tests; + - the workflow playground subtree, which explicitly defines a standalone + prop boundary and owns a browser-persisted workflow draft, graph + simulation, chat adapter, and generated project files. +- The marketing site and Remotion project are separate applications. Each has + its own package manifest, framework entry point, build command, assets, and + output/deployment lifecycle. +- The hand-written Fabro API client generation package is an assessable + component, but its checked-in `src/**` tree is generator output and should + be excluded from assessment. The distinction and counts are documented + below. + +## Proposed components + +### `fabro-web-app` — Fabro browser application + +- **Purpose:** Build and run the normal-mode React SPA for run operations, + chats, automations, insights, settings, profiles, and their shared browser + infrastructure. +- **Tracked files:** 309. +- **Globs:** `apps/fabro-web/**` +- **Exclude globs (assigned to sibling components):** + `apps/fabro-web/app/components/playground/**`, + `apps/fabro-web/app/install-*`, + `apps/fabro-web/app/mode.ts`, + `apps/fabro-web/app/mode.test.ts`, + `apps/fabro-web/app/hooks/use-install-effects.ts` +- **Entry points:** `apps/fabro-web/scripts/build.ts:main`, + `apps/fabro-web/app/entry.tsx`, + `apps/fabro-web/app/router.tsx:routes`, + `apps/fabro-web/index.template.html` +- **Owns:** Browser bundle assembly and content-hashed publication under + `dist/`; the normal-mode route graph; run, chat, automation, insight, + settings, and profile UX; shared API/query/mutation/event-stream adapters; + app-wide layouts, components, hooks, browser view preferences, and public + UI assets. +- **Depends-on candidates:** `fabro-web-install` (alternate route graph + composed by the browser entry), `fabro-workflow-playground` (route-level + feature composition), `fabro-api-client-generation` (through its generated + package output), and the parent map's server HTTP/API-contract component + (likely `fabro-server` and/or `fabro-api`). +- **Evidence:** + - `apps/fabro-web/package.json` — declares a private React application, + custom build/dev commands, browser dependencies, tests, and a workspace + dependency on `@qltysh/fabro-api-client`. + - `apps/fabro-web/scripts/build.ts:main` — bundles + `app/entry.tsx`, compiles Tailwind CSS, copies public/worker assets, writes + the HTML shell, publishes a content-addressed build, and provides the + watch lifecycle. + - `apps/fabro-web/app/entry.tsx` — creates the React root, browser router, + SWR runtime, build-version guard, and toaster, then selects the normal or + install route graph. + - `apps/fabro-web/app/router.tsx:routes` — explicitly composes the + normal-mode route tree for chats, playground, automations, runs, insights, + settings, and profile pages beneath the app shell. + - `apps/fabro-web/app/lib/api-client.ts` and + `apps/fabro-web/app/lib/queries.ts` — form the browser-side API and query + integration boundary used across normal-mode routes. + +### `fabro-web-install` — First-run browser installer + +- **Purpose:** Drive the browser-only first-run installation workflow that + configures server URL, object storage, sandbox, LLM providers, and GitHub + before finishing installation. +- **Tracked files:** 14. +- **Globs:** `apps/fabro-web/app/install-*`, + `apps/fabro-web/app/mode.ts`, + `apps/fabro-web/app/mode.test.ts`, + `apps/fabro-web/app/hooks/use-install-effects.ts` +- **Exclude globs:** none. +- **Entry points:** `apps/fabro-web/app/install-router.tsx:installRoutes`, + `apps/fabro-web/app/install-app.tsx:InstallApp`, + `apps/fabro-web/app/mode.ts:resolveFabroMode` +- **Owns:** The `install` browser mode; installation step navigation and form + reducer state; install-session query lifecycle; the + `fabro-install-token` session-storage value; URL token/GitHub callback + consumption; install-specific validation, persistence, finish, and restart + health-poll behavior. +- **Depends-on candidates:** `fabro-web-app` for the shared root, common UI, + hooks, and browser API transport; `fabro-api-client-generation` through + generated Install DTOs/API methods; and the parent map's server + installation/API-contract component. +- **Evidence:** + - `apps/fabro-web/app/entry.tsx` — selects `installRoutes` instead of the + normal `routes` when `window.__FABRO_MODE__` resolves to `install`. + - `apps/fabro-web/app/install-router.tsx:installRoutes` — defines a separate + catch-all route graph centered on `InstallApp`. + - `apps/fabro-web/app/install-app.tsx` — owns the seven-step install flow + and its installation-specific reducer/form state. + - `apps/fabro-web/app/install-api.ts` — wraps generated Install API methods + and owns the session-storage token contract. + - `docs/public/api-reference/fabro-api.yaml` — dependency evidence outside + owned scope: declares the `Install` tag as the first-run browser install + workflow. + +### `fabro-workflow-playground` — Browser workflow playground + +- **Purpose:** Provide a self-contained workflow drafting, simulation, chat, + visualization, file-generation, download, and run-launch surface. +- **Tracked files:** 44. +- **Globs:** `apps/fabro-web/app/components/playground/**` +- **Exclude globs:** none. +- **Entry points:** + `apps/fabro-web/app/components/playground/playground.tsx:Playground` +- **Owns:** The `WorkflowDraft` graph schema and reducer; the versioned + `fabro:playground:draft:v1` local-storage document; draft validation and + animation; workflow simulation state; canvas rendering; playground chat/SSE + adaptation; `workflow.fabro`, TOML, and README rendering; download and + real-run launch controls. +- **Depends-on candidates:** `fabro-web-app` for a small set of shared chat, + graph-theme, dynamic-import, event-hook, and test utilities; and the parent + map's server component for `/api/v1/playground/chat` and `/api/v1/runs`. +- **Evidence:** + - `apps/fabro-web/app/components/playground/playground.tsx:Playground` — + exposes `chatEndpoint`, `authMode`, and optional redirect props and states + that the subtree is framed for re-embedding without the app shell or + app-wide stores. + - `apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft` — + defines the complete workflow document and describes it as a + self-contained, re-embeddable island. + - `apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft` + — owns reducer-driven browser persistence and the versioned storage key. + - `apps/fabro-web/app/components/playground/chat/runtime.ts:createPlaygroundAdapter` + — adapts chat turns and streamed tool calls into draft changes. + - `apps/fabro-web/app/routes/playground.tsx:PlaygroundRoute` — integration + evidence in the sibling app component: mounts the feature at + `/playground` and supplies its endpoint/auth contract. + +### `fabro-marketing-site` — Fabro marketing site + +- **Purpose:** Build and deploy the public Fabro site, including product + landing content, blog, roadmap, showcase, install resources, and social + metadata/assets. +- **Tracked files:** 51 assigned; two generated Vercel link files excluded + below. +- **Globs:** `apps/marketing/**` +- **Exclude globs:** `apps/marketing/.vercel/**` +- **Entry points:** `apps/marketing/astro.config.mjs`, + `apps/marketing/src/pages/index.astro`, + `apps/marketing/src/content.config.ts` +- **Owns:** Astro page routing and layout; global marketing presentation; + blog, roadmap, and showcase content collections; workflow showcase + rendering; public install script/instructions and brand/social assets; + public redirects and Vercel deployment configuration. +- **Depends-on candidates:** none within this scout's assessable components. + It has framework dependencies and renders workflow graphs via Viz.js but + does not import another repository workspace. +- **Evidence:** + - `apps/marketing/package.json` — declares an independent private Astro + application with dev/build/preview lifecycle. + - `apps/marketing/astro.config.mjs` — integrates React/Tailwind and defines + public redirects. + - `apps/marketing/src/content.config.ts` — defines separately typed roadmap, + blog, and showcase content collections whose source documents are owned + under `src/content/**`. + - `apps/marketing/src/pages/**` — Astro's file-based entries own the landing, + roadmap, blog, and showcase URL surfaces. + - `apps/marketing/vercel.json` — owns production redirect behavior for the + deployed site. + +### `fabro-remotion-video` — Fabro Remotion composition + +- **Purpose:** Render the branded `FabroIntro` motion-graphics video. +- **Tracked files:** 9. +- **Globs:** `apps/remotion/**` +- **Exclude globs:** none. +- **Entry points:** `apps/remotion/src/index.ts`, + `apps/remotion/src/Root.tsx:RemotionRoot`, + `apps/remotion/src/FabroIntro.tsx:FabroIntro` +- **Owns:** The `FabroIntro` composition registration, 1920x1080/30fps/150 + frame timeline, image-format configuration, logo animation, brand assets, + and `out/intro.mp4` render lifecycle. +- **Depends-on candidates:** none within this scout's assessable components. +- **Evidence:** + - `apps/remotion/package.json` — declares an independent Remotion project + whose studio and render/build scripts target composition `FabroIntro`. + - `apps/remotion/src/index.ts` — registers the Remotion root. + - `apps/remotion/src/Root.tsx:RemotionRoot` — declares the composition ID, + component, dimensions, frame rate, and duration. + - `apps/remotion/src/FabroIntro.tsx:FabroIntro` — owns the composition's + animation timeline and use of the two local public assets. + +### `fabro-api-client-generation` — TypeScript API client generation contract + +- **Purpose:** Configure, normalize, and type-check the generated + TypeScript/Axios client for the Fabro OpenAPI contract. +- **Tracked files:** 6 assigned; 554 generated/output files excluded below. +- **Globs:** `lib/packages/fabro-api-client/package.json`, + `lib/packages/fabro-api-client/openapitools.json`, + `lib/packages/fabro-api-client/scripts/**`, + `lib/packages/fabro-api-client/tests/**`, + `lib/packages/fabro-api-client/tsconfig.json` +- **Exclude globs:** `lib/packages/fabro-api-client/src/**` +- **Entry points:** + `lib/packages/fabro-api-client/package.json:scripts.generate`, + `lib/packages/fabro-api-client/scripts/normalize-generated.ts` +- **Owns:** OpenAPI Generator CLI/template options and version selection; + output location; deterministic whitespace normalization; strict TypeScript + compilation of output; hand-written exhaustiveness/invariant checks for + generated discriminated unions and API shapes. +- **Depends-on candidates:** the parent map's `fabro-api`/OpenAPI-contract + component, whose source is + `docs/public/api-reference/fabro-api.yaml`. +- **Evidence:** + - `lib/packages/fabro-api-client/package.json` — `generate` invokes pinned + OpenAPI Generator CLI `2.20.2`, reads the repository OpenAPI YAML, selects + `typescript-axios` with separate model/API packages and tag-based APIs, + writes to `src`, then runs the normalizer. + - `lib/packages/fabro-api-client/openapitools.json` — selects generator + version `7.20.0`. + - `lib/packages/fabro-api-client/scripts/normalize-generated.ts` — is + explicitly hand-written normalization logic and scans exactly + `src/**/*.ts`. + - `lib/packages/fabro-api-client/tests/principal-exhaustive.ts` and + `tests/reasoning-output-invariant.ts` — hand-written compile-time + assertions over generated types. + - `lib/packages/fabro-api-client/tsconfig.json` — type-checks both + `src/**/*` and `tests/**/*`. + +## Evidence-backed exclusions + +### Generated TypeScript/Axios client output + +- **Glob:** `lib/packages/fabro-api-client/src/**` +- **Count:** 554 tracked files: 551 TypeScript files and three generator + bookkeeping/ignore files + (`.openapi-generator/FILES`, `.openapi-generator/VERSION`, and + `.openapi-generator-ignore`). +- **Reason/evidence:** + - The hand-written package script directs OpenAPI Generator to `-o src`. + - 550 of the 551 TypeScript files carry the literal header + `NOTE: This class is auto generated by OpenAPI Generator` and + `Do not edit the class manually`. + - The only TypeScript file without that header is + `src/models/index.ts`; it is explicitly named in + `src/.openapi-generator/FILES`. + - `src/.openapi-generator/FILES` contains 545 generated path entries and + `src/.openapi-generator/VERSION` records `7.20.0`. + - Six additional TypeScript files are not in that `FILES` snapshot, but + each has the same auto-generation marker: + `models/daytona-network-layer-one-of-allow-list.ts`, + `models/daytona-network-layer-one-of.ts`, + `models/daytona-network-layer.ts`, `models/docker-settings.ts`, + `models/run-projection-checkpoints-inner-inner.ts`, and + `models/sandbox-provider.ts`. + - Therefore the stable exclusion is the output-root glob `src/**`, not only + the metadata's current list or only marker-bearing files. + +### Vercel CLI link metadata + +- **Glob:** `apps/marketing/.vercel/**` +- **Count:** 2 tracked files. +- **Reason/evidence:** `apps/marketing/.vercel/README.txt` states that the + folder is automatically created when linking a directory to a Vercel + project, describes `project.json` as the linked project/team IDs, and says + the directory should not be committed/shared. These are generated local + deployment-link records rather than marketing-site source. + +## Computed coverage + +| Category | Count | +| --- | ---: | +| Tracked files in owned scope | 989 | +| Assigned to proposed components | 433 | +| Evidence-backed excluded | 556 | +| Unmapped | 0 | + +Assigned counts are `309 + 14 + 44 + 51 + 9 + 6 = 433`. Excluded counts are +`554 + 2 = 556`. The total is `433 + 556 + 0 = 989`. No file is claimed by +two proposed components. + +## Open questions + +1. Should the 14-file first-run installer remain a separate component in the + final map? Its alternate route graph, lifecycle, state, and API boundary + support the split, but it imports shared web UI/runtime code while the + shared browser entry imports its route graph, so source dependencies are + reciprocal at composition time. +2. Should `apps/fabro-web/app/routes/playground.tsx` remain assigned to + `fabro-web-app` as the app-level integration adapter (the proposal here), + or move into `fabro-workflow-playground`? Keeping the 44-file subtree as + the playground boundary matches its own standalone/re-embedding contract. +3. Which final Rust component ID owns + `docs/public/api-reference/fabro-api.yaml` and the server endpoints: + `fabro-api`, `fabro-server`, or a separately reconciled API-contract + component? The JavaScript dependencies above should be renamed to that + final ID. diff --git a/.config/nextest.toml b/.config/nextest.toml index fe7f4f7783..3af76c17c5 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -11,10 +11,6 @@ leak-timeout = "500ms" filter = "package(fabro-server)" slow-timeout = { period = "5s", terminate-after = 4 } - [[profile.default.overrides]] - filter = "package(fabro-server) & test(all_spec_routes_are_routable)" - slow-timeout = { period = "15s", terminate-after = 4 } - [[profile.default.overrides]] filter = "package(fabro-workflow)" slow-timeout = { period = "2s", terminate-after = 3 } diff --git a/.env.example b/.env.example index a2a74f3e63..bdb08589e5 100644 --- a/.env.example +++ b/.env.example @@ -1,11 +1,15 @@ ANTHROPIC_API_KEY= BRAVE_SEARCH_API_KEY= DAYTONA_API_KEY= +DEEPSEEK_API_KEY= FIREWORKS_API_KEY= GEMINI_API_KEY= INCEPTION_API_KEY= -KIMI_API_KEY= +MOONSHOT_API_KEY= MINIMAX_API_KEY= +MODAL_KIMI_K3_BASE_URL= +MODAL_TOKEN_ID= +MODAL_TOKEN_SECRET= OPENAI_API_KEY= OPENROUTER_API_KEY= POOLSIDE_API_KEY= diff --git a/.fabro/workflows/implement-plan/workflow.fabro b/.fabro/workflows/implement-plan/workflow.fabro index 7a4e5a26e7..562795f939 100644 --- a/.fabro/workflows/implement-plan/workflow.fabro +++ b/.fabro/workflows/implement-plan/workflow.fabro @@ -8,9 +8,9 @@ digraph ImplementPlan { toolchain [label="Toolchain", shape=parallelogram, script="command -v cargo >/dev/null || { curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && sudo ln -sf $HOME/.cargo/bin/* /usr/local/bin/; }; cargo --version 2>&1", max_retries=0] preflight_compile [label="Preflight Compile", shape=parallelogram, script="cargo check -q --workspace 2>&1", max_retries=0] preflight_lint [label="Preflight Lint", shape=parallelogram, script="cargo +nightly-2026-04-14 clippy -q --workspace --all-targets -- -D warnings 2>&1", max_retries=0] - fix_lints [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", model="anthropic/claude-fable-5", provider="openrouter", reasoning_effort="xhigh", max_visits=3] + fix_lints [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", model="claude-opus", provider="openrouter", reasoning_effort="xhigh", max_visits=3] implement [label="Implement", prompt="Read the plan file referenced in the goal and implement every step. Make all the code changes described in the plan. Use red/green TDD.", model="openai/gpt-5.6-sol", provider="openrouter", reasoning_effort="xhigh"] - simplify_fable [label="Simplify (Claude Fable 5)", prompt="@prompts/simplify.md", model="anthropic/claude-fable-5", provider="openrouter", reasoning_effort="xhigh"] + simplify_opus [label="Simplify (Claude Opus)", prompt="@prompts/simplify.md", model="claude-opus", provider="openrouter", reasoning_effort="xhigh"] simplify_sol [label="Simplify (GPT-5.6 Sol)", prompt="@prompts/simplify.md", model="openai/gpt-5.6-sol", provider="openrouter", reasoning_effort="max"] verify [label="Verify", shape=parallelogram, script="git fetch origin main 2>&1 && git merge --no-edit --no-stat origin/main 2>&1 && cargo +nightly-2026-04-14 fmt --all 2>&1 && cargo dev docs refresh 2>&1 && cargo +nightly-2026-04-14 fmt --check --all 2>&1 && { command -v rg >/dev/null 2>&1 || { echo 'rg is required for verify'; exit 127; }; } && ! rg -n 'AuthMode::Disabled|RunAuthMethod|RunSubjectProvenance|\bActorRef\b|\bActorKind\b|AuthenticatedSubject|AuthenticatedService|AuthorizeRunScoped|AuthorizeRunBlob|AuthorizeStageArtifact|AuthorizeCommandLog|auth_method\s*==\s*\"disabled\"' lib/apps lib/components lib/foundation apps lib/packages docs/public/api-reference/fabro-api.yaml 2>&1 && cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings 2>&1 && cargo nextest run --workspace --status-level slow --profile ci 2>&1 && cargo dev docs check 2>&1 && bun install --frozen-lockfile 2>&1 && (cd apps/fabro-web && bun run typecheck) 2>&1 && (cd apps/fabro-web && bun run test) 2>&1 && (cd lib/packages/fabro-api-client && bun run typecheck) 2>&1 && cargo dev build -- -p fabro-cli --release 2>&1", timeout="20m", goal_gate=true, retry_target="fixup"] fixup [label="Fixup", prompt="The verify step failed. Read the build output from context and fix all format, clippy, Rust test, docs, TypeScript typecheck/test, and build failures.", model="anthropic/claude-fable-5", provider="openrouter", reasoning_effort="xhigh", max_visits=3] @@ -23,7 +23,7 @@ digraph ImplementPlan { preflight_lint -> implement [condition="outcome=succeeded"] preflight_lint -> fix_lints fix_lints -> preflight_lint - implement -> simplify_fable -> simplify_sol -> verify + implement -> simplify_opus -> simplify_sol -> verify verify -> exit [condition="outcome=succeeded"] verify -> fixup fixup -> verify diff --git a/.fabro/workflows/pr-simplify/workflow.fabro b/.fabro/workflows/pr-simplify/workflow.fabro index 7866adad6e..dabd81dba7 100644 --- a/.fabro/workflows/pr-simplify/workflow.fabro +++ b/.fabro/workflows/pr-simplify/workflow.fabro @@ -1,7 +1,7 @@ digraph PrSimplify { graph [ goal="Run the simplify code-review pass on PR #{{ inputs.pr }}: review the changes for reuse, quality, and efficiency, apply the fixes, and update the existing PR in place.", - default_model="claude-fable-5", + default_model="claude-opus", rankdir=LR ] diff --git a/.fabro/workflows/pr-simplify/workflow.toml b/.fabro/workflows/pr-simplify/workflow.toml index 478356fc02..820bc0e339 100644 --- a/.fabro/workflows/pr-simplify/workflow.toml +++ b/.fabro/workflows/pr-simplify/workflow.toml @@ -8,11 +8,11 @@ _version = 1 # # Required input — the PR number — is passed at run time: # -# fabro run pr-simplify -I pr=547 # defaults to Fable +# fabro run pr-simplify -I pr=547 # defaults to Opus # fabro run pr-simplify -I pr=547 --model gpt-55 # override the model # -# The graph sets default_model=claude-fable-5, so every stage (orchestrator + -# review subagents) runs on Fable unless you pass --model, which wins over the +# The graph sets default_model=claude-opus, so every stage (orchestrator + +# review subagents) runs on Opus unless you pass --model, which wins over the # default (configured model / --model beats the graph default_model, which # beats the catalog default). The apply stage reads the model it is actually # running as and labels the PR `simplify:`, so the label always diff --git a/AGENTS.md b/AGENTS.md index bdc9ab53fa..59712966bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,7 +123,7 @@ Fabro is an AI-powered workflow orchestration platform. Workflows are defined as - **fabro-util** — Shared utilities (redaction, terminal formatting) ### TypeScript (`apps/` and `lib/packages/`) -- **apps/fabro-web** — React 19 + React Router + Vite + Tailwind CSS frontend +- **apps/fabro-web** — React 19 + React Router + Tailwind CSS frontend, bundled by a custom Bun script (`apps/fabro-web/scripts/build.ts`), not Vite - **lib/packages/fabro-api-client** — Auto-generated TypeScript Axios client from OpenAPI spec ### Key design patterns diff --git a/Cargo.lock b/Cargo.lock index 99f3642f2d..27792f4323 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -338,6 +338,7 @@ checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac" dependencies = [ "compression-codecs", "compression-core", + "futures-io", "pin-project-lite", "tokio", ] @@ -402,6 +403,21 @@ dependencies = [ "syn 2.0.117", ] +[[package]] +name = "async_zip" +version = "0.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d8c50d65ce1b0e0cb65a785ff615f78860d7754290647d3b983208daa4f85e6" +dependencies = [ + "async-compression", + "crc32fast", + "futures-lite", + "pin-project", + "thiserror 2.0.18", + "tokio", + "tokio-util", +] + [[package]] name = "atoi" version = "2.0.0" @@ -1854,7 +1870,7 @@ checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea" [[package]] name = "daytona-api-client" version = "0.1.0" -source = "git+https://github.com/brynary/daytona-sdk-rust?rev=fc58e22f7f25183df6264276ee186bbc32635738#fc58e22f7f25183df6264276ee186bbc32635738" +source = "git+https://github.com/brynary/daytona-sdk-rust?rev=73c9c458dd1a1d096afd3521175637af82afd8d8#73c9c458dd1a1d096afd3521175637af82afd8d8" dependencies = [ "reqwest 0.13.2", "reqwest-middleware", @@ -1868,7 +1884,7 @@ dependencies = [ [[package]] name = "daytona-sdk" version = "0.1.0" -source = "git+https://github.com/brynary/daytona-sdk-rust?rev=fc58e22f7f25183df6264276ee186bbc32635738#fc58e22f7f25183df6264276ee186bbc32635738" +source = "git+https://github.com/brynary/daytona-sdk-rust?rev=73c9c458dd1a1d096afd3521175637af82afd8d8#73c9c458dd1a1d096afd3521175637af82afd8d8" dependencies = [ "daytona-api-client", "daytona-toolbox-client", @@ -1888,7 +1904,7 @@ dependencies = [ [[package]] name = "daytona-toolbox-client" version = "0.1.0" -source = "git+https://github.com/brynary/daytona-sdk-rust?rev=fc58e22f7f25183df6264276ee186bbc32635738#fc58e22f7f25183df6264276ee186bbc32635738" +source = "git+https://github.com/brynary/daytona-sdk-rust?rev=73c9c458dd1a1d096afd3521175637af82afd8d8#73c9c458dd1a1d096afd3521175637af82afd8d8" dependencies = [ "reqwest 0.13.2", "reqwest-middleware", @@ -2239,7 +2255,7 @@ dependencies = [ [[package]] name = "fabro-acp" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "agent-client-protocol", "agent-client-protocol-tokio", @@ -2258,7 +2274,7 @@ dependencies = [ [[package]] name = "fabro-agent" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -2274,6 +2290,7 @@ dependencies = [ "fabro-model", "fabro-sandbox", "fabro-static", + "fabro-template", "fabro-test", "fabro-types", "fabro-util", @@ -2281,6 +2298,7 @@ dependencies = [ "futures", "glob", "htmd", + "insta", "jsonschema", "libc", "paste", @@ -2288,11 +2306,13 @@ dependencies = [ "serde_json", "sha2 0.10.9", "shell-escape", + "shlex", "strum 0.28.0", "tempfile", "thiserror 2.0.18", "tokio", "tokio-util", + "toml 0.8.23", "tracing", "tracing-subscriber", "uuid", @@ -2300,7 +2320,7 @@ dependencies = [ [[package]] name = "fabro-api" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "chrono", "fabro-automation", @@ -2323,7 +2343,7 @@ dependencies = [ [[package]] name = "fabro-auth" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -2348,7 +2368,7 @@ dependencies = [ [[package]] name = "fabro-automation" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -2367,11 +2387,11 @@ dependencies = [ [[package]] name = "fabro-build-support" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" [[package]] name = "fabro-checkpoint" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "chrono", "fabro-config", @@ -2387,7 +2407,7 @@ dependencies = [ [[package]] name = "fabro-cli" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "assert_cmd", @@ -2489,7 +2509,7 @@ dependencies = [ [[package]] name = "fabro-client" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "bytes", @@ -2518,7 +2538,7 @@ dependencies = [ [[package]] name = "fabro-config" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -2535,6 +2555,7 @@ dependencies = [ "serde", "serde_json", "strsim 0.11.1", + "strum 0.28.0", "temp-env", "tempfile", "thiserror 2.0.18", @@ -2547,7 +2568,7 @@ dependencies = [ [[package]] name = "fabro-core" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "async-trait", "fabro-types", @@ -2562,7 +2583,7 @@ dependencies = [ [[package]] name = "fabro-db" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -2574,7 +2595,7 @@ dependencies = [ [[package]] name = "fabro-dev" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "assert_cmd", @@ -2593,7 +2614,7 @@ dependencies = [ [[package]] name = "fabro-dump" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "bytes", @@ -2607,7 +2628,7 @@ dependencies = [ [[package]] name = "fabro-environment" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -2629,7 +2650,7 @@ dependencies = [ [[package]] name = "fabro-github" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "base64", @@ -2651,7 +2672,7 @@ dependencies = [ [[package]] name = "fabro-graphviz" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "fabro-types", @@ -2666,7 +2687,7 @@ dependencies = [ [[package]] name = "fabro-hooks" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "async-trait", "fabro-agent", @@ -2689,7 +2710,7 @@ dependencies = [ [[package]] name = "fabro-http" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "fabro-static", "http 1.4.0", @@ -2699,7 +2720,7 @@ dependencies = [ [[package]] name = "fabro-install" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "base64", @@ -2718,7 +2739,7 @@ dependencies = [ [[package]] name = "fabro-interview" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "async-trait", "dialoguer", @@ -2733,7 +2754,7 @@ dependencies = [ [[package]] name = "fabro-llm" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -2761,6 +2782,7 @@ dependencies = [ "rand 0.9.4", "serde", "serde_json", + "sha2 0.10.9", "strum 0.28.0", "thiserror 2.0.18", "tokio", @@ -2774,7 +2796,7 @@ dependencies = [ [[package]] name = "fabro-macros" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "clap", "fabro-options-metadata", @@ -2785,7 +2807,7 @@ dependencies = [ [[package]] name = "fabro-manifest" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "fabro-api", @@ -2803,7 +2825,7 @@ dependencies = [ [[package]] name = "fabro-mcp" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "axum", @@ -2823,7 +2845,7 @@ dependencies = [ [[package]] name = "fabro-mcp-server" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -2846,11 +2868,12 @@ dependencies = [ "tempfile", "tokio", "toml 0.8.23", + "tracing", ] [[package]] name = "fabro-mcp-store" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "chrono", "fabro-db", @@ -2868,7 +2891,7 @@ dependencies = [ [[package]] name = "fabro-model" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "fabro-static", "http 1.4.0", @@ -2884,7 +2907,7 @@ dependencies = [ [[package]] name = "fabro-oauth" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "axum", @@ -2906,7 +2929,7 @@ dependencies = [ [[package]] name = "fabro-options-metadata" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "serde", "serde_json", @@ -2914,7 +2937,7 @@ dependencies = [ [[package]] name = "fabro-proc" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "cc", "libc", @@ -2923,7 +2946,7 @@ dependencies = [ [[package]] name = "fabro-redact" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "aho-corasick", "ref-cast", @@ -2937,9 +2960,30 @@ dependencies = [ "url", ] +[[package]] +name = "fabro-referee" +version = "0.313.0-nightly.0" +dependencies = [ + "anyhow", + "base64", + "chrono", + "clap", + "fabro-http", + "regex", + "reqwest 0.13.2", + "serde", + "serde_json", + "sha2 0.10.9", + "strum 0.27.2", + "thiserror 2.0.18", + "tracing", + "tracing-subscriber", + "ulid", +] + [[package]] name = "fabro-sandbox" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -2960,11 +3004,11 @@ dependencies = [ "futures", "futures-util", "git2", - "glob", "hex", "hmac 0.12.1", "httpmock", "rand 0.9.4", + "reqwest 0.13.2", "reqwest-middleware", "rustls", "serde", @@ -2984,10 +3028,11 @@ dependencies = [ [[package]] name = "fabro-server" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", + "async_zip", "axum", "axum-extra", "base64", @@ -3024,6 +3069,7 @@ dependencies = [ "fabro-spa", "fabro-static", "fabro-store", + "fabro-template", "fabro-test", "fabro-tool", "fabro-types", @@ -3076,7 +3122,7 @@ dependencies = [ [[package]] name = "fabro-slack" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "fabro-http", "fabro-interview", @@ -3098,18 +3144,18 @@ dependencies = [ [[package]] name = "fabro-spa" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "rust-embed", ] [[package]] name = "fabro-static" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" [[package]] name = "fabro-store" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "async-trait", "bytes", @@ -3139,7 +3185,7 @@ dependencies = [ [[package]] name = "fabro-telemetry" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "base64", @@ -3165,7 +3211,7 @@ dependencies = [ [[package]] name = "fabro-template" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "fabro-types", @@ -3179,7 +3225,7 @@ dependencies = [ [[package]] name = "fabro-test" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "assert_cmd", @@ -3204,7 +3250,7 @@ dependencies = [ [[package]] name = "fabro-tool" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -3225,7 +3271,7 @@ dependencies = [ [[package]] name = "fabro-tracker" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-trait", @@ -3239,7 +3285,7 @@ dependencies = [ [[package]] name = "fabro-types" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "chrono", "clap", @@ -3254,6 +3300,7 @@ dependencies = [ "shlex", "strum 0.28.0", "tempfile", + "thiserror 2.0.18", "toml 0.8.23", "ulid", "url", @@ -3261,12 +3308,13 @@ dependencies = [ [[package]] name = "fabro-util" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "console 0.15.11", "dirs", "fabro-static", + "glob", "insta", "open", "rand 0.9.4", @@ -3275,6 +3323,7 @@ dependencies = [ "shlex", "tempfile", "termimad", + "thiserror 2.0.18", "tokio", "tracing", "tracing-subscriber", @@ -3282,7 +3331,7 @@ dependencies = [ [[package]] name = "fabro-validate" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "fabro-acp", "fabro-graphviz", @@ -3295,7 +3344,7 @@ dependencies = [ [[package]] name = "fabro-variable" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -3312,7 +3361,7 @@ dependencies = [ [[package]] name = "fabro-vault" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "chrono", @@ -3331,7 +3380,7 @@ dependencies = [ [[package]] name = "fabro-workflow" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "assert_cmd", @@ -3387,6 +3436,7 @@ dependencies = [ "serde_json", "sha2 0.10.9", "shlex", + "strum 0.28.0", "tempfile", "thiserror 2.0.18", "tokio", @@ -8495,7 +8545,7 @@ dependencies = [ [[package]] name = "twin-github" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "axum", "base64", @@ -8514,7 +8564,7 @@ dependencies = [ [[package]] name = "twin-openai" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" dependencies = [ "anyhow", "async-stream", diff --git a/Cargo.toml b/Cargo.toml index 7f2da4899b..1a62a717c8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ resolver = "2" [workspace.package] edition = "2021" -version = "0.304.0-nightly.1" +version = "0.313.0-nightly.0" license = "MIT" [workspace.dependencies] @@ -36,6 +36,7 @@ dotenvy = "0.15" futures = "0.3" tokio-stream = "0.1" async-trait = "0.1" +async_zip = { version = "0.0.18", features = ["tokio", "deflate"] } fs2 = "0.4" base64 = "0.22" bytes = "1" @@ -76,6 +77,7 @@ regex = "1" semver = "1" aho-corasick = "1" globset = "0.4" +glob = "0.3" dirs = "6" mac_address = "1" md5 = "0.7" @@ -95,8 +97,8 @@ twin-openai = { path = "test/twin/openai" } twin-github = { path = "test/twin/github" } tokio-tungstenite = { version = "0.26", features = ["rustls-tls-webpki-roots"] } futures-util = "0.3" -daytona-sdk = { git = "https://github.com/brynary/daytona-sdk-rust", rev = "fc58e22f7f25183df6264276ee186bbc32635738", package = "daytona-sdk" } -daytona-api-client = { git = "https://github.com/brynary/daytona-sdk-rust", rev = "fc58e22f7f25183df6264276ee186bbc32635738", package = "daytona-api-client" } +daytona-sdk = { git = "https://github.com/brynary/daytona-sdk-rust", rev = "73c9c458dd1a1d096afd3521175637af82afd8d8", package = "daytona-sdk" } +daytona-api-client = { git = "https://github.com/brynary/daytona-sdk-rust", rev = "73c9c458dd1a1d096afd3521175637af82afd8d8", package = "daytona-api-client" } sentry = { version = "0.35", default-features = false, features = ["backtrace", "contexts", "ureq", "rustls"] } fork = "0.2" exec = "0.3" diff --git a/apps/fabro-web/app/components/chats/tool-call-summary.tsx b/apps/fabro-web/app/components/chats/tool-call-summary.tsx index e8bbc35988..d881a20f2a 100644 --- a/apps/fabro-web/app/components/chats/tool-call-summary.tsx +++ b/apps/fabro-web/app/components/chats/tool-call-summary.tsx @@ -4,7 +4,8 @@ import type { ToolCallMessagePartProps, } from "@assistant-ui/react"; import { useMessage } from "@assistant-ui/react"; -import { WrenchScrewdriverIcon } from "@heroicons/react/24/outline"; + +import { ToolCallCount } from "../tool-call-count"; const EMPTY_PARTS: readonly ThreadAssistantMessagePart[] = []; @@ -33,19 +34,12 @@ export default function ToolCallSummary(props: ToolCallMessagePartProps) { const total = toolCalls.length; const errored = toolCalls.filter((toolCall) => toolCall.isError).length; - const noun = total === 1 ? "call" : "calls"; return ( -
-
+ ); } diff --git a/apps/fabro-web/app/components/event-debug.tsx b/apps/fabro-web/app/components/event-debug.tsx index 30f77e04fe..b50ced2f96 100644 --- a/apps/fabro-web/app/components/event-debug.tsx +++ b/apps/fabro-web/app/components/event-debug.tsx @@ -443,7 +443,10 @@ const THREAD_CATEGORY_COLOR: Record = { export type ThreadDnaSelection = | { kind: "single"; turnIndex: number } - | { kind: "group"; childTurnIndices: number[] }; + | { + kind: "group"; + childTurnIndices: readonly [number, number, ...number[]]; + }; export interface ThreadDnaItem { category: ThreadCategory; @@ -456,13 +459,15 @@ export interface ThreadDnaItem { const INSTANT_MARKER_PX = 4; const MIN_DURATION_PX = 3; -function selectionKey(s: ThreadDnaSelection): string { - return s.kind === "single" - ? `s:${s.turnIndex}` - : `g:${s.childTurnIndices.join(",")}`; +export function threadSelectionId(selection: ThreadDnaSelection): number { + const turnIndex = + selection.kind === "single" + ? selection.turnIndex + : selection.childTurnIndices[0]; + return turnIndex * 2 + (selection.kind === "group" ? 1 : 0); } -function selectionsEqual( +export function threadSelectionsEqual( a: ThreadDnaSelection, b: ThreadDnaSelection | null, ): boolean { @@ -504,19 +509,19 @@ export function ThreadDnaStrip({ selection: ThreadDnaSelection | null; onSelect: (s: ThreadDnaSelection) => void; }) { - const [hover, setHover] = useState<{ key: string; rect: DOMRect } | null>( + const [hover, setHover] = useState<{ id: number; rect: DOMRect } | null>( null, ); const visibleItems = useMemo( () => sampleStripItems(items, STRIP_MAX_MARKERS, (item) => - selectionsEqual(item.selection, selection) + threadSelectionsEqual(item.selection, selection) ), [items, selection], ); - const visibleItemByKey = useMemo( + const visibleItemById = useMemo( () => new Map( - visibleItems.map((item) => [selectionKey(item.selection), item]), + visibleItems.map((item) => [threadSelectionId(item.selection), item]), ), [visibleItems], ); @@ -542,7 +547,7 @@ export function ThreadDnaStrip({ const hoveredItem = hover != null - ? visibleItemByKey.get(hover.key) ?? null + ? visibleItemById.get(hover.id) ?? null : null; return ( @@ -552,10 +557,10 @@ export function ThreadDnaStrip({ >
{visibleItems.map((item) => { - const key = selectionKey(item.selection); + const id = threadSelectionId(item.selection); const isInstant = item.durationMs <= 0; - const isSelected = selectionsEqual(item.selection, selection); - const isHovered = hover?.key === key; + const isSelected = threadSelectionsEqual(item.selection, selection); + const isHovered = hover?.id === id; const leftPct = (item.startMs / totalMs) * 100; const baseColor = THREAD_CATEGORY_COLOR[item.category]; @@ -585,18 +590,18 @@ export function ThreadDnaStrip({ return ( - )} -
- ); -} - -function PulseDot() { - return ( -